FastGPT 接入自定义模型:config.json 与 OneAPI 渠道全流程

FastGPT 接入 kkaiapi 两条路:改 docker-compose 的 OPENAI_BASE_URL 直连 https://api.kkaiapi.com/v1,或在 OneAPI 加一个渠道做统一网关,再到 config.json 注册模型重启即生效。知识库场景用本地 bge-m3 做索引,生成侧按任务分层选 DeepSeek、GLM、Claude,质量和账单都能兼顾。

先选路线:config.json 直连还是 OneAPI 渠道

结论先行:只是想让 FastGPT 用上 DeepSeek、Claude、GPT 这些模型,不需要多上游管理,就直接改 docker-compose 环境变量加 config.json 注册模型,十分钟搞定,组件零增加。同时维护多个上游、多套应用要共用一个模型网关,再上 OneAPI 或 New API 做中转,FastGPT 只对接网关一个地址。两条路线最终接的都是同一个 OpenAI 兼容端点 https://api.kkaiapi.com/v1,一个 Key 可调 deepseek-v4-flash、deepseek-v4-pro、glm-5、kimi-k2.6、claude-sonnet-4-6、claude-opus-4-7、gpt-5.5 等全部模型,后续换模型不换端点。

方式一:docker-compose 加 config.json 直连

第一步,改 docker-compose.yml 中 fastgpt 服务的两个环境变量。OPENAI_BASE_URL 必须带 /v1 后缀,FastGPT 会自动拼接 /chat/completions,自己写全路径反而 404。第二步,在挂载进容器的 config.json 里注册模型。llmModels 数组每个对象对应一个模型,复制下面的条目改 model 和 name,就能再注册 claude-sonnet-4-6、glm-5、kimi-k2.6 等其它模型。datasetProcess、usedInClassify 这些开关决定该模型能否出现在知识库处理、问题分类等场景的下拉框里。第三步,执行 docker compose restart fastgpt 让配置生效,新建一个简易应用,模型下拉框里能看到新模型并成功对话即接入完成。FastGPT 4.9 之后也可以在管理后台的模型界面完成同样的注册,字段含义一致,本文以 config.json 为准。

environment:
  - OPENAI_BASE_URL=https://api.kkaiapi.com/v1
  - CHAT_API_KEY=sk-你在kkaiapi控制台生成的Key

方式二:OneAPI 加渠道,FastGPT 无感切换

FastGPT 官方 docker-compose 默认就带 OneAPI,搜 fastgpt oneapi 的人多数卡在渠道怎么填。同样三步: 第一步,进 OneAPI 后台的渠道页新建渠道,类型选 OpenAI,代理地址填 https://api.kkaiapi.com,注意这里不带 /v1,OneAPI 会自己拼接路径。模型栏填入要用的模型 ID,密钥填 kkaiapi 的 sk- Key。第二步,到令牌页新建一个令牌给 FastGPT 专用,FastGPT 的 OPENAI_BASE_URL 指向 OneAPI 地址(同一 compose 里容器互访通常是 http://oneapi:3000/v1),CHAT_API_KEY 填这个令牌。第三步,先用 curl 打 OneAPI 验证整条链路,通了再回 config.json 注册模型名。渠道模型栏、令牌可用模型、config.json 里的 model 三处必须逐字一致,大小写和横杠都不能差,这是 OneAPI 报无可用渠道的头号原因。

curl http://你的OneAPI地址:3001/v1/chat/completions \
  -H "Authorization: Bearer sk-OneAPI令牌" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"ping"}]}'

知识库场景:embedding 和 chat 模型怎么搭

知识库应用的效果由两个模型共同决定:embedding 决定找得准不准,chat 决定答得好不好。回答质量差时先查检索,在 FastGPT 的搜索测试里看命中分段对不对,分段都不对就先调 embedding 和分段策略,轮不到 chat 模型背锅。 embedding 的调用有两处:文档入库时全量向量化一次,之后每次提问再向量化一次问题,入库量大但一次性,提问 token 极少。中文知识库推荐用 Ollama 在本地跑 bge-m3 做索引,配到 config.json 的 vectorModels 里,生成侧全部走 kkaiapi,检索质量、数据私密性和成本三头都占。注意换 embedding 模型后旧知识库必须重建索引,不同模型的向量空间不通用。

常见问题

FastGPT 改了 config.json 为什么不生效?

最常见是没重启容器,config.json 在启动时读取,改完必须 docker compose restart fastgpt。其次检查 JSON 语法,多一个逗号少一个引号都会让整份配置回退默认。最后确认 docker-compose.yml 确实把这份 config.json 挂载进了容器,路径不对时你改的是一个没人读的文件。

FastGPT 一定要配 OneAPI 吗?

不一定。FastGPT 只认 OpenAI 兼容协议,OPENAI_BASE_URL 直接指向 https://api.kkaiapi.com/v1 就能用全部模型,kkaiapi 本身已聚合多家模型,单上游场景再加 OneAPI 纯属多一层维护。只有需要混合管理多个上游、给不同项目分令牌额度时,OneAPI 才有价值。

FastGPT 能用 Claude 模型吗?

能。Claude 官方是 Anthropic 协议,FastGPT 不直接支持,但通过 OpenAI 兼容中转就绕开了协议差异,model 填 claude-sonnet-4-6 或 claude-opus-4-7,按普通 OpenAI 模型注册即可,工具调用和流式输出都正常。

OneAPI 渠道测试一直报错怎么排查?

按顺序查三处:渠道代理地址是否误填了带 /v1 的形式,OneAPI 渠道这里不带 /v1;渠道模型栏、令牌可用模型、请求里的 model 三处名称是否逐字一致;最后在 OneAPI 所在机器上直接 curl 上游端点,确认服务器网络出得去。逐层验证比盲改配置快得多。

换了 embedding 模型,旧知识库还能用吗?

不能直接用。不同 embedding 模型的向量维度和语义空间不同,混用会让检索结果完全错乱。正确做法是新建知识库选新索引模型后重新导入文档,或对原库触发重建索引,数据量大时注意入库耗时。

知识库回答质量差,该换更贵的 chat 模型吗?

先别。用 FastGPT 自带的搜索测试看检索命中,引用分段没找对时换再贵的生成模型也没用,优先调 embedding、分段大小和检索模式。检索正常而回答依然差,再把生成模型升到 claude-sonnet-4-6 这一档对比效果。