Pular para o conteúdo principal

Análise de Documentos

A Análise de Documentos usa técnicas de pesquisa de última geração para extrair e visualizar dados estruturados de uma ampla gama de tipos de documentos, incluindo, mas não se limitando a PDFs, imagens, documentos do Word (DOC/DOCX) e arquivos do PowerPoint (PPT/PPTX). Ele é projetado para lidar com disposições complexas, como tabelas, gráficos e conteúdo misto de texto e imagem.

A análise de documentos está disponível por meio da UI do Agent Bricks, no SQL, com a API REST e com a API Assíncrona (Beta).

Criar um agente de análise de documentos na IU​

Requisitos​

Use a Análise de Documentos para analisar seus documentos e visualizar sua estrutura.

  1. Vá para Ícone de Agentes. **Agentes** no painel de navegação esquerdo do seu workspace.
  2. Clique em Criar Agente > Análise de Documentos .
  3. Selecione seu documento de origem. É possível optar por fazer o upload de um arquivo ou selecionar um de um catálogo existente do Unity Catalog. Formatos compatíveis incluem: PDF, imagens, DOC/DOCX e PPT/PPTX.
  4. Clique em **Analisar documento**.

A análise do seu documento pode levar alguns minutos. Quando concluído, a Análise de Documentos mostra o documento de origem à esquerda e o documento analisado à direita. É possível escolher visualizar o documento analisado como texto Formatado ou JSON Bruto .

Interface do usuário de análise de documentos mostrando documento de origem e analisado lado a lado

Processar e consultar resultados​

Para visualizar a consulta ai_parse_document e executá-la em mais documentos, clique em Usar Agente e escolha entre executar a consulta do Editor SQL ou do Notebook. Você pode editar a consulta para apontar para o volume ou tabela em que seus documentos estão.

Para preparar a saída analisada para recuperação (RAG), use ai_prep_search (Beta) downstream.

Analisar documentos em SQL​

Chame ai_parse_document em SQL para analisar documentos em escala:

SQL
SELECT
ai_parse_document(
content,
map('version', '2.0')
) AS parsed
FROM READ_FILES('/Volumes/my_catalog/my_schema/my_documents', format => 'binaryFile');

Consulte a referência de SQL ai_parse_document.

Analisar documentos com a API REST​

Use a API REST para analisar documentos de aplicativos, serviços e fluxos de trabalho de automação. Consulte a documentação da API REST para obter referência.

ai_parse_document REST API requests are limited to 100 pages per document.

O limite de taxa default para solicitações à API REST de ai_parse_document é de 250 solicitações por minuto por workspace. Entre em contato com sua equipe de account da Databricks para solicitar um limite maior.

ai_parse_document lê sua entrada de um volume do Unity Catalog. O exemplo a seguir faz o upload de um PDF local para um volume com a Files API e, em seguida, o analisa.

Primeiro, faça upload do documento para um volume:

Bash
curl -X PUT "$DATABRICKS_HOST/api/2.0/fs/files/Volumes/my_catalog/my_schema/my_volume/invoice.pdf?overwrite=true" \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
-H "Content-Type: application/octet-stream" \
--data-binary @invoice.pdf

Em seguida, analise o documento upload passando o caminho do volume como content:

Bash
curl -X POST "$DATABRICKS_HOST/api/2.0/ai-functions/ai-parse-document" \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"content": "/Volumes/my_catalog/my_schema/my_volume/invoice.pdf"
}'

Analise documentos com a Asynchronous API (Beta)​

Para processamento em lote, o Databricks recomenda tarefas da Função AI no Lakeflow Jobs. Para analisar documentos em um job, use uma tarefa ai_parse_document, que faz o seguinte:

  • Realiza a execução do processamento em segundo plano e grava os resultados em uma tabela do Unity Catalog, para que você não precise enviar lotes, verificar seu status ou fazer download de arquivos de saída.
  • Processa apenas os documentos que são novos ou alterados desde a execução anterior.
  • Mostra o progresso de cada execução e quantos inputs foram bem-sucedidos e falharam.

Use a API assíncrona do AI Functions (Beta) se desejar integrar o processamento em um aplicativo existente ou em um orquestrador externo e gerenciar as solicitações e os resultados você mesmo.

info

Beta

Esse recurso está em Beta. Para usá-lo, um administrador do Workspace deve ativar a API Assíncrona de AI Functions na página Prévias . Consulte Gerenciar prévias do Databricks.

Para os campos de solicitação e resposta, e para as solicitações de cancelamento e listagem de lotes, consulte a referência da API Assíncrona.

Diretório ou arquivo de entrada​

A entrada de um lote ai_parse_document é uma das seguintes:

  • Um diretório em um volume do Unity Catalog. O lote analisa cada arquivo no diretório e em seus subdiretórios, portanto, coloque apenas os documentos a serem analisados lá. A API faz uma solicitação para cada arquivo, com o caminho do arquivo como seu custom_id.
  • Um arquivo de entrada JSONL em um volume que lista os documentos a serem analisados. Use um arquivo de entrada para analisar apenas alguns dos documentos em um diretório ou para dar a cada documento o seu próprio custom_id.

Cada linha de um arquivo de entrada é uma solicitação, um objeto JSON com exatamente os seguintes campos:

campo

Descrição

custom_id

Uma string que identifica a solicitação. Cada linha do arquivo de saída tem o custom_id de sua solicitação, portanto, use um valor com o qual você possa combinar os resultados.

body

O documento a ser analisado, no formato {"path": "/Volumes/..."}, onde path é o caminho do volume do documento.

campo

Descrição

custom_id

Uma string que identifica a solicitação. Cada linha do arquivo de saída tem o custom_id de sua solicitação, portanto, use um valor com o qual você possa combinar os resultados.

body

O documento a ser analisado, no formato {"path": "/Volumes/..."}, onde path é o caminho do volume do documento.

O seguinte arquivo de entrada tem duas solicitações:

JSON
{"custom_id": "invoice-001", "body": {"path": "/Volumes/my_catalog/my_schema/my_volume/invoices/invoice-001.pdf"}}
{"custom_id": "invoice-002", "body": {"path": "/Volumes/my_catalog/my_schema/my_volume/invoices/invoice-002.pdf"}}

ai_parse_document não precisa de outros parâmetros além do documento. Para definir opções de função, como version ou pageRange, coloque-as em options em params quando você criar o lote, por exemplo "params": {"options": {"version": "2.0"}}. Escreva cada nome de opção em camelCase, por exemplo imageOutputPath em vez de image_output_path. As opções se aplicam a cada documento no lote. Para saber o que cada opção faz, consulte a referência da API REST do AI Parse Document.

Quando você cria um lote, a API verifica a entrada e params primeiro. Se a entrada ou params quebrar uma das seguintes regras, a solicitação falha com HTTP 400 e nenhum lote é criado:

  • Um diretório possui de 1 a 50.000 arquivos.

    • Para processar mais documentos, divida-os em vários diretórios ou arquivos de entrada e crie um lote para cada um.
  • Um arquivo de entrada é codificado em UTF-8 e cada linha é um objeto JSON com exatamente os campos custom_id e body. O arquivo não tem linhas em branco.

  • Cada custom_id é uma string não vazia, e não há duas linhas com o mesmo custom_id.

  • Cada body tem exatamente uma key, path.

    • Se um valor de path não for uma string, o lote ainda será criado e essa solicitação falhará com o tipo de erro invalid_request.
  • Um arquivo de entrada tem de 1 a 50.000 linhas e tem no máximo 200 MiB.

  • params não possui parâmetros que ai_parse_document não aceita.

Para um problema em uma linha do arquivo de entrada, a mensagem de erro fornece o número da linha e a regra, por exemplo Batch input line 3 custom_id must be unique. Se você não consegue ler a entrada ou um volume que um path nomeia, ou não consegue gravar em output_ref, a solicitação falha com HTTP 403.

A API lista o diretório, ou copia o arquivo de entrada, quando cria o lote. Os arquivos que você adiciona ao diretório posteriormente não fazem parte do lote.

Execução de lotes​

Para analisar documentos com a API assíncrona:

  1. Faça upload dos documentos para um diretório em um volume do Unity Catalog. Para analisar apenas alguns deles, crie também um arquivo de entrada que os liste e faça upload dele para um volume.

  2. Crie um lote que inicia a execução de ai_parse_document. Defina input_ref para o diretório ou para o arquivo de entrada e output_ref para um diretório de volume ou um novo caminho de arquivo para o arquivo de saída. O exemplo a seguir analisa um diretório:

    Bash
    curl -X POST "$DATABRICKS_HOST/api/2.0/ai-functions/batches" \
    -H "Authorization: Bearer $DATABRICKS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
    "endpoint": "ai_parse_document",
    "input_ref": "/Volumes/my_catalog/my_schema/my_volume/invoices/",
    "output_ref": "/Volumes/my_catalog/my_schema/my_volume/output/"
    }'

    A resposta contém os lotes name. Use-o no lugar de <batch-name> nos próximos passos. Por default, um workspace pode ter até 20 lotes não concluídos por vez, em todos os usuários. Se estiver no limite, a solicitação falha com HTTP 409. Crie o lote novamente após outro lote terminar ou ser cancelado.

  3. Verifique o status do lote. O lote é finalizado quando status é COMPLETED, CANCELLED ou FAILED:

    Bash
    curl -X GET "$DATABRICKS_HOST/api/2.0/ai-functions/batches/<batch-name>" \
    -H "Authorization: Bearer $DATABRICKS_TOKEN"

    Quando o arquivo de saída estiver pronto, output_ref na resposta conterá seu caminho.

  4. Faça o download do arquivo de saída com a API de arquivos:

    Bash
    curl -X GET "$DATABRICKS_HOST/api/2.0/fs/files/Volumes/my_catalog/my_schema/my_volume/output/<batch-name>_output.jsonl" \
    -H "Authorization: Bearer $DATABRICKS_TOKEN" \
    -o output.jsonl

Arquivo de saída​

A API assíncrona grava o arquivo de saída de um lote ai_parse_document no local em output_ref:

  • Se output_ref terminar com / ou nomear um diretório existente, a API gravará o arquivo de saída em <batch-name>_output.jsonl nesse diretório. Vários lotes podem compartilhar um diretório de saída.
  • Caso contrário, output_ref é o caminho do arquivo de saída. O arquivo não deve existir quando você criar o lote.

O arquivo de saída tem uma linha para cada documento. Cada linha tem o custom_id do seu pedido e um dos campos seguintes:

  • response: O resultado da solicitação. Tem os mesmos campos que a resposta da API REST do AI Parse Document.
  • error: O type e o message do erro, se a solicitação falhou. Se o lote foi cancelado antes que a execução da solicitação ocorresse, o tipo é cancelled.

Para um arquivo de entrada, as linhas estão na mesma ordem que o arquivo de entrada. Para um diretório, o custom_id de cada linha é o caminho do documento, e as linhas podem estar em qualquer ordem:

Text
{"custom_id": "/Volumes/my_catalog/my_schema/my_volume/invoices/invoice-001.pdf", "response": {...}}
{"custom_id": "/Volumes/my_catalog/my_schema/my_volume/invoices/invoice-002.pdf", "error": {"type": "request_failed", "message": "..."}}

Limitações​

Consulte limitações deai_parse_document.