这篇文章想聊一个很具体的场景用 AI Agent RAG 做一套类飞书文档的企业知识库让用户能基于内部文档完成向量检索和智能问答。它不是一个 Demo 级别的玩具项目而是从文档解析、切块入库、混合检索、Agent 编排、后端接口到前端交互的完整链路。如果你正在做企业知识库、内部智能助手或 AI 前端应用或者准备把这类项目写进简历这篇内容可以按落地顺序当参考地图用。我先把结论放在前面这类项目能不能在企业里真正用起来往往不取决于大模型本身有多强而取决于三条链路是否干净——数据链、检索链、交互链。数据链负责把文档变成可检索的结构化内容检索链负责在多种查询方式下都能召回正确片段交互链负责把结果以可接受的方式呈现给用户。前端在这里不是边缘角色而是决定“能不能用起来”的最后一公里。下面按实际开发顺序拆开讲。1. 类飞书知识库的 AI 问答到底难在哪1.1 它和普通智能客服的差别很多人第一次做知识库问答会下意识对标智能客服。其实两者差别很大。普通智能客服的问题集中在少量高频场景语料量小答案也相对固定。用户问“怎么申请假期”命中一篇制度文档基本上就能答。企业知识库不一样。文档是多作者、多格式、多版本、多权限的同一个术语在不同部门含义不同。一个员工问“培训费用怎么报销”可能同时命中财务制度、行政通知、团队 Wiki哪一份才是当前公司真实执行的标准不能只靠语义相似度来判断。另一个差别是权限隔离。飞书这类工具里文档按空间、部门、成员划分可见范围。检索阶段如果不过滤权限就会出现“推荐了用户本来没权限访问的文档片段”这种问题。轻则用户体验差重则信息泄露。所以做企业知识库第一件事不是调模型而是把数据和权限模型理清楚。1.2 全链路拆开看检索、编排、生成、前端一个完整的类飞书文档知识库问答系统我习惯拆成四条线数据线文档采集、格式解析、清洗、切块、嵌入、写入向量库。检索线意图识别、查询改写、向量检索、关键词检索、多路召回、重排。Agent 线判断当前问题是否需要查知识库需要的话调用检索工具把检索结果交给大模型生成回答。前端线会话界面、流式展示、引用定位、文档预览、上传进度、知识库管理页面。这四条线不是做完一条再测一条。我建议先用最简链路打通上传一份文档切块入库用一个固定的 RAG 接口返回答案前端先展示纯文本结果。等这条链路走通再去加混合检索、Agent 编排和复杂交互。否则很容易出现一个情况Embedding 模型换了一个又一个向量库调了三天但页面还没跑起来用户也不知道你到底做了什么。2. 先定技术底座组件选型与职责边界2.1 向量数据库与检索方案选型向量库存什么核心是三部分切块后的文本、Embedding 向量、文档元数据。元数据至少包括文档标题、文档 ID、切片 ID、所属空间、权限范围、上传时间。这些字段不只是展示用还是权限过滤和引用定位的基础。选向量库时不能只看相似度检索快不快还要看几个容易被忽略的点是否支持元数据过滤。否则每次检索都必须在代码里二次过滤性能差还容易漏。是否支持增量更新和删除。企业文档每天都会新增、修改、作废索引更新不了就是死库。有没有批量写入和重试机制。文档量大时逐条调用接口会非常慢。运维成本。集群部署、磁盘规划、监控告警是否可控。Embedding 模型同理。通用中文模型在日常场景下够用但如果你的文档里大量是代码、法律条款或医疗术语就要用真实切片做一次离线评测。评测指标不是“看着舒服”而是“给定一组真实问题能不能在 Top 5 内召回正确片段”。这类评测结果比模型榜单更有参考价值。2.2 混合检索为什么不能只靠向量只靠向量检索的问题做多了就会发现语义相近但关键词不同能召回精确的关键词比如工单号、合同编号、产品型号、人名反而容易漏。举例来说用户问“项目 HTB-2031 的验收标准是什么”如果索引里的切片内容是“该项目验收标准如下”语言模型会把“该项目”对应到错误的实体上或者根本没有针对编号做语义对齐。这时候 BM25 这类稀疏检索方法就有用了。所以现在 RAG 项目里常说的“向量混合检索加 BM25 多路召回”目的就是让语义检索和关键词检索互补向量负责语义近邻BM25 负责精确匹配。两者各自召回一批候选再通过重排或 RRF 合并。实现上有两条路一是自己同时维护向量索引和倒排索引查询时分别召回再融合二是选择已内置混合检索能力的数据库或框架减少自研成本。我的建议是先跑通后者等数据量和业务复杂度上来再评估是否需要自研重排服务。如果你不想从零造轮子也可以先用 Dify、RAGFlow 这类开源平台快速搭一套知识库做概念验证。但企业生产环境通常还是需要定制权限模型和前端交互纯平台方案可能会遇到扩展边界。2.3 前端和服务端的分工边界AI 前端不是普通管理后台。它要管会话、流式渲染、文档预览、引用跳转、上传进度、权限按钮显隐还要处理文档和切片的管理页面。如果前端直接读数据库或者自己拼检索逻辑后续权限调整和模型替换都会很痛苦。建议项目一开始就约定接口契约会话类创建会话、发送消息、接收流式回答。文档类上传文档、查询解析状态、删除文档。检索预览类搜索片段、获取引用原文、定位文档位置。管理类查看切片列表、调整文档可见范围、同步索引状态。前端只负责输入、展示、状态管理。要不要查知识库、查哪些范围、结果怎么生成全部交给后端。这样权限逻辑统一在后端模型可以随时换前端不会因为提示词调整而大改。3. 从文档到知识库数据清洗与切块策略3.1 企业文档的常见格式和解析坑类飞书文档的场景里输入格式比想象中杂。除了常见的 PDF、Word、Markdown还有导出的 HTML、表格、思维导图、幻灯片甚至截图里的文字。PDF 是最容易出问题的格式。有的是文字版可以直接抽有的是扫描件需要 OCR有的排版复杂表格被切断段落顺序被打乱。Word 文档则要小心文本框、批注、修订记录和页眉页脚。解析后最好统一转成带结构信息的文本比如标题层级、段落、表格行而不是把所有内容拼成一个长字符串。这里有个建议清洗阶段不要追求“所有格式都能解析”一步到位。先支持最常见的三种格式把链路跑通。其他格式可以在后台异步解析失败时不阻塞主流程。解析质量直接影响切块质量。一个表格被截成两半后面无论怎么切都很难检索到完整语义。3.2 切块策略固定长度、语义切块与父子块RAG 切块策略是影响召回效果的关键因素也是最值得做对比实验的地方。固定长度切块最简单按字符或 Token 数切重叠一部分。优点是实现稳定、可控缺点是没有语义边界一个段落很可能被切成两半一个问题要跨两个块才能找到答案。语义切块更好理解一些按标题、段落、列表项、表格边界切。先做文档结构解析再以结构为边界切分。这样每个块是一个相对完整的语义单元检索准确率通常会更高。实践中很常用的是“父子块”方案父块是较大语义单元比如整个小节子块是小片段。检索时命中子块但把父块作为上下文送给大模型。这样既保留了精确位置又让模型有足够的上下文理解语义。切块参数没有绝对标准但可以给一个起点。一般先试 256 到 512 个 token重叠 20 到 50 个 token然后用一组真实问题回测。如果答案缺失是因为片段太碎就调大如果命中片段包含太多无关内容就调小。注意切块策略的调优不要凭感觉。先把 20 条真实问题写下来每次调整后重新跑一遍记录命中片段和生成答案的变化。没有评测集的调参基本等于碰运气。3.3 元数据与权限隔离切块之后每一块都要带上元数据。最简单的元数据至少包含文档 ID 和标题切片 ID所属空间和部门可见范围或权限组文档链接或前端路由更新时间、版本号来源类型PDF、Word、Wiki 等这些字段的价值在检索阶段才体现出来。做权限过滤时可以直接在向量检索里带上元数据过滤条件只返回用户可见范围内的切片。前端拿到引用后也能直接拼接文档链接实现“点击引用跳转到原文”。如果你一开始没存权限字段后面再补权限隔离就要重新批量写入索引成本很高。企业知识库越早规划元数据后期越省事。如果业务中有大量“某个项目关联哪些文档”这类关系型查询未来可以引入知识图谱作为补充但初版优先把向量库、关键词索引和元数据做好。图谱不是起步阶段必须的东西。4. Agent 编排知识库如何被当作工具调用4.1 Agent、Tool、Skill 的关系先理清概念。RAG 解决的是“让模型基于外部资料回答”Agent 解决的是“根据用户需求决定调用什么工具、按什么顺序执行”。知识库本身可以是一个工具被 Agent 调用。Agent 的完整架构通常包括意图识别、规划、工具调用、记忆管理和最终生成。在这个项目里工具集至少有两个一个是知识库检索工具负责查文档片段另一个可能是外部 API比如查库存、查工单状态。Agent 根据用户问题决定是否调用某个工具再根据工具返回结果生成答案。这里引出一个很多人纠结的问题运用知识库应该用 Skill 还是 Tool。简单理解Tool 是能力单元比如“检索知识库”“调用审批 API”Skill 更像是把多个 Tool 和提示词组合成一个可复用的技能包。如果只是让用户问文档直接用 Tool 就够了如果想处理“查文档→综合分析→输出报告”这样的复合任务才值得封装成 Skill。不要把概念搞复杂。早期实现里知识库调一次、模型生成一次就够用了。4.2 用 Agent 还是把 RAG 写死初版建议把 RAG 链路写实不要急着上复杂 Agent。原因很简单Agent 需要依赖模型的工具调用能力模型如果选得不好光工具调用就经常出错。我先说一个判断标准如果用户的绝大多数问题是“查一下某份文档里怎么写的”写死 RAG 流程会更稳定。如果问题需要在多个工具之间切换或者需要先查询、再计算、再汇总那才需要 Agent 编排。等写死版本跑顺了再往 Agent 方向演进。演进路径通常是固定流程 RAG查询→检索→生成。条件判断先做意图识别再决定要不要检索。多工具路由问题命中某些业务关键词时调用对应工具。Agentic RAG让模型自己决定调用几次检索、要不要查询改写、要不要二次检索。每一步都保持上一个版本的可用性不要一步跳到最终形态。4.3 多轮问答和上下文管理多轮问答是知识库项目最容易翻车的地方。用户先问“公司年假规则”再问“那婚假呢”如果系统只拿第二句去检索结果大概率不准。处理思路是维护一个会话上下文列表。每次用户提问前先把最近的对话记录交给模型做查询改写生成一个完整的独立问题再拿改写后的 query 去检索。例如“那婚假呢”改写成“公司婚假的天数和申请条件是什么”。上下文列表要注意长度控制。对话超过一定轮数要么截断要么让模型做摘要压缩。否则一次查询的历史消息太多既增加模型耗时也稀释检索相关性。前端在这个环节要配合后端把 session_id 传好并且允许用户清空会话。企业用户对聊天记录的理解更像“一个问答任务”而不是永久内存这个交互细节值得在意。5. 智能问答链路从查询到生成5.1 意图识别与查询改写查询进入系统后第一步不是直接检索而是理解查询本身。可以简单分成三类一是知识库查询比如“报销流程是什么”二是闲聊或无关问题比如“你会做什么”三是需要调用其他工具的问题比如“帮我看看工单状态”。对第一类问题走 RAG对第二类直接给提示话术对第三类走工具路由。查询改写也很关键。用户口语化、代词多、指代不清直接用原文检索效果差。让大模型基于历史对话生成一个适合检索的独立问题是成本很低但收益明显的优化。注意改写不是让模型直接回答而是生成检索条件。Prompt 要明确只输出改写后的查询不要输出答案。5.2 多路召回与重排改写完成后进入检索阶段。我比较推荐的做法是同时发起向量检索和 BM25 关键词检索各自取 Top N合并去重后进入重排或 RRF 融合。如果已经有重排模型就做重排。重排模型会基于查询和候选片段的真实关联程度重新打分效果通常比 RRF 好但需要额外部署和推理资源。如果前期不想引入重排服务RRF 是简单有效的替代。召回数量也有讲究。不要把 Top 5 固定死。如果文档量大、问题需要多个片段拼答案可以取 Top 10 到 Top 20 做重排重排后再取 Top 5 送给大模型。检索阶段宁可多召回也别漏答案生成阶段再控制输入长度。5.3 生成答案与引用溯源生成阶段要重点考虑两件事答案格式和引用来源。企业场景下答案格式建议统一。比如按“结论 依据 引用文档”的结构返回。前端可以把它渲染成清晰的卡片。“无引用不回答”是知识库问答比较稳妥的原则如果检索结果不足以支撑答案就明确告诉用户“知识库里没有找到相关内容”而不是让模型硬编。引用溯源要靠元数据实现。每个切片都带文档 ID、切片 ID、原文链接。模型生成时我们可以要求它在依据位置标注引用索引前端拿到引用索引后再渲染成可点击的引用链接。这一步是从“看起来能用”到“真正敢用”的分水岭。后端返回引用信息时结构可以设计成下面这样方便前端渲染{ answer: 根据公司制度报销申请应在费用发生后 30 天内提交。, citations: [ { index: 1, doc_id: doc_2024_001, doc_title: 财务报销管理制度, chunk_id: chunk_1024, link: /docs/doc_2024_001#chunk_1024 } ] }这里只是示例结构实际字段名以你的后端契约为准但“可定位到原文”这个原则不建议省略。6. 前端接入流式问答、文档预览与交互6.1 流式输出和中断处理知识库问答的等待时间通常比普通接口长。如果等全部生成完再渲染用户会怀疑系统卡死了。所以前端必须做流式输出。常见的做法是服务端通过 SSE 逐段返回生成的 token前端在收到内容时追加渲染。这里要处理好三个状态等待检索阶段、生成中、完成。检索阶段可以显示“正在检索知识库”生成中逐字展示完成后再加载引用来源。中断处理也重要。用户可能随时停止生成。前端需要有一个“停止”按钮后端正则终止本次生成并释放资源。如果只顾着展示流式内容而忘了中断高并发时资源会被白白耗掉。我见过不少项目把精力花在让输出更流畅上却忽略了生成过程中用户已经在等一个超时错误。流式接口要设置合理的超时和重试策略不要让前端一直转圈。6.2 引用定位与文档预览引用不能只显示文字。企业用户看到答案后第一反应是点开原文确认。前端要把引用做成可点击的锚点点击后跳转到文档预览页并定位到具体段落。实现上后端返回的引用对象至少包含文档 ID、切片 ID、高亮位置。前端在文档预览里根据切片 ID 找到对应段落滚动到位置并高亮。如果文档本身无法直接在网页预览比如 PDF最好集成在线预览组件把 PDF 渲染在页面里再定位到对应页。不要只在答案下方放一个文件链接这样体验差很远。另外前端还需要处理文档版本变化。同一个文档被更新后旧切片可能已经失效。页面里要展示文档更新时间最好在引用卡片上标注“该文档已更新答案可能基于旧版本”。6.3 大文件上传与权限交互企业知识库里的文档可能很大几十 MB 甚至上百 MB。前端用普通 fetch 一次性上传很容易失败且没有进度反馈。可以走前端 Worker 或切片上传方案文件在前端按大小切分逐片上传后端合并。切片上传的好处是失败时只重传失败的分片。上传后用户更关心同步状态。前端要轮询或通过 WebSocket 接收解析进度上传完成、解析中、切块中、索引完成、解析失败。失败时要展示失败原因比如“PDF 为扫描件且未配置 OCR”。权限交互虽然主要靠后端控制但前端要按用户角色和能力渲染界面。没有权限的文档不要出现在搜索结果里也不要显示上传按钮。前端不能依赖“隐藏界面”来防越权但好的界面设计可以避免大部分误操作。7. 企业级落地部署、并发、日志与监控7.1 部署形态与资源评估先给出一个常见的最小部署形态前端静态站点 后端 API 服务 向量数据库 对象存储 大模型服务。前端通常打包成静态资源部署到 Nginx 或对象存储 CDN后端负责解析、索引、检索、编排和流式输出。资源估算要从三个维度看文档总量、并发用户数、大模型调用频次。文档总量决定向量库大小和 Embedding 计算量并发用户数决定 API 服务和向量检索是否需要横向扩展大模型调用频次直接决定 GPU 资源或外部 API 费用。Embedding 和重排模型如果本地部署需要 GPU。轻量场景下也可以只跑一个量化模型但要注意效果下降。这里给的是通用排查顺序实际参数要以你的环境为准。7.2 并发、任务队列与失败重试批量文档处理不能在前台请求里同步做。导入 100 份 PDF解析、切块、Embedding、写入向量库每一步都可能失败。要引入任务队列把文档任务分成多个阶段每个阶段可以失败重试。任务队列至少记录这几类信息任务 ID、文档 ID、当前阶段、重试次数、错误信息、重试时间。失败超过阈值后进入死信队列等人工处理。查询接口同样要注意并发。如果所有请求都直达大模型模型推理服务很容易被打满。建议加一层限流或排队机制。可以按用户维度限制并发也可以按全局 QPS 限制。不要等到生产环境告警了才想起限流。7.3 日志审计与效果评估企业知识库涉及内部资料日志和审计是最基本的要求。每个提问、每次检索、最终生成结果都要记录。至少保留用户 ID、会话 ID、问题文本、检索命中的文档列表、模型输出和耗时。效果评估不是上线之后再说。最好从项目开始就准备一组评测问题集分三类事实型问题、综合型问题、不可答问题。每次调完切块参数、换完 Embedding 模型、改完检索逻辑都用同一组问题集跑一遍对比命中率和回答质量。没有评测集的调优基本等于凭感觉碰运气。另外企业知识库不是一次建好就结束。文档会更新权限会变化旧索引要同步。建议定期做一次索引对账把失效文档从向量库里清理掉。最后留几个我自己排查时会优先看的点先看文档解析和切块是否正常再看检索召回片段是否包含答案接着看生成阶段是否拿全了上下文最后才是看前端流式和引用显示。很多问题看起来像模型不行、前端出错实际卡在数据清洗和切块这一层。