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 está diseñada 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 código SQL generado y solo permite consultas de tipo SELECT.
  • Looker: La API interactúa con Looker a través de métodos como run_inline_query, que se restringen a operaciones de lectura, como selecciones, filtros y límites. Estos métodos no admiten operaciones de DDL o DML, ni incluyen operaciones de eliminación o descarte.
  • Data Studio (para archivos CSV y Hojas de cálculo de Google): Data Studio usa un formato estructurado para definir y recuperar datos para las visualizaciones y los informes. Las búsquedas que se ejecutan con este método son de solo lectura y no admiten 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 todas estas fuentes de datos. Para obtener más información sobre la seguridad de la API de Conversational Analytics, consulta la entrada de blog Chatea con confianza: Desglosamos la seguridad en Conversational Analytics de Looker.

¿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 Google Cloud IAM. El usuario o la cuenta de servicio que intenta usar la API no tiene los permisos necesarios en el proyecto Google Cloud .
    • Solución de problemas:
      • El propietario del proyecto Google Cloud debe asegurarse de que el usuario o la cuenta de servicio tengan los roles de IAM correctos asignados en el proyecto Google Cloud . 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 de Usuario 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 de transmisión :chat, es posible que la API devuelva 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 agotado para una consulta de larga duración o una denegación repentina de permisos), finaliza la transmisión y, luego, incluye el código de error específico en los tráilers 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 Google Cloud bibliotecas cliente (SDKs) oficiales, como el SDK de Python. Estos SDK basados en gRPC analizan los tráilers de HTTP/2 y devuelven 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 desees realizar:

  1. Google Cloud Roles de IAM:

    • Necesitas roles de IAM suficientes en tu proyecto de Google Cloud para interactuar con la API degeminidataanalytics.googleapis.com. Los roles de IAM configurados de forma incorrecta suelen generar errores de PERMISSION_DENIED.
    • Los roles específicos necesarios pueden depender de las acciones, pero es posible que se necesiten roles generales, como el de editor de proyectos, 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 permisos y roles 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 asegurarte de que la autenticación y la habilitación de IAM sean correctas:

  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 realizar consultas en ella. 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 proyecto Google Cloud .

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 nuevo extremo oficial 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 del data_agent_id como un nombre completamente calificado (FQN), que adopta 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 se realizan operaciones get, update o delete, el data_agent.name completo se considera 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 generará un ID único automáticamente.
  • 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 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 sobrescribirá con {parent}/dataAgents/{data_agent_id}.

Para conversaciones:

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

{conversation_id} es el ID del recurso y 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 updateMask?

En el método patch 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 de un agente de datos?

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

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

En las siguientes muestras 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?

  • Dentro de 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 administrar el historial de conversaciones, lo que permite a los usuarios chatear en varias sesiones. También admite agentes con estado y 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 determinísticas, por lo que la respuesta en lenguaje natural que proporciona el agente puede variar incluso para una pregunta formulada de forma idéntica.
  • 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 en SQL o de Looker) sea determinística. 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 de los agentes de datos es proporcionarles 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.
  • En el caso de 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 permite que los agentes citen fuentes en sus respuestas. Para obtener más información, consulta Cómo definir 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 orientaciones definidas por el usuario que pueden moldear el comportamiento de un agente de datos. Esta orientación incluye lógica específica de la empresa, formato de respuesta o presentación de datos.
    • Puedes proporcionar consultas verificadas (también denominadas consultas de referencia según la fuente de datos), que son preguntas de lenguaje natural de muestra que se vinculan con sus consultas correctas en SQL o Looker.
    • En el caso de 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 Cómo guiar el comportamiento del agente con contexto creado.

Consulta la página Cómo hacer 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 devuelva código de Python. El código de Python que devuelven 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 elude 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 estos lineamientos:

  • 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 un entorno de pruebas seguro y aislado, como un notebook de Colaboratory, un contenedor efímero de Docker o una máquina virtual, que no tenga acceso a credenciales sensibles, redes internas ni 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 endpoints de la API de geminidataanalytics.googleapis.com debe poder enviar mensajes del usuario desde la aplicación al agente y mostrar las respuestas.

Para compilar una integración, consulta el repositorio de guías de inicio rápido de Conversational Analytics para ver 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á disponible de forma 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 por el uso de esos servicios. En el caso de 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 y los gráficos con BigQuery Graph)
  • Exploraciones de Looker
  • Data Studio
  • AlloyDB para PostgreSQL
  • GoogleSQL para Spanner
  • Cloud SQL para MySQL 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 proyectos de Google Cloud ?

No hay restricciones en la Google Cloud selección de proyectos ni en la ubicación. Puedes crear agentes de datos para consultar las fuentes de datos compatibles que pertenecen 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 endpoint 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 distintos del inglés?

El único idioma admitido oficialmente para la API de Conversational Analytics es el inglés. Si bien los modelos subyacentes de Gemini admiten muchos idiomas y algunos usuarios informaron haber tenido éxito de forma anecdótica con búsquedas en otros idiomas, la API de Conversational Analytics no admite oficialmente idiomas distintos del inglés.