通过一个 AI Proxy 模型渠道把 FastGPT 接到 Router One

确认部署走的是 AI Proxy，并为这套部署单独建 Key

本指南以官方 Docker Compose 模板自部署的 FastGPT 为前提，模板里 AI Proxy 是必需服务。FastGPT 容器带两个变量：AIPROXY_API_ENDPOINT 是 AI Proxy 服务根地址，不要附加 /v1，FastGPT 会按接口补充路径；AIPROXY_API_TOKEN 必须与 AI Proxy 服务端的 ADMIN_KEY 一致。V4.17.0 升级说明把两者列为必填，并写明旧的 OPENAI_BASE_URL 和 CHAT_API_KEY 已弃用并移除，配置后不再生效。下面的片段就是官方模板里的这几行——token 是模板生成的 YAML 引用别名，不是 Router One 的值。然后为这套部署单独创建一把设了 maxSpend 的 Router One Key：它只填进渠道表单，不进这些环境变量。

# 节选自 FastGPT 官方 docker-compose 模板
x-aiproxy-token: &x-aiproxy-token 'token'
services:
  fastgpt-app:
    environment:
      # AI Proxy 的地址，如果配了该地址，优先使用
      AIPROXY_API_ENDPOINT: http://fastgpt-aiproxy:3000
      # AI Proxy 的 Admin Token，与 AI Proxy 中的环境变量 ADMIN_KEY
      AIPROXY_API_TOKEN: *x-aiproxy-token
  fastgpt-aiproxy:
    environment:
      ADMIN_KEY: *x-aiproxy-token
      # 最大重试次数
      RETRY_TIMES: 3

把 FastGPT 配置到 Router One base URL

打开 管理员 → 模型提供商，切到「模型渠道」标签页，点右上角「新增渠道」，表单与下方代码块一一对应。协议类型选 OpenAI：AI Proxy 会把这个渠道的每次请求发到「代理地址 + /chat/completions」，所以代理地址要填带 /v1 的 https://api.router.one/v1——表单占位符给出的 OpenAI 默认地址本身也以 /v1 结尾。API 密钥填 Router One Key。「模型」是这个渠道要分发的目录 ID；下拉框只列「模型配置」里已有的模型，目录 ID 没有内置时，点「新增模型」（或到「模型配置」标签页）把精确的目录 ID 填进「模型ID」——它就是 FastGPT 请求体里 model 字段的值，渠道转发时也用同一个值。两边 ID 完全一致时「模型映射」留空，只有想用本地别名时才把它映射到精确目录 ID。保存后点「模型测试」→「开始测试」：它会对每个模型真实发一次请求并显示结果与耗时，这些测试请求同样会出现在 Dashboard → Logs。最后启用模型，在应用的 AI 配置或工作流的「AI 对话」节点里选它：

# FastGPT → 管理员 → 模型提供商 → 模型渠道 → 新增渠道
# FastGPT → Admin → Model provider → Model Channels → Add Channel
渠道名（Channel）:          Router One
协议类型（Protocol Type）:   OpenAI
代理地址（Base url）:        https://api.router.one/v1
API 密钥（API key）:         sk-your-router-one-key
模型（Models）:              <exact-model-id-from-/models>
模型映射（Model Mapping）:   留空 / leave empty（模型 ID 与目录 ID 完全一致时）

# 模型配置 → 新增模型（Model Configuration → Add Model）
模型ID（Model ID）:          <exact-model-id-from-/models>
别名（Alias）:               任意展示名 / any display name
最大上下文 / 支持工具调用 / 支持图片识别:  按 /models 模型详情页填写

# 保存后：模型测试 → 开始测试（Model Test → Start Test）

每个值填在哪里，怎么验证

Router One 需要的东西都在一个渠道加一条对应的模型配置里。首次登录时系统要求的其他模型类型在同一个管理页配置，但必须指向别的供应商：

给一套部署定预算，并逐次核对模型调用

一次工作流运行会散成多次模型请求：AI 对话节点、回到模型的工具调用、问题分类、内容提取各算一次，AI Proxy 还会自行重试失败的请求（官方 Compose 模板把 RETRY_TIMES 设为 3），每一次真正到达网关的尝试都是独立请求，有各自的 Trace 和费用。给每套 FastGPT 部署单独一把设了 maxSpend 的 Router One Key，失控的工作流会停在你设的上限。这里有三本账，只有一本是你要付的钱：Dashboard → Logs 是逐请求的费用，带模型、tokens、成本、延迟、状态和 request_id；AI Proxy 的「调用日志」页按次显示输入输出 tokens、耗时和请求地址——看实际打到哪个路径最快——错误详情默认只保留 1 小时（LOG_DETAIL_STORAGE_HOURS）；FastGPT 自己的积分（模型表单里的价格字段）用来给你的用户计量，与网关费率无关。按时间、模型和 token 数对账，报障时保留网关的 request_id。如果同一个模型 ID 还配在别的渠道里，AI Proxy 会按优先级在渠道间负载均衡，Router One Logs 里少的那一条可能只是被别的渠道接走了。

FastGPT 该填哪个模型 ID？

从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 FastGPT 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个工具单独建 API Key，并设置 maxSpend 消费上限。

FastGPT 用的是哪种 API 协议？

OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。

在 trace 里验证 FastGPT 的调用

先在 FastGPT 发出一次简单文本请求，再到 Dashboard → Logs 按时间、模型和 request_id 核对 trace：tokens、花费、延迟和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

常见问题