Recuperar contexto para recursos de dados

O contexto que envolve seus dados equipa seus aplicativos de IA com um entendimento profundo dos recursos de dados, melhorando a precisão e a relevância das respostas geradas por 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 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, por exemplo, tabelas, conjuntos de dados ou outras entradas.

Como os agentes podem receber o contexto de dados?

  1. O agente recupera recursos de dados que são potencialmente 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 Joins e outros relacionamentos, com base em registros de consultas históricas e insights de dados. Para mais informações, consulte Visualizar relacionamentos 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 e diretrizes.

    Observação: é possível usar o aspecto de diretrizes em recursos de dados para capturar mais contexto útil para 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 de dados Saídas de verificação automatizada da qualidade de dados em relação a regras predefinidas.
    Contexto em recursos de dados relacionados Contexto em recursos de dados relacionados, como termos de 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 necessárias.

Funções exigidas

Para receber as permissões necessárias para chamar o lookupContext método, 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 a 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 com 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, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel Proprietário (roles/owner). Caso contrário, você pode receber essa permissão pelo papel Administrador de uso do serviço (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 do Protocolo de Contexto de Modelo (MCP) remoto 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 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 existe (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 relacionamentos entre os recursos solicitados, como joins 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 retornará todos os campos de esquema, independentemente do valor context_budget.

Um exemplo de solicitação que recupera o contexto de uma tabela do BigQuery é o seguinte:

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 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 Python Knowledge Catalog.

Para autenticar no Knowledge Catalog, configure o Application Default Credentials. Se quiser 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}")

Quais são algumas 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 comprimento selecionado do contexto de saída com o parâmetro context_budget. O método lookupContext tem como objetivo 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 join entre elas, fornecendo orientações necessárias 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