Použití rozhraní Genie API k integraci Genie do vašich aplikací

Tato stránka vysvětluje, jak pomocí rozhraní API Genie povolit funkce Genie ve vašem vlastním chatovacím robotovi, agentovi nebo aplikaci.

Přehled

Rozhraní API Genie poskytuje dva typy funkcí:

Rozhraní API pro konverzaci (Public Preview): Povolení dotazování dat v přirozeném jazyce v aplikacích, chatovacích robotech a architekturách agentů AI Tato rozhraní API podporují stavové konverzace, ve kterých můžou uživatelé klást následné otázky a zkoumat data přirozeně v průběhu času.
Rozhraní API pro správu: Umožňuje programové vytváření, konfiguraci a nasazování prostorů Genie napříč pracovními prostory. Tato rozhraní API můžete použít pro kanály CI/CD, správu verzí a automatizovanou správu prostoru.

Tato stránka popisuje rozhraní API pro konverzaci i správu. Před voláním rozhraní API konverzace si připravte dobře upravený prostor "Genie". Prostor poskytuje kontext, který Genie používá k interpretaci otázek a generování odpovědí. Pokud je prostor neúplný nebo neotestovaný, uživatelé můžou stále obdržet nesprávné výsledky i se správnou integrací rozhraní API. Tato příručka vysvětluje minimální nastavení potřebné k vytvoření prostoru, který efektivně funguje s rozhraním Genie API.

Požadavky

Pokud chcete použít rozhraní API Genie, musíte mít:

Přístup k pracovnímu prostoru Azure Databricks s oprávněním Databricks SQL.
Alespoň MŮŽE POUŽÍVAT oprávnění k SQL Pro nebo bezserverové službě SQL Warehouse.

Začínáme

Konfigurace ověřování Azure Databricks

V produkčních případech použití, kdy je k dispozici uživatel s přístupem k prohlížeči, použijte OAuth pro uživatele (OAuth U2M). V situacích, kdy není možné autentizovat na základě prohlížeče, použijte služební účet k autentizaci prostřednictvím API. Viz OAuth pro služební účty (OAuth M2M). Instanční objekty musí mít oprávnění pro přístup k požadovaným datům a skladům SQL.

Shromáždění podrobností

Název instance pracovního prostoru: Vyhledejte a zkopírujte název instance pracovního prostoru z adresy URL pracovního prostoru Databricks. Podrobnosti o identifikátorech pracovního prostoru v adrese URL najdete v tématu Získání identifikátorů pro objekty pracovního prostoru.

Příklad: https://cust-success.cloud.databricks.com/
ID skladu: Potřebujete ID SQL skladu, ke kterému máte alespoň oprávnění POUŽÍVAT. Vyhledání ID skladu:
1. Ve svém pracovním prostoru přejděte do služby SQL Warehouse .
2. Vyberte sklad, který chcete použít.
3. Zkopírujte ID skladu z adresy URL nebo stránky s podrobnostmi o skladu.
Případně můžete použít List warehouses endpointGET /api/2.0/sql/warehouses pro programové načtení seznamu všech SQL skladů, ke kterým máte přístupová práva. Odpověď obsahuje ID skladu.

Vytvořte nebo vyberte prostor Genie

Dobře strukturovaný prostor Genie má následující charakteristiky:

Používá dobře anotovaná data: Genie spoléhá na metadata tabulky a komentáře sloupců. Ověřte, že zdroje dat katalogu Unity mají jasné a popisné komentáře.
Testuje se uživatel: Otestujte prostor kladením otázek, které očekáváte od koncových uživatelů. Pomocí testování můžete vytvářet a upřesňovat ukázkové dotazy SQL.
Zahrnuje kontext specifický pro společnost: Přidejte pokyny, například SQL a funkce. Viz Přidání příkladů a pokynů k SQL. Snažte se alespoň o pět testovaných ukázkových dotazů SQL.
Používá srovnávací testy k testování přesnosti: Přidejte alespoň pět otázek srovnávacích testů na základě očekávaných uživatelských otázek. Viz Použití srovnávacích testů v prostoru Genie.

Další informace o vytvoření prostoru najdete v tématu Nastavení a správa prostoru Genie a Curate efektivního prostoru Genie.

Můžete buď vytvořit nový prostor Genie, nebo použít existující prostor:

Vytvoření nového prostoru

Programově vytvořte prostor Genie pomocí rozhraní API pro vytvoření prostoru Genie. Následující příklad ukazuje dobře strukturovaný prostor, který dodržuje osvědčené postupy. Zástupné symboly nahraďte hodnotami:

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

Použití existujícího prostoru

Pokud už prostor Genie máte, můžete ID prostoru najít pomocí rozhraní API List Genie Spaces. ID místa najdete a zkopírujete také na kartě Nastavení prostoru Genie.

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

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

Použijte space_id z odpovědi v následných voláních rozhraní API.

Pochopení pole serializovaný_prostor

Pole serialized_space je řetězec JSON, který definuje konfiguraci a zdroje dat pro prostor Genie. V požadavku rozhraní API musí být tento json uchvácený jako řetězec. Pole obsahuje:

verze: Číslo verze schématu pro zpětnou kompatibilitu. Použijte 2 , jak je znázorněno v následujícím příkladu.
konfigurace: Konfigurace prostoru, včetně:
- sample_questions: Ukázkové otázky pro vedení uživatelů Každá otázka vyžaduje ID (šestnáctkový řetězec 32 znaků) a otázku (pole řetězců).
data_sources: Zdroje dat dostupné pro prostor:
- tabulky: Pole objektů tabulky s identifikátorem (tříúrovňový obor názvů), volitelným popisem a volitelnými konfiguracemi_sloupců.
- metric_views: Pole objektů zobrazení metrik (stejná struktura jako tabulky).
pokyny: Strukturované pokyny pro prostor:
- text_instructions: Obecné pokyny pro LLM.
- example_question_sqls: Ukázkové otázky s odpověďmi SQL, volitelně s parametry a usage_guidance
- sql_functions: Odkazy na funkce SQL dostupné v prostoru.
- join_specs: Předdefinované relace spojení mezi tabulkami
- sql_snippets: Opakovaně použitelné filtry, výrazy a míry.
srovnávací testy: Otázky týkající se vyhodnocení kvality prostoru, z nichž každá má základní odpověď SQL.

Neupravená verze pole serialized_space z příkladu vytvoření prostoru vypadá takto:

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

Při vytváření vašeho prostoru vytvořte tuto strukturu JSON a poté ji převeďte na řetězec pro požadavek API. Úplné podrobnosti schématu najdete v referenčních informacích k rozhraní API pro vytvoření prostoru Genie.

Ověřovací pravidla pro serialized_space

JSON serialized_space musí odpovídat následujícím ověřovacím pravidlům. Json, který není platný, se při vytváření nebo aktualizaci prostoru odmítne.

Version

Verze pole: Povinné. Použijte 2 pro nové mezery. Číslo verze existuje pro zpětnou kompatibilitu.

Formát ID

Všechna pole ID musí mít 32mísícové šestnáctkové řetězce (formát UUID bez pomlček).

Platné: a1b2c3d4e5f60000000000000000000a
Neplatné: a1b2c3d4e5f6 (příliš krátké), A1B2C3D4E5F60000000000000000000A (velké) a1b2c3d4-e5f6-0000-0000-00000000000a (obsahuje pomlčky)

ID jsou vyžadována pro:

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 (pokud jsou zahrnuty srovnávací testy)

K vygenerování platného ID můžete použít následující příkaz:

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

Tím se vygeneruje identifikátor UUID seřazený podle času. ID vygenerované v sekvenčním pořadí jsou automaticky řazeny abecedně podle pořadí jejich vytvoření, což splňuje požadavky na řazení automaticky.

Požadavky na řazení

Kolekce obsahující ID nebo identifikátory musí být předem seřazené. Systém ověří, že pole jsou již seřazená a odmítne neseřazené vstupy.

Collection	Klíč třídění
`data_sources.tables`	`identifier` (abecedně)
`data_sources.metric_views`	`identifier` (abecedně)
`data_sources.tables[].column_configs`	`column_name` (abecedně)
`data_sources.metric_views[].column_configs`	`column_name` (abecedně)
`config.sample_questions`	`id` (abecedně)
`instructions.text_instructions`	`id` (abecedně)
`instructions.example_question_sqls`	`id` (abecedně)
`instructions.sql_functions`	`(id, identifier)` n-tice (abecedně)
`instructions.join_specs`	`id` (abecedně)
`instructions.sql_snippets.filters`	`id` (abecedně)
`instructions.sql_snippets.expressions`	`id` (abecedně)
`instructions.sql_snippets.measures`	`id` (abecedně)
`benchmarks.questions`	`id` (abecedně)

Omezení jedinečnosti

ID otázek: Všechna ID v config.sample_questions a benchmarks.questions musí být jedinečná v obou kolekcích.
Identifikátory instrukcí: Všechna ID v rámci text_instructions, example_question_sqls, sql_functions, join_specs a všechny typy sql_snippets musí být jedinečné.
Konfigurace sloupců: Kombinace (table_identifier, column_name) musí být v prostoru jedinečná.

Omezení velikosti a délky

Délka řetězce: Jednotlivé prvky řetězce jsou omezeny na 25 000 znaků.
Velikost pole: Opakovaná pole jsou omezená na 10 000 položek.
Textové pokyny: Pro každou mezeru je povolena maximálně 1 textová instrukce.
Tabulky a zobrazení metrik: V závislosti na omezeních specifických pro pracovní prostor.
Obsah SQL: Dotazování textu v sql polích join_specs.sql podléhá omezením délky.

Další požadavky

Identifikátory tabulky: Musí používat tříúrovňový formát oboru názvů (catalog.schema.table).
Odpovědi na srovnávací testy: Každá otázka srovnávacího testu musí mít přesně jednu odpověď s formátem nastaveným na SQL.
Fragmenty kódu SQL: Pole Filtru, výrazu a míry SQL nesmí být prázdná.

Použití rozhraní API pro konverzaci

Po konfiguraci prostoru Genie využijte endpointy rozhraní API konverzace k kladení otázek, výsledků načítání a udržování vícekrokové konverzace s kontextem.

Zahájení konverzace

Koncový bod Zahájit konverzaciPOST /api/2.0/genie/spaces/{space_id}/start-conversation zahájí novou konverzaci v prostoru Genie.

Zástupné symboly nahraďte vaší instancí Databricks, ID prostoru Genie a ověřovacím tokenem. Příklad úspěšné odpovědi následuje po požadavku. Obsahuje podrobnosti, které můžete použít k dalšímu přístupu k této konverzaci pro následné otázky.

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

Načti vygenerované SQL

Pomocí conversation_id a message_id v rámci odpovědi na dotaz zkontrolujte stav generování zprávy a získejte vygenerovaný SQL z Genie. Podívejte se GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id} na úplné podrobnosti žádosti a odpovědi.

Poznámka:

Do POST za minutu se započítávají jenom požadavky. GET Na žádosti použité k získání výsledků se toto omezení nevztahuje.

Dosad’te své hodnoty do následujícího požadavku:

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

Následující příklad odpovědi hlásí podrobnosti zprávy:

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
}

Když je pole status naplněno, je odpověď umístěna v poli COMPLETED.

Načtení výsledků dotazu

Pole attachments obsahuje odpověď Genie. Obsahuje vygenerovanou textovou odpověď (text), příkaz dotazu, pokud existuje (query) a identifikátor, který můžete použít k získání přidružených výsledků dotazu (attachment_id). Nahraďte zástupné symboly v následujícím příkladu, abyste získali vygenerované výsledky dotazu:

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

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

Pokládání následných otázek

Jakmile obdržíte odpověď, použijte conversation_id k pokračování v konverzaci. Kontext z předchozích zpráv se uchovává a používá v následných odpovědích. Úplné podrobnosti o požadavku a odpovědi viz 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?",
}

Získání dat z prostoru a konverzace

Rozhraní Api Genie poskytuje další koncové body pro načítání konfiguračních a historických dat z existujících prostorů a konverzací.

Načtení konfigurace prostoru

Při načítání informací o prostoru pomocí rozhraní Get Genie Space API můžete do odpovědi zahrnout serialized_space pole nastavením parametru include_serialized_space na true. Pole serialized_space obsahuje serializovanou řetězcovou reprezentaci prostoru Genie, včetně pokynů, srovnávacích testů, spojení a dalších podrobností konfigurace.

Tuto serializovanou reprezentaci použijte s rozhraním Create Genie Space API a rozhraním Update Genie Space API k propagaci prostorů Genie napříč pracovními prostory nebo vytváření záloh konfigurací prostoru.

Příklad GET požadavku:

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

Odkaz na stará vlákna konverzace

Pokud chcete uživatelům umožnit odkazovat na stará vlákna konverzací, použijte koncový bodGET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages Seznam zpráv konverzace k načtení všech zpráv z konkrétního vlákna konverzace.

Načtení dat konverzace pro analýzu

Správci prostoru můžou programově načíst všechny předchozí zprávy napříč všemi uživateli daného prostoru za účelem analýzy. Ke získání těchto dat:

Pomocí koncového GET /api/2.0/genie/spaces/{space_id}/conversations bodu získáte všechna existující vlákna konverzace v prostoru.
Pro vrácené ID každé konverzace použijte GET /api/2.0/genie/spaces/{space_id}/conversations koncový bod k načtení seznamu zpráv pro danou konverzaci.

Osvědčené postupy a omezení

Osvědčené postupy pro používání rozhraní Genie API

Zachování výkonu a spolehlivosti při používání rozhraní Genie API:

Implementujte logiku opakování požadavků s exponenciálním backoffem: Rozhraní API za vás neopakuje neúspěšné požadavky, proto přidejte vlastní systém front a exponenciálního zpomalení. To pomáhá vaší aplikaci zpracovávat přechodné chyby, vyhnout se zbytečným opakovaným požadavkům a zůstat v mezích limitů propustnosti při růstu.
Zalogujte odpovědi API: Implementujte komplexní logování požadavků a odpovědí API, které vám pomůžou s laděním, monitorováním vzorců používání a sledováním nákladů.
Dotazování na aktualizace stavu každých 1 až 5 sekund. Pokračujte v dotazování, dokud nebude přijat konečný stav zprávy, například COMPLETED, FAILED nebo CANCELLED. U většiny dotazů omezte dotazování na 10 minut. Pokud po 10 minutách neexistuje žádná definitivní odpověď, zastavte dotazování a vraťte chybu časového limitu nebo vyzvěte uživatele, aby později ručně zkontroloval stav dotazu.
Pro dotazování použijte exponenciální zpoždění: Zvětšete zpoždění mezi dotazy až na maximální dobu jedné minuty. Tím se sníží nepotřebné požadavky na dlouho běžící dotazy a zároveň umožňují nízkou latenci pro rychlé dotazy.
Zahájení nové konverzace pro každou relaci: Vyhněte se opakovanému použití vláken konverzací napříč relacemi, protože to může snížit přesnost kvůli neúmyslnému opakovanému použití kontextu.
Zachovat limity konverzací: Pokud chcete spravovat staré konverzace a zůstat pod limitem 10 000 konverzací:
1. Pomocí koncového GET /api/2.0/genie/spaces/{space_id}/conversations bodu můžete zobrazit všechna existující vlákna konverzace v prostoru.
2. Identifikujte konverzace, které už nepotřebujete, například starší konverzace nebo testovací konverzace.
3. Pomocí koncového DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id} bodu můžete konverzace odebírat programově.
Mějte na paměti limit výsledků dotazu: Rozhraní API Genie vrátí maximálně 5 000 řádků na výsledek dotazu. Pokud analýza dat vyžaduje více řádků, zvažte upřesnění otázky, abyste se zaměřili na konkrétní podmnožinu dat, nebo použijte filtry k zúžení výsledků.

Limit propustnosti

Během období veřejného náhledu jsou rychlosti přenosu bezplatné úrovně rozhraní API pro konverzaci Genie určovány podle aktuálních možností systému. Za normálních nebo nízkých provozních podmínek omezuje rozhraní API požadavky na 5 otázek za minutu na pracovní prostor. Během období špičky systém zpracovává požadavky na základě dostupné kapacity, což může vést k nižší propustnosti. Limity úrovně Free jsou zavedeny, aby se zabránilo zneužití. Pokud chcete rozšířit stávající kapacitu, obraťte se na tým účtu Databricks.

Monitorování prostoru

Po nastavení aplikace můžete monitorovat otázky a odpovědi v uživatelském rozhraní Databricks.

Povzbuďte uživatele, aby otestovali prostor, abyste se dozvěděli o typech otázek, které budou pravděpodobně klást, a odpovědích, které obdrží. Poskytněte uživatelům pokyny , které jim pomůžou začít testovat prostor. Pomocí karty Monitorování můžete zobrazit otázky a odpovědi. Viz Monitorování prostoru.

Protokoly auditu můžete použít také k monitorování aktivity v prostoru Genie. Podívejte se na události Genie.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-03-11