Estrutura do Objeto de Configuração de OCR

Visão geral

O objeto ocr permite que você configure as definições de Reconhecimento Óptico de Caracteres (OCR) para a aplicação, possibilitando a extração de texto a partir de imagens. Esta seção fornece um detalhamento da estrutura do objeto ocr.

Existem 4 campos principais em ocr:

mistralModel
apiKey
baseURL
strategy

Notas:

Se estiver usando a API de OCR da Mistral, você não precisa editar seu arquivo librechat.yaml.
- Você só precisa das seguintes variáveis de ambiente para começar: OCR_API_KEY e OCR_BASEURL.
A funcionalidade de OCR permite que a aplicação extraia texto de imagens, que pode então ser processado por modelos de IA.
A estratégia padrão é mistral_ocr, que utiliza as capacidades de OCR da Mistral.
Você também pode configurar um serviço de OCR personalizado definindo a estratégia como custom_ocr.
Modelos Mistral OCR implantados no Azure podem ser usados definindo a estratégia como azure_mistral_ocr.
Modelos Mistral OCR implantados no Google Vertex AI podem ser usados definindo a estratégia como vertexai_mistral_ocr.
- Requer que a variável de ambiente GOOGLE_SERVICE_KEY_FILE seja definida com as credenciais da conta de serviço
- A service key pode ser fornecida como: caminho de arquivo, URL, JSON codificado em base64 ou string JSON bruta
- O ID do projeto e a localização são extraídos automaticamente das credenciais da conta de serviço
A extração de texto local está disponível via document_parser, que extrai texto de arquivos PDF, DOCX, XLS/XLSX e OpenDocument sem qualquer API externa.
- Usa pdfjs-dist, mammoth e SheetJS localmente — não é necessária chave de API ou URL base
- Apenas o campo strategy é obrigatório; apiKey, baseURL e mistralModel são ignorados
Se estiver usando o Mistral OCR padrão, você pode, opcionalmente, especificar um modelo Mistral específico para usar.
O parsing de variáveis de ambiente é suportado para os parâmetros apiKey, baseURL e mistralModel.
Uma opção de estratégia user_provided está planejada para versões futuras, mas ainda não foi implementada.

Análise Automática de Documentos (Nenhuma Configuração Necessária)

O document_parser integrado é executado automaticamente para uploads de arquivos de agentes, mesmo quando nenhum bloco ocr está configurado no seu librechat.yaml. Isso significa que arquivos PDF, DOCX, XLS/XLSX e ODS são analisados nativamente, sem necessidade de configuração.

A lógica de resolução funciona da seguinte forma:

Nenhuma configuração de ocr existe — Quando um arquivo de contexto de agente é enviado e seu tipo MIME corresponde a um tipo de documento suportado (PDF, DOCX, Excel, ODS), o document_parser é usado diretamente. Nenhuma verificação de capacidade de OCR é necessária para o agente.
ocr config exists — A estratégia configurada (por exemplo, mistral_ocr) é tentada primeiro. Se a estratégia configurada falhar em tempo de execução, o document_parser é usado como fallback para que a extração de texto ainda tenha sucesso para tipos de documento suportados.
Nenhum dos dois obtém sucesso — Se tanto a estratégia configurada quanto o analisador de documentos falharem (por exemplo, o arquivo é um PDF apenas de imagem sem texto incorporado), um erro é retornado sugerindo que um serviço de OCR é necessário.

O document_parser lida apenas com documentos baseados em texto. Para PDFs baseados em imagem ou documentos digitalizados, você ainda precisa de uma estratégia de OCR configurada (como mistral_ocr) para extrair texto das imagens dentro desses arquivos.

Exemplo

ocr:
  mistralModel: "mistral-ocr-latest"
  apiKey: "your-mistral-api-key"
  strategy: "mistral_ocr"

Exemplo com OCR personalizado:

ocr:
  apiKey: "your-custom-ocr-api-key"
  baseURL: "https://your-custom-ocr-service.com/api"
  strategy: "custom_ocr"

Exemplo com Azure Mistral OCR:

ocr:
  mistralModel: "deployed-mistral-ocr-2503" # should match deployment name on Azure
  apiKey: "${AZURE_MISTRAL_OCR_API_KEY}" # arbitrary .env var reference
  baseURL: "https://your-deployed-endpoint.models.ai.azure.com/v1" # hardcoded, can also be .env var reference
  strategy: "azure_mistral_ocr"

Exemplo com Google Vertex AI Mistral OCR:

ocr:
  mistralModel: "mistral-ocr-2505" # model name as deployed in Vertex AI
  strategy: "vertexai_mistral_ocr"

Exemplo com o processador de documentos local (nenhuma API externa necessária):

ocr:
  strategy: "document_parser"

mistralModel

Key	Type	Description	Example
mistralModel	String	O modelo Mistral a ser usado para processamento de OCR. Para implantações Azure, isso deve corresponder ao nome da sua implantação. Para Google Vertex AI, isso deve corresponder ao nome do modelo em sua implantação.	Optional. Specifies which Mistral model should be used when the strategy is set to mistral_ocr, azure_mistral_ocr, or vertexai_mistral_ocr.

ocr:
  mistralModel: "mistral-ocr-latest"

Para implantações no Azure:

ocr:
  mistralModel: "deployed-mistral-ocr-2503" # Your Azure deployment name

Para implantações do Google Vertex AI:

ocr:
  mistralModel: "mistral-ocr-2505" # Your Vertex AI model name

apiKey

Key	Type	Description	Example
apiKey	String	A chave de API para o serviço de OCR. Não é usada para o Google Vertex AI (utiliza autenticação de conta de serviço via GOOGLE_SERVICE_KEY_FILE).	Optional. Defaults to the environment variable OCR_API_KEY if not specified.

ocr:
  apiKey: "your-ocr-api-key"

baseURL

Key	Type	Description	Example
baseURL	String	A URL base para a API do serviço de OCR. Para o Google Vertex AI, ela é construída automaticamente a partir das credenciais da conta de serviço.	Optional. Defaults to the environment variable OCR_BASEURL if not specified.

ocr:
  baseURL: "https://your-ocr-service.com/api"

strategy

Key	Type	Description	Example
strategy	String	A estratégia de OCR a ser utilizada.	Determines which OCR service to use. Options are "mistral_ocr", "azure_mistral_ocr", "vertexai_mistral_ocr", "document_parser", or "custom_ocr". Defaults to "mistral_ocr".

ocr:
  strategy: "custom_ocr"

Estratégias Disponíveis:

mistral_ocr: Usa as capacidades de OCR da Mistral através da API da Mistral padrão.
azure_mistral_ocr: Usa modelos Mistral OCR implantados no Azure AI Foundry.
vertexai_mistral_ocr: Usa modelos Mistral OCR implantados no Google Cloud Vertex AI.
document_parser: Usa extração de texto local para arquivos PDF, DOCX, XLS/XLSX e OpenDocument. Nenhuma API externa é necessária. Também é executado automaticamente para uploads de arquivos de agentes quando nenhuma configuração de ocr está presente, e como um fallback quando uma estratégia de OCR configurada falha.
custom_ocr: Usa um serviço de OCR personalizado especificado pela baseURL (ainda não implementado).