Processar documentos com a função ML.PROCESS_DOCUMENT

Neste documento, descrevemos como usar a função ML.PROCESS_DOCUMENT com um modelo remoto para extrair insights úteis de documentos em um tabela de objetos.

Locais suportados

É necessário criar o modelo remoto usado neste procedimento na multirregião US ou EU. Execute a função ML.PROCESS_DOCUMENT na mesma região que o modelo remoto.

Permissões necessárias

• Para criar um processador da Document AI, você precisa do seguinte papel:

  • roles/documentai.editor

• Para criar uma conexão, você precisa da associação no seguinte papel:

  • roles/bigquery.connectionAdmin

• Para criar o modelo usando o BigQuery ML, você precisa das seguintes permissões:

  • bigquery.jobs.create
  • bigquery.models.create
  • bigquery.models.getData
  • bigquery.models.updateData
  • bigquery.models.updateMetadata

• Para executar a inferência, você precisa das seguintes permissões:

  • bigquery.tables.getData na tabela de objetos
  • bigquery.models.getData no modelo
  • bigquery.jobs.create

Antes de começar

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the BigQuery, BigQuery Connection API, and Document AI APIs.

   Enable the APIs

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the BigQuery, BigQuery Connection API, and Document AI APIs.

   Enable the APIs

Criar um processador

Crie um processador na Document AI para processar os documentos. O processador precisa ser de um tipo compatível.

Criar uma conexão

Crie uma Conexão de recursos do Cloud e tenha acesso à conta de serviço da conexão.

Selecione uma das seguintes opções:

Console

1. Acessar a página do BigQuery.

   Acessar o BigQuery

2. Para criar uma conexão, clique em Adicionar e em Conexões com fontes de dados externas.

3. Na lista Tipo de conexão, selecione Modelos remotos da Vertex AI, funções remotas e BigLake (Cloud Resource).

4. No campo ID da conexão, insira um nome para a conexão.

5. Clique em Criar conexão.

6. Clique em Ir para conexão.

7. No painel Informações da conexão, copie o ID da conta de serviço para uso em uma etapa posterior.

bq

1. Em um ambiente de linha de comando, crie uma conexão:

   bq mk --connection --location=REGION --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE CONNECTION_ID

   O parâmetro --project_id substitui o projeto padrão.

   Substitua:

   • REGION: sua região de conexão
   • PROJECT_ID: o ID do projeto do Google Cloud
   • CONNECTION_ID: um ID para sua conexão

   Quando você cria um recurso de conexão, o BigQuery cria uma conta de serviço do sistema exclusiva e a associa à conexão.

   Solução de problemas: se você receber o seguinte erro de conexão, atualize o SDK Google Cloud:

   Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
   

2. Recupere e copie o ID da conta de serviço para uso em uma etapa posterior:

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID

   O resultado será assim:

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "[e-mail]"}
   

Terraform

Anexe a seguinte seção ao seu arquivo main.tf.

 ## This creates a cloud resource connection.
 ## Note: The cloud resource nested object has only one output only field - serviceAccountId.
 resource "google_bigquery_connection" "connection" {
    connection_id = "CONNECTION_ID"
    project = "PROJECT_ID"
    location = "REGION"
    cloud_resource {}
}        

Substitua:

• CONNECTION_ID: um ID para sua conexão
• PROJECT_ID: o ID do projeto do Google Cloud
• REGION: sua região de conexão

Conceder acesso à conta de serviço

Selecione uma das seguintes opções:

Console

1. Acesse a página IAM e administrador.

   Acessar IAM e administrador

2. Clique em Conceder acesso.

   A caixa de diálogo Adicionar principais é aberta.

3. No campo Novos principais, digite o ID da conta de serviço que você copiou anteriormente.

4. No campo Selecionar um papel, selecione Document AI e, em seguida, Leitor da Document AI.

5. Clique em Adicionar outro papel.

6. No campo Selecionar papel, escolha Cloud Storage e, em seguida, Visualizador de objetos do Storage.

7. Clique em Salvar.

gcloud

Use o comando gcloud projects add-iam-policy-binding (em inglês).

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/documentai.viewer' --condition=None
gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/storage.objectViewer' --condition=None

Substitua:

• PROJECT_NUMBER: o número do projeto.
• MEMBER: o ID da conta de serviço que você copiou anteriormente.

Deixar de conceder a permissão resulta em um erro Permission denied.

Observação: se você criar o processador em um projeto diferente do bucket do Cloud Storage usado pela tabela de objetos, conceda os papéis do Identity and Access Management (IAM) da conta de serviço conforme a seguir:

• Conceda à conta de serviço o papel de Leitor da Document AI no projeto que contém o processador.
• Conceda à conta de serviço o papel de Leitor de objetos do Storage no projeto que contém o bucket do Cloud Storage.

crie um conjunto de dados

Crie um conjunto de dados para conter o modelo e a tabela de objetos. É necessário criar o conjunto de dados, a conexão e o processador de documentos na mesma região.

Criar um modelo

Crie um modelo remoto com um REMOTE_SERVICE_TYPE de CLOUD_AI_DOCUMENT_V1:

CREATE OR REPLACE MODEL
`PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
OPTIONS (
  REMOTE_SERVICE_TYPE = 'CLOUD_AI_DOCUMENT_V1',
  DOCUMENT_PROCESSOR = 'PROCESSOR_ID'
);

Substitua:

• PROJECT_ID: o ID do projeto.
• DATASET_ID: o ID do conjunto de dados para conter o modelo.
• MODEL_NAME: o nome do modelo
• REGION: a região usada pela conexão.
• CONNECTION_ID: o ID da conexão. Por exemplo, myconnection.

  Ao ver os detalhes da conexão no console do Google Cloud, o ID da conexão é o valor na última seção do ID da conexão totalmente qualificado, mostrado em ID da conexão, por exemplo, projects/myproject/locations/connection_location/connections/myconnection.

• PROCESSOR_ID: o ID do processador de documentos. Para encontrar esse valor, confira os detalhes do processador e observe a linha ID na seção Informações básicas.

Importante: é preciso especificar o ID do projeto para a conexão mesmo que ela esteja no projeto padrão.

Para ver as colunas de saída do modelo, clique em Acessar modelo no resultado da consulta após a criação do modelo. As colunas de saída são mostradas na seção Rótulos da guia Esquema.

Criar uma tabela de objetos

Crie uma tabela de objetos sobre um conjunto de documentos no Cloud Storage. Os documentos na tabela de objetos precisam ser de um tipo compatível.

Processar documentos

Processe todos os documentos com o ML.PROCESS_DOCUMENT:

SELECT *
FROM ML.PROCESS_DOCUMENT(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  TABLE `PROJECT_ID.DATASET_ID.OBJECT_TABLE_NAME`
);

Substitua:

• PROJECT_ID: o ID do projeto.
• DATASET_ID: o ID do conjunto de dados que contém o modelo.
• MODEL_NAME: o nome do modelo
• OBJECT_TABLE_NAME: o nome da tabela de objetos que contém os URIs dos documentos a serem processados.

Outra opção é processar alguns documentos com o ML.PROCESS_DOCUMENT:

SELECT *
FROM ML.PROCESS_DOCUMENT(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  (SELECT *
  FROM `PROJECT_ID.DATASET_ID.OBJECT_TABLE_NAME`
  WHERE FILTERS
  LIMIT NUM_DOCUMENTS
  )
);

Substitua:

• PROJECT_ID: o ID do projeto.
• DATASET_ID: o ID do conjunto de dados que contém o modelo.
• MODEL_NAME: o nome do modelo
• OBJECT_TABLE_NAME: o nome da tabela de objetos que contém os URIs dos documentos a serem processados.
• FILTERS: condições para filtrar os documentos que você quer processar nas colunas da tabela de objetos.
• NUM_DOCUMENTS: o número máximo de documentos que você quer processar.

Exemplos

Exemplo 1

O exemplo a seguir usa o analisador de despesas para processar os documentos representados pela tabela documents:

SELECT *
FROM ML.PROCESS_DOCUMENT(
  MODEL `myproject.mydataset.expense_parser`,
  TABLE `myproject.mydataset.documents`
);

Essa consulta retorna os relatórios de despesas analisadas, incluindo a moeda, o valor total, a data do recebimento e os itens de linha nos relatórios de despesas. A coluna ml_process_document_result contém a saída bruta do analisador de despesas, e a coluna ml_process_document_status contém todos os erros retornados pelo processamento de documentos.

Exemplo 2

O exemplo a seguir mostra como filtrar a tabela de objetos para escolher quais documentos processar e gravar os resultados em uma nova tabela:

CREATE TABLE `myproject.mydataset.expense_details`
AS
SELECT uri, content_type, receipt_date, purchase_time, total_amount, currency
FROM
  ML.PROCESS_DOCUMENT(
    MODEL `myproject.mydataset.expense_parser`,
    (SELECT * FROM `myproject.mydataset.expense_reports`
    WHERE uri LIKE '%restaurant%'));

A seguir

• Para informações sobre inferência de modelo no BigQuery ML, consulte Visão geral de inferência de modelo.
• Para informações sobre as funções e instruções SQL compatíveis com cada tipo de modelo, consulte Jornada do usuário completa de cada modelo.