> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 文档转换器

**文档转换器（Document Transformer）** 是 XpertAI [知识流水线](/docs/ai/knowledge/pipeline/)（Knowledge Pipeline）中的核心节点之一，用于将原始文档数据通过 [插件](/docs/plugin/) 的方式进行智能化的解析、提取与结构化转换。它能够将来自不同数据源的非结构化内容（如 PDF、Word、网页、图像、音频等）自动处理为知识库可理解的标准化文档对象，为后续的分块（Chunking）、索引（Embedding）与检索（Retrieval）提供清晰一致的输入。

在知识流水线中，文档转换器节点的主要目标是：

* 将不同格式的文档转换为统一的结构化知识文档；
* 对内容进行 **语义解析、OCR识别、文本提取与元数据增强**；
* 结合插件策略，实现对多种文件类型和来源的自适应处理；
* 支持测试模式（预览）与生产模式（正式发布）的转换流程；

***

## 工作原理

当知识流水线执行至文档转换节点时，系统会自动：

1. **读取上游节点输出的文档数据**（例如来自文件上传节点、网页抓取节点、或外部集成数据源）；
2. 根据知识库中配置的文档转换 [插件](/docs/plugin/)，选择合适的 **文档处理策略（Transformer Strategy）**；
3. 按照节点配置执行转换逻辑，包括：

   * 文本抽取（Text Extraction）
   * 光学字符识别（OCR）
   * 图片内容识别与描述生成（VLM / 多模态处理）
   * 格式标准化（Markdown、JSON、HTML等）
   * 元数据生成与清洗
4. 将转换结果回写到知识库，生成状态为 **“已转换（Transformed）”** 的文档版本；
5. 若转换失败，则自动记录错误状态与信息，便于在流水线中追踪与恢复。

***

## 应用场景

文档转换器节点在企业知识管理和智能文档处理场景中具有广泛应用价值：

* **OCR 场景**：对扫描版 PDF、影像报告、纸质文档扫描件自动识别文字；
* **结构提取**：从 Word、PPT、HTML 页面中抽取正文、标题、表格等关键内容；
* **富媒体处理**：识别并转译文档中的图片、图表或公式，使之可参与语义搜索；
* **网页与知识源同步**：对网页、在线文档（如 Feishu Docs、Notion 等）执行结构化同步；
* **内容清洗与增强**：对文本进行正则清洗、语义标注、命名实体识别等；
* **数据归档**：在知识库中形成标准化可追溯的知识资产，用于 RAG 检索或多智能体问答。

***

## 节点特性

| 特性       | 描述                                |
| -------- | --------------------------------- |
| **节点类型** | Processor（处理节点）                   |
| **节点名称** | 文档转换器（Document Transformer）       |
| **输入**   | 上游节点输出的原始文档对象                     |
| **输出**   | 已转换文档对象（结构化文档 + 元数据 + 分块）         |
| **状态更新** | 自动更新文档状态为 `TRANSFORMED` 或 `ERROR` |
| **测试模式** | 支持预览模式下的转换调试（不落库）                 |
| **错误处理** | 自动捕获转换错误并写入任务日志                   |
| **兼容性**  | 支持多种插件策略（文本、图片、网页、富媒体等）           |

***

## 插件机制

文档转换节点的强大之处在于其 **插件化架构**。
XpertAI 提供一套开放的文档转换插件接口（`DocumentTransformerStrategy`），允许官方与社区开发者实现以下类型的插件：

* 📄 **通用文本转换插件**：处理 PDF、DOCX、TXT 等常见文档；
* 🌐 **网页解析插件**：将网页内容结构化为知识文档；
* 🧠 **多模态识别插件**：调用视觉语言模型（如 GPT-4V、PaddleOCR、MinerU）理解图片与图表；
* 🧩 **企业集成插件**：连接 Feishu Docs、Notion、SharePoint、Confluence 等平台；
* ⚙️ **自定义脚本插件**：由用户编写的内容清洗、格式转换、字段提取逻辑。

插件执行前会根据节点上下文和系统环境变量完成授权验证，包括：

* API Key 授权；
* OAuth 应用授权；
* 临时文件目录（`tempDir`）隔离；
* 文件系统与外部集成权限控制（如访问云盘、远程文档库等）。

这种开放式机制让文档转换节点可以灵活扩展、快速适配不同企业的数据场景。

***

## 工作模式与阶段

文档转换节点支持两种运行模式：

| 模式             | 说明                                     |
| -------------- | -------------------------------------- |
| **预览模式（Test）** | 在知识流水线调试阶段执行，不保存结果，仅用于查看转换效果。          |
| **生产模式（Prod）** | 在发布后的正式知识库更新阶段执行，结果将持久化到数据库并可供索引与检索使用。 |

不同阶段的执行路径一致，区别仅在于：

* **是否写入知识库表结构；**
* **是否触发索引与任务状态更新；**
* **是否生成可供 AI 检索的持久化 Chunk 数据。**

***

## 转换结果与后续节点衔接

转换完成后，节点会输出标准化的知识文档对象：

* 每个文档包含结构化的 `metadata` 信息；
* 包含经分块处理的 `chunks`（用于向量索引与语义检索）；
* 状态为 `TRANSFORMED`；
* 同时输出 `Error` 通道以捕获异常。

下游节点（如 **分块器 Chunker**、**索引器 Embedder**、**召回测试 Recall Tester** 等）可直接引用这些输出进行后续流程。

***

## 小结

**文档转换器节点** 是 XpertAI 知识流水线中的“智能内容处理中心”。
它通过插件化机制和自动化管控，将复杂多样的原始文件转化为结构化、标准化、可检索的知识文档，是连接企业数据源与 AI 知识库的关键桥梁。

无论是构建企业知识库、训练专属大模型、还是为数字专家提供语义上下文，
文档转换器节点都是实现“**让非结构化数据变成可用知识资产**”的重要一环。