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

# 智能文档处理

> FIM One 如何处理上传的文档以供 AI 智能体理解，包括对 PDF、Office 文件和图像的自动视觉支持。

FIM One 自动处理上传的文档，以便 AI 智能体能够理解其内容。当模型支持视觉功能时，文档会以完整的视觉保真度进行处理——PDF 页面被渲染为图像，Office 文档中的嵌入图像会被提取并带有位置参考。当视觉功能不可用时，系统会回退到文本提取。

视觉内容在对话轮次中持久保存，因此模型在整个对话过程中都能保留来自上传文档的视觉上下文——不仅仅是上传文件的那一轮。

<Info>
  视觉模式默认自动启用。如果您配置的模型已启用视觉支持，上传的文档将使用该格式可用的最丰富的处理管道。
</Info>

## 格式支持矩阵

每种文档格式都有专门的处理管道。行为取决于模型是否支持视觉能力。

| 格式                                          | 文本提取                    | 视觉模式 (`supports_vision=ON`)                                | 回退模式 (`supports_vision=OFF`)                   |
| ------------------------------------------- | ----------------------- | ---------------------------------------------------------- | ---------------------------------------------- |
| **PDF**                                     | pdfplumber（逐页文本）        | 智能处理：文本丰富的页面提取文本 + 嵌入图像（令牌高效）；扫描/仅图像页面通过 PyMuPDF 渲染为全页 PNG | 仅文本提取；智能体通过 `read_uploaded_file` 工具读取          |
| **DOCX / DOC**                              | markitdown（Markdown 转换） | 通过 python-docx 提取嵌入图像，带有 `[Figure N]` 位置标记                 | 仅文本提取；图像丢失                                     |
| **PPTX / PPT**                              | markitdown（每张幻灯片的文本）    | 通过 python-pptx 提取嵌入图像，带有 `[Figure N]` 标记和幻灯片分隔符            | 仅文本提取；幻灯片视觉效果丢失                                |
| **XLSX / XLS**                              | markitdown（保留表格结构）      | 与文本模式相同（表格不受益于视觉能力）                                        | 相同                                             |
| **图像** (JPG, PNG, GIF, WebP)                | 不适用                     | 作为 `image_url` 视觉内容块发送                                     | 标注为 `[Attached image: filename]` — 模型知道但无法看到内容 |
| **文本文件** (TXT, MD, PY, JS, HTML, CSV, JSON) | 直接读取/解析                 | 不适用（文本就是文本）                                                | 相同                                             |

<Tip>
  **为了获得最大的视觉保真度**，在上传前将 DOCX 或 PPTX 文件导出为 PDF。PDF 视觉模式渲染完整的页面布局 — 文本、图像、图表和格式 — 全部在一张图像中。
</Tip>

## 工作原理

当用户将文档上传到对话时，FIM One 根据文件类型和模型功能运行处理管道：

<Steps>
  <Step title="文件类型检测">
    系统通过文件扩展名和 MIME 类型识别文档格式，然后选择适当的提取管道。每个上传的文件都用其 UUID `file_id` 标记，该标记被注入到消息上下文中，以便智能体可以通过 `read_uploaded_file` 工具直接访问它。
  </Step>

  <Step title="文本提取">
    无论是否支持视觉功能，系统始终提取文本内容。PDF 使用 pdfplumber 进行逐页文本提取。Office 格式使用 markitdown 进行 Markdown 转换。文本文件直接读取。
  </Step>

  <Step title="视觉处理（如果支持）">
    当模型具有 `supports_vision=true` 且文档是受支持的类型时：

    * **PDF（智能处理）**：分析每一页 — 文本丰富的页面分别提取文本和任何嵌入的图像（节省令牌），而扫描或仅图像页面以配置的 DPI 呈现为全页 PNG 以获得最大保真度
    * **DOCX / PPTX**：从文档 XML 中提取嵌入的图像，带有 `[Figure N]` 位置标记
    * **图像**：直接作为视觉内容块传递
  </Step>

  <Step title="内容组装">
    提取的文本和视觉内容被组装成模型期望的消息格式。文本和图像交错排列，以便模型可以关联视觉和文本信息。
  </Step>

  <Step title="多轮持久化">
    来自上传文件的视觉内容存储在消息元数据中，并在对话轮次中持久化。无论图像来自用户上传的照片还是从文档中提取，它们都保持可用，供模型在后续消息中引用。
  </Step>
</Steps>

## 视觉模式配置

有三种方式可以控制文档的处理方式，从最具体到最通用列出。

### 1. 按模型切换

导航到 **Admin > Models > Edit > Advanced**，切换 **Vision Support** 复选框。这是主要控制——它告诉系统特定模型是否可以接受图像内容。

### 2. 全局环境变量

在您的环境中设置 `DOCUMENT_PROCESSING_MODE` 以全局覆盖默认行为：

```bash theme={null}
# Use vision when the model supports it (default)
DOCUMENT_PROCESSING_MODE=auto

# Always attempt vision processing, regardless of model config
DOCUMENT_PROCESSING_MODE=vision

# Never use vision — text extraction only
DOCUMENT_PROCESSING_MODE=text
```

### 3. 按请求参数

在聊天 API 中传递 `doc_mode` 参数来控制单个请求的处理：

```json theme={null}
{
  "message": "Analyze this financial report",
  "doc_mode": "vision",
  "attachments": [...]
}
```

<Note>
  `auto` 模式（默认）在模型具有 `supports_vision=true` **且**文档是受益于视觉处理的类型时使用视觉。这是大多数部署的推荐设置。
</Note>

## 环境变量

| 变量                          | 默认值    | 描述                                                |
| --------------------------- | ------ | ------------------------------------------------- |
| `DOCUMENT_PROCESSING_MODE`  | `auto` | 处理策略：`auto`（在可用时使用视觉），`vision`（始终渲染），`text`（从不渲染） |
| `DOCUMENT_VISION_DPI`       | `150`  | PDF 渲染分辨率，单位为每英寸点数。更高的值会产生更好的质量，但消耗更多令牌           |
| `DOCUMENT_VISION_MAX_PAGES` | `20`   | 要渲染为图像的最大 PDF 页数。超过此限制的页面将回退到文本提取                 |

## 令牌成本考虑

视觉内容消耗的令牌远多于纯文本。了解成本权衡有助于您适当配置系统。

**粗略估计：**

| 场景               | 近似令牌成本              |
| ---------------- | ------------------- |
| 一页 PDF（150 DPI）  | 1,000 -- 2,000 令牌   |
| 10 页 PDF（视觉模式）   | 10,000 -- 20,000 令牌 |
| 同一 10 页 PDF（仅文本） | 2,000 -- 5,000 令牌   |
| 一个嵌入的 DOCX 图像    | 500 -- 1,500 令牌     |

<Warning>
  对于大型文档，视觉模式相比纯文本处理的成本可能增加 4--10 倍。使用 `DOCUMENT_VISION_MAX_PAGES` 限制呈现为图像的页数，并考虑为成本敏感的工作流使用 `text` 模式。
</Warning>

### 成本优化建议

* **设置 `DOCUMENT_VISION_MAX_PAGES`** 为合理的限制（例如 10）用于一般用途
* **将 `DOCUMENT_VISION_DPI`** 从 150 降低到 100（如果图像质量可接受）— 这可以将令牌消耗减少约 40%
* **对布局不重要的文档使用 `text` 模式**（例如纯文本报告、电子表格）
* **有选择地使用 `vision` 模式**处理视觉布局至关重要的文档（例如发票、表单、图表）

## 设计决策和限制

### 为什么不使用 LibreOffice 进行全页面渲染？

LibreOffice 可以生成 DOCX 和 PPTX 文件的像素完美页面渲染，但它会使 Docker 镜像增加约 4 GB。相反，FIM One 使用 python-docx 和 python-pptx 直接从文档 XML 中提取嵌入的图像——这两个库已经是 markitdown 的传递依赖项，因此不会增加任何额外的安装开销。

**权衡：** 我们获得了实际嵌入图像的完整质量，但失去了页面布局上下文。`[Figure N]` 位置标记有助于 LLM 关联文本和图像，但空间关系是近似的而非精确的。

### 没有 LibreOffice 会丢失什么？

| 丢失的元素                | 影响                        |
| -------------------- | ------------------------- |
| 文本格式（粗体、斜体、字体大小）     | LLM 仅接收纯文本                |
| 图像-文本空间位置            | `[Figure N]` 标记近似但不显示确切位置 |
| Office 生成的图表（未嵌入为图像） | 未提取 XML 定义的图表             |
| DOCX 中的页眉和页脚         | 由 markitdown 部分保留         |

### PDF 视觉处理 vs. DOCX/PPTX 视觉处理

不同格式的视觉处理质量存在差异：

* **PDF** — 智能逐页处理。富文本页面将文本内容和任何嵌入的图像分别提取，这在令牌效率上显著更高。扫描或仅包含图像的页面（例如拍摄的文档、扫描的合同）呈现为全页 PNG 图像以获得最大视觉保真度。这种自适应方法自动平衡质量和令牌成本。
* **DOCX / PPTX** — 文本内容加提取的嵌入图像。适用于大多数业务文档，但页面布局和格式不会保留。

**建议：** 对于视觉布局很重要的文档（表单、发票、具有复杂图形的幻灯片），请在上传前导出为 PDF。

### 自动回退

如果模型配置了视觉支持但在运行时实际拒绝图像内容，系统会自动重试请求，不包含文档图像。用户上传的图像（例如用户附加的截图）会保留在重试中 — 只有文档派生的图像会被移除。

<Info>
  此回退机制可防止因视觉设置配置错误而导致的任务失败。如果您看到模型持续回退，请在 **Admin > Models** 中检查其视觉支持配置。
</Info>

## 安全防护栏

### 文件完整性保护

当智能体无法读取文件（例如，未启用视觉功能的基于图像的 PDF）时，系统级护栏会阻止智能体用其他文件中的内容进行替换。没有这种保护，智能体可能会读取另一个可访问的文件，并将其内容呈现为来自目标文档。护栏确保当文件不可读时，智能体会诚实地报告限制，而不是从无关来源编造答案。

### 描述性错误指导

当 `read_uploaded_file` 工具无法读取文件时，错误消息包括：

* 检测到的文件类型以及无法处理的原因
* 如果文件是基于图像的，建议在模型上启用视觉功能
* 用户可以尝试的替代方法（例如，导出为不同格式）

这可以帮助用户理解和解决文件处理问题，而无需反复尝试。

## 最佳实践

### 对于管理员

* **有选择地启用视觉功能。** 仅在模型确实支持图像输入时启用 `supports_vision`。配置错误会浪费令牌在回退重试循环中。

* **从 `auto` 模式开始。** 默认行为对大多数部署都是正确的——视觉功能在有益且可用时使用。

* **监控令牌使用情况。** 启用视觉功能后，观察令牌消耗仪表板。如果成本意外激增，调整 `DOCUMENT_VISION_MAX_PAGES` 或 `DOCUMENT_VISION_DPI`。

* **使用预构建的沙箱镜像。** `Dockerfile.sandbox` 包含 AI 代码执行所需的常见数据科学包（pdfplumber、Pillow、pandas 等）。通过 `docker compose` 或使用 `docker build -f Dockerfile.sandbox -t fim-sandbox .` 手动构建，以确保代码执行在 `--network=none` 容器中正常工作。

### 对于最终用户

* **PDF 效果最佳。** 当视觉保真度很重要时，请在上传前将 Office 文档导出为 PDF。
* **电子表格可以按原样使用。** XLSX 文件被提取为结构化表格 — 视觉处理没有额外好处。
* **大型 PDF 可能会被截断。** 如果您的文档超过 `DOCUMENT_VISION_MAX_PAGES` 限制，只有前 N 页将被渲染为图像。剩余页面仍可作为提取的文本使用。
* **图像质量很重要。** 对于独立图像上传，尽可能使用高分辨率原始文件。压缩或低分辨率图像会降低模型提取细节的能力。