Použijte rozhraní API agentů Genie

Integrujte agenty Genie do vlastního chatovacího robota, agenta nebo aplikace s rozhraním API Genie Agents. API poskytuje konverzační API pro stavové dotazování nad daty v přirozeném jazyce (s navazujícími dotazy a historií) a API pro správu pro pracovní postupy CI/CD, které vytvářejí, konfigurují a nasazují agenty Genie v různých pracovních prostorech.

Poznámka:

Agenti Genie byli dříve označováni jako Genie Spaces.

Přehled

Rozhraní API Genie poskytuje dva typy funkcí:

  • Rozhraní API pro konverzaci: Povolení dotazování dat přirozeného jazyka 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: Povolení programového vytváření, konfigurace a nasazení agentů Genie napříč pracovními prostory Tato rozhraní API použijte pro kanály CI/CD, správu verzí a automatizovanou správu agentů.

Tato stránka popisuje rozhraní API pro konverzaci i správu. Před voláním rozhraní API pro konverzace připravte pečlivě připraveného agenta Genie. Agent poskytuje kontext, který Genie používá k interpretaci otázek a generování odpovědí. Pokud je agent 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í agenta, který efektivně funguje s rozhraním Genie API.

Příklady na této stránce používají přímo rozhraní REST API. Tato rozhraní API lze také volat pomocí SDK pro Azure Databricks. Podívejte se na Databricks SDK.

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ření nebo výběr agenta Genie

Dobře strukturovaná agentka 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 agenta 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řidání pokynů, příklad SQL a funkcí. 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 Srovnávací testy.

Další informace o vytvoření agenta najdete v tématu Vytvoření a správa agenta Genie a kurátorování efektivního agenta Genie.

Můžete buď vytvořit nového agenta Genie, nebo použít existující agenta:

Vytvoření nového agenta

Programově vytvořte agenta Genie pomocí rozhraní API pro vytvoření agenta Genie. Následující příklad ukazuje dobře strukturovaného agenta, 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 agenta

Pokud už máte agenta Genie, můžete ID prostoru zjistit pomocí API List Genie Agents. ID místa můžete najít a zkopírovat také na kartě Nastavení agenta 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 vašeho agenta 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 agenta, 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é agentům:
    • 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 agenta:
    • 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é pro agenta.
    • join_specs: Předdefinované relace spojení mezi tabulkami Pole sql vyžaduje přesně dva prvky: podmínku spojení, použití odkazů na aliasy uzavřené v backticku, a anotaci typu vazby, například "--rt=FROM_RELATIONSHIP_TYPE_MANY_TO_ONE--". Viz formát specifikace spojení.
    • sql_snippets: Opakovaně použitelné filtry, výrazy a míry.
  • benchmarky: Otázky pro hodnocení kvality agenta, každá s referenčně správnou SQL odpovědí.

Verze pole serialized_space z příkladu vytvoření agenta bez escapování 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`", "--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"]
          }
        ]
      }
    ]
  }
}

Při vytváření agenta vytvořte tuto strukturu JSON a poté ji escapujte jako řetězec pro požadavek API. Úplné podrobnosti schématu najdete v referenčních informacích k rozhraní API pro vytvoření agenta 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 agenta odmítne.

Version

  • Verze pole: Povinné. Použijte 2 pro nové agenty. Čí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 rámci agenta 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 agenta 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.

Formát specifikací připojení

Pole sql v každé specifikaci spojení musí obsahovat přesně dva prvky:

  1. Podmínka spojení s využitím aliasů uzavřených v opačných uvozovkách:

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

  2. Poznámka k typu relace v následujícím formátu:

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

    Platné hodnoty kardinality:

    • FROM_RELATIONSHIP_TYPE_MANY_TO_ONE
    • FROM_RELATIONSHIP_TYPE_ONE_TO_MANY
    • FROM_RELATIONSHIP_TYPE_ONE_TO_ONE
    • FROM_RELATIONSHIP_TYPE_MANY_TO_MANY

Vynechání poznámek typu relace způsobí, že rozhraní API odmítne požadavek s chybou analýzy. Pro spojení s více sloupci vytvořte pro každou relaci samostatnou specifikaci spojení.

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 nakonfigurování agenta Genie můžete pomocí koncových bodů rozhraní API pro konverzace klást otázky, získávat výsledky a vést vícekolové konverzace s kontextem.

Zahájení konverzace

Koncový bod POST /api/2.0/genie/spaces/{space_id}/start-conversation zahájí novou konverzaci ve vašem agentu Genie.

Zástupné symboly nahraďte vaší instancí Databricks, ID agenta 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.

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
}

Pole attachments se během zpracování postupně naplní. Pokud je stav PENDING_WAREHOUSE nebo EXECUTING_QUERY, už můžete začít číst pole attachments. Odpověď se naplní přírůstkově, počínaje vygenerovaným dotazem SQL, za kterým následuje popis, následné otázky a další kontext. Stav COMPLETED označuje, že proces odpovědi je plně dokončený a dotazování může zastavit, ale smysluplný obsah je k dispozici dříve, pokud klient zkontroluje odpověď během dotazování a nečeká na dokončení.

Pokud chcete zjistit, jestli byla odpověď vygenerována pomocí důvěryhodného prostředku, zkontrolujte attachments pole v odpovědi pro query.parameters objekt. Jeho přítomnost naznačuje, že odpověď pochází z důvěryhodného zdroje.

Pokud chcete získat přístup ke sledům odůvodnění Genie, zkontrolujte attachments pole zda obsahuje objekt typu query_attachments. Pokud je k dispozici, obsahuje podrobné odůvodnění Genie použité k vygenerování odpovědi. Úplné podrobnosti o polích najdete v referenčních informacích k rozhraní API pro získání zpráv.

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:

Poznámka:

Na rozdíl od uživatelského rozhraní Genie Agents rozhraní API pro konverzaci Genie nepodporuje vzor dvoufázové odpovědi, kde Genie zobrazuje předběžnou odpověď a po kontrole ji aktualizuje. Chcete-li uživatelům zobrazit průběžný postup, kontrolujte pole attachments při dotazování ve stavech PENDING_WAREHOUSE nebo EXECUTING_QUERY namísto čekání na COMPLETED.

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.

Načtení výsledků vizualizace (beta verze)

Ve výchozím nastavení vrátí rozhraní API pro konverzaci Genie výsledky tabulkových dotazů. Pokud chcete také načíst výsledky vizualizace, nastavte enable_visualization: true při zahájení konverzace nebo vytvoření zprávy. Je-li povoleno, pole attachments v odpovědi obsahuje objekt viz typu GenieVizAttachment, který obsahuje vizualizaci title a query_attachment_id, ze kterého byla vygenerována.

Pokud chcete stáhnout vizualizaci, použijte koncový bod vizualizace přílohy zprávy ke stažení:

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

Viz referenční informace k rozhraní Api Genie.

Poznámka:

Výsledky vizualizace nejsou podporovány u pracovních prostorů Private Link.

Poznámka:

Výsledky vizualizace se nepodporují v následujících Azure oblastech:

  • USA – východ​
  • USA – východ 2
  • Švýcarsko – sever
  • Německo – středozápad
  • Severní Evropa
  • Katar – střed

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

Přidání komentářů ke zprávám

Do zpráv můžete přidat textové komentáře a vypsat existující komentáře pomocí koncových bodů rozhraní API pro komentář zpráv.

Pokud chcete do zprávy přidat komentář, použijte koncový bod pro vytvoření komentáře ke zprávěPOST /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>
{
  "content": "<your comment text>"
}

Pokud chcete vypsat existující komentáře ke zprávě, použijte koncový bod Výpis komentářů zpráv.

Načtěte data agenta a data o konverzacích

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

Načíst konfiguraci agenta

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

Tuto serializovanou reprezentaci použijte s rozhraním API pro vytvoření agenta Genie a rozhraním API agenta Update Genie k propagaci agentů Genie napříč pracovními prostory nebo vytvoření záloh konfigurací agenta.

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 agentů mohou programově načítat všechny předchozí zprávy položené všemi uživateli agenta pro účely analýzy. Ke získání těchto dat:

  1. Pomocí koncového GET /api/2.0/genie/spaces/{space_id}/conversations bodu získáte všechna existující vlákna konverzace v agentu.
    • Ve výchozím nastavení tento endpoint vrací pouze konverzace požadujícího uživatele. Chcete-li vrátit konverzace od všech uživatelů agenta, nastavte include_all parametr na true. Použití include_all vyžaduje alespoň oprávnění CAN MANAGE pro agenta.
  2. 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í s exponenciálním zpomalováním: Rozhraní API za vás neopakuje neúspěšné požadavky, takže přidejte vlastní fronty a exponenciální zpomalování. To pomáhá vaší aplikaci zpracovávat přechodné selhání a vyhnout se zbytečným opakovaným požadavkům při růstu.
  • Odpovědi rozhraní LOG API: Implementujte komplexní protokolování požadavků rozhraní API a odpovědí, které vám pomůžou s laděním, monitorováním vzorů využití a sledováním nákladů.
  • Dotazování na stav se aktualizuje každou 1 až 5 vteřin: Pokračujte v dotazování, dokud se neobdrží jednoznač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í zpomalování: Zvětšete zpoždění mezi hlasováními o maximálně jednu minutu. Tím se sníží nepotřebné požadavky na dlouho běžící dotazy a zároveň umožňují nízkou latenci pro rychlé dotazy.
  • Zahajte novou konverzaci pro každou relaci: Vyhněte se opakovanému použití vláken konverzace 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 agentu.
    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ě.

Monitorujte agenta

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

Povzbuďte uživatele k otestování agenta, 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 agenta. Pomocí karty Monitorování můžete zobrazit otázky a odpovědi. Viz Monitorujte agenta.

Protokoly auditu můžete použít také k monitorování aktivity v agentu Genie. Viz události agenta Genie.

  • Last updated on