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
-
Um workspace que inclui o seguinte:
- Compute serverless ativado. Consulte requisitos do compute serverless.
- Unity Catalog ativado. Consulte Ativar um workspace para o Unity Catalog.
- Acesso a uma política de uso serverless com um orçamento diferente de zero.
-
Essa função está disponível apenas em algumas regiões, consulte disponibilidade da função de AI.
- A função
ai_parse_documenttambém está disponível para workspaces com o complemento Segurança e Compliance Aprimoradas.
- A função
Use a Análise de Documentos para analisar seus documentos e visualizar sua estrutura.
- Vá para
**Agentes** no painel de navegação esquerdo do seu workspace.
- Clique em Criar Agente > Análise de Documentos .
- 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.
- 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 .

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:
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:
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:
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.
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 |
|---|---|
| Uma string que identifica a solicitação. Cada linha do arquivo de saída tem o |
| O documento a ser analisado, no formato |
O seguinte arquivo de entrada tem duas solicitações:
{"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_idebody. O arquivo não tem linhas em branco. -
Cada
custom_idé uma string não vazia, e não há duas linhas com o mesmocustom_id. -
Cada
bodytem exatamente uma key,path.- Se um valor de
pathnão for uma string, o lote ainda será criado e essa solicitação falhará com o tipo de erroinvalid_request.
- Se um valor de
-
Um arquivo de entrada tem de 1 a 50.000 linhas e tem no máximo 200 MiB.
-
paramsnão possui parâmetros queai_parse_documentnã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:
-
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.
-
Crie um lote que inicia a execução de
ai_parse_document. Definainput_refpara o diretório ou para o arquivo de entrada eoutput_refpara 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:Bashcurl -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. -
Verifique o status do lote. O lote é finalizado quando
statuséCOMPLETED,CANCELLEDouFAILED:Bashcurl -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_refna resposta conterá seu caminho. -
Faça o download do arquivo de saída com a API de arquivos:
Bashcurl -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_refterminar com/ou nomear um diretório existente, a API gravará o arquivo de saída em<batch-name>_output.jsonlnesse 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: Otypee omessagedo 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:
{"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.