FastGPT——低代码快速构建高精度私有知识库问答LLM Agent

发表于 2026/08/24

作者 ManShouyuan

本文总阅读量次， 86 分钟阅读

引言

FastGPT（Labring开源，Apache 2.0）是一个基于大语言模型的AI Agent应用开发平台，集知识库问答、可视化工作流、Agent编排、工具调用和技能扩展于一体，让开发者和业务人员都能快速构建专属AI应用。

开箱即用的企业级RAG+可视化Agent工作流平台，是FastGPT的两大核心特色架构。核心能力包含私有知识库问答、零代码拖拽式AI流程编排、多模型统一接入、对话管理、API对外输出，主打降低行业知识库、智能客服、AI Agent落地成本。

定位：垂直深耕企业知识库问答的轻量化开源AI平台，RAG为绝对核心
核心特色：主打高精度私有知识库问答，配套轻量化可视化Flow编排；
差异化：自研优化RAG链路（专属QA式分片、空检索拦截、引用溯源、精准去幻觉），天生适配内部文档问答、智能客服、内部知识机器人；
弱化重型复杂Agent，强化知识检索效果、对话上下文精细化管控、文档一键导入解析；
适用：绝大多数场景只是基于企业文档问答，极少复杂跨系统多步骤编排的场景。

FastGPT一次问答全链路时序

FastGPT有什么

源码工程结构如下，

FastGPT/
├── packages/            # 全局共享基础包
│   ├── global/          # TS类型定义、枚举、常量，前后端共用类型约束
│   ├── service/         # 后端核心业务逻辑（RAG、对话、工作流、模型对接）
│   └── web/             # 前端国际化、公共组件
├── projects/            # 可独立运行应用服务
│   ├── app/             # Next.js主Web前后端一体应用
│   ├── agent-sandbox/   # Agent工具调用安全沙箱
│   ├── code-sandbox/    # 代码执行隔离沙箱
│   ├── marketplace/     # 应用/插件模板市场
│   └── mcp_server/     # 外部协议对接服务
├── sdk/                 # 对外开放SDK
├── deploy/              # Docker/K8s/Helm部署脚本
└── scripts/             # 工程脚本

FastGPT部署架构（来自官方文档）

FastGPT流程架构

整体分层架构（四层标准分层）

前端接入层：Next.js全栈前端、API网关、第三方对接入口；
业务核心逻辑层：Node.js+TS，对话引擎、知识库RAG、Workflow工作流、模型调度、用户权限管理；
基础设施中间件层：缓存、消息队列、对象存储、沙箱隔离服务；
数据持久层：业务库、向量库、文件存储、第三方LLM/Embedding服务。

各组件职责

MongoDB：业务元数据、对话历史、应用配置、知识库元数据；不存向量；
向量库(Milvus/PGVector)：保存文档Embedding向量，做语义检索；
Redis：会话缓存、BullMQ异步任务队列（文档解析、导入任务）；
MinIO：原始PDF、Word、图片等附件二进制文件；
Workflow调度器dispatchWorkFlow：核心引擎，驱动可视化节点流转（条件分支、循环、工具调用）；
One‑API：统一模型网关，屏蔽各家大模型接口差异，做密钥、限流计费；
沙箱：安全隔离执行代码、Agent工具调用；
MCP Server：把FastGPT能力对外暴露为Agent可调用工具。

设计优势：前后端共享一套类型，避免接口定义不一致，模块化低耦合扩展。

第一层：接入层（前端+网关+外部集成）

前端技术栈

框架：Next.js 16 + React18 + Chakra UI；
渲染模式：SSR+SSG混合，首屏加速、SEO友好；
能力：可视化知识库配置、Workflow拖拽编辑器、对话调试面板、模型参数配置、数据管理后台、多端适配（Web/小程序）；
国际化：中英日多语言i18n完整支持。

API网关与对外接入

内置Next.js原生API路由，生产环境可前置Nginx/Kong网关；
兼容OpenAI标准接口格式，第三方可直接像调用OpenAI一样调用FastGPT对话接口；
对接生态：飞书、企业微信、钉钉、公众号、自有业务系统、小程序、APP；
权限控制：API密钥鉴权、限流、IP黑白名单、租户隔离。

第二层：核心业务层（整个系统心脏，五大核心子模块）

模块1：AI模型统一调度中心（AI Core）

作用：统一屏蔽不同LLM/Embedding服务商差异，全局模型管理

模型分类管理
- LLM大语言模型：GPT、Claude、文心一言、通义千问、DeepSeek、本地私有化Llama/Qwen等；
- Embedding向量化模型：文本向量化，用于知识库向量构建；
- ReRank重排模型：检索结果精细打分排序；
统一抽象Provider架构每种模型封装独立适配器，统一入参出参，新增模型仅需新增Provider，无需改动上层业务，
1 请求入口 → 模型路由分发 → OpenAI/百度/阿里/本地模型适配器 → 流式/非流式返回
关键能力
- 上下文长度自动截断、token计数管控；
- 流式SSE实时对话输出；
- 多模型负载均衡、失败自动降级；
- 提示词模板全局管理、系统Prompt动态配置。

模块2：知识库RAG引擎（项目最核心）

知识库核心流程图（来自官方文档）

完整端到端RAG流水线：文档上传→预处理→切片→向量化入库→问答检索→答案生成闭环

知识库构建链路（离线构建）

文件接入：PDF、Word、Markdown、Excel、图片OCR、网页抓取、API推送文本；
文本预处理
- 自动清洗脏数据、表格解析、公式保留、分页拆分、去重；支持自定义清洗规则；
智能分块Chunk策略
- 固定长度分割、语义自适应分割、标题层级切割；
- 特色QA式分块：自动把文档转为问题-答案二元组存入向量库，检索准确率提升约23%；
Embedding向量化：调用配置的Embedding模型生成高维向量；
写入向量数据库建立索引。

在线问答检索链路（用户提问阶段）

查询扩展：LLM把原始问题拆解成多个相似子问题，提升召回覆盖面；
双层混合检索（核心优势）
- 稀疏检索：BM25关键词倒排索引检索，精准命中专有名词、编号、函数名；
- 密集检索：向量余弦相似度语义检索，理解模糊语义；
RRF融合算法：合并两路检索结果权重打分，解决单一检索偏科问题；
ReRank重排：轻量排序模型对Top-N候选片段精细打分，剔除低相关内容；
智能截断：控制总上下文token不超过LLM上下文上限，防止溢出；
溯源引用：生成答案附带原文出处链接、文档名称、位置，解决AI幻觉溯源问题。

用户问题 → 查询优化扩展 → 多路混合检索 → RRF分数融合 → ReRank重排 → 过滤阈值校验 → 上下文拼装进Prompt → LLM生成回答

支持向量存储选型

轻量部署：PostgreSQL + pgvector（单机首选）；
大规模分布式：Milvus、SeekDB、OceanBase向量引擎；
不支持向量库时可降级纯关键词检索。

模块3：Workflow可视化工作流引擎（差异化技术）

摆脱固定RAG流程，拖拽式零代码编排完整AI业务链路，本质是一套有向无环图DAG调度引擎

内置主流节点类型：
- 基础节点：用户提问、LLM对话、知识库检索、条件判断、循环分支；
- 工具节点：HTTP调用外部API、SQL数据库查询、代码执行、时间等待、变量赋值；
- 高级节点：意图分类、内容提取、数据格式化、消息推送、文件处理；
执行机制
- 前端拖拽生成JSON格式DAG配置，后端Workflow调度器串行/并行执行节点，全局变量透传上下文；支持断点调试、单步运行、日志回放；
典型场景：
- 用户提问→意图判断→查业务数据库库存→知识库补充说明→组装回答→推送结果到企业微信。

模块4：对话管理引擎（Chat Core）

多轮上下文管理：会话历史持久化、滑动窗口截断、记忆分层（短期对话记忆+长期知识库记忆）；
会话隔离：按用户/会话ID独立上下文，租户数据完全隔离；
对话记忆策略：精简摘要记忆、固定长度缓存、重要信息抽取长期记忆；
会话统计：token消耗、问答耗时、检索命中情况、模型调用日志全埋点。

模块5：租户&权限&应用管理

多租户隔离：企业空间独立知识库、模型配额、数据隔离；
RBAC权限：管理员、编辑、只读访客分级权限；
应用市场：一键创建对话应用、配置提示词、绑定知识库、发布对外API。

第三层：中间件基础设施层

组件	作用
`Redis`	热点对话缓存、模型限流计数、分布式锁、会话临时缓存、排队任务限流
`RabbitMQ`	异步任务队列：文档解析切片、批量向量化、定时任务、重负载离线任务削峰
对象存储`S3`	上传的原始文档、图片、附件文件持久化存储
`Sandbox`隔离服务	`agent-sandbox`：第三方工具调用网络隔离； `code-sandbox`：执行自定义代码沙箱，防止注入攻击
监控体系	接口耗时、向量检索耗时、`LLM`调用失败率、系统资源监控

第四层：数据持久层

MongoDB（核心业务主库）
- 存储：用户信息、租户配置、对话记录、知识库元数据、Workflow流程配置、模型配置、权限数据、系统日志；
- 部署建议：生产环境必须开启Mongo副本集保证高可用与数据可靠性；
向量数据库
- 存储文档切片向量、索引结构，支撑毫秒级相似度检索；
PostgreSQL（可选）
- 搭配pgvector兼顾业务数据+向量，小型部署单库搞定，无需额外向量组件；
对象存储：PDF、图片等原始文件。

两大核心特色架构

RAG多层递进检索架构（解决传统RAG召回差、精度低）

预处理层：问题改写、多角度子问题生成，扩大检索入口；
粗召回层：BM25+向量两路并行召回海量候选；
融合层：RRF归一化分数合并，消除两种检索打分体系差异；
精排层：ReRank模型语义精细打分，过滤无关噪声；
约束层：相似度阈值过滤低匹配片段、token总量约束。

整套架构相比单纯向量检索，实际业务问答准确率提升约40%。

Workflow DAG编排架构设计

静态：前端可视化拖拽生成JSON DAG描述文件，定义节点、连线、执行条件；
动态：后端Workflow Dispatcher调度器按拓扑序执行；
- 串行执行：依次运行节点
- 并行分支：多节点同时执行
- 条件分支：if-else路由不同流程
- 循环节点：批量遍历数据执行逻辑
上下文容器：全局Context存储所有节点输出变量，节点间数据互通，支持表达式取值。

小结

架构优势

低耦合模块化：RAG、对话、工作流、模型调度完全解耦，单独替换模块；
模型无关化：统一抽象层，无缝切换云端/本地私有化大模型；
轻量化上手：无需自研RAG基建，开箱即用整套链路；
企业级隔离：多租户、权限、数据隔离，适配私有化内网部署；
可观测性完善：全链路日志、检索耗时、LLM调用指标可视化。

架构取舍

后端基于Node.js而非Go/Java：前后端技术栈（Node.js+TS）统一，迭代开发效率高，业务层灵活扩展；高并发极致吞吐场景可前置网关+横向扩容弥补，依靠水平扩容补足吞吐；
MongoDB做主库：文档型天然适配对话、灵活的知识库结构配置，结构化强事务场景可对接外部MySQL；
Embedding与LLM外置：不内置训练推理，专注应用层编排，轻量化易对接各类自研大模型，轻量化对接各类云端/私有化自研大模型，降低部署门槛。

内网私有化部署架构（典型业务落地架构示例），如下，

内网用户 → Nginx网关 → FastGPT集群
↓
业务层：RAG检索 + Workflow对接内部业务数据库
↓
数据层：Mongo(业务)+Milvus(向量)+对象存储(文档)
↓
模型层：内网部署Qwen/Llama/DeepSeek私有化大模型+本地Embedding服务

扩展改造方向

接入自研Agent框架：在Workflow节点嵌入自定义Agent规划逻辑；
接入向量增强：自定义向量化预处理、分层向量索引；
对接自有计费系统：拦截AI调度层token统计做内部计费；
二次开发定制：新增行业专属切片规则、垂直领域重排模型、定制化工作流节点。

部署FastGPT

使用Docker Compose快速部署FastGPT（单机轻量化部署），组件包括FastGPT主服务、MongoDB、PostgreSQL/pgvector、Redis等，适合测试、小体量业务，一键拉起整套环境。

生产集群K8s部署
无状态服务：FastGPT应用多实例水平扩容；
有状态组件：Mongo副本集、Milvus分布式向量集群、Redis集群；
前置Ingress网关、监控Prometheus+Grafana、日志ELK、定时备份策略；
异步任务RabbitMQ集群解耦文档解析等高耗时任务，支撑每日百万级文档入库。

准备docker‑compose

FastGPT Docker Compose配置

这份是完整全组件部署模板，包含主服务、MCP、CodeSandbox、OpenSandbox Agent沙盒、Aiproxy、Mongo/Redis/Milvus/MinIO全套依赖，不是最小化版本。

组件	作用	端口
`fastgpt‑app`	`FastGPT`主前后端	`3000:3000`
`fastgpt‑mcp‑server`	`MCP`协议服务	`3003:3000`
`fastgpt‑code‑sandbox`	旧版代码沙盒（`JS/Python`代码执行）	内网不对外暴露
`fastgpt‑opensandbox‑server`	`Agent`新沙盒`OpenSandbox`核心	内网`8090`
`fastgpt‑volume‑manager`	`Agent`沙盒文件卷管理	内网`3000`
`fastgpt‑agent‑sandbox‑proxy`	`Agent`沙盒`WebSocket`鉴权代理	`3006:1006`
`fastgpt‑plugin`	插件独立服务	内网
`fastgpt‑aiproxy`+`aiproxy‑pg`	模型代理网关	内网
`fastgpt‑mongo`	业务数据库，开启副本集	内网`27017`
`fastgpt‑redis`	缓存/队列	内网`6379`
`fastgpt‑vector`(`milvus`)	向量数据库	内网`19530`
`fastgpt‑minio`	文件对象存储	`9000/9001`

关键区分
fastgpt-code-sandbox：旧代码沙盒，工作流代码块执行；
OpenSandbox(fastgpt‑opensandbox‑server)：Agent智能体沙盒，用于Agent运行完整环境，需要挂载宿主机docker.sock。

启动服务前，预先把需要的镜像拉到本地，

  
$ docker compose --profile prepull pull
[+] pull 183/183
 ✔ Image milvusdb/milvus:v2.4.3                                                        Pulled   844.3s
 ✔ Image sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/server:v0.2.0     Pulled   8.7s
 ✔ Image registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-mcp_server:v4.14.23         Pulled   1854.6s
 ✔ Image registry.cn-hangzhou.aliyuncs.com/fastgpt/mongo:5.0.32                        Pulled   1889.4s
 ✔ Image registry.cn-hangzhou.aliyuncs.com/fastgpt/redis:7.2-alpine                    Pulled   99.0s
 ✔ Image quay.io/coreos/etcd:v3.5.5                                                    Pulled   15.0s
 ✔ Image registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-agent-volume-manager:v0.2.0 Pulled   413.2s
 ✔ Image registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-plugin:v1.0.3               Pulled   413.0s
 ✔ Image registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-code-sandbox:v4.15.7        Pulled   1491.9s
 ✔ Image registry.cn-hangzhou.aliyuncs.com/fastgpt/pgvector:0.8.0-pg15                 Pulled   831.8s
 ✔ Image registry.cn-hangzhou.aliyuncs.com/labring/aiproxy:v0.6.5                      Pulled   16.7s
 ✔ Image minio/minio:RELEASE.2023-03-20T20-16-18Z                                      Pulled   957.9s
 ✔ Image registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-agent-sandbox:v0.2.0        Pulled   1154.8s
 ✔ Image sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/egress:v1.1.4     Pulled   9.9s
 ✔ Image registry.cn-hangzhou.aliyuncs.com/fastgpt/minio:RELEASE.2025-09-07T16-13-09Z  Pulled   287.9s
 ✔ Image registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt:v4.15.8                     Pulled   750.2s
 ✔ Image registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-agent-sandbox-proxy:v0.2.0  Pulled   37.8s
 ✔ Image sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/execd:v1.0.21     Pulled   6.1s

启动服务

启动服务，直到fastgpt-app主服务成功启动，如下，

  
$ docker-compose up -d
[+] up 20/20
 ✔ Network fastgpt_vector                Created                      0.0s
 ✔ Network fastgpt_data                  Created                      0.0s
 ✔ Network fastgpt_aiproxy               Created                      0.0s
 ✔ Network fastgpt_app                   Created                      0.0s
 ✔ Network fastgpt_codesandbox           Created                      0.0s
 ✔ Container fastgpt-agent-sandbox-proxy Started                      1.0s
 ✔ Container fastgpt-code-sandbox        Healthy                      32.0s
 ✔ Container fastgpt-mcp-server          Started                      0.8s
 ✔ Container fastgpt-minio               Healthy                      32.0s
 ✔ Container fastgpt-volume-manager      Started                      0.9s
 ✔ Container fastgpt-milvus-minio        Healthy                      31.4s
 ✔ Container fastgpt-redis               Healthy                      32.0s
 ✔ Container fastgpt-aiproxy-pg          Healthy                      6.4s
 ✔ Container fastgpt-opensandbox-server  Started                      0.8s
 ✔ Container fastgpt-mongo               Healthy                      32.0s
 ✔ Container fastgpt-milvus-etcd         Healthy                      31.4s
 ✔ Container fastgpt-milvus-standalone   Healthy                      47.9s
 ✔ Container fastgpt-plugin              Healthy                      36.4s
 ✔ Container fastgpt-aiproxy             Started                      6.4s
 ✔ Container fastgpt-app                 Started                      48.0s

登录访问

访问服务，http://localhost:3000，登录服务的默认账号为root, 密码可以自行指定（比如d1808b04b0875a12），

FastGPT主界面

配置模型

前面说过，粗排和知识库向量化索引会用到Embedding索引模型，精排会用到Ranking重排模型，生成内容会用到LLM语言模型，在FastGPT中，这些模型都可以在账号-模型提供商页面，进行模型配置，

FastGPT模型提供商界面

ollama运行本地模型

为了进行简单地测试，以开源的deepseek模型为例，在本地部署运行。这里选用对资源要求不是那么高的小规模阉割版模型，比如1.5b或7b。

参数版本模型	大小	建议CPU	建议内存	建议显存	特点
`deepseek‑r1:1.5b`	`1.1GB`	`4`核	`4~8G`	`4GB`	轻量级，速度快、普通文本处理
`deepseek‑r1:7b`	`4.7G`	`8`核	`16G`	`14GB`	性能较好，硬件要求适中
`deepseek‑r1:8b`	`4.9GB`	`8`核	`16G`	`14GB`	略强于`7b`，精度更高
`deepseek‑r1:14b`	`9GB`	`12`核	`32G`	`26GB`	高性能，擅长复杂任务，如数学推理、代码生成
`deepseek‑r1:32b`	`20GB`	`16`核	`64G`	`48GB`	专业级，适合高精度任务
`deepseek‑r1:70b`	`43GB`	`32`核	`128G`	`140GB`	顶级模型，适合大规模计算和高复杂度任务
`deepseek‑r1:671b`	`404GB`	`64`核	`512G`	`1342GB`	超大规模，性能卓越，推理速度快

备注：显存为FP16大致参考值；使用量化版本(q4_K_M/q5_K_M)显存占用可以大幅降低。Ollama环境下，无GPU会使用CPU+内存推理，速度会明显下降。

准备ollama docker compose配置文件，如下，

  
services:
  ollama:
    image: ollama/ollama
    container_name: ollama
    restart: unless-stopped
    ports:
      - 11434:11434
    volumes:
      - ./ollama:/root/.ollama
    environment:
      # 允许局域网跨域形式访问API
      - OLLAMA_HOST=0.0.0.0:11434
      - OLLAMA_ORIGINS=*

直接用ollama把模型跑起来，

  
$ docker compose --profile prepull pull
$ docker-compose up -d
$ docker exec -it ollama /bin/bash

$ ollama run deepseek-r1:1.5b
$ ollama run deepseek-r1:7b
$ ollama run bge-m3 "sky"

$ llama ps
NAME             ID              SIZE      PROCESSOR    CONTEXT    UNTIL
bge-m3:latest    790764642607    1.2 GB    100% CPU     4096       About a minute from now

$ ollama list
NAME                ID              SIZE      MODIFIED
bge-m3:latest       790764642607    1.2 GB    5 days ago
deepseek-r1:7b      755ced02ce7b    4.7 GB    5 days ago
deepseek-r1:1.5b    e0979632db5a    1.1 GB    6 days ago

用以下任一API测试下效果，看到正常的输出，就表示模型正常跑起来了。

http://localhost:11434/api/generate
http://localhost:11434/api/chat
http://localhost:11434/v1/chat/completions
http://localhost:11434/api/embeddings
http://localhost:11434/v1/embeddings

$ curl -X POST \
-H "Content-Type: application/json" \
-d '{"model":"deepseek-r1:1.5b","prompt":"What is DeepSeek AI?"}' \
"http://localhost:11434/api/generate"

$ curl http://localhost:11434/api/chat -d '{
  "model": "deepseek-r1:1.5b",
  "messages": [
    { "role": "user", "content": "why is the sky blue?" }
  ]
}'

$ curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model":"deepseek-r1:1.5b",
    "messages":[{"role":"user","content":"hello"}]
  }'
{"id":"chatcmpl-332","object":"chat.completion","created":1787557849,"model":"deepseek-r1:1.5b","system_fingerprint":"fp_ollama","choices":[{"index":0,"message":{"role":"assistant","content":"\n\nHello! How can I assist you today? 😊"},"finish_reason":"stop"}],"usage":{"prompt_tokens":4,"completion_tokens":16,"total_tokens":20}}

$ curl http://localhost:11434/api/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model":"bge-m3:latest",
    "prompt":"今天天气不错"
  }'

$ curl http://localhost:11434/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model":"bge‑m3:latest",
    "input":"今天天气不错"
  }'

不要用Ollama承载bge‑reranker‑v2‑m3做Rerank重排。
Ollama没有提供标准rerank接口，FastGPT的Rerank组件需要/rerank接口，入参query+documents输出相关性分数，Ollama原生做不到。
就算勉强跑通/api/embed，你要自己写中转服务拼接query‑document对、计算分数，开发成本高，还会遇到GGML断言随机崩溃。
推荐方案：TEI（text‑embeddings‑inference）部署reranker（生产稳定，完美适配FastGPT）。

FastGPT接入本地模型

方式一：渠道里添加模型（推荐，不用填自定义请求地址）

【模型】→【模型渠道】→【添加渠道】
渠道类型选 OpenAI
API地址填写：http://ip:11434/v1
API密钥：Ollama不需要鉴权，随便填占位字符串，例如sk‑dummy
模型列表添加：填入deepseek，勾选该模型，保存渠道
去到【模型列表】→【添加模型】
- 模型ID：deepseek-r1:7b（必须和ollama pull的模型名字完全一致）
- 模型类型：LLM‑聊天模型
- 选择刚刚建好的Ollama渠道
- 上下文填对应模型最大上下文，deepseek-r1:7b一般填8192
- 其他参数默认，保存

不需要填写自定义请求地址字段，留空！自定义请求地址是绕开渠道，直接指定完整接口地址。

方式二：使用自定义请求地址（不推荐，单模型专用）

自定义请求地址：http://ip:11434/v1/chat/completions
自定义请求Key：Ollama无密钥，随便填sk‑xxx占位。
模型ID：填写deepseek-r1:7b（和ollama模型名严格一致）

FastGPT语言模型配置

FastGPT索引模型配置

如果要用自定义请求地址字段，必须填OpenAI标准完整路径。
注意：这里填了自定义请求地址，会直接忽略渠道配置，直接POST到上面这个完整url。
错误地址：http://ip:11434/v1/api/chat，这是ollama原生接口，请求报文格式完全不一样，FastGPT会报错。

关键坑说明
自定义请求地址，这个字段是完整接口路径，Ollama OpenAI兼容接口地址格式要写对；/v1/api/chat是Ollama原生接口，不是OpenAI兼容接口，FastGPT不能用这个地址，要用/v1/chat/completions；同样地，索引模型用/v1/embeddings；
模型ID严格匹配：ollama那边是deepseek-r1:7b，FastGPT模型ID就必须写deepseek-r1:7b，不能写deepseek。大小写、tag标签必须完全一致；
网络：FastGPT是docker容器，HostIP要容器可以访问；如果ollama跑宿主机，部分环境要填宿主机网关，不能写127.0.0.1；
Ollama默认只监听127.0.0.1，docker容器访问会连接拒绝！必须配置OLLAMA_HOST=0.0.0.0重启ollama。

FastGPT可用模型列表

新建Agent

有了可用基础模型之后，就可以新建一个问答Agent测试一下，当然回答的内容的精度和所使用的模型能力有很大的关系。

FastGPT Agent测试

FastGPT Agent流程

新建并使用知识库

纯生成模型在处理事实类任务时存在一些固有的局限性。例如，由于这些模型依赖于固定的预训练数据，它们在回答需要最新或实时信息的问题时，可能会出现编造信息的现象，导致生成结果不准确或缺乏事实依据。此外，生成模型在面对长尾问题和复杂推理任务时，常因缺乏特定领域的外部知识支持而表现不佳，难以提供足够的深度和准确性。

检索模型（Retriever）能够通过在海量文档中快速找到相关信息，解决事实查询的问题。但传统检索模型（如BM25）在面对模糊查询或跨域问题时，往往只能返回孤立的结果，无法生成连贯的自然语言回答。由于缺乏上下文推理能力，检索模型生成的答案通常不够连贯和完整。

为了解决生成模型和检索模型的不足，RAG结合生成模型和检索模型的优势，实时从外部知识库中获取相关信息，并将其融入生成任务中，确保生成的文本既具备上下文连贯性，又包含准确的知识。

创建FastGPT Agent知识库

FastGPT Agent测试（知识库）

FastGPT Agent流程（知识库）

FastGPT Agent AI对话（知识库）

通过API访问FastGPT自定义Agent

FastGPT部署后，通过API访问自定义的Agent，调用核心三要素：应用ID + API密钥 + 接口地址。

获取Agent应用ID
- 登录FastGPT后台，进入已配置好的Agent应用详情页；
- 点击顶部【开发/API】菜单；
- 页面复制应用ID（AppID）（格式：app-xxxxxx）。
- FastGPT Agent 应用ID
获取FastGPT API密钥
- FastGPT个人头像 →【账号密钥】；
- 新建密钥，勾选允许调用应用API，复制API Key；
- 密钥权限全局通用，可调用当前账号下所有已发布的Agent应用。
- FastGPT API密钥
确认接口基础地址，私有化部署统一地址（根据你的部署域名/IP替换），
- 通用接口地址：http://你的IP:3000/api/v1/chat/completions
- Sealos域名部署：https://你的sealos域名/api/v1/chat/completions
- 完全兼容OpenAI接口格式，所有OpenAI客户端、SDK可直接复用。

几个关键参数，含义如下，

appId（核心）：指定调用你配置好的目标Agent，不传则调用默认模型，不会触发工作流、知识库、自定义提示词；
model：私有化部署可随意填写，FastGPT以应用内绑定的模型为准；
stream：False=一次性返回，True=流式SSE返回；
messages：支持多轮对话，传入历史对话即可实现多轮上下文联动。

  
$ curl -X POST http://localhost:3000/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fastgpt-ieQLqlDVqQ42d2XpouLjElfyL93DH8qmcyBxdHWOpwudqzY1oOK0" \
  -d '{
      "model": "deepseek-r1:1.5b",
      "appId": "6a8437a8010866c93e4ce9fc",
      "messages": [
          {"role": "user", "content": "why is the sky blue?"}
      ],
      "stream": false
  }'
{"title":"why is the sky blue?","id":"wqcpewzG0WxKdsq8c2hdGXTw","model":"","usage":{"prompt_tokens":1,"completion_tokens":1,"total_tokens":1},"choices":[{"message":{"role":"assistant","content":"\n\n天空是蓝色的，这是因为大气中的气体分子在太阳光照射下发生了微小的偏移，导致光波的波长变化，从而使我们看到了不同的颜色。同时，光的反射和散射、大气中的微小颗粒物的相互作用，进一步影响了可见光的颜色，最终天空呈现蓝色。\n\n参考：\n[Cite 1](https://www.hsc.sinica.edu.cn/chDatabase/Cite/Cite54543.html)\n[Cite 2](https://www.e backgrounds.com/tc/2022/8/28492.html)\n[Cite 5](https://www.zhihan.com/Bluesky-How-do-We-Love-Blueskies/)"},"finish_reason":"stop","index":0}]}%

  
$ curl -X POST http://localhost:3000/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fastgpt-ieQLqlDVqQ42d2XpouLjElfyL93DH8qmcyBxdHWOpwudqzY1oOK0" \
  -d '{
      "model": "deepseek-r1:1.5b",
      "appId": "6a8437a8010866c93e4ce9fc",
      "messages": [
          {"role": "user", "content": "why is the sky blue?"}
      ],
      "stream": true
  }'
data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":""},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":""},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"\n\nATMosphere"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"的"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"蓝色"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"来自"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"大气"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"的"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"色"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"散"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"作用"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"。"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"当"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"阳光"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"照射"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"到"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"空气中"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"时"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"，"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"色"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"散"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"作用"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"使得"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"不同"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"颜色"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"的"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"光"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"以"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"不同的"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"路径"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"穿过"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"大气"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"层"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"，"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"之后"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"到达"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"观察"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"者"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"的眼睛"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"。"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"蓝"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"光"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"由于"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"它"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"具有"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"较"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"短"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"的"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"波"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"长"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"，"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"更容易"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"通过"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"大气"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"层"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"的"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"折射"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"作用"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"，"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"从而"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"聚焦"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"在"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"视线"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"附近"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"，"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"因此"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"天空"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"看起来"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"是"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"蓝色"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"的"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"。"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"这种"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"现象"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"在"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":""},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"[477748e0a90b0087](CITE)中被详细描述。\n\n"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"参考"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"文献"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":":\n"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"-"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":" "},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"[477748e0a90b0087](CITE)：大气折射的作用"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"及其"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"对"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"光"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"谱"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"的影响"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"\n"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"-"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":" "},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":"[5e20e92](CITE)：温度对光谱的色散影响"},"index":0,"finish_reason":null}]}

data: {"id":"","object":"","created":0,"model":"","choices":[{"delta":{"role":"assistant","content":null},"index":0,"finish_reason":"stop"}]}

data: [DONE]

查看详细数据（Mongo、Milvus）

前面说过，MongoDB用于存储业务元数据、对话历史、应用配置、知识库元数据，不存向量；Milvus/PGVector保存文档Embedding向量，做语义检索；Redis则用来实现热点对话缓存、模型限流计数、分布式锁、会话临时缓存、BullMQ异步任务队列（排队任务限流、文档解析、导入任务）等。

FastGPT MongoDB业务数据库集合

下面是查询Agent对话的聊天详情的一个例子，

在fastgpt_chat集合里查询聊天详情（mongo）

数据库fastgpt属于V4.0及更早版本，版本里没有chat_histories集合。聊天记录全部保存在chats集合内的variables.historyList数组，不是独立拆分的消息表。

聊天会话相关

集合名	作用
`chats`	会话主表，核心！一个文档=一个会话。`variables.historyList[]`数组存放完整一轮轮聊天记录（`user/ai`）；字段包含`chatId`、`appId`、`teamId`
`chatitems`	会话子项，部分消息分片记录，旧版不存完整对话
`chat_item_responses`	`AI`返回响应的原始记录，大模型输出原始报文
`app_chat_logs`	应用聊天访问日志，统计类日志，无完整对话内容
`chat_settings`	会话独立配置（上下文长度、模型参数等）
`chat_favourite_apps`	用户收藏的应用
`chat_input_guides`	对话输入提示示例
`chat.files`	聊天上传文件元数据，记录会话上传的文件

应用&Agent相关

集合名	作用
`apps`	应用基础信息，应用名称、开场白、模型配置、应用`ID`（`appId`）
`app_versions`	应用版本快照，每次保存应用生成版本
`app_records`	应用发布记录
`app_plugin_groups`	应用绑定插件分组
`app_log_keys`	应用日志密钥
`app_registrations`	应用外部接入注册
`app_templates`/`app_template_types`	应用模板库
`agent_skills`	`Agent`智能体技能定义
`agent_skills_versions`	`Agent`技能版本
`agent_sandbox_instances`	`Agent`沙箱运行实例

知识库数据集相关

集合名	作用
`datasets`	知识库总表，知识库基础信息
`dataset_collections`	知识库集合（分组）
`dataset_collection_tags`	集合标签
`dataset_datas`	知识库文档主表，每条是一条知识库切片内容（`RAG`检索源）
`dataset_data_texts`	切片文本内容
`dataset.files`	知识库上传文件元信息
`dataset_image.files`	知识库图片文件
`dataset_trainings`	知识库索引训练任务记录
`dataset_migration_logs`	知识库迁移日志

团队、用户、权限

集合名	作用
`users`	系统账号用户表
`teams`	团队（租户）主表，`teamId`团队ID
`team_members`	团队成员
`team_member_groups`	团队成员分组
`team_group_members`	分组成员映射
`team_orgs` / `team_org_members`	组织架构
`team_installed_plugins`	团队安装插件
`team_subscriptions`	订阅套餐
`team_discount_coupons`	优惠券
`resource_permissions`	资源权限

插件、MCP、OpenAPI

集合名	作用
`system_plugins`	系统内置插件模板
`system_plugin_tools`	插件工具定义
`system_plugin_tool_tags`	插件标签
`mcp_keys`	MCP服务密钥配置
`openapis`	自定义`OpenAPI`插件配置
`openapi_tags`	`OpenAPI`标签

附加库fastgpt‑plugin：存放插件安装、运行时配置：plugin_installations、plugin_runtime_configs。

计费、调用、统计日志

集合名	作用
`llm_request_records`	大模型每一次请求完整记录，消耗`token`、请求入参出参，排查大模型报错非常有用
`usages`	团队用量统计汇总
`usage_items`	用量明细
`frequency_limits`	访问频率限制记录
`operationlogs`	后台操作审计日志
`eval_items`/`evals`	模型评测数据集、评测任务
`tracks`	埋点行为追踪

系统配置、文件存储

集合名	作用
`systemconfigs`	`FastGPT`全局系统配置
`system_models`	模型配置（模型列表、密钥）
`system_timer_locks`	分布式定时任务锁
`auth_codes`	授权验证码
`outlinks`	外部分享链接
`images`	图片资源元数据
`buffer_tts`	`TTS`语音缓存
`s3_upload_sessions`、`s3_ttls`、`s3_download_aliases`	对象存储上传下载会话

系统库（不是业务库，不要操作）

admin：mongodb系统账号库，存放数据库账号
config：副本集配置元数据
local：副本集oplog复制日志，绝对不要修改

FastGPT Milvus向量数据库

fastgpt milvus系统视图

在fastgpt_modeldata模式（milvus）

在fastgpt_modeldata数据（milvus）

关键点
FastGPT本身并不直接操作MinIO/ETCD。
MinIO、ETCD是Milvus向量库的内部依赖组件，不是FastGPT的直接依赖。
FastGPT使用Milvus只走Milvus SDK(gRPC 19530端口)；Milvus内部再去读写ETCD、MinIO。
ETCD = Milvus的大脑（元数据目录）
MinIO = Milvus的硬盘（真实向量数据）
FastGPT只跟Milvus对话，不直接碰etcd/minio。

整体链路如下，

FastGPT(知识库上传/向量检索)
        ↓ gRPC(19530)
Milvus‑Standalone
    ├─ ETCD：存Milvus全部元数据（集合、schema、segment信息、服务注册）
    └─ MinIO：存真实向量二进制数据、索引文件、binlog快照

ETCD在Milvus里做什么（FastGPT视角）

ETCD不存向量、不存文档，只存Milvus的元信息（强一致性KV存储），

Collection（Milvus集合）schema、字段定义、索引配置
segment段元信息：哪些数据段有效、属于哪个知识库集合
Milvus内部服务注册、节点状态、消费checkpoint
权限、别名、分区信息

故障现象：ETCD挂掉/损坏 → Milvus看不到集合，向量数据还在MinIO，但是Milvus不知道怎么读，知识库直接查不到数据。
MongoDB（fastgpt库）只记录：知识库ID、Milvus的collection名字；Mongo不存向量库schema、segment信息，这部分全部托管在ETCD。

MinIO在Milvus里做什么

MinIO是S3兼容对象存储，保存真正的向量二进制文件、索引文件，

.binlog：原始向量、标量字段（知识库切片、embedding向量）
.index：HNSW/IVF等向量索引文件
快照、WAL日志、compaction合并后的段文件

ETCD记录这个文件属于哪个集合、是否生效；MinIO存文件实体。
MinIO丢了=向量数据彻底丢失；ETCD丢了，文件还在，但Milvus无法识别，很难恢复。

注意：FastGPT自己也有一个minio（用于图片、文件上传），和Milvus使用的minio是两个完全独立服务，不要搞混。
fastgpt‑minio：FastGPT业务用，存上传文档、图片
milvus‑minio：Milvus向量库专用，存向量索引文件

FastGPT知识库一条文档完整流程（串联三者）

FastGPT上传文档，切片，调用Embedding模型生成向量；
FastGPT通过Milvus SDK，把向量+元字段写入Milvus；
Milvus内部流程
- Milvus先写WAL；
- 数据落盘，序列化binlog文件，写入MinIO；
- 更新segment、集合元信息，写入ETCD；
用户提问，RAG检索
- FastGPT向Milvus发起向量搜索；
- Milvus从ETCD读取元数据，知道要读取哪些segment；
- Milvus从MinIO读取向量/索引文件，加载到内存做相似度检索；
- 返回topN切片给FastGPT，再传给大模型。

和MongoDB职责对比

组件	存储内容
`MongoDB`(`fastgpt`库)	知识库元信息、文档切片文本、会话聊天记录、用户、应用配置；不存向量`embedding`
`Milvus`	向量数据库服务，对外提供`SDK`接口
`ETCD`(`Milvus`内部)	`Milvus`元数据：集合`schema`、`segment`状态
`MinIO`(`Milvus`内部)	`embedding`向量二进制、索引文件

MongoDB里dataset_datas存原始文本切片；向量embedding不在Mongo，全部在Milvus(MinIO)。

常见踩坑

只备份Mongo，不备份Milvus的ETCD+MinIO：Mongo恢复成功，但向量库全部丢失，知识库检索失效。
ETCD磁盘满、损坏：Milvus集合消失，MinIO文件还在，但无法正常使用。
两个MinIO混淆：修改fastgpt‑minio配置，对Milvus向量存储没有任何效果。
删除Milvus集合，MinIO对应的文件不会立刻删除，会后台compaction清理。

参考

附录

FastGPT六大核心技术体系（从AI算法、业务引擎、工程架构到配套基建）

FastGPT核心 = 工业化多层RAG（BM25+向量+RRF+ReRank）+ DAG可视化Workflow引擎 + 插件化多模型调度 + 异步文档处理管线 + 多租户企业级架构 + 安全沙箱防护。

核心1：多层级高精度RAG检索增强生成（项目最核心）

整套端到端工业化RAG流水线，区别于简易向量检索，多阶段递进召回+精排融合，是FastGPT立身之本。

文档预处理 & 特色分块技术

多模态文档解析引擎
- 集成MinerU、Marker专业解析引擎，支持PDF/Word/Excel/扫描件OCR、网页抓取、图片文本提取，自动解析表格、公式、排版层级；大文件分片上传+异步解析、断点续传。
三种智能Chunk切割策略
- 基础固定长度分割；
- 语义自适应分割；
- 独创QA二元组拆分：LLM自动把原文段落拆解成问题-答案键值对存入向量库，检索命中率提升约23%，专业知识库效果最优。
文本清洗：去冗余、去格式符、重复文本去重、脏数据过滤。

四层混合检索核心算法链路：用户提问 → 查询扩展 → 稀疏+密集双路召回 → RRF分数融合 → ReRank精排过滤 → Token截断拼接Prompt

LLM查询扩展
- 调用大模型把原始问题拆解为多个同义、多角度子问题，拓宽检索覆盖面，解决简短问句召回不足问题。
双引擎并行召回
- 稀疏检索（BM25）：关键词倒排索引，精准命中专有名词、编号、专业术语、固定字段；
- 密集向量检索：Embedding模型生成语义向量，依托向量库HNSW索引实现毫秒级余弦相似度匹配，解决语义模糊检索。
RRF（Reciprocal Rank Fusion）排名融合算法
- 归一化BM25与向量检索两套打分体系，无需人工配置权重，自动合并两路候选结果，规避单一检索的偏科问题。
ReRank重排精筛
- 轻量级排序模型对Top-N候选片段做精细化语义打分，剔除低相关噪声片段；搭配相似度阈值过滤无效数据。
智能上下文约束：自动统计Token，裁剪检索内容适配LLM上下文窗口，防止溢出，同时给回答附加原文溯源引用，抑制幻觉。

向量存储适配层，统一抽象向量库接口，无缝切换，

轻量部署：PostgreSQL+pgvector（HNSW向量索引）；
分布式大规模：Milvus、Zilliz、SeekDB；

业务元数据、文档基础信息存MongoDB，向量单独托管向量引擎。

核心2：DAG可视化Workflow低代码工作流引擎（差异化技术）

本质是一套有向无环图动态调度引擎，脱离固定RAG流程，零代码编排完整AI业务链路。

前端可视化编排
- 基于ReactFlow拖拽生成JSON格式DAG拓扑配置，定义节点、连线、执行条件。
后端调度核心技术点
- Tarjan SCC强连通分量检测：自动识别循环依赖、死循环，安全支持循环执行节点；
- 拓扑序驱动执行：支持串行、并行分支、IF条件判断、循环遍历、等待暂停；
- 全局上下文容器：统一变量池，全节点共享数据，支持表达式取值、变量读写；
- 执行快照、单步调试、全链路日志回放，定位流程卡点。
内置标准化节点：LLM对话、知识库检索、HTTP接口调用、SQL查询、自定义代码沙箱执行、意图分类、消息推送、数据格式化等。

核心3：统一多模型适配调度框架（模型抽象解耦层）

插件化Provider适配器架构，对各类LLM、Embedding、ReRank模型做统一接口封装，上层业务无感知切换模型，

云端模型：OpenAI、Claude、文心一言、通义千问、DeepSeek等；
本地私有化模型：Qwen、Llama、GLM等本地推理服务；
新增模型仅需开发独立适配器，无需改动RAG、对话上层逻辑。

内置调度管控能力

Token全局统计、上下文自动截断、流式SSE实时输出；
接口失败重试、自动降级、多模型负载均衡；
统一Prompt模板管理、全局参数（temperature、top_p）集中配置；
兼容OpenAI原生接口协议，第三方系统可无缝对接。

核心4：对话管理与上下文记忆体系

多轮会话上下文治理
- 会话独立隔离，支持滑动窗口截断、历史摘要压缩、超长对话精简，避免上下文无限膨胀；
分层记忆策略
- 短期记忆：当前对话轮次上下文；
- 长期记忆：抽取对话关键信息归档，结合知识库固化知识；
会话全埋点：模型耗时、检索耗时、Token消耗、问答命中率、异常失败统计，支撑计费与运维观测。

核心5：工程化后端架构与异步任务基建

整体技术栈底座

前后端一体：Next.js + TypeScript（Monorepo工程架构，前后端共用一套TS类型定义，杜绝接口不一致）；
后端运行时：Node.js；前端：React18 + Chakra UI + ReactFlow；
数据库：MongoDB（业务主库：用户、租户、对话、知识库配置、Workflow配置）；
中间件：
- Redis：会话缓存、限流、分布式锁、热点数据缓存、计数器；
- RabbitMQ：异步任务队列，承载文档解析、批量向量化、索引重建等重负载任务削峰解耦；
- S3对象存储：原始文档、附件、图片持久化存储。

异步离线任务架构

生产者-消费者模式，文档上传后丢入队列异步解析、切片、向量化入库，前端无需阻塞等待，支持任务优先级、失败重试、死信队列。

安全沙箱隔离技术

agent-sandbox：外部工具HTTP调用网络隔离，防止内网越权访问；
code-sandbox：用户自定义代码执行沙箱，资源限制、网络隔离，杜绝代码注入、服务器恶意攻击。

核心6：企业级配套关键技术

多租户数据隔离架构

基于租户ID做数据行级隔离，独立知识库、模型配额、资源限制、权限体系；RBAC分级权限（管理员、编辑、只读）。

API网关与接入层

内置鉴权：API Key校验、IP黑白名单、接口限流；
对接生态：企业微信、飞书、钉钉、公众号、自有APP/小程序；
生产环境可前置Nginx/Kong网关做负载均衡、HTTPS、WAF防护。

部署与运维架构能力

单机：Docker Compose一键部署全套组件；
集群：K8s容器化编排，应用无状态水平扩容，Mongo副本集、Redis集群、Milvus分布式集群保证高可用；
可观测：对接Prometheus+Grafana监控接口QPS、检索耗时、模型调用失败率、服务器资源。

FastGPT四层混合检索完整算法链路

整体链路完整流程
用户原始提问 → 查询增强优化层 → 稀疏+密集双路粗召回层 → RRF分数融合层 → ReRank精排过滤层

层层收敛，从大范围粗筛到精准择优，解决传统单向量检索召回不全、关键词漏匹配、排序错乱、无关文本混入Prompt等痛点。

前置前提：知识库文档已经完成解析、分块、Embedding向量化、构建BM25倒排索引、向量库HNSW索引。

第一层：查询增强优化（Query Rewrite & Query Expansion）

解决的痛点：用户提问简短、口语化、表述模糊、关键词过少，直接检索极易召回内容偏少、覆盖面不足。

具体执行逻辑

问题改写优化
- 调用LLM对用户原始问题做标准化润色：去除语气词、口语化语句，梳理成规范检索问句。
- 例：用户：咱们公司报销差旅标准是啥？ → 优化后：公司差旅费报销具体标准规定。
多角度子问题扩展（核心）
- 让大模型基于原问题拆解生成多条语义相近、不同表述角度的检索子问题。
  示例
  原问题：服务器硬盘故障怎么报修？
  扩展子问题：
  服务器硬盘损坏报修流程
  机房硬件故障申报渠道
  硬盘异常工单提交方式
同义词、实体扩充
- 识别问题里的专有名词、业务术语，补充行业同义词、缩写全称映射。

输出结果：一组经过优化后的检索Query列表，全部送入下一层并行检索。

第二层：双引擎并行粗召回（稀疏BM25检索 + 密集向量语义检索）

两路检索独立并行执行，各自召回Top-N候选文本块（Chunk），一般各自召回30～50条，拿到海量初选候选集。

稀疏检索：BM25关键词检索

原理：基于倒排索引的经典概率检索算法，对文档分词、建立词项倒排表，依靠关键词命中频次、文档长度、词重要性计算相关性得分。

优势与适用场景

精准命中专有名词、编号、代码、证件号、专业术语、固定关键词；
向量语义识别不到的精准字面匹配场景，弥补语义向量弱化字面特征的缺陷；

FastGPT落地细节

对知识库Chunk做中文分词、停用词过滤构建全局倒排索引；
输入优化后的Query，匹配关键词，输出按BM25分数降序的候选列表。

密集检索：Embedding向量相似度检索

原理

将优化后的Query送入配置的Embedding模型生成高维浮点向量；
在向量数据库的HNSW近似索引中，采用余弦相似度计算Query向量与知识库所有Chunk向量的距离；
召回语义上最相近的一批文本片段。

优势与适用场景

理解模糊语义、同义转述、上下文隐含意图，不需要关键词完全一致。
例：原文写：因公外出交通补贴，用户问：出门办事车费报销，关键词完全不同，向量可以精准匹配。

本层输出

两份独立排序列表：

ListA：BM25得分排序的候选集
ListB：向量余弦相似度排序的候选集

第三层：RRF(reciprocal rank fusion)倒数排名融合算法

为什么不能直接加权相加？
BM25的得分值域、向量余弦相似度值域完全不统一，数值无法直接加减加权；不同检索的打分逻辑维度不一样，人工调权重成本极高。RRF不需要训练、无需手动配置权重，纯基于排名位置做融合，是工业RAG主流轻量融合方案。

RRF核心计算公式如下，

RRF核心计算公式

\[RRF(Chunk) = \sum_{i\in检索渠道} \frac{1}{k + rank_i}\]

$rank_i$：该Chunk在某一路检索里的排名（第1名rank=1，第2名rank=2）；
$k$：平滑常数，FastGPT默认取值固定（通常k=60），用来弱化排名靠后文档的权重；

执行步骤

遍历两路召回里所有不重复的Chunk；
分别取出该文档在BM25列表、向量列表中的排名；没出现在某一路的rank记为无穷大，贡献值趋近于0；
累加计算每一条Chunk的RRF总分；
根据RRF总分从高到低重新全局排序，截取Top15～Top20作为融合后的候选集。

效果举例

某条文档在向量检索排第2，BM25检索排第5，两路都命中，融合分数会大幅拉高；
只在单一路靠后的文档，分数很低，会被压到列表末尾。

本层价值

融合关键词精准匹配+语义模糊匹配的优势，消除单一检索的排序偏见，输出一份兼顾字面与语义的混合排序列表。

第四层：ReRank重排精筛 + 阈值过滤 + Token截断约束

这是四层链路最后一关，对融合后的少量候选做精细化语义打分、过滤垃圾内容、控制上下文总长度，最终挑选最优片段塞入LLM Prompt。

ReRank重排模型精打分

运行逻辑
- 将用户原始问题 + 单条候选Chunk成对送入轻量级Cross-Encoder重排模型；
- 模型直接判别当前文本和用户问题的真实语义相关度，输出0~1之间的精准相关性分数。
和向量检索的本质区别
- Embedding是双塔架构：Query、文本分开编码，只能粗粒度语义匹配；
- Cross-Encoder是交叉编码，把问题+文本一起输入做深度交互计算，判断相关性精度远高于向量。
FastGPT策略：
- 只对前面RRF融合后的少量候选（十几条）执行ReRank，计算成本很低，不会带来巨大耗时。

多层过滤规则

分数阈值过滤
- 设定最低相关性阈值，ReRank分数低于阈值的文本直接丢弃，彻底剔除无关、弱相关片段，杜绝把垃圾上下文喂给大模型导致幻觉；
去重：语义高度重复的Chunk只保留最优一条；
业务黑白名单过滤：过滤禁用文档、加密内容、权限不可见知识库。

Token自适应截断（收尾关键步骤）

对筛选后按ReRank分数从高到低的文本依次累加统计Token；
不断追加文本，直到即将达到当前LLM设定的上下文安全上限；
终止加载后续文本，保证送入大模型的整体上下文不会溢出窗口、不会触发超长截断报错；
自动附带溯源标记：记录每条选中片段所属文档、页码、位置，回答时可以引用来源，方便核验。

最终输出

一批高相关、低冗余、总长度合规的知识库参考片段，拼接系统提示词+用户问题，送入LLM生成最终回答。

四层链路整体数据量级收敛变化

原始知识库百万级Chunk
↓ 第一层查询扩展：生成多条检索query
↓ 第二层双路粗召回：两路各召回30～50条，合计60～100条候选
↓ 第三层RRF融合去重：精简为15～20条混合排序候选
↓ 第四层ReRank打分+过滤+截断：最终精选3～8条高质量片段进Prompt

量级层层收缩，算力开销逐层降低，越往后计算越精细。

四层混合检索相比普通单向量RAG核心优势

解决关键词漏检：BM25兜底专业名词、编号、固定文本；
解决语义理解不足：向量覆盖模糊提问、同义改写；
解决打分体系不统一：RRF无监督融合，无需人工调参；
解决粗排序不准：ReRank深度语义精排，大幅度降低无关上下文；
约束上下文长度：防止上下文过载、LLM推理变慢、超长截断破坏有效信息。

典型问题适配演示

场景：企业制度库，用户提问：试用期离职薪资怎么结算？

查询扩展：生成多条同义问句；
BM25命中文档里试用期、离职薪资关键词片段；向量检索匹配语义相近的薪酬结算条款；
RRF把两路命中的同一份文档拉高排名；
ReRank精准判定高度相关的保留，无关的正式员工离职流程，分数偏低被过滤；
精选片段拼装Prompt，大模型依托准确资料作答。

可配置化说明

FastGPT后台全部参数能做可视化调整，

BM25、向量单次召回条数；
RRF平滑系数k；
ReRank启用/关闭、相关性阈值；
最大带入上下文Token上限；

业务简单场景甚至可以一键关闭ReRank，降低接口响应耗时。

FastGPT vs Harness

FastGPT是一套可直接部署落地的完整开源产品系统；Harness不是具体软件，是Agent工程架构范式/设计思想（Agent=LLM+Harness），定义大模型外围的执行、记忆、工具、观测、容错的整套工程层，没有标准源码实现，各家自己实现Harness层。

FastGPT内部已经实现了一套Harness能力，但它是面向业务应用、开箱即用；原生Harness范式更偏向底层Agent工程，侧重可靠性、观测、CI/CD评测闭环。

定位与本质

维度	`FastGPT`	`AI‑Harness`（`Agent Harness`范式）
本质	完整可运行的AI应用平台产品，开源软件，有`UI`、数据库、工作流、`RAG`全套组件	架构范式/设计模型，一套`Agent`外围工程规范，不是成品软件，需要开发者编码实现
核心目标	快速搭建`RAG`问答、业务`Agent`应用；低代码/可视化交付业务能力，面向业务上线	解决裸大模型缺陷：记忆丢失、工具失控、执行不可控、无法复现、缺少观测与容错，让`Agent`行为可约束、可评测、可迭代
面向人群	业务开发、实施人员，可零代码搭建`AI`应用	`AI`底层工程师，做`Agent`内核、平台底座、`CI`评测流水线
核心公式	`FastGPT` = 前端`UI` + `RAG`知识库 + `Flow`工作流引擎 + `LLM`网关 + 存储层 + 权限系统	`Agent = LLM + Harness`（记忆+工具+编排循环+观测评估+容错约束）

核心组件拆解

FastGPT架构（产品化系统），分层：前端层 → API业务层 → 核心域模块 → 存储层

前端层：Next.js可视化界面，知识库管理、Flow拖拽编排、对话调试
核心业务域core
- dataset：RAG全链路：文档解析、分块、向量化、混合检索、重排（FastGPT最强模块）
- workflow(Flow引擎)：DAG可视化编排，分支、循环、HTTP、代码节点、插件调用，实现Agent流程
- chat：会话管理、多轮对话上下文
- ai：模型抽象层，对接各类LLM/Embedding，兼容One‑API
- plugin/agentSkills：工具调用、简单Agent能力
支撑层support：用户权限、openapi开放接口、计费
存储层：MongoDB（业务、会话、应用配置）；PG‑Vector/Milvus（向量库）；Redis缓存

FastGPT内置了简化版Harness能力：会话记忆、工具调用、流程编排、变量、简单异常处理；但是缺少原生的执行轨迹观测、独立评估校验、CI门禁、子Agent沙箱、完整错误回滚等Harness范式强调的底层能力。

Harness范式组件（架构思想），Harness是包裹大模型的整套工程环境，六大核心模块，

记忆系统：短期上下文窗口、长期记忆存储、记忆压缩、子Agent记忆隔离
工具系统：MCP协议、沙箱环境、工具权限管控、工具输入输出校验
执行编排Loop：Agent循环、任务规划、子Agent委派、多步迭代，不限DAG，支持动态规划
上下文工程：上下文裁剪、信息过滤、Prompt组装，对抗上下文腐烂
观测&评估：执行轨迹Trace记录、每一步断言校验，对接Eval/Test Harness，可接入CI流水线做变更门禁（改动Prompt/Agent逻辑自动跑测试，不达标阻断上线）
约束与容错：规则拦截、异常捕获、重试、回滚、降级、Hook拦截

Harness不内置RAG知识库，知识库属于外部数据源，由开发者接入；没有UI界面，没有用户权限、应用管理等业务层。

关键差异点

编排模型

FastGPT Flow：静态DAG，拖拽定义好完整流程；执行路径预先定义，分支条件有限，适合业务确定场景；很难实现模型动态规划、无限循环自主探索。
Harness范式：Agent循环Loop，模型动态决定下一步调用什么工具、要不要生成子Agent；支持动态规划，适合开放式复杂任务；需要自己实现循环、终止条件。

RAG知识库

FastGPT：RAG是一等公民，完整成熟管线，文档解析、分块策略、混合检索、重排开箱即用，企业知识库场景极强。
Harness范式：没有内置RAG；知识库只是外部工具之一，需要自行封装检索能力接入。

可观测、评测、CI闭环

FastGPT：可看对话日志、工作流执行记录；没有原生自动化评测套件，不支持CI门禁；要做评估需要外部系统对接。
Harness范式：把Trace追踪、每一步断言、自动化评估、CI门禁作为核心组件；修改Prompt、工具逻辑后自动跑测试集，防止Agent行为退化，适合底座长期迭代。

记忆实现

FastGPT：会话级短期上下文；长期记忆需要知识库实现；缺少专门记忆压缩、记忆分离、子Agent隔离机制。
Harness范式：专门记忆子系统，区分短期上下文、长期持久记忆，支持记忆摘要、多子Agent记忆隔离，解决长任务上下文爆炸问题。

部署形态

FastGPT：Docker Compose/Helm一键部署完整产品，拿来即可做业务应用。
Harness：无成品，需要基于LangGraph/OpenHarness等框架二次开发，自己补齐存储、UI、业务层。

能力互补关系

用FastGPT做业务应用：开箱即用RAG+可视化Flow，快速交付企业问答、客服Agent。但如果需要强Agent能力：动态规划、复杂子Agent、完整观测评测，FastGPT原生能力不足，需要二次开发补齐Harness层的组件。
基于Harness范式自建底座：实现Agent循环、记忆、观测、容错；再接入RAG模块（可复用FastGPT的知识库API），再开发上层业务UI。适合做AI平台底座。

FastGPT vs Harness

选型建议

选FastGPT
- 需要快速落地企业知识库问答、业务流程Agent；希望可视化低代码，不想从零开发底层Agent引擎；私有化部署开箱即用。
- 局限：开放式自主Agent、复杂子Agent、自动化CI评测需要大量二次开发。
遵循Harness范式自建Agent底座
- 做通用Agent平台底座，需要模型动态规划、子Agent、强可观测、持续评测CI闭环；
- 缺点：全部需要自研，没有现成UI、RAG、权限系统，开发周期长。
混合方案（生产常用）
- FastGPT负责RAG知识库、业务应用管理、前端界面；基于Harness思想扩展Agent‑Loop、Trace观测、记忆管理；或者FastGPT输出API，上层封装Harness层做复杂Agent逻辑。

AI, Agent

AI Agent FastGPT

本文由作者按照 CC BY 4.0 进行授权