Configurar pré-requisitos para tarefas de enriquecimento

Antes de criar tarefas de enriquecimento no Knowledge Studio, talvez seja necessário configurar vários componentes de infraestrutura subjacentes, dependendo da sua arquitetura de segurança e das fontes de dados de destino.

Neste guia, descrevemos como configurar contas de serviço gerenciado pelo cliente, provedores de autenticação de terceiros, buckets do Cloud Storage e visualizações do Cloud Logging.

A tabela a seguir descreve as configurações de pré-requisito e quando você precisa configurá-las:

Recurso de configuração Quando configurar
APIs do Google Cloud Obrigatório. É necessário ativar as APIs do Google Cloud para executar fluxos de trabalho de enriquecimento.
Conta serviço gerenciado pelo cliente Você quer restringir o acesso de leitura e gravação nos conjuntos de dados de destino.
Papéis do Identity and Access Management (IAM) do usuário É necessário conceder permissões aos gerentes e revisores de fluxo de trabalho para gerar e aprovar metadados.
Provedores de autenticação de terceiros Você está se conectando a fontes de conhecimento de terceiros (como Microsoft SharePoint, Atlassian Confluence ou GitHub).
Buckets do Cloud Storage. Você está ingerindo contexto de negócios não estruturado (como PDFs, Markdown e CSV) e conjuntos de dados de avaliação.
Conjuntos de dados de avaliação Você quer fornecer consultas de semente e conjuntos de dados de comparativo de mercado para monitorar ativamente a precisão do agente.
Traces do agente para autoaprendizado Você quer que o agente de enriquecimento analise automaticamente as interações do agente downstream do Gemini Enterprise.
Criação de perfis de dados e insights de dados Recomendado. Você quer melhorar a qualidade do enriquecimento gerando perfis estatísticos e insights de IA de referência em tabelas usadas com frequência.

Antes de começar

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Dataplex, Data Lineage, BigQuery, Cloud Storage, and IAM Credentials APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Dataplex, Data Lineage, BigQuery, Cloud Storage, and IAM Credentials APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

    8.

Detalhes das APIs necessárias

Para configurar e executar tarefas de enriquecimento, as APIs ativadas realizam as seguintes funções:

Nome da API Identificador de serviço Finalidade nos fluxos de trabalho de enriquecimento
API Dataplex dataplex.googleapis.com API do plano de controle principal. Gerencia EnrichmentTask, EnrichmentRun, conjuntos de contexto, solicitações de mudança e o EnrichmentChatService.
API BigQuery bigquery.googleapis.com Necessária para verificar esquemas de tabela, ingerir o histórico de execução de SQL e consultar tabelas de trace da análise de agentes do BigQuery.
API Cloud Storage storage.googleapis.com Obrigatório para ingerir conjuntos de avaliação e gerenciar amostras de conjuntos de dados de avaliação.
API Service Account Credentials do IAM iamcredentials.googleapis.com Necessário para autenticar com segurança o agente de execução e conceder credenciais de curta duração (SLC, na sigla em inglês) durante as tarefas.

Configurar uma conta serviço gerenciado pelo cliente

As tarefas de enriquecimento usam uma conta serviço gerenciado pelo cliente para executar operações. Isso permite restringir o acesso de leitura e gravação nos conjuntos de dados de destino.

  1. Crie a conta de serviço.

    Para criar uma conta de serviço, você precisa ser um Proprietário do projeto (roles/owner) ou Editor (roles/editor) ou ter o papel de Administrador da conta de serviço (roles/iam.serviceAccountAdmin).

    Uma conta de serviço dedicada isola as operações de enriquecimento, permitindo que você conceda apenas as permissões específicas de leitura e gravação necessárias para essas tarefas, sem afetar outras cargas de trabalho.

    Para criar uma conta de serviço, siga estas etapas:

    CLI do Google Cloud

    Para criar uma conta de serviço, use o comando gcloud iam service-accounts create:

    Antes de usar os dados do comando abaixo, faça estas substituições:

    • SERVICE_ACCOUNT_NAME: o nome da sua conta de serviço.

    Execute o seguinte comando:

    Linux, macOS ou Cloud Shell

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
    --description="Service Account for Dataplex Knowledge Catalog enrichment agent execution" \
    --display-name="Knowledge Catalog enrichment agent SA"

    Windows (PowerShell)

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME `
    --description="Service Account for Dataplex Knowledge Catalog enrichment agent execution" `
    --display-name="Knowledge Catalog enrichment agent SA"

    Windows (cmd.exe)

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME ^
    --description="Service Account for Dataplex Knowledge Catalog enrichment agent execution" ^
    --display-name="Knowledge Catalog enrichment agent SA"

    REST

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • SERVICE_ACCOUNT_NAME: o nome da sua conta de serviço.
    • TARGET_PROJECT_ID: o ID do projeto do Google Cloud

    Método HTTP e URL:

    POST https://iam.googleapis.com/v1/projects/TARGET_PROJECT_ID/serviceAccounts

    Corpo JSON da solicitação:

    {
   "accountId": "SERVICE_ACCOUNT_NAME",
   "serviceAccount": {
    "displayName": "Knowledge Catalog enrichment agent SA",
    "description": "Service Account for Dataplex Knowledge Catalog enrichment agent execution"
   }
  }

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá um código de status bem-sucedido (2xx) e uma resposta vazia.

  2. Conceda os papéis do IAM necessários no nível do recurso à conta de serviço de execução nos escopos de destino:

    • Editor do Dataplex Catalog (roles/dataplex.catalogEditor) e Leitor do Dataplex Catalog (roles/dataplex.catalogViewer): permite que o agente inspecione metadados do catálogo, crie entradas de trabalho em etapas e publique manualmente as melhorias aprovadas.
    • (Opcional) Aprovador de fluxo de trabalho do Dataplex (roles/dataplex.workflowApprover): necessário apenas se você ativar a publicação automática na tarefa. Permite que o agente aprove e publique automaticamente as próprias solicitações de mudança de metadados.
    • Visualizador de Dados do BigQuery (roles/bigquery.dataViewer): permite que o agente leia esquemas de tabela, metadados de coluna e tabelas de trace de análise do agente.

    Observação: os exemplos de código a seguir concedem esses papéis no nível do projeto para facilitar a configuração. Para sistemas de produção, recomendamos conceder esses papéis com segurança no nível do recurso nos conjuntos de dados de destino específicos.

    Para conceder esses papéis padrão, siga estas etapas:

    Para adicionar uma vinculação de política do IAM a um projeto, use o comando gcloud projects add-iam-policy-binding:

    Antes de usar os dados do comando abaixo, faça estas substituições:

    • SERVICE_ACCOUNT_NAME: o nome da sua conta de serviço.
    • TARGET_PROJECT_ID: o ID do projeto do Google Cloud

    Execute o seguinte comando:

    Linux, macOS ou Cloud Shell

    gcloud projects add-iam-policy-binding TARGET_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/dataplex.catalogEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/bigquery.dataViewer"

    Windows (PowerShell)

    gcloud projects add-iam-policy-binding TARGET_PROJECT_ID `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/dataplex.catalogEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/bigquery.dataViewer"

    Windows (cmd.exe)

    gcloud projects add-iam-policy-binding TARGET_PROJECT_ID ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/dataplex.catalogEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/bigquery.dataViewer"

  3. Conceda aos usuários permissão para personificar a conta de serviço atribuindo a eles o papel de Usuário da conta de serviço (roles/iam.serviceAccountUser):

    Os usuários que criam as tarefas de enriquecimento no console precisam ter essa permissão para especificar e anexar essa conta de serviço à tarefa.

    Para conceder aos usuários o papel de Usuário da Conta de Serviço, siga estas etapas:

    Para adicionar uma vinculação de política do IAM a uma conta de serviço, use o comando gcloud iam service-accounts add-iam-policy-binding:

    Antes de usar os dados do comando abaixo, faça estas substituições:

    • SERVICE_ACCOUNT_NAME: o nome da sua conta de serviço.
    • TARGET_PROJECT_ID: o ID do projeto do Google Cloud
    • USER_EMAIL: o endereço de e-mail do usuário.

    Execute o seguinte comando:

    Linux, macOS ou Cloud Shell

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com \
    --member="user:USER_EMAIL@domain.com" \
    --role="roles/iam.serviceAccountUser"

    Windows (PowerShell)

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com `
    --member="user:USER_EMAIL@domain.com" `
    --role="roles/iam.serviceAccountUser"

    Windows (cmd.exe)

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com ^
    --member="user:USER_EMAIL@domain.com" ^
    --role="roles/iam.serviceAccountUser"

  4. Permita que o agente de serviço interno do Knowledge Catalog represente essa conta de serviço concedendo a ele o papel de Criador de token da conta de serviço (roles/iam.serviceAccountTokenCreator):

    Isso permite que o serviço subjacente do Knowledge Catalog assuma a identidade dessa conta de serviço dedicada e as permissões restritas dela ao executar as operações de enriquecimento em segundo plano em seu nome.

    Para autorizar o agente a assumir a identidade da conta de serviço, siga estas etapas:

    Para adicionar uma vinculação de política do IAM a uma conta de serviço, use o comando gcloud iam service-accounts add-iam-policy-binding:

    Antes de usar os dados do comando abaixo, faça estas substituições:

    • SERVICE_ACCOUNT_NAME: o nome da sua conta de serviço.
    • TARGET_PROJECT_ID: o ID do projeto do Google Cloud
    • TARGET_PROJECT_NUMBER: o número do projeto do Google Cloud.

    Execute o seguinte comando:

    Linux, macOS ou Cloud Shell

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com \
    --member="serviceAccount:service-TARGET_PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
    --role="roles/iam.serviceAccountTokenCreator"

    Windows (PowerShell)

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com `
    --member="serviceAccount:service-TARGET_PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" `
    --role="roles/iam.serviceAccountTokenCreator"

    Windows (cmd.exe)

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com ^
    --member="serviceAccount:service-TARGET_PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" ^
    --role="roles/iam.serviceAccountTokenCreator"

Conceder os papéis do IAM necessários aos usuários

Para garantir que sua equipe possa gerenciar fluxos de trabalho de enriquecimento e analisar propostas geradas com IA, conceda os papéis do IAM apropriados aos usuários. Para instruções sobre como conceder esses papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Os gerentes de fluxo de trabalho (como administradores de gestão de dados) que criam, configuram e monitoram tarefas precisam dos seguintes papéis:

  • Editor do DataScan Dataplex (roles/dataplex.dataScanEditor) ou Editor do Dataplex (roles/dataplex.editor): permite que os usuários criem, modifiquem, acionem e cancelem tarefas de enriquecimento.
  • Usuário da conta de serviço (roles/iam.serviceAccountUser) na conta serviço gerenciado pelo cliente: necessário para anexar a conta de serviço como a identidade de execução da tarefa.

Os revisores de mudanças (como proprietários de domínio ou especialistas no assunto) que inspecionam, aprovam e publicam propostas de metadados gerados com IA no catálogo precisam dos seguintes papéis:

  • Editor do Dataplex Catalog (roles/dataplex.catalogEditor) e Leitor do Dataplex Catalog (roles/dataplex.catalogViewer): necessários para abrir solicitações de mudança, inspecionar diferenças de propostas lado a lado e editar descrições inline.
  • Aprovador de fluxo de trabalho do Dataplex (roles/dataplex.workflowApprover): necessário para aprovar e publicar solicitações de alteração no catálogo ativo.
  • Leitor do DataScan Dataplex (roles/dataplex.dataScanViewer) ou Leitor do Dataplex (roles/dataplex.viewer): necessário para analisar as pontuações de confiança por proposta, o diagnóstico de falhas de teste e as visões gerais de avaliação downstream.

Configurar provedores de autenticação de terceiros

Ao conectar o agente de enriquecimento a fontes de conhecimento de terceiros (como Microsoft SharePoint, Atlassian Confluence ou GitHub), é necessário configurar um provedor de autenticação usando o serviço de identidade do agente do Google Cloud.

A identidade do agente funciona como um gerenciador de credenciais seguro que criptografa seus tokens de terceiros dentro do projeto, garantindo que os operadores humanos nunca precisem lidar com chaves secretas do cliente brutas durante a execução de tarefas.

Para instruções detalhadas sobre como gerar os tokens necessários e configurar o provedor de autenticação para plataformas externas específicas, consulte Configurar conectores externos para tarefas de enriquecimento.

Configurar permissões do IAM para provedores de autenticação

Para permitir que o agente de enriquecimento recupere com segurança as credenciais do provedor de autenticação dinamicamente durante uma execução ativa, conceda o papel Administrador de identidade do agente (roles/agentidentity.admin) ao Agente de serviço do Knowledge Catalog (service-<var>PROJECT_NUMBER</var>@gcp-sa-dataplex.iam.gserviceaccount.com) gerenciado. É possível conceder esse papel no nível do recurso do provedor de autenticação ou no nível do projeto.

Além disso, o usuário humano que anexa o provedor de autenticação à tarefa no console doGoogle Cloud precisa ter a permissão agentidentity.authProviders.get (incluída em Leitor de identidade do agente (roles/agentidentity.viewer)) no provedor de autenticação.

Preparar buckets do Cloud Storage

O Cloud Storage serve como a principal camada de preparo baseada em arquivos, ingestão de contexto e exportação de artefatos para fluxos de trabalho de enriquecimento de conhecimento.

É possível configurar o agente para ingerir arquivos de um ou mais buckets de entrada para embasar o raciocínio dele no conhecimento do domínio empresarial. Os tipos de contexto compatíveis incluem:

  • Documentação de domínio e dicionários de dados: arquivos Markdown, texto simples, PDF, HTML ou CSV que contêm definições de tabela, glossários empresariais, procedimentos operacionais padrão (SOPs, na sigla em inglês), arquiteturas de pipeline de dados ou diretrizes de nomenclatura de colunas.

  • Conjuntos de dados de avaliação: arquivos JSONL ou CSV que armazenam consultas de sementes e conjuntos de consultas de validação retidos. Para mais informações, consulte Formatar conjuntos de dados de avaliação.

  • Scripts de transformação e SQL de referência: scripts SQL salvos, definições de modelo dbt ou lógica de transformação de ETL que fornecem indicadores contextuais sobre padrões de mesclagem de tabelas e cálculos de negócios.

Quando configurado, o agente de enriquecimento também pode exportar pacotes estruturados e artefatos de execução para um bucket de saída. Os artefatos de saída compatíveis incluem:

  • Relatórios de avaliação detalhados: scorecards abrangentes que mostram deltas de precisão por consulta, diagnóstico de falhas de teste e métricas de distribuição de confiança.

Para garantir que o agente de enriquecimento possa funcionar fora do bucket, verifique se a conta de serviço de execução tem as permissões necessárias.

  • Conceda o papel de Leitor de objetos (roles/storage.objectViewer) nos buckets de entrada para que o agente possa ler documentos de preparo e arquivos de configuração.
  • (Opcional) Conceda o papel de Criador de objetos (roles/storage.objectCreator) no bucket de saída se quiser que o agente salve artefatos de execução e registros de validação.

Para conceder à conta de serviço acesso aos buckets do Cloud Storage, siga estas etapas:

Para adicionar uma vinculação de política do IAM a um bucket de armazenamento, use o comando gcloud storage buckets add-iam-policy-binding:

Antes de usar os dados do comando abaixo, faça estas substituições:

  • CUSTOMER_BUCKET: o nome do bucket do Cloud Storage
  • SERVICE_ACCOUNT_NAME: o nome da sua conta de serviço.
  • TARGET_PROJECT_ID: o ID do projeto do Google Cloud

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud storage buckets add-iam-policy-binding gs://CUSTOMER_BUCKET \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/storage.objectViewer"

Windows (PowerShell)

gcloud storage buckets add-iam-policy-binding gs://CUSTOMER_BUCKET `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/storage.objectViewer"

Windows (cmd.exe)

gcloud storage buckets add-iam-policy-binding gs://CUSTOMER_BUCKET ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/storage.objectViewer"

Formatar conjuntos de dados de avaliação

Os fluxos de trabalho de enriquecimento podem extrair informações automaticamente sem exemplos. No entanto, fornecer conjuntos de dados de avaliação permite que o agente se teste e melhore a precisão.

Você pode fornecer dois tipos de conjuntos de dados:

  • Conjunto de curadoria: uma lista de exemplos de perguntas de usuários e as consultas SQL esperadas. O agente usa essa lista para praticar e escrever resumos de tabelas melhores.

  • Conjunto de avaliação: uma lista separada de perguntas usadas para avaliar o desempenho do agente. Se o agente tiver um desempenho ruim, esse conjunto de avaliação vai impedir que atualizações ruins sejam publicadas no seu catálogo.

Como alternativa, é possível fornecer um único conjunto de dados consolidado. O serviço de enriquecimento divide automaticamente os dados em um conjunto de curadoria e um conjunto de avaliação.

Requisitos do esquema do conjunto de dados

Os conjuntos de dados de avaliação precisam ser formatados como arquivos JSONL e armazenados no Cloud Storage. Cada linha no arquivo precisa conter uma pergunta em linguagem natural pareada com a consulta SQL de informações empíricas esperada.

Verifique se o arquivo corresponde ao esquema do conjunto de dados de avaliação prescrito pela Gemini Enterprise Agent Platform. A tabela a seguir mostra os campos de formatação aceitos:

Nome do campo Tipo Descrição
display_name STRING Opcional. Um identificador ou nome para a solicitação de avaliação.
evaluation_request.prompt.text STRING A pergunta em linguagem natural ou o comando do usuário.
evaluation_request.golden_response.candidate STRING Identifica a resposta de ouro. Defina como golden.
evaluation_request.golden_response.text STRING As informações empíricas, consulta SQL validada que responde à pergunta. O avaliador executa esse SQL nos dados.

O snippet a seguir mostra um arquivo de avaliação .jsonl válido:

{"display_name": "revenue-2026", "evaluation_request": {"prompt": {"text": "What is total revenue for customer C100 in 2026?"}, "golden_response": {"candidate": "golden", "text": "SELECT SUM(amount) FROM `project.dataset.orders` WHERE customer_id = 'C100' AND EXTRACT(YEAR FROM order_date) = 2026;"}}}
{"display_name": "monthly-subscribers", "evaluation_request": {"prompt": {"text": "List active subscribers on monthly billing"}, "golden_response": {"candidate": "golden", "text": "SELECT user_id, email FROM `project.dataset.subscriptions` WHERE status = 'ACTIVE' AND plan_type = 'MONTHLY';"}}}

Para orientações detalhadas sobre como criar conjuntos de dados de avaliação de alta qualidade, consulte a documentação da Gemini Enterprise Agent Platform.

Configurar traces de agentes para autoaprendizado

Para permitir que o agente de enriquecimento analise automaticamente as interações do agente do Gemini Enterprise downstream (ou aplicativos personalizados da Gemini Enterprise Agent Platform), é possível fornecer a ele acesso de leitura aos traces de interação do aplicativo.

A ingestão desses traces permite que o agente realize a mineração de trajetórias. O agente descobre onde os agentes downstream tiveram dificuldades devido à falta de contexto, agrupa as perguntas frequentes dos usuários em classes de consulta de alto impacto e seleciona automaticamente os resumos exatos das tabelas, a semântica das colunas e os termos do glossário empresarial necessários para resolver essas lacunas.

Dependendo da arquitetura da empresa, escolha um dos dois métodos de configuração abaixo:

Geração de registros direta usando visualizações de registro com escopo (recomendado)

Quando a geração de registros de interação está ativada para um aplicativo, os registros de execução são transmitidos diretamente para o Logging. Para seguir o princípio de privilégio mínimo, crie uma visualização de registros dedicada restrita ao aplicativo específico e conceda à conta de serviço de execução acesso de leitura exclusivamente nessa visualização.

  1. Criar uma visualização de registros com escopo para isolar os registros. Isso garante que o serviço de enriquecimento leia apenas a telemetria de aplicativos configurados específicos (por exemplo, filtrando em resource.type="aiplatform.googleapis.com/Agent"), impedindo o acesso não autorizado aos registros mais amplos do Cloud.

    CLI da gcloud

    Para criar uma visualização de registros com escopo, use o comando gcloud logging views create:

    Antes de usar os dados do comando abaixo, faça estas substituições:

    • LOG_VIEW_NAME: o nome da visualização de registros.
    • YOUR_GEMINI_ENTERPRISE_APP_ID: o ID do seu aplicativo do Gemini Enterprise.

    Execute o seguinte comando:

    Linux, macOS ou Cloud Shell

    gcloud logging views create LOG_VIEW_NAME \
    --location=global \
    --bucket=_Default \
    --log-filter='resource.type="aiplatform.googleapis.com/Agent" AND resource.labels.agent_id="YOUR_GEMINI_ENTERPRISE_APP_ID"'

    Windows (PowerShell)

    gcloud logging views create LOG_VIEW_NAME `
    --location=global `
    --bucket=_Default `
    --log-filter='resource.type="aiplatform.googleapis.com/Agent" AND resource.labels.agent_id="YOUR_GEMINI_ENTERPRISE_APP_ID"'

    Windows (cmd.exe)

    gcloud logging views create LOG_VIEW_NAME ^
    --location=global ^
    --bucket=_Default ^
    --log-filter='resource.type="aiplatform.googleapis.com/Agent" AND resource.labels.agent_id="YOUR_GEMINI_ENTERPRISE_APP_ID"'

    REST

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • LOG_VIEW_NAME: o nome da visualização de registros.
    • TARGET_PROJECT_ID: o ID do projeto do Google Cloud
    • YOUR_GEMINI_ENTERPRISE_APP_ID: o ID do seu aplicativo do Gemini Enterprise.

    Método HTTP e URL: 

    POST https://logging.googleapis.com/v2/projects/TARGET_PROJECT_ID/locations/global/buckets/_Default/views?viewId=LOG_VIEW_NAME

    Corpo JSON da solicitação:

    {
 "filter": "resource.type=\"aiplatform.googleapis.com/Agent\" AND resource.labels.agent_id=\"YOUR_GEMINI_ENTERPRISE_APP_ID\""
}

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá um código de status bem-sucedido (2xx) e uma resposta vazia.

  2. Depois de criar a visualização de registro, conceda à conta de serviço de execução acesso de leitura a ela. Isso autoriza o job de enriquecimento a extrair a telemetria do aplicativo necessária durante a fase de autoaprendizado.

    Para adicionar uma vinculação de política do IAM a uma visualização de registro, use o comando gcloud logging views add-iam-policy-binding:

    Antes de usar os dados do comando abaixo, faça estas substituições:

    • LOG_VIEW_NAME: o nome da visualização de registros.
    • SERVICE_ACCOUNT_NAME: o nome da sua conta de serviço.
    • TARGET_PROJECT_ID: o ID do projeto do Google Cloud

    Execute o seguinte comando:

    Linux, macOS ou Cloud Shell

    gcloud logging views add-iam-policy-binding LOG_VIEW_NAME \
    --location=global \
    --bucket=_Default \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/logging.viewAccessor"

    Windows (PowerShell)

    gcloud logging views add-iam-policy-binding LOG_VIEW_NAME `
    --location=global `
    --bucket=_Default `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/logging.viewAccessor"

    Windows (cmd.exe)

    gcloud logging views add-iam-policy-binding LOG_VIEW_NAME ^
    --location=global ^
    --bucket=_Default ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/logging.viewAccessor"

Para mais informações, consulte Configurar visualizações de registro em um bucket de registros.

Análise de agentes do BigQuery

Se a organização transmitir registros de interação para o BigQuery usando um coletor de registros do Logging ou gravar diretamente nas tabelas de análise de agentes do BigQuery, conceda acesso ao conjunto de dados.

Verifique se os registros de interação estão configurados para serem transmitidos para um conjunto de dados designado do BigQuery e se a conta de serviço de execução recebeu o papel de Leitor de Dados do BigQuery (roles/bigquery.dataViewer) nesse conjunto de dados específico. Isso permite que o agente leia a telemetria exportada diretamente do BigQuery.

Para mais informações sobre como exportar registros, consulte Rotear registros para destinos compatíveis.

Ativar a criação de perfis e os insights de dados

Antes de executar uma tarefa de enriquecimento, recomendamos ativar a criação de perfis de dados e os insights de dados de IA nas tabelas de destino usadas com frequência. A criação de perfil de dados fornece características estatísticas, como valores comuns, distribuições de dados e contagens nulas, enquanto os insights de dados geram descrições de tabelas de referência e consultas de amostra. Fornecer esses indicadores ajuda o agente de enriquecimento a gerar propostas de metadados mais precisas.

A seguir