Recuperar contexto para recursos de dados

O contexto que envolve seus dados fornece aos aplicativos de IA uma compreensão profunda dos seus recursos de dados, melhorando a precisão e a relevância das respostas geradas pelo LLM.

O método lookupContext preenche a lacuna de contexto usando uma única solicitação de API para recuperar um pacote pré-formatado de metadados do recurso de dados otimizado para Agentic Workflows interativos. Use esse contexto compacto e pronto para LLM para fundamentar seus agentes na avaliação e no uso de recursos de dados.

É possível usar o método lookupContext para todos os recursos de dados armazenados no Knowledge Catalog, por exemplo, tabelas, conjuntos de dados e rotinas do BigQuery, além de domínios de dados e outras entradas.

Como os agentes podem receber contexto de dados?

  1. O agente recupera recursos de dados que podem ser relevantes para a recuperação de contexto, por exemplo, usando a pesquisa semântica do Knowledge Catalog.
  2. O agente usa o método lookupContext para fazer uma única chamada de API ou uma solicitação de ferramenta do MCP que recupera o contexto de um recurso específico.

  3. O método retorna uma resposta que contém um bloco de texto pré-formatado. Dependendo do parâmetro format especificado na solicitação, o documento pode estar no formato YAML, XML ou JSON.

    A resposta contém os seguintes elementos de contexto:

    Elemento de contexto Descrição
    Metadados técnicos Esquemas de recursos e configurações físicas, como estratégias de particionamento e clustering do BigQuery, e definições de rotina do BigQuery, incluindo argumentos, tipos de retorno e código-fonte.
    Metadados operacionais Mesclagens e outras relações, com base em registros de consultas históricos e insights de dados. Para mais informações, consulte Ver relações de dados.
    Descrições da empresa Termos de negócios relacionados, visões gerais, anotações de catálogo, descrições capturadas no sistema de origem e geradas automaticamente no Knowledge Catalog e diretrizes.

    Observação: é possível usar o aspecto de diretrizes em recursos de dados para capturar contexto adicional útil para os agentes ao descobrir, inspecionar ou usar recursos de dados.
    Perfil de dados Estatísticas de distribuição, contagens de valores distintos, proporções nulas e valores de amostra.
    Qualidade dos dados Resultados automatizados de verificação de qualidade de dados em relação a regras predefinidas.
    Contexto sobre recursos de dados relacionados Contexto sobre recursos de dados relacionados, como termos de glossário ou outros recursos relacionados, como tabelas frequentemente mescladas. O contexto retornado para recursos relacionados inclui o mesmo intervalo de elementos que o recurso ou recursos principais.

  4. O agente usa essa resposta para orientar a seleção de recursos relevantes ou o uso deles.

Antes de começar

Antes de usar o método lookupContext, verifique se você tem os papéis necessários e ative as APIs necessárias.

Funções exigidas

Para receber as permissões necessárias para chamar o método lookupContext, peça ao administrador para conceder a você os seguintes papéis do IAM no Google Cloud projeto iam.gserviceaccount.com:

  • Acesso de leitura aos recursos do catálogo, incluindo entradas, grupos de entradas e glossários: 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.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Ativar APIs

Para usar o método lookupContext, ative as seguintes APIs no seu projeto:

  • API Dataplex

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

Ativar a API

Recuperar o contexto de um recurso de dados

Para recuperar o contexto de um recurso de dados, acesse o método lookupContext diretamente com a API Dataplex ou use o servidor remoto do Protocolo de Contexto de Modelo (MCP) do Knowledge Catalog ou a MCP Toolbox for Databases.

O método lookupContext filtra os recursos com base nas suas permissões. A resposta contém dados apenas para recursos que sua identidade tem as permissões necessárias do Identity and Access Management (IAM) para acessar. Se você não tiver permissões nos recursos solicitados, o método vai retornar uma resposta vazia.

REST

Para recuperar o contexto de um recurso de dados, envie a seguinte solicitação:

curl --request POST \
   'https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupContext' \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "resources": RESOURCES
  "options": OPTIONS
  }' \
--compressed

Substitua:

  • PROJECT_ID: ID do projeto do Google Cloud
  • LOCATION: a região em que o recurso está (por exemplo, us-central1)
  • RESOURCES: até dez nomes de entrada para recuperar o contexto, formatados como projects/{project}/locations/{location}/entryGroups/{entryGroup}/entries/{entry}. Para vários recursos, a API estabelece relações entre os recursos solicitados, como mesclagens de esquemas frequentes, e retorna as informações de relação no contexto.
  • OPTIONS: as opções que permitem definir o contexto:
    • format é o formato do arquivo de contexto. Por exemplo, yaml.
    • context_budget é o número de caracteres a que a resposta é limitada. Se você definir o parâmetro all_schema_fields como true, a API vai retornar todos os campos do esquema, independentemente do valor de context_budget.

Veja um exemplo de solicitação que recupera o contexto de uma tabela do BigQuery:

curl --request POST \
'https://dataplex.googleapis.com/v1/projects/test-project/locations/us:lookupContext?key=[YOUR_API_KEY]' \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    "resources":
    ["projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/test-dataset/tables/test-table"],
    "options":
    {
      "format":"yaml",
      "context_budget":"4000"
    }
  }' \
--compressed

A resposta é um bloco de texto pré-formatado semelhante ao seguinte:

{
"context": "resource: \"projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/sales_data/tables/orders\"\ntechnical_metadata:\n  schema:\n    - name: order_id\n      type: STRING\n      description: \"Primary key for the order.\"\n    - name: customer_id\n      type: STRING\n    - name: total_amount\n      type: NUMERIC\n  partitioning:\n    type: TIMESTAMP\n    field: order_date\nbusiness_descriptions:\n  overview: \"Historical record of all customer transactions.\"\n  related_terms:\n    - \"Revenue\"\n    - \"Sales Transactions\"\n  guidelines: \"Always filter by 'order_date' to optimize query costs due to partitioning.\"\ndata_profile:\n  columns:\n    - name: total_amount\n      null_ratio: 0.001\n      distinct_values: 52340\n      sample_values: [45.99, 120.00, 15.50]\ndata_quality:\n  summary:\n    - rule: \"positive_amounts\"\n      status: PASSED\n      description: \"Ensures total_amount is greater than zero.\"\noperational_metadata:\n  frequent_joins:\n    - table: \"projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/sales_data/tables/customers\"\n      join_key: \"customer_id\"\n"
}

Python

Python

Antes de testar este exemplo, siga as instruções de configuração do Python no guia de início rápido do Knowledge Catalog: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Knowledge Catalog Python.

Para autenticar no Knowledge Catalog, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import dataplex_v1


def sample_lookup_context():
    # Create a client
    client = dataplex_v1.CatalogServiceClient()

    # Initialize request argument(s)
    request = dataplex_v1.LookupContextRequest(
        name="name_value",
        resources=["resources_value1", "resources_value2"],
    )

    # Make the request
    response = client.lookup_context(request=request)

    # Handle the response
    print(response)

O exemplo a seguir mostra como recuperar o contexto de uma tabela do BigQuery:

 from google.cloud import dataplex_v1

 # Initialize the client
 client = dataplex_v1.CatalogServiceClient()

 # Define the request with a seed resource
 request = dataplex_v1.LookupContextRequest(
     name="projects/test-project/locations/us",
     resources=["projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/test-dataset/tables/test-table"],
     options={"format": "yaml", "budget": "4000"}
 )

 # Retrieve the LLM-ready context
 response = client.lookup_context(request=request)
 context_yaml = response.context

 print(f"Retrieved Context: \n{context_yaml}")

Recuperar contexto para rotinas

É possível usar o método lookupContext para recuperar o contexto de rotinas do BigQuery, como funções definidas pelo usuário, funções de tabela e procedimentos armazenados. Os agentes podem usar esse contexto para entender o que uma rotina faz e como chamá-la, por exemplo, ao gerar consultas SQL. O contexto de uma rotina inclui as seguintes informações:

  • O tipo de rotina, como função escalar, função de tabela ou procedimento.
  • O idioma da rotina.
  • Os argumentos e o tipo de retorno da rotina.
  • O código-fonte da rotina (corpo da definição).
  • Descrições e outros metadados do Knowledge Catalog.

Para recuperar o contexto de uma rotina, inclua o nome da entrada da rotina na lista resources da solicitação. O nome da entrada tem o seguinte formato:

projects/PROJECT_ID/locations/LOCATION/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID/routines/ROUTINE_ID

Substitua:

  • PROJECT_ID: o ID do projeto que contém a rotina.
  • LOCATION: o local do conjunto de dados que contém a rotina (por exemplo, us).
  • DATASET_ID: o ID do conjunto de dados que contém a rotina.
  • ROUTINE_ID: o ID da rotina.

Quais são as práticas recomendadas para pesquisas de contexto?

Para otimizar os resultados ao usar o método lookupContext, considere as seguintes práticas recomendadas:

  • Solicite o tamanho selecionado do contexto de saída com o parâmetro context_budget. O método lookupContext vai tentar ajustar o contexto mais relevante à saída o mais próximo possível dos limites prescritos pelo parâmetro.
  • É possível listar até dez recursos de dados na lista resources. Por exemplo, incluir várias tabelas na lista resources faz com que a API forneça o contexto não apenas para essas tabelas, mas também para possíveis caminhos de mesclagem entre elas, fornecendo as orientações necessárias sobre como usar essas tabelas juntas.
  • Use a opção format, como yaml ou json, que melhor se alinhe à lógica de análise do LLM ou do agente para evitar transformações caras.

A seguir