什么是 文档转换器（Document Transformer）？
更新于
文档转换器（Document Transformer）是把一个或多个已加载文档转换为零个或多个派生文档的管线组件，在索引前执行清洗、结构重组、增强、过滤、脱敏或分块。
快速了解
| 规范文档 | 官方规范 |
|---|
工作原理
把转换流程设计成有顺序的文档图
规范化、去样板、结构抽取、脱敏、增强、去重和分块并不能任意交换顺序。先移除版式可能破坏表格含义，先分块再脱敏会复制敏感文本，在生成 ID 后才增加检索相关字段则可能使身份计算遗漏关键输入。应明确顺序，让每个阶段返回新文档，并保留父来源 ID、来源版本、页码或章节定位及已执行转换的版本。
用确定性身份划分缓存边界
派生文档应根据父 ID、来源版本、转换版本、分块序号和规范化内容等明确输入生成稳定 ID。确定性身份让重试具备幂等性，也让管线缓存复用未变化结果。当解析器、分块器、嵌入模型或元数据 Schema 变化时，只失效受影响阶段并构建新索引版本，不要在无法追溯的语料库上直接覆盖。
先验收转换质量，再归因给检索
检查正文保留率、标题与表格结构、分块长度分布、空白和重复输出、血缘完整度、敏感信息泄漏及重复构建一致性，再在固定查询集上评估检索效果。检索指标变好不能抵消权限或引用丢失，流程可重现也不能证明分块边界有用；质量、治理与可复现性应是独立发布门槛。
主要特点
- 在加载后消费文档对象，并输出零个、一个或多个派生文档
- 按明确顺序执行清洗、抽取、脱敏、增强和分块
- 保留父文档身份、来源版本、定位信息、权限和转换版本
- 使用确定性输出 ID，支持可靠重试、缓存、对比与回滚
- 把转换失败同来源访问失败和持久化索引失败区分开
- 同时接受语料质量检查和下游检索评估
常见用途
- 按语义标题切分制度手册，同时保留章节与页码定位
- 在索引前移除网页导航和重复样板内容
- 在文本被复制到分块或嵌入前完成敏感字段脱敏
- 把表格抽取为检索单元，同时保留行与原始来源上下文
- 解析器、分块器或元数据 Schema 变化后只重建受影响输出
示例
Loading code...常见问题
文档转换器和文档加载器有什么区别？
加载器访问外部来源并创建忠实于来源的文档对象；转换器消费这些对象，再生成清洗、增强、过滤或切分后的派生文档。拆分契约后，团队可以重试来源访问而不重复全部转换，也能替换解析或分块策略而不重写连接器。
文档转换应该按什么顺序执行？
不存在适合所有语料的固定顺序，但依赖关系必须明确。结构抽取通常需要原始版式，脱敏必须早于敏感文本被复制到分块或嵌入，分块则依赖要保留的结构。应给有序管线加版本，并用真实语料测试，而不能假设所有转换都可交换。
文档转换器应该原地修改输入吗？
优先返回不可变结果或防御性副本。原地修改可能让并行阶段、缓存和重试观察到相互污染的元数据，使血缘难以审计。如果框架为性能允许修改，应明确对象所有权，并测试并发执行不会读取到半转换状态。
转换后的分块 ID 应如何设计？
根据父文档 ID、来源版本、转换版本、分块序号和规范化内容等声明过的身份输入生成稳定 ID，不能只使用会随版本变化的数组位置。父级定位应独立保存，以便引用和删除操作能把每个分块准确映射回来源。
如何评估文档转换器？
测量正文保留率、结构与表格保留、重复和空输出、分块分布、血缘完整度、脱敏泄漏及重复构建一致性；再用固定查询与相关性集合评估检索影响。不能只看一个平均分，还要人工检查具有代表性的失败样本。