文档 OCR

LibreChat 中的 OCR（光学字符识别）是一项用于从文件中提取文本的可选增强功能。

以文本形式上传

“Upload as Text”功能（在聊天界面中）的工作方式相同：

• 匹配 fileConfig.ocr.supportedMimeTypes 的文件将在可用时使用 OCR。
• 如果未配置 OCR，则回退到文本解析
• 对于包含文本的图像、扫描文档和复杂的 PDF 文件特别有用
• 处理优先级：OCR > STT > 文本解析
• 请参阅 Upload as Text 文档以了解详细信息。

文件上下文（针对智能体）

当您通过 Agent Builder 的 File Context 部分上传文件时：

1. 默认情况下，文本通过文本解析提取（如果已配置且文件匹配，则使用 OCR/STT）。
2. 提取的文本将作为 Agent 系统指令的一部分进行存储
3. Agent 可以在所有对话中引用此上下文
4. OCR 服务是可选的 - 该功能无需 OCR 即可通过文本解析正常工作

作为“文件上下文 (File Context)”上传的文件会被处理以提取文本，随后这些文本会被添加到 Agent 的系统指令中。这非常适合文档、代码文件、PDF 或包含文本的图像，在这些场景下，您需要将全文内容包含在 Agent 的指令中。

注意： 提取的文本已包含在 agent 的系统指令中。

可选的 OCR 配置

Agent File Context 和 Upload as Text 均可通过文本解析直接开箱即用。若要提升图像和扫描文档的提取质量，您可以选择配置 OCR 服务：

# librechat.yaml
endpoints:
  agents:
    capabilities:
      - "context"  # Enables both agent file context and upload as text
      - "ocr"      # Optionally enhances both with OCR

ocr:
  strategy: "mistral_ocr"
  apiKey: "${OCR_API_KEY}"
  baseURL: "https://api.mistral.ai/v1"
  mistralModel: "mistral-ocr-latest"

注意： context 功能默认处于启用状态。仅当您需要提高图像和扫描文档的提取质量时，才需要配置 OCR（即 ocr 功能）。

OCR 功能概述

LibreChat 中的 OCR 功能允许：

• 从图像和文档中提取文本
• 保持文档结构和格式
• 处理复杂的布局，包括多栏文本
• 处理表格、公式以及其他专业内容
• 处理多语言内容

OCR 策略

LibreChat 支持多种 OCR 策略，以满足不同的部署需求和要求。请选择最适合您的基础设施和合规性要求的策略。

1. Mistral OCR (默认)

默认策略直接使用 Mistral 的云 API 服务。这是最简单的设置，仅需要一个来自 Mistral 的 API key。

环境变量：

# `.env`
OCR_API_KEY=your-mistral-api-key
# OCR_BASEURL=https://api.mistral.ai/v1 # this is the default value

配置：

# `librechat.yaml`
ocr:
  mistralModel: "mistral-ocr-latest"       # Optional: Specify Mistral model, defaults to "mistral-ocr-latest"
  apiKey: "your-mistral-api-key"           # Optional: Defaults to OCR_API_KEY env variable
  baseURL: "https://api.mistral.ai/v1"     # Optional: Defaults to OCR_BASEURL env variable, or Mistral's API if no variable set
  strategy: "mistral_ocr"                  # Optional: Defaults to "mistral_ocr"

主要功能：

• 文档结构保留：保持格式，如标题、段落、列表和表格
• 多语言支持：处理多种语言和脚本的文本
• 复杂布局处理：处理多栏文本和混合内容
• 数学表达式识别：准确处理方程式和公式
• 高速处理：每分钟处理高达 2000 页

注意事项：

• 费用: 使用 Mistral OCR 可能会产生费用，因为它是一项付费 API 服务（尽管可能提供免费试用）。
• 数据隐私：通过 Mistral OCR 处理的数据受 Mistral 云环境及其服务条款的约束
• 文档限制：
  • 最大文件大小：50 MB
  • 最大文档长度：1,000 页

2. Azure Mistral OCR

对于使用 Azure AI Foundry 的组织，您可以将 Mistral OCR 模型部署到您的 Azure 基础设施中。目前，Mistral OCR 2503 模型已可用于 Azure 部署。

配置：

# `librechat.yaml`
ocr:
  mistralModel: "deployed-mistral-ocr-2503"              # Should match your Azure deployment name
  apiKey: "${AZURE_MISTRAL_OCR_API_KEY}"                 # Reference to your Azure API key in .env
  baseURL: "https://your-deployed-endpoint.models.ai.azure.com/v1"  # Your Azure endpoint
  strategy: "azure_mistral_ocr"                          # Use Azure strategy

Azure 模型信息： 您可以在此处探索 Azure AI Foundry 上提供的最新 Mistral OCR 模型（需要 Azure 订阅）：

https://ai.azure.com/explore/models/mistral-ocr-2503

3. Google Vertex AI Mistral OCR

对于使用 Google Cloud Platform 的组织，您可以将 Mistral OCR 模型部署到您的 Google Cloud Vertex AI 基础设施中。

环境变量：

# `.env`
# Option 1: File path
GOOGLE_SERVICE_KEY_FILE=/path/to/your/service-account-key.json

# Option 2: URL to fetch the key
GOOGLE_SERVICE_KEY_FILE=https://your-secure-server.com/service-account-key.json

# Option 3: Base64 encoded JSON
GOOGLE_SERVICE_KEY_FILE=eyJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsICJwcm9qZWN0X2lkIjogInlvdXItcHJvamVjdC1pZCIsIC4uLn0=

# Option 4: Raw JSON string
GOOGLE_SERVICE_KEY_FILE='{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "...",
  "client_id": "...",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "..."
}'

配置：

# `librechat.yaml`
ocr:
  mistralModel: "mistral-ocr-2505"                        # Model name as deployed in Vertex AI
  strategy: "vertexai_mistral_ocr"                       # Use Google Vertex AI strategy

设置要求：

1. 将 Mistral OCR 模型部署到 Google Vertex AI（例如 mistral-ocr-2505）
2. 创建一个具有适当权限的服务账号，以访问 Vertex AI endpoint
3. 下载服务账号 JSON 密钥文件
4. 使用支持的方法之一设置 GOOGLE_SERVICE_KEY_FILE 环境变量

4. 自定义 OCR（计划中）

计划在未来的版本中支持自定义 OCR 提供商和用户定义的策略。

5. 将文件上传至提供商 (直接)

对于受支持的 LLM 提供商（OpenAI, AzureOpenAI, Anthropic, Google 和 AWS Bedrock）及其各自的模型，现在可以将文件直接作为消息附件发送到提供商 API，从而允许提供商使用其原生的 OCR 实现来解析文件，只需在文件附件下拉菜单中选择 Upload to Provider 选项即可。

目前，上述所有五个提供商均支持图像和 PDF，其中 Google 在配合兼容的多模态模型使用时，还支持音频和视频文件。AWS Bedrock 额外支持 CSV、DOC、DOCX、XLS、XLSX、HTML、TXT 和 Markdown 文档。

详细配置

有关更多详细的配置选项，请参阅 OCR Config Object Structure。

OCR 处理配置

使用 fileConfig 控制哪些文件类型通过 OCR 进行处理：

fileConfig:
  ocr:
    supportedMimeTypes:
      - "^image/(jpeg|gif|png|webp|heic|heif)$"
      - "^application/pdf$"
      - "^application/vnd\\.openxmlformats-officedocument\\.(wordprocessingml\\.document|presentationml\\.presentation|spreadsheetml\\.sheet)$"
      - "^application/vnd\\.ms-(word|powerpoint|excel)$"
      - "^application/epub\\+zip$"

符合这些模式的文件将在以下情况下使用 OCR：

• 上传至 agent 文件上下文（如果已配置 OCR，则始终上传）
• 作为聊天中的文本上传（如果配置了 OCR；否则回退到文本解析）

有关文件处理配置的更多详细信息，请参阅 File Config Object Structure。

Agent 文件上下文的使用场景

Agent File Context 非常适合：

• 持久化智能体知识 (Persistent Agent Knowledge)：将文档、策略或参考资料添加到智能体的系统指令中
• Specialized Agents: 创建具有来自文档的特定领域知识的智能体
• 基于文档的助手 (Document-Based Assistants)：构建始终参考特定手册或指南的智能体
• 代码文件：在 Agent 指令中包含代码示例或库
• 结构化数据：添加 CSV、JSON 或其他结构化数据供智能体参考

当配置了 OCR 时，File Context 还会处理：

• 扫描文档处理：从图像或扫描的 PDF 中提取并存储文本
• 图像文本提取：从截图或文档照片中提取文本

对于聊天中临时的文档提问，请参阅 Upload as Text。

局限性

• 文本提取的准确性可能会因文件类型、图像质量、文档复杂度和文本清晰度而异。
• 某些特殊的格式或不常见的布局可能无法被完美保留
• 由于底层 AI 模型存在 Token 限制，非常大的文档可能会被截断。
• 为了在使用图像和扫描文档时获得最佳效果，请配置 OCR 服务

未来增强功能

LibreChat 计划在未来的版本中扩展 OCR 功能：

• 支持自定义 OCR 提供商
• 一个 user_provided 策略选项，允许用户选择他们偏好的 OCR 服务
• 与开源 OCR 解决方案的集成
• 增强的文档处理选项
• 对 OCR 设置进行更精细的控制
• Mistral 计划通过其云合作伙伴（如 GCP 和 AWS）提供 OCR API，并为有严格数据隐私要求的组织提供企业级自托管方案（来源）
• LibreChat 目前不会在其响应中包含来自 OCR 处理过程的已解析图像内容，尽管诸如 Mistral's OCR API may provide 之类的服务可能会在结果中提供这些内容。此功能可能会在未来的更新中得到支持。

有关配置 OCR 的更多信息，请参阅 OCR 配置对象结构。