Récupérer le contexte des composants de données

Le contexte qui entoure vos données permet à vos applications d'IA de comprendre en profondeur vos éléments de données, ce qui améliore la précision et la pertinence des réponses générées par les LLM.

La méthode lookupContext comble le manque de contexte en utilisant une seule requête API pour récupérer un ensemble préformaté de métadonnées d'éléments de données optimisé pour les workflows agentiques interactifs. Vous pouvez utiliser ce contexte compact, prêt pour les LLM, pour ancrer vos agents dans l'évaluation et l'utilisation des éléments de données.

Vous pouvez utiliser la méthode lookupContext pour tous les éléments de données stockés dans Knowledge Catalog, par exemple les tables BigQuery, les ensembles de données et les routines, ainsi que les domaines de données et toutes les autres entrées.

Comment les agents peuvent-ils obtenir le contexte des données ?

  1. L'agent récupère les éléments de données potentiellement pertinents pour la récupération du contexte, par exemple en utilisant la recherche sémantique Knowledge Catalog.
  2. L'agent utilise la méthode lookupContext pour effectuer un seul appel d'API ou une requête d'outil MCP qui récupère le contexte d'un asset spécifique.

  3. La méthode renvoie une réponse contenant un bloc de texte préformaté. Selon le paramètre format que vous spécifiez dans la requête, le document peut être au format YAML, XML ou JSON.

    La réponse contient les éléments de contexte suivants :

    Élément de contexte Description
    Métadonnées techniques Schémas de ressources et configurations physiques, telles que les stratégies de partitionnement et de clustering BigQuery, et définitions de routines BigQuery, y compris les arguments, les types renvoyés et le code source.
    Métadonnées opérationnelles Jointures et autres relations, basées sur les journaux de requêtes historiques et les insights sur les données. Pour en savoir plus, consultez Afficher les relations entre les données.
    Descriptions de l'établissement Termes métier associés, présentations, annotations de catalogue, descriptions capturées dans le système source et générées automatiquement dans Knowledge Catalog, et consignes.

    Remarque : Vous pouvez utiliser l'aspect "Consignes" sur les éléments de données pour capturer du contexte supplémentaire utile aux agents lorsqu'ils découvrent, inspectent ou utilisent des éléments de données.
    Profil de données Statistiques de distribution, nombre de valeurs distinctes, ratios de valeurs nulles et exemples de valeurs.
    Qualité des données Vérification automatisée de la qualité des données par rapport à des règles prédéfinies.
    Contexte sur les éléments de données associés Contexte sur les éléments de données associés, tels que les termes du glossaire ou d'autres éléments associés, comme les tables fréquemment jointes. Le contexte renvoyé pour les assets associés inclut la même gamme d'éléments que pour l'asset ou les assets principaux.

  4. L'agent utilise cette réponse pour guider la sélection des composants pertinents ou leur utilisation.

Avant de commencer

Avant d'utiliser la méthode lookupContext, assurez-vous de disposer des rôles nécessaires et d'activer les API requises.

Rôles requis

Pour obtenir les autorisations nécessaires pour appeler la méthode lookupContext, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre Google Cloud projet iam.gserviceaccount.com :

  • Accès en lecture aux ressources du catalogue, y compris les entrées, les groupes d'entrées et les glossaires : Lecteur de catalogue Dataplex (roles/dataplex.catalogViewer)

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Activer les API

Pour utiliser la méthode lookupContext, activez les API suivantes dans votre projet :

  • API Dataplex

Rôles requis pour activer les API

Pour activer des API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez l'obtenir via le rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

Activer l'API

Récupérer le contexte d'un élément de données

Pour récupérer le contexte d'un élément de données, accédez directement à la méthode lookupContext avec l'API Dataplex ou utilisez le serveur MCP (Model Context Protocol) distant de Knowledge Catalog ou MCP Toolbox for Databases.

La méthode lookupContext filtre les ressources en fonction de vos autorisations. La réponse ne contient que les données des éléments pour lesquels votre identité dispose des autorisations IAM (Identity and Access Management) nécessaires. Si vous ne disposez d'aucune autorisation sur les ressources demandées, la méthode renvoie une réponse vide.

REST

Pour récupérer le contexte d'un élément de données, envoyez la requête suivante :

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

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet Google Cloud
  • LOCATION : région où se trouve l'élément (par exemple, us-central1)
  • RESOURCES : jusqu'à 10 noms d'entrées pour lesquels récupérer le contexte, au format projects/{project}/locations/{location}/entryGroups/{entryGroup}/entries/{entry}. Pour plusieurs ressources, l'API établit des relations entre les ressources demandées, telles que des jointures de schéma fréquentes, et renvoie les informations de relation dans le contexte.
  • OPTIONS : options permettant de définir le contexte :
    • format est le format du fichier de contexte. Exemple :yaml
    • context_budget est le nombre de caractères auquel la réponse est limitée. Si vous définissez le paramètre all_schema_fields sur true, l'API renvoie tous les champs du schéma, quelle que soit la valeur de context_budget.

Voici un exemple de requête qui récupère le contexte d'une table 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 réponse est un bloc de texte préformaté semblable à celui-ci :

{
"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

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide de Knowledge Catalog à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Knowledge Catalog pour Python.

Pour vous authentifier auprès de Knowledge Catalog, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement 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)

L'exemple suivant montre comment récupérer le contexte d'une table 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}")

Récupérer le contexte des routines

Vous pouvez utiliser la méthode lookupContext pour récupérer le contexte des routines BigQuery, telles que les fonctions définies par l'utilisateur, les fonctions de table et les procédures stockées. Les agents peuvent utiliser ce contexte pour comprendre ce que fait une routine et comment l'appeler, par exemple lorsqu'ils génèrent des requêtes SQL. Le contexte d'une routine inclut les informations suivantes :

  • Type de routine, tel que fonction scalaire, fonction de table ou procédure.
  • Langue de la routine.
  • Arguments et type renvoyé de la routine.
  • Code source de la routine (corps de la définition).
  • Descriptions et autres métadonnées de Knowledge Catalog.

Pour récupérer le contexte d'une routine, incluez le nom d'entrée de la routine dans la liste resources de la requête. Le nom de l'entrée est au format suivant :

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

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet contenant la routine.
  • LOCATION : emplacement de l'ensemble de données contenant la routine (par exemple, us).
  • DATASET_ID : ID de l'ensemble de données contenant la routine.
  • ROUTINE_ID : ID de la routine.

Quelles sont les bonnes pratiques pour les recherches de contexte ?

Pour optimiser vos résultats lorsque vous utilisez la méthode lookupContext, tenez compte des bonnes pratiques suivantes :

  • Demandez la longueur sélectionnée du contexte de sortie avec le paramètre context_budget. La méthode lookupContext vise à intégrer le contexte le plus pertinent possible dans la sortie, dans les limites prescrites par le paramètre.
  • Vous pouvez lister jusqu'à 10 éléments de données dans la liste resources. Par exemple, si vous incluez plusieurs tables dans la liste resources, l'API fournit le contexte non seulement pour ces tables, mais aussi pour les chemins de jointure possibles entre elles, ce qui fournit des conseils nécessaires sur la façon d'utiliser ces tables ensemble.
  • Utilisez l'option format, telle que yaml ou json, qui correspond le mieux à la logique d'analyse du LLM ou de l'agent pour éviter les transformations coûteuses.

Étapes suivantes