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

Le contexte qui entoure vos données permet à vos applications d'IA de bien comprendre vos assets 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 à l'aide d'une seule requête API pour récupérer un ensemble préformaté de métadonnées d'assets de données optimisé pour les workflows interactifs basés sur des agents. Vous pouvez utiliser ce contexte compact et prêt pour les LLM afin d'aider vos agents à évaluer et à utiliser les composants 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 ou toute autre entrée.

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

  1. L'agent récupère les composants 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 seule 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, comme les stratégies de partitionnement et de clustering BigQuery.
    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 des établissements Termes commerciaux 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 des informations contextuelles supplémentaires utiles 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 Résultats de la vérification automatisée de la qualité des données par rapport à des règles prédéfinies.
    Contexte sur les composants de données associés Contexte sur les composants de données associés, tels que les termes du glossaire ou d'autres composants associés, comme les tables fréquemment jointes. Le contexte renvoyé pour les éléments associés inclut la même plage d'éléments que pour le ou les éléments 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 Knowledge Catalog

Rôles requis pour activer les API

Pour activer les API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation grâce au rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation grâce au 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 composant 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 du catalogue de connaissances ou MCP Toolbox for Databases.

La méthode lookupContext filtre les ressources en fonction de vos autorisations. La réponse ne contient des données que pour les composants auxquels votre identité est autorisée à accéder (autorisations IAM). 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 composant 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 le composant (par exemple, us-central1)
  • RESOURCES : jusqu'à dix 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 sur les relations dans le contexte.
  • OPTIONS : options permettant de définir le contexte :
    • format est le format du fichier de contexte. Exemple :yaml
    • context_budget correspond au 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 de schéma, quelle que soit la valeur 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 à ce qui suit :

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

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 s'efforcera d'intégrer le contexte le plus pertinent dans la sortie, aussi près que possible des limites prescrites par le paramètre.
  • Vous pouvez lister jusqu'à 10 composants 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 éventuels chemins de jointure entre elles. Vous obtenez ainsi les conseils nécessaires pour 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 des transformations coûteuses.

Étapes suivantes