Configurer les conditions préalables pour les tâches d'enrichissement

Avant de pouvoir créer des tâches d'enrichissement dans Knowledge Studio, vous devrez peut-être configurer plusieurs composants d'infrastructure sous-jacents en fonction de votre architecture de sécurité et de vos sources de données cibles.

Ce guide explique comment configurer des comptes de service gérés par le client, des fournisseurs d'authentification tiers, des buckets Cloud Storage et des vues Cloud Logging.

Le tableau suivant décrit les configurations préalables et quand vous devez les configurer :

Fonctionnalité de configuration Quand configurer
API Google Cloud Obligatoire. Vous devez activer les API Google Cloud sous-jacentes pour exécuter des workflows d'enrichissement.
Compte de service géré par le client Vous souhaitez limiter l'accès en lecture et en écriture à vos ensembles de données cibles.
Rôles IAM (Identity and Access Management) des utilisateurs Vous devez accorder aux gestionnaires et aux réviseurs de workflows les autorisations nécessaires pour générer et approuver des métadonnées.
Fournisseurs d'authentification tiers Vous vous connectez à des sources de connaissances tierces (comme Microsoft SharePoint, Atlassian Confluence ou GitHub).
Buckets Cloud Storage Vous ingérez un contexte d'entreprise non structuré (comme des fichiers PDF, Markdown et CSV) et des ensembles de données d'évaluation.
Ensembles de données d'évaluation Vous souhaitez fournir des requêtes de départ et des ensembles de données de benchmark pour suivre activement la précision de l'agent.
Traces d'agent pour l'auto-apprentissage Vous souhaitez que l'agent d'enrichissement analyse automatiquement les interactions des agents Gemini Enterprise en aval.
Profilage des données et insights sur les données Recommended. Vous souhaitez améliorer la qualité de l'enrichissement en générant des profils statistiques et des insights d'IA de référence sur les tables fréquemment utilisées.

Avant de commencer

  1. Connectez-vous à votre compte Google Cloud . Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Dataplex, Data Lineage, BigQuery, Cloud Storage, and IAM Credentials APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Dataplex, Data Lineage, BigQuery, Cloud Storage, and IAM Credentials APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

    8.

Détails des API requises

Pour configurer et exécuter des tâches d'enrichissement, les API activées effectuent les fonctions suivantes :

Nom d'API Identifiant de service Objectif dans les workflows d'enrichissement
API Dataplex dataplex.googleapis.com API du plan de contrôle principal. Gère EnrichmentTask, EnrichmentRun, les ensembles de contexte, les demandes de modification et EnrichmentChatService.
API BigQuery bigquery.googleapis.com Obligatoire pour analyser les schémas de table, ingérer l'historique d'exécution SQL et interroger les tables de trace d'analyse BigQuery Agent Analytics.
API Cloud Storage storage.googleapis.com Requis pour ingérer des ensembles d'évaluation et gérer des exemples d'ensembles de données d'évaluation.
API IAM Service Account Credentials iamcredentials.googleapis.com Requis pour authentifier l'agent d'exécution de manière sécurisée et accorder des identifiants éphémères (SLC) pendant les tâches.

Configurer un compte de service géré par le client

Les tâches d'enrichissement utilisent un compte de service géré par le client pour exécuter des opérations. Cela vous permet de limiter l'accès en lecture et en écriture à vos ensembles de données cibles.

  1. Créez le compte de service.

    Pour créer un compte de service, vous devez être propriétaire du projet (roles/owner) ou éditeur (roles/editor), ou disposer du rôle Administrateur de compte de service (roles/iam.serviceAccountAdmin).

    Un compte de service dédié isole vos opérations d'enrichissement, ce qui vous permet de n'accorder que les autorisations de lecture et d'écriture spécifiques nécessaires à ces tâches, sans affecter les autres charges de travail.

    Pour créer un compte de service, procédez comme suit :

    Google Cloud CLI

    Pour créer un compte de service, exécutez la commande gcloud iam service-accounts create :

    Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

    • SERVICE_ACCOUNT_NAME : nom de votre compte de service.

    Exécutez la commande suivante :

    Linux, macOS ou Cloud Shell

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
    --description="Service Account for Dataplex Knowledge Catalog enrichment agent execution" \
    --display-name="Knowledge Catalog enrichment agent SA"

    Windows (PowerShell)

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME `
    --description="Service Account for Dataplex Knowledge Catalog enrichment agent execution" `
    --display-name="Knowledge Catalog enrichment agent SA"

    Windows (cmd.exe)

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME ^
    --description="Service Account for Dataplex Knowledge Catalog enrichment agent execution" ^
    --display-name="Knowledge Catalog enrichment agent SA"

    REST

    Avant d'utiliser les données de requête, effectuez les remplacements suivants :

    • SERVICE_ACCOUNT_NAME : nom de votre compte de service.
    • TARGET_PROJECT_ID : ID de votre projet Google Cloud

    Méthode HTTP et URL :

    POST https://iam.googleapis.com/v1/projects/TARGET_PROJECT_ID/serviceAccounts

    Corps JSON de la requête :

    {
   "accountId": "SERVICE_ACCOUNT_NAME",
   "serviceAccount": {
    "displayName": "Knowledge Catalog enrichment agent SA",
    "description": "Service Account for Dataplex Knowledge Catalog enrichment agent execution"
   }
  }

    Pour envoyer votre requête, développez l'une des options suivantes :

    Vous devriez recevoir un code d'état indiquant le succès de l'opération (2xx), ainsi qu'une réponse vide.

  2. Attribuez les rôles IAM nécessaires au niveau des ressources au compte de service d'exécution sur vos champs d'application cibles :

    • Éditeur de catalogue Dataplex (roles/dataplex.catalogEditor) et Lecteur de catalogue Dataplex (roles/dataplex.catalogViewer) : permet à l'agent d'inspecter les métadonnées du catalogue, de créer des entrées de travail intermédiaires et de publier manuellement les enrichissements approuvés.
    • (Facultatif) Approbateur de workflows Dataplex (roles/dataplex.workflowApprover) : requis uniquement si vous activez la publication automatique sur votre tâche. Permet à l'agent d'approuver et de publier automatiquement ses propres demandes de modification de métadonnées.
    • Lecteur de données BigQuery (roles/bigquery.dataViewer) : permet à l'agent de lire les schémas de table, les métadonnées de colonne et les tables de trace d'analyse de l'agent.

    Remarque : Les exemples de code suivants accordent ces rôles au niveau du projet pour faciliter la configuration. Pour les systèmes de production, nous vous recommandons vivement d'accorder ces rôles de manière sécurisée au niveau des ressources sur vos ensembles de données cibles spécifiques.

    Pour attribuer ces rôles standards, procédez comme suit :

    Pour ajouter une liaison de stratégie IAM à un projet, utilisez la commande gcloud projects add-iam-policy-binding :

    Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

    • SERVICE_ACCOUNT_NAME : nom de votre compte de service.
    • TARGET_PROJECT_ID : ID de votre projet Google Cloud

    Exécutez la commande suivante :

    Linux, macOS ou Cloud Shell

    gcloud projects add-iam-policy-binding TARGET_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/dataplex.catalogEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/bigquery.dataViewer"

    Windows (PowerShell)

    gcloud projects add-iam-policy-binding TARGET_PROJECT_ID `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/dataplex.catalogEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/bigquery.dataViewer"

    Windows (cmd.exe)

    gcloud projects add-iam-policy-binding TARGET_PROJECT_ID ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/dataplex.catalogEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/bigquery.dataViewer"

  3. Accordez aux utilisateurs l'autorisation d'emprunter l'identité du compte de service en leur attribuant le rôle Utilisateur du compte de service (roles/iam.serviceAccountUser) :

    Les utilisateurs qui créent les tâches d'enrichissement dans la console doivent disposer de cette autorisation pour pouvoir spécifier et associer ce compte de service à la tâche.

    Pour attribuer le rôle "Utilisateur du compte de service" à des utilisateurs, procédez comme suit :

    Pour ajouter une liaison de stratégie IAM à un compte de service, utilisez la commande gcloud iam service-accounts add-iam-policy-binding :

    Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

    • SERVICE_ACCOUNT_NAME : nom de votre compte de service.
    • TARGET_PROJECT_ID : ID de votre projet Google Cloud
    • USER_EMAIL : adresse e-mail de l'utilisateur.

    Exécutez la commande suivante :

    Linux, macOS ou Cloud Shell

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com \
    --member="user:USER_EMAIL@domain.com" \
    --role="roles/iam.serviceAccountUser"

    Windows (PowerShell)

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com `
    --member="user:USER_EMAIL@domain.com" `
    --role="roles/iam.serviceAccountUser"

    Windows (cmd.exe)

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com ^
    --member="user:USER_EMAIL@domain.com" ^
    --role="roles/iam.serviceAccountUser"

  4. Autorisez l'agent de service Knowledge Catalog interne à emprunter l'identité de ce compte de service en lui attribuant le rôle Créateur de jetons du compte de service (roles/iam.serviceAccountTokenCreator) :

    Cela permet au service Knowledge Catalog sous-jacent d'assumer l'identité de ce compte de service dédié et ses autorisations restreintes lorsqu'il exécute les opérations d'enrichissement en arrière-plan en votre nom.

    Pour autoriser l'agent à emprunter l'identité du compte de service, procédez comme suit :

    Pour ajouter une liaison de stratégie IAM à un compte de service, utilisez la commande gcloud iam service-accounts add-iam-policy-binding :

    Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

    • SERVICE_ACCOUNT_NAME : nom de votre compte de service.
    • TARGET_PROJECT_ID : ID de votre projet Google Cloud
    • TARGET_PROJECT_NUMBER : numéro de votre projet Google Cloud.

    Exécutez la commande suivante :

    Linux, macOS ou Cloud Shell

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com \
    --member="serviceAccount:service-TARGET_PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
    --role="roles/iam.serviceAccountTokenCreator"

    Windows (PowerShell)

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com `
    --member="serviceAccount:service-TARGET_PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" `
    --role="roles/iam.serviceAccountTokenCreator"

    Windows (cmd.exe)

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com ^
    --member="serviceAccount:service-TARGET_PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" ^
    --role="roles/iam.serviceAccountTokenCreator"

Accorder les rôles IAM requis aux utilisateurs

Pour vous assurer que votre équipe peut gérer les workflows d'enrichissement et examiner les propositions générées par l'IA, attribuez les rôles IAM appropriés à vos utilisateurs. Pour savoir comment attribuer ces rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Les gestionnaires de workflows (tels que les intendants des données) qui créent, configurent et surveillent les tâches ont besoin des rôles suivants :

  • Éditeur Dataplex DataScan (roles/dataplex.dataScanEditor) ou Éditeur Dataplex (roles/dataplex.editor) : permet aux utilisateurs de créer, modifier, déclencher et annuler des tâches d'enrichissement.
  • Utilisateur du compte de service (roles/iam.serviceAccountUser) sur le compte de service géré par le client : requis pour associer le compte de service en tant qu'identité d'exécution de la tâche.

Les réviseurs de modifications (tels que les propriétaires de domaine ou les experts du domaine) qui inspectent, approuvent et publient des propositions de métadonnées générées par l'IA dans le catalogue ont besoin des rôles suivants :

  • Éditeur de catalogue Dataplex (roles/dataplex.catalogEditor) et Lecteur de catalogue Dataplex (roles/dataplex.catalogViewer) : requis pour ouvrir des demandes de modification, inspecter les différences entre les propositions côte à côte et modifier les descriptions de manière intégrée.
  • Approbateur de workflows Dataplex (roles/dataplex.workflowApprover) : requis pour approuver et publier des demandes de modification dans le catalogue actif.
  • Lecteur Dataplex DataScan (roles/dataplex.dataScanViewer) ou Lecteur Dataplex (roles/dataplex.viewer) : requis pour examiner les scores de confiance par proposition, le diagnostic des échec du test et les fiches d'évaluation en aval.

Configurer des fournisseurs d'authentification tiers

Lorsque vous connectez l'agent d'enrichissement à des sources de connaissances tierces (comme Microsoft SharePoint, Atlassian Confluence ou GitHub), vous devez configurer un fournisseur d'authentification à l'aide du service d'identité d'agent de Google Cloud.

Agent Identity agit comme un gestionnaire d'identifiants de sécurité qui chiffre vos jetons tiers dans votre projet, ce qui garantit que les opérateurs humains n'ont jamais à gérer les codes secrets du client bruts lors de l'exécution des tâches.

Pour obtenir des instructions détaillées sur la génération des jetons requis et la configuration du fournisseur d'authentification pour des plates-formes externes spécifiques, consultez Configurer des connecteurs externes pour les tâches d'enrichissement.

Configurer les autorisations IAM pour les fournisseurs d'authentification

Pour permettre à l'agent d'enrichissement de récupérer de manière sécurisée vos identifiants de fournisseur d'authentification de manière dynamique lors d'une exécution active, vous devez attribuer le rôle Administrateur d'identité de l'agent (roles/agentidentity.admin) à l'agent de service Knowledge Catalog géré (service-<var>PROJECT_NUMBER</var>@gcp-sa-dataplex.iam.gserviceaccount.com). Vous pouvez attribuer ce rôle au niveau de la ressource du fournisseur d'authentification ou au niveau du projet.

De plus, l'utilisateur humain qui associe le fournisseur d'authentification à la tâche dans la consoleGoogle Cloud doit disposer de l'autorisation agentidentity.authProviders.get (incluse dans Lecteur d'identité de l'agent (roles/agentidentity.viewer)) sur le fournisseur d'authentification.

Préparer des buckets Cloud Storage

Cloud Storage sert de couche principale de préproduction basée sur des fichiers, d'ingestion de contexte et d'exportation d'artefacts pour les workflows d'enrichissement des connaissances.

Vous pouvez configurer l'agent pour qu'il ingère des fichiers d'un ou de plusieurs buckets d'entrée afin d'ancrer son raisonnement dans les connaissances de votre domaine d'entreprise. Les types de contexte compatibles sont les suivants :

  • Documentation de domaine et dictionnaires de données : fichiers Markdown, texte brut, PDF, HTML ou CSV contenant des définitions de table, des glossaires d'entreprise, des procédures d'exploitation standards, des architectures de pipeline de données ou des consignes de dénomination des colonnes.

  • Ensembles de données d'évaluation : fichiers JSONL ou CSV stockant les requêtes de départ et les ensembles de requêtes de validation retenus. Pour en savoir plus, consultez Formater les ensembles de données d'évaluation.

  • Scripts SQL et de transformation de référence : scripts SQL enregistrés, définitions de modèles dbt ou logique de transformation ETL qui fournissent des signaux de contexte concernant les modèles de jointure de table et les calculs métier.

Une fois configuré, l'agent d'enrichissement peut également exporter des bundles structurés et exécuter des artefacts vers un bucket de sortie. Les artefacts de sortie compatibles incluent les suivants :

  • Rapports d'évaluation détaillés : fiches d'évaluation complètes indiquant les écarts de précision par requête, le diagnostic des échec du test et les métriques de distribution de la confiance.

Pour vous assurer que l'agent d'enrichissement peut fonctionner en dehors du bucket, vérifiez que votre compte de service d'exécution dispose des autorisations nécessaires.

  • Attribuez le rôle Lecteur des objets (roles/storage.objectViewer) sur les buckets d'entrée afin que l'agent puisse lire les documents et les fichiers de configuration des étapes.
  • (Facultatif) Accordez le rôle Créateur d'objets (roles/storage.objectCreator) sur le bucket de sortie si vous souhaitez que l'agent enregistre les artefacts d'exécution et les journaux de validation.

Pour accorder au compte de service l'accès aux buckets Cloud Storage, procédez comme suit :

Pour ajouter une liaison de stratégie IAM à un bucket de stockage, utilisez la commande gcloud storage buckets add-iam-policy-binding :

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

  • CUSTOMER_BUCKET : nom de votre bucket Cloud Storage
  • SERVICE_ACCOUNT_NAME : nom de votre compte de service.
  • TARGET_PROJECT_ID : ID de votre projet Google Cloud

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

gcloud storage buckets add-iam-policy-binding gs://CUSTOMER_BUCKET \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/storage.objectViewer"

Windows (PowerShell)

gcloud storage buckets add-iam-policy-binding gs://CUSTOMER_BUCKET `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/storage.objectViewer"

Windows (cmd.exe)

gcloud storage buckets add-iam-policy-binding gs://CUSTOMER_BUCKET ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/storage.objectViewer"

Formater les ensembles de données d'évaluation

Les workflows d'enrichissement peuvent extraire automatiquement des informations sans exemples. Toutefois, fournir des ensembles de données d'évaluation permet à l'agent de se tester et d'améliorer sa précision.

Vous pouvez fournir deux types d'ensembles de données :

  • Ensemble de curation : liste d'exemples de questions d'utilisateurs et de requêtes SQL attendues. L'agent utilise cette liste pour s'entraîner et rédiger de meilleurs résumés de tableaux.

  • Ensemble d'évaluation : liste distincte de questions utilisées pour évaluer les performances de l'agent. Si l'agent n'est pas performant, cet ensemble d'évaluation empêche la publication de mises à jour de mauvaise qualité dans votre catalogue.

Vous pouvez également fournir un seul ensemble de données consolidé. Le service d'enrichissement partitionne automatiquement les données en un ensemble de curation et un ensemble d'évaluation.

Exigences concernant le schéma de l'ensemble de données

Les ensembles de données d'évaluation doivent être au format JSONL et stockés dans Cloud Storage. Chaque ligne du fichier doit contenir une question en langage naturel associée à la requête SQL de vérité terrain attendue.

Assurez-vous que votre fichier correspond au schéma de l'ensemble de données d'évaluation prescrit par Gemini Enterprise Agent Platform. Le tableau suivant présente les champs de mise en forme acceptés :

Nom du champ Type Description
display_name STRING Facultatif. Identifiant ou nom de la demande d'évaluation.
evaluation_request.prompt.text STRING La question en langage naturel ou la requête de l'utilisateur.
evaluation_request.golden_response.candidate STRING Identifie la réponse de référence. Variable définie sur golden.
evaluation_request.golden_response.text STRING La requête SQL validée par la vérité terrain qui répond à la question. Le scorer exécute ce code SQL sur les données.

L'extrait de code suivant montre un fichier d'évaluation .jsonl valide :

{"display_name": "revenue-2026", "evaluation_request": {"prompt": {"text": "What is total revenue for customer C100 in 2026?"}, "golden_response": {"candidate": "golden", "text": "SELECT SUM(amount) FROM `project.dataset.orders` WHERE customer_id = 'C100' AND EXTRACT(YEAR FROM order_date) = 2026;"}}}
{"display_name": "monthly-subscribers", "evaluation_request": {"prompt": {"text": "List active subscribers on monthly billing"}, "golden_response": {"candidate": "golden", "text": "SELECT user_id, email FROM `project.dataset.subscriptions` WHERE status = 'ACTIVE' AND plan_type = 'MONTHLY';"}}}

Pour obtenir des instructions détaillées sur la création d'ensembles de données d'évaluation de haute qualité, consultez la documentation de Gemini Enterprise Agent Platform.

Configurer les traces de l'agent pour l'auto-apprentissage

Pour permettre à l'agent d'enrichissement d'analyser automatiquement les interactions des agents Gemini Enterprise en aval (ou des applications Gemini Enterprise Agent Platform personnalisées), vous pouvez éventuellement lui accorder un accès en lecture aux traces d'interaction de votre application.

L'ingestion de ces traces permet à l'agent d'effectuer une exploration de trajectoire. L'agent découvre les points de blocage des agents en aval en raison d'un manque de contexte, regroupe les questions fréquentes des utilisateurs dans des classes de requêtes à fort impact, et organise automatiquement les résumés de table, la sémantique des colonnes et les termes du glossaire d'entreprise nécessaires pour combler ces lacunes.

En fonction de l'architecture de votre entreprise, choisissez l'une des deux méthodes de configuration suivantes :

  • Journalisation directe à l'aide de vues de journaux délimitées : créez une vue de journaux limitée à la télémétrie de l'application pour accorder un accès en lecture selon le principe du moindre privilège. Recommended.
  • BigQuery Agent Analytics : accordez un accès en lecture à un ensemble de données BigQuery exporté si votre organisation achemine de manière native les journaux d'interaction vers un récepteur de journaux BigQuery.

Journalisation directe à l'aide de vues de journaux limitées (recommandé)

Lorsque la journalisation des interactions est activée pour une application, les journaux d'exécution sont diffusés directement dans Logging. Pour respecter le principe du moindre privilège, créez une vue de journaux dédiée limitée à l'application spécifique et accordez au compte de service d'exécution un accès en lecture exclusivement sur cette vue.

  1. Créez une vue de journal délimitée pour isoler les journaux. Cela garantit que le service d'enrichissement ne lit que la télémétrie d'applications configurées spécifiques (par exemple, en filtrant sur resource.type="aiplatform.googleapis.com/Agent"), ce qui empêche tout accès non autorisé à vos journaux Cloud plus larges.

    gcloud CLI

    Pour créer une vue de journaux limitée, utilisez la commande gcloud logging views create :

    Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

    • LOG_VIEW_NAME : nom de votre vue de journaux.
    • YOUR_GEMINI_ENTERPRISE_APP_ID : ID application Gemini Enterprise

    Exécutez la commande suivante :

    Linux, macOS ou Cloud Shell

    gcloud logging views create LOG_VIEW_NAME \
    --location=global \
    --bucket=_Default \
    --log-filter='resource.type="aiplatform.googleapis.com/Agent" AND resource.labels.agent_id="YOUR_GEMINI_ENTERPRISE_APP_ID"'

    Windows (PowerShell)

    gcloud logging views create LOG_VIEW_NAME `
    --location=global `
    --bucket=_Default `
    --log-filter='resource.type="aiplatform.googleapis.com/Agent" AND resource.labels.agent_id="YOUR_GEMINI_ENTERPRISE_APP_ID"'

    Windows (cmd.exe)

    gcloud logging views create LOG_VIEW_NAME ^
    --location=global ^
    --bucket=_Default ^
    --log-filter='resource.type="aiplatform.googleapis.com/Agent" AND resource.labels.agent_id="YOUR_GEMINI_ENTERPRISE_APP_ID"'

    REST

    Avant d'utiliser les données de requête, effectuez les remplacements suivants :

    • LOG_VIEW_NAME : nom de votre vue de journaux
    • TARGET_PROJECT_ID : ID de votre projet Google Cloud
    • YOUR_GEMINI_ENTERPRISE_APP_ID : ID application Gemini Enterprise

    Méthode HTTP et URL : 

    POST https://logging.googleapis.com/v2/projects/TARGET_PROJECT_ID/locations/global/buckets/_Default/views?viewId=LOG_VIEW_NAME

    Corps JSON de la requête :

    {
 "filter": "resource.type=\"aiplatform.googleapis.com/Agent\" AND resource.labels.agent_id=\"YOUR_GEMINI_ENTERPRISE_APP_ID\""
}

    Pour envoyer votre requête, développez l'une des options suivantes :

    Vous devriez recevoir un code d'état indiquant le succès de l'opération (2xx), ainsi qu'une réponse vide.

  2. Après avoir créé la vue de journaux, accordez au compte de service d'exécution un accès en lecture à celle-ci. Cela autorise le job d'enrichissement à extraire la télémétrie d'application dont il a besoin pendant la phase d'auto-apprentissage.

    Pour ajouter une liaison de stratégie IAM à une vue de journaux, utilisez la commande gcloud logging views add-iam-policy-binding :

    Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

    • LOG_VIEW_NAME : nom de votre vue de journaux.
    • SERVICE_ACCOUNT_NAME : nom de votre compte de service.
    • TARGET_PROJECT_ID : ID de votre projet Google Cloud

    Exécutez la commande suivante :

    Linux, macOS ou Cloud Shell

    gcloud logging views add-iam-policy-binding LOG_VIEW_NAME \
    --location=global \
    --bucket=_Default \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/logging.viewAccessor"

    Windows (PowerShell)

    gcloud logging views add-iam-policy-binding LOG_VIEW_NAME `
    --location=global `
    --bucket=_Default `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/logging.viewAccessor"

    Windows (cmd.exe)

    gcloud logging views add-iam-policy-binding LOG_VIEW_NAME ^
    --location=global ^
    --bucket=_Default ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/logging.viewAccessor"

Pour en savoir plus, consultez Configurer des vues de journaux sur un bucket de journaux.

BigQuery Agent Analytics

Si votre organisation diffuse des journaux d'interaction dans BigQuery à l'aide d'un récepteur de journaux Logging ou écrit directement dans les tables d'analyse de l'agent BigQuery, vous pouvez accorder l'accès à l'ensemble de données à la place.

Assurez-vous que les journaux d'interaction sont configurés pour être diffusés dans un ensemble de données BigQuery désigné, et vérifiez que le compte de service d'exécution dispose du rôle Lecteur de données BigQuery (roles/bigquery.dataViewer) sur cet ensemble de données spécifique. Cela permet à l'agent de lire la télémétrie exportée directement depuis BigQuery.

Pour en savoir plus sur l'exportation des journaux, consultez Acheminer les journaux vers des destinations compatibles.

Activer le profilage des données et les insights sur les données

Avant d'exécuter une tâche d'enrichissement, nous vous recommandons d'activer le profilage des données et les insights sur les données d'IA sur vos tables cibles fréquemment utilisées. Le profilage des données fournit des caractéristiques statistiques (valeurs courantes, distributions des données et nombres de valeurs nulles, par exemple), tandis que les insights sur les données génèrent des descriptions de tables de référence et des exemples de requêtes. En fournissant ces signaux, vous aidez l'agent d'enrichissement à générer des propositions de métadonnées plus précises.

Étapes suivantes