Użyj interfejsu API Genie Agents

Zintegruj agentów usługi Genie z własnym czatbotem, agentem lub aplikacją przy użyciu interfejsu API agentów genie. Interfejs API udostępnia interfejsy API trybu czatu do stanowego wykonywania zapytań do danych w języku naturalnym (z pytaniami uzupełniającymi i historią konwersacji) oraz interfejsy API do zarządzania na potrzeby przepływów pracy CI/CD, które umożliwiają tworzenie, konfigurowanie i wdrażanie agentów Genie w przestrzeniach roboczych.

Przegląd

API Genie oferuje następujące rodzaje funkcji:

• API w trybie czatu: Umożliwiają zapytania do danych w języku naturalnym w aplikacjach, chatbotach i frameworkach agentów. Te API wspierają stanowe rozmowy tworzone w trybie czatu, gdzie użytkownicy mogą zadawać pytania uzupełniające i naturalnie eksplorować dane w czasie.
• API trybu agenta: Umożliwiają programowo wysyłanie promptów w trybie agenta, przesyłanie wyników rozumowania i SQL oraz otrzymywanie końcowych raportów z cytowaniami.
• Interfejsy API zarządzania: Umożliwiają programowe tworzenie, konfigurowanie i wdrażanie agentów Genie w różnych obszarach roboczych. Użyj tych interfejsów API do potoków CI/CD, kontroli wersji i zautomatyzowanego zarządzania agentami.

Ta strona wyjaśnia, jak przygotować starannie dobranego agenta Genie i zarządzać agentami w różnych przestrzeniach roboczych, aby API zwracało wiarygodne wyniki. Agent udostępnia kontekst, z którego Genie korzysta do interpretacji pytań i generowania odpowiedzi. Jeśli agent jest niekompletny lub nietestowany, użytkownicy mogą nadal otrzymywać nieprawidłowe wyniki nawet przy prawidłowej integracji interfejsu API. Aby uzyskać informacje o końcowych punktach uruchomieniowych, formatach żądań i formatach odpowiedzi, zobacz odniesienie do API REST powiązane w referencji Genie API.

Przykłady ustawień na tej stronie korzystają bezpośrednio z API REST. Te interfejsy API można również wywoływać przy użyciu zestawów SDK Azure Databricks. Zobacz Databricks SDK.

Wymagania wstępne

Aby korzystać z interfejsu API Genie, musisz mieć następujące elementy:

• Dostęp do obszaru roboczego usługi Azure Databricks przy użyciu uprawnień usługi Databricks SQL.
• Co najmniej MOŻE UŻYWAć uprawnień w usłudze SQL Pro lub bezserwerowej usługi SQL Warehouse.

Rozpoczęcie pracy

Konfigurowanie uwierzytelniania usługi Azure Databricks

W przypadku przypadków użycia w środowisku produkcyjnym, w których użytkownik z dostępem do przeglądarki jest obecny, użyj protokołu OAuth dla użytkowników (OAuth U2M). W sytuacjach, gdy uwierzytelnianie oparte na przeglądarce nie jest możliwe, użyj jednostki usługi do uwierzytelniania za pomocą interfejsu API. Zobacz OAuth dla podmiotów usługi (OAuth M2M). Jednostki usługi muszą mieć uprawnienia dostępu do wymaganych danych i magazynów SQL.

Zbieranie szczegółów

• Nazwa wystąpienia obszaru roboczego: znajdź i skopiuj nazwę wystąpienia obszaru roboczego z adresu URL obszaru roboczego usługi Databricks. Aby uzyskać szczegółowe informacje o identyfikatorach obszarów roboczych w adresie URL, zobacz Pobieranie identyfikatorów obiektów obszaru roboczego.

  Przykład: https://cust-success.cloud.databricks.com/

• Identyfikator magazynu: potrzebujesz identyfikatora usługi SQL Warehouse, dla której masz co najmniej uprawnienia CAN USE. Aby znaleźć identyfikator magazynu:

  1. Przejdź do usługi SQL Warehouse w obszarze roboczym.
  2. Wybierz magazyn, którego chcesz użyć.
  3. Skopiuj identyfikator magazynu z adresu URL lub strony szczegółów magazynu.

  Alternatywnie, użyj punktu końcowego Listy magazynówGET /api/2.0/sql/warehouses aby programistycznie pobrać listę wszystkich magazynów SQL, do których masz prawa dostępu. Odpowiedź zawiera identyfikator magazynu.

Utwórz lub wybierz agenta Genie

Dobrze ustrukturyzowany agent Genie ma następujące cechy:

• Używa dobrze oznaczonych danych: Genie opiera się na metadanych tabeli i komentarzach kolumn. Upewnij się, że źródła danych Unity Catalog mają jasne, opisowe komentarze.
• Czy testowany jest użytkownik: przetestuj agenta, zadając pytania, których oczekujesz od użytkowników końcowych. Użyj testowania, aby utworzyć i uściślić przykładowe zapytania SQL.
• Zawiera kontekst specyficzny dla firmy: dodaj instrukcje, przykładowy SQL i funkcje. Zobacz Dodawanie przykładów i instrukcji SQL. Celem jest co najmniej pięć przetestowanych przykładowych zapytań SQL.
• Używa testów porównawczych do testowania dokładności: dodaj co najmniej pięć pytań porównawczych na podstawie przewidywanych pytań użytkowników. Zobacz Testy porównawcze.

Aby uzyskać więcej informacji na temat tworzenia agenta, zobacz Tworzenie agenta Genie i zarządzanie nim oraz Jak przygotować skutecznego agenta Genie.

Możesz utworzyć nowego agenta Genie lub użyć istniejącego:

Tworzenie nowego agenta

Utwórz agenta Genie programowo za pomocą interfejsu API Create Genie Agent. W poniższym przykładzie pokazano dobrze ustrukturyzowanego agenta, który jest zgodny z najlepszymi rozwiązaniami. Zastąp symbole zastępcze swoimi wartościami.

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

Korzystanie z istniejącego agenta

Jeśli masz już agenta Genie, możesz znaleźć identyfikator miejsca za pomocą interfejsu API List Genie Agents. Identyfikator miejsca można również znaleźć i skopiować na karcie Ustawienia 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>",
    }
  ]
}

Użyj space_id z odpowiedzi w kolejnych wywołaniach interfejsu API.

Zrozumienie pola serialized_space

Pole serialized_space to ciąg JSON, który definiuje konfigurację i źródła danych dla agenta Genie. W żądaniu interfejsu API ten kod JSON musi zostać usunięty jako ciąg. Pole zawiera:

• wersja: numer wersji schematu dla zgodności z poprzednimi wersjami. Użyj polecenia 2 , jak pokazano w poniższym przykładzie.
• konfiguracja: Konfiguracja agenta, w tym:
  • sample_questions: Przykładowe pytania dotyczące kierowania użytkownikami. Każde pytanie wymaga identyfikatora (32-znakowego ciągu szesnastkowego) i pytania (tablicy ciągów).
• data_sources: Źródła danych dostępne dla agenta:
  • tabele: Zbiór obiektów tabeli z identyfikatorem (trzy-poziomową przestrzenią nazw), opcjonalnym opisem i opcjonalnymi konfiguracjami kolumn.
  • metric_views: Tablica obiektów widoku metryki (taka sama struktura jak tabele).
• instrukcje: Ustrukturyzowane instrukcje dla agenta:
  • text_instructions: ogólne wskazówki dotyczące usługi LLM.
  • example_question_sqls: Przykładowe pytania z odpowiedziami SQL, opcjonalnie z parametrami i usage_guidance.
  • sql_functions: odwołania do funkcji SQL dostępnych dla agenta.
  • join_specs: wstępnie zdefiniowane relacje sprzężenia między tabelami. Pole sql wymaga dokładnie dwóch elementów: warunku połączenia, wykorzystując odwołania aliasu w backtick, oraz adnotacji typu relacji, na przykład "--rt=FROM_RELATIONSHIP_TYPE_MANY_TO_ONE--". Zobacz Format specyfikacji sprzężenia.
  • sql_snippets: Filtry, wyrażenia i miary wielokrotnego użytku.
• testy porównawcze: Pytania dotyczące oceny jakości agenta, z których każda ma podstawowe odpowiedzi SQL.

Niezaobsobna wersja serialized_space pola z przykładu tworzenia agenta wygląda następująco:

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

Podczas konstruowania agenta utwórz tę strukturę JSON, a następnie uniknie jej jako ciągu żądania interfejsu API. Szczegółowe informacje o schemacie znajdziesz w dokumencie Create Genie Agent API reference.

Reguły sprawdzania poprawności dla serialized_space

Kod serialized_space JSON musi być zgodny z następującymi regułami walidacji. Kod JSON, który nie jest prawidłowy, jest odrzucany podczas tworzenia lub aktualizowania agenta.

Version

• Pole wersji: wymagane. Użyj 2 dla nowych agentów. Numer wersji istnieje w celu zapewnienia zgodności z poprzednimi wersjami.

Format identyfikatora

Wszystkie pola identyfikatorów muszą być 32-znakowymi ciągami szesnastkowymi pisanymi małymi literami (format UUID bez łączników).

• Prawidłowe: a1b2c3d4e5f60000000000000000000a
• Nieprawidłowa: a1b2c3d4e5f6 (zbyt krótka), A1B2C3D4E5F60000000000000000000A (wielkie litery), a1b2c3d4-e5f6-0000-0000-00000000000a (zawiera łączniki)

Identyfikatory są wymagane dla:

• 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 (jeśli są uwzględnione testy porównawcze)

Aby wygenerować prawidłowy identyfikator, możesz użyć następującego polecenia:

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

Spowoduje to wygenerowanie identyfikatora UUID uporządkowanego czasowo. Identyfikatory generowane sekwencyjnie są sortowane alfabetycznie według kolejności ich tworzenia, co automatycznie spełnia wymagania dotyczące sortowania.

Wymagania dotyczące sortowania

Kolekcje zawierające identyfikatory muszą być wstępnie posortowane. System sprawdza, czy tablice są już sortowane i odrzuca niesortowane dane wejściowe.

Ograniczenia unikatowości

• Identyfikatory pytań: Wszystkie identyfikatory w config.sample_questions i benchmarks.questions muszą być unikatowe w obu zbiorach.
• Identyfikatory instrukcji: Wszystkie identyfikatory we wszystkich text_instructions, example_question_sqls, sql_functions, join_specs oraz we wszystkich typach sql_snippets muszą być unikatowe.
• Konfiguracje kolumn: Kombinacja (table_identifier, column_name) musi być unikalna w obrębie agenta.

Limity rozmiaru i długości

• Długość ciągu: Pojedyncze elementy ciągu są ograniczone do 25 000 znaków.
• Rozmiar tablicy: Powtarzające się pola są ograniczone do 10 000 elementów.
• Instrukcje tekstowe: Na agenta dozwolona jest co najwyżej 1 instrukcja tekstowa.
• Tabele i widoki metryk: Podlega limitom specyficznym dla obszaru roboczego.
• Zawartość SQL: tekst zapytania w sql polach i join_specs.sql podlega limitom długości.

Format specyfikacji sprzężenia

Pole sql w każdej specyfikacji sprzężenia musi zawierać dokładnie dwa elementy:

1. Warunek sprzężenia, używając odwołań aliasu cytowanego za pomocą backtick:

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

2. Adnotacja typu relacji w następującym formacie:

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

   Prawidłowe wartości kardynalności:

   • FROM_RELATIONSHIP_TYPE_MANY_TO_ONE
   • FROM_RELATIONSHIP_TYPE_ONE_TO_MANY
   • FROM_RELATIONSHIP_TYPE_ONE_TO_ONE
   • FROM_RELATIONSHIP_TYPE_MANY_TO_MANY

Pominięcie adnotacji typu relacji powoduje odrzucenie żądania przez interfejs API z błędem analizy. W przypadku sprzężeń wielokolumnowych utwórz oddzielną specyfikację sprzężenia dla każdej relacji.

Inne wymagania

• Identyfikatory tabel: musi używać formatu przestrzeni nazw na poziomie trzech poziomów (catalog.schema.table).
• Odpowiedzi na testy porównawcze: każde pytanie porównawcze musi mieć dokładnie jedną odpowiedź z formatem ustawionym na sql.
• Fragmenty kodu SQL: pola filtru, wyrażenia i miary SQL nie mogą być puste.

Referencja API Genie

Powyższe sekcje pokazują, jak przygotować agenta Genie i zarządzać agentami w różnych przestrzeniach roboczych. Aby rozpocząć rozmowy, wysyłać wiadomości i pobierać wyniki z Genie Agents, zobacz odniesienie do API REST:

• API w trybie Agent: Wysyłają prompty w trybie Agent, przesyłają wnioski i wyniki SQL oraz otrzymują końcowe raporty z cytowaniami. Zobacz odniesienie do API trybu agenta.
• API do trybu czatu: rozpocznij rozmowę w trybie czatu, zadawaj pytania uzupełniające i pobieraj wygenerowane SQL, wyniki zapytań oraz wizualizacje. Zobacz dokumentację interfejsu Conversation API.

Najlepsze rozwiązania i limity

Najlepsze rozwiązania dotyczące korzystania z interfejsu API Genie

Aby zachować wydajność i niezawodność podczas korzystania z interfejsu API Genie:

• Zaimplementuj logikę ponawiania przy użyciu odstępów wykładniczych: API nie ponawia nieudanych żądań, więc dodaj własne kolejkowanie i odstępy wykładnicze. Pomaga to aplikacji obsługiwać błędy przejściowe i unikać niepotrzebnych powtarzających się żądań w miarę wzrostu.
• Dziennikowanie odpowiedzi API: zaimplementuj kompleksowe rejestrowanie żądań i odpowiedzi API, aby ułatwić debugowanie, monitorowanie wzorców użycia i śledzenie kosztów.
• Sonduj aktualizacje stanu co 1 do 5 sekund: kontynuuj sondowanie do momentu odebrania jednoznacznego stanu komunikatu, takiego jak COMPLETED, FAILEDlub CANCELLED. Ogranicz sondowanie do 10 minut dla większości zapytań. Jeśli nie ma jednoznacznej odpowiedzi po 10 minutach, zatrzymaj sondowanie i zwróć błąd przekroczenia limitu czasu lub monituj użytkownika o ręczne sprawdzenie stanu zapytania później.
• Użyj wycofywania wykładniczego na potrzeby sondowania: zwiększ opóźnienie między sondami do maksymalnie jednej minuty. Zmniejsza to niepotrzebne żądania dla długotrwałych zapytań, jednocześnie pozwalając na małe opóźnienia dla szybkich.
• Rozpocznij nową konwersację dla każdej sesji: unikaj ponownego używania wątków konwersacji między sesjami, ponieważ może to zmniejszyć dokładność z powodu niezamierzonego ponownego użycia kontekstu.
• Utrzymuj limit rozmów: Aby zarządzać starymi rozmowami i nie przekraczać limitu 200 000:
  1. Użyj punktu końcowego GET /api/2.0/genie/spaces/{space_id}/conversations , aby wyświetlić wszystkie istniejące wątki konwersacji w agencie.
  2. Zidentyfikuj konwersacje, które nie są już potrzebne, takie jak starsze konwersacje lub przetestuj konwersacje.
  3. Użyj punktu końcowego DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id} , aby programowo usunąć konwersacje.

Monitorowanie agenta

Po skonfigurowaniu aplikacji możesz monitorować pytania i odpowiedzi w interfejsie użytkownika usługi Databricks.

Zachęcaj użytkowników do testowania agenta, aby dowiedzieć się więcej o typach pytań, które mogą zadawać i otrzymywać odpowiedzi. Udostępnij użytkownikom wskazówki ułatwiające im rozpoczęcie testowania agenta. Użyj karty Monitorowanie , aby wyświetlić pytania i odpowiedzi. Zobacz Monitorowanie agenta.

Możesz również używać dzienników audytu do monitorowania aktywności w agencie Genie. Zobacz Zdarzenia agenta Genie.