Compartir a través de

Uso de Genie Conversation API para integrar Genie en las aplicaciones

Importante

Esta característica está en versión preliminar pública.

En esta página se explica cómo usar Genie Conversation API para habilitar las funcionalidades de Genie en su propio bot de chat, agente o aplicación.

Información general

Genie Conversation API permite a los desarrolladores integrar consultas de datos de lenguaje natural en aplicaciones, bots de chat y marcos de agente de IA. Admite conversaciones con estado, lo que permite a los usuarios formular preguntas de seguimiento y explorar datos de forma más natural a lo largo del tiempo. Con Genie API, puede integrar consultas de lenguaje natural en sus herramientas y flujos de trabajo, lo que hace que los datos sean más accesibles en toda la organización.

Antes de usar la API, debe preparar un entorno de Genie bien organizado. El espacio define el contexto que usa Genie para interpretar preguntas y devolver resultados. Si el espacio está incompleto o no probado, los usuarios pueden recibir una alta tasa de respuestas incorrectas, incluso si la propia integración de api es correcta. En esta guía se describe la configuración mínima necesaria para crear un espacio que funcione de forma eficaz con Genie API.

Prerrequisitos

Para usar la API de conversación de Genie, debe tener:

  • Acceso a un área de trabajo de Azure Databricks con el permiso de Databricks SQL.
  • Necesita al menos privilegios para usar en SQL Pro o en un almacén de SQL sin servidor.
  • Familiaridad con la referencia de la API de REST de Databricks.

Paso 1: Crear y probar un espacio de Genie

Prepare un espacio de Genie que responda de forma confiable a las preguntas del usuario con un alto grado de precisión.

Nota:

Incluso si planea consultar el espacio de Genie mediante la API, debe configurar y refinar el espacio mediante la interfaz de usuario de Azure Databricks.

Use los siguientes recursos para ayudarle a configurar y mantener el espacio de Genie:

  1. Configure un espacio de Genie: Aprenda a crear un espacio de Genie mediante la interfaz de usuario de Azure Databricks. En este artículo se incluyen instrucciones paso a paso para usar herramientas de interfaz de usuario para crear un espacio de Genie en funcionamiento.
  2. Revise los procedimientos recomendados: Obtenga información sobre los procedimientos recomendados para mantener un nuevo espacio de Genie. En este artículo se ofrecen recomendaciones sobre cómo abordar la creación de nuevos espacios de Genie y cómo refinarlos e iterar sobre ellos mediante pruebas y retroalimentación.
  3. Establecer pruebas comparativas: Prepare las preguntas de prueba de pruebas comparativas que puede ejecutar para medir la precisión de la respuesta de Genie.

Un espacio Genie bien estructurado tiene las siguientes características:

  • Usa datos anotados bien: Genie se basa en los metadatos de tabla y los comentarios de columna para generar respuestas. Las fuentes de datos del Unity Catalog para el espacio de Genie deben incluir comentarios claros y descriptivos.
  • Está probado por el usuario: usted debería ser el primer usuario de su espacio. Pruebe el espacio haciendo preguntas que espera de los usuarios finales. Use las pruebas para crear y refinar consultas SQL de ejemplo.
  • Incluye contexto específico de la empresa: Debe incluir contexto para enseñar a Genie sobre los datos y la jerga de su empresa. Consulte Adición de ejemplos e instrucciones para obtener información sobre cómo agregar instrucciones, por ejemplo, SQL y funciones para procesar preguntas comunes. Apunte a incluir al menos 5 consultas SQL de ejemplo que se han sometido a pruebas y refinamiento.
  • Usa pruebas comparativas para probar la precisión: Agregue al menos 5 preguntas comparativas en función de las preguntas que prevé de los usuarios finales. Ejecute pruebas comparativas para comprobar que Genie responde con precisión a esas preguntas.

Cuando esté satisfecho con las respuestas de su espacio de Genie y la haya probado con preguntas representativas, puede empezar a integrarla con la aplicación.

Paso 2: Configuración de la autenticación de Azure Databricks

Para casos de uso de producción en los que esté presente un usuario con acceso a un navegador, use OAuth para usuarios (OAuth U2M). En situaciones en las que no es posible la autenticación basada en navegador, puede usar una entidad de servicio para autenticarse con la API. Consulte OAuth para entidades de servicio (OAuth M2M). Las entidades de servicio deben tener permisos para acceder a los datos necesarios y a los almacenes de datos SQL.

Paso 3: Recopilar detalles

Utilice la URL del espacio de Genie para encontrar el nombre de la instancia del espacio de trabajo y la ID del espacio de Genie. En el ejemplo siguiente se muestra cómo localizar estos componentes en la dirección URL. Para más información sobre los identificadores del área de trabajo en la dirección URL, consulte Obtención de identificadores para objetos del área de trabajo.

https://<databricks-instance>/genie/rooms/<space-id>

Copie el <databricks-instance> y el <space-id> para su espacio de Genie.

Enumerar espacios de Genie

En lugar de buscar el space-id en la dirección URL, puede usar el punto de conexión Enumerar espacios de GenieGET /api/2.0/genie/spaces para obtener programáticamente una lista de todos los espacios de Genie en un área de trabajo a la que el usuario tiene acceso. La matriz devuelta spaces enumera la descripción, el identificador de espacio y el título de cada espacio de Genie.

Paso 4: Iniciar una conversación

El punto de conexión Iniciar conversaciónPOST /api/2.0/genie/spaces/{space_id}/start-conversation inicia una nueva conversación en su espacio Genie.

Reemplace los marcadores de posición por su instancia de Databricks, su identificador de espacio de Genie y su token de autenticación. Un ejemplo de respuesta correcta sigue a la solicitud. Incluye detalles que puede usar para acceder a esta conversación de nuevo para las preguntas de seguimiento.

POST /api/2.0/genie/spaces/{space_id}/start-conversation

HOST= <DATABRICKS_INSTANCE>
Authorization: <your_authentication_token>
{
    "content": "<your question>",
}


Response:

{
  "conversation": {
    "created_timestamp": 1719769718,
    "id": "6a64adad2e664ee58de08488f986af3e",
    "last_updated_timestamp": 1719769718,
    "space_id": "3c409c00b54a44c79f79da06b82460e2",
    "title": "Give me top sales for last month",
    "user_id": 12345
  },
  "message": {
    "attachments": null,
    "content": "Give me top sales for last month",
    "conversation_id": "6a64adad2e664ee58de08488f986af3e",
    "created_timestamp": 1719769718,
    "error": null,
    "id": "e1ef34712a29169db030324fd0e1df5f",
    "last_updated_timestamp": 1719769718,
    "query_result": null,
    "space_id": "3c409c00b54a44c79f79da06b82460e2",
    "status": "IN_PROGRESS",
    "user_id": 12345
  }
}

Paso 5: Recuperación de SQL generado

Use los conversation_id y message_id en la respuesta para sondear y comprobar el estado de generación del mensaje y recuperar el código SQL generado por Genie. Consulte GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id} para obtener detalles completos de solicitud y respuesta.

Nota:

Solo POST las solicitudes cuentan para el límite de capacidad de procesamiento de consultas por minuto. GET Las solicitudes usadas para sondear los resultados no están sujetas a este límite.

Sustituya sus valores en la siguiente solicitud:

GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}
HOST= <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>

La siguiente respuesta de ejemplo informa de los detalles del mensaje:

Response:

{
  "attachments": null,
  "content": "Give me top sales for last month",
  "conversation_id": "6a64adad2e664ee58de08488f986af3e",
  "created_timestamp": 1719769718,
  "error": null,
  "id": "e1ef34712a29169db030324fd0e1df5f",
  "last_updated_timestamp": 1719769718,
  "query_result": null,
  "space_id": "3c409c00b54a44c79f79da06b82460e2",
  "status": "IN_PROGRESS",
  "user_id": 12345
}

Cuando el status campo es COMPLETED la respuesta se rellena en la attachments matriz.

Paso 6: Recuperar los resultados de la consulta

La attachments matriz contiene la respuesta de Genie. Incluye la respuesta de texto generada (text), la instrucción de consulta si existe (query) y un identificador que puede usar para obtener los resultados de la consulta asociada (attachment_id). Reemplace los marcadores de posición en el ejemplo siguiente para recuperar los resultados de la consulta generada:

GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/query-result/{attachment_id}
Authorization: Bearer <your_authentication_token>

Consulte GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/attachments/{attachment_id}/query-result.

Paso 7: Formular preguntas de seguimiento

Después de recibir una respuesta, utilice el conversation_id para continuar la conversación. El contexto de los mensajes anteriores se conserva y se usa en las respuestas de seguimiento. Para obtener detalles completos de solicitud y respuesta, consulte POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages.

POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages
HOST= <DATABRICKS_INSTANCE>
Authorization: <your_authentication_token>
{
  "content": "Which of these customers opened and forwarded the email?",
}

Procedimientos recomendados para usar Conversation API

Para mantener el rendimiento y la confiabilidad al usar Genie Conversation API:

  • Implemente la puesta en cola y el retroceso de solicitudes: La API no administra los reintentos de solicitud. Use su propio sistema de puesta en cola e implemente retroceso incremental para evitar superar los límites de rendimiento.
  • Sondee las actualizaciones de estado cada 5 a 10 segundos: Continúe sondeando hasta que se reciba un estado de mensaje concluyente, como COMPLETED, FAILEDo CANCELLED. Limite el sondeo a 10 minutos para la mayoría de las consultas. Si no hay ninguna respuesta concluyente después de 10 minutos, detenga el sondeo y devuelva un error de tiempo de espera o pida al usuario que compruebe manualmente el estado de la consulta más adelante.
  • Use retroceso exponencial después de 2 minutos: Si no se recibe ninguna respuesta en un plazo de 2 minutos, aplique retroceso exponencial para mejorar la confiabilidad.
  • Inicie una nueva conversación para cada sesión: Evite reutilizar los subprocesos de conversación entre sesiones, ya que esto puede reducir la precisión debido a la reutilización de contexto no deseada.
  • Mantener límites de conversación: Utilice el punto de conexión de eliminación de conversación para eliminar conversaciones mediante programación cuando se acerque al límite de 10,000 conversaciones.

Supervisión del espacio

Una vez configurada la aplicación, puede supervisar las preguntas y respuestas en la interfaz de usuario de Databricks.

Anime a los usuarios a probar el espacio para que obtenga información sobre los tipos de preguntas que es probable que hagan y las respuestas que reciben. Proporcione a los usuarios instrucciones para ayudarles a empezar a probar el espacio. Use la pestaña Supervisión para ver preguntas y respuestas. Consulte Monitorizar el espacio.

También puede usar registros de auditoría para supervisar la actividad en un espacio de Genie. Consulte Eventos de IA/BI Genie.

Límite de rendimiento

Durante el período de vista previa pública, las tasas de rendimiento de la API de Conversaciones se ofrecen en función del mejor esfuerzo y dependen de la capacidad del sistema. En condiciones normales o de poco tráfico, las solicitudes se limitan a 5 consultas por minuto por área de trabajo. Durante los períodos de uso máximo, el rendimiento real puede ser menor, ya que las solicitudes se procesan en función de la capacidad disponible.