> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/sdks/backend-sdk/ocr/installation/installation_instructions.md). # 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: ```bash 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: ```yaml 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: ```bash docker compose up ``` ## 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: ```init LICENSE_TYPE= # Tipo de licença, pode ser MACHINE, SHARED ou LOCAL LICENSE_BEHAVIOUR= # Comportamento da licença, pode ser ONLINE ou OFFLINE LICENSE_KEY= # Chave de licença LICENSE_ID= # ID do produto LICENSE_DATA= # Dados do produto LICENSE_URLS= # URLs do servidor de licença separadas por vírgula. Necessárias apenas se LICENSE_TYPE for LOCAL LICENSE_PATH_OFFLINE= # Arquivo local com dados para ativação offline. Necessário apenas se LICENSE_TYPE=MACHINE e LICENSE_BEHAVIOUR=OFFLINE ``` 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: ```json { "port": 6982, # Número da porta do serviço. # O número de usados pelo serviço REST, 1 por padrão. # Se o valor for definido como 0, o número de threads é detectado automaticamente. "number_of_threads": 1, "connection_timeout": 60, # Tempo de vida da conexão sem leitura ou escrita. # Defina o número máximo de solicitações que podem ser atendidas por uma conexão keep-alive. # Após o número máximo de solicitações ser atingido, a conexão é fechada. # O valor padrão 0 significa sem limite. "keep_alive_request_number": 0, # O tamanho máximo do corpo permitido nas solicitações em Mb. O valor padrão de 100 Mb. "client_max_body_size": 100, "logger_path": "./logs", # Defina o caminho para armazenar os arquivos de log. "logger_level": "trace", # Os valores possíveis são [trace|debug|info|warning|error|critical|off]. "logger_rotation": "daily", # Os valores possíveis são [hourly|daily]. "logger_max_files": 31, # O valor padrão 0 significa sem limite. "auth_enabled": false, # Ative uma proteção JWT para endpoints não públicos. "auth_jwt_secret": "", # Segredo compartilhado usado para validar tokens JWT HS256. "auth_accept_authorization_header": true, "auth_accept_api_key_header": false, "auth_api_key_header_name": "x-api-key", # Pasta que contém os modelos, templates e outros recursos. "config_path": "data", # Caminho para a pasta que contém os templates. "templates_path": "data/templates", # Versão do interpretador de documentos a ser usada. 1 versão legada, 2 nova versão. Por padrão, está definida como 1. "document_interpreter_version": 1, # Por padrão, é 0 (use o formato de saída legado). Se 1, use o universal. "document_interpreter_use_universal": 0, # Número de threads no pool para processar imagens de documentos em paralelo. # Por padrão, está definido como 2. Se o valor for definido como 0, o número de threads é detectado automaticamente. "processor_threads_pool_size": 2, # Número de threads no pool de fluxo para processar inferências em paralelo ao executar o pipeline. "pipeline_threads_pool_size": 1, # Número de threads no pool para criar interpretadores em paralelo. "global_threads_pool_size": 1, # Número máximo de threads usadas durante a inferência. Se 0, use tantos threads quanto núcleos. "max_inference_threads": 0, # Número de regiões de interesse de OCR que podem ser processadas simultaneamente. "ocr_latin_batch_size": 1, # Configuração do multi service "multi_service_base_url": "http://localhost", # URL base do multi service remoto. "multi_service_api_key": "fake_key", # API Key para autenticação com o multi service remoto. "multi_service_connection_timeout": 10000, # Timeout de conexão em milissegundos para solicitações ao multi service remoto. "multi_service_request_timeout": 60000, # Timeout de solicitação em milissegundos para solicitações ao multi service remoto. "multi_service_max_retries": 3, # Número máximo de tentativas ao multi service remoto. "multi_service_verify_ssl": true # Se deve verificar os certificados SSL ao conectar ao multi service remoto. } ``` 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 ` 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: ```json { "back": { "Address": "REDACTED", ... }, "front": { "DateOfBirth": "01/09/1972", ... } } ``` 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: ```json { "reader": { "0/MRZ/DateOfBirth": "01/09/1972", ... "1/ML/Address": "Redacted", ... } } ``` 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.