企业官网建设流程全解析

做 AI 应用落地这两年，FastGPT 是我迭代最频繁、也最常被问起的一个开源项目。它把知识库、AI Agent 和云原生部署这三件事串在了一条链路上，早期看起来只是一个能挂文档、能问答的轻量知识库，演进到现在，已经能支撑企业级应用：内部资料问答、工单助手、售前客服、甚至结合工作流做复杂 Agent 任务。这篇文章不讲官方文档复读，我从选型、知识库搭建、工作流编排、部署扩容到排障，把这两年踩过的坑一次性写清楚，希望给正在评估 FastGPT 或者已经在用的人一点实际参考。

1. 为什么偏偏是 FastGPT：定位、演进路线与选型对比

1.1 从轻量知识库到全流程平台，它到底解决了什么问题

早期 FastGPT 给我的印象就是一个知识库问答工具：上传 PDF、Word、Markdown，系统自动切分、向量化，然后让大模型基于这些资料回答。这个能力今天看起来稀松平常，但在当时已经解决了一个非常实际的问题——企业里的资料散落在文档、Wiki、聊天记录里，员工想找一个答案翻半天，客户想问一个问题没人接得住，而 FastGPT 提供了一条把“私有资料”变成“可问答资产”的路径。

后来它加了工作流编排，事情就开始不一样了。你可以把一次复杂的业务处理拆成多个节点：先调用模型做意图判断，再根据判断结果走不同的分支，有些节点取数据库数据，有些节点调外部 API，最后汇总成答案。这意味着 FastGPT 不再是“聊天机器人外壳”，而是能编排真实业务动作的 AI Agent 平台。再配合团队协作、API 集成、多应用管理这些企业功能，它已经从个人玩具长成了能上生产环境的半成品 PaaS。

1.2 和 Dify、Coze、RagFlow 放在一起，怎么选

每次有人问 FastGPT 和 Dify、Coze、RagFlow 有什么区别，我都会说：选型不能只看功能清单，要看你的落地场景。

• Coze 的强项是快速搭建面向 C 端的 Bot，插件生态丰富，但数据主权和私有化部署能力偏弱，适合个人玩和轻业务验证。
• Dify 是目前最接近“全家桶”的方案之一，RAG、Agent、工作流、模型管理都覆盖，适合需要一个通用 AI 应用平台的团队，文档和社区活跃度也高。
• RagFlow 走的是深度文档解析路线，对 PDF、表格、复杂排版的解析能力很强，适合把知识库质量当成核心诉求的场景，但 Agent 编排和外部系统集成相对薄弱。
• FastGPT 的特点是：知识库体验好、工作流编排细、中文语境下理解度高，而且部署形态灵活，从 docker-compose 到 Kubernetes 都有成熟方案，企业内部落地阻力小。

我的建议是，如果你要处理大量复杂格式文档，优先试 RagFlow；如果你需要一个 AI 应用平台但团队没有强开发能力，Dify 的体验更顺滑；如果你已经确定要建知识库并且希望后续能长成 Agent 平台，FastGPT 是性价比很高的选项。别迷信“哪个项目 star 多”，跑到生产环境接几天真实数据，答案自然出来。

2. RAG 知识库核心拆解：文档接入、向量化与召回参数

2.1 知识库建立的完整流程：清洗永远比切分重要

FastGPT 把知识库基础流程做成了开箱即用：新建知识库、上传文件、自动清洗、向量化、索引。但“能用”和“好用”之间，隔着一条数据清洗的鸿沟。

我建议先做数据预处理。理想情况是用 FastGPT 自带清洗逻辑，设置里可以配置文本清洗规则，比如去除空行、特殊符号、合并分段，这能处理掉大部分格式噪音。但更脏的数据——比如扫描版 PDF、带页眉页脚的导出文档、表格里的关键字段——必须提前人工或脚本处理一遍。我的习惯是：凡是上传前需要额外清洗的数据，统一转成 Markdown，把标题层级、表格、列表交给文本结构，这样切分之后语义完整度会高很多。

FastGPT 的切分策略也要认真对待。默认是固定长度切分加按标点符号断句，这个配置对英文和结构化文本还好，对中文长文档容易把一段完整的逻辑拦腰截断。我踩过的坑是：一份产品规格说明书，每个章节前半部分讲参数表格、后半部分讲使用限制，默认切分后模型经常只召回前半截，回答就出现只给参数、不给限制条件的情况。解决方案是把切分粒度调大，并开启“QA 拆分”模式，先让模型把长文生成成问答对再入库，召回的命中率明显上了一个台阶。

2.2 召回不是搜索：向量化、相似度与 TopK 要联动调

很多人把知识库问答理解为“搜索引擎给结果、大模型润色”，这是对 RAG 最大的误解。FastGPT 的召回环节本质上是把用户问题和文档都映射到向量空间，靠向量距离判断相关性，再结合关键词匹配做加权，最后返回 TopK 个片段给模型。

上线后最常遇到的问题是“明明库里有答案，模型就是答不上来”。排查顺序我很固定：先看召回，再看模型。

召回阶段，核心调整两个参数：相似度阈值和 TopK。阈值太高过滤掉有效片段，模型只能瞎编；阈值太低灌入大量无关片段，模型被噪声带偏。参考经验是把相似度阈值设置在 0.6 到 0.75 之间，TopK 设置 3 到 8 条，并开启“引用”展示，方便判断答案到底基于哪些片段。另外，FastGPT 支持同时设置向量检索和全文检索的权重，我的做法是：技术文档类库用向量检索为主，关键词权重设低；如果库里有大量固定术语、型号、人名，就必须提高关键词权重，不然向量召回很容易漏掉精确匹配的内容。

2.3 图片能不能进 RAG 知识库：多模态知识的落地真相

“RAG 知识库能存储图片吗”这个问题我几乎每周都遇到。直接给结论：FastGPT 知识库本身以文本片段为索引单元，但它可以处理带图片的内容，前提是你把图片以 Markdown 图片链接的形式嵌入文档，并在提问时把图片信息一并交给模型。

实际生产中常见的做法有两种。第一种是图片本身就是答案的一部分，比如操作截图、界面标注图，此时把图片和文字说明放在同一个片段里，模型回答时引用外部链接或 Base64 编码后的图片，用户能直接看到图。第二种是图片承载了关键信息，比如产品缺陷照片、流程示意图，这种要先做图文解析，把图片转成文本描述或结构化数据再入库，否则检索阶段根本找不到这张图。

一个真实的坑：早期我把一批接口文档的流程图直接以 PNG 插入知识库，用户问“参数传递顺序是什么”，模型答不出来，因为流程图的文字信息根本没有被提取。后来改成先把流程图转成文字描述、再和原图一起挂入片段，问题立刻解决。所以我的建议是：图片知识库最关键的不是“能不能存”，而是“能不能被文字索引”，不能索引的图片放进去就是信息孤岛。

3. AI Agent 工作流编排：从对话到可执行的业务流程

3.1 节点化编排的核心思路：把大模型当成一个会思考的中间件

FastGPT 的工作流编排，本质上是用可视化画布把一次 AI 任务的执行过程拆成若干节点。典型的节点有：用户输入、AI 对话、知识库检索、条件分支、代码执行、HTTP 请求、变量赋值、插件调用、结束回复。这套设计最大的价值是把“意图-动作-输出”链路显性化，让人能控制模型在每一步的行为，而不是靠一个 Prompt 赌运气。

我在设计工作流时的习惯是：先写业务流程，再画节点。比如做一个退货申请助手，流程是用户描述问题、判断是否为质量问题、查订单状态、给出退货方案、必要时转人工。对应到 FastGPT 节点就是五个：AI 对话节点做意图分类，知识库节点查询售后政策，HTTP 节点调用订单系统，条件分支节点决定走自动退款还是人工介入，最后汇总输出。这样做的好处是每个环节都能单独调试，哪个节点出问题一眼就能定位。

还有一个容易忽略的细节：AI 对话节点的 Prompt 要区分“系统指令”和“上下文数据”。FastGPT 允许在节点里指定用户输入、历史对话、知识库结果作为变量注入提示词，但注入顺序和格式会影响模型理解。我通常把系统指令写在最前，明确角色和输出格式，然后把知识库引用片段用标识符分隔，最后才是用户输入，三段之间用分隔符隔开，模型的表现稳定很多。

3.2 一个可复制的搭建案例：企业客服智能答疑 Agent

用一个我在生产环境实际跑通的案例来展示搭建过程。需求是：企业内部客服每天要回答大量关于报销流程、请假制度、办公设备申领的问题，80% 是重复问答，希望做一个自动答疑 Agent，答不上的转人工。

第一步，整理资料。我建了两个知识库，一个放制度文档，一个放历史客服问答记录。制度文档启用 QA 拆分，问答记录直接导入，让模型可以参考历史真实回答的语气和口径。

第二步，画工作流。入口是用户输入，第一层 AI 对话节点识别意图：报销、请假、设备、无关闲聊。报销和请假走知识库检索并回答；设备申领除了检索知识库，还接了一个 HTTP 节点，去查库存状态，有库存才给出申领成功提示；识别为闲聊则直接回复固定提示；识别为情绪激动或复杂问题，通过条件分支节点转给人工工单系统。

第三步，测试调优。我按 80 条历史对话做回放测试，发现两个问题：一是“报销流程”和“报销标准”经常被混答，原因是制度文档里这两个主题穿插在同一段落，切分后语义边界模糊，重新整理文档结构后解决；二是知识库回答偶尔出现官方文档没有的口径，我在 AI 对话节点的提示词里加了限定语“只能依据给定引用内容回答，引用不足时明确说不知道”，幻觉明显减少。

第四步，发布对接。应用发布后通过 API 接入企业微信机器人，用户在工作群里 @ 机器人就能提问。考虑到客服场景的合规要求，我开启了引用展示，模型回答后面会附上知识库原文链接，既方便用户核对，也给客服复核留了依据。

4. 云原生部署实战：资源规划、并发扩展与稳定性调优

4.1 组件构成与最小部署资源规划

FastGPT 部署起来不复杂，但依赖的组件不少。完整架构大致是：FastGPT 主服务（Node.js 应用）、MongoDB（存放应用数据、对话记录）、PostgreSQL（存放向量数据和索引）、向量插件（pgvector）、可选的文件存储对象存储、以及沙箱执行组件（用于工作流中代码节点）。如果是完整安装，还有一个 OneAPI 或者类似的模型网关层，用来统一管理各家模型 API。

最小部署建议是 4C8G 起步，跑通 demo 的时候 2C4G 也能凑合，但别指望稳定。我给一个相对充裕的资源参考：

部署方式上，个人试用直接用 docker-compose 最省事。国内网络环境下要特别注意镜像拉取问题，建议先配置镜像加速器，或者通过外部镜像仓库同步最近使用的几个基础镜像，能省很多时间。

4.2 从 docker-compose 到 Kubernetes：一步一步迁移扩容

如果你的 FastGPT 只是为了验证，docker-compose 撑住二三十个并发用户问题不大。但要放到生产环境，面对几十上百人的团队使用，我强烈建议迁移到 Kubernetes。

迁移的核心思路是“无状态服务上多副本，有状态服务单独管理”。FastGPT 主服务本身是无状态的，可以同时跑很多个副本，负载由 Ingress 均衡分发；真正需要谨慎对待的是 MongoDB 和 PostgreSQL，它们的数据不能丢，也不建议直接跑在临时容器里，必须挂持久化存储卷，生产环境至少开启副本集或高可用模式。

以下是迁移步骤的简化版本：

1. 将 docker-compose 中的环境变量整理为 ConfigMap，包括数据库连接串、模型接口地址、系统密钥等。
2. 为 PG 开启 pgvector 插件，确认向量表结构能够被新版本读取。
3. 将 FastGPT 主服务部署为 Deployment，配置 HPA 自动扩缩策略。
4. 将 MongoDB 和 PostgreSQL 迁到可挂载云盘的 StatefulSet，设置备份策略。
5. 挂好 Ingress，开启 HTTPS，并通过 ConfigMap 调整前端静态资源缓存策略。

这里我特别提醒一个细节：FastGPT 的前端和后端在 Docker 镜像里是打包在一起的，多副本部署时，修改系统配置类的环境变量必须保持一致，否则会出现两个副本行为不一致的问题。建议所有副本共用同一套 ConfigMap，不要为单独副本单独配环境变量。

4.3 “AI Agent 怎么扛并发”：水平扩展与数据库层优化

“AI Agent 怎么扛并发”是我上线后最关心的问题，FastGPT 的模型调用链路比普通 Web 应用长得多：用户请求进来，工作流跑几个节点，每个节点可能调一次模型 API、查一次向量库、写一次对话记录，整个链路可能持续十几秒甚至几分钟。如果系统设计不考虑并发，实际使用人多起来就会立刻崩。

我这里列几点真正有效的调优手段：

第一，应用层水平扩展。FastGPT 主服务多副本部署，通过负载均衡分发请求。注意工作流里的长时间请求要配置合理的超时时间，前端的请求超时一般设置 60 秒以上，否则关浏览器就断链。

第二，数据库连接池调优。MongoDB 和 PostgreSQL 的连接数是有限的，默认配置下几十个并发就可能把连接池打满。建议调大maxPoolSize，同时给数据库预留足够的文件句柄上限。

第三，模型接口并发控制。大多数模型 API 有 RPM/TPM 限制，FastGPT 在应用层可以配置模型调用并发和频率，批量任务建议启用请求队列，避免瞬时请求打爆模型服务商配额。

第四，会话状态与多副本冲突。FastGPT 的对话状态默认存数据库，多副本时同一个用户的连续对话可能被分发到不同副本，但状态是共享的，所以问题不大。需要注意是工作流执行过程中不要依赖单副本内存里的临时数据，所有中间结果尽量显式存储或传递。

第五，流式输出体验优化。FastGPT 支持流式响应，适合长答案场景，前端能边生成边渲染，用户感知的响应时间可以从十几秒缩短到两三秒，这也是提升并发承载体验的有效方式。

我实测过一组数据：4C8G 双副本加 4C8G 数据库，接入一个每分钟约 60 次问答请求的客服场景，单个请求的平均耗时在 3 到 5 秒，系统 CPU 峰值在 60% 左右，基本稳定。如果请求量再翻几倍，优先扩数据库规格，其次扩应用副本数，瓶颈往往先出现在数据库侧的连接和查询上。

5. 上线后最常踩的坑：问题现象与排查实录

5.1 检索结果不准，先查 embedding 和分段，而不是换模型

“知识库里明明有答案，模型就是回答不出来”是最常见的投诉。我的排查思路是：先看知识库有没有正确召回，再看模型有没有正确使用召回内容。

可以在应用调试面板里开启“引用展示”，直接看到模型是基于哪几条知识库片段回答的。如果引用的片段明显没包含正确答案，问题出在召回；如果引用了正确答案但模型答错，问题出在模型或提示词。

召回不准的常见原因有三个：分段太大导致向量语义被稀释、切分后关键信息被割裂、引入的新文档和旧文档内容冲突。处理手段分别是调小切分长度、用 QA 拆分模式重组片段、排查重复或冲突内容。如果换了大模型还是不准，问题大概率不在模型。

5.2 高并发下数据库连接数被打满

第一次遇到 MongoDB 报连接数不够的错，是在上线第二天。现象是：用户一多，日志里疯狂出现failed to connect，应用响应越来越慢，过一会儿整个服务不可用。

排查发现，FastGPT 应用实例的连接池配置过小，数据库默认最大连接数也不够支撑多实例同时建立连接。解决方案很简单：把应用实例的连接池调大，数据库侧最大连接数同步调高，同时在连接字符串里设置maxPoolSize。另外，给工作流里的高频查询加缓存，比如热门问题的知识库召回结果缓存 10 分钟，数据库压力降了一个量级。

5.3 多副本部署后，外部 API 调用出现重复提交

这个坑隐藏得很深。工作流里有一个 HTTP 节点，每次调用外部系统创建工单，结果发现用户在页面上点一次按钮，工单系统里生成了两条记录。原因是个别请求被负载均衡重发，或者用户在前端重复点击。

解决办法分两层：外部 API 侧做幂等处理，业务系统根据请求唯一 ID 去重；FastGPT 工作流里，在调用外部系统的 HTTP 节点前增加一个“检查是否已处理”的判断节点，通过查历史对话记录防止重复执行。作为一个通用原则，所有会让外部系统产生副作用的工作流节点，都必须考虑重入问题。

5.4 升级和迁移：备份比你想的更重要

FastGPT 版本迭代很快，社区也一直在更新，但升级前一定要三件事做齐全：备份 MongoDB、备份 PostgreSQL、备份环境变量和配置文件。不要只备份数据库，配置丢了重新填一遍也很痛苦。

我遇到过两次升级后向量库不兼容的报错，都是因为 PG 的 pgvector 插件版本和 FastGPT 版本要求不一致。升级前先看官方升级文档，确认镜像 tag 对应的数据库版本和插件版本，最好在测试环境完整跑一遍升级流程，再把数据同步过去。生产环境升级前建议先停服务、全量备份，再执行升级迁移，避免中途数据写入导致脏数据。

另外，如果沿用 docker-compose 部署，升级前一定要比对配置项的变化。FastGPT 新版本经常会增加或调整环境变量，直接沿用旧配置可能导致新功能不生效或启动异常，官方文档里的配置变更记录值得一读。

写在最后：一点个人体会

FastGPT 这两年的演进速度让我感受很深。它是一个典型的“由项目推着走”的开源产品：知识库解决的是“让模型有据可依”的基础问题，工作流解决的是“让模型可被执行”的工程问题，而云原生解决了“让应用可被规模化使用”的平台问题。这几件事层层递进，恰好对应了一个 AI 应用从 Demo 到上线的完整路径。

如果你正在用它，我的建议是：不要在 Demo 阶段停留太久，尽早把真实数据接进来，把工作流拆细，把部署环境从 docker-compose 迁到 Kubernetes，每一个步骤都会暴露文档里看不到的问题，而这些问题才是真正让你把 FastGPT 用明白的教材。最后再分享一个小技巧：日常维护时养成看日志的习惯，FastGPT 的日志里会记录每次请求的节点执行链，哪一步慢、哪一步报错，比你在界面上猜一百次要准得多。