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 à l'aide d'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 interactifs des agents. Vous pouvez utiliser ce contexte compact et prêt pour les LLM afin d'aider vos agents à évaluer et à utiliser les é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 ou toute autre entrée.

Récupérer le contexte d'un élément avec la méthode lookupContext

  1. L'agent récupère les éléments de données potentiellement pertinents pour la récupération du contexte, par exemple à l'aide de la recherche sémantique de 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 élément 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.
    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 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 un 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 nuls et exemples de valeurs.
    Qualité des données Résultats des vérifications automatisées 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 de glossaire ou d'autres éléments 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 l'élément ou les éléments principaux.

  4. L'agent utilise cette réponse pour guider la sélection des éléments 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 de 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 avez besoin du rôle IAM Administrateur d'utilisation du service (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. 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) à distance de Knowledge Catalog ou la boîte à outils MCP pour les bases de données.

La méthode lookupContext filtre les ressources en fonction de vos autorisations. La réponse ne contient des données que pour les éléments auxquels votre identité dispose des autorisations Identity and Access Management (IAM) nécessaires pour accéder. 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 Google Cloud projet
  • LOCATION : région où se trouve l'élément (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 les jointures de schéma fréquentes, et renvoie les informations de relation dans le contexte.
  • OPTIONS : options qui vous permettent de définir le contexte :
    • format : format du fichier de contexte. Exemple : yaml.
    • context_budget : 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 à 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.Python

Pour vous authentifier auprès de Knowledge Catalog, configurez le service 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}")

Bonnes pratiques pour la méthode lookupContext

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 dans le résultat aussi près que possible des limites prescrites par le paramètre.
  • Vous pouvez répertorier jusqu'à dix é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 également 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 des transformations coûteuses.

Étape suivante