Criar tarefas de enriquecimento

As tarefas de enriquecimento do Knowledge Studio permitem documentar automaticamente o significado comercial dos seus dados para que os aplicativos de IA possam consultá-los com precisão sem alucinações. Essas tarefas usam IA para verificar seus procedimentos operacionais padrão (SOPs), repositórios de código e interações do usuário, extraindo a lógica de negócios necessária para embasar seus agentes de IA.

Antes de começar

Siga estes pré-requisitos antes de criar uma tarefa de enriquecimento.

Entender os conceitos

Antes de executar uma tarefa de enriquecimento, recomendamos que você se familiarize com os principais componentes da arquitetura de enriquecimento:

  • Para uma visão geral de como os agentes do Knowledge Studio automatizam a geração de metadados, consulte Sobre as tarefas de enriquecimento.

  • Para uma visão geral de como o contexto de metadados embasa os agentes de IA e simplifica a exploração de dados, consulte Sobre o contexto de dados.

  • Para uma visão geral da hierarquia do Knowledge Catalog, incluindo grupos de entradas, entradas, aspectos e links de entrada, consulte Sobre metadados.

Preparar os componentes necessários

Antes de criar uma tarefa de enriquecimento, verifique se o ambiente está configurado corretamente para o enriquecimento de IA, conforme detalhado em Configurar pré-requisitos para tarefas de enriquecimento.

Tenha os seguintes componentes prontos:

  • Conta de serviço: uma conta de serviço de usuário dedicada com os papéis necessários. Nesta documentação, chamamos isso de conta de serviço de execução para diferenciá-la dos agentes de serviço do Knowledge Catalog gerenciados pelo Google. A tarefa de enriquecimento é executada como essa conta de serviço e a usa para ler as fontes e gravar no conjunto de contexto.

  • Conjunto de contexto: um conjunto de contexto de destino para salvar os metadados enriquecidos. O conjunto de contextos também serve como fonte de recursos para enriquecer. O que estiver no conjunto de contexto será enriquecido por padrão se nenhum recurso adicional for adicionado durante a configuração. Também é possível criar um conjunto de contexto vazio durante a configuração da tarefa, se não houver um.

  • Recursos para enriquecer (opcional): outros recursos de dados que você quer enriquecer e que ainda não estão no conjunto de contexto de destino. Adicionar esses recursos extras durante a criação de tarefas os enriquece e os adiciona automaticamente ao conjunto de contexto de destino. Esses recursos podem incluir conjuntos de dados, tabelas ou recursos do Lakehouse do BigQuery e já precisam existir.

  • Indicadores de conhecimento (opcional): se você planeja fornecer ao agente de IA documentos ou modelos para aprender, prepare seus buckets do Cloud Storage, formate seus conjuntos de dados de avaliação .jsonl ou configure o OAuth para URLs de origem de terceiros.

  • Registros de rastreamento (opcional): se você planeja ativar o autoaprendizado do agente, configure os registros de rastreamento do agente definindo visualizações de registro com escopo ou uma tabela de análise de agentes do BigQuery para que o agente possa aprender com as interações históricas.

  • Criação de perfis de dados e insights de dados (recomendado): para melhorar a qualidade das propostas de metadados geradas, ative a criação de perfis de dados e os insights de dados de IA nas tabelas de destino usadas com frequência antes de executar a tarefa. Para mais informações, consulte Configurar pré-requisitos para tarefas de enriquecimento.

Funções exigidas

Para configurar e executar tarefas de enriquecimento, identidades diferentes exigem permissões específicas.

O usuário final

Para criar e gerenciar tarefas de enriquecimento, você precisa ter os seguintes papéis obrigatórios.

Criar, modificar, executar e cancelar tarefas de enriquecimento

Para garantir que você tenha as permissões necessárias para criar, modificar, executar e cancelar tarefas de enriquecimento, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para criar, modificar, executar e cancelar tarefas de enriquecimento. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para criar, modificar, executar e cancelar tarefas de enriquecimento:

  • Criar tarefas de enriquecimento: dataplex.agentTasks.create
  • Ver tarefas de enriquecimento: dataplex.agentTasks.get
  • Listar tarefas de enriquecimento: dataplex.agentTasks.list
  • Excluir tarefas de enriquecimento: dataplex.agentTasks.delete
  • Atualizar tarefas de enriquecimento: dataplex.agentTasks.update
  • Executar tarefas de enriquecimento: dataplex.agentTasks.run
  • Cancelar tarefas de enriquecimento: dataplex.agentTasks.cancel

O administrador também pode conceder essas permissões a você com papéis personalizados ou outros papéis predefinidos.

Anexar a conta de serviço de execução à configuração da tarefa de enriquecimento

Para garantir que você tenha as permissões necessárias para anexar a conta de serviço de execução à configuração da tarefa de enriquecimento, peça ao administrador para conceder a você os seguintes papéis do IAM na conta de serviço de execução:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para anexar a conta de serviço de execução à configuração da tarefa de enriquecimento. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para anexar a conta de serviço de execução à configuração da tarefa de enriquecimento:

  • Representar contas de serviço: iam.serviceAccounts.actAs

O administrador também pode conceder essas permissões a você com papéis personalizados ou outros papéis predefinidos.

A conta de serviço de execução

A conta de serviço de execução é a identidade em que a tarefa de enriquecimento é executada e realiza todas as operações.

Consumir serviços obrigatórios

Para garantir que a conta de serviço de execução tenha as permissões necessárias para consumir APIs durante a execução da tarefa de enriquecimento, peça ao administrador para conceder os seguintes papéis do IAM à conta de serviço de execução no projeto que contém a tarefa de enriquecimento:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para consumir APIs durante a execução da tarefa de enriquecimento. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para consumir APIs durante a execução da tarefa de enriquecimento:

  • Consumir cotas e serviços: serviceusage.services.use

O administrador também pode conceder essas permissões à conta de serviço de execução com papéis personalizados ou outros papéis predefinidos.

Visualizar e criar perfis de conteúdo de dados de destino

Para garantir que a conta de serviço de execução tenha as permissões necessárias para visualizar e criar perfis de conteúdo de dados nos conjuntos de dados de destino, peça ao administrador para conceder os seguintes papéis do IAM à conta de serviço de execução nas tabelas de destino:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para visualizar e criar perfis de conteúdo de dados nos conjuntos de dados de destino. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para visualizar e criar perfis de conteúdo de dados nos conjuntos de dados de destino:

  • Ver metadados do conjunto de dados: bigquery.datasets.get
  • Ver metadados da tabela: bigquery.tables.get
  • Ler dados da tabela: bigquery.tables.getData

O administrador também pode conceder essas permissões à conta de serviço de execução com papéis personalizados ou outros papéis predefinidos.

Propor e gravar metadados em conjuntos de contexto

Para garantir que a conta de serviço de execução tenha as permissões necessárias para propor e gravar definições de metadados em conjuntos de contexto, peça ao administrador que conceda os seguintes papéis do IAM à conta de serviço de execução no projeto:

  • Para conceder as permissões necessárias: Editor do Dataplex Catalog (roles/dataplex.catalogEditor) e Leitor do Dataplex Catalog (roles/dataplex.catalogViewer)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para propor e gravar definições de metadados em conjuntos de contexto. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para propor e gravar definições de metadados em conjuntos de contexto:

  • Crie entradas de metadados: dataplex.entries.create
  • Atualize as entradas de metadados: dataplex.entries.update
  • Veja as entradas de metadados: dataplex.entries.get
  • Liste as entradas de metadados: dataplex.entries.list
  • Criar grupos de entrada: dataplex.entryGroups.create
  • Atualize os grupos de entrada: dataplex.entryGroups.update
  • Propor mudanças nos grupos de entrada: dataplex.entryGroups.requestChanges

O administrador também pode conceder essas permissões à conta de serviço de execução com papéis personalizados ou outros papéis predefinidos.

Publicar enriquecimentos automaticamente (opcional)

(Opcional) Se você ativar a publicação automática na tarefa, inclua o seguinte papel:

Para garantir que a conta de serviço de execução tenha as permissões necessárias para aprovar e publicar mudanças automaticamente, peça ao administrador para conceder os seguintes papéis do IAM à conta de serviço de execução no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para aprovar e publicar mudanças automaticamente. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para aprovar e publicar mudanças automaticamente:

  • Use solicitações de mudança: dataplex.changeRequests.use

O administrador também pode conceder essas permissões à conta de serviço de execução com papéis personalizados ou outros papéis predefinidos.

Aprender com os registros de rastreamento

(Opcional) Se você planeja aprender com os registros de rastreamento atuais (autoaprendizado), inclua as seguintes funções:

Para garantir que a conta de serviço de execução tenha as permissões necessárias para ler interações históricas dos registros de rastreamento, peça ao administrador para conceder os seguintes papéis do IAM à conta de serviço de execução no projeto que possui o app do Gemini:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para ler interações históricas de registros de rastreamento. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para ler interações históricas de registros de rastreamento:

  • Acessar visualizações de registro: logging.views.access
  • Ler entradas de registro: logging.logEntries.list

O administrador também pode conceder essas permissões à conta de serviço de execução com papéis personalizados ou outros papéis predefinidos.

(Opcional) Se você planeja aprender com uma tabela de análise de agentes do BigQuery, a conta de serviço de execução também precisa do papel Leitor de dados do BigQuery (roles/bigquery.dataViewer) na tabela de análise de agentes.

O agente de serviço do Dataplex

O agente de serviço do Knowledge Catalog é uma conta serviço gerenciado pelo Google que o Knowledge Catalog usa para realizar operações de back-end em seu nome, como personificar sua conta de serviço de execução durante uma execução de enriquecimento e orquestrar jobs de criação de perfil do BigQuery.

O agente de serviço do Knowledge Catalog usa o seguinte formato de e-mail:

service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com

Substitua PROJECT_NUMBER pelo número do projeto do Google Cloud .

Representar a conta de serviço de execução

Para garantir que o agente de serviço do Knowledge Catalog tenha as permissões necessárias para representar a conta de serviço de execução e executar a tarefa, peça ao administrador para conceder os seguintes papéis do IAM ao agente de serviço do Knowledge Catalog na conta de serviço de execução:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para personificar a conta de serviço de execução para executar a tarefa. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para personificar a conta de serviço de execução para executar a tarefa:

  • Gerar tokens de acesso: iam.serviceAccounts.getAccessToken
  • Gerar tokens do OpenID: iam.serviceAccounts.getOpenIdToken
  • Assinar JWTs: iam.serviceAccounts.signJwt
  • Assinar BLOBs: iam.serviceAccounts.signBlob

O administrador também pode conceder ao agente de serviço do Knowledge Catalog essas permissões com papéis personalizados ou outros papéis predefinidos.

Criar perfis do BigQuery e ler o histórico de consultas

Para garantir que o agente de serviço do Dataplex tenha as permissões necessárias para realizar a criação de perfil do BigQuery de back-end e ler o histórico de consultas da tabela, peça ao administrador para conceder os seguintes papéis do IAM ao agente de serviço do Dataplex no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para realizar a criação de perfis de back-end do BigQuery e ler o histórico de consultas de tabelas. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para realizar a criação de perfil de back-end do BigQuery e ler o histórico de consultas da tabela:

  • Ver metadados do conjunto de dados: bigquery.datasets.get
  • Ver metadados da tabela: bigquery.tables.get
  • Ler dados da tabela: bigquery.tables.getData
  • Liste os jobs do BigQuery: bigquery.jobs.list
  • Ver metadados básicos do recurso: resourcemanager.projects.get

O administrador também pode conceder ao agente de serviço do Dataplex essas permissões com papéis personalizados ou outros papéis predefinidos.

Abrir o espaço de trabalho do Knowledge Studio

Para abrir o assistente de criação de tarefas, siga estas etapas:

  1. No console do Google Cloud , acesse a página Knowledge Studio.

    Acessar o Knowledge Studio

  2. No painel de navegação à esquerda, selecione Enriquecimentos.

  3. Clique em + Criar tarefa de enriquecimento.

Dê um nome à tarefa de enriquecimento

No painel Definir, siga estas etapas:

  1. No campo Nome de exibição, forneça um nome descritivo para a tarefa (por exemplo, Finance Dataset enrichment).
  2. No campo ID da tarefa, forneça um ID exclusivo ou use o ID gerado automaticamente.

  3. No campo Meta, descreva o objetivo da tarefa de enriquecimento para orientar o processo de extração. Forneça orientações em linguagem natural detalhando a missão empresarial e as metas de capacidade de IA para esse conjunto de contexto.

    Exemplo:

    Curate and maintain the authoritative context set for the
`subscription_revenue` domain. Focus on resolving metric discrepancies
between `gross_sales`, `net_billed_revenue`, and `discount_applied`.
Ensure all customer join keys (e.g. `customer_id`, `subscription_fk`)
have explicit column documentation, and establish parameterized query
templates for Monthly Recurring Revenue (MRR) and Churn Rate calculations.

  4. Clique em Continuar.

Configurar os parâmetros da tarefa de enriquecimento

O escopo especifica o que é enriquecido e o que o agente lê.

No painel Escopo, siga estas etapas:

  1. No campo Projeto, selecione o projeto que contém o conjunto de contexto.

  2. No campo Conjunto de contexto, selecione o conjunto de contexto que a tarefa enriquece e em que ela salva os resultados.

    A tarefa de enriquecimento herda a região Google Cloud do conjunto de contexto selecionado.

    Se você não tiver um conjunto de contextos, clique em Criar conjunto de contextos.

    Para mais informações sobre como criar um conjunto de contexto, consulte Criar um conjunto de contexto.

  3. Opcional: na seção Recursos para enriquecer, adicione recursos do BigQuery ou do Lakehouse que você quer enriquecer, além do conjunto de contexto.

    Todos os recursos adicionados precisam estar na mesma região do conjunto de contexto selecionado. Os locais multirregionais (como us) correspondem às regiões únicas nesse local (como us-central1). Regiões incompatíveis causam falha na criação de tarefas.

    Se você selecionar um conjunto de contexto vazio e não adicionar outros recursos nesta seção, o Knowledge Studio vai mostrar um aviso. Se você executar a tarefa com essa configuração, ela vai gerar uma base de conhecimento semântica com base nas suas instruções, mas não vai enriquecer nenhuma entrada.

    1. Insira o nome completo do recurso do recurso de dados de destino.

      Exemplo:

      • Tabela do BigQuery: //bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID

      • Recurso do Lakehouse: //dataplex.googleapis.com/projects/PROJECT_ID/locations/LOCATION/lakes/LAKE_ID/zones/ZONE_ID/assets/ASSET_ID

    Como alternativa, para selecionar um recurso visualmente, siga estas etapas:

    1. Clique em Procurar para abrir a caixa de diálogo Selecionar fontes.
    2. Para selecionar recursos usados recentemente, clique na guia Recentes e selecione os recursos que você quer adicionar.
    3. Para navegar ou pesquisar todos os recursos, clique na guia Todos e faça o seguinte:
      1. No campo Pesquisar, digite um termo de pesquisa para o recurso do BigQuery ou do Lakehouse.
      2. Na árvore de recursos, expanda a hierarquia do projeto e do conjunto de dados para localizar o recurso.
      3. Marque a caixa de seleção ao lado de um ou mais recursos. É possível visualizar o esquema e os detalhes do recurso selecionado no painel à direita.
    4. Clique em Confirmar.

    Para adicionar mais recursos, use vírgulas para separar os nomes deles.

  4. Opcional: na seção Indicadores de conhecimento, conecte o agente de IA a outras fontes para ler o contexto. Esses recursos são somente leitura e não são enriquecidos.

    • Buckets do Cloud Storage: insira o nome do bucket ou clique em Procurar para pesquisar um bucket. Pressione Enter, vírgula ou Espaço após cada nome de bucket. A tarefa requer buckets inteiros. Não é possível configurá-la para ler apenas arquivos individuais.

    • Glossários: insira o nome do glossário ou clique em Procurar para pesquisar um glossário. Pressione Enter, vírgula ou Espaço após cada nome de glossário.

      Verifique se todos os glossários conectados estão localizados exatamente na mesma região que a tarefa de enriquecimento e o conjunto de contexto (por exemplo, us-central1). Adicionar um glossário de um local multirregional inválido (como us) faz com que a criação da tarefa falhe.

    • Fontes externas: para conectar plataformas de terceiros, como Google Workspace, Microsoft SharePoint, GitHub ou Atlassian Confluence, é possível configurá-las individualmente ou fornecer um arquivo de configuração YAML.

      Para configurar fontes usando um arquivo YAML:

      1. No campo Arquivo de configuração de origem (opcional), clique em Procurar e selecione o arquivo YAML.

      Para configurar uma origem manualmente:

      1. Em Fontes conectadas, clique em Configurar ao lado da plataforma que você quer configurar.
      2. No campo URLs de origem, insira os URLs dos seus documentos, repositórios ou espaços e pressione Enter ou vírgula após cada URL.

      3. Se a plataforma exigir autenticação (como GitHub, Atlassian ou Microsoft), anexe suas credenciais fazendo o seguinte:

        1. Clique em + Adicionar conexão.
        2. No painel Nova conexão, insira o nome completo do recurso do provedor de autenticação no campo Provedor de autenticação. Use o seguinte formato:
          projects/PROJECT_ID/locations/LOCATION/authProviders/PROVIDER_NAME
        3. Em Padrões de URI, clique em + Adicionar padrão de URI para especificar quais URLs essa credencial tem permissão para acessar. É possível usar asteriscos (*) como caracteres curinga (por exemplo, https://github.com/test-org/*).
        4. Clique em Concluído.

        Os recursos do Google Workspace se conectam diretamente usando as permissões do IAM da conta de serviço de execução da tarefa, portanto, não exigem uma conexão de provedor de autenticação.

  5. Clique em Continuar.

Configurar avaliação e autoaprendizado

Esta seção é opcional. No painel Melhorar, siga estas etapas:

  1. Opcional: na seção Avaliação, configure os seguintes campos:

    Para mais informações sobre como formatar conjuntos de dados de avaliação e curadoria, consulte Requisitos de esquema de conjunto de dados.

    • Conjunto de avaliação: para medir o impacto das mudanças de contexto propostas, insira um URI do Cloud Storage ou clique em Procurar para selecionar o arquivo .jsonl.

    • Conjunto de curadoria: para fornecer um conjunto de perguntas iniciais para otimização iterativa, insira um URI do Cloud Storage ou clique em Procurar para selecionar o arquivo .jsonl.

  2. Opcional: na seção Publicação, especifique a cadência de publicação:

    Quando a publicação automática está ativada, as mudanças de metadados aprovadas automaticamente são gravadas diretamente no conjunto de contexto. Quando desativada, a execução de enriquecimento gera rascunhos de edições que um revisor humano precisa aprovar antes de serem mesclados na base de código.

    • Para exigir a revisão humana antes que os metadados sejam mesclados ao conjunto de contexto de produção, desmarque a caixa de seleção Ativar publicação automática.

    • Para publicar automaticamente as mudanças que atendem a um limite de alta qualidade, marque a caixa de seleção Ativar publicação automática. Use o controle deslizante Publicar automaticamente acima para definir a pontuação de confiança mínima necessária para que as mudanças sejam publicadas automaticamente (por exemplo, 85%). Se um conjunto de dados de avaliação estiver configurado, você também poderá usar o controle deslizante Queda máxima de qualidade para restringir a publicação com segurança quando o desempenho do agente cair (por exemplo, -5%). As propostas que não atenderem a esses limites serão colocadas em fila como uma solicitação de mudança para revisão manual.

  3. Opcional: para encontrar lacunas em conversas reais de agentes e manter o contexto atualizado, na seção Autoaprendizado, selecione o botão de alternância Ativar autoaprendizado.

  4. Opcional: se você ativou o autoaprendizado, na seção Aprender com, adicione uma das seguintes fontes:

    • Apps do Gemini Enterprise: na lista ID do projeto, selecione o projeto. Na lista App do Gemini Enterprise, selecione o app que gera rastros de conversas e clique em Concluído.

      É possível adicionar vários apps do Gemini Enterprise.

      Para otimizar esses recursos de enriquecimento e autoaprendizagem, recomendamos especificar um modelo Gemini 3.8 Flash ou posterior no aplicativo Gemini Enterprise. Para mais informações sobre as etapas de seleção de modelos, consulte a seção "Criar um agente usando o criador de fluxos" em Criar agentes no Agent Studio.

    • Análise de agentes do BigQuery: no campo Tabela, insira o nome da tabela que contém os eventos de chat do agente ou clique em Procurar para selecioná-la visualmente e clique em Concluído.

      É possível adicionar várias tabelas.

  5. Clique em Continuar.

Definir as configurações de execução

No painel Executar, siga estas etapas:

  1. Na seção Executar como, clique na lista Conta de serviço do usuário e selecione a identidade que a tarefa usa para ler as fontes e gravar no conjunto de contexto. Verifique se essa é a identidade configurada em Antes de começar.
  2. Em Acionador, selecione a condição de acionamento:
    • On demand: é executado apenas quando você clica em "Run".
    • Programada: é executada automaticamente em uma programação recorrente.
  3. Opcional: em Notificações, clique em + Adicionar destinatário para especificar até cinco endereços de e-mail que vão receber um relatório após cada execução.
  4. Verifique os parâmetros no painel Resumo e clique em Criar.

Sua nova tarefa de enriquecimento foi salva. Dependendo das configurações do gatilho, a tarefa aguarda a primeira execução programada ou está pronta para ser executada imediatamente. Quando a tarefa conclui uma execução, o agente coloca as propostas de metadados de IA generativa geradas em uma fila de solicitação de mudança para sua análise.

A seguir