生产级RAG构建

你要解决的问题

很多团队搭 RAG 时不看评估数据，检索调参靠直觉：文档解析把表格和图片丢成噪声，词法索引和向量索引共用分词器导致歧义，BM25 与 Char-BM25 同时开启徒增噪声。领域术语（缩写、口语、错别字）被通用分词器切开后，召回率不可诊断；缺少 Q-DOC-Q 评估集时，任何分块或索引调整都没法判断回召率变化方向。反过来，评估只跑原始检索又难以隔离改写、路由、重排的影响。

技能如何工作

rag-build-skills 强制把离线一次性构建与在线迭代循环拆开，每一步都有可验证的中间产物。

• Intake 与规划：先确认领域、文档类型、知识库数量、生成模型和视觉内容占比，输出 pipeline 计划后再动手。多模态模块仅当存在图表且用户可能以图搜图时才激活。
• 关键词字典：从语料、查询日志和专家输入抽取标准词、缩写、口语和错别字，写为 keyword_dict.json，同时用于标注、改写和 jieba 自定义词典。
• 文档解析与分块：PaddleOCR-VL 把 PDF/图片解析为 Markdown，提取图片生成描述并留下图片链接，表格转 Markdown，保持阅读顺序和页码映射。分块采用父-子策略：parent chunk 1024 tokens，child chunk 256 tokens，overlap 50 tokens，且不跨章节切割。每个 chunk 必须带齐元数据，缺失即拒绝写入。
• 混合索引：词法索引二选一——默认 BM25 配 jieba 领域词典，仅当查询有大量错别字或口语时才切到 Char-BM25；Dense 索引使用 embedding 模型内置分词器（如 BGE-M3 的 BPE）。两者分词器严格隔离，不能强行统一。
• 多模态索引（可选）：Step 3.5 把图像用 Qwen3-VL-Embedding 编码到独立向量索引，通过 parent_chunk_id 等元数据桥接文本块，文本流水线零侵入。
• 自动评估集：Step 5 由 LLM 生成 Q-DOC-Q 对（1:1 与 1:N），去重后可并入专家标注。Step 6 离线评估只跑原始检索（无改写、无路由、无重排），用于隔离数据处理问题，必须通过后才能进入在线循环。
• Embedding 微调（可选）：仅当 Dense 回召持续偏低且其他手段无效时启动，从 Bad Cases 挖掘难负样本；微调后必须重编码全量 chunk，再对比 chunk recall@K（≥5pp 才部署，≥2pp 回退）。
• 在线循环：围绕检索、分块质量、Prompt 六要素逐项优化，所有改进由评估数据支撑，组件可独立替换和评估。

适用边界与注意点

• 该技能不适用于纯 FAQ 或零领域知识的小语料，也不替代人工标注；评估集仅是从语料自动生成，可并入专家标注增强覆盖。
• BM25 与 Char-BM25 互相排斥，多开只会增加噪声。
• 多模态索引依赖文档中确有大量图表且用户有图像检索意图；纯文本知识库请跳过 Step 3.5 和 Step 4.6。
• Embedding 微调会破坏原向量空间，必须全量重建 Dense 索引，并存池化；没有评估证据时不要触发。