在 Docker 里把 FastGPT 拉起来之后真正让人卡住的往往不是容器而是 one-api 里的自定义渠道BaseURL 写 http 还是 https、末尾要不要 /v1、密钥对应哪个上游、模型名和 FastGPT config.json 是否一致。尤其是同时接入本地千问和 m3e 时对话模型、向量模型各建一个渠道改一处漏一处测试就给你连接失败或 404。现在可以把这些自定义渠道统一指向 TaoToken先去 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentfastgpt_intro 创建 Key再把 one-api 的 BaseUrl 填成 https://taotoken.net/apiFastGPT 的对话和知识库切片请求都交给 one-api 转发。这样你不需要逐个维护上游地址只维护一套 Key 和模型名模型调用就更容易走通。1. FastGPT 的 one-api 渠道里BaseURL 为什么一写错就连接失败1.1 本地千问和 m3e 分开建渠道配置面一多就漏FastGPT 的模型接入并不直接写在大模型配置里而是先让 one-api 管模型再由 FastGPT 去 one-api 拿模型列表。这个设计在单模型时很轻但一旦同时接入本地千问、m3e、重排模型渠道数就会上来对话模型一个渠道向量模型一个渠道可能还有个 rerank 渠道。每个渠道都要填 BaseUrl、密钥、模型名任何一个字段跟另一个渠道不一致FastGPT 就会出现“模型列表能看到但调用报错”的情况。更麻烦的是本地模型地址通常跟部署方式绑在一起。one-api 跑在容器里BaseUrl 写 127.0.0.1 会指向容器自己写宿主机 IP可能因为 Docker 网络模式不同而不通写 http上游却要求 https写 https证书又可能让容器校验失败。你并不是不会配而是渠道太多每次加模型都要重新判断一遍网络拓扑。把 BaseUrl 统一成 TaoToken 的兼容通道后one-api 只认一个上游地址FastGPT 也只需要在 config.json 里加模型名配置面立刻收窄。1.2 http、https、/v1 三个细节One API 测试按钮会直接告诉你one-api 的自定义渠道里BaseUrl 不是随便填一个域名就完事。它会把渠道里的模型名和 BaseUrl 组合成实际请求地址。不同上游对路径要求不一样有的希望 BaseUrl 以 /v1 结尾有的希望不写 /v1由 one-api 自己补。你如果按习惯在 BaseUrl 后面加了 /v1而实际接口又不接受重复路径测试按钮就会给你 404 或者提示找不到模型。本篇要填的接口 Base URL 是https://taotoken.net/api末尾不带/v1。注意这里说的是填进 one-api 的地址不是浏览器里打开的官网页面。官网页面是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentfastgpt_oneapi 用来注册、创建 Key、看模型广场和看用量填进工具的 BaseUrl 一律是https://taotoken.net/api不要再拼/v1也不要把官网链接后面的查询参数带进去。1.3 把 BaseURL 指向 TaoToken 后的统一链路改完后的链路可以理解成三层FastGPT 负责对话界面和知识库流程one-api 负责把模型名映射到上游TaoToken 负责提供统一的 API 通道。FastGPT 不需要知道上游模型到底在哪个机房里它只看到 one-api 暴露出来的模型名one-api 也不需要为每个本地模型单独维护一个地址它只需要把自定义渠道的 BaseUrl 指向 TaoToken再用一把 Key 去请求。这样做的直接好处是对话模型和向量模型可以在同一个渠道里配置也可以分成“对话渠道”和“向量渠道”两个自定义渠道但 BaseUrl 都一样。你不用再为千问写一个 http 地址为 m3e 写一个 https 地址为另一个模型写宿主机 IP。只要 one-api 渠道测试能通过FastGPT 的 config.json 里把对应模型 ID 加上重启 fastgpt 容器后模型列表就能读到可用模型。2. 在 TaoToken 控制台创建 Key并确认模型广场里的模型 ID2.1 打开控制台创建 YOUR_API_KEY先处理密钥。打开 TaoToken 控制台 注册并登录进控制台里的 API Keys 页面新建一个 Key。复制出来的字符串不要直接写进公开的 docker-compose.yml也不要在聊天记录里明文保存本文统一用YOUR_API_KEY占位。等会儿在 one-api 添加自定义渠道时密钥一栏就填这个占位符对应的真实 Key。这里跟原文里“申请或复制 API Key”是同一个动作只是申请入口换到 TaoToken。Key 创建后最好分环境命名比如fastgpt-oneapi-test、fastgpt-prod后面回控制台看用量时能一眼分清是哪个 FastGPT 环境打过来的请求。不要用同一个 Key 同时跑测试、生产、临时脚本否则 401 排查时很难判断是 Key 被删了还是复制少了字符。2.2 模型名不要凭记忆写以模型广场当时列表为准模型名是这类接入里最容易出错的地方。很多人记住一个名字就填进 one-api或者从旧文章里复制一个带日期后缀的模型 ID结果测试按钮报“模型不存在”。本篇不编造固定模型 ID所有模型名都以 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 里的模型广场当时列表为准。你在模型广场里复制对话模型 ID填到 one-api 自定义渠道的“模型”一栏如果 FastGPT 知识库也要做切片再去模型广场确认向量模型或 embedding 模型的可用情况。one-api 渠道里的模型名和 FastGPT config.json 里的model字段必须对得上。比如 one-api 渠道里填了YOUR_CHAT_MODEL_IDFastGPT 的llmModels里也要写同一个YOUR_CHAT_MODEL_ID如果你在 one-api 里写的是别名而 FastGPT 里写的是另一个名字FastGPT 模型列表可能显示出来但一发消息就会 404。最稳的做法是从模型广场复制原始模型 IDone-api 和 FastGPT 两边都粘贴同一个字符串。2.3 分清官网落地页和接口 Base URL这两个地址很容易混官网落地页是给人看的带utm_source和utm_content用于注册、创建 Key、看模型广场、看用量接口 Base URL 是给工具填的固定为https://taotoken.net/api末尾不带/v1也不带任何查询参数。你可以在浏览器里打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentfastgpt_docs 看模型广场和文档入口但 one-api 的 BaseUrl 字段里只能填https://taotoken.net/api。如果把官网链接整段复制进 one-api 的 BaseUrl就会出现路径拼接错误如果在https://taotoken.net/api后面加了/v1也可能让实际请求路径多一层。记住一句看页面用带 UTM 的官网链接填工具用不带 UTM 的https://taotoken.net/api。接下来进入 one-api 渠道页时所有配置都围绕这个 Base URL 展开。3. one-api 添加自定义渠道BaseUrl 填 https://taotoken.net/api3.1 渠道类型仍然选自定义渠道登录 one-api 控制台按原文路径走one-api 界面 → 渠道 → 添加新的渠道。类型不要改成别的仍然选“自定义渠道”。名称可以按用途写例如TaoToken-Chat、TaoToken-Embedding这样后面在 FastGPT 里看模型来源时更清楚。分组按你 FastGPT 实际使用的分组来选如果只是本地部署测试默认分组通常就够。自定义渠道的意义在于one-api 不假设上游一定是 OpenAI、Azure 或某一家固定厂商而是让你自己填 BaseUrl、Key 和模型名。FastGPT 原本用这种方式接本地千问和 m3e现在只是把 BaseUrl 从本地模型服务地址换成 TaoToken 的 API 地址密钥换成刚创建的 Key模型名换成模型广场里的可用 ID。渠道类型不变FastGPT 那边也不需要改调用逻辑。3.2 密钥、BaseUrl、模型名的填写顺序建议按“先 BaseUrl、再密钥、再模型”的顺序填因为测试按钮主要检查这三项。字段可以参考下面这张表字段填法类型自定义渠道名称TaoToken-Chat或TaoToken-EmbeddingBaseUrlhttps://taotoken.net/api密钥YOUR_API_KEY模型从模型广场复制的模型 ID多个用英文逗号分隔分组按 FastGPT 实际使用的分组选择密钥一栏填原始 Key 即可不要自己加Bearer前缀除非 one-api 当前版本的界面明确要求。BaseUrl 末尾不要加/v1也不要把官网链接后面的?utm_source...带进去。模型一栏如果同时放对话模型和向量模型记得用英文逗号分隔但更推荐拆成两个自定义渠道一个放对话模型一个放向量模型后面排查切片问题时会清晰很多。3.3 保存后先点测试不要急着动 FastGPT渠道保存后先点 one-api 的测试按钮选一个刚填进去的模型发测试请求。测试通过再动 FastGPT测试不通过先待在 one-api 渠道页排查不要同时改 config.json 和 docker-compose否则你分不清是渠道错还是 FastGPT 配置错。测试时重点看返回信息如果提示 401优先检查 Key 是否复制完整、是否从正确的控制台创建如果提示模型不存在回模型广场确认模型 ID如果提示路径错误检查 BaseUrl 是否被多加了/v1。测试通过的含义是one-api 已经能用这把 Key通过https://taotoken.net/api访问到模型。接下来 FastGPT 的 config.json 只是告诉 FastGPT 有哪些模型可以选真正的转发仍然由 one-api 完成。所以 one-api 测试失败时改 FastGPT 没有任何帮助one-api 测试通过后FastGPT 还看不到模型才轮到 config.json 和容器重启。4. FastGPT config.json 补模型名docker-compose 重启 fastgpt4.1 先确认 config.json 是不是挂载进容器FastGPT 的模型配置通常写在项目目录下的config.json再通过 docker-compose 挂载进 fastgpt 容器。你要改的是宿主机上的文件不是进容器里改。可以先看 docker-compose 里 fastgpt 服务的 volumes常见写法是volumes: - ./config.json:/app/data/config.json如果挂载路径不是这个以你当前 FastGPT 版本的 compose 文件为准。改之前先备份一份config.json避免 JSON 逗号或括号写错导致容器起不来。改完后不用进容器直接重启 fastgpt 服务即可如果你改的是容器内文件重启后很可能被宿主机文件覆盖白改。4.2 llmModels 和 vectorModels 分别补什么llmModels负责对话模型vectorModels负责知识库切片和向量检索。下面只列关键字段你需要把它合并到现有 config.json 的对应数组里不要整份覆盖。YOUR_CHAT_MODEL_ID和YOUR_EMBEDDING_MODEL_ID都换成模型广场里的实际模型 ID并且和 one-api 渠道里的模型名保持一致。{ llmModels: [ { model: YOUR_CHAT_MODEL_ID, name: Chat Model, maxContext: 16000, maxResponse: 4000, quoteMaxToken: 13000, maxTemperature: 1, charsPointsPrice: 0, censor: false, vision: false, datasetProcess: true, usedInClassify: true, usedInExtractFields: true, usedInToolCall: true, usedInQueryExtension: true, toolChoice: true, functionCall: false, defaultConfig: {} } ], vectorModels: [ { model: YOUR_EMBEDDING_MODEL_ID, name: Embedding Model, charsPointsPrice: 0, maxToken: 3000, weight: 100 } ] }name是 FastGPT 界面里显示的名字可以自定义model必须和 one-api 渠道里的模型 ID 一致。对话模型和向量模型最好分开渠道、分开验证因为它们的请求路径和失败表现不同。改完 JSON 后可以用本地编辑器检查语法或者用python -m json.tool config.json这类命令确认格式没错。4.3 docker-compose pull 与 up -d 的写法配置保存后在 FastGPT 的 docker-compose 目录执行docker-compose pull docker-compose up -d fastgpt如果你的环境用的是docker compose新语法也可以写成docker compose pull docker compose up -d fastgpt。服务名不一定是fastgpt可以先执行docker-compose config --services确认服务名后再替换。重启后看日志docker-compose logs -f fastgpt --tail100日志里如果出现模型配置解析失败、JSON 格式错误、找不到模型之类提示先回到 config.json 检查逗号和模型 ID。容器正常启动不代表模型一定加载成功这一步要顺手看一眼日志。4.4 模型列表出现不代表知识库切片也通了FastGPT 的模型列表能选到对话模型只能说明llmModels和 one-api 的对话渠道通了。知识库上传文件后能不能切片还取决于vectorModels和 one-api 的向量渠道。很多人看到对话能用就以为全好了结果知识库一上传就报错回头才发现只配了 chat 模型没配 embedding 模型。所以重启后至少做两次验证一次新建对话选模型发消息一次上传一个小文本文件走一遍知识库切片。对话失败查llmModels切片失败查vectorModels和 one-api 里对应的向量渠道。两边都查一遍比在 FastGPT 界面反复刷新更快定位。5. 回到 FastGPT 模型列表验证并排查 401/404/切片失败5.1 对话模型选模型发一条最简单的消息回到 FastGPT新建对话在模型下拉里找 config.json 里配的那个模型。能选中后发一条“你好”观察是否返回内容。如果返回正常再去 one-api 的日志页看有没有对应请求记录。返回内容但日志没有记录可能是 FastGPT 用了别的模型返回错误就去 one-api 渠道测试页复现。对话验证不要一上来就挂知识库、开工具调用、传长文档。先用最简单的纯对话跑通确认 FastGPT → one-api → TaoToken 这条链路是通的。链路通了再加知识库、再调参数排查范围会小很多。5.2 向量模型上传小文件看切片日志知识库验证用小文件几十 KB 的 txt 就够。上传后触发切片观察 FastGPT 日志和 one-api 日志。如果切片任务失败先看vectorModels里的模型 ID 是否写对再看 one-api 的向量渠道里有没有同一个模型最后看模型广场当时是否提供对应向量模型。向量模型和对话模型不是一回事不能拿对话模型去填vectorModels。如果 one-api 测试向量模型时报 404重点查 BaseUrl 和模型名。BaseUrl 必须是https://taotoken.net/api不能多/v1模型名必须是模型广场里的实际 ID。如果 one-api 测试通过但 FastGPT 切片失败重点查 config.json 是否挂载成功、fastgpt 是否真的重启、vectorModels是否写进了正确的数组。5.3 401 先查 Key404 先查 BaseUrl 和模型名401 一般和 Key 有关Key 是否从正确入口创建、是否复制完整、是否被删除、是否有多余空格。回 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentfastgpt_usage 的控制台看 Key 列表和调用记录比在 one-api 里反复重填更直接。404 一般和路径或模型名有关BaseUrl 是不是https://taotoken.net/api有没有误加/v1one-api 渠道里的模型名是不是和 FastGPT config.json 一致。连接失败则更偏向网络和地址格式one-api 容器能不能访问外网BaseUrl 有没有写成 http是否误填了官网落地页链接。官网落地页是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentfastgpt_troubleshoot给人看one-api 的 BaseUrl 是https://taotoken.net/api给工具用。这两个混用测试按钮会直接给你连接错误或路径错误。5.4 用量与调用记录回 TaoToken 控制台核对one-api 测试通过、FastGPT 对话也返回内容后回控制台看这次调用有没有记上。用量记录能帮你确认请求确实到了 TaoToken而不是被 one-api 缓存、命中别的渠道或者 FastGPT 实际调了其他模型。如果用量里没有记录但 FastGPT 有返回要检查 one-api 渠道分组和 FastGPT 模型名是否真的指向了新建的自定义渠道。核对用量还有一个好处你能看到对话模型和向量模型分别打了多少请求。知识库切片通常会在短时间内产生多次 embedding 请求如果用量里只有对话请求没有向量请求说明切片链路还没走通。这个判断比在 FastGPT 界面看“处理中”更可靠。6. 跑通后去控制台看这次 one-api 调用是否记上账6.1 用同一把 Key 在模型对话里发测试消息配置保存后先用同一把 Key 到 TaoToken 模型对话 发一条测试消息确认模型 ID 和 Base URL 没填错。这里能正常返回再去 one-api 和 FastGPT 里排查方向会清楚很多。模型对话页面相当于一个独立的验证入口不依赖 FastGPT 和 one-api能帮你快速判断 Key 和模型本身是否可用。6.2 长期使用看 Coding Plan 是否合适如果这套 FastGPT 只是内部试用按量调用通常够用如果知识库切片、日常问答、多轮对话都要长期跑可以打开 Coding Plan 看套餐是否比按量更合适。选之前先看自己过去几天的请求量尤其是向量模型切片频率再决定要不要换套餐。不要只看对话次数知识库导入阶段的 embedding 请求往往比聊天更密集。6.3 创建和管理 Key 的入口后续如果要把测试环境和生产环境分开去 控制台 API Keys 分别创建 Key再在 one-api 里建不同渠道或不同分组。测试 Key 可以随时禁用生产 Key 单独保留用量排查时不会混在一起。改完 Key 后记得回 one-api 更新对应渠道的密钥字段再点一次测试按钮。最后回 FastGPT 模型列表刷新一次确认对话模型能选、能返回内容知识库上传小文件能切片one-api 日志里能看到对应请求控制台用量里也能查到这次调用。到这一步FastGPT one-api TaoToken 的接入就不再依赖一堆本地上游地址自定义渠道的 http、https 和 /v1 问题也被收进一个 BaseUrl 里。