# 全量数据入口方案

## 1. 方案综述
本方案旨在构建一套标准化、高可用的“全量数据入口”，解决知识库建设中数据源异构、更新延迟大、质量不可控等痛点。通过统一的接入架构，实现从源端采集到 RAG 索引构建的全链路自动化。

基础采集与质量治理流程见 `docs/05-data-pipeline-and-quality.md`，本文侧重工程化与可观测的深度方案。

## 2. 目标与范围
- 覆盖采集、清洗、索引、发布的全链路能力。
- 支持多数据源统一接入与稳定运行。
- 具备可追溯的数据血缘与版本治理。

## 3. 关键指标与验收标准
### 3.1 性能指标 (KPI)
- 更新时延：热数据 < 5 分钟，冷数据 < 24 小时。
- 采集成功率：> 99.9%（含重试）。
- 去重准确率：100%（基于内容指纹）。

### 3.2 验收标准
- 所有接入源具备自动化 Schema 映射配置。
- 可视化的数据血缘追踪能力。
- 支持通过文档系统接口发布更新记录。

## 4. 总体架构与分层设计
系统采用经典的 ETL-RAG 分层架构，确保数据处理的解耦与可扩展性。

| 层级 | 核心职责 | 稳定性设计要点 |
| --- | --- | --- |
| 数据源层 | 提供原始数据（Web/API/DB/消息/文件） | 被动适配，需处理网络抖动与源端限流 |
| 适配采集层 | 协议转换、增量识别、流式消费 | 断点续传、退避重试、分布式采集 |
| 规范清洗层 | Schema 映射、字段标准化、去重、质量校验 | 幂等性设计、脏数据隔离 |
| 入库索引层 | 元数据存储、文档切分、Embedding 向量化 | 写入流控、主从副本、索引预热 |
| 编排监控层 | 任务调度、依赖管理、告警、链路追踪 | SLA 监控、超时熔断、死信队列 |

## 5. 核心组件与接口定义
| 组件 | 输入/输出 | 核心配置 | 失败处理与重试 |
| --- | --- | --- | --- |
| 采集器 (Collector) | In: Source Config / Out: Raw Blob | Cron Schedule、Rate Limit、Auth Token | 指数退避重试，失败进入 DLQ |
| 解析器 (Parser) | In: Raw Blob / Out: Structured JSON | Format Rules (HTML/PDF/JSON Path) | 解析异常标记为脏数据，保留原始文件 |
| 清洗管道 (Cleaner) | In: JSON / Out: Normalized Doc | Schema Mapping、Deduplication Rules | 字段缺失时默认值或丢弃，记录日志 |
| 向量化器 (Embedder) | In: Text Chunks / Out: Vectors | Model Name、Chunk Size、Overlap | API 超时重试，批量失败降级 |

## 6. 端到端流程与发布机制
1) 新源接入与配置：配置连接信息、Schema 映射与采集频率，完成连通性测试。
2) 采集与解析：按计划拉取数据并解析为标准中间格式，生成指纹去重。
3) 清洗与规范化：类型转换、脱敏、无效过滤，通过质量校验进入待发布区。
4) 索引构建与向量化：文本分块、生成向量，写入向量库与全文索引。
5) 灰度发布与上线：新批次先入灰度索引，通过评测后合并主索引。

## 7. 发布与迭代记录
文档发布与迭代记录已在知识库文档系统中统一规范，本方案仅引用：
- 发布与鉴权接口：`docs/18-docs-rest-api.md`
- 迭代记录模板：`docs/21-iteration-template.md`
- 文档管理流程：`docs/17-docs-management.md`

## 8. 关联文档
- `docs/05-data-pipeline-and-quality.md`：数据处理与质量治理
- `docs/28-crawling-and-sync.md`：稳定爬取与同步策略
- `docs/27-rag-pipeline.md`：RAG 索引构建流水线