# RAG 数据生成流水线设计

面向工程团队的可复用、可观测、版本化数据处理架构。

本方案旨在构建一套通用的 RAG (Retrieval-Augmented Generation) 数据处理流水线，解决非结构化数据到向量索引的标准化转化问题。系统覆盖从原始数据切分、清洗、Embedding 向量化到最终入库与评测的全生命周期，并实施版本治理，确保数据迭代可追溯。

运行态问答与路由策略见 `docs/24-rag-regional-inheritance-llm-logic.md`，自动进化与索引更新见 `docs/19-graphrag-searxng.md`。

## 1. RAG 目标与适用性

RAG 流水线的核心目标是建立高信噪比的知识索引，而非简单的全量数据堆砌。在接入数据前，必须明确其适用范围与关键性能指标(KPI)。

### 1.1 适用场景

- 适用场景
  - 非结构化文档：PDF 研报、Markdown 技术文档、Word 合同。
  - 长尾知识检索：企业内部 Wiki、历史工单记录。
  - 语义模糊查询：用户无法准确描述关键词的自然语言问答。
- 非适用场景
  - 结构化强统计：如“查询 2023 年 Q3 总销售额”(应使用 Text2SQL)。
  - 超长上下文依赖：需要通读整书才能理解的逻辑推理。
  - 高频实时数据：秒级变化的股票价格或传感器读数。

### 1.2 核心度量指标(KPIs)

| 指标 | 说明 | 目标/口径 |
| --- | --- | --- |
| Recall@K | Top-K 结果是否包含标准答案 | 召回率 |
| Precision | 检索内容与问题的相关性密度 | 准确率 |
| Latency | P99 检索耗时(含重排) | < 200ms |
| Cost | 向量维度与索引内存占用 | 存储成本 |

## 2. 内容切分与清洗策略

垃圾进，垃圾出(Garbage In, Garbage Out)。清洗与切分是决定 RAG 效果的关键环节。采用“语义优先，结构辅助”的分层处理策略。

### 2.1 处理流水线

- 格式标准化(Normalization)：将 PDF/Word/HTML 统一转换为 Markdown，移除不可见字符、多余空行，统一全角/半角标点。
- 去噪与脱敏(Cleaning)：过滤噪声文本、广告片段、敏感信息。
- 结构化切分(Structural Splitting)：优先按 Header (H1-H3) 切分，保持段落语义完整性。代码块与表格禁止内部拆分。
- 递归兜底切分(Recursive Splitting)：对超过 chunk_size 的段落使用递归字符切分器，设定 10%~20% 的 chunk_overlap 维持上下文连贯。

### 2.2 参数化配置示例

流水线支持通过 YAML 文件定义不同数据源的处理策略。

```yaml
strategies:
  technical_docs:
    parser: "markdown"
    cleaning:
      remove_urls: false # 保留技术文档中的链接
      fix_unicode: true
    splitter:
      type: "recursive"
      chunk_size: 1000 # 大块切分以保留完整上下文
      chunk_overlap: 200
      separators: ["\\n\\n", "\\n", "。", "！"]
  user_comments:
    parser: "text"
    cleaning:
      remove_urls: true # 移除评论中的广告链接
      remove_emojis: true
    splitter:
      type: "token"
      chunk_size: 300 # 短文本小块切分
      chunk_overlap: 50
```

## 3. Embedding 与向量库选型

### 3.1 Embedding 模型策略

Embedding 将文本转换为高维向量，选型需权衡语义表达能力与推理成本。

- 模型推荐：多语言场景推荐 OpenAI text-embedding-3-small (1536 dim) 或开源 BGE-M3。
- 归一化：对向量进行 L2 归一化，使用点积(Dot Product)计算余弦相似度。
- 生成策略：采用异步批量(Async Batch)模式调用模型 API，并发控制在 50-100 batch/s，避免触发 Rate Limit。

### 3.2 向量数据库选型矩阵

| 维度 | PGVector | Elasticsearch (kNN) | Milvus / Zilliz |
| --- | --- | --- | --- |
| 定位 | PostgreSQL 插件 | 搜索引擎扩展 | 专用向量数据库 |
| 适用规模 | 中小规模(<1000 万) | 中等规模(千万级) | 超大规模(十亿级) |
| 运维复杂度 | 低(复用现有 PG) | 中(JVM, 集群) | 高(微服务架构) |
| 混合检索 | 强(SQL Join + Vector) | 极强(BM25 + Vector) | 弱(依赖元数据过滤) |
| 推荐场景 | 企业内部知识库 | 电商/日志搜索增强 | 公有云 AI 平台 |

### 3.3 选型建议

针对大多数企业内部知识库场景，PGVector 是性价比最高的选择，因为它可以利用现有 RDS 基础设施，且支持 ACID 事务，便于管理“文档-向量”的一致性。

## 4. 检索与评测策略

### 4.1 检索与重排流程

- 混合检索：结合 BM25(关键词匹配) 与 Embedding(语义匹配)，使用 RRF(Reciprocal Rank Fusion) 融合结果。
- Metadata 过滤：在检索前应用 pre-filtering，例如限制 date > 2024-01-01 或 category == "technical"。
- 重排序(Re-ranking)：使用 BGE-Reranker 或 Cohere 对 Top-50 粗排结果进行精排，最终保留 Top-5 输入 LLM。

### 4.2 评测体系

使用 Ragas 框架计算核心指标：

- Faithfulness(忠实度)：生成答案是否完全基于检索上下文，避免幻觉。
- Context Relevance(上下文相关性)：检索到的片段是否包含回答所需信息。

## 5. 版本治理与迭代联动

RAG 系统的效果优化是持续迭代过程。为避免“改了一个参数，效果不知是好是坏”，必须对每次数据生成进行版本控制，并将元数据同步至中央治理平台。

### 5.1 版本化策略

每次执行数据生成流水线(Ingestion Job)必须生成唯一的 Iteration ID (如 `rag-v1.2-20260123`)，并记录完整上下文快照：

- Source Hash：源文件的 Git Commit ID。
- Config Snapshot：当时使用的 chunk_size、Embedding 模型版本。
- Index Name：对应向量库索引名称(便于回滚)。

### 5.2 与 Docs API 的联动

RAG 迭代登记统一走知识库文档系统接口，避免在本方案中重复维护示例代码：
- 接口与鉴权：`docs/18-docs-rest-api.md`
- 迭代记录模板：`docs/21-iteration-template.md`

## 6. 关联文档

- `docs/24-rag-regional-inheritance-llm-logic.md`：RAG 交互逻辑与问答路由
- `docs/19-graphrag-searxng.md`：自动进化与索引更新机制
- `docs/05-data-pipeline-and-quality.md`：数据清洗与标准化流程