企业级 RAG 项目全流程复盘本文从项目目标、数据准备、知识入库、在线问答、Prompt 编排、质量评测到部署运维完整梳理 此系统 的建设与运行流程。文档重点不是罗列框架而是说明每一层解决的问题、模块之间如何协作以及关键技术决策背后的取舍。1. 项目概述该系统 是一套基于LangChain Milvus Hybrid Search FastAPI构建的企业级多场景知识问答平台。项目将 FAQ 标准问答、非结构化文档检索、表格资料检索、知识库版本治理、数据权限隔离、Prompt 路由、流式回答和质量回归整合在一条可观测、可验收的工程链路中。我在设计这套系统时没有把目标限定为“把文档塞进向量库后调用一次大模型”而是围绕企业知识问答的四个核心问题展开答案是否有依据生成内容必须来自当前知识库版本并能够回溯到具体来源。检索是否稳定既要覆盖语义表达差异也要保留关键词、编号、术语等精确信号。数据是否串域场景、租户、数据集、可见范围和角色权限必须贯穿入库与查询。版本是否可治理新资料不能直接污染线上索引需要经过构建、质检、评测、激活和回滚。2. 建设目标与系统边界2.1 核心能力能力实现方式多场景接入scenario.toml faq.csv data/配置化注册FAQ 标准问答精确命中或高置信召回后直接返回标准答案文档问答Dense Sparse 混合召回、CrossEncoder 重排、上下文构建、LLM 生成多格式资料Markdown、TXT、PDF、DOCX、PPTX、CSV、XLS/XLSX表格检索工作表和行级 Document保留表头、行号与单元格键值扫描件治理离线 OCR、人工复核、资料提升、重新构建版本多轮对话MySQL 持久化历史、按需查询改写、后台会话摘要Prompt 路由按问题类别与意图选择 Prompt Profile数据隔离scenario / tenant / dataset / visibility / roles联合过滤版本治理STAGED → 质量门禁 → ACTIVE支持对比与回滚可观测性Trace、阶段耗时、首 Token、召回结果、缓存命中、置信度质量闭环入库质检、离线评测、Gate、反馈与 Bad Case 回归2.2 技术边界V1 主链路聚焦企业知识库 RAG不引入任务规划、工具调用和跨系统 Agent 协作。这样做的目的是先把“资料进入系统以后如何被稳定、合规地检索和回答”做成闭环。知识检索与业务状态采用分层存储Milvus承担 Dense Vector、BM25 Sparse、Hybrid Search 和 metadata 过滤是知识数据面。MySQL保存聊天历史、摘要、反馈、知识库版本、激活记录、Manifest 和缓存 namespace是治理控制面。Redis缓存 query embedding 和带完整业务边界的检索候选不缓存普通 LLM 最终答案。MinIO etcd作为 Milvus 的对象存储和元数据依赖。3. 总体架构3.1 分层职责层级主要目录职责启动层app.py预检、Schema 初始化、active 版本检查、模型和检索栈预热、路由注册API 层core/api/参数校验、限流、WebSocket 事件转发、管理接口应用层core/application/提供无状态Service连接 API 与 PipelinePipeline 层core/pipeline/查询路由、检索准备、召回、上下文、生成、引用、置信度与收口意图层core/intent/确定性规则、BERT 模型治理、场景与 source 判断检索层core/retrieval/检索计划、Milvus Hybrid Store、过滤、合并和重排Prompt 层core/prompts/Prompt Profile 定义、优先级选择与场景变量注入入库层core/indexing/Loader、规范化、切分、Manifest、FAQ/文档写入和 OCR 治理治理层core/governance/知识库版本、active 指针、数据域和 chunk 版本状态层core/memory/会话历史、摘要和用户反馈缓存层core/cache/L1 namespace 快照、Redis 业务缓存、MySQL epoch 治理质量层core/quality/、scripts/quality/入库质量、检索评测、性能基线与门禁4. 项目从 0 到 1 的建设流程4.1 第一步定义业务场景而不是先写检索代码每个业务场景由独立配置包描述核心内容包括scenario_id、展示名称、行业和业务说明FAQ 与文档 Milvus Collection合法source及其展示标签source 关键词模式标准问题、业务资料目录与人工支持入口场景级 Prompt 变量。这样的设计把“业务知识”与“RAG 引擎”分离。新增场景时主要工作是补充场景配置、FAQ、资料和评测集而不是修改问答主链路。场景接入遵循以下顺序明确业务边界 → 定义 source 分类 → 整理标准 FAQ → 准备结构化与非结构化资料 → 配置场景描述及支持入口 → 建立该场景的正向、边界和回归问题集4.2 第二步建立统一的资料元数据契约入库前先统一 metadata保证同一条数据可以被版本、权限和来源共同约束。核心字段包括scenario_id 业务场景 source 业务分类 source_type faq / doc tenant_id 租户 dataset_id 数据集 visibility 可见级别 allowed_roles 允许访问的角色 kb_version 知识库版本 document_id 文档标识 parent_id 父块标识 chunk_id 子块标识 chunk_schema 切分规则版本 embedding_model 向量模型版本这组字段不是只用于页面展示而是实际参与 Milvus 查询过滤、缓存 Key 生成、版本切换和来源引用。权限边界只有贯穿入库、检索、缓存和响应四个环节才是真正的数据隔离。4.3 第三步构建离线知识入库链路知识库构建入口是scripts/initial_version.py。它完成的不是简单的“文件向量化”而是一次可追溯、可验收、可回滚的知识库版本构建。为避免部分 Markdown 工具无法解析 Mermaid这里使用普通文本展示完整主线1. 解析场景和参数初始化 MySQL Schema → 2. 按需重置 Milvus Collection → 3. 创建或复用目标知识库版本 → 4. 解析跨版本增量基准 → 5. FAQ 快照式全量入库 → 6. 文档加载、切分及增量入库 → 7. 生成质量报告通过门禁后按需激活 → 8. 输出构建摘要8 个阶段的具体职责解析场景和初始化 MySQL读取--scenario、数据目录、FAQ 路径、版本策略、权限范围和质量阈值解析场景的 FAQ/Doc Collection、valid_sources和默认资料路径检查冲突参数统一创建或确认版本表、active 指针、激活流水、Chunk 版本索引、Manifest、缓存命名空间、反馈和会话表。这个阶段只确保表结构存在不会清空业务数据。按需重置 Milvus Collection默认保留现有 Collection。只有向量维度、BM25、稀疏向量字段等 Schema 不兼容时才使用--reset-collections。脚本负责删除当前场景的 FAQ/Doc Collection后续 Store 初始化和首次写入时按照新 Schema 创建。因为旧向量已经删除所以该选项不能和跨版本增量同时使用。创建或复用目标版本--new-version创建新的 STAGED 候选版本--kb-version用于复用指定版本并重试。版本记录包含kb_version、单调递增的version_seq、Collection 名称、模型版本、Chunk Schema 版本和入库统计。正式发布应显式使用--new-version否则当 active 已存在时当前实现可能复用 active 版本。解析增量基准--force表示所有文档重新加载、切分和向量化--incremental-from active或显式历史版本表示跨版本增量。脚本验证基准存在且不同于目标版本并将基准版本写入目标版本统计。逐文件是否复用在第 6 阶段判断。FAQ 快照式入库FAQ 不做跨版本引用复用。脚本读取 CSV兼容“问题/答案”和question/answer列跳过空问题或空答案规范化 source生成稳定 FAQ ID补齐场景、版本和数据权限 metadata再写入 FAQ Collection。在线 FAQ 检索按kb_version精确过滤。文档增量入库按data_root/source_data/遍历文件执行 Loader 解析、metadata 规范化、Parent-Child 切分、Embedding、Milvus 写入并同步更新 MySQL ChunkVersionIndex 和 Manifest。文件可能进入“目标版本未变化直接跳过”“跨版本未变化引用旧 Chunk”“新增或变化后重新向量化”三种分支基准版本中已删除的文件通过valid_to_seq从新版本开始失效而不是物理删除。质量报告、门禁和激活重新对候选资料执行一次只读解析与切分检查不支持文件、解析失败、空文件、OCR/图片风险、低质量或重复 Chunk、FAQ 空值与重复、非法 source、FAQ/正文冲突以及模型版本字段。门禁失败时报告落盘、进程非零退出、目标版本不激活门禁通过并指定--activate时事务切换 active 指针、记录激活流水、推进cache_epoch并清理 L1 缓存。输出构建摘要输出目标版本、FAQ 数量、文档 Chunk 总数、是否激活、增量基准和质量报告路径。增量模式中的文档总数包含“重新写入 引用复用”并不等于本次新增的 Milvus 行数。正式构建建议始终先创建 STAGED 版本质量检查通过后再激活这样构建期间线上请求仍然读取旧 active 版本。文档加载默认使用 native loaderMarkdown/TXT按 UTF-8 文本加载PDF通过 PyMuPDF 读取文本层DOCX通过 python-docx 提取段落与表格PPTX通过 python-pptx 提取页面文本CSV/Excel始终走项目内表格 Loader按行构造 Document复杂 PDF/DOCX/PPTX/HTML可切换到 Docling 增强解析。表格资料不会简单拼成一大段文本而是保留sheet_name、行号、表头与“字段值”的单元格结构。这样既便于检索也能在回答中精确引用某一行。扫描件不直接静默进入 active 知识库。系统先通过 PaddleOCR PyMuPDF 输出候选 Markdown 和置信度报告经人工复核后再将资料提升到正式目录最后走正常的版本构建与质量门禁。文档切分切分采用 Parent-Child 思路Parent Chunk 保留较完整的业务语义Child Chunk 控制向量检索粒度检索阶段用较小块提高命中率构建上下文时通过父子关系恢复更完整的信息chunk_schema进入版本和缓存边界防止切分策略变化后误用旧结果。增量构建文档 Manifest 保存场景、source、绝对文件路径、文件指纹、目标版本、对应的chunk_ids、Embedding 模型版本和 Chunk Schema 版本。新版本构建时未变化文件复用基准版本记录避免重复解析和 embedding新增或变化文件重新生成 chunk已删除文件标记为过期FAQ 每次全量构建确保标准口径清晰可控最终形成一个独立的 STAGED 版本不直接影响线上请求。文档版本不是在查询时把多个kb_version的数据临时拼接起来而是使用单调递增的version_seq解释 Chunk 有效期valid_from_seq 当前查询版本序号并且valid_to_seq 0 或 valid_to_seq 当前查询版本序号valid_to_seq0表示目前没有失效上限。文件修改或删除后旧 Chunk 的valid_to_seq会被设置为新版本序号因此旧版本仍可查询新版本不再可见。入库质量与失败行为质量报告会记录文件扫描数、成功加载数、不支持文件、解析失败文件、空文件、表格文件、OCR/图片风险、各 source 的 Chunk 数、低质量 Chunk、FAQ 质量、FAQ/正文冲突和本次实际写入统计。默认门禁采用严格策略。只要出现超出阈值的问题构建脚本就会将失败原因写入质量报告保存报告到reports/ingestion/scenario_id/以非零退出码结束不激活目标版本保持原 active 版本继续服务。文档加载、向量写入等阶段如果直接抛出异常脚本同样会中止。只要本次目标是新建 STAGED 版本就不会自动切换线上 active 指针可以修复资料或依赖后使用原--kb-version重试。推荐构建命令首次全量构建并激活python scripts/initial_version.py --scenario enterprise_knowledge --new-version --force --quality-gate --activate --description initial full build日常增量构建并激活python scripts/initial_version.py --scenario enterprise_knowledge --new-version --incremental-from active --quality-gate --activate --description incremental build from active只构建 STAGED 版本进行预演不切换线上版本python scripts/initial_version.py --scenario enterprise_knowledge --new-version --force --description staged validation buildSchema 变更后重建 Collectionpython scripts/initial_version.py --scenario enterprise_knowledge --new-version --force --reset-collections --quality-gate --activate --description rebuild after schema migration4.4 第四步建立版本发布机制知识库版本采用状态化发布资料变更 → 创建 STAGED 版本 → 入库质量检查 → base/candidate 召回对比 → 离线回归评测 → 激活为 ACTIVE → 线上观察 → 必要时回滚到上一版本激活版本时系统在同一事务中更新 active 指针、写入激活流水并推进场景cache_epoch。因此版本切换不需要扫描删除全部 Redis Key新请求会自然使用新的缓存世代旧 Key 按 TTL 过期。5. 服务启动流程app.py保持为薄入口。FastAPI 接收流量前依次完成校验 LLM Key、Milvus、MySQL、本地模型、场景配置等运行环境初始化 MySQL 运行时 Schema校验场景是否存在 active 知识库版本预热 BERT 意图决策组件后台探测 LLM 供应商连通性预热 BGE Embedding、Reranker 和 Milvus Collection预热通过后再开放 API。我没有为关键依赖设计隐藏降级路径。数据库、检索模型或 active 版本缺失时直接启动失败比“服务看似可用、实际悄悄降低质量”更容易排查也更符合生产环境的可预期性要求。6. 单次在线问答的八阶段 Pipeline这套在线主链路是带分支和提前结束能力的 Pipeline而不是固定的线性 Chain。标准问题可以走快速路径越界问题可以立即拦截证据不足时也不会强行调用大模型。Stage 0创建请求上下文将一次请求所需的信息集中到RAGQueryContext原始问题、会话 ID、Trace ID场景配置与 active 知识库版本source 过滤条件tenant、dataset、visibility、user roles阶段耗时、缓存事件、召回结果、答案片段和置信度状态。请求级状态全部放在 Context 中Service本身保持无状态便于进程内复用和并发请求隔离。Stage 1低成本查询路由先判断下一步该做什么顺序是校验用户指定的source_filter识别问候、转人工、明显越界等确定性意图执行场景边界和 source 边界检查对“短、完整、像标准问法”的问题尝试 FAQ 精确匹配以上均未命中时进入完整检索。路由结果分为route含义是否调用 LLMdirect_answer问候、越界、转人工、边界阻断否faq_exact与标准 FAQ 问题完全一致否retrieval需要意图识别、召回和 生成视后续结果而定FAQ 快速路径只允许标准问题精确命中不使用相似分数直接作答。原因是此时还没有完成完整意图判断过早使用语义相似度直出容易将知识咨询误判成标准 FAQ。Stage 2检索准备统一生成下游参数包包含读取历史消息与会话摘要识别 FAQ、知识咨询、追问等意图自动推断 source或校验前端指定的 source对依赖上文的追问执行查询改写生成RetrievalPlan生成查询变体选择回答所需的 Prompt Profile。检索参数不是全局固定值。RetrievalPlan会根据问题长度、意图、风险类别、规则分数和表格特征动态调整是否执行 FAQ 或文档召回FAQ/Doc 的top_k是否启用 RerankFAQ 直出阈值最终上下文数量。Stage 3FAQ 检索与标准直出FAQ 检索支持多个 query variants并带上知识库版本、DataScope 和 source 过滤条件。结果先去重、再统一重排。这里与 Stage 1 的区别是Stage 1 是标准问题精确匹配目的是降低首 Token 延迟Stage 3 已完成意图识别和检索计划可以在安全阈值内进行高置信 FAQ 直出未达到阈值时保留 FAQ 候选继续文档检索而不是丢弃已有证据。如果 Stage 1 已经探测过原始问题但未精确命中Stage 3 会复用该候选只查询新增变体避免对同一个问题重复访问 Milvus。Stage 4文档混合检索文档召回在 Milvus 中同时使用Dense Vector覆盖同义表达、自然语言改写和语义相关性BM25 Sparse保留产品名、条款号、金额、缩写、设备编号等精确词信号Hybrid Fusion合并两路结果CrossEncoder Rerank对合并候选做精排。多查询变体的结果以文档标识合并避免同一 chunk 重复占据上下文窗口。所有查询都附带scenario_id kb_version DataScope source过滤确保召回结果属于当前业务与权限域。Stage 5上下文构建与信息充分性判断负责把候选结果转换为可控的 LLM 证据合并 FAQ 与文档命中按文档/chunk 标识去重根据 RetrievalPlan 选择上下文数量表格类问题优先保留表格行对超长内容截断控制 Token 成本为每段上下文加入来源编号和必要 metadata记录 top score、来源数量和上下文数量。随后计算生成前的 evidence confidence。没有有效文档、最高召回分不足、边界冲突或证据覆盖不足时链路直接返回“信息不足 人工支持入口”不让 LLM 根据常识补答案。Stage 6Prompt 组装、流式生成与生成后核验有足够证据时Pipeline 将 Prompt Profile、历史、当前问题和编号化上下文组装为最终输入并通过 LLM 流式接口逐 Token 产出答案。模型生成结束后执行两层后处理引用增强检查答案是否包含来源编号如果模型漏写则追加可见的参考来源。表格问题还会补充行级明细。答案核验检查引用覆盖、引用编号合法性、回答与上下文的词项重合及关键主张支撑度形成 generation confidence。最终answer_confidence由生成前证据置信度与生成后核验结果共同决定。引用补齐只解决展示完整性不会被当作事实正确性的证明。Stage 7统一收口不论是直答、FAQ 直出、信息不足还是 LLM 生成最终都进入统一出口保存完整问答历史汇总来源、意图、路由、检索计划、缓存命中和阶段耗时写入 Trace返回end事件异常则转为用户可读的error事件。统一出口避免不同分支出现“页面显示成功但没有历史”“FAQ 直出缺少 Trace”等不一致问题。7. Prompt 工程设计Prompt 不是链路末尾的一段固定字符串而是检索准备阶段产生的可追踪配置对象。PromptProfile包含Profile 名称System PromptUser Prompt 模板输出格式要求场景变量。选择优先级是风险类别 Prompt 意图 Prompt 默认安全 Prompt7.1 意图模板FAQ、普通知识问答和多轮追问分别使用不同模板。风险模板优先于意图模板例如一个“预算能否绕过审批”的问题即使意图属于知识咨询也必须优先使用pricing_guard。7.2 场景变量注入同一个 Prompt Profile 会注入当前场景的assistant_name、business_domain和support_contact。这使 Prompt 模板可以跨场景复用同时保留行业口径和人工升级入口。8. WebSocket 流式事件协议在线问答统一走/api/stream。后端将一次请求拆为以下事件事件用途start返回 session、trace、场景和知识库版本status告知前端当前处于路由、检索或生成阶段token增量返回 LLM 文本或补充引用end返回最终答案、来源、意图、检索诊断、耗时和置信度error返回可恢复的错误信息与 trace_idService.stream_query()是同步生成器内部包含 Milvus gRPC、本地 Rerank 和 LLM 流式读取等阻塞操作FastAPI WebSocket 是异步接口。API 层通过asyncio.thread()在线程池推进生成器再由事件循环负责send_json()从而避免单个请求阻塞其他连接。9. 缓存设计V1 的三级缓存是“业务缓存 namespace 治理”不是三份相同数据层级内容作用L1 进程内短 TTLcache epoch 快照减少频繁读取 MySQL namespaceL2 Redisquery embedding、FAQ/Doc 检索候选复用热点计算和召回结果L3 MySQLscenario/tenant/dataset 对应的 cache epoch控制版本失效边界检索缓存 Key 不只包含问题文本还包含scenario tenant dataset visibility roles kb_version cache_epoch source_filter query_variants top_k rerank embedding/reranker/chunk_schema version系统明确不缓存普通 LLM 最终答案。同一个问题可能因为版本、权限、Prompt Profile 和会话历史不同而得到不同回答直接复用整段答案会放大过期知识和越权泄露风险。10. 多轮记忆与反馈闭环MySQL 中的聊天历史用于两个目的页面恢复历史问答判断当前问题是否为依赖上文的追问并在需要时改写为独立查询。生成完成后API 异步调度会话摘要刷新不阻塞用户看到最终答案。摘要和最近消息共同参与后续追问理解避免无限拼接全部历史。用户点赞/点踩和备注通过反馈接口写入 MySQL。低质量答案进入 Bad Case 流程线上反馈 / 离线评测失败 → 导出失败样本 → 人工复核 expected 字段 → 加入 eval_sets → 修复资料、检索规则或 Prompt → 重跑 Evaluation → Gate 通过后发布11. 质量保障体系11.1 入库质量每次版本构建都会生成质量报告重点检查文档是否为空、过短或解析失败Chunk 长度、重复率和低质量比例FAQ 与正文是否存在口径冲突表格是否按行保留结构图片型文档和 OCR 风险实际写入 FAQ 数和文档 Chunk 数Manifest 与当前版本是否一致。Quality Gate 失败时目标版本保持 STAGED不会更新 active 指针。11.2 离线评测主评测指标包括指标说明RecallK目标证据是否进入前 K 个召回结果MRR第一条正确证据的排名是否靠前Hit Type AccuracyFAQ 直出、文档 RAG、边界拦截是否符合预期Source Inference Accuracy自动 source 推断是否准确Prompt Profile Accuracy风险与意图模板是否选择正确Scenario Isolation Accuracy是否出现跨场景召回Keyword Coverage回答是否覆盖业务关键点Error Rate链路异常比例LatencyFAQ、检索、首 Token 和总耗时RAGAS 可作为faithfulness、answer_relevancy等语义指标的补充但不替代确定性的工程 Gate。11.3 测试分层单元测试 → 意图、边界、检索计划、缓存 Key、Prompt、置信度 集成测试 → MySQL Store、Milvus 适配、知识库版本、入库契约 离线回归 → 多场景、表格、负样本、多轮追问、业务深度 接口冒烟 → HTTP、WebSocket、管理接口、页面资源 发布验收 → Guardrail 文档一致性 全量测试 Docker 健康检查12. 部署与运行12.1 Docker Compose 服务生产化演示环境由以下服务组成apiFastAPI、静态前端、RAG Pipelinemysql历史、反馈和治理元数据redisEmbedding 与检索候选缓存milvus混合向量检索etcdMilvus metadataminioMilvus object storage。13. 关键设计取舍13.1 为什么采用 Milvus 内置 BM25Dense、Sparse、Hybrid Search、版本过滤和权限过滤统一在 Milvus 内完成避免维护本地 BM25 或第二套索引系统。langchain-milvus提供 VectorStore 抽象PyMilvus 适配层只负责数据库、连接别名和 BM25 Function 等底层差异不进入业务编排。13.2 为什么 FAQ 与文档分开FAQ 是标准口径适合高置信直接返回文档是解释依据适合复杂问题和组合问题。两者混在同一个召回池中会导致长文档稀释标准答案或单条 FAQ 过度简化复杂业务问题。13.3 为什么 Prompt 路由必须可测费用、合同、隐私、安全和理赔问题的回答边界不同。如果完全交由模型自由决定表达方式很难保证关键审批和禁止项稳定出现。Prompt Profile 将业务风险变成显式、可追踪、可回归的工程配置。13.4 为什么不做无依据降级当 Milvus、MySQL、本地模型或 active 版本不可用时系统直接失败并返回 trace而不是绕过知识库让模型自由回答。对企业知识平台而言“明确不可用”比“无证据但看起来能回答”更安全。13.5 为什么不缓存最终答案缓存 query embedding 和检索候选能够减少主要重复计算同时仍保留每次请求的权限校验、Prompt 选择、上下文构建和生成后核验。最终答案缓存只有在真实 Trace 证明生成成本是主要瓶颈并且能将版本、权限、会话与模型参数完整纳入 Key 后才值得引入。14. 一次完整发布的操作清单[业务] 明确场景、source、FAQ、文档和边界问题[数据] 清洗资料处理表格与扫描件补齐 metadata[构建] 创建 STAGED 版本执行 FAQ 与文档入库[质检] 检查解析、Chunk、冲突、OCR 和写入统计[对比] 比较 base/candidate 的召回结果[回归] 运行多场景、边界、表格和多轮评测[门禁] 检查 RecallK、MRR、隔离率、Prompt 和性能指标[发布] 激活新版本推进 cache epoch[验收] 执行 API、WebSocket、页面与 Docker 冒烟[观察] 查看 Trace、阶段耗时、引用和置信度[闭环] 将反馈与失败样本沉淀为新的回归用例15. 项目总结此项目的核心价值不是单点模型能力而是将企业 RAG 拆成了几个能够独立验证的工程环节用场景配置约束业务边界用统一 metadata 贯穿数据隔离用版本化入库隔离资料变更风险用 Dense BM25 Rerank 提升召回稳定性用 FAQ 快路径降低标准问题延迟用 Prompt Profile 固化高风险回答口径用证据置信度、引用增强和生成后核验降低无依据回答用 WebSocket 事件协议连接同步 RAG 与异步前端用缓存、Trace、评测集和 Gate 形成持续优化闭环。最终形成的不是一条“问题 → 向量库 → 大模型”的演示链而是一套从资料治理、知识发布到在线问答和质量运营都能够解释、复现和验收的 RAG 系统。
