FastGPT 部署与知识库搭建实战：docker 起步、向量库选型、RAG 调参
适用人群
这份指南适合三类用户：准备用 FastGPT 搭企业知识库的开发者、已经装了 FastGPT 但 RAG 精度不满意的团队、在 FastGPT / Dify / Coze 之间做技术选型的架构师。
它不是抄命令行的操作手册，而是把"部署 → 建库 → 调参 → 上线"这条链路上真正会踩的坑写清楚，让你少走弯路。
前置条件
在开始之前，确认三件事：
- 一台 Linux 服务器（阿里云 / 腾讯云 / 自建都行），最低 2C4G + 20GB 硬盘。
- 已装 Docker 28+ 和 Docker Compose 2.20+。
- 至少一个可用的 LLM API Key（OpenAI 兼容即可，DeepSeek、豆包、Qwen、Kimi 都行）。
如果打算做企业级、日均 10 万次问答规模，起步就上 8C16G + 200GB SSD + Milvus 向量库，别用 pgvector。
部署（10 分钟）
标准命令：
git clone https://github.com/labring/FastGPT.git
cd FastGPT/deploy/docker/cn
wget https://doc.fastgpt.cn/deploy/config/config.json
docker-compose -f docker-compose.pg.yml up -d
启动后访问 http://<服务器IP>:3000，默认账号 root / 1234。登录后第一件事：改 root 密码 + 改 MinIO 默认密码。
如果服务器有其他服务占用 3000/9000/3005 端口，编辑 docker-compose.pg.yml 里对应服务的 ports:，把宿主机端口改成没冲突的。
向量库怎么选
这是最容易选错的地方。选错了后续要重新 embedding 整个知识库，成本很高。
| 索引量 | 推荐向量库 | 说明 |
|---|---|---|
| < 500 万 | pgvector | docker-compose.pg.yml，最简单 |
| 500 万–5000 万 | pgvector 或 Milvus | 看查询延迟需求 |
| > 5000 万 | Milvus | 亿级索引首选 |
| 企业国产化 | OceanBase / SeekDB | 有信创要求走这条 |
判断索引量：文档数 × 每份平均分块数（通常 20–100 段）。100 份 100 页文档 ≈ 100 × 200 = 2 万段，pgvector 完全够。1 万份 100 页 ≈ 200 万段，仍在 pgvector 范围内。5 万份以上再考虑 Milvus。
配模型
进入后台 → 账号 → 模型提供商，必须同时配置两类模型：
- 对话模型 LLM：DeepSeek-V3 / GPT-5 / Claude Sonnet 4 / 豆包-Pro / Kimi K2 都行
- 嵌入模型 Embedding：
bge-large-zh-v1.5（中文首选）、text-embedding-3-large（OpenAI 兼容）
常见坑：只配对话模型没配嵌入模型，知识库上传后无法索引。请务必两类都配。
如果预算敏感，推荐组合：DeepSeek-V3（对话）+ bge-large-zh（嵌入 + 本地），token 便宜、中文强。
建第一个知识库
进入 知识库 → 新建 → 输入名称、简介、选择嵌入模型。
上传文档：拖入 PDF / Word / Markdown / TXT。上传后 FastGPT 会做：
- 文本提取（PDF 会走 pdfjs / minerU）
- 切片（默认按段落 + 长度）
- 向量化（调 embedding 模型）
- 入库（PG/Milvus）
关键参数：
| 参数 | 默认 | 说明 |
|---|---|---|
| chunk_size | 512 | 每块字符数，长文档调高到 800–1000 |
| chunk_overlap | 50 | 块之间重叠，避免语义断裂 |
| 分段策略 | 按段落 | 长法律 / 医疗文档改"按章节" |
上传后可以在详情页看每一段的切片结果——这一步一定要抽样看，很多知识库 RAG 效果差是因为切片乱。
建第一个应用
应用 → 新建 → 简易应用（对话），绑定刚才建的知识库。
进入调试页，问一个知识库里明确有答案的问题，看：
- 是否召回了相关 chunk（右侧会显示）
- 答案是否引用了正确的段落
- 答案是否幻觉（没引用凭空说话）
如果召回不对，回到知识库调 chunk_size / overlap；如果召回对但答案不对，调 prompt 或换模型。
RAG 调参：五步都能调
FastGPT 相比 Coze/Dify 最大优势是 RAG 五步都能可视化调。
1. 问题预处理
在应用节点里打开"问题优化"：
- 改写：把口语化问题改成结构化查询
- 扩展：一个问题拆成多个子问题，分别检索再合并
- 纠错：修正错别字
对不熟悉领域术语的用户，问题预处理能让召回率提升 10%–20%。
2. 检索策略
三种检索：
- 语义检索：向量相似度，适合意图理解
- 关键词 BM25：字面匹配，适合专业术语、编号
- 混合检索：两者加权，通常最好
对政策、条款、代号密集的场景（如法律条文、药品编号），一定要开混合检索。
3. 重排序 Rerank
在检索节点加一个 reranker，可以用：
- BGE Reranker（本地，中文好）
- Cohere Rerank（云端，多语言）
Rerank 会把初步召回的前 20 段进一步排序，选出最相关的 5–10 段。对精度提升明显，但每次调用会增加 200–500ms 延迟。
4. 上下文组装
控制送给 LLM 的 chunk 数量：
- 少（3–5 段）：答案精准但可能漏信息
- 多（10–20 段）：召回全但 token 贵、幻觉风险高
通用推荐 5–8 段起步，看真实业务再调。
5. 答案生成
调 prompt 的 4 个关键点：
- 明确"只根据参考资料回答"
- 强制"引用来源段号"
- 拒答"参考资料里没有的问题"
- 输出格式（Markdown / JSON / 表格）
上线前 checklist
-
root密码已改，MinIO 默认密码已改 - 服务器只开必要端口，3000 走 Nginx 反代 + HTTPS
- 数据库（PG/Milvus）已定期备份
- LLM API Key 走 secret 管理，不写到代码里
- 至少 20 条测试问答已跑过，召回准确率 > 80%
- 幻觉抽查：对知识库里没有的问题应该拒答
- 监控：接了日志（LLM 调用量、错误率、延迟）
- 限流：单用户 QPM、单知识库 QPS 都有上限
- 内网 DNS 已配好，员工能通过友好域名访问
常见坑
部署阶段
- 镜像 tag 对不上：编排文件里的 image tag 不一定是最新 release，腾讯云教程 提到过；把
image:手动改成对应 release tag - PG 数据卷权限错：first run 有时 PG 会因 volume 权限报错，删卷重来一次即可
- MinIO 默认密码
minioadmin/minioadmin：公网部署前必须改，否则文档会被爬走 - 服务器时间不同步：token 签发失败，登录不上；
ntpdate同步一下
建库阶段
- 忘配 embedding 模型：只配 GPT-4 对话模型，上传知识库后无法索引，界面显示"处理中"永远不结束
- 切片太碎：默认 512 字符对代码 / 长条款不友好，改成"按章节 + 800 字符 + overlap 100"
- 上传大 PDF 卡住：单文件 > 50MB 时切分工作会占用大量内存，先本地拆成小 PDF 再上传
调参阶段
- 只调 prompt 不调切片：答案不准 90% 是切片问题，不是 prompt 问题；先看召回段是否正确，再改 prompt
- rerank 全开不看延迟：对话延迟从 2s 涨到 5s 会影响用户体验，只对精度敏感场景开 rerank
- 上下文塞太多：一次给 LLM 20 段参考资料，token 成本涨 4 倍，幻觉反而更多
上线阶段
- 没做限流：员工问出恶意长文本 prompt，一次烧掉几十美元；后台一定要配 QPM 限制
- 知识库没版本管理：文档更新后没重建 embedding，答案继续用老版本内容；定期重建 + 记录版本号
- 没日志：出错误答案后无法回溯是哪段召回的哪个 chunk 出的问题
和 Dify / Coze 的衔接
如果你未来会加入 Dify 或 Coze，FastGPT 提供 OpenAI 兼容的对话 API 和知识库检索 API：
- 在 Dify 里把 FastGPT 应用地址配成"OpenAI 兼容模型端点"，可以直接在 Dify 工作流里用 FastGPT 的知识库能力。
- 在 Coze 里通过"外部 API 插件"调 FastGPT 检索 API，把召回内容拼进 Coze 的 Bot prompt。
这两个组合让"FastGPT 做知识库底座 + Dify/Coze 做应用层"变得非常自然。