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

> https://router.one/zh/integrations/fastgpt 的 Markdown 镜像，供 AI 助手与爬虫使用。Router One 是 OpenAI 兼容的统一 LLM API 网关。
> 最后更新：2026-09-11

FastGPT 是开源的知识库与 Agent 应用平台：应用以工作流搭建，AI 对话、工具调用、问题分类、内容提取等节点都要挂一个语言模型。FastGPT 通过内置的 AI Proxy 连接模型服务商——从 V4.17.0 起它是必需依赖——所以 Router One 是在那里加成一个 OpenAI 协议渠道：一把 Key 覆盖 GPT、Claude、Gemini、Grok 和 DeepSeek 系列，每次请求在 Dashboard → Logs 都有成本 Trace。本指南讲清渠道表单该填什么、如何在模型配置里登记精确模型 ID 并做渠道测试，以及索引、重排和语音模型为什么要另找供应商。

## 确认部署走的是 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：它只填进渠道表单，不进这些环境变量。

`docker-compose.yml (excerpt)`

```yaml
# 节选自 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-model-channel`

```text
# 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 需要的东西都在一个渠道加一条对应的模型配置里。首次登录时系统要求的其他模型类型在同一个管理页配置，但必须指向别的供应商：

| FastGPT 字段 | 填什么 | 怎么验证 |
| --- | --- | --- |
| 模型渠道 → 协议类型 | OpenAI | AI Proxy 在代理地址后拼 /chat/completions，目录里所有聊天模型都在这个端点上提供服务 |
| 模型渠道 → 代理地址 | https://api.router.one/v1 | 模型测试通过；测试报 404 not_found 说明少了 /v1 |
| 模型渠道 → API 密钥 | 为这套部署单独创建、设了 maxSpend 的 Router One Key | 测试请求出现在 Dashboard → Logs 里这把 Key 名下 |
| 模型渠道 → 模型 / 模型映射 | 精确目录 ID；映射只用于把本地别名指向精确 ID | Logs 里每条 Trace 的模型与 /models 逐字一致 |
| 模型配置 → 模型ID | 同一个精确 ID；上下文、工具调用、图片输入按模型详情页填 | 工具调用、问题分类、内容提取节点要求打开「支持工具调用」，且模型详情页列出工具调用 |
| 模型配置 → 自定义请求地址 / Key | 已标记即将弃用；若使用，填完整路径 https://api.router.one/v1/chat/completions | 绕过渠道和它的调用日志；官方文档要求改成渠道管理 |
| 索引、重排、语音合成、语音识别模型 | 另一家供应商的渠道 | Router One 没有 embeddings 和 rerank 端点；FastGPT 至少要有一个索引模型才能建知识库 |

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

一次工作流运行会散成多次模型请求：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；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

## 常见问题

### 渠道测试成功，但应用里调用报 400 或 404，差在哪里？

两个 ID 必须一致：「模型配置」里的模型ID 就是 FastGPT 请求体里 model 字段的值，渠道原样转发，除非「模型映射」改写了它——所以模型启用时的拼写和目录 ID 不同，或映射指向了已下架的 ID，只会在真实调用时才报错。先看 AI Proxy「调用日志」里的请求地址，再到 Dashboard → Logs 看错误消息和 request_id。协议类型为 OpenAI 时路径是 /v1/chat/completions，目录里所有聊天模型都在这个端点上；400 且消息含 must be called via，说明请求走到了别的端点——比如用 Anthropic 协议类型建的渠道会往代理地址下的 /messages 发请求，而网关只为它列出的 Claude 系列和 DeepSeek ID 提供该端点——所以即使是 Claude 系列 ID，Router One 渠道也保持 OpenAI 协议类型。400 里点名某个参数，则是模型拒绝了它：FastGPT 模型表单注明最大温度留空表示模型不支持 temperature，Body 额外字段会合并进每次请求。

### 代理地址到底带不带 /v1？one-api 的教程说不要带。

在 FastGPT 里要带。渠道存在 AI Proxy 里，它的 OpenAI 协议类型会在你填的地址后面拼 /chat/completions；表单占位符是以 /v1 结尾的 OpenAI 默认地址，FastGPT 文档也提醒「注意是否需要增加 /v1」。不带的话请求会发到 https://api.router.one/chat/completions，网关返回 404 not_found，消息里直接说明 OpenAI 兼容客户端需要以 /v1 结尾的 base URL。中转站页面上相反的口径没有错，但那是 one-api 和 new-api 的「OpenAI」渠道类型，它们自己拼完整的 /v1/chat/completions。测试失败时，先到 AI Proxy「调用日志」看请求地址，再决定增删 /v1；连接排查页有这一步的完整走法。

### 知识库的索引模型、重排模型、语音模型能不能也用 Router One？

不能。FastGPT 把五类模型分开配置——语言、索引、重排、语音合成、语音识别——系统至少要有一个语言模型和一个索引模型才能正常使用。Router One 在 /v1/chat/completions 上提供聊天模型，没有 embeddings、rerank 和音频端点，所以这三类模型要从另一家供应商的渠道来，Router One 渠道里只放语言模型。一把 Router One Key 仍然覆盖所有对话和 Agent 节点——GPT、Claude、Gemini、Grok 和 DeepSeek 系列——知识库索引的费用则留在另一家的账单上。

### FastGPT 能通过网关用哪些模型？

选用当前目录中同时支持 FastGPT 所用端点和所需功能的模型。精确 ID、当前单价与能力以 /models 及模型详情为准；不要仅按 GPT、Claude 等系列名判断兼容性。客户端能列出模型，只证明模型发现成功，仍需验证实际调用。

### 能列出模型，但调用报 400 或 404，怎么办？

先记录实际请求路径和错误消息，再核对精确模型 ID。400 可能是参数、工具类型或模型与端点不匹配；404 可能是请求路径或资源不存在，不能直接判定模型下线。若错误提示 must be called via，按它指明的端点调整客户端 provider，或换用支持当前端点的模型。不要在所有工具里统一增删 /v1 或 /chat/completions。

### 中国大陆能直连吗？

能。网关在大陆可直连、无需 VPN，配置与全球环境完全一致。

### 报 401/402/403/429 怎么排查？

先到 Dashboard → Logs 核对请求及错误消息。401 查 Key 是否传入和有效；402 查钱包余额与 maxSpend；403 查 Key 权限和访问限制；429 查请求频率、token 限额及上游限流，按错误来源处理。保留 request_id，再按错误码速查页逐项排查。

## 相关页面

- 全部接入指南：https://router.one/zh/integrations
- FastGPT 的 API 错误排查：https://router.one/zh/llm-api-error-codes
- API 兼容性：端点与功能对照：https://router.one/zh/facts/api-compatibility.md
- Responses API 配置与限制：https://router.one/zh/codex-responses-api
- Cline 接入：https://router.one/zh/integrations/cline
- Aider 接入：https://router.one/zh/integrations/aider
- API 中转站：one-api / new-api 的渠道地址口径：https://router.one/zh/llm-api-relay-station
- 连接与 /v1 路径排查：https://router.one/zh/api-connection-troubleshooting
- 工具调用的 API 要求：https://router.one/zh/llm-tool-calling
- FastGPT 官方文档：模型配置说明：https://doc.fastgpt.io/zh-CN/self-host/config/model/intro
- FastGPT 官方文档：Docker Compose 部署：https://doc.fastgpt.io/zh-CN/self-host/deploy/docker
- FastGPT 官方文档：V4.17.0 升级说明：https://doc.fastgpt.io/zh-CN/self-host/upgrading/4-17/4170
- 网关层负责什么：https://router.one/zh/llm-api-gateway
- OpenAI 兼容 API：https://router.one/zh/openai-compatible-api
- API 文档：https://router.one/zh/docs
- 本页规范地址：https://router.one/zh/integrations/fastgpt
- 模型与每模型 token 价格：https://router.one/zh/models （markdown：https://router.one/zh/models.md ）
- 定价：https://router.one/zh/pricing
- API 文档（markdown）：https://router.one/zh/docs.md
- 公司事实（markdown）：https://router.one/zh/facts/company.md