Recupera el contexto de los recursos de datos

El contexto que rodea tus datos dota a tus aplicaciones de IA de una comprensión profunda de tus activos de datos, lo que mejora la exactitud y relevancia de las respuestas generadas por el LLM.

El método lookupContext cierra la brecha de contexto con una sola solicitud a la API para recuperar un paquete con formato previo de metadatos de activos de datos optimizados para flujos de trabajo de agentes interactivos. 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 y rutinas, así como dominios de datos y cualquier otra entrada.

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

  1. El agente recupera recursos de datos que podrían ser pertinentes para la recuperación de 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 recurso 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 parámetros de configuración físicos, como las estrategias de partición y agrupamiento en clústeres de BigQuery, y las definiciones de rutinas de BigQuery, incluidos los argumentos, los tipos de datos que se devuelven y el código fuente.
    Metadatos operativos Uniones y otras relaciones, basadas en registros de consultas históricos 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, descripciones generales, anotaciones del catálogo, descripciones capturadas en el sistema de origen y generadas de forma automática 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 Verificación automatizada de la calidad de los datos con reglas predefinidas.
    Contexto sobre los recursos de datos relacionados Contexto sobre los recursos de datos relacionados, como los términos del glosario o de otros recursos relacionados, como las tablas unidas con frecuencia. El contexto que se devuelve 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 habilita 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 proyecto de Google Cloud 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 Dataplex

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 de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de 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 al método lookupContext directamente 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 de Identity and Access Management (IAM) necesarios para acceder. Si no tienes permisos en los recursos solicitados, el método devuelve 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 del proyecto de Google Cloud .
  • LOCATION: la región en la que existe el recurso (por ejemplo, us-central1)
  • RESOURCES: hasta diez nombres de entradas 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 uniones de esquemas frecuentes, y devuelve 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 configuras el parámetro all_schema_fields como true, la API devuelve todos los campos del esquema, independientemente del valor de context_budget.

A continuación, se muestra un ejemplo de solicitud que recupera el contexto de una tabla de 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

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 las bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Knowledge Catalog para 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}")

Recupera el contexto de las rutinas

Puedes usar el método lookupContext para recuperar el contexto de las rutinas de BigQuery, como las funciones definidas por el usuario, las funciones de tabla y los procedimientos almacenados. Los agentes pueden usar este contexto para comprender qué hace una rutina y cómo llamarla, por ejemplo, cuando generan consultas en SQL. El contexto de una rutina incluye la siguiente información:

  • El tipo de rutina, como función escalar, función de tabla o procedimiento.
  • Es el lenguaje de la rutina.
  • Son los argumentos y el tipo de datos que se devuelve de la rutina.
  • Es el código fuente de la rutina (cuerpo de la definición).
  • Descripciones y otros metadatos de Knowledge Catalog.

Para recuperar el contexto de una rutina, incluye el nombre de entrada de la rutina en la lista resources de la solicitud. El nombre de la entrada tiene el siguiente formato:

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

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto que contiene la rutina.
  • LOCATION: Es la ubicación del conjunto de datos que contiene la rutina (por ejemplo, us).
  • DATASET_ID: Es el ID del conjunto de datos que contiene la rutina.
  • ROUTINE_ID: el ID de la rutina.

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

Para optimizar los 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 relevante al resultado lo más cerca posible dentro de los límites que prescribe el parámetro.
  • Puedes incluir 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 mejor se alinee con la lógica de análisis del LLM o del agente para evitar transformaciones costosas.

¿Qué sigue?