1. FastGPT 离线部署后模型调用链路为什么总出问题FastGPT 全部离线部署这件事真正麻烦的地方从来不是把容器拉起来而是拉起来之后模型怎么调。FastGPT 本身是一个知识库问答编排平台它自己不产出模型能力所有对话、向量化、重排、图表生成都要通过 OpenAI 兼容接口去请求外部服务。离线环境里没有公网你就得在内网里自己搭一套模型网关把各家模型的地址和 Key 收敛到一个入口。我见过太多内网部署的现场是这样的FastGPT 的OPENAI_BASE_URL指向一台 OneAPIOneAPI 里又配了七八个渠道每个渠道一个 Key向量模型走 m3e 的 6008 端口重排走另一个服务图表渲染又走 gpt-vis-api 的 3100 端口。结果就是配置文件里散落着四五个不同的 endpointKey 更是东一个西一个。哪天某个 Key 过期了你得挨个容器进去翻环境变量排查半小时才发现是某个渠道的密钥失效。这篇要解决的就是这个链路问题。核心思路是在 FastGPT 和底层模型服务之间放一个统一的 Key 通道把 endpoint 和鉴权都收敛到一处。TaoToken 在这里扮演的就是这个统一入口的角色——它提供 OpenAI 兼容的/v1接口你只需要在 FastGPT 侧改一个OPENAI_BASE_URL和一个CHAT_API_KEY所有模型调用都从这一个口子出去。对于内网离线场景你可以在内网网关层做一次地址映射让 FastGPT 容器访问的是一个内网可达的地址实际请求再转发到统一通道。适合谁看已经用 docker compose 把 FastGPT 全家桶pg、mongo、redis、minio、sandbox、aiproxy跑起来但被多模型 Key 管理折磨的运维和开发以及准备做内网知识库、要求调用链路可审计、可回滚的团队。下面我会给出可直接复制的 compose 片段、config.json配置、连通性验证命令以及出问题时的回滚步骤。先说清楚一个前提FastGPT 的模型调用有两条路径。一条是老的OPENAI_BASE_URLCHAT_API_KEY直连另一条是走 AI Proxy通过AIPROXY_API_ENDPOINTAIPROXY_API_TOKEN。两条路径的优先级是 AI Proxy 更高只要配了AIPROXY_API_ENDPOINTFastGPT 就优先走它。所以你要统一 Key 通道得先确认自己走的是哪条别改了半天发现根本没生效。这个坑我后面在排障章节会详细讲。2. TaoToken 统一 Key 通道的前置准备与地址规划在动手改配置之前先把地址和凭证规划清楚否则后面改到一半发现端口冲突或者网络不通返工成本很高。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。注意 API 地址后面不加任何查询参数FastGPT 里填的OPENAI_BASE_URL要带上/v1也就是最终形态是https://taotoken.net/api/v1。这个/v1千万别漏漏了会直接返回 404FastGPT 日志里看到的是一堆reading choices相关的解析错误很容易误判成模型问题。凭证方面你需要先在控制台创建一个 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建出来的 Key 形如sk-开头的一串字符这个 Key 就是你要填进 FastGPT 的CHAT_API_KEY。模型 ID 这块要特别注意。FastGPT 在调用对话模型时会把你配置里的模型名原样传给接口。所以你在 TaoToken 侧能用哪些模型取决于你的账号权限和通道配置。常见的对话模型 ID 比如gpt-4o、claude-3-5-sonnet这类向量模型比如text-embedding-3-small。你可以在模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 先手动发一条消息确认模型 ID 拼写正确、通道可用再去改 FastGPT 配置。这一步能省掉大量「配置没错但就是不通」的排查时间。内网离线场景的地址规划核心是解决「FastGPT 容器能不能访问到 TaoToken」这个问题。如果你的部署环境完全无外网那 FastGPT 容器直连taotoken.net是不通的。这时候有两种做法第一种在内网网关比如一台能出网的跳板机或者反向代理上做转发把内网某个地址映射到 TaoToken 的 API。FastGPT 里填的是内网地址网关负责出网。这种做法的好处是 FastGPT 侧完全无感坏处是你得维护网关的高可用。第二种如果你的环境允许容器访问外网那直接在OPENAI_BASE_URL里填https://taotoken.net/api/v1即可最简单。下面我按第二种来写配置第一种只需要把地址换成你的内网映射地址其余完全一致。网络规划上还要注意一点FastGPT 的 compose 里定义了一个fastgpt网络所有服务都在这个网络里。如果你要加一个统一通道的代理容器记得把它也加入fastgpt网络这样 FastGPT 容器可以用服务名访问它而不是依赖宿主机 IP。用服务名比用 IP 稳IP 变了不用改配置。最后提醒一句CHAT_API_KEY这个环境变量在 FastGPT 里是明文写在 compose 文件里的。生产环境建议用 docker secret 或者外部环境变量文件别直接提交到代码仓库。下面示例里我会用占位符你替换成自己的真实 Key。3. 可复制的 FastGPT 与 TaoToken 接入配置片段这一节是全文的核心给出可以直接粘贴的配置。分三块FastGPT 的 compose 环境变量、config.json里的模型定义、以及可选的 AI Proxy 配置。先看 FastGPT 主服务的环境变量。找到你 compose 文件里fastgpt或fastgpt3服务下的environment段把OPENAI_BASE_URL和CHAT_API_KEY改成下面这样fastgpt: container_name: fastgpt image: registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt:v4.8.1 ports: - 3000:3000 networks: - fastgpt depends_on: - mongo - sandbox - pg restart: always environment: - FE_DOMAIN - DEFAULT_ROOT_PSW1234 # 统一 Key 通道TaoToken 的 OpenAI 兼容地址务必带 /v1 - OPENAI_BASE_URLhttps://taotoken.net/api/v1 # 统一鉴权 Key替换成你在控制台创建的真实 Key - CHAT_API_KEYsk-你的TaoToken密钥 - TOKEN_KEYany - ROOT_KEYroot_key - FILE_TOKEN_KEYfiletoken - AES256_SECRET_KEYfastgptkey - PLUGIN_BASE_URLhttp://fastgpt-plugin:3000 - PLUGIN_TOKENxxxxxx - SANDBOX_URLhttp://sandbox:3000 - DB_MAX_LINK30 - MONGODB_URImongodb://myusername:mypasswordmongo:27017/fastgpt?authSourceadmin - REDIS_URLredis://default:mypasswordredis:6379 - PG_URLpostgresql://username:passwordpg:5432/postgres - LOG_LEVELinfo - STORE_LOG_LEVELwarn - WORKFLOW_MAX_RUN_TIMES1000 - WORKFLOW_MAX_LOOP_TIMES100 - CHAT_FILE_EXPIRE_TIME7 volumes: - ./config.json:/app/data/config.json注意这里我把AIPROXY_API_ENDPOINT和AIPROXY_API_TOKEN两行去掉了。原因前面说过AI Proxy 优先级更高只要它存在FastGPT 就不走OPENAI_BASE_URL。你要用统一通道就得先把 AI Proxy 这条路断掉否则改了OPENAI_BASE_URL也不生效。如果你确实想保留 AI Proxy那就得在 AI Proxy 侧配置上游那是另一套改法本文按直连统一通道来写。接下来是config.json。FastGPT 的模型列表、向量模型、重排模型都在这个文件里定义。它挂载在/app/data/config.json你本地 compose 目录下应该有一个同名文件。关键字段是llmModels、vectorModels、reRankModels里的requestUrl和requestAuth。改成统一通道后所有模型的requestUrl都指向同一个地址{ feConfigs: { lafEnv: https://laf.dev }, systemEnv: { vectorMaxProcess: 15, qaMaxProcess: 15, vlmMaxProcess: 15, tokenWorkers: 30, pgHNSWEfSearch: 100 }, llmModels: [ { model: gpt-4o, name: gpt-4o, maxContext: 128000, maxResponse: 16000, quoteMaxToken: 120000, maxTemperature: 1.2, vision: true, toolChoice: true, functionCall: true, defaultSystemChatPrompt: , requestUrl: https://taotoken.net/api/v1/chat/completions, requestAuth: sk-你的TaoToken密钥 }, { model: claude-3-5-sonnet, name: claude-3-5-sonnet, maxContext: 200000, maxResponse: 8000, quoteMaxToken: 180000, maxTemperature: 1.0, vision: true, toolChoice: true, functionCall: true, requestUrl: https://taotoken.net/api/v1/chat/completions, requestAuth: sk-你的TaoToken密钥 } ], vectorModels: [ { model: text-embedding-3-small, name: text-embedding-3-small, defaultToken: 512, maxToken: 3000, weight: 100, requestUrl: https://taotoken.net/api/v1/embeddings, requestAuth: sk-你的TaoToken密钥 } ], reRankModels: [], audioSpeechModels: [], whisperModel: {} }这里有个细节requestUrl要写到具体的端点比如/v1/chat/completions和/v1/embeddings而不是只写到/v1。FastGPT 在部分版本里不会自动补全路径写错了会 404。requestAuth就是你的 Key注意它和环境变量里的CHAT_API_KEY是两套东西——config.json里的模型定义优先如果你在config.json里写了requestAuthFastGPT 就用这个环境变量里的CHAT_API_KEY反而可能被忽略。所以两处都要填成同一个 Key保持一致最省心。如果你走的是 AI Proxy 路径那配置在aiproxy服务里需要设置上游通道。但本文主线是直连统一通道AI Proxy 这块只提一句它的ADMIN_KEY和 FastGPT 里的AIPROXY_API_TOKEN要对应上游地址在 AI Proxy 的管理后台配置。改完记得重启aiproxy容器。配置改完执行重启docker compose down docker compose up -d docker compose logs -f fastgpt看日志里有没有Mongo connected、Redis connected、PG connected这类成功信息以及有没有模型加载相关的报错。如果config.json格式写错了FastGPT 启动时会直接报 JSON 解析失败日志里能看到具体行号。4. 连通性验证与成功结果确认配置改完不代表通了必须做连通性验证。分三层验证容器网络层、接口层、FastGPT 应用层。第一层容器网络层。先进 FastGPT 容器确认能不能解析并访问到 TaoToken 的地址docker exec -it fastgpt sh # 容器内执行 curl -I https://taotoken.net/api/v1/models如果返回HTTP/2 401或者HTTP/2 200说明网络是通的401 是因为没带 Key正常。如果卡住或者报Could not resolve host那就是容器出网有问题回到上一节检查网关或 DNS 配置。第二层接口层。在宿主机或者容器内用真实 Key 发一个最小请求确认鉴权和模型都可用curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -d { model: gpt-4o, messages: [{role: user, content: ping}], max_tokens: 10 }成功的返回长这样{ id: chatcmpl-xxxx, object: chat.completion, created: 1730000000, model: gpt-4o, choices: [ { index: 0, message: { role: assistant, content: pong }, finish_reason: stop } ], usage: { prompt_tokens: 5, completion_tokens: 2, total_tokens: 7 } }看到choices数组里有内容就说明接口层通了。如果返回401是 Key 问题返回404是地址或模型 ID 问题返回model not found是模型 ID 拼写问题。第三层FastGPT 应用层。打开 FastGPT 的 Web 界面地址是http://你的宿主机IP:3000用 root 账号登录默认密码是 compose 里的DEFAULT_ROOT_PSW示例里是 1234。进「账号-模型提供商」看模型列表里有没有你config.json里配的模型。然后新建一个简单的对话应用选gpt-4o发一句「你好」看能不能正常返回。如果 Web 界面能返回但日志里报错那多半是流式输出或者 token 计算的问题不影响主流程。如果 Web 界面直接报「模型请求失败」去docker compose logs fastgpt看具体错误对照下一节的排障表。还有一个验证点容易被忽略向量模型。知识库能不能用取决于 embedding 接口通不通。你可以在 FastGPT 里新建一个知识库上传一个小的 txt 文件看能不能成功向量化。如果向量化失败日志里会有embeddings相关的报错回去检查config.json里vectorModels的requestUrl是不是写成了/v1/embeddings。三层都通过说明统一 Key 通道接入成功。这时候你可以把config.json和环境变量里的 Key 做一次一致性检查确保没有残留的旧 Key。我建议用grep扫一遍 compose 目录grep -rn sk- ./docker-compose.yml ./config.json看看输出的 Key 是不是都是同一个 TaoToken 的 Key有没有漏改的旧渠道 Key。5. 常见报错排查401、local proxy failed 与 reading choices这一节按真实报错来排每个报错给出原因和修法。这些错误我在内网部署里基本都踩过。报错一401 Unauthorized。日志里看到401或者invalid api key。原因通常是三个Key 填错、Key 前后有空格、config.json里的requestAuth和环境变量里的CHAT_API_KEY不一致。排查方法先用第 4 节的 curl 命令单独测 Key确认 Key 本身可用然后检查config.json里每个模型的requestAuth是不是都替换了最后注意 YAML 里CHAT_API_KEYsk-xxx不要加引号加了引号在某些解析器里会把引号当内容。报错二local proxy failed。这个报错一般出现在 FastGPT 走 AI Proxy 路径时日志里是local proxy failed或者aiproxy request failed。原因是AIPROXY_API_ENDPOINT配了但 AI Proxy 服务没起来或者AIPROXY_API_TOKEN和 AI Proxy 的ADMIN_KEY不一致。修法要么把AIPROXY_API_ENDPOINT和AIPROXY_API_TOKEN两行删掉强制走OPENAI_BASE_URL要么进aiproxy容器确认服务健康docker compose logs aiproxy看有没有启动报错。我建议统一通道场景直接删掉 AI Proxy 配置链路更短排查更简单。报错三reading choices 相关解析错误。日志里出现cannot read property choices of undefined或者reading choices。这个错误的本质是 FastGPT 拿到了一个不符合 OpenAI 格式的响应。常见原因requestUrl写成了/v1而不是/v1/chat/completions导致请求打到了错误端点返回的是 HTML 或者错误 JSON或者模型 ID 不存在接口返回了错误结构。修法检查config.json里requestUrl的完整路径用 curl 直接打这个 URL 看返回结构确认模型 ID 在 TaoToken 侧可用。报错四OAuth 或鉴权头格式错误。有些版本 FastGPT 在拼接鉴权头时如果requestAuth里已经带了Bearer前缀会拼成Bearer Bearer sk-xxx导致鉴权失败。修法requestAuth里只填sk-xxx不要带Bearer。这个坑比较隐蔽日志里可能只显示 401不会明确告诉你头拼错了。报错五容器启动后模型列表为空。Web 界面里看不到任何模型。原因是config.json挂载路径不对或者 JSON 格式错误导致 FastGPT 用了默认空配置。修法docker exec -it fastgpt cat /app/data/config.json看容器内实际读到的内容确认和你本地文件一致用python -m json.tool config.json校验 JSON 合法性。回滚步骤。改配置之前先把原来的docker-compose.yml和config.json备份cp docker-compose.yml docker-compose.yml.bak cp config.json config.json.bak如果改完发现不通且短时间排查不出来直接回滚cp docker-compose.yml.bak docker-compose.yml cp config.json.bak config.json docker compose down docker compose up -d回滚后确认原来的模型调用恢复正常再重新分析问题。内网环境排查时间宝贵先恢复可用比死磕更重要。排查时还有一个通用技巧把 FastGPT 的日志级别临时调到debugLOG_LEVELdebug重启后能看到完整的请求 URL、请求头Key 会被脱敏和响应体定位问题快很多。排查完记得调回info否则日志量很大。6. 统一通道后的模型验证与长期使用建议配置通了之后建议做一次完整的模型验证别只测一个对话模型就收工。FastGPT 的知识库链路涉及对话模型、向量模型如果你的应用用了重排或者图表还涉及重排模型和 gpt-vis。逐个验证一遍避免上线后才发现某个环节不通。对话模型验证在模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 手动发几条消息确认响应正常、流式输出正常。然后在 FastGPT 里建一个对话应用选同一个模型对比两边返回是否一致。如果 FastGPT 侧报错但模型对话侧正常问题一定在 FastGPT 的配置或网络不在模型通道。向量模型验证建一个知识库上传一个几百字的小文件看向量化是否成功。成功后问一个文件里明确有答案的问题看能不能检索到。这一步能同时验证 embedding 和检索链路。长期使用上有几个建议。第一Key 轮换要有预案。TaoToken 的 Key 如果泄露或者需要定期更换你只需要改config.json里的requestAuth和环境变量里的CHAT_API_KEY然后重启 FastGPT不用动底层模型服务。这就是统一通道的价值——变更点收敛到一处。第二如果你要做更复杂的编码或 Agent 场景可以了解下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它适合长期跑代码生成、多轮 Agent 调用的场景和 FastGPT 的知识库问答是互补的。第三接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有针对不同客户端的配置示例。如果你用的是 Claude Code 这类工具文档里有对应的接入说明地址是 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite 配置逻辑和 FastGPT 一样都是 Base URL 加 Key 加 Model ID 三件套。最后说一个实操细节FastGPT 的config.json修改后有些版本需要重启容器才生效有些版本支持热加载。保险起见改完一律docker compose restart fastgpt。重启后进 Web 界面确认模型列表刷新了再开始用。内网环境里把这份配置和回滚步骤写进你的运维文档下次换 Key 或者加模型照着改就行不用重新摸一遍链路。
1. FastGPT 离线部署后模型调用链路为什么总出问题FastGPT 全部离线部署这件事真正麻烦的地方从来不是把容器拉起来而是拉起来之后模型怎么调。FastGPT 本身是一个知识库问答编排平台它自己不产出模型能力所有对话、向量化、重排、图表生成都要通过 OpenAI 兼容接口去请求外部服务。离线环境里没有公网你就得在内网里自己搭一套模型网关把各家模型的地址和 Key 收敛到一个入口。我见过太多内网部署的现场是这样的FastGPT 的OPENAI_BASE_URL指向一台 OneAPIOneAPI 里又配了七八个渠道每个渠道一个 Key向量模型走 m3e 的 6008 端口重排走另一个服务图表渲染又走 gpt-vis-api 的 3100 端口。结果就是配置文件里散落着四五个不同的 endpointKey 更是东一个西一个。哪天某个 Key 过期了你得挨个容器进去翻环境变量排查半小时才发现是某个渠道的密钥失效。这篇要解决的就是这个链路问题。核心思路是在 FastGPT 和底层模型服务之间放一个统一的 Key 通道把 endpoint 和鉴权都收敛到一处。TaoToken 在这里扮演的就是这个统一入口的角色——它提供 OpenAI 兼容的/v1接口你只需要在 FastGPT 侧改一个OPENAI_BASE_URL和一个CHAT_API_KEY所有模型调用都从这一个口子出去。对于内网离线场景你可以在内网网关层做一次地址映射让 FastGPT 容器访问的是一个内网可达的地址实际请求再转发到统一通道。适合谁看已经用 docker compose 把 FastGPT 全家桶pg、mongo、redis、minio、sandbox、aiproxy跑起来但被多模型 Key 管理折磨的运维和开发以及准备做内网知识库、要求调用链路可审计、可回滚的团队。下面我会给出可直接复制的 compose 片段、config.json配置、连通性验证命令以及出问题时的回滚步骤。先说清楚一个前提FastGPT 的模型调用有两条路径。一条是老的OPENAI_BASE_URLCHAT_API_KEY直连另一条是走 AI Proxy通过AIPROXY_API_ENDPOINTAIPROXY_API_TOKEN。两条路径的优先级是 AI Proxy 更高只要配了AIPROXY_API_ENDPOINTFastGPT 就优先走它。所以你要统一 Key 通道得先确认自己走的是哪条别改了半天发现根本没生效。这个坑我后面在排障章节会详细讲。2. TaoToken 统一 Key 通道的前置准备与地址规划在动手改配置之前先把地址和凭证规划清楚否则后面改到一半发现端口冲突或者网络不通返工成本很高。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。注意 API 地址后面不加任何查询参数FastGPT 里填的OPENAI_BASE_URL要带上/v1也就是最终形态是https://taotoken.net/api/v1。这个/v1千万别漏漏了会直接返回 404FastGPT 日志里看到的是一堆reading choices相关的解析错误很容易误判成模型问题。凭证方面你需要先在控制台创建一个 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建出来的 Key 形如sk-开头的一串字符这个 Key 就是你要填进 FastGPT 的CHAT_API_KEY。模型 ID 这块要特别注意。FastGPT 在调用对话模型时会把你配置里的模型名原样传给接口。所以你在 TaoToken 侧能用哪些模型取决于你的账号权限和通道配置。常见的对话模型 ID 比如gpt-4o、claude-3-5-sonnet这类向量模型比如text-embedding-3-small。你可以在模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 先手动发一条消息确认模型 ID 拼写正确、通道可用再去改 FastGPT 配置。这一步能省掉大量「配置没错但就是不通」的排查时间。内网离线场景的地址规划核心是解决「FastGPT 容器能不能访问到 TaoToken」这个问题。如果你的部署环境完全无外网那 FastGPT 容器直连taotoken.net是不通的。这时候有两种做法第一种在内网网关比如一台能出网的跳板机或者反向代理上做转发把内网某个地址映射到 TaoToken 的 API。FastGPT 里填的是内网地址网关负责出网。这种做法的好处是 FastGPT 侧完全无感坏处是你得维护网关的高可用。第二种如果你的环境允许容器访问外网那直接在OPENAI_BASE_URL里填https://taotoken.net/api/v1即可最简单。下面我按第二种来写配置第一种只需要把地址换成你的内网映射地址其余完全一致。网络规划上还要注意一点FastGPT 的 compose 里定义了一个fastgpt网络所有服务都在这个网络里。如果你要加一个统一通道的代理容器记得把它也加入fastgpt网络这样 FastGPT 容器可以用服务名访问它而不是依赖宿主机 IP。用服务名比用 IP 稳IP 变了不用改配置。最后提醒一句CHAT_API_KEY这个环境变量在 FastGPT 里是明文写在 compose 文件里的。生产环境建议用 docker secret 或者外部环境变量文件别直接提交到代码仓库。下面示例里我会用占位符你替换成自己的真实 Key。3. 可复制的 FastGPT 与 TaoToken 接入配置片段这一节是全文的核心给出可以直接粘贴的配置。分三块FastGPT 的 compose 环境变量、config.json里的模型定义、以及可选的 AI Proxy 配置。先看 FastGPT 主服务的环境变量。找到你 compose 文件里fastgpt或fastgpt3服务下的environment段把OPENAI_BASE_URL和CHAT_API_KEY改成下面这样fastgpt: container_name: fastgpt image: registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt:v4.8.1 ports: - 3000:3000 networks: - fastgpt depends_on: - mongo - sandbox - pg restart: always environment: - FE_DOMAIN - DEFAULT_ROOT_PSW1234 # 统一 Key 通道TaoToken 的 OpenAI 兼容地址务必带 /v1 - OPENAI_BASE_URLhttps://taotoken.net/api/v1 # 统一鉴权 Key替换成你在控制台创建的真实 Key - CHAT_API_KEYsk-你的TaoToken密钥 - TOKEN_KEYany - ROOT_KEYroot_key - FILE_TOKEN_KEYfiletoken - AES256_SECRET_KEYfastgptkey - PLUGIN_BASE_URLhttp://fastgpt-plugin:3000 - PLUGIN_TOKENxxxxxx - SANDBOX_URLhttp://sandbox:3000 - DB_MAX_LINK30 - MONGODB_URImongodb://myusername:mypasswordmongo:27017/fastgpt?authSourceadmin - REDIS_URLredis://default:mypasswordredis:6379 - PG_URLpostgresql://username:passwordpg:5432/postgres - LOG_LEVELinfo - STORE_LOG_LEVELwarn - WORKFLOW_MAX_RUN_TIMES1000 - WORKFLOW_MAX_LOOP_TIMES100 - CHAT_FILE_EXPIRE_TIME7 volumes: - ./config.json:/app/data/config.json注意这里我把AIPROXY_API_ENDPOINT和AIPROXY_API_TOKEN两行去掉了。原因前面说过AI Proxy 优先级更高只要它存在FastGPT 就不走OPENAI_BASE_URL。你要用统一通道就得先把 AI Proxy 这条路断掉否则改了OPENAI_BASE_URL也不生效。如果你确实想保留 AI Proxy那就得在 AI Proxy 侧配置上游那是另一套改法本文按直连统一通道来写。接下来是config.json。FastGPT 的模型列表、向量模型、重排模型都在这个文件里定义。它挂载在/app/data/config.json你本地 compose 目录下应该有一个同名文件。关键字段是llmModels、vectorModels、reRankModels里的requestUrl和requestAuth。改成统一通道后所有模型的requestUrl都指向同一个地址{ feConfigs: { lafEnv: https://laf.dev }, systemEnv: { vectorMaxProcess: 15, qaMaxProcess: 15, vlmMaxProcess: 15, tokenWorkers: 30, pgHNSWEfSearch: 100 }, llmModels: [ { model: gpt-4o, name: gpt-4o, maxContext: 128000, maxResponse: 16000, quoteMaxToken: 120000, maxTemperature: 1.2, vision: true, toolChoice: true, functionCall: true, defaultSystemChatPrompt: , requestUrl: https://taotoken.net/api/v1/chat/completions, requestAuth: sk-你的TaoToken密钥 }, { model: claude-3-5-sonnet, name: claude-3-5-sonnet, maxContext: 200000, maxResponse: 8000, quoteMaxToken: 180000, maxTemperature: 1.0, vision: true, toolChoice: true, functionCall: true, requestUrl: https://taotoken.net/api/v1/chat/completions, requestAuth: sk-你的TaoToken密钥 } ], vectorModels: [ { model: text-embedding-3-small, name: text-embedding-3-small, defaultToken: 512, maxToken: 3000, weight: 100, requestUrl: https://taotoken.net/api/v1/embeddings, requestAuth: sk-你的TaoToken密钥 } ], reRankModels: [], audioSpeechModels: [], whisperModel: {} }这里有个细节requestUrl要写到具体的端点比如/v1/chat/completions和/v1/embeddings而不是只写到/v1。FastGPT 在部分版本里不会自动补全路径写错了会 404。requestAuth就是你的 Key注意它和环境变量里的CHAT_API_KEY是两套东西——config.json里的模型定义优先如果你在config.json里写了requestAuthFastGPT 就用这个环境变量里的CHAT_API_KEY反而可能被忽略。所以两处都要填成同一个 Key保持一致最省心。如果你走的是 AI Proxy 路径那配置在aiproxy服务里需要设置上游通道。但本文主线是直连统一通道AI Proxy 这块只提一句它的ADMIN_KEY和 FastGPT 里的AIPROXY_API_TOKEN要对应上游地址在 AI Proxy 的管理后台配置。改完记得重启aiproxy容器。配置改完执行重启docker compose down docker compose up -d docker compose logs -f fastgpt看日志里有没有Mongo connected、Redis connected、PG connected这类成功信息以及有没有模型加载相关的报错。如果config.json格式写错了FastGPT 启动时会直接报 JSON 解析失败日志里能看到具体行号。4. 连通性验证与成功结果确认配置改完不代表通了必须做连通性验证。分三层验证容器网络层、接口层、FastGPT 应用层。第一层容器网络层。先进 FastGPT 容器确认能不能解析并访问到 TaoToken 的地址docker exec -it fastgpt sh # 容器内执行 curl -I https://taotoken.net/api/v1/models如果返回HTTP/2 401或者HTTP/2 200说明网络是通的401 是因为没带 Key正常。如果卡住或者报Could not resolve host那就是容器出网有问题回到上一节检查网关或 DNS 配置。第二层接口层。在宿主机或者容器内用真实 Key 发一个最小请求确认鉴权和模型都可用curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -d { model: gpt-4o, messages: [{role: user, content: ping}], max_tokens: 10 }成功的返回长这样{ id: chatcmpl-xxxx, object: chat.completion, created: 1730000000, model: gpt-4o, choices: [ { index: 0, message: { role: assistant, content: pong }, finish_reason: stop } ], usage: { prompt_tokens: 5, completion_tokens: 2, total_tokens: 7 } }看到choices数组里有内容就说明接口层通了。如果返回401是 Key 问题返回404是地址或模型 ID 问题返回model not found是模型 ID 拼写问题。第三层FastGPT 应用层。打开 FastGPT 的 Web 界面地址是http://你的宿主机IP:3000用 root 账号登录默认密码是 compose 里的DEFAULT_ROOT_PSW示例里是 1234。进「账号-模型提供商」看模型列表里有没有你config.json里配的模型。然后新建一个简单的对话应用选gpt-4o发一句「你好」看能不能正常返回。如果 Web 界面能返回但日志里报错那多半是流式输出或者 token 计算的问题不影响主流程。如果 Web 界面直接报「模型请求失败」去docker compose logs fastgpt看具体错误对照下一节的排障表。还有一个验证点容易被忽略向量模型。知识库能不能用取决于 embedding 接口通不通。你可以在 FastGPT 里新建一个知识库上传一个小的 txt 文件看能不能成功向量化。如果向量化失败日志里会有embeddings相关的报错回去检查config.json里vectorModels的requestUrl是不是写成了/v1/embeddings。三层都通过说明统一 Key 通道接入成功。这时候你可以把config.json和环境变量里的 Key 做一次一致性检查确保没有残留的旧 Key。我建议用grep扫一遍 compose 目录grep -rn sk- ./docker-compose.yml ./config.json看看输出的 Key 是不是都是同一个 TaoToken 的 Key有没有漏改的旧渠道 Key。5. 常见报错排查401、local proxy failed 与 reading choices这一节按真实报错来排每个报错给出原因和修法。这些错误我在内网部署里基本都踩过。报错一401 Unauthorized。日志里看到401或者invalid api key。原因通常是三个Key 填错、Key 前后有空格、config.json里的requestAuth和环境变量里的CHAT_API_KEY不一致。排查方法先用第 4 节的 curl 命令单独测 Key确认 Key 本身可用然后检查config.json里每个模型的requestAuth是不是都替换了最后注意 YAML 里CHAT_API_KEYsk-xxx不要加引号加了引号在某些解析器里会把引号当内容。报错二local proxy failed。这个报错一般出现在 FastGPT 走 AI Proxy 路径时日志里是local proxy failed或者aiproxy request failed。原因是AIPROXY_API_ENDPOINT配了但 AI Proxy 服务没起来或者AIPROXY_API_TOKEN和 AI Proxy 的ADMIN_KEY不一致。修法要么把AIPROXY_API_ENDPOINT和AIPROXY_API_TOKEN两行删掉强制走OPENAI_BASE_URL要么进aiproxy容器确认服务健康docker compose logs aiproxy看有没有启动报错。我建议统一通道场景直接删掉 AI Proxy 配置链路更短排查更简单。报错三reading choices 相关解析错误。日志里出现cannot read property choices of undefined或者reading choices。这个错误的本质是 FastGPT 拿到了一个不符合 OpenAI 格式的响应。常见原因requestUrl写成了/v1而不是/v1/chat/completions导致请求打到了错误端点返回的是 HTML 或者错误 JSON或者模型 ID 不存在接口返回了错误结构。修法检查config.json里requestUrl的完整路径用 curl 直接打这个 URL 看返回结构确认模型 ID 在 TaoToken 侧可用。报错四OAuth 或鉴权头格式错误。有些版本 FastGPT 在拼接鉴权头时如果requestAuth里已经带了Bearer前缀会拼成Bearer Bearer sk-xxx导致鉴权失败。修法requestAuth里只填sk-xxx不要带Bearer。这个坑比较隐蔽日志里可能只显示 401不会明确告诉你头拼错了。报错五容器启动后模型列表为空。Web 界面里看不到任何模型。原因是config.json挂载路径不对或者 JSON 格式错误导致 FastGPT 用了默认空配置。修法docker exec -it fastgpt cat /app/data/config.json看容器内实际读到的内容确认和你本地文件一致用python -m json.tool config.json校验 JSON 合法性。回滚步骤。改配置之前先把原来的docker-compose.yml和config.json备份cp docker-compose.yml docker-compose.yml.bak cp config.json config.json.bak如果改完发现不通且短时间排查不出来直接回滚cp docker-compose.yml.bak docker-compose.yml cp config.json.bak config.json docker compose down docker compose up -d回滚后确认原来的模型调用恢复正常再重新分析问题。内网环境排查时间宝贵先恢复可用比死磕更重要。排查时还有一个通用技巧把 FastGPT 的日志级别临时调到debugLOG_LEVELdebug重启后能看到完整的请求 URL、请求头Key 会被脱敏和响应体定位问题快很多。排查完记得调回info否则日志量很大。6. 统一通道后的模型验证与长期使用建议配置通了之后建议做一次完整的模型验证别只测一个对话模型就收工。FastGPT 的知识库链路涉及对话模型、向量模型如果你的应用用了重排或者图表还涉及重排模型和 gpt-vis。逐个验证一遍避免上线后才发现某个环节不通。对话模型验证在模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 手动发几条消息确认响应正常、流式输出正常。然后在 FastGPT 里建一个对话应用选同一个模型对比两边返回是否一致。如果 FastGPT 侧报错但模型对话侧正常问题一定在 FastGPT 的配置或网络不在模型通道。向量模型验证建一个知识库上传一个几百字的小文件看向量化是否成功。成功后问一个文件里明确有答案的问题看能不能检索到。这一步能同时验证 embedding 和检索链路。长期使用上有几个建议。第一Key 轮换要有预案。TaoToken 的 Key 如果泄露或者需要定期更换你只需要改config.json里的requestAuth和环境变量里的CHAT_API_KEY然后重启 FastGPT不用动底层模型服务。这就是统一通道的价值——变更点收敛到一处。第二如果你要做更复杂的编码或 Agent 场景可以了解下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它适合长期跑代码生成、多轮 Agent 调用的场景和 FastGPT 的知识库问答是互补的。第三接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有针对不同客户端的配置示例。如果你用的是 Claude Code 这类工具文档里有对应的接入说明地址是 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite 配置逻辑和 FastGPT 一样都是 Base URL 加 Key 加 Model ID 三件套。最后说一个实操细节FastGPT 的config.json修改后有些版本需要重启容器才生效有些版本支持热加载。保险起见改完一律docker compose restart fastgpt。重启后进 Web 界面确认模型列表刷新了再开始用。内网环境里把这份配置和回滚步骤写进你的运维文档下次换 Key 或者加模型照着改就行不用重新摸一遍链路。
与快照完整实战)
