业务流程总览¶
本节将交互式业务流程页转换为静态 Mermaid 图和步骤说明，覆盖在线问答、离线入库、系统全景及章节实现路线。
在线问答流程¶
当前页面以 WebSocket 作为在线问答唯一主路径。
flowchart TD
USER["👤 用户浏览器<br/>输入问题 + 选择业务分类"]
WS["🔌 WS /api/stream<br/>在线问答唯一入口"]
USER -->|"1. 当前页面直接建立长连接"| WS
subgraph WSAPI["WebSocket 入口层"]
WACCEPT["接受连接<br/>websocket.accept()"]
WRATE["消息级限流<br/>check_rate_limit()"]
WPARSE["解析 JSON<br/>QueryServiceContext"]
WACCEPT --> WRATE --> WPARSE
end
WS --> WSAPI
subgraph PIPELINE["RAG Pipeline - stream_query() 在线主链路"]
S0["🏗️ Stage 0<br/>create_query_context()<br/>场景/数据域/会话/trace_id/KB版本"]
S1["🧭 Stage 1<br/>decide_route()<br/>direct_answer / faq_exact / retrieval<br/>FAQ 快速探测未命中保留原问题候选"]
S3["🧠 Stage 2<br/>prepare_retrieval()<br/>历史加载→意图决策→source/计划→变体"]
S4["📋 Stage 3<br/>search_faq()<br/>复用原问题候选 + 仅补查变体<br/>合并去重后统一重排 / 不满足则完整回退"]
S5["📄 Stage 4<br/>search_doc() + Reranker<br/>文档混合检索→CrossEncoder精排"]
S6["📊 Stage 5<br/>prepare_answer()<br/>上下文筛选→来源→证据置信度"]
S7["🤖 Stage 6<br/>stream_llm_answer()<br/>LLM 流式生成→引用增强→生成核验"]
S8["💾 Stage 7<br/>finish_success()<br/>保存历史→Trace→end含最终置信度"]
S0 --> S1
S1 -->|"route=retrieval"| S3
S1 -->|"route=direct_answer"| DIRECT["🚫 直接返回"]
S1 -->|"route=faq_exact"| FAST["⚡ FAQ 直出<br/>intent=FAQ_QUERY"]
S3 --> S4
S4 -->|"分数 < 阈值"| S5
S4 -->|"分数 ≥ 阈值"| FAQOUT["📋 FAQ 直出"]
S5 --> S6 --> S7 --> S8
end
WSAPI --> PIPELINE
subgraph EXTERNAL["外部系统依赖"]
MILVUS[("🗄️ Milvus 2.5<br/>Dense + Sparse<br/>混合检索")]
EMBED["🧮 BGE-M3<br/>文本→1024维向量"]
RERANK["⚖️ BGE Reranker<br/>CrossEncoder 精排"]
LLM["🤖 LLM<br/>qwen-plus<br/>DashScope/OpenAI兼容"]
MYSQL[("🗃️ MySQL 8.0<br/>历史·摘要·反馈")]
end
S4 -.->|"Dense向量"| EMBED
S4 -.->|"仅新增变体 Hybrid Search<br/>或安全回退完整检索"| MILVUS
S5 -.->|"Dense向量"| EMBED
S5 -.->|"Hybrid Search"| MILVUS
S5 -.->|"精排打分"| RERANK
S7 -.->|"流式生成"| LLM
S8 -.->|"读写历史"| MYSQL
S3 -.->|"追问改写/查询变体"| LLM
S1 -.->|"FAQ 精确试探"| MILVUS
STREAMOUT["📤 WebSocket 逐 token 推送<br/>打字机效果 + 来源引用"]
S7 --> STREAMOUT
S8 --> STREAMOUT
style USER fill:#1e3a5f,stroke:#3b82f6,stroke-width:2px
style WS fill:#1e293b,stroke:#818cf8,stroke-width:2px
style FAST fill:#064e3b,stroke:#34d399
style FAQOUT fill:#064e3b,stroke:#34d399
style DIRECT fill:#713f12,stroke:#fbbf24
style STREAMOUT fill:#1e3a5f,stroke:#3b82f6,stroke-width:2px
style S5 fill:#131c2e,stroke:#f59e0b,stroke-width:2px
style S6 fill:#131c2e,stroke:#f59e0b,stroke-width:2px
style LLM fill:#500724,stroke:#ec4899
style MILVUS fill:#0f766e,stroke:#06b6d4
style EMBED fill:#3b0764,stroke:#a78bfa
style RERANK fill:#451a03,stroke:#f59e0b
style MYSQL fill:#1a2e05,stroke:#84cc16流程步骤：
- 用户浏览器：用户输入问题，并带上业务分类、租户、数据集、可见级别等上下文。
- WebSocket 主通道：当前前端代码直接建立 /api/stream 长连接，并把问题参数作为第一条消息发送。
- WebSocket 入口层：后端接受连接，对每条消息做限流、JSON 解析和 QueryServiceContext 构造。
- 创建运行上下文：汇总场景、数据域、会话、trace_id、知识库版本等运行参数。
- 查询路由：统一决定 direct_answer / faq_exact / retrieval。FAQ 精确命中是 route=faq_exact，intent 仍是 FAQ_QUERY。
- 检索准备：route=retrieval 后，加载历史并通过意图决策网关生成 IntentResult；必要时改写追问，再确定 source 过滤、检索计划、查询变体和 Prompt Profile。
- FAQ 混合检索：使用 Dense + Sparse Hybrid Search 检索 FAQ，并根据阈值决定是否直出。
- 文档检索与精排：文档混合检索后进入 CrossEncoder rerank。
- 上下文构建：筛选 FAQ 和文档候选，去重、截断并格式化为带来源编号的 Prompt Context，同时写入 evidence_confidence。
- LLM 流式生成：调用 qwen-plus 流式生成答案，生成后增强来源引用，并计算 generation_verification。
- 保存与结束：保存聊天历史，写入 Trace，并发送包含最终 answer_confidence 的 end 事件。
- 逐 token 推送：通过 WebSocket 将答案持续推回浏览器，形成打字机效果。
离线入库流程¶
从文件进入系统到 Milvus 可检索，展示文档处理、向量化、索引清单和 FAQ 并行通道。
flowchart TD
START["📁 上传文档<br/>PDF / Word / MD / CSV / Excel"]
subgraph LOAD["1. 文档加载 - Document Loaders 注册表"]
REGISTRY["按后缀匹配 Loader<br/>.pdf→PyPDFLoader<br/>.docx→Docx2txtLoader<br/>.md→TextLoader<br/>.csv/.xlsx→TableLoader"]
LOADED["Document 对象<br/>page_content + metadata"]
REGISTRY --> LOADED
end
START --> LOAD
subgraph NORMALIZE["2. 文档标准化"]
META["补充元数据<br/>source / file_name / doc_id<br/>scenario_id / kb_version"]
DEDUP["去重检测<br/>SHA256 文件指纹"]
META --> DEDUP
end
LOAD --> NORMALIZE
subgraph CHUNK["3. 文档切分 - Parent-Child Chunking"]
HEADER["Markdown 按标题切分<br/>保留 h1/h2/h3 层级"]
PARENT["父块切分<br/>RecursiveCharacterTextSplitter<br/>chunk_size=2000"]
CHILD["子块切分<br/>RecursiveCharacterTextSplitter<br/>chunk_size=500, overlap=50"]
HEADER --> PARENT --> CHILD
end
NORMALIZE --> CHUNK
subgraph EMBEDDING["4. 向量化"]
DENSE["BGE-M3 → Dense 向量<br/>1024 维 · L2 归一化"]
SPARSE["Milvus BM25 → Sparse 向量<br/>服务端自动生成"]
end
CHILD --> EMBEDDING
subgraph STORE["5. 写入 Milvus"]
SCHEMA["自动创建 Collection<br/>pk / text / dense / sparse<br/>+ source / kb_version"]
INDEX["创建向量索引<br/>Dense HNSW + Sparse BM25"]
INSERT["insert / upsert<br/>+ flush 持久化"]
LOADCOL["load_collection()<br/>加载到内存"]
SCHEMA --> INDEX --> INSERT --> LOADCOL
end
EMBEDDING --> STORE
subgraph MANIFEST["6. 索引清单 - MySQL IndexManifest"]
RECORD["记录入库文件清单<br/>fingerprint + chunk_ids"]
DIFF["版本差异对比<br/>目标版本跳过 / 基准版本复用 / 变化重建"]
REUSE["引用式复用<br/>目标 manifest 记录已有 chunk_ids<br/>不复制、不重算向量"]
CLEANUP["变化文件失效旧 chunk<br/>valid_to_seq = target_seq"]
RECORD --> DIFF
DIFF -->|"未变化"| REUSE
DIFF -->|"变化"| CLEANUP
end
STORE --> MANIFEST
READY["✅ 知识就绪<br/>按 active version_seq 解释有效视图"]
REUSE --> READY
CLEANUP --> READY
FAQIN["📋 FAQ CSV 入库<br/>并行通道"]
FAQIN -->|"CSV → Milvus FAQ Collection<br/>标准问题 + 标准答案"| READY
style START fill:#1e3a5f,stroke:#3b82f6,stroke-width:2px
style READY fill:#064e3b,stroke:#34d399,stroke-width:2px
style EMBEDDING fill:#3b0764,stroke:#a78bfa
style STORE fill:#0f766e,stroke:#06b6d4
style MANIFEST fill:#451a03,stroke:#fbbf24
style FAQIN fill:#134e4a,stroke:#2dd4bf流程步骤：
- 上传文档：支持 PDF、Word、Markdown、CSV、Excel 等知识资料进入入库流程。
- 文档加载：根据文件后缀选择 Loader，把原始文件转换成 Document 对象。
- 文档标准化：补充 source、doc_id、scenario_id、kb_version 等元数据，并进行文件指纹去重。
- 父子块切分：先保留标题结构，再生成父块和子块，让检索粒度与上下文粒度分离。
- 向量化：BGE-M3 生成 dense 向量，Milvus BM25 Function 在服务端生成 sparse 向量。
- 写入 Milvus：创建 schema 与索引后写入数据，flush 并 load collection。
- 索引清单：记录文件和 chunk 的对应关系；未变化 chunk 继续被有效期视图引用，变化文件才重新 embedding。
- FAQ 并行入库：FAQ CSV 进入 FAQ Collection，作为在线问答的快速直出来源。
- 知识就绪：FAQ 与文档索引完成后，在线问答即可检索到新知识。
系统全景图¶
把启动校验、在线问答、离线入库、存储层、模型层和 LLM 服务放在同一张图中。
flowchart TB
subgraph STARTUP["🚀 系统启动"]
APP["app.py"]
PREFLIGHT["Preflight Check<br/>LLM · Milvus · MySQL · 模型 · 场景<br/>任一缺失 → 启动失败"]
WARM["检索栈预热并等待 ready<br/>BERT + BGE 真实编码 + Reranker<br/>全部 Milvus Collection"]
APP --> PREFLIGHT --> WARM
end
subgraph ONLINE["🟢 在线问答（实时）"]
direction TB
B["浏览器"]
API2["FastAPI<br/>HTTP + WebSocket"]
QASVC["QAService<br/>编排层"]
PIPE["RAG Pipeline<br/>7 阶段管线"]
B -->|"提问"| API2 --> QASVC --> PIPE -->|"流式答案"| B
end
subgraph OFFLINE["🔵 离线入库（异步）"]
direction TB
DOC["文档上传"]
INGEST["入库管线<br/>加载→标准化→切分→向量化→存储"]
MANIFEST2["MySQL IndexManifest<br/>引用式增量构建<br/>有效期版本视图"]
DOC --> INGEST --> MANIFEST2
end
subgraph STORAGE["💾 存储层"]
MILVUS2[("Milvus 2.5<br/>Dense 向量<br/>+ Sparse BM25")]
MYSQL2[("MySQL 8.0<br/>聊天历史<br/>会话摘要<br/>用户反馈<br/>KB 版本<br/>IndexManifest")]
MINIO[("MinIO<br/>向量索引文件<br/>binlog")]
end
subgraph MODELS["🧠 模型层（本地部署）"]
BGE3["BGE-M3<br/>Embedding<br/>1024维"]
RERANKER["BGE Reranker<br/>CrossEncoder<br/>精排"]
end
subgraph LLM2["🤖 LLM 服务"]
DASHSCOPE["DashScope<br/>qwen-plus<br/>OpenAI 兼容接口"]
end
ONLINE -->|"检索"| STORAGE
ONLINE -->|"向量化"| MODELS
ONLINE -->|"生成"| LLM2
OFFLINE -->|"写入"| STORAGE
OFFLINE -->|"向量化"| MODELS
STARTUP -->|"校验"| STORAGE
STARTUP -->|"校验"| MODELS
STARTUP -->|"校验"| LLM2
style ONLINE fill:#064e3b,stroke:#34d399,stroke-width:2px
style OFFLINE fill:#1e3a5f,stroke:#3b82f6,stroke-width:2px
style STARTUP fill:#451a03,stroke:#f59e0b,stroke-width:2px
style STORAGE fill:#0f766e,stroke:#06b6d4,stroke-width:2px
style MODELS fill:#3b0764,stroke:#a78bfa,stroke-width:2px
style LLM2 fill:#500724,stroke:#ec4899,stroke-width:2px流程步骤：
- 系统启动：app.py 启动时执行 Preflight Check，依赖缺失会直接失败。
- 运行前校验：检查 LLM Key、Milvus、MySQL、本地模型和场景配置；LLM 连通性进入运行态探测。
- 检索栈预热：提前加载 Embedding 与 Reranker，减少首问等待时间。
- 在线问答：浏览器、FastAPI、QAService、RAG Pipeline 组成实时问答主链路。
- 离线入库：文档通过入库管线转换成可检索知识；日常更新在构建阶段维护有效期窗口，查询阶段按 active version_seq 解释有效视图。
- 存储层：Milvus 存向量与 BM25，MySQL 存历史、摘要、反馈和清单，MinIO 承载底层对象。
- 模型层：BGE-M3 负责 Embedding，BGE Reranker 负责 CrossEncoder 精排。
- LLM 服务：DashScope qwen-plus 以 OpenAI 兼容接口提供生成能力。
章节实现路线图¶
从第 05 章开始，把每一章放回业务流程图中，明确当前代码位于整条项目链路的哪里。
flowchart LR
START["学习内容入口<br/>第 01-04 章<br/>环境/RAG/LangChain/Milvus 基础"]
subgraph ONLINE_COURSE["在线问答主链路：第 05-12 章"]
CH05["05 意图分类与路由入口<br/>Stage 1 decide_route()<br/>规则候选 + 模型候选 + 网关仲裁"]
CH06["06 检索策略与动态计划<br/>Stage 2 检索计划<br/>run_faq / run_doc / top_k / 阈值"]
CH07["07 查询改写与变体生成<br/>Stage 2 追问改写 + 查询变体<br/>rewrite_query / query_variants"]
CH08["08 Milvus 混合检索<br/>Stage 3-4<br/>FAQ/doc Hybrid Search + Rerank"]
CH09["09 QAService 核心编排<br/>服务编排层<br/>把检索能力封装成问答服务"]
CH10["10 RAG Pipeline 主流程<br/>Stage 0-7 串联<br/>在线问答闭环"]
CH11["11 Prompt 工程与 Profile<br/>Stage 5-6<br/>上下文组织 + 回答口径"]
CH12["12 FastAPI 服务入口<br/>WebSocket / HTTP<br/>浏览器可调用"]
end
subgraph ENGINEERING_COURSE["工程化与治理：第 13-19 章"]
CH13["13 启动前置校验<br/>Preflight Check<br/>依赖缺失直接失败"]
CH14["14 知识库版本管理<br/>Stage 0 KB 版本<br/>查询绑定有效版本"]
CH15["15 数据隔离<br/>场景 / 数据域 / source filter<br/>避免跨域回答"]
CH16["16 文档入库链路<br/>离线入库流程<br/>加载→切分→向量化→写入 Milvus"]
CH17["17 质量评估<br/>问答评测集<br/>衡量召回和回答质量"]
CH18["18 测试体系与门禁<br/>自动化测试 / 接口验收<br/>防止链路回退"]
CH19["19 可观测性与 Trace<br/>Stage 7 Trace / 日志<br/>定位每一步耗时和错误"]
end
DONE["最终项目闭环<br/>可启动 / 可入库 / 可问答 / 可测试 / 可观测"]
START --> CH05 --> CH06 --> CH07 --> CH08 --> CH09 --> CH10 --> CH11 --> CH12
CH12 --> CH13 --> CH14 --> CH15 --> CH16 --> CH17 --> CH18 --> CH19 --> DONE
CH05 -.对应.-> ONLINE_STAGE1["动画在线流程 Stage 1<br/>decide_route()"]
CH06 -.对应.-> ONLINE_STAGE2A["动画在线流程 Stage 2<br/>检索计划"]
CH07 -.对应.-> ONLINE_STAGE2B["动画在线流程 Stage 2<br/>追问改写/查询变体"]
CH08 -.对应.-> ONLINE_STAGE34["动画在线流程 Stage 3-4<br/>FAQ/文档检索"]
CH10 -.对应.-> ONLINE_STAGE07["动画在线流程 Stage 0-7<br/>主链路串联"]
CH16 -.对应.-> OFFLINE_FLOW["动画离线入库流程<br/>文档/FAQ 入库"]
CH19 -.对应.-> TRACE_FLOW["动画在线流程 Stage 7<br/>Trace/end 事件"]
style START fill:#1e3a5f,stroke:#3b82f6,stroke-width:2px
style DONE fill:#064e3b,stroke:#34d399,stroke-width:2px
style CH05 fill:#713f12,stroke:#fbbf24,stroke-width:2px
style CH06 fill:#713f12,stroke:#fbbf24,stroke-width:2px
style CH07 fill:#713f12,stroke:#fbbf24,stroke-width:2px
style CH08 fill:#0f766e,stroke:#06b6d4,stroke-width:2px
style CH09 fill:#1e293b,stroke:#818cf8,stroke-width:2px
style CH10 fill:#1e293b,stroke:#818cf8,stroke-width:2px
style CH11 fill:#500724,stroke:#ec4899,stroke-width:2px
style CH12 fill:#1e3a5f,stroke:#3b82f6,stroke-width:2px
style CH13 fill:#451a03,stroke:#f59e0b
style CH14 fill:#0f766e,stroke:#06b6d4
style CH15 fill:#0f766e,stroke:#06b6d4
style CH16 fill:#1e3a5f,stroke:#3b82f6
style CH17 fill:#3b0764,stroke:#a78bfa
style CH18 fill:#3b0764,stroke:#a78bfa
style CH19 fill:#451a03,stroke:#f59e0b
style ONLINE_STAGE1 fill:#1e293b,stroke:#fbbf24
style ONLINE_STAGE2A fill:#1e293b,stroke:#fbbf24
style ONLINE_STAGE2B fill:#1e293b,stroke:#fbbf24
style ONLINE_STAGE34 fill:#0f766e,stroke:#06b6d4
style ONLINE_STAGE07 fill:#1e293b,stroke:#818cf8
style OFFLINE_FLOW fill:#1e3a5f,stroke:#3b82f6
style TRACE_FLOW fill:#451a03,stroke:#f59e0b流程步骤：
- 第 01-04 章：进入项目前的准备：先建立环境、RAG 基础、LangChain 生态和 Milvus 检索基础。第 05 章开始进入项目主链路实现。
- 第 05 章：意图分类与路由入口：对应在线流程 Stage 1 decide_route()，并完成 Stage 2 的规则候选、模型候选与意图决策网关。本章重点是区分 route（系统下一步）和 intent（用户意图），并输出可治理的 rule_score、final_score、decision_policy 和 candidate_intents。
- 第 06 章：检索策略与动态计划：对应在线流程 Stage 2 的检索计划。进入 retrieval 后，系统会决定 FAQ/doc 查多少、阈值多高、是否使用查询变体。
- 第 07 章：查询改写与变体生成：继续补完 Stage 2：追问改写和查询变体，说明 FOLLOW_UP 为什么需要 requires_rewrite。
- 第 08 章：Milvus 混合检索：对应 Stage 3 search_faq() 和 Stage 4 search_doc()+Reranker，第一次真正从 Milvus 召回候选内容。
- 第 09 章：QAService 核心编排：把前面零散能力封装成服务类，让入口层不用关心检索细节。
- 第 10 章：RAG Pipeline 主流程：把 Stage 0 到 Stage 7 串起来，形成在线问答主链路闭环。
- 第 11 章：Prompt 工程与 Profile：对应上下文构建和 LLM 生成阶段，控制回答口径、引用格式和不同场景下的提示词策略。
- 第 12 章：FastAPI 服务入口：把项目能力变成浏览器和接口都能调用的 Web 服务，对应 WebSocket/HTTP 入口层。
- 第 13 章：启动前置校验：对应系统全景图的 Preflight Check，启动前确认基础依赖可用，并把 LLM 供应商状态暴露到健康检查。
- 第 14 章：知识库版本管理：对应 Stage 0 中的 KB 版本，让查询绑定当前激活版本，支持后续重建和回滚。
- 第 15 章：数据隔离：对应 Stage 0 的场景、数据域和 source filter，避免跨场景、跨分类、跨租户误答。
- 第 16 章：文档入库链路：对应离线入库流程，把文档和 FAQ 处理成 Milvus 可检索的数据。
- 第 17 章：质量评估：建立评测集，衡量召回、直出和生成结果，避免只靠主观感觉判断效果。
- 第 18 章：测试体系与门禁：把单元测试、接口验收和回归检查串起来，防止后续修改破坏前面章节成果。
- 第 19 章：可观测性与 Trace：对应 Stage 7 的 Trace、日志和 end 事件，让每次问答能追踪每一步耗时、输入、输出和错误。
- 最终项目闭环：第 19 章结束时，项目应具备可启动、可入库、可问答、可测试、可观测的完整闭环。