很多人本地部署 FastGPT 时，第一道墙不是 FastGPT 本身，而是模型从哪来：手里有 Ollama、有 vLLM、有云端 API 的 key，接口格式和鉴权方式各不相同。OneAPI 的作用就是把这些渠道统一成一套 OpenAI 兼容接口，FastGPT 只认这一个地址。这篇讲怎么分工、按什么顺序配、哪里最容易断，具体数字和版本一律去站内对应页面核对。
本地部署 FastGPT，很多人卡住的地方不是 FastGPT 本身，而是模型从哪来。手里可能同时有 Ollama、有 vLLM，还有几家云端官方接口的 key，接口格式和鉴权方式各不一样。让 FastGPT 去一个个适配，改一次配置动一次刀，很难维护。
比较省心的办法是中间垫一层 OneAPI，把这些渠道统一成一套 OpenAI 兼容接口，FastGPT 只认一个地址和一把令牌。这篇讲三层怎么分工、按什么顺序配、断在哪一层怎么定位。涉及价格、模型版本、跑分这类会变的数字，一律去站内对应页面看当时的数值，本文不写死。
先想清楚为什么要多一层 OneAPI
多一层不是为了好看，是为了解耦。FastGPT 侧只要填一个 base URL 和一把 key，模型怎么换、换到哪家，都在 OneAPI 里改渠道。哪天本地推理服务重启换了端口，或者临时加一家云端兜底，FastGPT 这边完全不用动。
- FastGPT 按 OpenAI 兼容格式填地址和 key，用 OneAPI 当统一出口就不必为每个模型单独改配置
- 真正的模型可以来自本地推理服务，也可以来自云端官方接口，切换只改 OneAPI 渠道，不动 FastGPT
- OneAPI 还能顺手做令牌分组和用量查看，谁能用哪些模型在一层里就能管住
- 什么情况下不需要：只接一个本地模型、永远不换、也不做多模型对比，那直连更省事，多一层反而多一个故障点
三层各自负责什么，别配串了
把整条链路想成三层：推理层、OneAPI 层、FastGPT 层。每一层只关心自己上下两端的接口，出问题时才能一段一段量，而不是对着一堆日志猜。
| 层 | 负责什么 | 填错时的典型表现 |
|---|---|---|
| 推理层 | 把模型跑起来并暴露一个 HTTP 地址 | 本地 curl 就不通，或返回模型不存在 |
| OneAPI 层 | 渠道、令牌、模型名映射 | 渠道测试按钮报错，或模型列表里找不到名字 |
| FastGPT 层 | 填 OneAPI 地址与令牌、向量与重排模型名 | 能连上但检索为空，或问答直接报模型错误 |
一个容易忽略的点：FastGPT 里填的模型名，必须是 OneAPI 对外暴露的那个名字，不是推理服务内部的原始名字。两边名字对不上，链路能通却调不到模型。模型清单和对应关系可以到 模型资料库（/models） 核对，那里维护的是站内当前收录的对照信息。
按这个顺序配，出问题好定位
配置顺序本身就是排查工具。从最下层往上配，每配一层就验一层，出问题一定是你刚刚动过的那一层，范围最小。
- 起推理服务并单独验证先把本地推理服务跑起来，用 curl 或站内接口工具打一次，确认单模型能出字再往下走。这一步不通，后面全是白搭。
- 起 OneAPI 并逐个加渠道每加一个渠道就用自带测试打一次，通过了再加下一个。一次加完再统一测，出了错不知道是哪个渠道的问题。
- 起 FastGPT 依赖组件数据库与向量库先起来，确认健康检查通过，再启动 FastGPT 应用本体。依赖没就绪就起应用，日志里全是连接失败，干扰判断。
- 后台配模型再建库进 FastGPT 后台先配好对话、向量、重排模型，再建知识库、上传一个小文件做一次完整问答，最后才接业务数据。
- 检查容器间地址容器之间通信用服务名而不是 localhost，这类地址写错是最常见的断链原因，配完顺手核对一遍。
如果你不确定各家接口实际的响应速度差异，可以先到 接口测速（/tools/speed-test） 量一遍基线，再回头对比应用侧表现，能省下不少来回试的时间。
对不上号时按这个顺序排查
排查的核心思路是从下往上，一层一层确认接口通不通，而不是一上来就翻 FastGPT 日志。上游没通，应用侧日志只会给你一堆误导性的报错。多数问题集中在四类原因上，按这个清单过一遍，命中率不低。
- 模型名不一致：OneAPI 暴露的名字和 FastGPT 里填的名字对不上
- 令牌额度用尽或被禁用：换一把新令牌测一下就知道
- 上下文长度超出：长文档问答时提示超长，多半是这里
- 向量模型维度与建库时不匹配：改了嵌入模型但没重建索引，检索必然为空
链路能通不等于能调模型，名字对得上才算真的接上。
拿不准某个云端渠道当前是否稳定，可以参考 中转站导航（/sites） 里维护的可信度与在线状态信息，那里会定期更新检测结果，比你自己反复试要快。
哪些情况这套搭法不合适
这套方案不是万能的，有几类场景硬套反而添麻烦。判断标准很简单：看你对延迟、复杂度和合规的敏感程度，哪一条压过便利性，就别用这套。
- 对延迟极敏感、要求一跳直达的场景：中间多一层就是多一次转发开销
- 只需要单模型、单用户、不做知识库的轻量试用：直接连推理服务更快
- 合规上要求所有组件都过审或必须走国产化栈：选型清单要单独过一遍，不能照搬通用方案
- 团队里没人愿意维护多一个服务：那这层的收益抵不过运维成本，直连更现实
要不要上这层，本质是拿运维复杂度换灵活性。受益最多的是要接多种模型来源、又要频繁切换的团队；受益最小的就是单模型固定跑的小场景。
下一步把模型来源、接口地址和当前可用性对一遍，再决定哪些接本地、哪些走云端，配的时候能少走弯路。→常见问题
OneAPI 和 FastGPT 必须部署在同一台机器上吗？
不是必须。同机部署接线最简单，容器间用服务名互访即可；分开部署要确认网络可达、端口开放、以及两边的时区和日志时间对得上。分开的好处是模型侧可以独立扩容或换卡，代价是排查时要多看一层网络。
为什么渠道测试通过了，FastGPT 里还是用不了？
渠道测试只验证了 OneAPI 到模型这一段。FastGPT 侧还要单独填模型名、向量模型和重排模型，名字必须和 OneAPI 暴露的一致；另外知识库维度在建库时就定了，换向量模型往往要重建索引，不是改个名字就能生效。
本地跑不动大参数模型，还能用这套结构吗？
可以。这套结构的价值就在于模型来源可替换：本地只跑得动小模型就先跑小的，把重活分流到云端渠道，FastGPT 侧不用改。具体哪种量化档位、多大显存够用，去站内的部署测算页面按你的参数量和并发算一遍再决定。
