Configura los requisitos previos para las tareas de enriquecimiento

Para ejecutar tareas de enriquecimiento en Knowledge Studio, puedes configurar cuentas de servicio administradas por el cliente, proveedores de autenticación de terceros, buckets de Cloud Storage y vistas de Cloud Logging. La configuración de estos componentes de requisitos previos permite que los agentes de enriquecimiento accedan de forma segura a tus fuentes de datos de destino, transfieran indicadores de conocimiento no estructurados y aprendan de las interacciones históricas de los agentes.

En la siguiente tabla, se describen los parámetros de configuración de requisitos previos y cuándo debes configurarlos:

Función de configuración Cuándo configurar
APIs de Google Cloud Obligatorio. Debes habilitar las APIs de Google Cloud subyacentes para ejecutar flujos de trabajo de enriquecimiento. Para obtener más detalles, consulta la sección Antes de comenzar de este documento.
Cuenta de servicio administrada por el cliente Obligatorio. Usas una cuenta de servicio dedicada para restringir el acceso de lectura y escritura en tus conjuntos de datos de destino y de información contextual. Para obtener más detalles, consulta la sección Configura una cuenta de servicio administrada por el cliente de este documento.
Roles de Identity and Access Management (IAM) de los usuarios Obligatorio. Otorgas permisos a los administradores y revisores de flujos de trabajo para que generen y aprueben metadatos. Para obtener más detalles, consulta la sección Otorga los roles de IAM necesarios a los usuarios de este documento.
Proveedores de autenticación de terceros Es opcional. Te conectas a fuentes de conocimiento de terceros (como Microsoft SharePoint, Atlassian Confluence o GitHub). Para obtener más detalles, consulta la sección Configura proveedores de autenticación de terceros de este documento.
Buckets de Cloud Storage Es opcional. Estás transfiriendo contexto empresarial no estructurado (como archivos PDF, Markdown y CSV) y conjuntos de datos de evaluación. Para obtener más información, consulta la sección Prepara buckets de Cloud Storage de este documento.
Conjuntos de datos de evaluación Es opcional. Quieres proporcionar consultas de origen y conjuntos de datos de referencia para hacer un seguimiento activo de la exactitud del agente. Para obtener más detalles, consulta la sección Formatea conjuntos de datos de evaluación de este documento.
Seguimientos de agentes para el autoaprendizaje Es opcional. Quieres que el agente de enriquecimiento analice automáticamente las interacciones de los agentes downstream de las aplicaciones de Gemini Enterprise o las tablas de análisis de agentes de BigQuery. Para obtener más detalles, consulta la sección Configura los seguimientos de agentes para el autoaprendizaje de este documento.
Generación de perfiles y estadísticas de datos (recomendado) Quieres mejorar la calidad del enriquecimiento generando perfiles estadísticos y estadísticas de IA de referencia en las tablas que se usan con frecuencia. Para obtener más información, consulta la sección Habilita la generación de perfiles de datos y las estadísticas de datos de este documento.

Antes de comenzar

  1. Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

  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.

Detalles de las APIs requeridas

Para configurar y ejecutar tareas de enriquecimiento, las APIs habilitadas realizan las siguientes funciones:

Nombre de la API Identificador de servicio Propósito en los flujos de trabajo de enriquecimiento
API de Dataplex dataplex.googleapis.com Es la API del plano de control principal. Administra EnrichmentTask, EnrichmentRun, conjuntos de contexto, ChangeRequests y EnrichmentChatService.
API de BigQuery bigquery.googleapis.com Es necesario para analizar esquemas de tablas, transferir el historial de ejecución de SQL y consultar tablas de seguimiento de análisis de agentes de BigQuery.
API de Cloud Storage storage.googleapis.com Es obligatorio para transferir conjuntos de evaluación y administrar muestras de conjuntos de datos de evaluación.
API de Service Account Credentials de IAM iamcredentials.googleapis.com Es necesario para autenticar de forma segura el agente de ejecución y otorgar credenciales de corta duración (SLC) durante las tareas.

Configura una cuenta de servicio administrada por el cliente

Las tareas de enriquecimiento usan una cuenta de servicio administrada por el cliente para ejecutar operaciones. Usar una cuenta de servicio dedicada te permite restringir el acceso de lectura y escritura en tus conjuntos de datos de destino y conjuntos de información contextual.

  1. Cree la cuenta de servicio.

    Para crear una cuenta de servicio, debes tener el rol de Propietario (roles/owner), Editor (roles/editor) o Administrador de cuentas de servicio (roles/iam.serviceAccountAdmin) en el proyecto.

    Una cuenta de servicio dedicada aísla tus operaciones de enriquecimiento, lo que te permite otorgar solo los permisos de lectura y escritura específicos necesarios para estas tareas sin afectar otras cargas de trabajo.

    Para crear una cuenta de servicio, sigue estos pasos:

    Google Cloud CLI

    Para crear una cuenta de servicio, usa el comando gcloud iam service-accounts create:

    Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

    • SERVICE_ACCOUNT_NAME: Es el nombre de tu cuenta de servicio.

    Ejecuta el siguiente comando:

    Linux, macOS o 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

    Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

    • SERVICE_ACCOUNT_NAME: Es el nombre de tu cuenta de servicio.
    • TARGET_PROJECT_ID: El ID del proyecto de Google Cloud.

    Método HTTP y URL: 

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

    Cuerpo JSON de la solicitud:

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

    Para enviar tu solicitud, expande una de estas opciones:

    Deberías recibir un código de estado exitoso (2xx) y una respuesta vacía.

  2. Otorga los roles de IAM necesarios a nivel de recurso a la cuenta de servicio de ejecución en tus permisos de destino:

    • Editor de contenido de Dataplex (roles/dataplex.contentEditor) en el conjunto de contexto de destino (o Administrador del catálogo de Dataplex (roles/dataplex.catalogAdmin) en el proyecto): Permite que el agente lea las entradas del conjunto de contexto, cree y actualice las entradas de contexto y los vínculos de entrada de reference, y envíe solicitudes de cambio (dataplex.entryGroups.getContextSet, dataplex.entryGroups.requestContextChanges, dataplex.entries.*Context y dataplex.entryLinks.create).
    • Editor del catálogo de Dataplex (roles/dataplex.catalogEditor) y Visualizador del catálogo de Dataplex (roles/dataplex.catalogViewer) en el proyecto (o los recursos del catálogo de destino): Permite que el agente inspeccione los metadatos del catálogo, lea los glosarios empresariales conectados y almacene en etapa intermedia las entradas de trabajo.
    • Visualizador de datos de BigQuery (roles/bigquery.dataViewer) en los conjuntos de datos y las tablas de destino: Permite que el agente enumere tablas y lea esquemas de tablas y tablas de seguimiento de estadísticas de agentes.
    • Visualizador de BigLake (roles/biglake.viewer) en los catálogos, espacios de nombres o tablas de Lakehouse de destino: Es obligatorio cuando se enriquecen los recursos de Lakehouse.
    • (Opcional) Usuario de trabajo de BigQuery (roles/bigquery.jobUser) en el proyecto (bigquery.jobs.create): Es obligatorio en el proyecto que contiene la tabla de análisis de agentes de BigQuery si aprendes de los seguimientos de análisis de agentes, o en el proyecto de tareas si la creación de trabajos de BigQuery se mueve dentro de un perímetro de Controles del servicio de VPC. De forma predeterminada, los trabajos de consulta de BigQuery de la tabla de destino (muestreo, análisis del historial de consultas y verificaciones de validación) se ejecutan como el agente de servicio de Knowledge Catalog en un proyecto administrado por Google.
    • (Opcional) Aprobador de flujos de trabajo de Dataplex (roles/dataplex.workflowApprover): Solo se requiere si habilitas la publicación automática en tu tarea. Permite que el agente apruebe y publique automáticamente sus propias solicitudes de cambio de metadatos.

    Nota: En las siguientes muestras de código, se otorgan estos roles a nivel de proyecto para facilitar la configuración. En el caso de los sistemas de producción, te recomendamos que otorgues estos roles a nivel del recurso en tus conjuntos de datos y de contextos de destino específicos.

    Para otorgar estos roles estándar, sigue estos pasos:

    Para agregar una vinculación de política de IAM a un proyecto, usa el comando gcloud projects add-iam-policy-binding:

    Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

    • SERVICE_ACCOUNT_NAME: Es el nombre de tu cuenta de servicio.
    • TARGET_PROJECT_ID: El ID del proyecto de Google Cloud.

    Ejecuta el siguiente comando:

    Linux, macOS o 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.contentEditor"

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/dataplex.catalogViewer"

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.contentEditor"

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/dataplex.catalogViewer"

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.contentEditor"

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/dataplex.catalogViewer"

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. Otorga a los usuarios permiso para actuar en nombre de la cuenta de servicio asignándoles el rol de usuario de cuenta de servicio (roles/iam.serviceAccountUser):

    Los usuarios que crean las tareas de enriquecimiento en la consola deben tener este permiso para poder especificar y adjuntar esta cuenta de servicio a la tarea.

    Para otorgar a los usuarios el rol de usuario de cuenta de servicio (roles/iam.serviceAccountUser), sigue estos pasos:

    Para agregar una vinculación de política de IAM a una cuenta de servicio, usa el comando gcloud iam service-accounts add-iam-policy-binding:

    Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

    • SERVICE_ACCOUNT_NAME: Es el nombre de tu cuenta de servicio.
    • TARGET_PROJECT_ID: El ID del proyecto de Google Cloud.
    • USER_EMAIL: Es la dirección de correo electrónico del usuario.

    Ejecuta el siguiente comando:

    Linux, macOS o 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. Permite que el agente de servicio interno de Knowledge Catalog actúe en nombre de esta cuenta de servicio otorgándole el rol Creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator):

    Este rol permite que el servicio de Knowledge Catalog subyacente asuma la identidad de esta cuenta de servicio dedicada y sus permisos restringidos cuando ejecuta las operaciones de enriquecimiento en segundo plano en tu nombre.

    Para autorizar al agente a asumir la identidad de la cuenta de servicio, sigue estos pasos:

    Para agregar una vinculación de política de IAM a una cuenta de servicio, usa el comando gcloud iam service-accounts add-iam-policy-binding:

    Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

    • SERVICE_ACCOUNT_NAME: Es el nombre de tu cuenta de servicio.
    • TARGET_PROJECT_ID: El ID del proyecto de Google Cloud.
    • TARGET_PROJECT_NUMBER: el número de tu proyecto de Google Cloud.

    Ejecuta el siguiente comando:

    Linux, macOS o 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"

  5. Permite que el agente de servicio de Knowledge Catalog (service-<var>PROJECT_NUMBER</var>@gcp-sa-dataplex.iam.gserviceaccount.com) ejecute trabajos de consulta de BigQuery de backend (muestreo, análisis del historial de consultas y verificaciones de validación) desde un proyecto administrado por Google:

    • Visualizador de datos de BigQuery (roles/bigquery.dataViewer) en tus conjuntos de datos o proyectos de destino: Permite que el agente de servicio tome muestras de los datos de la tabla y ejecute verificaciones de validación.
    • (Recomendado) Visualizador de recursos de BigQuery (roles/bigquery.resourceViewer) en los proyectos cuyo historial de consultas de BigQuery lee el agente de servicio (bigquery.jobs.listAll, que se debe otorgar a nivel del proyecto, no en conjuntos de datos individuales): Permite que el agente de servicio analice las consultas en SQL históricas para descubrir uniones y filtros comunes. Si no se otorga este rol, el agente omite el análisis del historial de consultas sin que falle la ejecución.

Otorga los roles de IAM necesarios a los usuarios

Para asegurarte de que tu equipo pueda administrar los flujos de trabajo de enriquecimiento y revisar las propuestas generadas por IA, otorga los roles de IAM adecuados a tus usuarios. Para obtener instrucciones sobre cómo otorgar estos roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Los administradores de flujos de trabajo (como los administradores de datos) que crean, configuran y supervisan tareas requieren los siguientes roles:

  • Editor de DataScan de Dataplex (roles/dataplex.dataScanEditor) o Editor de Dataplex (roles/dataplex.editor): Permite que los usuarios creen, modifiquen y activen tareas de enriquecimiento.
  • Usuario de cuenta de servicio (roles/iam.serviceAccountUser) en la cuenta de servicio administrada por el cliente: Es necesario para adjuntar la cuenta de servicio como la identidad de ejecución de la tarea. Para obtener detalles de la configuración, consulta la sección Configura una cuenta de servicio administrada por el cliente de este documento.

Los revisores de cambios (como los propietarios de dominios o los expertos en la materia) que inspeccionan, aprueban y publican propuestas de metadatos generados por IA en el catálogo necesitan los siguientes roles:

  • Editor de contenido de Dataplex (roles/dataplex.contentEditor) (o Usuario de contenido de Dataplex (roles/dataplex.contentUser) para la inspección de solo lectura) en el conjunto de contexto, junto con Editor del catálogo de Dataplex (roles/dataplex.catalogEditor) y Visualizador del catálogo de Dataplex (roles/dataplex.catalogViewer) en el proyecto: Es necesario para abrir solicitudes de cambio, inspeccionar diferencias de propuestas en paralelo y editar descripciones de forma intercalada.
  • Aprobador de flujos de trabajo de Dataplex (roles/dataplex.workflowApprover): Es obligatorio para aprobar y publicar solicitudes de cambio en el conjunto de contexto activo.
  • Visualizador de DataScan de Dataplex (roles/dataplex.dataScanViewer) o Visualizador de Dataplex (roles/dataplex.viewer): Es necesario para revisar las puntuaciones de confianza por propuesta, el diagnóstico de fallas de pruebas y los cuadros de evaluación posteriores.

Configura proveedores de autenticación de terceros

Cuando conectas el agente de enriquecimiento a fuentes de conocimiento de terceros (como Microsoft SharePoint, Atlassian Confluence y Jira, o GitHub), debes configurar un proveedor de autenticación con el servicio de identidad del agente de Google Cloud.

Agent Identity actúa como un administrador de credenciales de seguridad seguro que encripta tus tokens de terceros dentro de tu proyecto, lo que garantiza que los operadores humanos nunca tengan que controlar secretos del cliente sin procesar durante la ejecución de tareas.

Para obtener instrucciones paso a paso sobre cómo generar los tokens necesarios y configurar el proveedor de autenticación para plataformas externas específicas, consulta Configura conectores externos para tareas de enriquecimiento.

Configura los permisos de IAM para los proveedores de autenticación

Para permitir que el agente de enriquecimiento recupere de forma segura tus credenciales del proveedor de autenticación de forma dinámica durante una ejecución activa, debes otorgar el rol Administrador de identidad del agente (roles/agentidentity.admin) al agente de servicio de Knowledge Catalog administrado (service-<var>PROJECT_NUMBER</var>@gcp-sa-dataplex.iam.gserviceaccount.com). Puedes otorgar este rol a nivel del recurso del proveedor de autenticación o a nivel del proyecto.

Además, el usuario humano que adjunta el proveedor de autenticación a la tarea en la consola deGoogle Cloud debe tener el permiso agentidentity.authProviders.get (incluido en Visualizador de identidades de agentes (roles/agentidentity.viewer)) en el proveedor de autenticación.

Prepara buckets de Cloud Storage

Cloud Storage funciona como la capa principal de etapa de pruebas basada en archivos, transferencia de contexto y exportación de artefactos para los flujos de trabajo de enriquecimiento de conocimiento.

Puedes configurar el agente para que transfiera archivos de uno o más buckets de entrada, rutas de acceso de carpetas o archivos individuales para fundamentar su razonamiento en el conocimiento del dominio de tu empresa. Entre los tipos de contexto admitidos, se incluyen los siguientes:

  • Documentación de dominio y diccionarios de datos: Archivos Markdown, de texto sin formato, PDF, HTML o CSV que contienen definiciones de tablas, glosarios empresariales, procedimientos operativos estándar (SOP), arquitecturas de canalizaciones de datos o lineamientos para asignar nombres a las columnas. La configuración de Indicadores de conocimiento admite buckets completos, rutas de carpetas (como bucket-name/folder/) o rutas de archivos individuales. Te recomendamos que organices estos documentos en un bucket o una carpeta de Cloud Storage dedicados, separados de tus conjuntos de datos de evaluación y archivos no relacionados.

  • Conjuntos de datos de evaluación: Son archivos JSONL que almacenan consultas de origen y conjuntos de consultas de validación retenidos. Para obtener más información, consulta la sección Formatea los conjuntos de datos de evaluación de este documento.

  • Secuencias de comandos de SQL y transformación de referencia: Secuencias de comandos de SQL guardadas, definiciones de modelos de dbt o lógica de transformación de ETL que proporcionan indicadores contextuales sobre los patrones de unión de tablas y los cálculos empresariales.

Cuando configuras un bucket de salida, el agente de enriquecimiento también puede exportar paquetes estructurados y ejecutar artefactos en ese bucket. Entre los artefactos de salida compatibles, se incluyen los siguientes:

  • Informes de evaluación detallados: Cuadros de evaluación integrales que muestran las diferencias de exactitud por consulta, el diagnóstico de fallas de las pruebas y las métricas de distribución de confianza.

Para asegurarte de que el agente de enriquecimiento pueda trabajar fuera del bucket, asegúrate de que tu cuenta de servicio de ejecución tenga los permisos necesarios:

  • Otorga el rol de visualizador de objetos de Storage (roles/storage.objectViewer) en los buckets de entrada para que el agente pueda leer los documentos en etapa de pruebas y los archivos de configuración.
  • (Opcional) Otorga el rol de creador de objetos de almacenamiento (roles/storage.objectCreator) en el bucket de salida si quieres que el agente guarde los artefactos de ejecución y los registros de validación.

Para otorgar a la cuenta de servicio acceso a los buckets de Cloud Storage, sigue estos pasos:

Para agregar una vinculación de política de IAM a un bucket de almacenamiento, usa el comando gcloud storage buckets add-iam-policy-binding:

Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

  • CUSTOMER_BUCKET: Es el nombre de tu bucket de Cloud Storage.
  • SERVICE_ACCOUNT_NAME: Es el nombre de tu cuenta de servicio.
  • TARGET_PROJECT_ID: El ID del proyecto de Google Cloud.

Ejecuta el siguiente comando:

Linux, macOS o 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"

Formatea conjuntos de datos de evaluación

Los flujos de trabajo de enriquecimiento pueden extraer información automáticamente sin ejemplos. Sin embargo, proporcionar conjuntos de datos de evaluación permite que el agente se pruebe a sí mismo y mejore su exactitud.

Puedes proporcionar dos tipos de conjuntos de datos:

  • Conjunto de selección: Es una lista de preguntas de usuario de ejemplo y las consultas en SQL esperadas. El agente usa esta lista para practicar y escribir mejores resúmenes de tablas.

  • Conjunto de evaluación: Es una lista independiente de preguntas que se usa para calificar el rendimiento del agente. Si el agente tiene un rendimiento deficiente, este conjunto de evaluación evita que se publiquen actualizaciones deficientes en tu catálogo.

Como alternativa, puedes proporcionar un único conjunto de datos consolidado. El servicio de enriquecimiento divide automáticamente los datos en un conjunto de selección y un conjunto de evaluación.

Requisitos del esquema del conjunto de datos

Los conjuntos de datos de evaluación deben tener el formato de archivos JSONL y almacenarse en Cloud Storage. Cada línea del archivo debe contener una pregunta en lenguaje natural vinculada con la consulta en SQL de verdad fundamental esperada. En la siguiente tabla, se muestran los campos de formato aceptados:

Nombre del campo Tipo Descripción
display_name STRING Es opcional. Es un identificador o nombre para la solicitud de evaluación.
evaluation_request.prompt.text STRING Es la pregunta en lenguaje natural o la instrucción del usuario.
evaluation_request.golden_response.candidate STRING Identifica la respuesta de referencia. Se define en golden.
evaluation_request.golden_response.text STRING Es la consulta en SQL validada y de verdad fundamental que responde la pregunta. El calificador automático compara el SQL del agente con esta consulta.

Cómo se califican los resultados de la evaluación: Un evaluador automático basado en Gemini verifica si el SQL final del agente es semánticamente equivalente al SQL de verdad fundamental, lo que significa que devuelve la misma respuesta. No se penalizan las diferencias de formato ni de alias. Cada pregunta se aprueba o se reprueba, y la puntuación de calidad es la tasa de aprobación. La verdad fundamental debe ser una consulta en SQL. No se admiten las métricas personalizadas.

En el siguiente fragmento, se muestra un archivo de evaluación .jsonl válido:

{"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';"}}}

Configura los seguimientos de agentes para el autoaprendizaje

Para permitir que el agente de enriquecimiento analice automáticamente las interacciones del agente de Gemini Enterprise o las tablas de análisis de agentes de BigQuery en sentido descendente, puedes proporcionarle acceso de lectura a los seguimientos de interacción de tu aplicación.

La transferencia de estos seguimientos permite que el agente realice la minería de trayectorias. El agente descubre dónde tuvieron dificultades los agentes downstream debido a la falta de contexto, agrupa las preguntas frecuentes de los usuarios en clases de consultas de alto impacto y organiza automáticamente los resúmenes de tablas, la semántica de las columnas y los términos del glosario empresarial exactos que se necesitan para resolver esas brechas.

Según la arquitectura de tu empresa, elige uno de los siguientes dos métodos de configuración:

  • Registro directo con vistas de registro con alcance (recomendado): Crea una vista de registro restringida solo a la telemetría de la aplicación para otorgar acceso de lectura con privilegios mínimos. Para obtener instrucciones, consulta la sección Registro directo con vistas de registro con alcance de este documento.
  • Análisis de agentes de BigQuery: Otorga acceso de lectura a un conjunto de datos de BigQuery exportado si tu organización enruta de forma nativa los registros de interacción a un receptor de registros de BigQuery. Para obtener instrucciones, consulta la sección Análisis de agentes de BigQuery de este documento.

Registro directo con vistas de registro con alcance (recomendado)

Cuando se habilita el registro de interacciones para una aplicación, los registros de ejecución se transmiten directamente a Logging. Puedes crear una vista de registro dedicada restringida a los registros de auditoría de uso de tu aplicación de Gemini Enterprise y otorgar acceso a esa vista a la cuenta de servicio de ejecución. Debido a que el servicio de enriquecimiento emite lecturas de registros con alcance de proyecto (projects/<var>TARGET_PROJECT_ID</var>), un otorgamiento solo a nivel de vista no es suficiente: la cuenta de servicio de ejecución también debe tener los permisos logging.logEntries.list y logging.views.access en el proyecto propietario de la aplicación de Gemini Enterprise. Para obtener instrucciones sobre cómo activar la instrumentación de seguimiento y el registro de instrucciones y respuestas para tu aplicación de Gemini Enterprise, consulta Administra la configuración de observabilidad.

  1. Crea una vista de registro con permiso para aislar los registros. Una vista de registro con alcance garantiza que la vista solo exponga la telemetría de inferencia y auditoría de uso de tus aplicaciones de Gemini Enterprise (filtrando por logName="projects/<var>TARGET_PROJECT_ID</var>/logs/discoveryengine.googleapis.com%2Fgemini_enterprise_user_activity" OR logName=~"projects/<var>TARGET_PROJECT_ID</var>/logs/discoveryengine.googleapis.com%2Fgen_ai.*"). Para obtener más información, consulta Accede a los registros de auditoría de uso de Gemini Enterprise con Cloud Logging.

    gcloud CLI

    Para crear una vista de registro con alcance, usa el comando gcloud logging views create:

    Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

    • LOG_VIEW_NAME: el nombre de tu vista de registro
    • TARGET_PROJECT_ID: Es el ID del proyecto de Google Cloud que posee tu aplicación de Gemini Enterprise.

    Ejecuta el siguiente comando:

    Linux, macOS o Cloud Shell

    gcloud logging views create LOG_VIEW_NAME \
    --project=TARGET_PROJECT_ID \
    --location=global \
    --bucket=_Default \
    --log-filter='logName="projects/TARGET_PROJECT_ID/logs/discoveryengine.googleapis.com%2Fgemini_enterprise_user_activity" OR logName=~"projects/TARGET_PROJECT_ID/logs/discoveryengine.googleapis.com%2Fgen_ai.*"'

    Windows (PowerShell)

    gcloud logging views create LOG_VIEW_NAME `
    --project=TARGET_PROJECT_ID `
    --location=global `
    --bucket=_Default `
    --log-filter='logName="projects/TARGET_PROJECT_ID/logs/discoveryengine.googleapis.com%2Fgemini_enterprise_user_activity" OR logName=~"projects/TARGET_PROJECT_ID/logs/discoveryengine.googleapis.com%2Fgen_ai.*"'

    Windows (cmd.exe)

    gcloud logging views create LOG_VIEW_NAME ^
    --project=TARGET_PROJECT_ID ^
    --location=global ^
    --bucket=_Default ^
    --log-filter='logName="projects/TARGET_PROJECT_ID/logs/discoveryengine.googleapis.com%2Fgemini_enterprise_user_activity" OR logName=~"projects/TARGET_PROJECT_ID/logs/discoveryengine.googleapis.com%2Fgen_ai.*"'

    REST

    Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

    • LOG_VIEW_NAME: el nombre de tu vista de registro
    • TARGET_PROJECT_ID: Es el ID del proyecto de Google Cloud que posee tu aplicación de Gemini Enterprise.

    Método HTTP y URL: 

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

    Cuerpo JSON de la solicitud:

    {
 "filter": "logName=\"projects/TARGET_PROJECT_ID/logs/discoveryengine.googleapis.com%2Fgemini_enterprise_user_activity\" OR logName=~\"projects/TARGET_PROJECT_ID/logs/discoveryengine.googleapis.com%2Fgen_ai.*\""
}

    Para enviar tu solicitud, expande una de estas opciones:

    Deberías recibir un código de estado exitoso (2xx) y una respuesta vacía.

  2. Después de crear la vista de registro, otorga a la cuenta de servicio de ejecución el rol Descriptor de acceso de vistas de registros (roles/logging.viewAccessor) en la vista y asegúrate de que la cuenta de servicio también tenga el permiso logging.logEntries.list en el proyecto que posee la aplicación de Gemini Enterprise.

    Para agregar una vinculación de política de IAM a una vista de registro, usa el comando gcloud logging views add-iam-policy-binding:

    Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

    • LOG_VIEW_NAME: el nombre de tu vista de registro
    • SERVICE_ACCOUNT_NAME: Es el nombre de tu cuenta de servicio.
    • TARGET_PROJECT_ID: El ID del proyecto de Google Cloud.

    Ejecuta el siguiente comando:

    Linux, macOS o 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"

Para obtener más información, consulta Configura vistas de registros en un bucket de registros.

Análisis de agentes de BigQuery

Si tu organización transmite registros de interacción a BigQuery con un receptor de registros de Logging o escribe directamente en las tablas de análisis de agentes de BigQuery, puedes otorgar acceso al conjunto de datos.

Asegúrate de que los registros de interacción estén configurados para transmitirse a un conjunto de datos de BigQuery designado y verifica que a la cuenta de servicio de ejecución se le otorgue el rol de Visualizador de datos de BigQuery (roles/bigquery.dataViewer) en la tabla de estadísticas del agente (o su conjunto de datos) y el rol de Usuario de trabajos de BigQuery (roles/bigquery.jobUser) en el proyecto que contiene esa tabla. Estos roles permiten que el agente ejecute trabajos de consulta y lea la telemetría exportada directamente desde BigQuery.

Para obtener más información sobre la exportación de registros, consulta Enruta registros a destinos compatibles.

Habilita la generación de perfiles de datos y las estadísticas de datos

Antes de ejecutar una tarea de enriquecimiento, te recomendamos que habilites la generación de perfiles de datos y las estadísticas de datos de IA en las tablas de destino que usas con frecuencia. La generación de perfiles de datos proporciona características estadísticas, como valores comunes, distribuciones de datos y recuentos de valores nulos, y las estadísticas de datos generan descripciones de tablas de referencia y consultas de muestra. Proporcionar estos indicadores ayuda al agente de enriquecimiento a generar propuestas de metadatos más precisas.

¿Qué sigue?