TensorZero 网关部署指南

开始使用TensorZero Gateway非常简单。

要部署TensorZero网关，您需要：

设置一个ClickHouse数据库
可选：创建配置文件
运行网关

ClickHouse

TensorZero网关将推理和反馈数据存储在ClickHouse数据库中。这些数据后续用于模型可观测性、实验和优化。

开发

出于开发目的，您可以在本地运行单节点ClickHouse实例（例如使用Homebrew或Docker），或者在ClickHouse Cloud上运行廉价的Development级集群。

有关配置ClickHouse部署的更多详情，请参阅ClickHouse文档。

生产环境

托管服务

对于生产环境部署，最简单的设置是使用托管服务，例如ClickHouse Cloud。

ClickHouse Cloud 也可通过 AWS Marketplace、GCP Marketplace 和 Azure Marketplace 获取。

托管ClickHouse部署的其他选项包括Tinybird（无服务器）和Altinity（提供技术支持）。

自主管理部署

您也可以选择运行自己的自托管ClickHouse实例或集群。

配置

设置好数据库后，您需要配置TENSORZERO_CLICKHOUSE_URL环境变量以提供连接信息。该变量采用标准格式。

TENSORZERO_CLICKHOUSE_URL="http[s]://[username]:[password]@[hostname]:[port]/[database]"

# Example: ClickHouse running locally
TENSORZERO_CLICKHOUSE_URL="http://chuser:chpassword@localhost:8123/tensorzero"

# Example: ClickHouse Cloud
TENSORZERO_CLICKHOUSE_URL="https://USERNAME:[email protected]:8443/tensorzero"

# Example: TensorZero Gateway running in a container, ClickHouse running on host machine
TENSORZERO_CLICKHOUSE_URL="http://host.docker.internal:8123/tensorzero"

TensorZero网关在启动时自动应用数据库迁移。

Disabling Observability (Not Recommended)

如果您对存储实验和优化数据不感兴趣，可以禁用可观测性功能。在这种情况下，您无需设置ClickHouse，TensorZero Gateway将充当简单的模型网关。

要禁用可观测性，请在tensorzero.toml文件中设置以下配置：

[gateway]
observability.enabled = false

如果只需临时禁用可观测性，可以向推理和反馈API端点传递dryrun: true参数。

TensorZero Gateway

开发

Running with Docker (Recommended)

你可以轻松地使用Docker在本地运行TensorZero Gateway。

您需要提供一个文件夹路径，其中包含您的tensorzero.toml文件及其依赖项（例如模式和模板），以及上述讨论的环境变量。

docker run \
  --name tensorzero-gateway \
  -v "./config:/app/config" \
  --env-file .env \
  -p 3000:3000 \
  -d \
  tensorzero/gateway

Building from source

或者，您可以从源代码构建TensorZero Gateway，并使用Cargo直接在主机上运行：

cargo run --release --bin gateway -- path/to/your/tensorzero.toml

生产环境

您可以将TensorZero Gateway与您的应用程序一起部署（例如作为边车容器）或作为独立服务运行。

单个网关实例可在亚毫秒延迟下处理超过每秒1千次查询（参见基准测试），因此简单部署即可满足绝大多数应用需求。若将其作为独立服务部署，建议在负载均衡器后至少部署两个实例以确保高可用性。该网关为无状态设计，可轻松横向扩展，无需考虑持久化问题。

Running with Docker (Recommended)

在生产环境中运行TensorZero Gateway的推荐方式是使用Docker。

在生产环境中运行Docker容器有多种方式。一个简单的解决方案是使用Docker Compose。我们提供了一个示例docker-compose.yml供参考。

Building from source

或者，您也可以从源码构建TensorZero Gateway，并使用Cargo直接在主机上运行。对于生产环境部署，我们建议启用性能优化：

cargo run --profile performance --bin gateway -- path/to/your/tensorzero.toml

命令行参数

TensorZero网关需要指定--config-file来使用自定义配置文件（例如--config-file /path/to/tensorzero.toml），或者使用--default-config来采用默认设置（即不使用自定义函数、指标等）。您还可以通过--log-format将日志格式设置为pretty（默认）或json。

客户端

有关如何与TensorZero网关交互的更多详情，请参阅Clients页面。

配置

要运行TensorZero网关，首先需要创建一个tensorzero.toml配置文件。了解更多关于配置文件的信息请点击这里。

模型供应商凭证

除了上述讨论的TENSORZERO_CLICKHOUSE_URL环境变量外，TensorZero网关还接受以下用于提供者凭证的环境变量。除非您在配置文件中指定了替代的凭证位置，否则这些环境变量对于权重为正的变体中所使用的提供者是必需的。如果缺少必需的凭证，网关将在启动时失败。

服务提供商	环境变量
Anthropic	`ANTHROPIC_API_KEY`
AWS Bedrock	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION` (optional)
AWS SageMaker	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION` (optional)
Azure OpenAI	`AZURE_OPENAI_API_KEY`
Fireworks	`FIREWORKS_API_KEY`
GCP Vertex AI Anthropic	`GCP_VERTEX_CREDENTIALS_PATH` (see below for details)
GCP Vertex AI Gemini	`GCP_VERTEX_CREDENTIALS_PATH` (see below for details)
Google AI Studio Gemini	`GOOGLE_AI_STUDIO_GEMINI_API_KEY`
Hyperbolic	`HYPERBOLIC_API_KEY`
Mistral	`MISTRAL_API_KEY`
OpenAI	`OPENAI_API_KEY`
Together	`TOGETHER_API_KEY`
xAI	`XAI_API_KEY`

注意事项：

AWS Bedrock支持多种认证方式，包括环境变量、IAM角色等。详情请参阅AWS文档。
如果您使用的是GCP Vertex提供商，还需要通过额外的-v标志将服务账户的JWT格式凭证（描述见此处）挂载到/app/gcp-credentials.json。