For the complete documentation index, see llms.txt. This page is also available as Markdown.

Instalação e implantação do serviço

1. Instalação e implantação

O serviço está dockerizado e existe uma imagem Docker em um repositório da Facephi. Para poder baixar a imagem, você deve fazer login da seguinte maneira:

docker login facephicorp.jfrog.io
user: username
pass: token

Baixe a imagem:

docker pull facephicorp.jfrog.io/docker-pro-fphi/facephi-ocr-service:#VERSION#

Onde #VERSION# é o número da versão que queremos baixar (por ex. 6.8.2).

2. docker-compose

Uma forma de implantar o serviço é criar um arquivo docker-compose.yml com o seguinte conteúdo:

version: '3.7'

services:
  ocr-service:
    image: facephicorp.jfrog.io/docker-pro-fphi/facephi-ocr-service:#VERSION#
    container_name: facephi-ocr-service
    ports:
      - "6982:6982"
    environment:
      # Proteção JWT opcional
      # - FACEPHI_OCR_REST_AUTH_ENABLED=true
      # - FACEPHI_OCR_REST_AUTH_JWT_SECRET=shared-secret
      # - FACEPHI_OCR_REST_AUTH_ACCEPT_AUTHORIZATION_HEADER=true
      # - FACEPHI_OCR_REST_AUTH_ACCEPT_API_KEY_HEADER=false
      # - FACEPHI_OCR_REST_AUTH_API_KEY_HEADER_NAME=x-api-key
    volumes:
      - ~/facephi_ocr_license:/service/license
      - ~/facephi_ocr_configuration:/service/config
      - ~/facephi_ocr_logs:/service/logs
      - ~/facephi_ocr_custom_templates:/service/custom_templates

Observe o volume montado no contêiner. Esse volume é usado para armazenar o arquivo de licença. O volume facephi_ocr_configuration é opcional, mas permite configurar o serviço. Consulte a seção 2.2 Serviço. O volume facephi_ocr_logs é opcional, mas permite salvar os logs no armazenamento local, evitando perdê-los quando o contêiner Docker é interrompido. O volume facephi_ocr_custom_templates é opcional, mas permite adicionar modelos personalizados de documentos. Você pode copiar seus modelos personalizados para esta pasta e depois configurar o serviço para que os utilize. Consulte a seção 3.2 Serviço.

Execute o seguinte comando, dentro da pasta onde se encontra o arquivo docker-compose.yml, para implantar o serviço:

3. Configuração da licença

Para usar este serviço, você precisa ter um arquivo de licença válido.

O arquivo de licença pode conter as seguintes informações:

O arquivo de licença pode ser passado como parâmetro para o serviço. Por padrão, o serviço procurará um arquivo chamado /service/license/license.lic. No caso do contêiner Docker, o arquivo de configuração poderia ficar em um volume montado em /service/license.

Para poder conectar aos nossos servidores de licença, você deve adicionar às regras do seu firewall as seguintes regras:

IP
Porta
Tipo

52.223.22.71

443

TCP/IP

35.71.188.31

443

TCP/IP

75.2.113.112

443

TCP/IP

99.83.149.57

443

TCP/IP

Em seguida, adicione as seguintes URLs à sua lista de permissões:

4. Configuração do serviço

O arquivo de configuração pode conter as seguintes informações padrão:

O arquivo de configuração pode ser passado como parâmetro para o serviço. Por padrão, o serviço procurará um arquivo chamado /service/config/config.json. No caso do contêiner Docker, o arquivo de configuração poderia ficar em um volume montado em /service/config.

Todos os parâmetros são opcionais. Se algum parâmetro não estiver presente, será usado o valor padrão em seu lugar.

A autenticação JWT é opcional e está desativada por padrão. As configurações de inicialização anteriores também podem ser fornecidas por variáveis de ambiente com o prefixo FACEPHI_OCR_REST_AUTH_:

  • FACEPHI_OCR_REST_AUTH_ENABLED

  • FACEPHI_OCR_REST_AUTH_JWT_SECRET

  • FACEPHI_OCR_REST_AUTH_ACCEPT_AUTHORIZATION_HEADER

  • FACEPHI_OCR_REST_AUTH_ACCEPT_API_KEY_HEADER

  • FACEPHI_OCR_REST_AUTH_API_KEY_HEADER_NAME

Quando o JWT está habilitado, GET /api/v1/version e GET /api/v1/health permanecem públicos. O restante dos endpoints requerem um JWT válido por meio de Authorization: Bearer <jwt> ou o cabeçalho de API key configurado.

As configurações de inicialização de JWT se aplicam somente quando o serviço é iniciado. GET /api/v1/config não expõe estes campos e POST /api/v1/config rejeita as tentativas de modificá-los.

4.1. document_interpreter_version

Há dois interpretadores distintos disponíveis para o processamento de documentos de identidade e documentos de estrangeiros.

Esses interpretadores diferem nos seguintes aspectos:

  • Países suportados

  • Formato de saída

  • Campos disponíveis

Países suportados

Versão 1:

  • Argentina (ARG)

  • México (MEX)

A versão 2 suporta oficialmente um conjunto mais amplo de países, entre eles:

  • Argentina (ARG)

  • Bolívia (BOL)

  • Brasil (BRA)

  • Canadá (CAN)

  • Chile (CHL)

  • Colômbia (COL)

  • Costa Rica (CRI)

  • República Dominicana (DOM)

  • Equador (ECU)

  • El Salvador (SLV)

  • Guatemala (GTM)

  • Honduras (HND)

  • Jordânia (JOR)

  • México (MEX)

  • Nicarágua (NIC)

  • Nigéria (NGA)

  • Panamá (PAN)

  • Paraguai (PRY): PRY I v3, PRY I v2

  • Peru (PER): PER I v5, PER I v2

  • África do Sul (ZAF)

  • Coreia do Sul (KOR)

  • Espanha (ESP)

  • Uganda (UGA)

  • Uruguai (URY)

  • Vietnã (VNM)

Formato de saída

Cada versão estrutura seus dados de saída de forma diferente.

A versão 1 organiza os dados extraídos usando as chaves front e back para distinguir entre a frente e o verso do documento:

A versão 2, por sua vez, usa uma estrutura aninhada sob a chave reader, com identificadores numéricos para representar cada face do documento (0 para a frente e 1 para o verso), junto com chaves de tipo caminho mais detalhadas:

A versão 2 também suporta a saída universal (document_interpreter_use_universal=1)

Campos disponíveis

Além das variações na estrutura de dados, pode haver diferenças nos próprios campos. Alguns campos podem existir apenas em um formato e, embora um campo apareça em todos os formatos, seu conteúdo pode mudar.

Atualizado