产品研发RAG_总体方案与实施手册.md 22.4 KB

Raw Blame History Permalink


title: 产品研发 RAG 总体方案与实施手册
status: active
owner: xwk
updated_at: 2026-03-19


1. 文档目标

本文是当前项目的唯一主方案文档，用于统一回答下面几件事：


这个 RAG 项目要解决什么问题
现有数据资产有哪些，质量如何
技术架构和数据流怎么设计
当前仓库里的脚本和产物分别做什么
如何重新生成知识库、如何导入、如何日常维护
后续如何扩展到需求预评审和代码知识库


不再建议继续维护多份平行方案文档。

项目仓库地址：


http://gitlab.dajiazhongyi.com/xuweikang/RAG_


2. 项目目标


2.1 业务目标

这个项目最终要服务三类能力：


能力一：产品逻辑问答（已完成）

用户通过对话直接询问：


某个功能现在怎么做
哪些场景会报错
某个按钮/弹窗/校验规则是什么
某个功能从哪个版本开始变化


能力二：需求 AI 预评审（待完善）

当新增需求时，AI 应能基于现有知识库输出：


影响模块
影响触点
已有相似规则
潜在冲突
建议补充的测试场景


能力三：代码知识库底座（待实现）

后续把接口、服务、前后端代码说明接到同一套知识骨架上，形成：


产品规则
版本演进
技术实现


三层联动的知识体系。


2.2 当前阶段目标

当前阶段不追求“一步到位的完美智能体”，而是先把以下基础能力稳定下来：


统一知识生产链
统一知识索引层
最终可导入的合成知识库
可复跑、可迭代、可增量更新


3. 当前资产现状


3.1 已有原始资产

项目当前已经具备四类核心输入：


培训文档


来源：飞书文档导出 PDF
目录：pdf/

特点：


相对接近产品官方描述
有版本信息
但 PDF 导出后会有断行、标题丢失、版式噪声


测试用例


来源：迭代测试 XML
目录：testCase/

特点：


行为和回归场景丰富
对异常、边界、校验类问题很有价值
但大量步骤是枚举式表达，语义不稳定


Figma 规则


来源：Figma 链接和已产出的 rule atoms
目录：inputs/figma/、build/*/rule_atoms.jsonl

特点：


对页面交互、弹窗、toast、按钮态最强
但业务背景往往不完整


后台代码仓库


来源：后台 Java 多模块仓库
当前接入路径：/Users/xwk/Downloads/studio-server2

特点：


对接口路径、鉴权、枚举、状态机、异常约束最强
适合补“系统实际上怎么实现、受什么条件限制”
不直接定义产品主事实


高优先参考文档


来源：测试同学或产品同学人工整理的专项说明
目录：inputs/priority_refs/

特点：


通常聚焦单一主题
比普通测试补充更干净
适合在培训文档未覆盖专项细节时，作为强参考


3.2 现状判断

当前项目不是“没有数据”，而是“数据已经够用，但知识层还不够稳定”。

主要问题：


老的 case_atoms.jsonl 中仍有 [截图]、满足预期、枚举步骤等噪声
老的 doc_atoms.jsonl 有 PDF 切分断裂问题
历史产物按版本分散存放，缺少统一知识索引
版本演进和需求预评审能力没有被组织成独立知识层


所以当前正确定位是：


原始资产层：可用
候选原子层：可用但不稳定
统一知识索引层：已补齐
最终合成知识库：已可用


4. 总体架构


4.1 分层架构图

flowchart TB
    A[培训文档 PDF 主事实源] --> B[结构化抽取]
    C[Figma 链接与规则 交互细节补充源] --> B
    D[测试用例 XML 行为验证与边界补充源] --> B
    X[后台代码仓库 实现补充源] --> Y[代码扫描与蒸馏]

    B --> E[候选层 Candidate]
    E --> F[语义蒸馏 / 合成原子]
    F --> G[质量校验]
    G --> H[统一知识索引层 主轴: feature_scope + app_version + 来源优先级]
    H --> I[最终合成知识库 培训文档主事实层与补充层]
    Y --> I

    H --> M[模块标签 辅助过滤与路由]
    I --> J[产品逻辑问答]
    I --> K[需求 AI 预评审]
    I --> L[代码影响分析与实现约束问答]


4.2 四层说明


第一层：Raw 原始资产层

保存原始输入，不做知识承诺。

包括：


pdf/*.pdf
testCase/*.xml
inputs/figma/*
inputs/priority_refs/*


第二层：Candidate 候选层

把原始资产解析成更适合模型和脚本处理的结构化中间层。

包括：


build/<version>/case_candidates.jsonl
build/<version>/doc_segments.jsonl


第三层：Atom 层

分成两类：


历史原子：case_atoms.jsonl、doc_atoms.jsonl、rule_atoms.jsonl

增强原子：case_atoms_model.jsonl、doc_atoms_model.jsonl


增强原子带有：


confidence
qa_status


用于在统一索引中优先覆盖旧原子。


第四层：Knowledge 层

统一索引与最终知识库：


dist/rag/
dist/final_kb/
dist/backend_code/
dist/usable_kb/
dist/dify_import/


这是实际对接 Dify / Bot 的主输出层。


4.5 事实源优先级与冲突裁决

这套体系里，三类原始资产不是平级关系，必须明确主次。

固定优先级：


培训文档
Figma
测试用例


说明：


这条优先级只用于“产品事实裁决”
后台代码不参与主事实抢占
后台代码只作为“实现补充层”


事实源裁决图

flowchart TD
    A[同一功能出现多来源信息] --> B{培训文档是否存在}
    B -->|是| C[以培训文档为主事实]
    B -->|否| D{Figma 是否存在}
    D -->|是| E[以 Figma 补充事实]
    D -->|否| F[以测试用例作为候选补充事实]
    C --> G[补充 Figma 交互细节]
    G --> H[补充测试用例边界/异常]
    E --> H
    F --> I[标记为候选事实或待确认]


为什么这样定


培训文档

培训文档是主事实源。

原因：


内容覆盖最全
最接近产品口径
不仅有预定义模块内容，也有大量跨模块、非标准模块、背景性产品逻辑


因此原则是：


培训文档必须完整保留
不能因为模块体系而过滤
不能因为不是 INCOME / INQUIRY / ... 这些预定义模块就丢弃


Figma

Figma 是交互细节补充源。

主要补：


toast
弹窗
按钮状态
默认值
页面交互和流程表现


当培训文档未覆盖这些细节时，Figma 用来补足。


测试用例

测试用例是行为验证与边界补充源。

主要补：


异常场景
边界条件
回归行为
历史遗留逻辑


测试用例不应直接定义“产品主事实”，而应作为：


培训文档规则的验证证据
培训文档缺失时的候选补充事实


冲突裁决规则


培训文档 vs Figma


默认培训文档优先
如果培训文档明显是旧版本，而 Figma 是更高版本，则以更高版本为准，并保留演进说明


培训文档 vs 测试用例


默认培训文档优先
测试用例作为验证层证据，不抢主事实定义权


Figma vs 测试用例


交互表现、文案、按钮态：优先 Figma
边界场景、异常路径、回归验证：优先测试用例


多版本冲突


最新版本优先
同时保留版本演进
不允许直接覆盖掉历史变化线索


最终落地原则

在最终知识库里，事实源角色应固定为：


培训文档：规则主事实源
Figma：交互细节事实源
测试用例：行为验证与边界补充源
后台代码：接口契约、枚举状态、实现约束补充源


5. 数据流与流程图


5.1 知识生产主流程

flowchart LR
    A[培训文档 PDF] --> B[提取结构]
    C[Figma 规则] --> B
    D[测试用例 XML] --> B

    B --> E[Candidate 层]
    E --> F[模型蒸馏 / 启发式合成]
    F --> G[*_model.jsonl]
    G --> H[质量校验]
    H --> I[来源优先级合并]
    I --> J[统一索引 dist/rag]
    J --> K[最终知识库 dist/final_kb]

    L[模块标签] -.辅助元数据.-> J


5.2 问答流程

flowchart TD
    Q[用户提问] --> A{问题类型}
    A -->|产品逻辑| B[先查培训文档主事实 再补 Figma 与测试细节]
    A -->|版本变化| C[版本演进文档 与 功能主题索引]
    A -->|需求预评审| D[预评审文档 与 功能主题索引]
    B --> E[生成回答]
    C --> E
    D --> E


5.3 需求预评审流程

flowchart TD
    A[输入新需求] --> B[识别模块]
    B --> C[召回相似功能主题]
    C --> D[优先检查培训文档主事实]
    D --> E[补查 Figma 交互细节]
    E --> F[补查测试用例边界与异常]
    F --> G[检查历史版本变化]
    G --> H[检查跨模块触点]
    H --> I[输出影响范围 / 风险 / 建议]


6. 目录与核心产物说明


6.1 docs

当前保留的文档职责：


docs/产品研发RAG_总体方案与实施手册.md


主方案文档


docs/Figma链接索引_来自历史对话_v1.md


Figma 历史链接索引


docs/version_sync_template.yaml


新版本同步模板


docs/version_sync_v4.57.3.yaml


已有版本同步样例


6.2 build

按版本存储中间层与候选层产物：


rule_atoms.jsonl
case_atoms.jsonl
doc_atoms.jsonl
case_candidates.jsonl
doc_segments.jsonl
case_atoms_model.jsonl
doc_atoms_model.jsonl


6.3 dist/rag

统一知识索引层：


master_atoms.jsonl
feature_catalog.jsonl
review_index.jsonl
knowledge_v2/*.md


6.4 dist/final_kb

最终可导入知识库：


00_导入说明.md
01_知识库设计原则.md
02_培训文档主事实库.md
03_培训文档保留项.md
04_Figma与测试补充库.md
05_版本演进.md
06_需求预评审.md
07_模块辅助索引.md
08_后台代码实现补充库.md


6.5 dist/backend_code

后台实现补充知识：


code_atoms.jsonl
01_接口契约.md
02_枚举与状态.md
03_实现约束.md
04_模块映射.md
05_业务实现主题.md


6.6 dist/usable_kb

面向日常问答和预评审的可用知识库包：


00_导入说明.md
01_知识库使用规则.md
02_版本变更总览.md
03_需求预评审执行指南.md
04_后台实现导读.md
10_AUTH_认证.md
11_INCOME_收入提现.md
12_INQUIRY_问诊.md
13_CLINIC_门诊.md
14_PATIENT_患者.md
15_NOTIFICATION_通知.md
16_BACKSTAGE_后台.md
17_GENERAL_通用.md


6.7 dist/dify_import

面向 Dify / 通用 RAG 平台的中颗粒度导入包：


00_导入说明.md
01_使用规则.md
02_版本变更总览.md
03_需求预评审执行指南.md
04_后台实现导读.md
09_AUTH_高优先参考_医师认证流程.md
10_AUTH_主知识库.md
11_INCOME_主知识库.md
12_INQUIRY_主知识库.md
13_CLINIC_主知识库.md
14_PATIENT_主知识库.md
15_NOTIFICATION_主知识库.md
16_BACKSTAGE_主知识库.md
17_GENERAL_主知识库.md


7. 关键脚本说明


7.1 抽取层


scripts/extract_testcase_candidates.py


作用：


把 XML 解析成结构化 testcase candidates


输出：


build/<version>/case_candidates.jsonl


scripts/extract_pdf_segments.py


作用：


把 PDF 解析成结构化 doc segments


输出：


build/<version>/doc_segments.jsonl


7.2 原子层


scripts/build_synthesized_atoms.py


作用：


在没有外部模型时，基于 candidates/segments 批量合成更干净的 atoms


输出：


build/<version>/case_atoms_model.jsonl
build/<version>/doc_atoms_model.jsonl


scripts/normalize_model_atoms.py


作用：


当你接入外部模型后，把模型输出规范化回仓库


7.3 校验与索引层


scripts/validate_atoms.py


作用：


检查 atoms 质量问题


输出：


dist/quality/atom_quality_summary.md
dist/quality/atom_issues.jsonl


scripts/build_rag_assets.py


作用：


聚合所有 atoms
生成统一知识索引


输出：


dist/rag/*


scripts/build_final_knowledge_base.py


作用：


从统一索引生成最终可导入知识库


输出：


dist/final_kb/*


scripts/build_backend_code_knowledge.py


作用：


扫描后台代码仓库
生成接口契约、枚举状态、实现约束三类实现补充知识


输出：


dist/backend_code/*
dist/final_kb/08_后台代码实现补充库.md


scripts/build_usable_knowledge_pack.py


作用：


把主事实、补充事实、后台实现信息整理成一套更适合直接使用的知识库包
当前默认输出“完整主知识库版”，不再把模块文件裁成少量主题摘要
每个主题会完整展开产品主事实与交互/测试补充事实
导出前会对 feature_scope、模块标签和主题标题做归一化，尽量减少版本前缀、端侧容器前缀与脏标题


输出：


dist/usable_kb/*


scripts/build_dify_import_pack.py


作用：


把 dist/usable_kb/ 整理成中颗粒度导入包
保留公共文件和模块主文件
自动吸收 inputs/priority_refs/*.md 这类高优先参考文件
交给 Dify 在导入时继续做内部切分
当前不会再次把模块主文件压缩成摘要版，而是直接复制完整展开后的主知识库文件


输出：


dist/dify_import/*


8. 当前推荐运行手册


8.1 全量重建

按顺序执行：

python3 scripts/extract_testcase_candidates.py
python3 scripts/extract_pdf_segments.py
python3 scripts/build_synthesized_atoms.py
python3 scripts/validate_atoms.py
python3 scripts/build_rag_assets.py
python3 scripts/build_final_knowledge_base.py
python3 scripts/build_usable_knowledge_pack.py
python3 scripts/build_dify_import_pack.py


8.1.1 维护约束


只要修改了知识库生成脚本、导出结构、主题归一化规则或 Dify 导入规则，必须同步更新 docs/ 下对应说明文档
同时必须同步更新 repo 内维护 skill：skills/product-rag-maintainer/SKILL.md

不要把脚本行为改了但文档和 skill 还停留在旧流程


如需同时接入后台代码仓库，再执行：

python3 scripts/build_backend_code_knowledge.py --repo /Users/xwk/Downloads/studio-server2
python3 scripts/build_final_knowledge_base.py
python3 scripts/build_usable_knowledge_pack.py
python3 scripts/build_dify_import_pack.py


8.2 指定版本重建

python3 scripts/extract_testcase_candidates.py 4.57.3
python3 scripts/extract_pdf_segments.py 4.57.3
python3 scripts/build_synthesized_atoms.py 4.57.3
python3 scripts/build_rag_assets.py
python3 scripts/build_final_knowledge_base.py
python3 scripts/build_usable_knowledge_pack.py
python3 scripts/build_dify_import_pack.py


8.3 接入外部模型时

如果后续用 OpenAI / Claude / Dify 工作流做更高质量蒸馏，推荐流程：

python3 scripts/extract_testcase_candidates.py
python3 scripts/extract_pdf_segments.py
# 使用 prompts/*.md 驱动模型批量生成 atoms
python3 scripts/normalize_model_atoms.py model_output_case.jsonl case
python3 scripts/normalize_model_atoms.py model_output_doc.jsonl doc
python3 scripts/validate_atoms.py
python3 scripts/build_rag_assets.py
python3 scripts/build_final_knowledge_base.py


8.4 增量更新推荐做法

如果只是新版本上线，优先跑增量链路，而不是每次手动拼命令：

bash scripts/rebuild_version_kb.sh 4.57.3 /Users/xwk/Downloads/studio-server2


如果是脚本逻辑、知识结构、历史规则做了明显调整，再跑全量：

bash scripts/rebuild_all_kb.sh /Users/xwk/Downloads/studio-server2


8.5 新专项文档接入

如果拿到类似“医师认证流程”这种人工整理后的专项文档：


原始文件放到 inputs/priority_refs/

整理出一份清晰 Markdown，也放到 inputs/priority_refs/

执行：


python3 scripts/build_dify_import_pack.py


把新生成的高优先参考文件上传到 Dify 的“产品主知识库”


9. 当前输出结果说明

截至当前仓库状态，项目已经生成了最终合成知识库：


目录：dist/final_kb/


它已经具备以下特性：


按模块组织
包含当前规则
包含版本演进
包含预评审线索
能直接导入知识库系统


当前索引层和最终库已经优先使用增强原子。

但从设计原则上，最终库后续应继续朝下面这条方向收敛：


以培训文档为主事实层
以功能主题和版本演进为主组织方式
以模块作为辅助索引，而不是主切分维度
用 Figma 和测试用例补足培训文档未覆盖的细节与边界


也就是说，最终库的目标不是“把所有内容先塞进模块”，而是“先保住主事实，再提供模块化检索能力”。


10. 质量控制策略


10.1 目前的主要噪声

历史数据里仍然存在：


[截图]
满足预期
纯枚举动作
PDF 断句碎片


10.2 当前处理策略

已经采取的策略：


最终知识库层做过滤
候选层和增强原子分开存放
统一索引优先使用：


同源更高质量
validated
更高 confidence


10.3 后续最优解

当前的 build_synthesized_atoms.py 是“无外部模型时的替代方案”，它比旧 atoms 干净，但还不等于真正的高质量语义蒸馏。

最佳做法仍然是：


用模型重做 case_atoms

用模型重做 doc_atoms

再用 normalize_model_atoms.py 回写


10.5 模块体系的定位

模块最初是为了帮助 AI 分类，但在当前项目目标下，模块不应该成为知识组织的主轴。


为什么不能把模块当主轴

原因有三点：


培训文档里存在大量非预定义模块的产品逻辑
同一条规则可能天然跨模块
如果以模块作为硬边界，会误伤培训文档的完整性


因此模块不适合承担：


知识切分主键
合并主键
培训文档是否保留的过滤条件


模块应该承担什么角色

模块建议保留，但降级为辅助元数据。

适合承担：


检索过滤
路由提示
需求预评审时的影响范围提示
未来代码知识库的粗粒度归属


这套体系真正的主轴是什么

建议以三件事作为主轴：


feature_scope
app_version
事实源优先级


也就是说：


知识按功能主题组织
变化按版本组织
冲突按来源优先级裁决
模块只作为辅助标签存在


对最终知识库的要求

最终知识库应该满足：


培训文档内容完整保留
非预定义模块内容允许存在
能标模块则标，不能标不强行归类

GENERAL 只作为兜底，不代表低价值内容


11. 知识库导入手册


11.1 推荐导入内容

如果你要保留“完整知识骨架”，优先导入：


dist/final_kb/00_导入说明.md
dist/final_kb/01_知识库设计原则.md
dist/final_kb/02_培训文档主事实库.md
dist/final_kb/03_培训文档保留项.md
dist/final_kb/04_Figma与测试补充库.md
dist/final_kb/05_版本演进.md
dist/final_kb/06_需求预评审.md
dist/final_kb/07_模块辅助索引.md
dist/final_kb/08_后台代码实现补充库.md


如果你要直接接 Dify / 通用 RAG 平台，优先导入：


dist/dify_import/00_导入说明.md
dist/dify_import/01_使用规则.md
dist/dify_import/02_版本变更总览.md
dist/dify_import/03_需求预评审执行指南.md
dist/dify_import/04_后台实现导读.md
dist/dify_import/10_AUTH_主知识库.md
dist/dify_import/11_INCOME_主知识库.md
dist/dify_import/12_INQUIRY_主知识库.md
dist/dify_import/13_CLINIC_主知识库.md
dist/dify_import/14_PATIENT_主知识库.md
dist/dify_import/15_NOTIFICATION_主知识库.md
dist/dify_import/16_BACKSTAGE_主知识库.md
dist/dify_import/17_GENERAL_主知识库.md
dist/dify_import/*高优先参考*.md


11.2 推荐使用方式


产品问答

主要使用：


培训文档主事实库
培训文档保留项
Figma 与测试补充库
后台代码实现补充库


版本查询

主要使用：


版本演进文档
培训文档主事实库


需求预评审

主要使用：


需求预评审文档
模块辅助索引
版本演进文档
Figma 与测试补充库
后台代码实现补充库


11.3 当前 Dify 实施经验

当前实测有效的参数是：


分段标识符：\n\n

分段最大长度：1200

分段重叠长度：100

索引方式：高质量

检索方式：混合检索

Top K：5

Score 阈值：先不开
Rerank：能开就开
Embedding：text-embedding-v4


当前实测更稳的 Dify 结构是三库：


产品主知识库
版本与预评审知识库
后台实现补充知识库


原因：


底层知识资产是一套
但 Dify 里的知识库同时承担检索域职责
按用途拆分后，普通问答、版本追溯、后台实现约束的召回更稳


11.4 未来 AI 的接手入口

为了避免上下文丢失后无法继续维护，仓库里保留了三类持续化资产：


docs/产品研发RAG_增量更新与Dify维护手册.md
docs/产品研发RAG_接手说明.md
skills/product-rag-maintainer/SKILL.md


新 AI 或新同学接手时，优先阅读这三份资产。


12. 未来扩展方案


12.1 接入需求文档 / 评审记录

建议新增：


PRD atoms
评审决策 atoms


这样可以补齐“为什么这样设计”。


12.2 接入代码知识

当前已经完成第一版代码接入：


controller 接口契约
enum / constant 枚举与状态
Assert / BusinessException / RequestLock 实现约束


后续继续补强：


service 级规则归纳
mapper / repository / SQL 约束
数据表与字段语义
关键调用链路


推荐沿用同样的元数据：


app_version
primary_module
feature_scope
touchpoints


12.3 接入真实模型生产链

建议最终演进为：

flowchart LR
    A[候选层] --> B[外部模型蒸馏]
    B --> C[规范化]
    C --> D[质量校验]
    D --> E[统一索引]
    E --> F[最终知识库]


13. 最终结论

这个项目目前已经完成了从“散落的原始资产”到“可导入的合成知识库”的关键一步。

当前最重要的不是再改大方向，而是持续做两件事：


新版本按这套流程稳定增量入库
用真实模型逐步替换历史低质量 atoms


这份文档就是当前项目的统一思路、统一架构和统一手册。