跳转到主要内容
FIM One 自动处理上传的文档，以便 AI 智能体能够理解其内容。当模型支持视觉功能时，文档会以完整的视觉保真度进行处理——PDF 页面被渲染为图像，Office 文档中的嵌入图像会被提取并带有位置参考。当视觉功能不可用时，系统会回退到文本提取。 视觉内容在对话轮次中持久保存，因此模型在整个对话过程中都能保留来自上传文档的视觉上下文——不仅仅是上传文件的那一轮。
视觉模式默认自动启用。如果您配置的模型已启用视觉支持，上传的文档将使用该格式可用的最丰富的处理管道。

​
格式支持矩阵

每种文档格式都有专门的处理管道。行为取决于模型是否支持视觉能力。
格式文本提取视觉模式 (supports_vision=ON)回退模式 (supports_vision=OFF)
PDFpdfplumber（逐页文本）智能处理：文本丰富的页面提取文本 + 嵌入图像（令牌高效）；扫描/仅图像页面通过 PyMuPDF 渲染为全页 PNG仅文本提取；智能体通过 read_uploaded_file 工具读取
DOCX / DOCmarkitdown（Markdown 转换）通过 python-docx 提取嵌入图像，带有 [Figure N] 位置标记仅文本提取；图像丢失
PPTX / PPTmarkitdown（每张幻灯片的文本）通过 python-pptx 提取嵌入图像，带有 [Figure N] 标记和幻灯片分隔符仅文本提取；幻灯片视觉效果丢失
XLSX / XLSmarkitdown（保留表格结构）与文本模式相同（表格不受益于视觉能力）相同
图像 (JPG, PNG, GIF, WebP)不适用作为 image_url 视觉内容块发送标注为 [Attached image: filename] — 模型知道但无法看到内容
文本文件 (TXT, MD, PY, JS, HTML, CSV, JSON)直接读取/解析不适用（文本就是文本）相同
为了获得最大的视觉保真度，在上传前将 DOCX 或 PPTX 文件导出为 PDF。PDF 视觉模式渲染完整的页面布局 — 文本、图像、图表和格式 — 全部在一张图像中。

​
工作原理

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

文件类型检测

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

文本提取

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

视觉处理（如果支持）

当模型具有 supports_vision=true 且文档是受支持的类型时：
  • PDF（智能处理）：分析每一页 — 文本丰富的页面分别提取文本和任何嵌入的图像（节省令牌），而扫描或仅图像页面以配置的 DPI 呈现为全页 PNG 以获得最大保真度
  • DOCX / PPTX：从文档 XML 中提取嵌入的图像，带有 [Figure N] 位置标记
  • 图像：直接作为视觉内容块传递
4

内容组装

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

多轮持久化

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

​
视觉模式配置

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

​
1. 按模型切换

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

​
2. 全局环境变量

在您的环境中设置 DOCUMENT_PROCESSING_MODE 以全局覆盖默认行为： 
# 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 参数来控制单个请求的处理： 
{
  "message": "Analyze this financial report",
  "doc_mode": "vision",
  "attachments": [...]
}
auto 模式（默认）在模型具有 supports_vision=true 且文档是受益于视觉处理的类型时使用视觉。这是大多数部署的推荐设置。

​
环境变量

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

​
令牌成本考虑

视觉内容消耗的令牌远多于纯文本。了解成本权衡有助于您适当配置系统。 粗略估计：
场景近似令牌成本
一页 PDF（150 DPI）1,000 — 2,000 令牌
10 页 PDF（视觉模式）10,000 — 20,000 令牌
同一 10 页 PDF（仅文本）2,000 — 5,000 令牌
一个嵌入的 DOCX 图像500 — 1,500 令牌
对于大型文档，视觉模式相比纯文本处理的成本可能增加 4—10 倍。使用 DOCUMENT_VISION_MAX_PAGES 限制呈现为图像的页数，并考虑为成本敏感的工作流使用 text 模式。

​
成本优化建议

  • 设置 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。

​
自动回退

如果模型配置了视觉支持但在运行时实际拒绝图像内容，系统会自动重试请求，不包含文档图像。用户上传的图像（例如用户附加的截图）会保留在重试中 — 只有文档派生的图像会被移除。
此回退机制可防止因视觉设置配置错误而导致的任务失败。如果您看到模型持续回退，请在 Admin > Models 中检查其视觉支持配置。

​
安全防护栏

​
文件完整性保护

当智能体无法读取文件（例如，未启用视觉功能的基于图像的 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 页将被渲染为图像。剩余页面仍可作为提取的文本使用。
  • 图像质量很重要。 对于独立图像上传，尽可能使用高分辨率原始文件。压缩或低分辨率图像会降低模型提取细节的能力。