Utiliser l’API Genie pour intégrer Genie dans vos applications

Importante

Cette fonctionnalité est disponible en préversion publique.

Cette page explique comment utiliser l’API Genie pour activer les fonctionnalités de Génie dans votre propre chatbot, agent ou application.

Aperçu

L’API Genie fournit deux types de fonctionnalités :

API de conversation : activez l’interrogation des données en langage naturel dans les applications, les chatbots et les infrastructures de l’agent IA. Ces API prennent en charge les conversations à état où les utilisateurs peuvent poser des questions de suivi et explorer des données naturellement au fil du temps.
API de gestion : activez la création, la configuration et le déploiement par programmation d’espaces de travail Genie. Utilisez ces API pour les pipelines CI/CD, le contrôle de version et la gestion automatisée de l’espace.

Cette page décrit les API de conversation et de gestion. Avant d’appeler les API de conversation, préparez un espace Génie bien organisé. L’espace fournit le contexte que Genie utilise pour interpréter les questions et générer des réponses. Si l’espace est incomplet ou non testé, les utilisateurs peuvent toujours recevoir des résultats incorrects même avec une intégration d’API correcte. Ce guide explique la configuration minimale nécessaire pour créer un espace qui fonctionne efficacement avec l’API Genie.

Conditions préalables

Pour utiliser l’API Genie, vous devez avoir :

Accès à un espace de travail Azure Databricks avec l'autorisation Databricks SQL.
Au moins les privilèges PEUT UTILISER sur un entrepôt de données SQL Pro ou SQL serverless.

Mise en route

Configurer l’authentification Azure Databricks

Pour les cas d’usage de production où un utilisateur ayant accès à un navigateur est présent, utilisez OAuth pour les utilisateurs (OAuth U2M). Dans les situations où l’authentification basée sur un navigateur n’est pas possible, utilisez un principal de service pour s’authentifier auprès de l’API. Consultez OAuth pour les entités de service (OAuth M2M). Les principaux de service doivent disposer des autorisations nécessaires pour accéder aux données requises et aux entrepôts SQL.

Collecter les détails

Nom de l’instance de l’espace de travail : recherchez et copiez le nom de votre instance d’espace de travail à partir de l’URL de votre espace de travail Databricks. Pour plus d’informations sur les identificateurs d’espace de travail dans votre URL, consultez Obtenir des identificateurs pour les objets d’espace de travail.

Exemple : https://cust-success.cloud.databricks.com/
ID d’entrepôt : vous avez besoin de l’ID d’un entrepôt SQL sur lequel vous disposez au moins des privilèges CAN USE. Pour trouver votre ID d’entrepôt :
1. Accédez à SQL Warehouses dans votre espace de travail.
2. Sélectionnez l’entrepôt que vous souhaitez utiliser.
3. Copiez l’ID de l’entrepôt à partir de l’URL ou de la page de détails de l’entrepôt.
Vous pouvez également utiliser le point de terminaisonGET /api/2.0/sql/warehouses d’entrepôts de liste pour récupérer par programme une liste de tous les entrepôts SQL auxquels vous disposez des autorisations d’accès. La réponse inclut l’ID de l’entrepôt.

Créer ou sélectionner un espace Génie

Un espace Génie bien structuré présente les caractéristiques suivantes :

Utilise des données bien annotées : Genie s’appuie sur les métadonnées de table et les commentaires de colonne. Vérifiez que vos sources de données Unity Catalog ont des commentaires clairs et descriptifs.
Est-il testé par l’utilisateur final : Testez votre espace en posant des questions que vous attendez des utilisateurs finaux. Utilisez des tests pour créer et affiner des exemples de requêtes SQL.
Inclut le contexte spécifique à l’entreprise : Ajoutez des instructions, des exemples de sql et des fonctions. Consultez ajouter des exemples et des instructions SQL. Visez au moins cinq exemples de requêtes SQL testées.
Utilise des benchmarks pour tester la précision : Ajoutez au moins cinq questions de référence en fonction des questions attendues de l’utilisateur. Consultez Utiliser des points de référence dans un espace Genie.

Pour plus d’informations sur la création d’un espace, consultez Configurer et gérer un espace AI/BI Genie et Organiser un espace Génie efficace.

Vous pouvez créer un espace Génie ou utiliser un espace existant :

Créer un nouvel espace

Créez un espace Genie par programmation à l’aide de l’API Créer un espace Génie. L’exemple suivant illustre un espace bien structuré qui suit les meilleures pratiques. Remplacez les espaces réservés par vos valeurs :

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

Utiliser un espace existant

Si vous disposez déjà d’un espace Génie, vous trouverez l’ID d’espace à l’aide de l’API d’espaces List Genie. Vous pouvez également rechercher et copier l’ID d’espace à partir de l’onglet Paramètres de l’espace Génie.

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

Utilisez la réponse space_id dans les appels d’API suivants.

Comprendre le champ serialized_space

Le serialized_space champ est une chaîne JSON qui définit la configuration et les sources de données pour votre espace Genie. Dans la requête d’API, ce JSON doit être échappé sous forme de chaîne. Le champ contient :

version : Version du schéma (actuellement 1)
config : Configuration de l’espace, y compris :
- sample_questions : Exemples de questions pour guider les utilisateurs. Chaque question nécessite :
  - ID : identificateur unique de la question. Vous pouvez générer n’importe quelle chaîne unique (par exemple, des chaînes alphanumériques courtes ou des UUID). Le système normalise ces identificateurs à 32 caractères.
  - question : tableau contenant le texte de la question.
  Incluez au moins cinq questions diverses qui représentent des cas d’usage courants.
data_sources : Sources de données disponibles pour l’espace, notamment :
- tables : tableau d’objets de table au format d’espace de noms de trois niveaux (catalog.schema.table). Chaque table peut inclure :
  - identificateur : obligatoire. Nom complet de la table.
  - description : facultatif. Tableau contenant du texte de description à propos de la table.
  - column_configs : facultatif. Tableau d’objets de configuration de colonne avec :
    - column_name : nom de colonne.
    - get_example_values : booléen. Indique s’il faut échantillonner des exemples de valeurs de cette colonne.
    - build_value_dictionary : booléen. Indique s’il faut créer un dictionnaire de valeurs pour les colonnes catégorielles.
instructions : facultatif. Instructions structurées pour l’espace, notamment :
- text_instructions : instructions de texte pour l’espace.
- example_question_sqls : tableau d’exemples d’objets de requête SQL.
- join_specs : tableau définissant les relations de jointure entre les tables.
- sql_snippets : objet contenant des filtres, des expressions et des mesures.

La version non échappée du champ à partir de serialized_space de l’exemple de création d'espace ressemble à ceci :

{
  "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"]
        }
      ]
    }
  }
}

Lors de la construction de votre espace, créez cette structure JSON, puis transformez-la en chaîne de caractères pour la requête d’API. Pour plus d’informations sur le schéma, consultez la référence de l’API Créer un espace Génie.

Utilisation de l’API de conversation

Après avoir configuré un espace Genie, utilisez les endpoints de l’API de conversation pour poser des questions, récupérer des résultats et maintenir le contexte dans des conversations multi-tours.

Démarrer une conversation

Le endpoint Démarrer la conversationPOST /api/2.0/genie/spaces/{space_id}/start-conversation démarre une nouvelle conversation dans votre espace Genie.

Remplacez les espaces réservés par votre instance Databricks, l’ID d’espace Genie et le jeton d’authentification. Un exemple de réponse réussie suit la demande. Il inclut des détails que vous pouvez utiliser pour accéder à cette conversation à nouveau pour les questions de suivi.

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

Récupérer la SQL générée.

Utilisez conversation_id et message_id dans la réponse au sondage pour vérifier l’état de génération du message et récupérer le SQL généré de Genie. Consultez GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id} les détails complets de la demande et de la réponse.

Remarque

Seules les POST requêtes comptent pour la limite de débit des requêtes par minute. GET les requêtes utilisées pour interroger les résultats ne sont pas soumises à cette limite.

Remplacez vos valeurs dans la requête suivante :

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

L’exemple de réponse suivant signale les détails du message :

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
}

Lorsque le status champ est COMPLETED, la réponse est renseignée dans le tableau attachments.

Récupérer les résultats de la requête

Le attachments tableau contient la réponse de Genie. Il inclut la réponse de texte générée (text), l’instruction de requête s’il existe (query) et un identificateur que vous pouvez utiliser pour obtenir les résultats de requête associés (attachment_id). Remplacez les espaces réservés dans l’exemple suivant pour récupérer les résultats de requête générés :

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

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

Poser des questions de suivi

Une fois que vous avez reçu une réponse, utilisez l'outil conversation_id pour poursuivre la conversation. Le contexte des messages précédents est conservé et utilisé dans les réponses de suivi. Pour obtenir des détails complets sur la demande et la réponse, consultez 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?",
}

Récupérer des données d’espace et de conversation

L’API Genie fournit des points de terminaison supplémentaires pour récupérer des données de configuration et d’historique à partir d’espaces et de conversations existants.

Récupérer la configuration de l’espace

Lorsque vous récupérez des informations sur l’espace à l’aide de l’API Get Genie Space, vous pouvez inclure le champ serialized_space dans la réponse en définissant le paramètre include_serialized_space à true. Le serialized_space champ contient la représentation sous forme de chaîne sérialisée de l’espace Genie, notamment les instructions, les benchmarks, les jointures et d’autres détails de configuration.

Utilisez cette représentation sérialisée avec l’API Create Genie Space et l’API Update Genie Space pour promouvoir les espaces Genie dans les environnements de travail ou pour créer des sauvegardes des configurations des espaces.

Exemple de GET demande :

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\"]}]}}}"
}

Référencer les anciens threads de conversation

Pour permettre aux utilisateurs de faire référence à d’anciens threads de conversation, utilisez le point de terminaisonGET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages répertorier les messages de conversation pour récupérer tous les messages d’un thread de conversation spécifique.

Récupérer des données de conversation à des fins d’analyse

Les gestionnaires d’espace peuvent récupérer par programmation tous les messages précédents demandés à tous les utilisateurs d’un espace pour l’analyse. Pour récupérer ces données :

Utilisez le GET /api/2.0/genie/spaces/{space_id}/conversations point de terminaison pour obtenir tous les threads de conversation existants dans un espace.
Pour chaque ID de conversation retourné, utilisez le GET /api/2.0/genie/spaces/{space_id}/conversations point de terminaison pour récupérer la liste des messages de cette conversation.

Meilleures pratiques et limites

Meilleures pratiques pour l’utilisation de l’API Genie

Pour maintenir les performances et la fiabilité lors de l’utilisation de l’API Genie :

Implémentez une logique de nouvelle tentative avec interruption exponentielle : L’API n’effectue pas de nouvelles tentatives de demandes ayant échoué pour vous, ajoutez donc votre propre mise en file d’attente et votre interruption exponentielle. Cela permet à votre application de gérer les défaillances temporaires, d’éviter les demandes répétées inutiles et de rester dans les limites de débit à mesure qu’elle augmente.
Consigner les réponses API : Implémentez la journalisation complète des demandes et des réponses d’API pour faciliter le débogage, la surveillance des modèles d’utilisation et le suivi des coûts.
Interrogez les mises à jour d’état toutes les 1 à 5 secondes : Continuez l’interrogation jusqu’à ce qu’un état de message concluant, tel que COMPLETED, FAILEDou CANCELLED, soit reçu. Limitez l’interrogation à 10 minutes pour la plupart des requêtes. S’il n’existe aucune réponse concluante après 10 minutes, arrêtez l’interrogation et retournez une erreur de délai d’expiration ou invitez l’utilisateur à vérifier manuellement l’état de la requête ultérieurement.
Adoptez le recul exponentiel pour le sondage : Augmentez le temps d’attente entre les sondages jusqu’à un maximum d’une minute. Cela réduit les requêtes inutiles pour les requêtes longues tout en autorisant une faible latence pour les requêtes rapides.
Démarrez une nouvelle conversation pour chaque session : Évitez de réutiliser les threads de conversation entre les sessions, car cela peut réduire la précision en raison d’une réutilisation inattendue du contexte.
Maintenir les limites de conversation : Pour gérer les anciennes conversations et rester sous la limite de 10 000 conversations :
1. Utilisez le GET /api/2.0/genie/spaces/{space_id}/conversations point de terminaison pour afficher tous les threads de conversation existants dans un espace.
2. Identifiez les conversations qui ne sont plus nécessaires, telles que les conversations plus anciennes ou les conversations de test.
3. Utilisez le DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id} point de terminaison pour supprimer les conversations par programmation.
N’oubliez pas la limite du résultat de la requête : l’API Genie retourne un maximum de 5 000 lignes par résultat de requête. Si votre analyse des données nécessite davantage de lignes, envisagez d’affiner votre question pour vous concentrer sur un sous-ensemble spécifique de données ou d’utiliser des filtres pour affiner les résultats.

Limite de débit

Pendant la période de préversion publique, les débits pour le niveau gratuit de l’API Genie sont en mode "best-effort" et dépendent de la capacité du système. Dans des conditions normales ou à faible trafic, l’API limite les requêtes à 5 requêtes par minute par espace de travail. Pendant les périodes d’utilisation maximales, le système traite les demandes en fonction de la capacité disponible, ce qui peut entraîner un débit inférieur.

Surveiller l’espace

Une fois votre application configurée, vous pouvez surveiller les questions et réponses dans l’interface utilisateur Databricks.

Encouragez les utilisateurs à tester l’espace afin d’en savoir plus sur les types de questions qu’ils sont susceptibles de poser et les réponses qu’ils reçoivent. Fournissez aux utilisateurs des conseils pour les aider à commencer à tester l’espace. Utilisez l’onglet Surveillance pour afficher les questions et les réponses. Consultez Surveiller l’espace.

Vous pouvez également utiliser les journaux d’audit pour surveiller l’activité dans un espace Génie. Consultez les événements AI/BI Genie.

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2025-12-16