Verwenden der Genie Agents-API

Integrieren Sie Genie Agents in Ihren eigenen Chatbot, Agent oder Ihre Anwendung mit der Genie Agents-API. Die API bietet Chat-APIs für zustandsbehaftete natürliche Sprachdatenabfragen (mit Folgefragen und Historie) sowie Management-APIs für CI/CD-Workflows, die Genie Agents über Arbeitsbereiche hinweg erstellen, konfigurieren und bereitstellen.

Übersicht

Die Genie API bietet folgende Arten von Funktionen:

• Chatmodus-APIs: Ermöglichen die Abfrage natürlicher Sprachdaten in Anwendungen, Chatbots und Agenten-Frameworks. Diese APIs unterstützen zustandsbehaftete Konversationen, die im Chat-Modus erstellt werden, in denen Nutzer Folgefragen stellen und Daten im Laufe der Zeit auf natürliche Weise erkunden können.
• APIs im Agentenmodus: Ermöglichen es Entwicklern, programmatisch Prompts im Agentenmodus zu senden, die Argumentations- und SQL-Ergebnisse zu streamen und Abschlussberichte mit Zitaten zu erhalten.
• Verwaltungs-APIs: Aktivieren Sie die programmgesteuerte Erstellung, Konfiguration und Bereitstellung von Genie Agents über Arbeitsbereiche hinweg. Verwenden Sie diese APIs für CI/CD-Pipelines, Versionssteuerung und automatisierte Agentverwaltung.

Diese Seite erklärt, wie man einen gut kuratierten Genie-Agent vorbereitet und Agenten über Arbeitsbereiche hinweg verwaltet, damit die API zuverlässige Ergebnisse liefert. Der Agent stellt den Kontext bereit, den Genie verwendet, um Fragen zu interpretieren und Antworten zu generieren. Wenn der Agent unvollständig oder ungetestet ist, erhalten Benutzer möglicherweise auch bei einer korrekten API-Integration immer noch falsche Ergebnisse. Für die Laufzeit-Endpunkte, Anfrageformate und Antwortformate siehe die REST-API-Referenz, die in Genie API-Referenz verlinkt ist.

Die Setup-Beispiele auf dieser Seite verwenden direkt die REST-API. Sie können diese APIs auch mithilfe der Azure Databricks SDKs aufrufen. Siehe Databricks-SDKs.

Voraussetzungen

Um die Genie-API zu verwenden, müssen Sie folgendes haben:

• Zugriff auf einen Azure Databricks-Arbeitsbereich mit der Berechtigung "Databricks SQL".
• Mindestens CAN USE-Berechtigungen auf einem SQL pro oder serverlosen SQL Warehouse.

Erste Schritte

Konfigurieren der Azure Databricks-Authentifizierung

Verwenden Sie für Produktionsanwendungsfälle, in denen ein Benutzer mit Zugriff auf einen Browser vorhanden ist, OAuth für Benutzer (OAuth U2M). In Situationen, in denen die browserbasierte Authentifizierung nicht möglich ist, verwenden Sie ein Dienstprinzipal-Objekt, um sich mit der API zu authentifizieren. Siehe OAuth für Dienstprinzipale (OAuth M2M). Dienstprinzipale müssen über Berechtigungen für den Zugriff auf die erforderlichen Daten und SQL-Warehouses verfügen.

Sammeln von Details

• Name der Arbeitsbereichsinstanz: Suchen Sie und kopieren Sie den Arbeitsbereichsinstanznamen aus der Databricks-Arbeitsbereichs-URL. Ausführliche Informationen zu den Arbeitsbereichsbezeichnern in Ihrer URL finden Sie unter Abrufen von Bezeichnern für Arbeitsbereichsobjekte.

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

• Warehouse-ID: Sie benötigen die ID eines SQL-Warehouses, für das Sie mindestens über CAN USE-Berechtigungen verfügen. So finden Sie Ihre Lager-ID:

  1. Wechseln Sie zu SQL Warehouses in Ihrem Arbeitsbereich.
  2. Wählen Sie das Lager aus, das Sie verwenden möchten.
  3. Kopieren Sie die Lager-ID aus der URL oder der Seite mit den Lagerdetails.

  Alternativ können Sie den Endpunkt "List warehouses"GET /api/2.0/sql/warehouses verwenden, um programmgesteuert eine Liste aller SQL-Lagerhäuser abzurufen, auf die Sie über Zugriffsberechtigungen verfügen. Die Antwort enthält die Lager-ID.

Erstellen oder Auswählen eines Genie-Agents

Ein gut strukturierter Genie Agent hat die folgenden Merkmale:

• Verwendet gut kommentierte Daten: Genie basiert auf Tabellenmetadaten und Spaltenkommentaren. Vergewissern Sie sich, dass Ihre Unity-Katalogdatenquellen klare, beschreibende Kommentare enthalten.
• Wird vom Benutzer getestet: Testen Sie Ihren Agent, indem Sie Fragen stellen, die Sie von Endbenutzern erwarten. Verwenden Sie Tests zum Erstellen und Verfeinern von BEISPIEL-SQL-Abfragen.
• Umfasst unternehmensspezifischen Kontext: Hinzufügen von Anweisungen, Beispiel-SQL und Funktionen. Weitere Informationen finden Sie unter Hinzufügen von SQL-Beispielen und Anweisungen. Zielen Sie auf mindestens fünf getestete BEISPIEL-SQL-Abfragen ab.
• Verwendet Benchmarks zum Testen der Genauigkeit: Fügen Sie mindestens fünf Benchmarkfragen basierend auf erwarteten Benutzerfragen hinzu. Siehe Benchmarks.

Weitere Informationen zum Erstellen eines Agenten finden Sie unter Erstellen und verwalten eines Genie-Agenten und Optimieren eines effektiven Genie-Agenten.

Sie können entweder einen neuen Genie Agent erstellen oder einen vorhandenen verwenden:

Erstellen eines neuen Agents

Erstellen Sie einen Genie Agent programmgesteuert mithilfe der Create Genie Agent-API. Das folgende Beispiel veranschaulicht einen gut strukturierten Agent, der bewährte Methoden befolgt. Ersetzen Sie die Platzhalter durch Ihre Werte:

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

Verwenden eines vorhandenen Agents

Wenn Sie bereits einen Genie Agent haben, können Sie die Space-ID über die List Genie Agents API finden. Sie können die Space-ID auch im Tab „Genie Agent Einstellungen“ finden und kopieren.

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

Verwenden Sie das space_id aus der Antwort in nachfolgenden API-Aufrufen.

Grundlegendes zum Feld "serialized_space"

Das serialized_space Feld ist eine JSON-Zeichenfolge, die die Konfiguration und Datenquellen für Ihren Genie-Agent definiert. In der API-Anforderung muss dieser JSON-Code als Zeichenfolge mit Escape-Zeichen versehen werden. Das Feld enthält:

• version: Schemaversionsnummer für Abwärtskompatibilität. Verwenden Sie 2 wie im folgenden Beispiel gezeigt.
• konfiguration: Agentkonfiguration, einschließlich:
  • sample_questions: Beispielfragen zur Anleitung von Benutzern. Jede Frage erfordert eine ID (32-stellige Hex-Zeichenfolge) und eine Frage (Array von Zeichenfolgen).
• data_sources: Datenquellen, die für den Agent verfügbar sind:
  • tables: Array von Tabllenobjekten mit einem identifier (Drei-Ebenen-Namespace), einer optionalen description und optionalen column_configs.
  • metric_views: Array von metrischen Ansichtsobjekten (gleiche Struktur wie Tabellen).
• Anweisungen: Strukturierte Anweisungen für den Agenten:
  • text_instructions: Übergeordnete Anleitungen für LLM.
  • example_question_sqls: Beispielfragen mit SQL-Antworten, optional mit Parametern und usage_guidance.
  • sql_functions: Verweise auf SQL-Funktionen, die für den Agent verfügbar sind.
  • join_specs: Vordefinierte Verknüpfungsbeziehungen zwischen Tabellen. Das Feld sql erfordert genau zwei Elemente: die Verknüpfungsbedingung, die mit Graviszeichen zitierte Aliasverweise verwendet, und eine Beziehungstypanmerkung, zum Beispiel "--rt=FROM_RELATIONSHIP_TYPE_MANY_TO_ONE--". Siehe Join-Spezifikationen-Format.
  • sql_snippets: Wiederverwendbare Filter, Ausdrücke und Measures.
• Benchmarks: Fragen zur Bewertung der Qualität des Agenten, jeweils mit einer SQL-Antwort als Ground-Truth.

Die nicht mit Escape-Zeichen versehene Version des serialized_space-Feldes aus dem Beispiel zum Erstellen eines Agenten sieht wie folgt aus:

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

Erstellen Sie beim Aufbau Ihres Agenten diese JSON-Struktur und versehen Sie sie anschließend als Zeichenfolge mit Escape-Zeichen für die API-Anfrage. Vollständige Schemadetails finden Sie in der Referenz zur Create Genie Agent-API.

Gültigkeitsprüfungsregeln für serialized_space

Der serialized_space JSON-Code muss den folgenden Gültigkeitsprüfungsregeln entsprechen. JSON, das ungültig ist, wird während der Agenterstellung oder -aktualisierung abgelehnt.

Version

• Versionsfeld: Erforderlich. Verwenden Sie 2 für neue Agenten. Die Versionsnummer ist aus Gründen der Abwärtskompatibilität vorhanden.

ID-Format

Alle ID-Felder müssen 32-stellige hexadezimale Zeichenfolgen (UUID-Format ohne Bindestriche) sein.

• Gültig: a1b2c3d4e5f60000000000000000000a
• Ungültig: a1b2c3d4e5f6 (zu kurz), A1B2C3D4E5F60000000000000000000A (Großbuchstaben), a1b2c3d4-e5f6-0000-0000-00000000000a (enthält Bindestriche)

IDs sind erforderlich für:

• 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 (wenn Benchmarks enthalten sind)

Sie können den folgenden Befehl verwenden, um eine gültige ID zu generieren:

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

Dadurch wird eine zeitgeordnete UUID generiert. Die in Sequenz generierten IDs lassen sich alphabetisch in der Reihenfolge sortieren, in der sie erstellt wurden, was den Sortieranforderungen automatisch entspricht.

Sortieranforderungen

Sammlungen, die IDs oder Bezeichner enthalten, müssen vorsortiert werden. Das System überprüft, ob Arrays bereits sortiert sind und nicht sortierte Eingaben ablehnen.

Eindeutigkeitseinschränkungen

• Frage-IDs: Alle IDs in config.sample_questions und benchmarks.questions müssen in beiden Sammlungen eindeutig sein.
• Anweisungs-IDs: Alle IDs müssen über text_instructions, example_question_sqls, sql_functions, join_specsund alle sql_snippets Typen eindeutig sein.
• Spaltenkonfigurationen: Die Kombination von (table_identifier, column_name) muss innerhalb des Agents eindeutig sein.

Größen- und Längenbeschränkungen

• Zeichenfolgenlänge: Einzelne Zeichenfolgenelemente sind auf 25.000 Zeichen begrenzt.
• Arraygröße: Wiederholte Felder sind auf 10.000 Elemente beschränkt.
• Textanweisungen: Höchstens 1 Textanweisung ist pro Agent zulässig.
• Tabellen und Metrikansichten: Unterliegt arbeitsbereichspezifischen Grenzwerten.
• SQL-Inhalt: Abfragetext in sql und join_specs.sql Feldern unterliegt Längenbeschränkungen.

Format der Verknüpfungsspezifikation

Das sql Feld in jeder Verknüpfungsspezifikation muss genau zwei Elemente enthalten:

1. Die Verknüpfungsbedingung, wobei mit Graviszeichen zitierte Aliasverweise verwendet werden:

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

2. Eine Beziehungstypanmerkung im folgenden Format:

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

   Gültige Kardinalitätswerte:

   • FROM_RELATIONSHIP_TYPE_MANY_TO_ONE
   • FROM_RELATIONSHIP_TYPE_ONE_TO_MANY
   • FROM_RELATIONSHIP_TYPE_ONE_TO_ONE
   • FROM_RELATIONSHIP_TYPE_MANY_TO_MANY

Wenn die Beziehungstypanmerkung weggelassen wird, wird die API die Anforderung mit einem Analysefehler ablehnen. Erstellen Sie für mehrspaltige Verknüpfungen eine separate Verknüpfungsspezifikation für jede Beziehung.

Weitere Anforderungen

• Tabellenbezeichner: Muss das Namespaceformat der drei Ebenen (catalog.schema.table) verwenden.
• Benchmark-Antworten: Jede Benchmarkfrage muss genau eine Antwort haben, bei der das Format auf SQL festgelegt ist.
• SQL-Codeausschnitte: Filter-, Ausdrucks- und Measure-SQL-Felder dürfen nicht leer sein.

Genie API-Referenz

Die vorherigen Abschnitte zeigen, wie man einen Genie-Agent vorbereitet und Agenten über Arbeitsbereiche hinweg verwaltet. Um Gespräche zu beginnen, Nachrichten zu senden und Ergebnisse von Genie Agents abzurufen, siehe die REST API-Referenz:

• APIs im Agentenmodus: Senden Sie Prompts im Agentenmodus, streamen Sie die Begründung und SQL-Ergebnisse und erhalten Sie Abschlussberichte mit Zitaten. Siehe die Referenz zur Agent Mode API.
• APIs im Chatmodus: Starten Sie ein Chat-Modus-Gespräch, stellen Sie Folgefragen und rufen Sie generiertes SQL, Abfrageergebnisse und Visualisierungen ab. Siehe die Referenz zur Conversation API.

Bewährte Methoden und Grenzwerte

Bewährte Methoden für die Verwendung der Genie-API

So behalten Sie leistung und Zuverlässigkeit bei Verwendung der Genie-API bei:

• Implementieren Sie die Wiederholungslogik mit exponentiellem Backoff: Da die API fehlgeschlagene Anfragen nicht für Sie wiederholt, fügen Sie daher Ihre eigenen Warteschlangen und exponentielle Backoff-Strategien hinzu. Dadurch kann Ihre Anwendung vorübergehende Fehler behandeln und unnötige Wiederholungsanforderungen vermeiden, wenn sie wächst.
• Protokoll-API-Antworten: Implementieren Sie umfassende Protokollierung von API-Anforderungen und -Antworten, um beim Debuggen, Überwachen von Verwendungsmustern und der Nachverfolgung von Kosten zu helfen.
• Abrufen von Statusaktualisierungen alle 1 bis 5 Sekunden: Das Abfragen fortsetzen, bis ein abschließender Nachrichtenstatus, wie z.B. COMPLETED, FAILED oder CANCELLED, empfangen wird. Begrenzen Sie die Abfrage auf 10 Minuten für die meisten Abfragen. Wenn nach 10 Minuten keine abschließende Antwort vorhanden ist, beenden Sie die Abfrage, und geben Sie einen Timeoutfehler zurück, oder fordern Sie den Benutzer auf, den Abfragestatus später manuell zu überprüfen.
• Verwenden Sie "Exponential Backoff" für das Polling: Erhöhen Sie die Verzögerung zwischen den Abfragen schrittweise, bis sie eine maximale Dauer von einer Minute erreicht. Dadurch werden unnötige Anforderungen für lange ausgeführte Abfragen reduziert und gleichzeitig eine geringe Latenz für schnelle Abfragen ermöglicht.
• Starten Sie eine neue Unterhaltung für jede Sitzung: Vermeiden Sie die erneute Verwendung von Unterhaltungsthreads über Sitzungen hinweg, da dies die Genauigkeit aufgrund der unbeabsichtigten Wiederverwendung des Kontexts verringern kann.
• Verwalten Von Unterhaltungsgrenzwerten: So verwalten Sie alte Unterhaltungen und bleiben unter dem Grenzwert von 10.000 Unterhaltungen:
  1. Verwenden Sie den GET /api/2.0/genie/spaces/{space_id}/conversations Endpunkt, um alle vorhandenen Unterhaltungsthreads in einem Agent anzuzeigen.
  2. Identifizieren Sie Unterhaltungen, die nicht mehr benötigt werden, z. B. ältere Unterhaltungen oder Testunterhaltungen.
  3. Verwenden Sie den DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id} Endpunkt, um Unterhaltungen programmgesteuert zu entfernen.

Überwachen des Agents

Nachdem Ihre Anwendung eingerichtet wurde, können Sie Fragen und Antworten in der Databricks-Benutzeroberfläche überwachen.

Ermutigen Sie Benutzer, den Agent zu testen, damit Sie mehr über die Arten von Fragen erfahren, die sie wahrscheinlich stellen und welche Antworten sie erhalten. Stellen Sie Benutzern Anleitungen zur Verfügung , um ihnen beim Testen des Agents zu helfen. Verwenden Sie die Registerkarte " Überwachung ", um Fragen und Antworten anzuzeigen. Siehe "Überwachen des Agents".

Sie können auch Überwachungsprotokolle verwenden, um Aktivitäten in einem Genie-Agent zu überwachen. Siehe Genie Agent-Ereignisse.