FastGPT 配置小鱼API：docker 部署与模型接入

用 docker 部署 FastGPT

FastGPT 的自托管是用上游仓库自带的 compose 文件加一个 config.json 拉起来的，三条命令进目录、两条命令启动。部署完之后，接模型这一步在网页界面里做：

mkdir fastgpt && cd fastgpt
curl -O https://raw.githubusercontent.com/labring/FastGPT/main/projects/app/data/config.json
curl -O https://raw.githubusercontent.com/labring/FastGPT/main/deploy/docker/docker-compose.yml
docker compose up -d          # 首次会拉取 mongo、pg、fastgpt 等镜像
docker compose ps             # 全部 Up 后访问

浏览器打开 http://你的服务器IP:3000，默认管理员账户是 root，初始密码 1234，登录后立刻改掉。

目录结构与端口

容器	默认端口	作用
fastgpt	3000	主程序与控制台
aiproxy / oneapi	3001	模型渠道转发（不同版本命名不同）
mongo	27017	业务数据
pg（含向量扩展）	5432	知识库向量数据
sandbox	内部	代码节点和插件运行沙箱

pg 这个容器是带向量扩展的定制镜像，不要换成普通 postgres 镜像，换掉之后知识库建不起来，报的是 extension vector does not exist 之类的错误。

docker-compose 关键项

不建议直接改下载下来的 compose 文件，另写一个覆盖文件更稳，将来升级不会冲突：

# 与 docker-compose.yml 同目录，文件名 docker-compose.override.yaml
services:
  fastgpt:
    ports:
      - "3010:3000"            # 外网端口换掉，避免与其他服务冲突
    restart: always
    environment:
      - DEFAULT_ROOT_PSW=换成你自己的强密码
      - FILE_TOKEN_KEY=换成一串随机字符
  pg:
    restart: always
    volumes:
      - ./pg/data:/var/lib/postgresql/data
  mongo:
    restart: always
    volumes:
      - ./mongo/data:/data/db

FILE_TOKEN_KEY 是文件下载链接的签名密钥，用默认值等于告诉别人怎么拼你的文件地址。DEFAULT_ROOT_PSW 只在数据库首次初始化时生效，容器已经跑起来过的，改这个变量不会改掉已有密码，要在界面上改。

config.json 要不要改

老版本把模型清单写在这个文件里，改完要重启容器；新版本把模型配置挪到了数据库，直接在网页上配，config.json 里只留界面相关的开关。判断方法很简单：登录后左侧菜单里能看到「模型提供商」就是新版，看不到就去翻 config.json。老版本里模型是这样写的：

{
  "llmModels": [
    {
      "model": "deepseek-v3.2-thinking",
      "name": "DeepSeek 中文主力",
      "maxContext": 65536,
      "maxResponse": 8192,
      "quoteMaxToken": 60000,
      "charsPointsPrice": 0,
      "vision": false,
      "toolChoice": true,
      "functionCall": true,
      "defaultSystemChatPrompt": ""
    }
  ]
}

model 字段的值必须和后台模型列表完全一致，多一个空格都会导致调用时报模型不存在。functionCall 决定这个模型能不能在工作流里调工具，做流程编排的模型要把它打开。

首次登录

密码改完之后先别急着建应用，先去模型提供商页面把渠道配好。没有可用模型的 FastGPT 建出来的应用是跑不动的，选了模型也会报错。

界面配置：添加 OpenAI 兼容渠道

进模型提供商页面

左侧菜单底部「账户」→「模型提供商」，页面会列出所有已配置的渠道。刚装好时这里是空的，点右上角「新增渠道」。

添加自定义渠道

渠道类型选「OpenAI 兼容接口」或者「自定义请求地址」这一类。FastGPT 对不同供应商做了预设模板，小鱼API 走的是标准 OpenAI 协议，选兼容接口即可，不用逐个填请求路径。

字段逐个填

字段	填什么	备注
渠道名称	小鱼API	自己看得懂就行
接口地址	`https://xyuapi.top/v1`	结尾 `/v1` 必须带
密钥	后台生成的令牌	首尾不能有空格
模型名	`claude-sonnet-4-5-thinking`	与列表逐字一致
模型类型	对话 / 向量 / 重排	分开添加，不要混填
最大上下文	65536	按模型实际支持填
最大回复长度	8192	影响长文输出
支持工具调用	需要就开	工作流用工具时必须开
支持视觉	看图才开	开了但模型不支持会报错

多个模型就在同一个渠道下继续「添加模型」，接口地址和密钥填一次就行，不用每个模型重复建渠道。

添加向量模型与重排模型

知识库必须配向量模型，否则文档上传后索引不了。向量模型同样走兼容接口，模型类型选「向量」，模型名要用后台列表里实际提供的向量化型号，名字不对会报模型不存在。重排模型可选，配上之后搜索结果排序更准，代价是每次检索多一次调用。

测试渠道并建分组

每个模型后面有一个测试按钮，点一下能返回内容就说明通。测完记得在「模型分组」里建一个分组把模型放进去，没进分组的模型在建应用时选不到，这个设计是为了区分不同项目的可用模型，个人自用建一个分组就够。

建应用：从对话到工作流

对话应用起步

「工作台」→「新建应用」→ 选「简易对话」或「对话引导」。进去在右上角选模型，下拉里的模型来自你刚才配好并加入了分组的那些。系统提示词里写清楚角色和输出边界，尤其是涉及价格、时效这类信息时，明确要求它只依据知识库作答。

工作流编排

「工作流」类型的应用由节点拼成。常见的结构是：开始节点收用户输入 → 知识库搜索节点召回资料 → AI 对话节点带着资料生成答案 → 指定回复节点输出。每个节点的输出都要在节点面板里命名，下游才能用 {{节点名.输出字段}} 引用。

发布与对外接口

点右上角发布之后，在「发布渠道」里可以拿到一个 API 密钥和调用地址。FastGPT 的对外接口自带流式返回，前端对接时直接按服务端推送处理即可，注意在反向代理上关掉响应缓冲，否则打字机效果会被攒成一整段。

知识库与检索调优

建库与上传文档

「知识库」→「新建」→ 选向量模型 → 上传文件 → 开始训练。训练过程就是在跑向量化，文档多的时候这一步慢是正常的，页面会有进度。中途关掉浏览器不影响后台任务。

分段与索引设置

设置项	建议值	说明
分段长度	500 到 800 字	太长检索不准，太短语义不完整
分段重叠	50 到 100 字	防止句子被硬切断
索引方式	高质量	检索更准，训练更慢
自动补充问题	按需开	提升召回，但会额外消耗调用次数
文本预处理	开启	清掉多余换行和页眉页脚

「自动补充问题」和「自动补充索引」这两项会调用模型生成内容，文档量大时能把成本推上去一截。先不打开跑一轮试效果，不够准再逐项开。

搜索测试怎么调

知识库里有个搜索测试入口，输入真实用户会问的问题，看召回结果准不准。这一步比盯着参数调有用得多：召回不准，再好的提示词也救不回来。相似度阈值先给 0.3 左右，召回条数 4 到 6 条，边测边调。

常见问题排查

现象	原因	处理
容器反复重启	`.env` 或密钥字段填错，或端口被占	看 `docker compose logs fastgpt` 末尾报错
登录后模型选不到	模型没进分组，或渠道测试没通过	建分组并把模型加进去
401 认证失败	令牌带空格，或密钥填错渠道	重新复制令牌，注意首尾空白
404 模型不存在	模型名与列表不一致	逐字核对模型名
知识库训练失败	向量模型没配或名字不对	单独测试向量模型连通性
回答是编的	提示词没约束、召回为空	加「只依据资料回答」，检查召回

容器起不来

docker compose ps 里状态是 Restarting 或 Exited，直接看日志：

docker compose logs --tail=80 fastgpt
docker compose logs --tail=80 pg

十次里有八次是端口冲突或者数据卷权限问题，日志末尾会写清楚是 address already in use 还是 permission denied。

401 与 404 怎么区分

401 是认证问题，方向在令牌上；404 是模型问题，方向在模型名上。还有一种容易混的情况：渠道地址漏写了 /v1，请求打到根路径，返回的是 404 加一段 HTML，看起来像模型不存在，其实是地址不对。看到返回内容不是 JSON 时，先查地址。

知识库索引失败

索引失败基本是向量模型不可用。判断方法是去模型提供商页面单独测那个向量模型，通了再重新训练，不通就先修模型配置。已经上传的文档不用重传，改好模型后重新点训练即可。

升级与备份

升级步骤

cd fastgpt
docker compose down
# 重新下载最新的 docker-compose.yml 与 config.json，
# 保留你自己的 docker-compose.override.yaml
docker compose pull
docker compose up -d

跨大版本升级时数据库结构会变，升级日志里通常会提示先跑一次迁移，照提示执行。升级前务必先备份。

备份哪些卷

目录	内容	丢失后果
`./pg/data`	知识库向量、业务数据	数据全丢
`./mongo/data`	应用、对话记录、账户	应用要重建
`./config.json`	界面与模型相关配置	要重配一遍
`docker-compose.override.yaml`	端口与密码覆盖	要重配一遍

docker compose stop
tar czf fastgpt-backup-$(date +%Y%m%d).tar.gz pg mongo config.json docker-compose.override.yaml
docker compose start

先停容器再打包，运行中直接打包数据库目录，恢复出来的文件可能是不一致的。

成本怎么算

常用模型单价

模型名	单价	放在哪个环节
`gemini-2.5-pro`	0.031 元/次	查询改写、意图判断、轻量问答
`deepseek-v3.2-thinking`	0.049 元/次	主对话、中文内容生成
`claude-sonnet-4-5-thinking`	0.09 元/次	长文输出、多步工作流
`gpt-5.5`	0.2 元/次	高难推理环节

一次问答的实际花费

FastGPT 一次问答通常包含好几次模型调用：检索前的查询改写一次、生成答案一次，如果开了「自动补充问题」或者接入了重排模型，还要再加。按上面的单价算，一次普通问答大概在一毛钱上下，量大之后这个数字就是主要成本项。

压缩成本的方向有两个：减少链路里的模型节点数量，以及把低价值环节换成 gemini-2.5-pro。两个方向里，砍节点的效果更明显。

小结

FastGPT 的部署部分是三条命令加一份覆盖配置，接模型部分是一个界面表单。真正会让人卡住的是两类问题：模型没进分组导致选不到，以及渠道地址写错导致 404。前者在「模型分组」里加一下就解决，后者对照 https://xyuapi.top/v1 逐字改一遍即可。整套流程从零到能跑通一次带知识库的问答，熟悉之后大概二十分钟。