Recupera el contexto de los recursos de datos

El contexto que rodea tus datos equipa tus aplicaciones de IA con un conocimiento profundo de tus recursos de datos, lo que mejora la exactitud y la relevancia de las respuestas generadas por LLM.

El método lookupContext cierra la brecha de contexto con una sola solicitud a la API para recuperar un paquete preformateado de metadatos de recursos de datos optimizados para flujos de trabajo interactivos de agentes. Puedes usar este contexto compacto y listo para LLM para fundamentar a tus agentes en la evaluación y el uso de recursos de datos.

Puedes usar el método lookupContext para cualquier recurso de datos almacenado en Knowledge Catalog, por ejemplo, tablas de BigQuery, conjuntos de datos o cualquier otra entrada.

¿Cómo pueden los agentes obtener contexto de datos?

  1. El agente recupera los recursos de datos que son potencialmente relevantes para la recuperación del contexto, por ejemplo, mediante la búsqueda semántica de Knowledge Catalog.
  2. El agente usa el método lookupContext para realizar una sola llamada a la API o una solicitud de herramienta MCP que recupera el contexto de un recurso específico.

  3. El método muestra una respuesta que contiene un bloque de texto preformateado. Según el parámetro format que especifiques en la solicitud, el documento puede estar en formato YAML, XML o JSON.

    La respuesta contiene los siguientes elementos de contexto:

    Elemento de contexto Descripción
    Metadatos técnicos Esquemas de recursos y configuraciones físicas, como las estrategias de partición y agrupamiento en clústeres de BigQuery
    Metadatos operativos Uniones y otras relaciones, según los registros de consultas históricos y las estadísticas de datos (para obtener más información, consulta Visualiza las relaciones de datos)
    Descripciones de la empresa Términos comerciales relacionados, resúmenes, anotaciones de catálogo, descripciones capturadas en el sistema de origen y generadas automáticamente en Knowledge Catalog, y lineamientos.

    Nota: Puedes usar el aspecto de lineamientos en los recursos de datos para capturar contexto adicional útil para los agentes cuando descubren, inspeccionan o usan recursos de datos.
    Perfil de datos Estadísticas de distribución, recuentos de valores distintos, proporciones nulas y valores de muestra
    Calidad de los datos Resultados de la verificación automatizada de la calidad de los datos en comparación con reglas predefinidas
    Contexto sobre los recursos de datos relacionados Contexto sobre los recursos de datos relacionados, como términos de glosario u otros recursos relacionados, como tablas unidas con frecuencia (el contexto que se muestra para los recursos relacionados incluye el mismo rango de elementos que para el recurso o los recursos principales)

  4. El agente usa esta respuesta para guiar la selección de recursos relevantes o su uso.

Antes de comenzar

Antes de usar el método lookupContext, asegúrate de tener los roles necesarios y habilitar las APIs requeridas.

Roles obligatorios

Para obtener los permisos que necesitas para llamar al método lookupContext, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu Google Cloud proyecto iam.gserviceaccount.com:

  • Acceso de lectura a los recursos del catálogo, incluidas las entradas, los grupos de entradas y los glosarios: Visualizador de Dataplex Catalog (roles/dataplex.catalogViewer)

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Habilita las APIs

Para usar el método lookupContext, habilita las siguientes APIs en tu proyecto:

  • API de Knowledge Catalog

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol Propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol Administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén información para otorgar roles.

Habilitar la API

Recupera el contexto de un recurso de datos

Para recuperar el contexto de un recurso de datos, accede directamente al método lookupContext con la API de Dataplex o usa el servidor remoto del Protocolo de contexto del modelo (MCP) de Knowledge Catalog o MCP Toolbox para bases de datos.

El método lookupContext filtra los recursos según tus permisos. La respuesta contiene datos solo para los recursos a los que tu identidad tiene los permisos necesarios de Identity and Access Management (IAM) para acceder. Si no tienes permisos para los recursos solicitados, el método muestra una respuesta vacía.

REST

Para recuperar el contexto de un recurso de datos, envía la siguiente solicitud:

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

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID de tu Google Cloud proyecto.
  • LOCATION: Es la región en la que existe el recurso (por ejemplo, us-central1).
  • RESOURCES: Son hasta diez nombres de entradas para recuperar el contexto, con el formato projects/{project}/locations/{location}/entryGroups/{entryGroup}/entries/{entry}. Para varios recursos, la API establece relaciones entre los recursos solicitados, como las uniones de esquemas frecuentes, y muestra la información de la relación en el contexto.
  • OPTIONS: Son las opciones que te permiten definir el contexto:
    • format es el formato del archivo de contexto. Por ejemplo, yaml.
    • context_budget es la cantidad de caracteres a la que se limita la respuesta. Si estableces el parámetro all_schema_fields en true, la API muestra todos los campos de esquema, independientemente del valor context_budget.

Una solicitud de ejemplo que recupera el contexto de una tabla de BigQuery se ve de la siguiente manera:

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

La respuesta es un bloque de texto preformateado similar al siguiente:

{
"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 probar este ejemplo, sigue las instrucciones de configuración de Python que encontrarás en la guía de inicio rápido de Knowledge Catalog sobre las bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de PythonKnowledge Catalog.

Para autenticarte en Knowledge Catalog, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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)

En el siguiente ejemplo, se muestra cómo recuperar el contexto de una tabla de 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}")

¿Cuáles son algunas prácticas recomendadas para las búsquedas de contexto?

Para optimizar los resultados cuando usas el método lookupContext, considera las siguientes prácticas recomendadas:

  • Solicita la longitud seleccionada del contexto de salida con el parámetro context_budget. El método lookupContext intentará ajustar el contexto más relevante en la salida lo más cerca posible dentro de los límites prescritos por el parámetro.
  • Puedes enumerar hasta diez recursos de datos en la lista resources. Por ejemplo, si incluyes varias tablas en la lista resources, la API proporciona el contexto no solo para esas tablas, sino también para las posibles rutas de unión entre ellas, lo que proporciona la orientación necesaria sobre cómo usar estas tablas juntas.
  • Usa la opción format, como yaml o json, que se alinee mejor con la lógica de análisis del LLM o del agente para evitar transformaciones costosas.

¿Qué sigue?