跳转至

FastGPT 接入 OpenAI 兼容 API：模型渠道、知识库与应用发布完整教程

最后核验：2026-07-14

适用范围：FastGPT 当前云端版与自托管版（AI Proxy 模型管理界面）

推荐路径：先配置语言模型与 Embedding 模型，再创建知识库和应用

← 返回教程目录

[!NOTE] 本文适用于任何符合对应协议的 API。还没有测试 Key 时，可查看 教程配套 API。

1. FastGPT 适合什么场景

FastGPT 是以知识库、工作流和 Agent 为重点的 AI 应用平台，适合：

  • 企业文档问答、客服机器人和内部知识助手；
  • 用可视化节点编排模型、检索、条件与工具；
  • 管理语言、Embedding、Rerank、语音等多类模型；
  • 把完成的应用发布给网页或第三方客户端；
  • 私有化部署并自行管理数据、模型和成员。

FastGPT 自托管版包含主服务、数据库、向量数据库、对象存储、AI Proxy、插件等组件，维护成本高于普通聊天客户端。

2. 关键概念

名称 含义
模型配置 定义 FastGPT 中可选择的模型 ID、类型与能力
模型渠道 定义模型请求实际发往哪里、使用什么协议和 Key
模型映射 把 FastGPT 内部模型 ID 映射为 API 接受的真实模型 ID
应用 API Key 外部调用 FastGPT 应用的凭据，不是模型渠道 Key

当前官方文档明确要求系统至少配置一个语言模型和一个 Embedding 模型，才能完整使用基础功能。

3. 准备信息

  • API Key；
  • OpenAI 兼容 Base URL；
  • 聊天模型 ID；
  • Embedding 模型 ID；
  • 可选的 Rerank、TTS、STT 模型 ID；
  • 自托管时准备 Docker、Docker Compose、域名和备份空间。

典型 Base URL：

https://<你的-api-域名>/v1

渠道的 Proxy URL 要填 Base URL，不要填完整请求端点：

正确： https://<你的-api-域名>/v1
错误： https://<你的-api-域名>/v1/chat/completions

4. Docker Compose 自托管（可选）

云端版用户可跳到第 5 节。官方当前推荐通过交互式部署脚本生成配置；测试环境最低约 2 核 4 GiB，知识库规模和并发上升后需要更多 CPU、内存和磁盘。

更谨慎的执行方式是先下载并检查脚本：

curl -fsSL https://doc.fastgpt.cn/deploy/install.sh -o install.sh
less install.sh
bash install.sh

脚本会引导选择向量数据库和部署参数，并生成随机密码及最终 docker-compose.yml。务必保存脚本输出的 root 密码和最终 Compose 文件。

启动与检查：

docker compose up -d
docker compose ps
docker compose logs --tail=200

默认访问端口通常是 3000。公网部署应配置域名和 HTTPS，而不是直接暴露管理端口。

资源选择

  • 小规模测试和中小知识库：优先官方推荐的轻量向量数据库方案；
  • 大规模向量数据：根据官方规格选择更高性能方案；
  • 对象存储地址必须能同时被浏览器与 FastGPT 服务访问；
  • Docker 网络里的 127.0.0.1 只代表当前容器，不能代替宿主机或其他容器。

5. 进入模型供应商页面

  1. 登录 FastGPT；
  2. 打开 账号 → 模型供应商；
  3. 进入 模型渠道 标签；
  4. 点击右上角 新增渠道；
  5. 准备添加 OpenAI 协议渠道。

首次登录如果系统提示语言模型或索引模型未配置，按提示跳转到同一页面即可。

6. 添加 OpenAI 兼容渠道

推荐配置：

字段 填写内容
渠道名称 自定义易识别名称，如“主聊天渠道”
协议类型 OpenAI
模型 选择或新增准确的模型 ID
Proxy URL https://<你的-api-域名>/v1
API Key <你的API-Key>
优先级 单渠道保持默认即可

多数 OpenAI 兼容接口可使用 OpenAI 协议类型。协议选错会导致请求体、鉴权头或流式格式不匹配。

模型不在下拉列表

  1. 在渠道表单点击 新增模型，或切换到 模型配置；
  2. 选择模型类型；
  3. 填写精确模型 ID；
  4. 根据模型真实能力设置上下文、输出长度、视觉、推理和工具调用；
  5. 保存后回到渠道，将该模型加入渠道。

模型 ID 在 FastGPT 中必须全局唯一。

7. 模型映射

如果希望 FastGPT 内显示友好 ID，但 API 需要另一个真实 ID，可配置映射：

{
  "<FastGPT中的模型ID>": "<API实际模型ID>"
}

没有重命名需求时不要增加映射。映射写反、拼写错误或两端类型不同都会造成模型不存在错误。

8. 渠道测试与启用

  1. 保存渠道；
  2. 在渠道操作菜单点击 模型测试；
  3. 选择模型并开始测试；
  4. 查看成功状态与响应时间；
  5. 回到 模型配置；
  6. 确认目标模型已经 启用；
  7. 用模型配置页的测试功能再发一次请求。

渠道测试会真实调用 API 并产生用量。首次只测一个模型，避免一次测试全部模型造成不必要消耗。

9. 添加 Embedding 模型

知识库向量检索需要 Embedding 模型：

  1. 在 模型配置 新增或启用一个 Embedding 模型；
  2. 模型 ID 填 <Embedding模型ID>；
  3. 在 模型渠道 中把它加入 OpenAI 协议渠道；
  4. 使用同一 Base URL 和有该模型权限的 Key；
  5. 单独运行 Embedding 测试。

兼容接口通常调用：

POST /v1/embeddings

Embedding 模型的向量维度一旦用于知识库索引，不应直接替换成不同维度。更换时应重新建立或完整重建索引。

10. 可选：Rerank、TTS 与 STT

类型 常见端点 用途
Rerank /v1/rerank 对初步召回片段重新排序
TTS /v1/audio/speech 文字转语音
STT /v1/audio/transcriptions 语音转文字

Rerank 常采用 Cohere 风格请求，并非所有“OpenAI 兼容”接口都支持。FastGPT 当前只允许同时启用一个语音识别模型。每种模型都应单独测试，不能用聊天成功来推断它们可用。

11. 创建第一个知识库

  1. 进入 知识库，点击新建；
  2. 选择已测试的索引/Embedding 模型；
  3. 上传一份短小、结构清晰的测试文档；
  4. 检查文件解析预览；
  5. 选择分段方式并设置块大小；
  6. 等待索引完成；
  7. 使用搜索测试输入文档中确实存在的问题；
  8. 查看命中的片段、分数与排序。

文档处理模型与索引模型

  • 文档处理模型：用于增强处理、生成问题或问答拆分；
  • 索引模型：用于把文本向量化并支持语义检索。

两者职责不同。索引无进度时，优先检查 Embedding 请求和 Worker，而不是只换聊天模型。

12. 创建知识库问答应用

最小流程：

用户问题 → 知识库搜索 → AI 对话 → 输出

建议：

  1. 先创建对话型应用；
  2. 选择已验证的语言模型；
  3. 绑定刚建立的知识库；
  4. 先保留默认参数；
  5. 用 5～10 个答案明确的问题测试；
  6. 观察引用片段是否正确；
  7. 再调整 Top K、相似度、Rerank 与提示词。

如果检索片段正确但答案不对，调提示词和语言模型；如果片段就错了，先调分段、Embedding 和召回参数。

13. AI 参数建议

参数 建议
历史轮数 客服与知识问答保持较少，降低噪声和成本
最大回复 设置满足业务的合理上限
Temperature 事实问答较低，创意写作可提高
引用上限 给系统提示、历史与输出留出上下文空间
多模态 只有模型和接口都支持时开启
工具调用 用一个简单工具先验证协议兼容性

推理、视觉、JSON、工具调用等能力开关必须与真实接口能力一致。

14. 发布应用并从第三方调用

完成应用测试后：

  1. 打开应用的 发布渠道 → API；
  2. 创建 FastGPT API Key；
  3. 设置额度和过期时间；
  4. 找到应用 ID；
  5. 第三方调用时使用 FastGPT 的应用地址，而不是模型供应商 Base URL。

FastGPT 的 OpenAPI 基础地址通常类似：

https://<你的-FastGPT-域名>/api

BaseURL 是端点根路径，直接在浏览器打开不一定有内容。调用聊天接口时推荐在请求体传 appId；如果第三方只能接受 OpenAI 风格 Key，可按 FastGPT 官方文档使用兼容格式。

不要把模型渠道 Key 分发给应用用户。

15. 旧版环境变量配置

官方当前推荐通过 AI Proxy 的模型供应商页面管理渠道。某些旧部署或未配置 AI Proxy 的场景仍会读取：

OPENAI_BASE_URL=https://<你的-api-域名>/v1
CHAT_API_KEY=<你的API-Key>

修改后需要按部署方式重建对应容器：

docker compose up -d
docker compose ps

不要同时维护多套相互冲突的 UI 渠道与环境变量配置。以当前部署版本的官方说明为准。

16. Docker 网络注意事项

FastGPT 容器访问宿主机服务时，不能使用容器内的 localhost。

Docker Desktop 常见地址：

http://host.docker.internal:<端口>/v1

同一 Compose 网络中的服务应使用服务名和容器端口。对象存储的外部访问地址不得使用 127.0.0.1，否则浏览器访问签名 URL 时可能出现 403 或无法连接。

17. 常见错误

401 Unauthorized

  • Key 错误、过期或粘贴带空格；
  • 把 FastGPT 应用 Key 填进模型渠道；
  • 目标接口要求的鉴权格式不兼容。

404 Not Found

  • Proxy URL 漏写 /v1；
  • 错填了完整 /chat/completions；
  • 反向代理删除或重复添加路径；
  • 模型协议类型选错。

模型测试成功但应用失败

  • 应用选的是另一个模型 ID；
  • 模型未启用；
  • 打开了渠道不支持的视觉、工具或推理参数；
  • 应用上下文超过模型限制。

知识库索引没有进度

  • Embedding 模型未启用或测试失败；
  • Worker、数据库、向量库或对象存储异常；
  • 文档解析失败；
  • 请求超时、限流或输入长度超限。

查看日志时先定位失败组件，不要盲目重启全部服务。

429 / 请求过多

  • 降低知识库批量索引并发；
  • 减少工作流并行分支；
  • 使用指数退避；
  • 检查 Key 的额度与限速。

502 / 504 / 流中断

  • 检查 FastGPT 到 API 的网络；
  • 检查反向代理流式缓冲与超时；
  • 用非流式最小请求区分接口和代理问题；
  • 查看模型调用日志和容器日志。

18. 安全与生产检查

  • 首次部署立即更换 root 密码和所有服务 Token；
  • 不把 docker-compose.yml、.env、Key 或数据库密码提交到公开仓库；
  • 使用 HTTPS 和受控的管理入口；
  • 给不同环境和团队分配不同 Key；
  • 给发布的应用 Key 设置额度、范围与过期时间；
  • 定期检查模型调用日志和异常用量；
  • 文档、日志与截图中隐藏用户内容和凭据；
  • 按需安装插件，不运行来源不明的包；
  • 为数据库、向量库、对象存储和配置做加密备份。

19. 升级、备份与回滚

升级前保存：

  • 当前 FastGPT 与插件版本；
  • 最终生成的 docker-compose.yml；
  • MongoDB 数据；
  • 向量数据库数据；
  • 对象存储数据；
  • AI Proxy 渠道和模型配置；
  • 各服务密钥、域名与反向代理配置。

升级顺序：

  1. 阅读目标版本升级文档，不跨越官方要求的中间版本；
  2. 安排维护窗口并停止写入；
  3. 制作一致性备份并验证恢复；
  4. 在测试实例验证升级；
  5. 修改镜像标签后运行 docker compose up -d；
  6. 执行该版本要求的初始化或迁移；
  7. 验证登录、模型测试、索引、搜索、应用和 API。

回滚时必须恢复与旧镜像匹配的数据快照和 Compose 配置。只降镜像、不回滚已迁移的数据可能造成结构不兼容。

20. 官方资料

求助时请提供 FastGPT 版本、部署方式、模型类型、脱敏后的 Base URL 结构、模型 ID、HTTP 状态码和相关服务日志。务必删除 Key、密码、内部文档和用户对话。