视觉模式默认自动启用。如果您配置的模型已启用视觉支持，上传的文档将使用该格式可用的最丰富的处理管道。
格式支持矩阵
每种文档格式都有专门的处理管道。行为取决于模型是否支持视觉能力。工作原理
当用户将文档上传到对话时，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 以全局覆盖默认行为：
3. 按请求参数
在聊天 API 中传递doc_mode 参数来控制单个请求的处理：
auto 模式（默认）在模型具有 supports_vision=true 且文档是受益于视觉处理的类型时使用视觉。这是大多数部署的推荐设置。环境变量
令牌成本考虑
视觉内容消耗的令牌远多于纯文本。了解成本权衡有助于您适当配置系统。 粗略估计：成本优化建议
- 设置
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 会丢失什么？
PDF 视觉处理 vs. DOCX/PPTX 视觉处理
不同格式的视觉处理质量存在差异：- PDF — 智能逐页处理。富文本页面将文本内容和任何嵌入的图像分别提取，这在令牌效率上显著更高。扫描或仅包含图像的页面（例如拍摄的文档、扫描的合同）呈现为全页 PNG 图像以获得最大视觉保真度。这种自适应方法自动平衡质量和令牌成本。
- DOCX / PPTX — 文本内容加提取的嵌入图像。适用于大多数业务文档，但页面布局和格式不会保留。
自动回退
如果模型配置了视觉支持但在运行时实际拒绝图像内容，系统会自动重试请求，不包含文档图像。用户上传的图像（例如用户附加的截图）会保留在重试中 — 只有文档派生的图像会被移除。此回退机制可防止因视觉设置配置错误而导致的任务失败。如果您看到模型持续回退，请在 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 页将被渲染为图像。剩余页面仍可作为提取的文本使用。 - 图像质量很重要。 对于独立图像上传，尽可能使用高分辨率原始文件。压缩或低分辨率图像会降低模型提取细节的能力。