WARNING

本页面内容经 AI 翻译生成，仅供参考。具体细节请以英文原文为准。

使用 TensorZero 作为 AI 模型网关和可观测性平台

TensorZero 是一个一体化平台，用于管理、连接和监控你的 AI 模型。它充当一个中央网关，将你的客户端应用连接到本地 AI 模型。它会记录每一次对话和请求，让你能够追踪性能表现，并帮助你测试不同的配置以获得最佳结果。

学习目标

在本指南中，你将学习如何：

• 在 Olares 上安装 TensorZero。
• 理解 TensorZero 如何管理 AI 连接。
• 连接一个聊天模型和一个功能。
• （可选）连接一个嵌入模型。
• 使用内置的 Playground 测试你的配置。
• 将其他应用连接到 TensorZero。
• 通过内置的 MCP 服务器让你的 AI 智能体读取性能数据。

前提条件

• 安装以下模型：

  模型类型	模型	获取方式
  聊天	Qwen3.6-27B (llama.cpp)	从 Market 安装
  嵌入	EmbeddingGemma	从 Market 安装。如果客户端应用不需要嵌入功能，则无需安装

• 确保你的客户端应用（如 OpenCode 和 AgentZero）已经安装并完全可用。本指南仅涵盖将它们连接到 TensorZero 所需的特定设置。

安装 TensorZero

1. 打开 Market，搜索 "TensorZero"。

   

2. 点击 Get，然后点击 Install。等待安装完成。

了解配置要求

TensorZero 不提供图形界面来配置模型。你需要在 Files 中编辑它的配置文件来管理所有设置。

在编辑文件之前，请查看以下规则以避免错误：

• 严格的权限控制：TensorZero 拒绝直接请求原始模型名称，如 gpt-4o 和 Qwen3.6-27B。你必须为每个要使用的模型定义一个别名。不要在别名中使用点号或冒号。例如，使用 qwen3_6_27b，而不是 qwen3.6:27b。

• 精确命名：当你将其他应用连接到 TensorZero 时，必须在模型别名前添加特定前缀，例如 tensorzero::model_name::<alias> 和 tensorzero::function_name::<alias>。

  TIP

  对于使用 LiteLLM 框架的应用，你必须在模型名称中包含 openai/ 前缀。例如，AgentZero 的嵌入功能需要格式为 openai/tensorzero::embedding_model_name::embeddinggemma 的嵌入模型名称。

• 格式规则：配置文件使用 TOML 文本格式。你必须在不同部分之间保持至少一个空行，例如在 [models] 和 [functions] 之间。如果删除空行，应用可能无法启动。

获取模型连接信息

模型连接的工作原理

Olares 上的独立模型作为与客户端应用分开的服务运行。要连接两者，客户端需要准确的 Model name，以及与其所需 API 格式相匹配的 Base URL。

你可以从模型控制台获取这两个值。有关更多信息，可参阅连接 AI 应用。

对于 Qwen3.6-27B (llama.cpp) 和 EmbeddingGemma，选择 OpenAI-Compatible API 格式：

1. 从启动台打开模型应用。其模型控制台会自动打开。

2. 等待模型显示就绪，且引擎显示运行中。

   

3. 在模型部分，按显示内容原样复制模型名称。

4. 在引擎部分：

   a. 连接来源：选择 Olares 内应用。

   b. API 格式：选择 OpenAI-Compatible。

   c.按显示内容原样复制 Base URL 地址。

配置聊天模型和功能

要让 TensorZero 工作，你需要两样东西：一个充当 AI 引擎的模型，以及一个作为你的应用与该引擎通信的接入点的功能。

你需要定义模型来告诉 TensorZero AI 在哪里，然后将它链接到一个功能来处理请求。

本示例连接 Qwen3.6-27B (llama.cpp)。

1. 打开 Files，然后进入 Data > tensorzero > config。

2. 右键点击 tensorzero.toml，然后点击 edit_square。

3. 在编辑器中添加以下代码片段。将 <qwen-base-url> 替换为从 Qwen3.6-27B 模型控制台复制的 Base URL。

   此配置将模型注册为别名 qwen3_6_27b，并创建一个名为 general_chat 的客户端功能，将传入的应用请求路由到该模型。

   # models
   [models.qwen3_6_27b]
   routing = ["qwen"]
   [models.qwen3_6_27b.providers.qwen]
   type = "openai"
   api_base = "<qwen-base-url>"
   model_name = "unsloth/Qwen3.6-27B-GGUF:Q4_K_M"
   api_key_location = "none"
   
   # functions
   [functions.general_chat]
   type = "chat"
   [functions.general_chat.variants.my_default_variant]
   type = "chat_completion"
   model = "qwen3_6_27b"

4. 点击 save，然后关闭文件。

5. 打开 Control Hub，进入 Browse > tensorzero-{username} > Deployments > tensorzero，然后点击 Restart 以应用新设置。

   

（可选）配置嵌入模型

某些应用需要嵌入模型来搜索文档或构建记忆功能。TensorZero 将嵌入模型与聊天模型分开处理。你必须定义一个专用的嵌入模型。不要为记忆任务使用聊天功能。

1. 在 tensorzero.toml 中添加以下代码片段以定义一个嵌入模型：

   将 <embedding-base-url> 替换为从 EmbeddingGemma 模型控制台复制的 Base URL。此配置将模型注册为别名 embeddinggemma。

   # embedding_models
   [embedding_models.embeddinggemma]
   routing = ["embeddinggemma"]
   [embedding_models.embeddinggemma.providers.embeddinggemma]
   type = "openai"
   api_base = "<embedding-base-url>"
   model_name = "embeddinggemma-300m"
   api_key_location = "none"

2. 在 Control Hub 中重启 tensorzero 容器以应用新设置。

验证连接

使用内置的 Playground 测试功能是否能够正常调用聊天模型。

Playground 需要至少一个测试用例（称为 Datapoint）来显示聊天界面。如果你还没有，必须手动创建一个。

1. 从 Launchpad 打开 TensorZero。

2. 从左侧边栏选择 Datasets。

3. 点击 New Datapoint，然后配置测试用例详情。

   例如，创建一个基础地理测试：

   • Dataset：指定一个名称来创建新的测试用例集合。例如，Baseline tests。
   • Function：选择你之前配置的功能。例如，general_chat。
   • Input：选择 + User Message，点击 + Text，然后输入一个测试提示。例如，What is the capital of Spain?。
   • Output：选择 + Text，然后输入你期望模型生成的确切答案。例如，Madrid。
   • （可选）Tags 和 Metadata：输入标签以帮助以后识别此测试用例。例如，添加一个标签，Key 设置为 type，Value 设置为 QA。

   

4. 点击 Create Datapoint。

5. 从左侧边栏选择 Playground。

6. 选择你的功能、刚才创建的数据集和你的变体。聊天界面将出现。如果你收到正常回复，说明设置成功。

   

获取 TensorZero 端点

应用端点（endpoint）如何工作

当客户端连接另一个 Olares 应用时，会使用该应用的端点作为网络地址。如果应用提供多个端点，请选择与客户端所需功能或协议相匹配的端点。

对于 TensorZero：

1. 打开 Settings，然后进入 Applications > TensorZero > Entrances > TensorZero。

   

2. 复制 Endpoint URL。对于 OpenAI-compatible 客户端，需要在该 URL 后追加 /openai/v1。

将模型路由到客户端应用

配置你的第三方应用以使用 TensorZero。

确定你的模型名称字符串

根据你要调用的资源，使用以下前缀构建正确的模型名称：

资源类型	必需的字符串格式	示例
功能	tensorzero::function_name::<alias>	tensorzero::function_name::general_chat
模型	tensorzero::model_name::<alias>	tensorzero::model_name::qwen3_6_27b
嵌入	tensorzero::embedding_model_name::<alias>	tensorzero::embedding_model_name::embeddinggemma

TIP

• 不要在别名中使用点号或冒号。例如，使用 qwen3_6_27b，而不是 qwen3.6:27b。
• 如果模型名称不起作用，请在前面添加 openai/ 以满足 LiteLLM 框架的要求，然后重试。例如，使用 openai/tensorzero::embedding_model_name::embeddinggemma。

连接你的客户端应用

以下步骤演示如何配置 OpenCode 和 AgentZero，使其通过 TensorZero 路由请求。

访问内置的 MCP 服务器

TensorZero 在 /mcp 端点包含一个内置的 Model Context Protocol (MCP) 服务器。此功能允许你的 AI 智能体查看 TensorZero 中的性能数据。

例如，你可以让你的智能体检索今天 general_chat 的平均响应时间，智能体将使用 MCP 连接读取日志并将数据报告给你。

以下示例演示如何配置 OpenCode 以访问此 MCP 工具。

1. 打开 Files，然后进入 Data > opencode > .config > opencode。

2. 双击 opencode.json，然后点击 edit_square。

3. 添加以下 MCP 配置块。确保将 <tensorzero-endpoint> 替换为你的实际 TensorZero 端点 URL。

   {
   "mcp": {
       "tensorzero": {
       "type": "remote",
       "url": "<tensorzero-endpoint>/mcp",
       "enabled": true
       }
   }
   }

4. 点击 save。

5. 重启 OpenCode 应用以应用更改。在右上角的 MCP 标签页中，验证 tensorzero 显示为已启用。

   

6. 在聊天中直接指示你的 AI 智能体显式使用此工具。例如，输入 Use the TensorZero MCP tool to analyze the latest inference logs。

   

常见问题

连接到模型与连接到功能有什么区别？

在 TensorZero 中，模型和功能都允许你的应用与 AI 通信，但强烈建议将你的应用连接到功能。

• 模型（tensorzero::model_name::...）：这代表原始的 AI 引擎。虽然你可以将客户端应用直接连接到模型，但这样做会绕过 TensorZero 的高级监控功能。
• 功能（tensorzero::function_name::...）：这代表你的应用正在执行的特定任务，例如 coding_assistant 或 text_summarizer。通过功能连接可以使用 TensorZero 的详细可观测性和统计跟踪。它还允许你将多个不同的功能链接到同一个底层模型，帮助你分别跟踪和优化每个特定任务。

错误：model field must start with tensorzero::function_name::...

原因：你在客户端的模型字段中输入了原始模型名称（如 unsloth/Qwen3.6-27B-GGUF:Q4_K_M）或格式不正确。

解决方法：根据你要连接的内容，始终使用以下三种精确格式之一：

你要调用	格式	示例
功能	tensorzero::function_name::<alias>	tensorzero::function_name::general_chat
直接调用模型	tensorzero::model_name::<alias>	tensorzero::model_name::qwen3_6_27b
嵌入模型	tensorzero::embedding_model_name::<alias>	tensorzero::embedding_model_name::embeddinggemma

错误：litellm.BadRequestError: LLM Provider NOT provided

原因：此错误发生在依赖 LiteLLM 框架的应用中，例如 AgentZero 的嵌入功能。这些特定应用不会自动识别标准的 TensorZero 模型字符串。它们需要显式的提供商前缀来理解如何格式化连接。

解决方法： 查看错误消息详情以确定具体哪个模型失败。打开你的应用设置，并在该模型名称的最前面添加 openai/。

例如，如果错误提到 model=tensorzero::embedding_model_name::embeddinggemma，你必须将嵌入模型名称或 ID 更改为 openai/tensorzero::embedding_model_name::embeddinggemma。保存设置并重试请求。

编辑配置文件后 TensorZero 无法启动

原因：TOML 格式已损坏，通常是由于部分之间缺少空行或别名中包含无效字符导致的。

解决方法：

1. 打开 Control Hub，进入 tensorzero-{username} > Deployments > tensorzero > Pods，然后点击 tensorzero pod。

2. 在 Containers 部分，找到 gateway，然后点击它旁边的 article。

   

3. 查找以下常见错误：

   • Failed to parse tensorzero.toml：语法错误。确保在每个部分块（# models、# functions、# embedding_models）之间恰好有一个空行。如果你在粘贴代码时删除了空行，应用将无法启动。
   • unknown field：设置名称不正确，例如别名中包含点号或冒号。使用下划线，如 qwen3_6_27b，而不是 qwen3.6:27b。
   • provider...not found：routing = ["name"] 行中的提供商名称与紧接其下方定义的块 [models.alias.providers.name] 不匹配。例如，如果你写 routing = ["qwen"]，则必须有对应的 [models.xxx.providers.qwen] 配置块。

4. 修复语法后，重启 TensorZero 容器。

我的配置更改未在 TensorZero UI 中显示

原因：UI 缓存、网关未重新加载配置，或重启失败。

解决方法：

尝试以下方法：

• 按 Ctrl+Shift+R 或 Cmd+Shift+R 强制刷新浏览器以清除浏览器缓存。
• 检查 gateway 容器日志中是否有 Starting gateway server...。如果你看到迁移消息，请再等待 30 秒。
• 重启 TensorZero 容器。

官方文档中提到的某些页面（Autopilot、Config Editor）缺失

原因：这些是高级组件，不包含在默认的 Olares 部署中。Olares 提供核心网关、UI 和可观测性堆栈。

解决方法：如果你需要这些功能，请参阅 TensorZero 官方文档以自行托管额外服务。

了解更多

• 使用 LiteLLM 作为统一的 AI 模型网关
• 将 Bifrost 设置为 AI 模型网关