Recuperar contexto para recursos de dados

O contexto que envolve seus dados equipa seus aplicativos de IA com um entendimento profundo dos ativos de dados, melhorando a acurácia e a relevância das respostas geradas por LLMs.

O método lookupContext preenche a lacuna de contexto usando uma única solicitação de API para recuperar um pacote pré-formatado de metadados de recursos de dados otimizado para fluxos de trabalho interativos de agentes. Você pode usar 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 qualquer recurso de dados armazenado no Knowledge Catalog, como tabelas, conjuntos de dados ou outras entradas do BigQuery.

Como recuperar o contexto de um recurso com o método lookupContext

  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.
    Metadados operacionais Junções e outros relacionamentos, com base em registros de consultas históricas e insights de dados. Para mais informações, consulte Visualizar relações de dados.
    Descrições de empresas Termos comerciais relacionados, visões gerais, anotações de catálogo, descrições capturadas no sistema de origem e geradas automaticamente no Knowledge Catalog, além de diretrizes.

    Observação: você pode usar o aspecto de diretrizes em recursos de dados para capturar mais contexto útil para os agentes quando eles descobrem, inspecionam ou usam recursos de dados.
    Perfil dos dados Estatísticas de distribuição, contagens de valores distintos, proporções nulas e valores de amostra.
    Qualidade dos dados Saídas de verificação automatizada da qualidade de dados em relação a regras predefinidas.
    Contexto sobre recursos de dados relacionados Contexto sobre recursos de dados relacionados, como termos do glossário ou outros recursos relacionados, como tabelas unidas com frequência. 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 obrigató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 seu 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 Knowledge Catalog

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. 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 a 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: o ID do seu Google Cloud projeto
  • LOCATION: a região em que o recurso está localizado (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 junções de esquema frequentes, e retorna as informações de relacionamento 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 de esquema, independente do valor de context_budget.

Uma solicitação de exemplo que recupera o contexto de uma tabela do BigQuery tem esta aparência:

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 a este:

{
"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 esta amostra, 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}")

Práticas recomendadas para o método lookupContext

Para otimizar seus 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 tenta ajustar o contexto mais relevante à saída o mais próximo possível dentro 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 junção entre elas, oferecendo orientação necessária sobre como usar essas tabelas juntas.
  • Use a opção format, como yaml ou json, que melhor se alinha à lógica de análise do LLM ou do agente para evitar transformações caras.

A seguir