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

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.

Les exemples de cette page utilisent directement l’API REST. Vous pouvez également appeler ces API à l’aide des sdk Azure Databricks. Consultez les Kits de développement logiciel (SDK) Databricks.

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.
  • Test de l’utilisateur : 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 un contexte spécifique à l’entreprise : ajouter 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 benchmark 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 Génie etOrganiser 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 : numéro de version du schéma pour la compatibilité descendante. Utilisez 2 comme indiqué dans l’exemple ci-dessous.
  • config : Configuration de l’espace, y compris :
    • sample_questions : Exemples de questions pour guider les utilisateurs. Chaque question nécessite un ID (chaîne hexadécimal de 32 caractères) et une question (tableau de chaînes).
  • data_sources : sources de données disponibles pour l’espace :
    • tables : tableau d’objets de table avec identificateur (espace de noms à trois niveaux), description facultative et column_configs facultatif.
    • metric_views : tableau d’objets de vue de métrique (même structure que les tables).
  • instructions : instructions structurées pour l’espace :
    • text_instructions : lignes directrices générales pour le LLM.
    • example_question_sqls : Exemples de questions avec des réponses SQL, éventuellement avec des paramètres et des usage_guidance.
    • sql_functions : références aux fonctions SQL disponibles pour l’espace.
    • join_specs : relations de jointure prédéfinies entre les tables. Le sql champ nécessite exactement deux éléments : la condition de jointure, à l’aide de références d’alias entre guillemets inversés, et une annotation de type relationnel, par exemple "--rt=FROM_RELATIONSHIP_TYPE_MANY_TO_ONE--". Consultez le format des spécifications de jointure.
    • sql_snippets : filtres, expressions et mesuresréutilisables.
  • benchmarks : Questions sur l'évaluation de la qualité de l'espace de données, chacune avec une réponse de référence SQL.

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

{
  "version": 2,
  "config": {
    "sample_questions": [
      {
        "id": "a1b2c3d4e5f60000000000000000000a",
        "question": ["What were total sales last month?"]
      },
      {
        "id": "b2c3d4e5f6a70000000000000000000b",
        "question": ["Show top 10 customers by revenue"]
      }
    ]
  },
  "data_sources": {
    "tables": [
      {
        "identifier": "sales.analytics.customers",
        "description": ["Customer master data including contact information and account details"],
        "column_configs": [
          {
            "column_name": "customer_id",
            "description": ["Unique identifier for each customer"],
            "synonyms": ["cust_id", "account_id"]
          },
          {
            "column_name": "customer_name",
            "enable_entity_matching": true
          },
          {
            "column_name": "internal_notes",
            "exclude": true
          }
        ]
      },
      {
        "identifier": "sales.analytics.orders",
        "description": ["Transactional order data including order date, amount, and customer information"],
        "column_configs": [
          {
            "column_name": "order_date",
            "enable_format_assistance": true
          },
          {
            "column_name": "region",
            "enable_format_assistance": true,
            "enable_entity_matching": true
          },
          {
            "column_name": "status",
            "enable_format_assistance": true,
            "enable_entity_matching": true
          }
        ]
      },
      {
        "identifier": "sales.analytics.products"
      }
    ],
    "metric_views": [
      {
        "identifier": "sales.analytics.revenue_metrics",
        "description": ["Pre-aggregated revenue metrics by region and time period"],
        "column_configs": [
          {
            "column_name": "period",
            "description": ["Time period for the metric (monthly, quarterly, yearly)"],
            "enable_format_assistance": true
          }
        ]
      }
    ]
  },
  "instructions": {
    "text_instructions": [
      {
        "id": "01f0b37c378e1c9100000000000000a1",
        "content": [
          "When calculating revenue, sum the order_amount column. ",
          "When asked about 'last month', use the previous calendar month. ",
          "Round all monetary values to 2 decimal places."
        ]
      }
    ],
    "example_question_sqls": [
      {
        "id": "01f0821116d912db00000000000000b1",
        "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": "01f099751a3a1df300000000000000b2",
        "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)"
        ]
      },
      {
        "id": "01f099751a3a1df300000000000000b3",
        "question": ["Show sales for a specific region"],
        "sql": [
          "SELECT SUM(order_amount) as total_sales\n",
          "FROM sales.analytics.orders\n",
          "WHERE region = :region_name"
        ],
        "parameters": [
          {
            "name": "region_name",
            "type_hint": "STRING",
            "description": ["The region to filter by (e.g., 'North America', 'Europe')"],
            "default_value": {
              "values": ["North America"]
            }
          }
        ],
        "usage_guidance": ["Use this example when the user asks about sales filtered by a specific geographic region"]
      }
    ],
    "sql_functions": [
      {
        "id": "01f0c0b4e815100000000000000000f1",
        "identifier": "sales.analytics.fiscal_quarter"
      }
    ],
    "join_specs": [
      {
        "id": "01f0c0b4e815100000000000000000c1",
        "left": {
          "identifier": "sales.analytics.orders",
          "alias": "orders"
        },
        "right": {
          "identifier": "sales.analytics.customers",
          "alias": "customers"
        },
        "sql": ["`orders`.`customer_id` = `customers`.`customer_id`", "--rt=FROM_RELATIONSHIP_TYPE_MANY_TO_ONE--"],
        "comment": ["Join orders to customers on customer_id"],
        "instruction": ["Use this join when you need customer details for order analysis"]
      }
    ],
    "sql_snippets": {
      "filters": [
        {
          "id": "01f09972e66d100000000000000000d1",
          "sql": ["orders.order_amount > 1000"],
          "display_name": "high value orders",
          "synonyms": ["large orders", "big purchases"],
          "comment": ["Filters to orders over $1000"],
          "instruction": ["Use when the user asks about high-value or large orders"]
        }
      ],
      "expressions": [
        {
          "id": "01f09974563a100000000000000000e1",
          "alias": "order_year",
          "sql": ["YEAR(orders.order_date)"],
          "display_name": "year",
          "synonyms": ["fiscal year", "calendar year"],
          "comment": ["Extracts the year from order date"],
          "instruction": ["Use for year-over-year analysis"]
        }
      ],
      "measures": [
        {
          "id": "01f09972611f100000000000000000f1",
          "alias": "total_revenue",
          "sql": ["SUM(orders.order_amount)"],
          "display_name": "total revenue",
          "synonyms": ["revenue", "total sales"],
          "comment": ["Sum of all order amounts"],
          "instruction": ["Use this measure for revenue calculations"]
        }
      ]
    }
  },
  "benchmarks": {
    "questions": [
      {
        "id": "01f0d0b4e815100000000000000000g1",
        "question": ["What is the average order value?"],
        "answer": [
          {
            "format": "SQL",
            "content": ["SELECT AVG(order_amount) as avg_order_value\n", "FROM sales.analytics.orders"]
          }
        ]
      }
    ]
  }
}

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.

Règles de validation pour serialized_space

Le serialized_space json doit être conforme aux règles de validation suivantes. JSON qui n’est pas valide est rejeté lors de la création ou de la mise à jour de l’espace.

Version

  • Champ Version : Obligatoire. Utiliser 2 pour les nouveaux espaces. Le numéro de version existe pour la compatibilité descendante.

Format de l'ID

Tous les champs d’ID doivent être des chaînes hexadécimales minuscules de 32 caractères (format UUID sans traits d’union).

  • Valide : a1b2c3d4e5f60000000000000000000a
  • Non valide : a1b2c3d4e5f6 (trop court), A1B2C3D4E5F60000000000000000000A (majuscules), a1b2c3d4-e5f6-0000-0000-00000000000a (contient des traits d’union)

Les ID sont requis pour :

  • config.sample_questions[].id
  • instructions.text_instructions[].id
  • instructions.example_question_sqls[].id
  • instructions.join_specs[].id
  • instructions.sql_snippets.filters[].id
  • instructions.sql_snippets.expressions[].id
  • instructions.sql_snippets.measures[].id
  • benchmarks.questions[].id (si des benchmarks sont inclus)

Vous pouvez utiliser la commande suivante pour générer un ID valide :

python3 -c "import random,datetime;t=int((datetime.datetime.now()-datetime.datetime(1582,10,15)).total_seconds()*1e7);print(f'{(t&0xFFFFFFFFFFFF0000)|(1<<12)|((t&0xFFFF)>>4):016x}{random.getrandbits(62)|0x8000000000000000:016x}')"

Cela génère un UUID chronologique. Les ID générés séquentiellement s'ordonnent automatiquement dans l’ordre de leur création, satisfaisant ainsi les exigences de tri automatiquement.

Exigences de tri

Les collections contenant des ID ou des identificateurs doivent être pré-triées. Le système valide que les tableaux sont déjà triés et rejettent l’entrée non triée.

Collection Clé de tri
data_sources.tables identifier (alphabétiquement)
data_sources.metric_views identifier (alphabétiquement)
data_sources.tables[].column_configs column_name (alphabétiquement)
data_sources.metric_views[].column_configs column_name (alphabétiquement)
config.sample_questions id (alphabétiquement)
instructions.text_instructions id (alphabétiquement)
instructions.example_question_sqls id (alphabétiquement)
instructions.sql_functions (id, identifier) tuple (alphabétiquement)
instructions.join_specs id (alphabétiquement)
instructions.sql_snippets.filters id (alphabétiquement)
instructions.sql_snippets.expressions id (alphabétiquement)
instructions.sql_snippets.measures id (alphabétiquement)
benchmarks.questions id (alphabétiquement)

Contraintes d’unicité

  • ID de question : tous les ID dans config.sample_questions et benchmarks.questions doivent être uniques dans les deux collections.
  • ID d’instruction : tous les ID entre text_instructions, example_question_sqls, sql_functions, join_specset tous les sql_snippets types doivent être uniques.
  • Configurations de colonne : la combinaison de (table_identifier, column_name) doit être unique dans l’espace.

Limites de taille et de longueur

  • Longueur de chaîne : les éléments de chaîne individuels sont limités à 25 000 caractères.
  • Taille du tableau : les champs répétés sont limités à 10 000 éléments.
  • Instructions de texte : Au maximum 1 instruction de texte est autorisée par espace.
  • Tables et vues de métriques : soumis à des limites spécifiques à l’espace de travail.
  • Contenu SQL : le texte de requête dans sql et join_specs.sql les champs est soumis à des limites de longueur.

Format des spécifications de jointure

Le sql champ de chaque spécification de jointure doit contenir exactement deux éléments :

  1. Condition de jointure, à l’aide de références d’alias entre guillemets inversés :

    "`orders`.`customer_id` = `customers`.`customer_id`"

  2. Annotation de type relation au format suivant :

    "--rt=FROM_RELATIONSHIP_TYPE_<CARDINALITY>--"

    Valeurs de cardinalité valides :

    • FROM_RELATIONSHIP_TYPE_MANY_TO_ONE
    • FROM_RELATIONSHIP_TYPE_ONE_TO_MANY
    • FROM_RELATIONSHIP_TYPE_ONE_TO_ONE
    • FROM_RELATIONSHIP_TYPE_MANY_TO_MANY

L’omission de l’annotation de type de relation entraîne le rejet de la requête par une erreur d’analyse. Pour les jointures à plusieurs colonnes, créez une spécification de jointure distincte pour chaque relation.

Autres exigences

  • Identificateurs de table : doit utiliser le format d’espace de noms de trois niveaux (catalog.schema.table).
  • Réponses de benchmark : chaque question de benchmark doit avoir exactement une réponse avec un format défini sur SQL.
  • Extraits de code SQL : Les champs SQL de filtre, d’expression et de mesure ne doivent pas être vides.

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 POST les requêtes sont comptabilisées dans les considérations relatives au débit de 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.

Pour déterminer si une réponse a été générée à l’aide d’une ressource approuvée, vérifiez le attachments champ dans la réponse d’un query.parameters objet. Sa présence indique que la réponse provient d’une ressource approuvée.

Pour accéder aux traces de raisonnement de Genie, consultez le champ attachments pour un objet query_attachments de type GenieQueryAttachments. Lorsqu'il est présent, il contient le raisonnement pas à pas que Genie a utilisé pour générer la réponse. Pour plus d’informations sur le champ, consultez la référence de l’API Get message.

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 :

Remarque

L’API Genie Conversation retourne les résultats des requêtes tabulaires sous forme de données structurées. Il ne retourne pas de graphiques ou de visualisations rendus. Pour afficher des graphiques, récupérez les résultats de attachment_id la requête et affichez-les dans votre application à l’aide d’une bibliothèque de graphiques de votre choix. Le query champ de la pièce jointe contient le code SQL généré par Genie, que vous pouvez également exécuter directement sur votre entrepôt pour récupérer les résultats pour la visualisation.

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

Ajouter des commentaires aux messages

Vous pouvez ajouter des commentaires texte aux messages et répertorier les commentaires existants à l’aide des points de terminaison de l’API de commentaire de message.

Pour ajouter un commentaire à un message, utilisez le point de terminaison Créer un commentaire de messagePOST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/comments :

POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/comments
HOST= <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>
{
  "comment": "<your comment text>"
}

Pour répertorier les commentaires existants sur un message, utilisez le point de terminaison Consulter les commentaires de message.

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>",
  "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 fils de conversation, utilisez le point de terminaison List conversation messagesGET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages afin de récupérer tous les messages d’un fil 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 :

  1. 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.
  2. 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 ne tente pas les demandes ayant échoué pour vous. Ajoutez donc votre propre 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.
  • Journalisation des réponses API : implémenter la journalisation complète des demandes et réponses API pour faciliter le débogage, le suivi des modèles d’utilisation et le suivi des coûts.
  • Interroger les mises à jour d’état toutes les 1 à 5 secondes : continuez l’interrogation jusqu’à ce qu’un message d’état concluant, tel que COMPLETED, FAILED ou 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.
  • Utilisez une attente exponentielle pour l'interrogation : augmentez le délai entre les interrogations 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.

Considérations relatives au débit

Les taux de débit pour le niveau gratuit de l'API de conversation Genie sont basés sur le meilleur effort et dépendent de la capacité du système. Pour atténuer l’utilisation abusive et empêcher les abus pendant les périodes d’utilisation maximales, le système traite les demandes en fonction de la capacité disponible. Dans des conditions normales ou à faible trafic, l'API prend en charge les requêtes de cinq questions par minute et par espace de travail. Si vous recherchez une prise en charge d'un débit plus élevé, contactez votre équipe de compte Databricks.

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. Voir les événements Génie.

  • Last updated on