Recupera el contexto de los recursos de datos

El contexto que rodea tus datos equipa tus aplicaciones de IA con una comprensión profunda de tus activos de datos, lo que mejora la precisión 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 activos de datos optimizados para flujos de trabajo interactivos basados en agentes. Puedes usar este contexto compacto y listo para LLM para fundamentar a tus agentes en la evaluación y el uso de los 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 recuperar el contexto de un recurso con el método lookupContext

  1. El agente recupera recursos de datos que podrían ser relevantes para la recuperación del contexto, por ejemplo, con 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 de MCP que recupera el contexto de un activo específico.

  3. El método devuelve una respuesta que contiene un bloque de texto con formato previo. 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, basadas en registros históricos de consultas y estadísticas de datos. Para obtener más información, consulta Cómo ver las relaciones de datos.
    Descripciones de la empresa Términos comerciales relacionados, resúmenes, anotaciones del catálogo, descripciones capturadas en el sistema fuente 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 que sea ú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 de valores nulos 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 del glosario o recursos relacionados, como tablas que se unen con frecuencia El contexto que se devuelve para los activos relacionados incluye el mismo rango de elementos que para el activo o los activos principales.

  4. El agente usa esta respuesta para guiar la selección de recursos pertinentes 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:

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 a través de 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 rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

Habilitar la API

Recupera el contexto de un recurso de datos

Para recuperar el contexto de un activo 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 For Databases.

El método lookupContext filtra los recursos según tus permisos. La respuesta solo contiene datos de 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 devuelve una respuesta vacía.

REST

Para recuperar el contexto de un activo 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 proyecto de Google Cloud .
  • LOCATION: Es la región en la que existe el activo (por ejemplo, us-central1).
  • RESOURCES: Hasta diez nombres de entrada para recuperar el contexto, con el formato projects/{project}/locations/{location}/entryGroups/{entryGroup}/entries/{entry}. En el caso de varios recursos, la API establece relaciones entre los recursos solicitados, como combinaciones de esquemas frecuentes, y devuelve la información de la relación en el contexto.
  • OPTIONS: 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 configuras el parámetro all_schema_fields como true, la API devolverá todos los campos del esquema, independientemente del valor de 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 con formato previo 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 para Python que encontrarás en la guía de inicio rápido de Knowledge Catalog sobre cómo usar las bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Knowledge Catalog Python.

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}")

Prácticas recomendadas para el método lookupContext

Para optimizar tus resultados cuando uses el método lookupContext, ten en cuenta 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 pertinente en la salida lo más cerca posible dentro de los límites prescritos por el parámetro.
  • Puedes incluir hasta diez recursos de datos en la lista resources. Por ejemplo, incluir varias tablas en la lista resources hace que la API proporcione 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?