Condividi tramite

Usare l'API Genie per integrare Genie nelle applicazioni

Importante

Questa funzionalità è in Anteprima Pubblica.

Questa pagina illustra come usare l'API Genie per abilitare le funzionalità Genie nel proprio chatbot, agente o applicazione.

Informazioni generali

L'API Genie offre due tipi di funzionalità:

  • API di conversazione: abilitare l'esecuzione di query sui dati in linguaggio naturale in applicazioni, chatbot e framework dell'agente di intelligenza artificiale. Queste API supportano conversazioni con stato in cui gli utenti possono porre domande di approfondimento ed esplorare i dati in modo naturale nel tempo.
  • API di gestione: abilitare la creazione, la configurazione e la distribuzione a livello di codice di spazi Genie tra aree di lavoro. Usare queste API per le pipeline CI/CD, il controllo delle versioni e la gestione automatizzata dello spazio.

Questa pagina descrive sia le API di conversazione che di gestione. Prima di chiamare le API di conversazione, preparare uno spazio Genie ben curato. Lo spazio fornisce il contesto usato da Genie per interpretare le domande e generare risposte. Se lo spazio è incompleto o non testato, gli utenti potrebbero comunque ricevere risultati non corretti anche con un'integrazione dell'API corretta. Questa guida illustra la configurazione minima necessaria per creare uno spazio che funziona in modo efficace con l'API Genie.

Prerequisiti

Per usare l'API Genie, è necessario disporre di:

  • Accesso a un'area di lavoro di Azure Databricks con il diritto SQL di Databricks.
  • Almeno può usare privilegi su un SQL Pro o SQL warehouse serverless.

Come iniziare

Configurare l'autenticazione di Azure Databricks

Per i casi d'uso di produzione in cui è presente un utente con accesso a un browser, usare OAuth per gli utenti (OAuth U2M). In situazioni in cui l'autenticazione basata su browser non è possibile, usare un'entità servizio per eseguire l'autenticazione con l'API. Vedere OAuth per le entità servizio (OAuth M2M). I principali di servizio devono avere le autorizzazioni per accedere ai dati richiesti e ai database SQL.

Raccogliere i dettagli

  • Nome istanza dell'area di lavoro: Trovare e copiare il nome dell'istanza dell'area di lavoro dall'URL dell'area di lavoro di Databricks. Per informazioni dettagliate sugli identificatori dell'area di lavoro nell'URL, vedere Ottenere gli identificatori per gli oggetti dell'area di lavoro.

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

  • ID del magazzino: hai bisogno dell'ID di un magazzino SQL su cui hai almeno i privilegi CAN USE. Per trovare l'ID magazzino:

    1. Passare a SQL Warehouses nell'area di lavoro.
    2. Selezionare il magazzino da usare.
    3. Copiare l'ID magazzino dall'URL o dalla pagina dei dettagli del magazzino.

    In alternativa, usare l'endpoint GET /api/2.0/sql/warehouses per recuperare a livello di codice un elenco di tutti i warehouse SQL a cui si dispone delle autorizzazioni di accesso. La risposta include l'ID magazzino.

Creare o selezionare uno spazio Genie

Uno spazio Genie ben strutturato presenta le caratteristiche seguenti:

  • Usa dati con annotazioni ben annotate: Genie si basa sui metadati della tabella e sui commenti delle colonne. Verificare che le origini dati di Unity Catalog abbiano commenti chiari e descrittivi.
  • Viene testato dall'utente: Testa il tuo spazio ponendo domande che ti aspetti dagli utenti finali. Usare i test per creare e perfezionare query SQL di esempio.
  • Include un contesto specifico dell'azienda: Aggiungere istruzioni, ad esempio SQL e funzioni. Vedere Aggiungere esempi e istruzioni SQL. Mirare ad almeno cinque query SQL di esempio testate.
  • Usa i benchmark per testare l'accuratezza: Aggiungere almeno cinque domande di benchmark in base alle domande degli utenti previste. Consulta Usare i benchmark nello spazio Genie.

Per altre informazioni sulla creazione di uno spazio, vedere Configurare e gestire uno spazio di intelligenza artificiale/BI Genie e Curare uno spazio genie efficace.

È possibile creare un nuovo spazio Genie oppure usarne uno esistente:

Creare un nuovo spazio

Creare uno spazio Genie a livello di codice usando l'API Crea spazio Genie. L'esempio seguente illustra uno spazio ben strutturato che segue le procedure consigliate. Sostituire i segnaposto con i valori:

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

Usare uno spazio esistente

Se si dispone già di uno spazio Genie, è possibile trovare l'ID spazio usando l'API List Genie spaces. È anche possibile trovare e copiare l'ID spazio dalla scheda dello spazio Genie Impostazioni.

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

Usare il space_id della risposta nelle chiamate API successive.

Informazioni sul campo serialized_space

Il serialized_space campo è una stringa JSON che definisce la configurazione e le origini dati per lo spazio Genie. Nella richiesta API, questo JSON deve essere codificato come stringa. Il campo contiene:

  • version: numero di versione dello schema per la compatibilità con le versioni precedenti. Usare 2 come illustrato nell'esempio seguente.
  • config: configurazione dello spazio, tra cui:
    • sample_questions: domande di esempio per guidare gli utenti. Ogni domanda richiede un ID (stringa esadecimale di 32 caratteri) e una domanda (matrice di stringhe).
  • data_sources: fonti di dati disponibili per spazio
    • tables: array di oggetti di tabella con identificatore (spazio dei nomi a tre livelli), descrizione facoltativa e configurazioni delle colonne facoltative.
    • metric_views: matrice di oggetti visualizzazione metrica (stessa struttura delle tabelle).
  • istruzioni: Istruzioni strutturate per lo spazio:
    • text_instructions: linee guida generali per LLM.
    • example_question_sqls: domande di esempio con risposte SQL, facoltativamente con parametri e usage_guidance.
    • sql_functions: riferimenti alle funzioni SQL disponibili per lo spazio.
    • join_specs: relazioni di join predefinite tra tabelle.
    • sql_snippets: filtri riutilizzabili, espressioni e misure.
  • benchmark: domande per la valutazione della qualità dello spazio, ognuna con una risposta SQL di verità di base.

La versione senza caratteri di escape del campo serialized_space dall'esempio di creazione dello spazio appare come segue:

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

Quando costruisci il tuo spazio, crea questa struttura JSON e poi trasformala in una stringa per la richiesta API. Per informazioni dettagliate sullo schema completo, vedere le informazioni di riferimento sull'API Create Genie space (Creare un'API per lo spazio Genie).

Regole di convalida per serialized_space

Il serialized_space codice JSON deve essere conforme alle regole di convalida seguenti. JSON non valido viene rifiutato durante la creazione o l'aggiornamento dello spazio.

Versione

  • Campo versione: obbligatorio. Usare 2 per i nuovi spazi. Il numero di versione esiste per la compatibilità con le versioni precedenti.

Formato ID

Tutti i campi ID devono essere stringhe esadecimali minuscole di 32 caratteri (formato UUID senza trattini).

  • Valido: a1b2c3d4e5f60000000000000000000a
  • Non valido: a1b2c3d4e5f6 (troppo breve), A1B2C3D4E5F60000000000000000000A (maiuscolo), a1b2c3d4-e5f6-0000-0000-00000000000a (contiene trattini)

Gli ID sono obbligatori per:

  • 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 (nel caso in cui fossero inclusi i benchmark)

Requisiti di ordinamento

Le raccolte contenenti ID o identificatori devono essere ordinate in ordine preliminare. Il sistema verifica che le matrici siano già ordinate e rifiutino l'input non ordinato.

Collection Ordinamento della chiave
data_sources.tables identifier (alfabeticamente)
data_sources.metric_views identifier (alfabeticamente)
data_sources.tables[].column_configs column_name (alfabeticamente)
data_sources.metric_views[].column_configs column_name (alfabeticamente)
config.sample_questions id (alfabeticamente)
instructions.text_instructions id (alfabeticamente)
instructions.example_question_sqls id (alfabeticamente)
instructions.sql_functions (id, identifier) tupla (alfabeticamente)
instructions.join_specs id (alfabeticamente)
instructions.sql_snippets.filters id (alfabeticamente)
instructions.sql_snippets.expressions id (alfabeticamente)
instructions.sql_snippets.measures id (alfabeticamente)
benchmarks.questions id (alfabeticamente)

Vincoli di univocità

  • ID domanda: tutti gli ID in config.sample_questions e benchmarks.questions devono essere univoci in entrambe le raccolte.
  • ID istruzione: tutti gli ID in text_instructions, example_question_sqls, sql_functions, join_specs e tutti i tipi di sql_snippets devono essere univoci.
  • Configurazioni di colonna: la combinazione di (table_identifier, column_name) deve essere univoca all'interno dello spazio.

Limiti di dimensioni e lunghezza

  • Lunghezza di stringa: Gli singoli elementi stringa sono limitati a 25.000 caratteri.
  • Dimensioni matrice: i campi ripetuti sono limitati a 10.000 elementi.
  • Istruzioni di testo: al massimo 1 istruzione di testo è consentita per spazio.
  • Tabelle e visualizzazioni delle metriche: soggette a limiti specifici dell'area di lavoro.
  • Contenuto SQL: il testo della query in sql e join_specs.sql i campi è soggetto a limiti di lunghezza.

Altri requisiti

  • Identificatori di tabella: deve usare il formato dello spazio dei nomi a tre livelli (catalog.schema.table).
  • Risposte al benchmark: ogni domanda di benchmark deve avere esattamente una risposta con formato impostato su SQL.
  • Frammenti di codice SQL: i campi filtro, espressione e misura SQL non devono essere vuoti.

Uso dell'API di conversazione

Dopo aver configurato uno spazio Genie, usare gli endpoint dell'API di conversazione per porre domande, recuperare i risultati e gestire conversazioni a più turni con il contesto.

Avviare una conversazione

L'endpoint Avvia conversazionePOST /api/2.0/genie/spaces/{space_id}/start-conversation avvia una nuova conversazione nello spazio Genie.

Sostituire i segnaposto con l'istanza di Databricks, l'ID spazio Genie e il token di autenticazione. Un esempio di risposta riuscita segue la richiesta. Include dettagli che è possibile usare per accedere di nuovo a questa conversazione per le domande di completamento.

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

Recuperare SQL generato

Nella risposta, utilizzare conversation_id e message_id per effettuare un controllo periodico dello stato di generazione del messaggio e ottenere il codice SQL generato da Genie. Per informazioni dettagliate sulla richiesta e sulla risposta complete, vedere GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id} .

Annotazioni

Solo POST le richieste vengono conteggiate per il limite di throughput delle query al minuto. GET le richieste utilizzate per eseguire il polling dei risultati non sono soggette a questo limite.

Sostituire i valori nella richiesta seguente:

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

La risposta di esempio seguente segnala i dettagli del messaggio:

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
}

Quando il status campo è COMPLETED la risposta viene popolata nella attachments matrice.

Recuperare i risultati della query

La attachments matrice contiene la risposta di Genie. Include la risposta di testo generata (text), l'istruzione di query se esistente (query) e un identificatore che è possibile usare per ottenere i risultati della query associati (attachment_id). Sostituire i segnaposto nell'esempio seguente per recuperare i risultati della query generati:

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

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

Porre domande di completamento

Dopo aver ricevuto una risposta, utilizzare il conversation_id per continuare la conversazione. Il contesto dei messaggi precedenti viene conservato e usato nelle risposte di completamento. Per informazioni complete sulla richiesta e sulla risposta, vedere 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?",
}

Recuperare spazio e dati di conversazione

L'API Genie fornisce endpoint aggiuntivi per il recupero di dati di configurazione e cronologici da spazi e conversazioni esistenti.

Recuperare la configurazione dello spazio

Quando si recuperano informazioni sullo spazio usando l'API Get Genie Space, è possibile includere il serialized_space campo nella risposta impostando il include_serialized_space parametro su true. Il serialized_space campo contiene la rappresentazione di stringa serializzata dello spazio Genie, incluse istruzioni, benchmark, join e altri dettagli di configurazione.

Usare questa rappresentazione serializzata con l'API Create Genie Space e Update Genie Space API per alzare di livello gli spazi Genie tra aree di lavoro o creare backup di configurazioni dello spazio.

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

Fare riferimento a thread di conversazione precedenti

Per consentire agli utenti di fare riferimento ai thread di conversazione precedenti, usare l'endpoint GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages per recuperare tutti i messaggi da un thread di conversazione specifico.

Recuperare i dati della conversazione per l'analisi

Gli strumenti di gestione dello spazio possono recuperare a livello di codice tutti i messaggi precedenti richiesti in tutti gli utenti di uno spazio per l'analisi. Per recuperare questi dati:

  1. Usare l'endpoint GET /api/2.0/genie/spaces/{space_id}/conversations per ottenere tutti i thread di conversazione esistenti in uno spazio.
  2. Per ogni ID conversazione restituito, usare l'endpoint per recuperare l'elenco GET /api/2.0/genie/spaces/{space_id}/conversations dei messaggi per tale conversazione.

Procedure consigliate e limiti

Procedure consigliate per l'uso dell'API Genie

Per mantenere le prestazioni e l'affidabilità quando si usa l'API Genie:

  • Implementare la logica di ripetizione dei tentativi con backoff esponenziale: L'API non ritenta le richieste non riuscite, quindi aggiungere il proprio backoff esponenziale e di accodamento. Ciò consente all'applicazione di gestire gli errori temporanei, evitare richieste ripetute non necessarie e rimanere entro i limiti di velocità effettiva man mano che aumenta.
  • Risposte all'API di log: Implementare la registrazione completa delle richieste e delle risposte api per facilitare il debug, il monitoraggio dei modelli di utilizzo e il monitoraggio dei costi.
  • Interrogare per ottenere aggiornamenti dello stato ogni 1 a 5 secondi: Continuare l'interrogazione fino a quando non si riceve un messaggio finale, ad esempio COMPLETED, FAILED o CANCELLED. Limitare il polling a 10 minuti per la maggior parte delle query. Se non è presente alcuna risposta conclusiva dopo 10 minuti, interrompere il polling e restituire un errore di timeout o chiedere all'utente di controllare manualmente lo stato della query in un secondo momento.
  • Usare il backoff esponenziale per il polling: Aumentare il ritardo tra i polling fino a un massimo di un minuto. In questo modo si riducono le richieste non necessarie per le query a esecuzione prolungata, consentendo comunque una bassa latenza per quelle veloci.
  • Avviare una nuova conversazione per ogni sessione: Evitare di riutilizzare i thread di conversazione tra le sessioni, in quanto ciò può ridurre l'accuratezza a causa del riutilizzo imprevisto del contesto.
  • Mantenere i limiti delle conversazioni: Per gestire le conversazioni precedenti e rimanere al di sotto del limite di 10.000 conversazioni:
    1. Usare l'endpoint GET /api/2.0/genie/spaces/{space_id}/conversations per visualizzare tutti i thread di conversazione esistenti in uno spazio.
    2. Identificare le conversazioni che non sono più necessarie, ad esempio conversazioni precedenti o conversazioni di test.
    3. Usare l'endpoint DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id} per rimuovere le conversazioni a livello di codice.
  • Tenere presente il limite dei risultati della query: l'API Genie restituisce un massimo di 5.000 righe per risultato della query. Se l'analisi dei dati richiede più righe, valutare la possibilità di perfezionare la domanda per concentrarsi su un subset specifico di dati o usare filtri per restringere i risultati.

Limite di velocità effettiva

Durante il periodo di anteprima pubblica, i tassi di velocità effettiva per il livello gratuito dell'API Genie sono ottimali e dipendono dalla capacità del sistema. In condizioni normali o con traffico ridotto, l'API limita le richieste a 5 query al minuto per area di lavoro. Durante i periodi di utilizzo di picco, il sistema elabora le richieste in base alla capacità disponibile, con conseguente riduzione della velocità effettiva.

Monitorare lo spazio

Dopo aver configurato l'applicazione, è possibile monitorare domande e risposte nell'interfaccia utente di Databricks.

Incoraggiare gli utenti a testare lo spazio in modo da ottenere informazioni sui tipi di domande che potrebbero porre e sulle risposte ricevute. Fornire agli utenti indicazioni per iniziare a testare lo spazio. Usare la scheda Monitoraggio per visualizzare domande e risposte. Vedi Monitorare lo spazio.

È anche possibile usare i log di controllo per monitorare l'attività in uno spazio Genie. Visualizzare gli eventi AI/BI Genie .

  • Last updated on