Uso de Genie API para integrar Genie en las aplicaciones

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

Información general

La API de Genie proporciona dos tipos de funcionalidades:

• API de conversación: habilite la consulta de datos de lenguaje natural en aplicaciones, bots de chat y marcos de agente de IA. Estas API admiten conversaciones con estado en las que los usuarios pueden formular preguntas de seguimiento y explorar datos de forma natural a lo largo del tiempo.
• API de administración: habilite la creación, la configuración y la implementación de espacios de Genie en áreas de trabajo. Use estas API para canalizaciones de CI/CD, control de versiones y administración automatizada de espacios.

En esta página se describen las API de conversación y administración. Antes de llamar a las APIs de conversación, prepara un espacio de Genie bien preparado. El espacio proporciona el contexto que usa Genie para interpretar preguntas y generar respuestas. Si el espacio está incompleto o no probado, es posible que los usuarios sigan recibiendo resultados incorrectos incluso con una integración de API correcta. En esta guía se explica la configuración mínima necesaria para crear un espacio que funcione eficazmente con la API de Genie.

Prerrequisitos

Para usar la API 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.

Cómo empezar

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 explorador, use 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.

Recopilación de detalles

• Nombre de la instancia del área de trabajo: Busque y copie el nombre de la instancia de su área de trabajo desde la URL del área de trabajo de Databricks. 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.

  Ejemplo: https://cust-success.cloud.databricks.com/

• ID del almacén: necesita el identificador de un almacén SQL para el que tenga al menos privilegios de USO. Para encontrar el identificador de tu almacén:

  1. Vaya a SQL Warehouses en el área de trabajo.
  2. Seleccione el almacén que desea usar.
  3. Copie el identificador de almacenamiento desde la dirección URL o la página de detalles del almacenamiento.

  Como alternativa, use el endpoint List warehousesGET /api/2.0/sql/warehouses para recuperar programáticamente una lista de todos los almacenes SQL a los que tiene permisos de acceso. La respuesta incluye el ID de almacén.

Crear o seleccionar un espacio de Genie

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

• Usa bien datos anotados: Genie se basa en los metadatos de tabla y los comentarios de columna. Compruebe que los orígenes de datos del Catálogo de Unity tengan comentarios claros y descriptivos.
• Está probado por los usuarios: Prueba tu espacio haciendo las preguntas que esperas que hagan los usuarios finales. Use pruebas para crear y refinar consultas SQL de ejemplo.
• Incluye contexto específico de la empresa: Agregue instrucciones, por ejemplo, SQL y funciones. Consulte Adición de ejemplos e instrucciones de SQL. Apunte a al menos cinco consultas SQL de ejemplo probadas.
• Usa pruebas comparativas para probar la precisión: Agregue al menos cinco preguntas comparativas en función de las preguntas anticipadas del usuario. Consulte Uso de pruebas comparativas en un espacio de Genie.

Para obtener más información sobre cómo crear un espacio, consulte Configuración y administración de un espacio de AI/BI Genie y Curación de un espacio eficaz de Genie.

Puede crear un nuevo espacio de Genie o usar uno existente:

Creación de un nuevo espacio

Cree un espacio de Genie mediante programación mediante la API de creación de espacio de Genie. En el ejemplo siguiente se muestra un espacio bien estructurado que sigue los procedimientos recomendados. Reemplace los marcadores de posición por sus valores:

POST /api/2.0/genie/spaces
Host: <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>
{
  "description": "Space for analyzing sales performance and trends",
  "parent_path": "/Workspace/Users/<username>",
  "serialized_space": "{\"version\":1,\"config\":{\"sample_questions\":[{\"id\":\"a1b2c3d4e5f6\",\"question\":[\"What were total sales last month?\"]},{\"id\":\"b2c3d4e5f6g7\",\"question\":[\"Show top 10 customers by revenue\"]},{\"id\":\"c3d4e5f6g7h8\",\"question\":[\"Compare sales by region for Q1 vs Q2\"]}]},\"data_sources\":{\"tables\":[{\"identifier\":\"sales.analytics.orders\",\"description\":[\"Transactional order data including order date, amount, and customer information\"],\"column_configs\":[{\"column_name\":\"order_date\",\"get_example_values\":true},{\"column_name\":\"status\",\"get_example_values\":true,\"build_value_dictionary\":true},{\"column_name\":\"region\",\"get_example_values\":true,\"build_value_dictionary\":true}]},{\"identifier\":\"sales.analytics.customers\"},{\"identifier\":\"sales.analytics.products\"}]},\"instructions\":{\"text_instructions\":[{\"id\":\"01f0b37c378e1c91\",\"content\":[\"When calculating revenue, sum the order_amount column. When asked about 'last month', use the previous calendar month (not the last 30 days). Round all monetary values to 2 decimal places.\"]}],\"example_question_sqls\":[{\"id\":\"01f0821116d912db\",\"question\":[\"Show top 10 customers by revenue\"],\"sql\":[\"SELECT customer_name, SUM(order_amount) as total_revenue\\n\",\"FROM sales.analytics.orders o\\n\",\"JOIN sales.analytics.customers c ON o.customer_id = c.customer_id\\n\",\"GROUP BY customer_name\\n\",\"ORDER BY total_revenue DESC\\n\",\"LIMIT 10\"]},{\"id\":\"01f099751a3a1df3\",\"question\":[\"What were total sales last month\"],\"sql\":[\"SELECT SUM(order_amount) as total_sales\\n\",\"FROM sales.analytics.orders\\n\",\"WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL 1 MONTH)\\n\",\"AND order_date < DATE_TRUNC('month', CURRENT_DATE)\"]}],\"join_specs\":[{\"id\":\"01f0c0b4e8151\",\"left\":{\"identifier\":\"sales.analytics.orders\",\"alias\":\"orders\"},\"right\":{\"identifier\":\"sales.analytics.customers\",\"alias\":\"customers\"},\"sql\":[\"orders.customer_id = customers.customer_id\"]}],\"sql_snippets\":{\"filters\":[{\"id\":\"01f09972e66d1\",\"sql\":[\"orders.order_amount > 1000\"],\"display_name\":\"high value orders\",\"synonyms\":[\"large orders\",\"big purchases\"]}],\"expressions\":[{\"id\":\"01f09974563a1\",\"alias\":\"order_year\",\"sql\":[\"YEAR(orders.order_date)\"],\"display_name\":\"year\"}],\"measures\":[{\"id\":\"01f09972611f1\",\"alias\":\"total_revenue\",\"sql\":[\"SUM(orders.order_amount)\"],\"display_name\":\"total revenue\",\"synonyms\":[\"revenue\",\"total sales\"]}]}}}",
  "title": "Sales Analytics Space",
  "warehouse_id": "<warehouse-id>"
}

Response:
{
  "space_id": "3c409c00b54a44c79f79da06b82460e2",
  "title": "Sales Analytics Space",
  "description": "Space for analyzing sales performance and trends",
  "warehouse_id": "<warehouse-id>",
  "serialized_space": "{\n  \"version\": 1,\n  \"config\": {\n    \"sample_questions\": [\n      {\n        \"id\": \"a1b2c3d4e5f600000000000000000000\",\n        \"question\": [\n          \"What were total sales last month?\"\n        ]\n      },\n      {\n        \"id\": \"b2c3d4e5f6g700000000000000000000\",\n        \"question\": [\n          \"Show top 10 customers by revenue\"\n        ]\n      },\n      {\n        \"id\": \"c3d4e5f6g7h800000000000000000000\",\n        \"question\": [\n          \"Compare sales by region for Q1 vs Q2\"\n        ]\n      }\n    ]\n  },\n  \"data_sources\": {\n    \"tables\": [\n      {\n        \"identifier\": \"sales.analytics.orders\",\n        \"description\": [\n          \"Transactional order data including order date, amount, and customer information\"\n        ],\n        \"column_configs\": [\n          {\n            \"column_name\": \"order_date\",\n            \"get_example_values\": true\n          },\n          {\n            \"column_name\": \"status\",\n            \"get_example_values\": true,\n            \"build_value_dictionary\": true\n          },\n          {\n            \"column_name\": \"region\",\n            \"get_example_values\": true,\n            \"build_value_dictionary\": true\n          }\n        ]\n      },\n      {\n        \"identifier\": \"sales.analytics.customers\"\n      },\n      {\n        \"identifier\": \"sales.analytics.products\"\n      }\n    ]\n  },\n  \"instructions\": {\n    \"text_instructions\": [\n      {\n        \"id\": \"01f0b37c378e1c91\",\n        \"content\": [\n          \"When calculating revenue, sum the order_amount column. When asked about 'last month', use the previous calendar month (not the last 30 days). Round all monetary values to 2 decimal places.\"\n        ]\n      }\n    ],\n    \"example_question_sqls\": [\n      {\n        \"id\": \"01f0821116d912db\",\n        \"question\": [\n          \"Show top 10 customers by revenue\"\n        ],\n        \"sql\": [\n          \"SELECT customer_name, SUM(order_amount) as total_revenue\\n\",\n          \"FROM sales.analytics.orders o\\n\",\n          \"JOIN sales.analytics.customers c ON o.customer_id = c.customer_id\\n\",\n          \"GROUP BY customer_name\\n\",\n          \"ORDER BY total_revenue DESC\\n\",\n          \"LIMIT 10\"\n        ]\n      },\n      {\n        \"id\": \"01f099751a3a1df3\",\n        \"question\": [\n          \"What were total sales last month\"\n        ],\n        \"sql\": [\n          \"SELECT SUM(order_amount) as total_sales\\n\",\n          \"FROM sales.analytics.orders\\n\",\n          \"WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL 1 MONTH)\\n\",\n          \"AND order_date < DATE_TRUNC('month', CURRENT_DATE)\"\n        ]\n      }\n    ],\n    \"join_specs\": [\n      {\n        \"id\": \"01f0c0b4e8151\",\n        \"left\": {\n          \"identifier\": \"sales.analytics.orders\",\n          \"alias\": \"orders\"\n        },\n        \"right\": {\n          \"identifier\": \"sales.analytics.customers\",\n          \"alias\": \"customers\"\n        },\n        \"sql\": [\n          \"orders.customer_id = customers.customer_id\"\n        ]\n      }\n    ],\n    \"sql_snippets\": {\n      \"filters\": [\n        {\n          \"id\": \"01f09972e66d1\",\n          \"sql\": [\"orders.order_amount > 1000\"],\n          \"display_name\": \"high value orders\",\n          \"synonyms\": [\"large orders\", \"big purchases\"]\n        }\n      ],\n      \"expressions\": [\n        {\n          \"id\": \"01f09974563a1\",\n          \"alias\": \"order_year\",\n          \"sql\": [\"YEAR(orders.order_date)\"],\n          \"display_name\": \"year\"\n        }\n      ],\n      \"measures\": [\n        {\n          \"id\": \"01f09972611f1\",\n          \"alias\": \"total_revenue\",\n          \"sql\": [\"SUM(orders.order_amount)\"],\n          \"display_name\": \"total revenue\",\n          \"synonyms\": [\"revenue\", \"total sales\"]\n        }\n      ]\n    }\n  }\n}\n"
}

Uso de un espacio existente

Si ya tiene un espacio de Genie, puede encontrar el identificador de espacio mediante list Genie spaces API. También puede encontrar y copiar el identificador de espacio en la pestaña Configuración del espacio de Genie .

GET /api/2.0/genie/spaces
Host: <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>

Response:
{
  "spaces": [
    {
      "description": "Space for analyzing sales performance and trends",
      "serialized_space": "{\"version\":1,\"config\":{\"sample_questions\":[{\"id\":\"a1b2c3d4e5f6\",\"question\":[\"What were total sales last month?\"]},{\"id\":\"b2c3d4e5f6g7\",\"question\":[\"Show top 10 customers by revenue\"]},{\"id\":\"c3d4e5f6g7h8\",\"question\":[\"Compare sales by region for Q1 vs Q2\"]}]},\"data_sources\":{\"tables\":[{\"identifier\":\"sales.analytics.orders\",\"description\":[\"Transactional order data including order date, amount, and customer information\"],\"column_configs\":[{\"column_name\":\"order_date\",\"get_example_values\":true},{\"column_name\":\"status\",\"get_example_values\":true,\"build_value_dictionary\":true},{\"column_name\":\"region\",\"get_example_values\":true,\"build_value_dictionary\":true}]},{\"identifier\":\"sales.analytics.customers\"},{\"identifier\":\"sales.analytics.products\"}]},\"instructions\":{\"text_instructions\":[{\"id\":\"01f0b37c378e1c91\",\"content\":[\"When calculating revenue, sum the order_amount column. When asked about 'last month', use the previous calendar month (not the last 30 days). Round all monetary values to 2 decimal places.\"]}],\"example_question_sqls\":[{\"id\":\"01f0821116d912db\",\"question\":[\"Show top 10 customers by revenue\"],\"sql\":[\"SELECT customer_name, SUM(order_amount) as total_revenue\\n\",\"FROM sales.analytics.orders o\\n\",\"JOIN sales.analytics.customers c ON o.customer_id = c.customer_id\\n\",\"GROUP BY customer_name\\n\",\"ORDER BY total_revenue DESC\\n\",\"LIMIT 10\"]},{\"id\":\"01f099751a3a1df3\",\"question\":[\"What were total sales last month\"],\"sql\":[\"SELECT SUM(order_amount) as total_sales\\n\",\"FROM sales.analytics.orders\\n\",\"WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL 1 MONTH)\\n\",\"AND order_date < DATE_TRUNC('month', CURRENT_DATE)\"]}],\"join_specs\":[{\"id\":\"01f0c0b4e8151\",\"left\":{\"identifier\":\"sales.analytics.orders\",\"alias\":\"orders\"},\"right\":{\"identifier\":\"sales.analytics.customers\",\"alias\":\"customers\"},\"sql\":[\"orders.customer_id = customers.customer_id\"]}],\"sql_snippets\":{\"filters\":[{\"id\":\"01f09972e66d1\",\"sql\":[\"orders.order_amount > 1000\"],\"display_name\":\"high value orders\",\"synonyms\":[\"large orders\",\"big purchases\"]}],\"expressions\":[{\"id\":\"01f09974563a1\",\"alias\":\"order_year\",\"sql\":[\"YEAR(orders.order_date)\"],\"display_name\":\"year\"}],\"measures\":[{\"id\":\"01f09972611f1\",\"alias\":\"total_revenue\",\"sql\":[\"SUM(orders.order_amount)\"],\"display_name\":\"total revenue\",\"synonyms\":[\"revenue\",\"total sales\"]}]}}}",
      "space_id": "3c409c00b54a44c79f79da06b82460e2",
      "title": "Sales Analytics Space",
      "warehouse_id": "<warehouse-id>",
    },
    {
      "description": "Space for marketing campaign analysis",
      "serialized_space": "{\"version\":1,\"config\":{\"sample_questions\":[{\"id\":\"a1b2c3d4e5f6\",\"question\":[\"Show total revenue by state\"]}]},\"data_sources\":{\"tables\":[{\"identifier\":\"sales.gold.orders\"}]}}",
      "space_id": "7f8e9d0c1b2a3456789abcdef0123456",
      "title": "Marketing Analytics Space",
      "warehouse_id": "<warehouse-id>",
    }
  ]
}

Utilice el space_id de la respuesta en las llamadas API posteriores.

Descripción del campo serialized_space

El serialized_space campo es una cadena JSON que define la configuración y los orígenes de datos para el espacio de Genie. En la solicitud de API, este JSON debe ser escapado como una cadena. El campo contiene:

• versión: versión del esquema (actualmente 1)

• config: configuración del espacio, entre las que se incluyen:

  • sample_questions: preguntas de ejemplo para guiar a los usuarios. Cada pregunta requiere:

    • id: identificador único para la pregunta. Puede generar cualquier cadena única (como cadenas alfanuméricas cortas o UUID). El sistema normaliza estos a identificadores de 32 caracteres.
    • pregunta: matriz que contiene el texto de la pregunta.

    Incluya al menos cinco preguntas diversas que representen casos de uso comunes.

• data_sources: orígenes de datos disponibles para el espacio, entre los que se incluyen:

  • tablas: matriz de objetos de tabla en formato de espacio de nombres de tres niveles (catalog.schema.table). Cada tabla puede incluir:

    • identificador: obligatorio. Nombre completo de la tabla.
    • description: opcional. Matriz que contiene texto de descripción sobre la tabla.
    • column_configs: opcional. Matriz de objetos de configuración de columnas con:
      • column_name: nombre de columna.
      • get_example_values: booleano. Indica si se deben mostrar valores de ejemplo de esta columna.
      • build_value_dictionary: booleano. Si se va a crear un diccionario de valores para columnas de categorías.

• instrucciones: opcional. Instrucciones estructuradas para el espacio, entre las que se incluyen:

  • text_instructions: instrucciones de texto del espacio.
  • example_question_sqls: matriz de objetos de consulta SQL de ejemplo.
  • join_specs: matriz que define las relaciones de combinación entre tablas.
  • sql_snippets: objeto que contiene filtros, expresiones y medidas.

La versión sin escape del serialized_space campo del ejemplo de espacio de creación tiene el siguiente aspecto:

{
  "version": 1,
  "config": {
    "sample_questions": [
      {
        "id": "a1b2c3d4e5f6",
        "question": ["What were total sales last month?"]
      },
      {
        "id": "b2c3d4e5f6g7",
        "question": ["Show top 10 customers by revenue"]
      },
      {
        "id": "c3d4e5f6g7h8",
        "question": ["Compare sales by region for Q1 vs Q2"]
      }
    ]
  },
  "data_sources": {
    "tables": [
      {
        "identifier": "sales.analytics.orders",
        "description": ["Transactional order data including order date, amount, and customer information"],
        "column_configs": [
          {
            "column_name": "order_date",
            "get_example_values": true
          },
          {
            "column_name": "status",
            "get_example_values": true,
            "build_value_dictionary": true
          },
          {
            "column_name": "region",
            "get_example_values": true,
            "build_value_dictionary": true
          }
        ]
      },
      {
        "identifier": "sales.analytics.customers"
      },
      {
        "identifier": "sales.analytics.products"
      }
    ]
  },
  "instructions": {
    "text_instructions": [
      {
        "id": "01f0b37c378e1c91",
        "content": [
          "When calculating revenue, sum the order_amount column. When asked about 'last month', use the previous calendar month (not the last 30 days). Round all monetary values to 2 decimal places."
        ]
      }
    ],
    "example_question_sqls": [
      {
        "id": "01f0821116d912db",
        "question": ["Show top 10 customers by revenue"],
        "sql": [
          "SELECT customer_name, SUM(order_amount) as total_revenue\n",
          "FROM sales.analytics.orders o\n",
          "JOIN sales.analytics.customers c ON o.customer_id = c.customer_id\n",
          "GROUP BY customer_name\n",
          "ORDER BY total_revenue DESC\n",
          "LIMIT 10"
        ]
      },
      {
        "id": "01f099751a3a1df3",
        "question": ["What were total sales last month"],
        "sql": [
          "SELECT SUM(order_amount) as total_sales\n",
          "FROM sales.analytics.orders\n",
          "WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL 1 MONTH)\n",
          "AND order_date < DATE_TRUNC('month', CURRENT_DATE)"
        ]
      }
    ],
    "join_specs": [
      {
        "id": "01f0c0b4e8151",
        "left": {
          "identifier": "sales.analytics.orders",
          "alias": "orders"
        },
        "right": {
          "identifier": "sales.analytics.customers",
          "alias": "customers"
        },
        "sql": ["orders.customer_id = customers.customer_id"]
      }
    ],
    "sql_snippets": {
      "filters": [
        {
          "id": "01f09972e66d1",
          "sql": ["orders.order_amount > 1000"],
          "display_name": "high value orders",
          "synonyms": ["large orders", "big purchases"]
        }
      ],
      "expressions": [
        {
          "id": "01f09974563a1",
          "alias": "order_year",
          "sql": ["YEAR(orders.order_date)"],
          "display_name": "year"
        }
      ],
      "measures": [
        {
          "id": "01f09972611f1",
          "alias": "total_revenue",
          "sql": ["SUM(orders.order_amount)"],
          "display_name": "total revenue",
          "synonyms": ["revenue", "total sales"]
        }
      ]
    }
  }
}

Al crear su espacio, cree esta estructura JSON y, a continuación, conviértala en una cadena para la solicitud de API. Para obtener detalles completos del esquema, ver la documentación de la API 'Create Genie Space'.

Uso de la API de conversación

Después de configurar un espacio de Genie, use los puntos de conexión de la API de conversación para formular preguntas, recuperar resultados y mantener conversaciones multiturno con contexto.

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
  }
}

Recupera el 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.

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.

Recuperación de 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.

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?",
}

Recuperación de datos de espacio y conversación

La API de Genie proporciona puntos de conexión adicionales para recuperar datos históricos y de configuración de espacios y conversaciones existentes.

Recuperación de la configuración del espacio

Al recuperar información del espacio mediante Get Genie Space API, puede incluir el campo serialized_space en la respuesta estableciendo el parámetro include_serialized_space a true. El serialized_space campo contiene la representación de cadena serializada del espacio de Genie, incluidas instrucciones, pruebas comparativas, combinaciones y otros detalles de configuración.

Use esta representación serializada con Create Genie Space API y Update Genie Space API para promover espacios de Genie entre áreas de trabajo o crear copias de seguridad de configuraciones de espacio.

Solicitud de ejemplo GET :

GET /api/2.0/genie/spaces/{space_id}?include_serialized_space=true
Host: <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>

Response:
{
  "space_id": "3c409c00b54a44c79f79da06b82460e2",
  "title": "Sales Analytics Space",
  "description": "Space for analyzing sales performance and trends",
  "warehouse_id": "<warehouse-id>",
  "created_timestamp": 1719769718,
  "last_updated_timestamp": 1719769718,
  "serialized_space": "{\"version\":1,\"config\":{\"sample_questions\":[{\"id\":\"a1b2c3d4e5f600000000000000000000\",\"question\":[\"What were total sales last month?\"]},{\"id\":\"b2c3d4e5f6g700000000000000000000\",\"question\":[\"Show top 10 customers by revenue\"]}]},\"data_sources\":{\"tables\":[{\"identifier\":\"sales.analytics.orders\",\"description\":[\"Transactional order data including order date, amount, and customer information\"],\"column_configs\":[{\"column_name\":\"order_date\",\"get_example_values\":true},{\"column_name\":\"status\",\"get_example_values\":true,\"build_value_dictionary\":true},{\"column_name\":\"region\",\"get_example_values\":true,\"build_value_dictionary\":true}]},{\"identifier\":\"sales.analytics.customers\"},{\"identifier\":\"sales.analytics.products\"}]},\"instructions\":{\"text_instructions\":[{\"id\":\"01f0b37c378e1c91\",\"content\":[\"When calculating revenue, sum the order_amount column. When asked about 'last month', use the previous calendar month (not the last 30 days). Round all monetary values to 2 decimal places.\"]}],\"example_question_sqls\":[{\"id\":\"01f0821116d912db\",\"question\":[\"Show top 10 customers by revenue\"],\"sql\":[\"SELECT customer_name, SUM(order_amount) as total_revenue\\n\",\"FROM sales.analytics.orders o\\n\",\"JOIN sales.analytics.customers c ON o.customer_id = c.customer_id\\n\",\"GROUP BY customer_name\\n\",\"ORDER BY total_revenue DESC\\n\",\"LIMIT 10\"]},{\"id\":\"01f099751a3a1df3\",\"question\":[\"What were total sales last month\"],\"sql\":[\"SELECT SUM(order_amount) as total_sales\\n\",\"FROM sales.analytics.orders\\n\",\"WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL 1 MONTH)\\n\",\"AND order_date < DATE_TRUNC('month', CURRENT_DATE)\"]}],\"join_specs\":[{\"id\":\"01f0c0b4e8151\",\"left\":{\"identifier\":\"sales.analytics.orders\",\"alias\":\"orders\"},\"right\":{\"identifier\":\"sales.analytics.customers\",\"alias\":\"customers\"},\"sql\":[\"orders.customer_id = customers.customer_id\"]}],\"sql_snippets\":{\"filters\":[{\"id\":\"01f09972e66d1\",\"sql\":[\"orders.order_amount > 1000\"],\"display_name\":\"high value orders\",\"synonyms\":[\"large orders\",\"big purchases\"]}],\"expressions\":[{\"id\":\"01f09974563a1\",\"alias\":\"order_year\",\"sql\":[\"YEAR(orders.order_date)\"],\"display_name\":\"year\"}],\"measures\":[{\"id\":\"01f09972611f1\",\"alias\":\"total_revenue\",\"sql\":[\"SUM(orders.order_amount)\"],\"display_name\":\"total revenue\",\"synonyms\":[\"revenue\",\"total sales\"]}]}}}"
}

Hacer referencia a los subprocesos de conversación antiguos

Para permitir que los usuarios hagan referencia a los subprocesos de conversación antiguos, use el punto de conexiónGET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages Enumerar mensajes de conversación para recuperar todos los mensajes de un subproceso de conversación específico.

Recuperación de datos de conversación para el análisis

Los administradores de espacio pueden recuperar mediante programación todos los mensajes anteriores solicitados en todos los usuarios de un espacio para su análisis. Para recuperar estos datos:

1. Use el GET /api/2.0/genie/spaces/{space_id}/conversations punto de conexión para obtener todos los subprocesos de conversación existentes en un espacio.
2. Para cada identificador de conversación devuelto, use el GET /api/2.0/genie/spaces/{space_id}/conversations punto de conexión para recuperar la lista de mensajes de esa conversación.

Procedimientos recomendados y límites

Procedimientos recomendados para usar la API de Genie

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

• Implemente la lógica de reintento con espera exponencial: La API no vuelve a intentar las solicitudes fallidas, por lo que debe agregar su propio encolamiento y espera exponencial. Esto ayuda a la aplicación a controlar errores transitorios, evitar solicitudes de repetición innecesarias y mantenerse dentro de los límites de rendimiento a medida que crece.
• Registro de respuestas y solicitudes de la API: Implemente un registro exhaustivo de las solicitudes y respuestas de la API para ayudar con la depuración, la supervisión de patrones de uso y el seguimiento de costos.
• Sondee las actualizaciones de estado cada 1 a 5 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.
• Utilice backoff exponencial para las consultas: Incremente el intervalo entre las consultas hasta un máximo de un minuto. Esto reduce las solicitudes innecesarias para las consultas de larga duración, a la vez que permite una latencia baja para las rápidas.
• 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: Para administrar conversaciones antiguas y mantenerse por debajo del límite de 10 000 conversaciones:
  1. Use el GET /api/2.0/genie/spaces/{space_id}/conversations punto de conexión para ver todos los subprocesos de conversación existentes en un espacio.
  2. Identifique las conversaciones que ya no son necesarias, como conversaciones anteriores o conversaciones de prueba.
  3. Use el DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id} punto de conexión para quitar conversaciones mediante programación.
• Tenga en cuenta el límite de resultados de la consulta: Genie API devuelve un máximo de 5000 filas por resultado de consulta. Si el análisis de datos requiere más filas, considere la posibilidad de refinar la pregunta para centrarse en un subconjunto específico de datos o usar filtros para restringir los resultados.

Límite de rendimiento

Durante el período de versión preliminar pública, las tasas de rendimiento del nivel gratis de Genie API son el mejor esfuerzo y dependen de la capacidad del sistema. En condiciones normales o de poco tráfico, la API limita las solicitudes a 5 consultas por minuto por área de trabajo. Durante los períodos de uso máximo, el sistema procesa las solicitudes en función de la capacidad disponible, lo que puede dar lugar a un menor rendimiento.

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.