tensorzero/tensorzero · 上手攻略

• 仓库：tensorzero/tensorzero
• 链接：https://github.com/tensorzero/tensorzero
• 分类：ai / llm-infra
• 作者：Jay
• 更新：2026-07-09

⚠️ 重要注意：该仓库已于 2026 年 6 月 12 日被官方归档（read-only）。本文档如实记录其功能与用法；后续是否由社区 fork 延续请关注 GitHub。已生产使用的项目请评估替代方案（如 Langfuse、vLLM Gateway 等）。

这是什么

TensorZero 是一个开源 LLMOps 平台，用 Rust 编写，以单一 Docker 容器交付，统一了以下能力：

• LLM Gateway：通过统一 API 访问所有 LLM 提供商（OpenAI、Anthropic、DeepSeek、vLLM、SGLang 等），兼容 OpenAI SDK，Rust 实现带来 <1ms p99 延迟开销（10k+ QPS）
• 可观测性：存储推理记录和用户反馈，支持程序化查询和 UI，可对接 OpenTelemetry
• 评测（Evaluations）：用启发式方法或 LLM Judge 对单次推理或端到端工作流做基准测试
• 优化（Optimization）：收集指标和人工反馈，自动优化 Prompt、模型和推理策略
• 实验（Experimentation）：内置 A/B 测试、路由、回退、重试机制

技术栈：Rust 编写（高性能），配置文件 tensorzero.toml + 数据库后端（本地默认 DuckDB，生产推荐 ClickHouse 或 PostgreSQL），全量 Docker 部署。

解决什么问题

LLM 应用生产化时团队常面临：

1. 多 Provider 管理混乱：OpenAI / Anthropic / 本地 vLLM / DeepSeek 各有各的 API，消费记录分散，无法统一控费
2. Prompt 迭代没有闭环：改完 Prompt 不知道效果变好还是变坏，缺乏量化反馈
3. 推理性能瓶颈：高并发下 Python 框架延迟高、吞吐低
4. A/B 测试靠手动：换模型/换 Prompt 没有可靠的灰度机制
5. 工具链碎片：Gateway、Tracing、Evaluation 要拼三套工具

TensorZero 一站式解决，用配置文件驱动 + Rust 高性能网关。

快速安装

方式一：Docker Compose（推荐本地开发）

# 克隆仓库
git clone https://github.com/tensorzero/tensorzero.git
cd tensorzero

# 启动（默认使用 DuckDB 本地存储）
docker compose up -d

# 验证
curl http://localhost:3000/health

⚠️ 注意：DuckDB 适合开发/小规模；生产环境请换 ClickHouse 或 PostgreSQL。

方式二：独立 Docker（需要已有的数据库）

docker run -p 3000:3000 \
  -v $(pwd)/tensorzero.toml:/tensorzero.toml \
  tensorzero/tensorzero

3. 配置 tensorzero.toml（最小示例）

# tensorzero.toml
[gateway]

[datasources.clickhouse]
url = "clickhouse://localhost:9000"
database = "tensorzero"

[[models]]
name = "claude-sonnet"
provider = "anthropic"

[models.providers.anthropic]
type = "anthropic"
api_key = "sk-ant-..."  # 或环境变量 ANTHROPIC_API_KEY

核心用法

1. 通过 OpenAI SDK 调用（最常用）

无需改业务代码，只需换 base_url：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:3000/openai/v1",
    api_key="not-used"  # TensorZero 不需要你的 Provider API Key
)

# 通过 TensorZero 调用 Anthropic Claude
response = client.chat.completions.create(
    model="tensorzero::claude-sonnet::anthropic::claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Share a fun fact about Rust."}]
)
print(response.choices[0].message.content)

模型名称格式：tensorzero::{function_name}::{provider}::{model}——一个配置文件定义多个"Function"（逻辑模型），每个 Function 可以绑定不同 Provider。

2. 创建 Prompt 模板（Structured Interface）

在 tensorzero.toml 中定义 Prompt：

[[functions]]
name = "code-review"

[functions.code-review.prompts.system]
template = "You are an expert code reviewer. Focus on: {{focus_area}}"

[functions.code-review.prompts.user]
template = "Review this code:\n{{code}}"

[functions.code-review.schemas.response]
json_schema = """{"type": "object", "properties": {"issues": {"type": "array", "items": {"type": "string"}}, "score": {"type": "number"}}}"""

调用时自动结构化输出（JSON Mode）：

response = client.chat.completions.create(
    model="tensorzero::code-review::anthropic::claude-sonnet-4-6",
    messages=[
        {"role": "system", "content": "You are an expert code reviewer."},
        {"role": "user", "content": "Review this code:\ndef foo():\n    pass"}
    ],
    extra_body={
        "function_name": "code-review",
        "response_format": {"type": "json_object"}
    }
)

3. 配置多个 Provider 的 Fallback

[[functions]]
name = "chat"

[functions.chat.routing]
strategy = "fallback"
order = ["openai", "anthropic", "deepseek"]

[[models]]
name = "openai-gpt4o"
provider = "openai"
[models.providers.openai]
type = "openai"

[[models]]
name = "anthropic-claude"
provider = "anthropic"
[models.providers.anthropic]
type = "anthropic"

当 OpenAI 不可用时，自动切换到 Anthropic。

4. 开启 Tool Use（Function Calling）

[functions.code-review.tools]
tool_call_format = "Object"

response = client.chat.completions.create(
    model="tensorzero::my-agent::anthropic::claude-sonnet-4-6",
    messages=[{"role": "user", "content": "What's the weather in Beijing?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "parameters": {"type": "object", "properties": {"city": {"type": "string"}}}
        }
    }],
    tool_choice={"type": "function", "function": {"name": "get_weather"}}
)

5. 开启 Caching（降成本）

[functions.my-function.caching]
enabled = true
ttl_seconds = 3600

推理结果自动缓存，相同输入不重复计费。

6. Observability（查看调用记录）

# TensorZero 自动记录每次调用
# 通过 Dashboard 查看：
# http://localhost:3000/dashboard
# 或用 API 查询：
response = requests.get("http://localhost:3000/v1/traces", params={"function": "code-review"})

7. TensorZero Autopilot（自动优化）

🚨 依赖仓库仍活跃；官方已归档后不确定 Autopilot 服务是否继续可用，建议谨慎评估。

[autopilot]
enabled = true

Autopilot 会自动： - 分析 observability 数据，建立 baseline - 设置评测（Evaluations） - 优化 Prompt 和模型选择 - 运行 A/B 测试验证效果

典型适用场景

坑与注意

1. ⚠️ 仓库已归档：2026 年 6 月 12 日被官方归档为只读。生产项目务必关注是否有社区 fork 延续；若无，可能需要迁移至其他活跃项目（如 Langfuse + vLLM 组合）
2. 模型名称格式有学习成本：tensorzero::{function}::{provider}::{model} 三段式名称对于习惯直接写模型名的开发者有额外认知负担
3. DuckDB 存储限制：开发友好，但不支持并发写入、无法横向扩展，大规模团队慎用
4. 配置驱动 vs 代码驱动：TensorZero 偏配置文件（YAML/TOML），不习惯 Infrastructure-as-Code 的团队可能觉得灵活性受限
5. Autopilot 依赖官方服务：优化建议生成可能调用 TensorZero 官方 API；归档后服务可用性未知
6. Rust 生态：如果需要深度定制（修改 Gateway 逻辑），需要 Rust 能力

与同类对比

结论： - 选 TensorZero（归档前）：追求极低延迟网关 + 统一评测 + A/B 测试闭环，且能接受配置驱动；当前建议观望是否社区 fork - 选 Langfuse：需要完整 LLMOps（Tracing + Prompt 管理 + 评测），开源且活跃开发 - 选 vLLM：专注推理性能，需要 PagedAttention、Continuous Batching 等能力 - 选 LiteLLM：只需要统一 Proxy 层快速接入 100+ Provider，不在意评测和实验功能

一句话推荐结论

TensorZero 在归档前是 Rust 时代最高性能的 LLMOps 平台之一，极低延迟网关 + 评测 + A/B 测试三合一；但鉴于仓库已归档（2026.06），新项目建议评估 Langfuse 或等社区 fork明朗后再投入生产。