1. Ubuntu 单机部署 FastGPT 与 OneAPI 的真实痛点如果你在 Ubuntu 上折腾过 FastGPT 加 OneAPI 这套组合大概率遇到过这种场景FastGPT 要调模型OneAPI 要管渠道两边的 Key 和地址各写一份改一个模型就得来回翻配置文件。更麻烦的是一旦你想换一个统一的模型接入入口就得把 OneAPI 的渠道、FastGPT 的环境变量、config.local.json 里的模型定义全部对一遍漏一个就报 401 或者 reading choices 错误。这篇内容聚焦 Ubuntu 单机环境把 FastGPT 和 OneAPI 的联调部署讲清楚重点解决多模型 Key 分散、接口地址不统一的问题。我会给出 docker-compose 片段、OneAPI 渠道配置、FastGPT 环境变量样例并且演示把模型接入地址改到 TaoToken 之后用一条对话请求验证知识库问答链路是否打通。适合已经在 Ubuntu 上跑过 Docker、想自己搭一套知识库问答系统、又不想被多个模型 Key 搞晕的人。先说清楚这套架构的分工。FastGPT 负责知识库、向量检索、对话编排它本身不直接持有各家模型的 Key而是通过一个 OpenAI 兼容的接口去调模型。OneAPI 就是那个中间层它把不同厂商的模型统一成 OpenAI 格式对外暴露一个/v1地址和一个令牌。你只要在 OneAPI 里配好渠道FastGPT 里只填一个 Base URL 和一个 Key 就行。那为什么还要把接入地址改到 TaoToken因为 OneAPI 的渠道配置本身也需要一个上游地址和 Key。如果你手上有多个来源的模型每个都单独配渠道管理成本会上去。把上游统一指向 TaoToken 的 API 地址OneAPI 这边只维护一个渠道FastGPT 那边只认 OneAPI链路就变成 FastGPT → OneAPI → TaoToken → 模型。这样换模型、加模型都只动一处。我试过在 Ubuntu 20.04 上从零走一遍下面按步骤来。先确认基础环境Docker 和 Docker Compose 装好docker --version能输出即可。如果你打算用源码方式跑 OneAPI还需要 Node 18 和 Go 1.21但用 Docker 会省掉很多编译的坑。FastGPT 官方也提供了 docker-compose单机部署推荐直接用容器数据库用 MongoDB 加 PostgreSQL带 pgvector。先建目录把编排文件放进去mkdir -p ~/fastgpt-oneapi cd ~/fastgpt-oneapi然后写docker-compose.yml。这里我把 OneAPI、FastGPT、MongoDB、PostgreSQL 放在同一个网络里FastGPT 通过服务名访问 OneAPI避免写死 IP。片段如下version: 3.8 services: mongo: image: mongo:6.0.12 restart: always ports: - 27017:27017 environment: - MONGO_INITDB_ROOT_USERNAMEroot - MONGO_INITDB_ROOT_PASSWORDfastgpt123 volumes: - ./mongo_data:/data/db pg: image: pgvector/pgvector:pg16 restart: always ports: - 5432:5432 environment: - POSTGRES_USERfastgpt - POSTGRES_PASSWORDfastgpt123 - POSTGRES_DBfastgpt volumes: - ./pg_data:/var/lib/postgresql/data oneapi: image: justsong/one-api:latest restart: always ports: - 3001:3000 environment: - SQL_DSNroot:fastgpt123tcp(mongo:27017)/oneapi depends_on: - mongo fastgpt: image: ghcr.io/labring/fastgpt:latest restart: always ports: - 3000:3000 environment: - MONGODB_URImongodb://root:fastgpt123mongo:27017/fastgpt?authSourceadmin - PG_URLpostgresql://fastgpt:fastgpt123pg:5432/fastgpt - OPENAI_BASE_URLhttp://oneapi:3000/v1 - CHAT_API_KEYsk-你的OneAPI令牌 depends_on: - mongo - pg - oneapi注意 OneAPI 容器内部端口是 3000映射到宿主机 3001所以 FastGPT 里写http://oneapi:3000/v1走的是容器网络。如果你把 OneAPI 单独跑在宿主机上那就写宿主机的 IP 加端口。启动之前先把 pgvector 扩展建好PostgreSQL 容器起来后执行docker exec -it fastgpt-oneapi-pg-1 psql -U fastgpt -d fastgpt -c CREATE EXTENSION IF NOT EXISTS vector;容器名可能因目录名不同而变化用docker ps确认一下。扩展建好FastGPT 的向量检索才能工作。2. TaoToken 前置准备拿到统一接入的 Base URL 和 Key在把 OneAPI 的渠道指向 TaoToken 之前你需要先准备好两样东西一个 OpenAI 兼容的 Base URL和一个可用的 API Key。TaoToken 的 API 地址是https://taotoken.net/api这个地址就是你要填到 OneAPI 渠道里的上游地址。注意它和官网https://taotoken.net不是一回事渠道里填的是带/api的那个。Key 的获取在控制台里完成。登录之后进 API Keys 页面新建一个令牌复制出来。这个 Key 就是 OneAPI 渠道里的「密钥」。如果你还没注册可以先从官网入口进去注册流程不复杂这里不展开。为什么要在 OneAPI 里配 TaoToken 而不是直接在 FastGPT 里填因为 OneAPI 的价值在于统一管理和格式转换。FastGPT 只认 OpenAI 格式而 TaoToken 提供的也是 OpenAI 兼容接口两者本来就能直连。但如果你后面要加别的模型来源或者要做用量统计、令牌分发OneAPI 这层就派上用场了。把 TaoToken 作为 OneAPI 的上游渠道等于把统一入口再收敛一层。具体操作浏览器打开http://你的服务器IP:3001用默认账号root密码123456登录第一件事是改密码。然后进「渠道」页面点「添加渠道」。类型选 OpenAI名称随便写比如taotokenBase URL 填https://taotoken.net/api密钥填你刚才复制的 Key。模型列表里把你需要的模型名填进去比如gpt-3.5-turbo、gpt-4o-mini、text-embedding-ada-002这些。填完保存渠道状态应该是绿色启用。这里有个细节OneAPI 的渠道 Base URL 填https://taotoken.net/api之后它请求时会自动拼/v1/chat/completions所以最终打到的是https://taotoken.net/api/v1/chat/completions。如果你填成https://taotoken.net/api/v1就会变成/v1/v1/...直接 404。这个坑我踩过渠道测试报错先检查这里。渠道配好之后去「令牌」页面新建一个令牌这个令牌是给 FastGPT 用的。复制出来填到 FastGPT 的CHAT_API_KEY里。注意区分OneAPI 渠道里的密钥是 TaoToken 的 KeyFastGPT 环境变量里的 Key 是 OneAPI 自己生成的令牌两者不是同一个。如果你用的是 Claude Code 或者想在编码场景里直接调TaoToken 也有对应的 coding-plan 入口不过这篇聚焦 FastGPT 知识库链路编码场景另说。模型对话的调试入口在https://taotoken.net/model-chat可以用来单独验证 Key 是否可用但正式链路还是走 OneAPI。3. 可复制配置OneAPI 渠道与 FastGPT 环境变量样例这一节把配置写全你直接抄改就行。先看 OneAPI 渠道的等价配置。如果你不想在网页上点OneAPI 也支持通过管理 API 创建渠道但网页操作更直观。渠道的关键字段是 Base URL 和模型列表对应关系如下字段填写值说明类型OpenAI兼容 OpenAI 格式名称taotoken自定义便于识别Base URLhttps://taotoken.net/api不带 /v1密钥你的 TaoToken Key控制台生成模型gpt-3.5-turbo,text-embedding-ada-002 等按需填然后是 FastGPT 的环境变量。FastGPT 的配置分两部分.env.local管数据库和基础地址config.local.json管模型定义。如果你用 Docker环境变量直接写在 compose 里如果用源码跑就改projects/app/.env.local。.env.local里跟模型接入相关的就两行OPENAI_BASE_URLhttp://oneapi:3000/v1 CHAT_API_KEYsk-你的OneAPI令牌注意OPENAI_BASE_URL结尾要带/v1因为 FastGPT 内部会拼/chat/completions。如果你 OneAPI 跑在宿主机而不是同一网络就换成http://宿主机IP:3001/v1。config.local.json里定义模型。这个文件决定 FastGPT 界面上能选哪些模型。一个精简版样例如下{ ChatModels: [ { model: gpt-3.5-turbo, name: GPT35, maxContext: 16000, maxResponse: 4000, price: 0 } ], QAModels: [ { model: gpt-3.5-turbo, name: GPT35-QA, maxContext: 16000, maxResponse: 4000, price: 0 } ], VectorModels: [ { model: text-embedding-ada-002, name: Embedding-2, price: 0.2, defaultToken: 700, maxToken: 3000 } ], ReRankModels: [], AudioSpeechModels: [], WhisperModel: {} }这里model字段必须和 OneAPI 渠道里填的模型名完全一致否则 FastGPT 请求过去 OneAPI 找不到对应渠道会返回模型不存在。VectorModels是知识库向量化用的必须配不然上传文档建索引会失败。如果你用源码方式跑 FastGPT复制配置文件的命令是cd projects/app cp .env.template .env.local cp data/config.json data/config.local.json然后编辑这两个文件。改完重启 FastGPT 服务。Docker 方式就docker compose restart fastgpt。还有一点OneAPI 的SQL_DSN如果指向 MySQL格式是用户名:密码tcp(地址:3306)/oneapi。上面 compose 里我图省事用了 mongo但 OneAPI 官方更推荐 MySQL。如果你用 MySQL把SQL_DSN换成root:密码tcp(mysql:3306)/oneapi并加一个 mysql 服务。这个不影响模型接入链路按你现有数据库选就行。4. 验证请求一条对话打通知识库问答链路配置改完别急着建知识库先用一条最简单的对话请求确认 FastGPT → OneAPI → TaoToken 这条链路是通的。打开 FastGPT 界面进「对话」页面新建一个对话模型选你 config 里配的GPT35发一句「你好回复一个字」。如果返回正常说明基础对话链路通了。如果报错看 FastGPT 容器日志docker logs -f fastgpt-oneapi-fastgpt-1常见的是 401说明CHAT_API_KEY和 OneAPI 令牌对不上或者 OneAPI 渠道里的 TaoToken Key 失效。也可能是OPENAI_BASE_URL写错比如漏了/v1或者端口不对。基础对话通了之后再验证知识库链路。知识库链路比普通对话多两步文档向量化和检索增强。先在 FastGPT 里新建知识库上传一个小的 txt 或 pdf等它处理完。处理过程中会调VectorModels里的 embedding 模型这一步走的是 OneAPI → TaoToken 的 embedding 接口。如果 embedding 模型没配或者模型名不对这里会卡住或者报错。文档处理完新建一个应用关联这个知识库然后在应用里提问一个文档里才有的内容。比如你上传的是产品手册就问手册里的某个参数。如果回答里带出了文档内容说明检索和生成都通了。也可以用 curl 直接打 OneAPI 的接口绕过 FastGPT 先确认 OneAPI 到 TaoToken 这段没问题curl http://localhost:3001/v1/chat/completions \ -H Authorization: Bearer sk-你的OneAPI令牌 \ -H Content-Type: application/json \ -d { model: gpt-3.5-turbo, messages: [{role: user, content: 回复ok}] }返回里有choices字段且内容正常就说明 OneAPI 渠道配置没问题。这一步能快速定位问题出在 FastGPT 还是 OneAPI。如果这个 curl 通了但 FastGPT 不通问题就在 FastGPT 的环境变量或 config 文件如果这个 curl 就不通问题在 OneAPI 渠道或 TaoToken Key。实测下来最容易出问题的是模型名大小写和空格。OneAPI 渠道里填gpt-3.5-turboconfig 里也必须是gpt-3.5-turbo不能写成GPT-3.5-Turbo。另一个是 embedding 模型很多人只配了 chat 模型忘了配 vector 模型结果对话能用但知识库建不了。5. 本篇常见错排查401、local proxy failed、reading choices部署过程中报错集中在几个地方逐个说。401 错误。FastGPT 日志里出现401 Unauthorized先分清楚是哪一段的 401。如果是 FastGPT 调 OneAPI 报 401检查CHAT_API_KEY是不是 OneAPI 生成的令牌以及令牌有没有过期或被禁用。如果是 OneAPI 调 TaoToken 报 401去 OneAPI 渠道页面点「测试」看返回信息。渠道测试 401 通常是 TaoToken Key 复制错了或者 Key 前面多了空格。重新复制一次注意别带上换行。local proxy failed。这个报错一般出现在 OneAPI 渠道测试时提示连接失败。原因通常是 Base URL 写错或者网络不通。确认 Base URL 是https://taotoken.net/api不是https://taotoken.net也不是带/v1的。然后在服务器上直接 curl 一下curl -I https://taotoken.net/api能返回 HTTP 状态码说明网络可达。如果服务器 DNS 有问题检查/etc/resolv.conf。另外 OneAPI 容器如果没配网络可能出不去确认容器能访问外网。reading choices 报错。FastGPT 日志里出现Cannot read properties of undefined (reading choices)意思是它期望返回里有choices字段但没拿到。这通常是 OneAPI 返回了错误信息而不是正常响应。去 OneAPI 的「日志」页面看这次请求的实际返回多半是模型名不匹配或者渠道被禁用。也可能是 TaoToken 那边返回了限流或余额不足的提示OneAPI 原样透传了。检查渠道状态和账户余额。OAuth 相关报错。如果你在 FastGPT 里配了第三方登录可能遇到 OAuth 回调失败。这跟模型接入无关检查回调地址和 client secret。如果只是本地测试可以先关掉 OAuth用账号密码登录。向量检索报错。上传文档后建索引失败日志里出现 pgvector 相关错误检查 PostgreSQL 的 vector 扩展有没有建。执行\dx看扩展列表里有没有 vector。没有就手动建一次。另外PG_URL里的用户名密码要和 PostgreSQL 容器的一致。模型列表为空。FastGPT 界面里选不到模型说明config.local.json没生效。检查文件路径对不对Docker 方式要确认这个文件挂载进了容器。源码方式确认改的是projects/app/data/config.local.json。改完必须重启服务。排查顺序建议从下往上先 curl OneAPI再 curl FastGPT 的接口最后看界面。这样能快速定位是哪一层的问题。6. 把接入地址收敛到一处之后整套跑通之后你会发现模型接入这件事变得很轻。FastGPT 那边永远只认 OneAPI 的地址和令牌OneAPI 那边只维护一个指向 TaoToken 的渠道。以后要换模型改 OneAPI 渠道里的模型列表和 FastGPT 的 config 文件两处对齐就行不用再去翻各个厂商的 Key。如果你后面要在编码场景里用同一套 KeyTaoToken 的 coding-plan 可以直接接 Claude Code 这类工具Base URL 和 Key 复用同一套。API Keys 管理在控制台接入文档在文档页遇到配置问题先看文档里的示例。知识库问答这条链路验证通过之后剩下的就是往知识库里灌文档、调提示词那部分跟模型接入无关了。最后留一个实用习惯每次改完配置先用那条 curl 命令打一次 OneAPI确认上游通再去界面上点。这样能把问题范围缩小到一半。