FastGPT API 配置教程：接入 GPT、Claude、Gemini 等 100+ 模型完整指南

核心要点

FastGPT 是目前最流行的开源 RAG 知识库平台（GitHub 80k+ Star），但它本身不内置大模型——你需要配置外部 API 才能让它跑起来。本文覆盖 FastGPT 模型配置的三种方式：内置 AI Proxy（推荐）、OneAPI 中间件（经典方案）和自定义请求地址（简单场景），帮你 10 分钟内完成从零到可用的模型接入。

FastGPT 模型配置为什么重要

FastGPT 是一个基于大模型的知识库平台，核心能力包括：

• RAG 检索增强生成：将你的文档、网页、数据库变成 AI 可检索的知识库
• 可视化工作流：拖拽式构建复杂的 AI 应用逻辑
• 多模型协作：在一个工作流中调用不同模型处理不同任务

但所有这些能力都建立在一个前提上：你必须正确配置至少一个语言模型和一个索引（Embedding）模型。没有模型，FastGPT 什么都做不了。

FastGPT 支持的模型类型包括：

方式一：内置 AI Proxy（推荐）

从 v4.8.23 版本起，FastGPT 内置了 AI Proxy 模型聚合服务，直接在页面上配置即可，不需要额外部署 OneAPI。这是目前最推荐的方式。

第一步：添加模型渠道

进入 FastGPT 后台，导航到 账号 → 模型提供商 → 模型渠道，点击右上角「新增渠道」：

渠道名称：OpenAI（或任意标识名称）
协议类型：OpenAI
模型：选择你需要的模型（如 gpt-4o、gpt-5）
代理地址：https://api.openai.com（注意不要加 /v1）
API 密钥：sk-xxxxxxxxxxxx

配置说明：

• 协议类型：大多数模型供应商都兼容 OpenAI 协议，直接选 OpenAI 即可。Anthropic、Google 等有专属协议类型可选
• 代理地址：填 Base URL，不要填完整的 /v1/chat/completions 路径。注意看供应商文档是否需要加 /v1
• 模型：系统内置了主流模型列表。如果下拉框没有你要的模型，点击「新增模型」添加自定义模型

第二步：模型映射（可选）

如果你的 API 提供商用了不同的模型名称，可以配置模型映射：

{
  "gpt-4o": "gpt-4o-2024-11-20"
}

FastGPT 内部使用 gpt-4o，但实际请求时会映射为 gpt-4o-2024-11-20 发送给上游。

第三步：测试渠道

配置完成后，点击渠道列表中的「模型测试」按钮。系统会对每个模型发送一个测试请求，返回结果和响应时间。确保所有模型都通过测试再投入使用。

第四步：启用模型

切换到「模型配置」标签页。系统内置了主流模型的配置参数（上下文长度、最大回复 token 等），点击「启用」即可。

注意：模型配置中的「模型 ID」必须和渠道中添加的模型名完全一致，否则请求会找不到对应渠道。

方式二：通过 OneAPI 接入（经典方案）

如果你使用的是 v4.8.23 之前的版本，或者已经在用 OneAPI 管理多个模型供应商，可以通过 OneAPI 作为中间层。

部署 OneAPI

OneAPI 支持 Docker 一键部署：

docker run -d --name oneapi \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v /opt/oneapi:/data \
  justsong/one-api:latest

启动后访问 http://localhost:3000，默认账号 root，密码 123456。

在 OneAPI 中添加渠道

1. 进入 OneAPI 后台 → 渠道管理 → 添加新渠道
2. 选择渠道类型（OpenAI、Anthropic、Google 等）
3. 填入对应供应商的 API Key 和代理地址
4. 选择该渠道支持的模型

配置 FastGPT 连接 OneAPI

修改 FastGPT 的 docker-compose.yml 环境变量：

environment:
  # OneAPI 的访问地址，注意必须加 /v1
  - OPENAI_BASE_URL=http://oneapi:3000/v1
  # OneAPI 中创建的令牌
  - CHAT_API_KEY=sk-your-oneapi-token

重启 FastGPT 容器使配置生效：

docker restart fastgpt

OneAPI 令牌注意事项：创建令牌时不要设置模型范围权限限制，否则容易出现模型匹配失败的问题。

迁移到 AI Proxy

如果你已经在 OneAPI 中配置了大量渠道，可以用官方迁移脚本一键导入到 AI Proxy：

curl --location --request POST 'http://your-aiproxy:port/api/channels/import/oneapi' \
--header 'Authorization: Bearer your-admin-key' \
--header 'Content-Type: application/json' \
--data-raw '{
    "dsn": "mysql://user:pass@tcp(host:port)/dbname"
}'

迁移后建议手动检查渠道配置是否正确。

方式三：自定义请求地址（简单场景）

如果你只用一两个模型，不想配置渠道体系，可以在模型配置中直接填写自定义请求地址。这种方式绕过 AI Proxy/OneAPI，直接向目标地址发请求。

需要填写完整路径：

所有接口遵循 OpenAI API 格式。这种方式简单直接，但不支持负载均衡和日志监控。

实战：用 API 聚合平台一站式接入 100+ 模型

对国内开发者来说，最大的痛点是：OpenAI、Anthropic、Google 的 API 在国内无法直连。即使部署了 FastGPT，也用不上 GPT-5、Claude、Gemini 这些顶级模型。

解决方案是使用兼容 OpenAI 协议的 API 聚合平台。以 Ofox 为例，一个 API Key 就能调用 100+ 模型，包括 GPT-5.3 Codex、Claude Opus 4.6、Gemini 3.1 Pro、DeepSeek V3.2 等。

配置步骤

1. 获取 API Key

在 Ofox 控制台 注册并创建 API Key。

2. 在 FastGPT 中添加渠道

进入 模型渠道 → 新增渠道：

渠道名称：Ofox（GPT + Claude + Gemini）
协议类型：OpenAI
模型：gpt-5, gpt-4o, claude-opus-4-6, claude-sonnet-4, gemini-3-pro, deepseek-chat, ...
代理地址：https://api.ofox.ai/v1
API 密钥：sk-your-ofox-key

3. 启用模型并测试

在模型配置中启用需要的模型，然后运行渠道测试确认连通。

这种方案的优势

• 一个渠道覆盖所有模型：不需要分别注册 OpenAI、Anthropic、Google 账号
• 国内低延迟直连：通过加速节点访问，无需额外网络配置
• 统一计费：支付宝/微信充值，按用量付费
• 与 FastGPT 原生兼容：完全走 OpenAI 协议，零改造

添加自定义模型

如果系统内置的模型列表没有你需要的模型（比如刚发布的新模型），可以手动添加。

通过页面添加

在 模型配置 页面点击「新增自定义模型」，填写模型参数。

通过配置文件添加

适合批量配置或跨系统迁移。语言模型的 JSON 配置示例：

{
  "model": "gpt-5",
  "metadata": {
    "isCustom": true,
    "isActive": true,
    "provider": "OpenAI",
    "model": "gpt-5",
    "name": "GPT-5",
    "maxContext": 256000,
    "maxResponse": 32000,
    "quoteMaxToken": 240000,
    "maxTemperature": 1.2,
    "vision": true,
    "datasetProcess": true,
    "usedInClassify": true,
    "usedInExtractFields": true,
    "usedInToolCall": true,
    "toolChoice": true,
    "functionCall": false
  }
}

索引模型的配置示例：

{
  "model": "text-embedding-3-small",
  "metadata": {
    "isCustom": true,
    "isActive": true,
    "provider": "OpenAI",
    "model": "text-embedding-3-small",
    "name": "Embedding-3-Small",
    "defaultToken": 512,
    "maxToken": 8191
  }
}

关键字段说明：

• model：模型 ID，全局唯一，必须和渠道中的模型名一致
• maxContext：最大上下文 token 数
• maxResponse：最大回复 token 数
• vision：是否支持图片输入（多模态模型设为 true）
• toolChoice：是否支持工具调用（Function Calling）
• datasetProcess：是否可用于知识库 QA 处理

模型分级策略：成本与效果的平衡

FastGPT 支持在工作流不同环节使用不同模型，这是优化成本的关键：

通过这种分级策略，可以在保证回答质量的同时，将 API 成本降低 60-80%。

常见报错与解决方案

401 Unauthorized

原因：API Key 无效或过期。

排查步骤：

1. 检查 Key 是否正确复制（注意首尾空格）
2. 确认 Key 未被吊销或过期
3. 如果用 OneAPI，检查令牌是否有效

404 Not Found

原因：模型名称不匹配。

排查步骤：

1. 确认模型配置中的「模型 ID」和渠道中的「模型」完全一致
2. 检查代理地址是否正确（是否多加或少加了 /v1）

模型测试超时

原因：网络不通或代理地址错误。

排查步骤：

1. 在服务器上用 curl 测试 API 连通性：

curl -X POST https://your-api-url/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"hi"}]}'

2. 检查 Docker 网络配置，确保 FastGPT 容器能访问外网或 OneAPI 容器

知识库报错「未找到可用的索引模型」

原因：没有启用 Embedding 模型。

解决：在模型配置中至少启用一个索引模型（如 text-embedding-3-small），并确保对应渠道已正确配置。

总结

FastGPT 的模型配置有三种方式，按推荐顺序：

1. 内置 AI Proxy（v4.8.23+）：最简单，页面上直接配置渠道和模型，自带负载均衡和日志
2. OneAPI 中间件：适合已有 OneAPI 基础设施的团队，配置灵活但需要额外维护
3. 自定义请求地址：最轻量，适合只用一两个模型的简单场景

对国内开发者来说，推荐使用兼容 OpenAI 协议的 API 聚合平台作为上游，一个渠道就能接入 GPT、Claude、Gemini 等 100+ 模型，省去分别注册和网络配置的麻烦。

参考资料

• FastGPT 官方文档 - 模型配置说明
• FastGPT 官方文档 - 通过 OneAPI 接入模型
• FastGPT GitHub 仓库
• OneAPI GitHub 仓库
• Ofox API 文档