什么是 文档加载器（Document Loader）？
文档加载器（Document Loader）是面向数据源的摄取组件，从文件、网页、对象存储、数据库、SaaS 系统或 API 读取内容及来源元数据，并返回供下游处理的标准化文档对象。
快速了解
| 规范文档 | 官方规范 |
|---|
工作原理
把来源访问与内容解释分开
加载器负责向数据源认证、枚举记录、读取字节或字段，并输出统一文档契约。格式解析器负责把 PDF、HTML 或办公文档解释为文本与结构元素，两者并非同一职责：同一个来源连接器可以选择不同解析策略，同一个解析器也能服务不同来源。边界清晰后，来源重试和权限逻辑不会与抽取启发式规则纠缠在一起。
让同步可恢复并能传播删除
生产任务需要声明快照或游标、限制并发、区分可重试错误，并且只在下游持久化成功后写入检查点。稳定来源 ID 标识逻辑记录，版本号或内容哈希标识变化。加载器还应输出删除标记，或用本次来源清单与上次索引清单对账；只更新新增和变化内容而不删除消失记录，会让过期证据继续被检索。
从覆盖率、出处、新鲜度和隔离性验收
HTTP 请求成功或文件可读不等于摄取正确。应观测发现记录数与输出记录数、跳过和隔离项、重复来源 ID、版本延迟、解析交接失败、出处字段缺失及权限不一致，并用对抗样例验证租户隔离和最小权限。解析后的内容质量另行评估；加载器本身应对完整、及时、可归因且已授权的数据交付负责。
主要特点
- 连接外部来源并输出稳定、与后续实现解耦的文档契约
- 保留来源 ID、版本、出处、媒体类型、时间戳和权限信息
- 把来源访问与同步职责同解析、分块和嵌入职责分离
- 支持游标、分页、有界读取、重试、检查点和部分失败恢复
- 传播删除或墓碑信息，而不是只追加新内容
- 提供覆盖率、新鲜度、重复率和授权审计证据
常见用途
- 把内部 Wiki 增量同步到具备权限过滤的 RAG 知识库
- 加载版本化对象并保留 URI、校验和、负责人及访问元数据
- 按游标读取 SaaS 分页记录并正确处理限流和断点恢复
- 在重建索引前识别代码仓库中变化或已删除的文档
- 为受监管的客服或制度问答生成可引用、可审计的来源记录
示例
Loading code...常见问题
文档加载器和解析器是一回事吗？
不是。加载器访问来源，处理认证、枚举、分页、版本和元数据，再返回文档对象；解析器解释具体字节或标记格式。框架可以把二者封装在一起，但工程上保留独立契约更便于定位故障、替换解析器和复用连接器。
文档加载器至少应该保留哪些元数据？
至少保留稳定来源 ID、来源 URI、版本号或校验和、媒体类型、观测时间、来源修改时间与出处。企业系统通常还需要租户、负责人、数据分级和权限属性。元数据 Schema 应有版本，身份不明确时应拒绝写入，不能静默覆盖旧记录。
文档加载器如何实现增量摄取？
使用来源游标或快照枚举变化，对比稳定 ID 与版本，并在依赖的解析和索引都提交后再推进检查点。重试必须具备幂等性。同时应定期做全量清单对账，因为变更流可能过期、遗漏删除，或被供应商重置。
来源文档删除后应如何处理？
把删除视为明确的状态变化。加载器可以发出墓碑事件，也可以比较当前来源清单与上次索引清单，然后删除所有派生分块和检索记录。保留策略与法律留置应单独定义；停止继续加载并不会移除已有的过期证据。
文档加载器上线前应如何测试？
为分页边界、重复 ID、超大对象、损坏内容、限流、权限变化、检查点中断和删除准备固定测试样例；对比发现与输出清单，验证版本指纹确定性，并执行租户隔离测试。解析质量和检索质量需要在后续阶段独立评估。