Preguntas frecuentes sobre la API de Conversational Analytics

En esta página, se responden preguntas frecuentes sobre la API de Conversational Analytics.

¿La API de Conversational Analytics puede alterar o borrar mis datos?

La API de Conversational Analytics se diseñó con medidas de protección para evitar que se alteren o borren tus datos.

A continuación, se explica cómo se maneja la seguridad de los datos para diferentes fuentes de datos:

  • BigQuery: La API bloquea las instrucciones del lenguaje de definición de datos (DDL) y del lenguaje de manipulación de datos (DML). Específicamente, el sistema realiza una ejecución de prueba en el SQL generado y solo permite consultas de tipo SELECT.
  • Looker: La API interactúa con Looker mediante métodos como run_inline_query, que están restringidos a operaciones de lectura, como selecciones, filtros y límites. Estos métodos no admiten operaciones de DDL ni DML, y no incluyen operaciones de eliminación ni de eliminación.
  • Data Studio (para archivos CSV y Hojas de cálculo de Google): Data Studio usa un formato estructurado para definir y recuperar datos para visualizaciones y, también, informes. Cualquier consulta que se ejecute con este método es de solo lectura y no admite mutaciones de datos.
  • Bases de datos: El sistema solo permite consultas de tipo SELECT. Para evitar la alteración o eliminación de datos, asegúrate de que la cuenta de servicio o el usuario que interactúa con la API de Conversational Analytics tenga permisos de solo lectura para tu base de datos.

La API de Conversational Analytics está diseñada para ser de solo lectura en estas fuentes de datos. Para obtener más información sobre la seguridad de la API de Conversational Analytics, consulta la entrada de blog Chat with confidence: Unpacking security in Looker Conversational Analytics.

¿Cómo manejo los errores de autenticación y permisos?

Estos son algunos errores comunes de autenticación y permisos que puedes encontrar cuando usas la API de Conversational Analytics:

  1. Error: PERMISSION_DENIED o 403 Write access to project ... was denied

    • Causa probable: Este mensaje suele indicar problemas con los roles de IAM. Google Cloud El usuario o la cuenta de servicio que intenta usar la API no tiene los permisos necesarios en el Google Cloud proyecto.
    • Solución de problemas:
      • El Google Cloud propietario del proyecto debe asegurarse de que el usuario o la cuenta de servicio tengan los roles de IAM correctos asignados en el Google Cloud proyecto. Es posible que se necesiten roles como Project Editor para ciertas operaciones, como habilitar la API o probar sus funciones.
      • Si encuentras un error 403 como Write access to project 'us-gcp-project-name' was denied cuando cambias de región, verifica la configuración de IAM de tu proyecto.

  2. Error: 500 Internal Server Error cuando un usuario de Looker con el rol User intenta chatear con un agente de datos.

¿Por qué veo errores 503 o 500 cuando transmito respuestas?

Si usas un cliente HTTP o REST básico (como la biblioteca requests de Python) para llamar al extremo :chat de transmisión, es posible que la API muestre un mensaje de error genérico, como 503 Connection reset by peer o 500 Internal error.

Estos errores genéricos se producen porque la API de transmisión envía un encabezado HTTP 200 OK en cuanto se abre la transmisión. Si el agente de datos encuentra un error fatal durante la transmisión (como un tiempo de espera para una consulta de larga duración o una denegación repentina de permisos), finaliza la transmisión y, además, incluye el código de error específico en los trailers de HTTP/2. Los clientes HTTP o REST estándar no pueden analizar estos encabezados finales y, en cambio, interpretan la finalización abrupta como una falla de socket.

Para controlar los errores que se producen durante una transmisión, te recomendamos que uses las bibliotecas cliente oficiales (SDKs) Google Cloud , como el SDK de Python. Estos SDKs basados en gRPC analizan los trailers de HTTP/2 y muestran el código de error específico, como DEADLINE_EXCEEDED o PERMISSION_DENIED, en lugar de un error de red genérico.

¿Cuáles son los requisitos de Looker para usar la API de Conversational Analytics?

Para usar la API de Conversational Analytics, necesitas los permisos adecuados tanto en Google Cloud IAM como en Looker, según la fuente de datos y las acciones que deseas realizar:

  1. Google Cloud Roles de IAM:

    • Necesitas suficientes roles de IAM en tu Google Cloud proyecto para interactuar con la geminidataanalytics.googleapis.com API. Los roles de IAM mal configurados suelen generar errores PERMISSION_DENIED.
    • Los roles específicos necesarios pueden depender de las acciones, pero es posible que se necesiten roles generales como Project Editor para ciertas operaciones.

  2. Permisos y roles de Looker:

    • Permisos a nivel del modelo: Para usar Conversational Analytics y la API de Conversational Analytics, se debe asignar a un usuario de Looker un rol de Looker que contenga el permiso gemini_in_looker para los modelos con los que interactúa.

Para obtener más información sobre los permisos y roles necesarios para usar la API de Conversational Analytics, consulta la página de documentación Otorga roles y permisos de IAM de la API de Conversational Analytics.

Además, tu instancia de Looker debe cumplir con requisitos específicos:

Para usar la API de Conversational Analytics con Data Studio Pro, tu suscripción a Pro debe estar fuera de un perímetro de VPC-SC.

¿Cuáles son los requisitos de la base de datos para usar la API de Conversational Analytics?

Para usar la API de Conversational Analytics con bases de datos como AlloyDB para PostgreSQL, GoogleSQL para Spanner, Cloud SQL para MySQL y Cloud SQL para PostgreSQL, debes garantizar la autenticación y la habilitación adecuadas de IAM:

  1. Google Cloud Roles de IAM:

    • La cuenta de servicio o el usuario deben tener los roles de IAM necesarios para conectarse a la base de datos específica y consultarla. Por lo general, esto implica roles con acceso de lectura a la base de datos.

  2. Habilitación de la API:

    • Asegúrate de que la API de IA de Cloud Companion esté habilitada en tu Google Cloud proyecto.

Para obtener más información sobre cómo habilitar la autenticación de IAM, consulta la documentación de cada base de datos:

¿Cómo migro de la API de Data QnA a la API de Conversational Analytics?

Si usaste la versión experimental anterior de la API de Data QnA (dataqna.googleapis.com), consulta la guía de migración para migrar al extremo oficial nuevo de la API de Conversational Analytics (geminidataanalytics.googleapis.com).

¿Cuál es la diferencia entre el nombre y el ID de un agente de datos?

El ID del agente de datos, que se define como el valor de data_agent_id, es el identificador único del agente de datos. El nombre del agente de datos, data_agent.name, se deriva automáticamente de data_agent_id como un nombre completamente calificado (FQN), que toma la forma projects/<project>/locations/<location>/dataAgents/<data_agent_id>.

Cuando creas un agente de datos, se ignora cualquier valor que hayas ingresado para data_agent.name. Cuando realizas operaciones get, update o delete, el data_agent.name completo se trata como el identificador único del agente de datos.

Cuando se usa la API de Conversational Analytics para crear agentes de datos, se aplican las siguientes situaciones:

  • Si no defines data_agent_id, se genera un ID único de forma automática.
  • Si defines data_agent_id como, por ejemplo, TestID, cualquier valor que hayas ingresado para data_agent.name se reemplazará por projects/<project>/locations/<location>/dataAgents/TestID.
  • Si defines data_agent_id con un FQN, recibirás un error de "nombre con formato incorrecto".

¿Cuál es el formato aceptado para un ID en Create Agent o Create Conversation?

Para los agentes de datos:

projects/{project}/locations/{location}/dataAgents/{data_agent_id}

{data_agent} es el ID del recurso. Debe tener 63 caracteres o menos y debe coincidir con el formato que se describe en https://google.aip.dev/122#resource-id-segments.

Ejemplo: projects/1234567890/locations/us-central1/dataAgents/my-agent

Te recomendamos que omitas la configuración de este campo durante la creación del agente, ya que se inferirá automáticamente y se reemplazará por {parent}/dataAgents/{data_agent_id}.

Para las conversaciones:

projects/{project}/locations/{location}/conversations/{conversation_id}

{conversation_id} es el ID del recurso, debe tener 63 caracteres o menos y debe coincidir con el formato que se describe en https://google.aip.dev/122#resource-id-segments.

Ejemplo: projects/1234567890/locations/us-central1/conversations/my-conversation.

Te recomendamos que omitas la configuración de este campo durante la creación de la conversación, ya que Conversational Analytics lo identificará automáticamente y, luego, lo reemplazará por {parent}/conversations/{conversation_id}.

¿Cómo uso la máscara de actualización?

En el flujo de actualización del agente de datos, el parámetro updateMask toma una cadena de formato FieldMask que especifica qué campos dataAgent se reemplazarán en el recurso dataAgent con la actualización. El parámetro updateMask es un campo obligatorio y se valida de la siguiente manera:

  • Si updateMask está vacío, se arrojará un BadRequestException y no se actualizará ningún campo.
  • Si todos los campos de updateMask son campos dataAgent válidos, solo se actualizarán esos campos.
  • Si se proporciona una combinación de campos válidos y no válidos, se ignorarán los campos no válidos y solo se actualizarán los válidos.

¿Cómo uso getIAMPolicy y setIAMPolicy para establecer la política de IAM para un agente de datos?

Puedes usar el getIamPolicy método y el setIamPolicy método para asignar roles de IAM a los usuarios de un agente específico.

En los siguientes ejemplos de código, se muestra cómo recuperar la política de IAM para un agente de datos:

En los siguientes ejemplos de código, se muestra cómo asignar IAM a un agente de datos:

¿Cuáles son las capacidades de memoria del agente de datos de la API de Conversational Analytics?

  • En una sola sesión: La API de Conversational Analytics admite conversaciones de varios turnos, lo que significa que puede hacer referencia a partes anteriores de la conversación actual.
  • En varias sesiones: La API de Conversational Analytics incluye funciones para el historial de conversaciones administrado, lo que permite a los usuarios chatear en varias sesiones. También admite agentes con estado con conversaciones de varios turnos administradas por Google.
  • Memoria a largo plazo: Los agentes de datos de la API de Conversational Analytics no admiten capacidades explícitas de memoria a largo plazo.

¿Un agente de datos de la API de Conversational Analytics me dará la misma respuesta cada vez que haga la misma pregunta?

  • Las respuestas en lenguaje natural del agente de datos de la API de Conversational Analytics no son deterministas, por lo que la respuesta en lenguaje natural que proporciona el agente puede variar incluso para una pregunta con la misma redacción.
  • Respuestas a consultas de datos: Sin embargo, para una pregunta específica de búsqueda de datos, se espera que la consulta subyacente generada (consulta de SQL o Looker) sea determinista. Los datos recuperados deben ser los mismos, suponiendo que los datos subyacentes no hayan cambiado.

¿Cómo puedo mejorar la precisión de las respuestas de un agente de datos de la API de Conversational Analytics?

Una forma de mejorar la precisión de las respuestas del agente de datos es proporcionarle información contextual sólida. Puedes agregar contexto de las siguientes maneras:

  • En la capa semántica de Looker, puedes proporcionar contexto dentro de las definiciones de LookML. Para obtener más información y ejemplos, consulta la página de documentación Guía el comportamiento del agente con contexto creado en Looker.
  • Para las fuentes de datos de BigQuery, puedes proporcionar contexto creado a través de campos de contexto estructurados, como descripciones a nivel de la tabla y la columna, sinónimos, etiquetas y consultas de ejemplo, y a través de instrucciones del sistema. Proporcionar este contexto también ayuda a mejorar la precisión de las respuestas y puede permitir que los agentes citen fuentes en sus respuestas. Para obtener más información, consulta Define el contexto del agente de datos para las fuentes de datos de BigQuery.
  • En las fuentes de datos de AlloyDB para PostgreSQL, Cloud SQL para MySQL, Cloud SQL para PostgreSQL y Spanner, puedes proporcionar contexto agregando descripciones de tablas, columnas y esquemas, y restricciones como guía para los datos y cómo interpretarlos.

  • Cuando creas un agente de datos, puedes proporcionar instrucciones del sistema, consultas verificadas y contexto avanzado:

    • Instrucciones del sistema, que son instrucciones definidas por el usuario que pueden dar forma al comportamiento de un agente de datos. Esta guía incluye lógica específica de la empresa, formato de respuesta o presentación de datos.
    • Puedes proporcionar consultas verificadas (también denominadas consultas doradas según la fuente de datos), que son preguntas de ejemplo en lenguaje natural que se combinan con sus consultas correctas de SQL o Looker.
    • Para las fuentes de datos de AlloyDB, Cloud SQL para MySQL, Cloud SQL para PostgreSQL y Spanner, puedes proporcionar contexto avanzado, lo que te ayuda a optimizar la comprensión y la precisión de los datos de tus agentes.

    Para obtener más información, consulta Guía el comportamiento del agente con contexto creado.

Consulta la página Haz preguntas eficaces para obtener orientación sobre cómo hacer preguntas para obtener respuestas más eficaces y precisas.

¿Cómo puedo inspeccionar y controlar de forma segura el código de Python generado por el agente?

Si habilitaste el análisis avanzado con Python, es posible que tu agente de datos muestre código de Python. El código de Python que muestran los agentes de datos está diseñado para ejecutarse en una zona de pruebas segura administrada por Google. Ejecutar este código en un entorno local o en otro entorno no verificado omite las protecciones de seguridad de la zona de pruebas y puede exponer tu sistema a riesgos de seguridad, como la ejecución de código malicioso.

Para inspeccionar y controlar de forma segura el código de Python generado por el agente, sigue estas instrucciones:

  • Inspecciona manualmente el código generado antes de ejecutarlo. Busca patrones sospechosos, como solicitudes de red inesperadas (por ejemplo, socket, requests o urllib), comandos a nivel del sistema (por ejemplo, os.system o subprocess) o literales y variables de cadena muy ofuscados.
  • Nunca ejecutes código no verificado directamente en una máquina local o en un entorno de producción. Usa una zona de pruebas segura y aislada, como un notebook de Colaboratory, un contenedor de Docker efímero o una máquina virtual, que no tenga acceso a credenciales sensibles, redes internas o sistemas de archivos locales.
  • Cuando sea posible, antes de ejecutar el código, debes ejecutar herramientas de análisis estático o linters en el código para marcar operaciones potencialmente inseguras o patrones maliciosos conocidos.

¿Puedo integrar la API de Conversational Analytics con aplicaciones de terceros?

La integración de la API de Conversational Analytics con aplicaciones de terceros permite a los usuarios interactuar con sus datos directamente en las herramientas que usan a diario.

Cualquier aplicación de terceros que interactúe con los extremos de la API de geminidataanalytics.googleapis.com debe poder enviar mensajes de usuario desde la aplicación al agente y mostrar las respuestas.

Para compilar una integración, consulta el repositorio de inicios rápidos de Conversational Analytics para obtener ejemplos o bibliotecas. También puedes visitar los foros para desarrolladores de Google para buscar ejemplos de otros usuarios.

¿Cuánto cuesta la API de Conversational Analytics?

La API de Conversational Analytics está en disponibilidad general (DG). Para obtener más información sobre los precios, consulta la guía de precios.

Además, las consultas que los agentes de datos ejecutan en fuentes de datos como BigQuery pueden generar costos de esos servicios. En BigQuery, puedes administrar los costos configurando cuotas o limitando los bytes facturados por consulta con el parámetro bigquery_max_billed_bytes.

¿Qué fuentes de datos admite la API de Conversational Analytics?

La API de Conversational Analytics admite las siguientes fuentes de datos:

  • BigQuery (incluidas las tablas o un gráfico)
  • Exploraciones de Looker
  • Data Studio
  • AlloyDB para PostgreSQL
  • GoogleSQL para Spanner
  • Cloud SQL y Cloud SQL para PostgreSQL

También puedes conectarte a fuentes como SAP y Salesforce a través de BigQuery, y a archivos CSV y Hojas de cálculo de Google a través de Data Studio.

¿Cuáles son las limitaciones conocidas de la API de Conversational Analytics?

Para obtener más información sobre las limitaciones conocidas de la API de Conversational Analytics, consulta la página de documentación Limitaciones conocidas de la API de Conversational Analytics.

¿Qué cuotas debo tener en cuenta para los Google Cloud proyectos?

No hay restricciones en la selección o ubicación del Google Cloud proyecto. Puedes crear agentes de datos para consultar fuentes de datos compatibles que pertenezcan a cualquier proyecto o región.

¿La API de Conversational Analytics admite la residencia de datos?

Sí, la API de Conversational Analytics admite la residencia de datos. Para controlar dónde se procesan y almacenan tus datos, especifica un extremo de servicio regional o multirregional cuando realices solicitudes a la API. Para obtener información detallada sobre la compatibilidad con ubicaciones específicas y los detalles de configuración, consulta Residencia de datos.

¿La API de Conversational Analytics admite idiomas que no sean inglés?

El único idioma admitido oficialmente para la API de Conversational Analytics es el inglés. Aunque los modelos subyacentes de Gemini admiten muchos idiomas y algunos usuarios informaron sobre el éxito anecdótico con consultas que no están en inglés, la API de Conversational Analytics no admite oficialmente idiomas que no sean inglés.