FastGPT 是一款开源的知识库问答系统，它把大语言模型与本地文档检索结合起来，适合搭建企业内部的私有问答助手。和直接调大模型 API 相比，FastGPT 会把上传的文档先进行清洗、切片和向量化，用户提问时先通过向量检索找到相关内容，再把这些内容作为上下文拼进提示词，让模型基于资料作答。这种模式能有效降低模型编造答案的概率，同时让回答附带原文引用。下面按照从零开始的方式，完整走一遍部署、配置、导入和调优流程。
一、准备服务器与Docker环境
FastGPT 的核心服务依赖容器化运行，因此第一步要准备好 Linux 服务器和 Docker 环境。最低配置建议 2 核 CPU、4GB 内存和 40GB 可用磁盘，如果只是内部测试，1 核 2GB 的轻量服务器也能跑通，但上传大文件或批量向量化时会比较慢。操作系统可以选择 Ubuntu 22.04、Debian 12 或 CentOS Stream 9，以下步骤以 Ubuntu 为例。
安装 Docker 时推荐使用官方脚本，避免系统自带的旧版本带来兼容问题。执行完安装命令后，把当前用户加入 docker 组，这样后续运行 docker 命令就不需要频繁加 sudo。时区建议统一设置为 Asia/Shanghai，否则日志时间和问题记录可能会偏差八个小时。
# 安装Docker官方脚本 curl -fsSL https://get.docker.com | bash # 将当前用户加入docker组 sudo usermod -aG docker $USER # 重新登录后验证 docker version docker compose version
接下来从 GitHub 拉取 FastGPT 项目代码。该项目把部署所需的配置文件、初始化脚本和示例环境变量都放在仓库里，直接克隆到本地即可。克隆完成后进入目录，先浏览一下 docker-compose.yml 和 .env.example 文件，了解服务组成和默认配置，再根据实际环境做修改。
git clone https://github.com/labring/FastGPT.git cd FastGPT ls -la
二、配置docker-compose并启动核心服务
FastGPT 的完整运行依赖三类基础服务：PostgreSQL 负责业务数据存储，MongoDB 负责知识库切片和向量数据存储，OneAPI 负责统一管理和转发大模型 API。如果使用内置的 pgvector 扩展，PostgreSQL 本身也能承担向量检索任务，不过 FastGPT 默认方案通常会把向量数据放在 MongoDB 或专门的向量数据库中。下面的配置使用 pgvector 镜像和 MongoDB 6.0，适合快速部署。
在 docker-compose.yml 中需要重点修改数据库密码、OneAPI 端口和 FastGPT 后台初始密码。实际生产环境不要把 DEFAULT_ROOT_PSW 设置为 123456 这类弱密码。数据库连接地址里的用户名和密码必须与前面设置的环境变量保持一致，否则服务启动后会反复报认证失败。
version: '3.8'
services:
pg:
image: pgvector/pgvector:pg16
container_name: fastgpt-pg
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: your_password
POSTGRES_DB: fastgpt
ports:
- "5432:5432"
volumes:
- ./data/pg:/var/lib/postgresql/data
mongo:
image: mongo:6.0
container_name: fastgpt-mongo
ports:
- "27017:27017"
volumes:
- ./data/mongo:/data/db
oneapi:
image: justsong/one-api
container_name: fastgpt-oneapi
ports:
- "3000:3000"
environment:
- TZ=Asia/Shanghai
fastgpt:
image: ghcr.io/labring/fastgpt:latest
container_name: fastgpt-app
ports:
- "3001:3000"
environment:
- DEFAULT_ROOT_PSW=123456
- OPENAI_BASE_URL=http://oneapi:3000/v1
- CHAT_API_KEY=your_api_key
- DB_PG_URL=postgresql://postgres:your_password@pg:5432/fastgpt
- DB_MONGO_URL=mongodb://mongo:27017/fastgpt?authSource=admin
depends_on:
- pg
- mongo
- oneapi
配置完成后，在项目根目录执行 docker compose up -d 启动所有容器。第一次启动会拉取镜像，耗时取决于网络速度。可以使用 docker compose logs -f fastgpt 查看实时日志，如果没有明显报错，浏览器访问服务器的 3001 端口就能看到 FastGPT 的登录页面。此时 OneAPI 的管理界面会暴露在 3000 端口，默认账号通常是 root，初始密码需要根据 OneAPI 项目文档确认。
# 启动全部服务 docker compose up -d # 查看运行状态 docker compose ps # 查看FastGPT日志 docker compose logs -f fastgpt
三、接入大模型API并创建知识库
FastGPT 本身不提供大模型服务，需要接入第三方的模型 API，比如 OpenAI、文心一言、通义千问、DeepSeek 或者本地部署的 Ollama。OneAPI 的作用就是把这些不同协议和渠道的模型统一转换成 OpenAI 兼容格式，FastGPT 只需要配置一个统一地址和令牌就能调用多个模型。先进入 OneAPI 后台，在渠道管理中添加供应商信息，包括 API 地址、访问密钥和模型列表。
添加渠道后，在 OneAPI 中创建一个新的访问令牌，这个令牌就是 FastGPT 侧要填的 CHAT_API_KEY。如果已经有 OpenAI 格式的 API 地址，也可以跳过 OneAPI，直接把 OPENAI_BASE_URL 指向该地址，再填入对应的密钥。不过使用 OneAPI 的好处是后续更换模型供应商时不需要改动 FastGPT 配置，只要在 OneAPI 后台切换渠道即可。
登录 FastGPT 后台，进入模型配置页面，添加需要使用的对话模型和向量模型。对话模型负责生成最终答案，向量模型负责把文本转成向量用于检索。通常选择同一个供应商的 embedding 模型，例如 text-embedding-3-small 或者本地模型 bge-large-zh。模型名称必须与 OneAPI 渠道中填写的名称完全一致，否则请求会返回模型不存在。
接着创建第一个知识库。知识库可以理解为一组文档的集合，适合按部门、项目或产品线划分。创建时需要指定向量模型和索引方式，按默认参数即可。知识库本身只是一个容器，真正的数据需要在上传文档后才会进入向量索引。
四、导入文档并测试问答效果
进入知识库页面，上传需要检索的文档。FastGPT 支持 txt、md、pdf、docx、html 等常见格式。上传后系统会自动对文档进行分段，默认的切片大小通常在 512 个 token 左右，相邻片段之间保留一定重叠，避免一句话被截断后丢失语义。对于格式复杂的 PDF，建议先转换成纯文本再上传，否则可能会混入页眉页脚等噪声。
切片参数会直接影响回答质量。如果文档内容较短且问题集中，可以把切片长度调小，让召回的内容更聚焦；如果文档逻辑连贯、段落较长，适当增大切片长度并提高重叠比例，能保留更多上下文。切片越小，召回越精准，但可能遗漏跨段落的信息；切片越大，上下文越完整，但容易引入无关内容。可以根据测试结果逐步调整。
上传完成后，可以在知识库的测试窗口直接提问。问题尽量用自然语言描述，例如输入“公司年假怎么申请”，系统会先召回相关文档片段，再让大模型基于这些片段作答。返回结果中通常包含引用来源，点击来源可以查看原文位置。如果答案不理想，先检查召回片段是否包含正确信息，再判断是模型能力不足还是切片策略不合适。
如果需要通过 API 进行自动化测试，可以使用下面的 Python 脚本。注意把 your_fastgpt_token 替换成 FastGPT 后台生成的访问令牌，模型名称替换成已配置的对话模型。
import requests
url = "http://localhost:3001/api/v1/chat/completions"
headers = {
"Authorization": "Bearer your_fastgpt_token",
"Content-Type": "application/json"
}
payload = {
"model": "gpt-4o-mini",
"messages": [
{"role": "user", "content": "公司年假怎么申请？"}
],
"temperature": 0.2
}
resp = requests.post(url, json=payload, headers=headers, timeout=30)
print(resp.json())
五、常见问题与检索优化
初次部署后最常遇到的问题是模型接口连通失败。可以先用 curl 直接请求 OneAPI 的接口确认令牌有效，再检查 FastGPT 容器内部是否能访问 OneAPI 容器。由于两者通过 Docker 内部网络通信，FastGPT 的 OPENAI_BASE_URL 必须使用服务名 oneapi 而不是 localhost，否则容器内无法解析宿主机地址。
回答不够准确时，优先调整检索参数而不是频繁更换模型。FastGPT 的检索阶段支持配置召回条数和相似度阈值，适当增加召回条数能让更多相关片段进入上下文，但同时会增加 token 消耗。温度参数建议保持在 0.1 到 0.3 之间，知识库问答场景不需要太强的创造性，较低的随机性能减少模型偏离资料内容的概率。
如果文档更新频繁，需要定期重新上传或触发重新向量化。FastGPT 支持增量更新，但删除旧版本后索引可能不会立即清理干净，建议每周统一做一次全量重建。对于敏感数据，可以配合 Nginx 反向代理和 HTTPS 限制公网访问，或直接部署在内网环境，避免知识库内容暴露在公网。
通过以上步骤，一台普通服务器就能承载完整的企业知识库问答能力。后续根据使用情况，还可以扩展多知识库权限、多用户管理、工作流编排等高级功能，逐步把 FastGPT 嵌入到内部工单、客服和培训系统中。