Verwenden sie die Genie-API, um Genie in Ihre Anwendungen zu integrieren

Auf dieser Seite wird erläutert, wie Sie die Genie-API verwenden, um Genie-Funktionen in Ihrem eigenen Chatbot, Agent oder ihrer Anwendung zu aktivieren.

Überblick

Die Genie-API bietet zwei Arten von Funktionen:

• Konversations-APIs: Ermöglichen die Abfrage von natürlicher Sprachdaten in Anwendungen, Chatbots und KI-Agent-Frameworks. Diese APIs unterstützen zustandsbehaftete Unterhaltungen, in denen Benutzer Nachverfolgungsfragen stellen und Daten im Laufe der Zeit natürlich untersuchen können.
• Verwaltungs-APIs: Aktivieren Sie programmgesteuerte Erstellung, Konfiguration und Bereitstellung von Genie-Räumen über Arbeitsbereiche hinweg. Verwenden Sie diese APIs für CI/CD-Pipelines, Versionssteuerung und automatisierte Raumverwaltung.

Auf dieser Seite werden sowohl Unterhaltungs- als auch Verwaltungs-APIs beschrieben. Bereiten Sie vor dem Aufrufen der Unterhaltungs-APIs einen gut kuratierten Genie-Raum vor. Der Raum bietet den Kontext, den Genie verwendet, um Fragen zu interpretieren und Antworten zu generieren. Wenn der Speicherplatz unvollständig oder ungetestet ist, erhalten Benutzer möglicherweise auch bei einer korrekten API-Integration immer noch falsche Ergebnisse. In diesem Leitfaden wird das Mindestsetup erläutert, das erforderlich ist, um einen Raum zu schaffen, der effektiv mit der Genie-API funktioniert.

Voraussetzungen

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

• Zugriff auf einen Azure Databricks-Arbeitsbereich mit der SQL-Berechtigung "Databricks".
• 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/

• Lager-ID: Sie benötigen die ID eines SQL-Warehouses, für das Sie mindestens Verwendungsberechtigungen haben. 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-Raums

Ein gut strukturierter Genie-Raum hat die folgenden Merkmale:

• Verwendet gut kommentierte Daten: Genie stützt sich auf Tabellenmetadaten und Spaltenkommentare. Vergewissern Sie sich, dass Ihre Unity-Katalogdatenquellen klare, beschreibende Kommentare enthalten.
• Wird vom Benutzer getestet: Testen Sie Ihren Platz, indem Sie Fragen stellen, die Sie von Endbenutzern erwarten. Verwenden Sie Tests zum Erstellen und Verfeinern von BEISPIEL-SQL-Abfragen.
• Umfasst unternehmensspezifischen Kontext: Fügen Sie Anweisungen, z. B. SQL und Funktionen hinzu. 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 Benchmark-Fragen basierend auf erwarteten Benutzerfragen hinzu. Siehe Verwenden von Benchmarks in einem Genie-Raum.

Weitere Informationen zum Erstellen eines Raums finden Sie unter Einrichten und Verwalten eines AI/BI Genie-Raums und Kuratiert einen effektiven Genie-Raum.

Sie können entweder einen neuen Genie-Raum erstellen oder ein vorhandenes verwenden:

Erstellen eines neuen Raums

Erstellen Sie einen Genie-Raum programmgesteuert mithilfe der Create Genie Space API. Das folgende Beispiel veranschaulicht einen gut strukturierten Raum, der bewährten Methoden folgt. 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 Bereichs

Wenn Sie bereits über einen Genie-Raum verfügen, können Sie die Space-ID mithilfe der List Genie Spaces-API finden. Sie können die Space-ID auch auf der Registerkarte "Einstellungen" von Genie 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-Raum definiert. In der API-Anforderung muss dieser JSON als Zeichenfolge escapet werden. Das Feld enthält:

• version: Schemaversion (derzeit 1)

• konfiguration: Raumkonfiguration, einschließlich:

  • sample_questions: Beispielfragen zur Anleitung von Benutzern. Jede Frage erfordert Folgendes:

    • id: Ein eindeutiger Bezeichner für die Frage. Sie können eine beliebige eindeutige Zeichenfolge (z. B. kurze alphanumerische Zeichenfolgen oder UUIDs) generieren. Das System normalisiert diese auf 32-stellige Bezeichner.
    • frage: Ein Array, das den Fragetext enthält.

    Schließen Sie mindestens fünf verschiedene Fragen ein, die häufige Anwendungsfälle darstellen.

• data_sources: Datenquellen, die für den Raum verfügbar sind, einschließlich:

  • tables: Array von Tabellenobjekten im dreistufigen Namensraum-Format (catalog.schema.table). Jede Tabelle kann Folgendes enthalten:

    • Bezeichner: Erforderlich. Der vollständige Tabellenname.
    • description: Optional. Array mit Beschreibungstext zur Tabelle.
    • column_configs: Optional. Array von Spaltenkonfigurationsobjekten mit:
      • column_name: Der Spaltenname.
      • get_example_values: Boolean. Gibt an, ob Beispielwerte aus dieser Spalte verwendet werden sollen.
      • build_value_dictionary: Boolean. Gibt an, ob ein Wertwörterbuch für kategorisierte Spalten erstellt werden soll.

• Anweisungen: Optional. Strukturierte Anweisungen für den Raum, einschließlich:

  • text_instructions: Die Textanweisungen für den Raum.
  • example_question_sqls: Array von BEISPIEL-SQL-Abfrageobjekten.
  • join_specs: Array, das Verknüpfungsbeziehungen zwischen Tabellen definiert.
  • sql_snippets: Objekt, das Filter, Ausdrücke und Measures enthält.

Die nicht gescapete Version des serialized_space Felds aus dem Beispiel "Raum erstellen" sieht wie folgt aus:

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

Wenn Sie Ihren Space erstellen, erstellen Sie diese JSON-Struktur und escapen Sie sie dann als Zeichenfolge für die API-Anfrage. Vollständige Schemadetails finden Sie in der Referenz zur Create Genie space API.

Verwenden der Konversations-API

Nachdem Sie einen Genie-Raum konfiguriert haben, verwenden Sie die Unterhaltungs-API-Endpunkte, um Fragen zu stellen, Ergebnisse abzurufen und Multi-Turn-Unterhaltungen mit Kontext zu verwalten.

Starten einer Unterhaltung

Der "Gespräch starten"-EndpunktPOST /api/2.0/genie/spaces/{space_id}/start-conversation startet eine neue Unterhaltung in Ihrem Genie-Bereich.

Ersetzen Sie die Platzhalter durch Ihre Databricks-Instanz, Ihre Genie-Space-ID und Ihr Authentifizierungstoken. Ein Beispiel für eine erfolgreiche Antwort folgt der Anforderung. Es enthält Details, mit denen Sie diese Unterhaltung erneut aufrufen können, um weitere Fragen zu stellen.

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

Abrufen generierter SQL-Dateien

Verwenden Sie conversation_id und message_id in der Antwort auf die Umfrage, um den Status der Nachrichtengenerierung zu überprüfen und generierte SQL von Genie abzurufen. Vollständige Anforderungs- und Antwortdetails finden Sie unter GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}.

Ersetzen Sie Ihre Werte in die folgende Anforderung:

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

Im folgenden Beispiel meldet die Antwort die Nachrichtendetails:

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
}

Wenn das status Feld COMPLETED ist, wird die Antwort im attachments Array eingetragen.

Abrufen von Abfrageergebnissen

Das attachments Array enthält die Antwort von Genie. Sie enthält die generierte Textantwort (text), die Abfrage-Anweisung, sofern vorhanden (query) und einen Bezeichner, den Sie zum Abrufen der zugehörigen Abfrageergebnisse (attachment_id) verwenden können. Ersetzen Sie die Platzhalter im folgenden Beispiel, um die generierten Abfrageergebnisse abzurufen:

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

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

Folgefragen stellen

Nachdem Sie eine Antwort erhalten haben, verwenden Sie die conversation_id Datei, um die Unterhaltung fortzusetzen. Kontext aus vorherigen Nachrichten wird beibehalten und in Nachverfolgungsantworten verwendet. Vollständige Anforderungs- und Antwortdetails finden Sie unter 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?",
}

Abrufen von Raum- und Konversationsdaten

Die Genie-API bietet zusätzliche Endpunkte zum Abrufen von Konfigurations- und Verlaufsdaten aus vorhandenen Räumen und Unterhaltungen.

Abrufen der Raumkonfiguration

Beim Abrufen von Rauminformationen mithilfe der Get Genie Space-API können Sie das serialized_space Feld in die Antwort einschließen, indem Sie den include_serialized_space Parameter auf truefestlegen. Das serialized_space Feld enthält die serialisierte Zeichenfolgendarstellung des Genie-Raums, einschließlich Anweisungen, Benchmarks, Verknüpfungen und anderen Konfigurationsdetails.

Verwenden Sie diese serialisierte Darstellung mit der Create Genie Space API und der Update Genie Space API , um Genie-Räume über Arbeitsbereiche hinweg zu bewerben oder Sicherungen von Raumkonfigurationen zu erstellen.

Beispielanforderung GET :

GET /api/2.0/genie/spaces/{space_id}?include_serialized_space=true
Host: <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>

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

Verweisen auf alte Unterhaltungsthreads

Um Benutzern das Verweisen auf alte Unterhaltungsthreads zu ermöglichen, verwenden Sie den Endpunkt "GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages", um alle Nachrichten aus einem bestimmten Unterhaltungsthread abzurufen.

Abrufen von Unterhaltungsdaten für die Analyse

Space Manager können programmgesteuert alle vorherigen Nachrichten abrufen, die für alle Benutzer eines Raums zur Analyse gefragt werden. So rufen Sie diese Daten ab:

1. Verwenden Sie den GET /api/2.0/genie/spaces/{space_id}/conversations Endpunkt, um alle vorhandenen Unterhaltungsthreads in einem Raum abzurufen.
2. Verwenden Sie für jede zurückgegebene Unterhaltungs-ID den GET /api/2.0/genie/spaces/{space_id}/conversations Endpunkt, um die Liste der Nachrichten für diese Unterhaltung abzurufen.

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 Wiederholungslogik mit exponentiellem Backoff: Die API versucht keine fehlgeschlagenen Anforderungen für Sie erneut. Fügen Sie daher Ihre eigenen Warteschlangen und exponentiellen Backoffs hinzu. Dies hilft Ihrer Anwendung, vorübergehende Fehler zu verarbeiten, unnötige Wiederholungsanforderungen zu vermeiden und beim Zunehmen innerhalb der Durchsatzgrenzen zu bleiben.
• Protokollierung von API-Antworten: Implementieren Sie eine umfassende Protokollierung von API-Anfragen und -Antworten, um das Debuggen zu unterstützen, Nutzungsmuster zu überwachen und Kosten nachzuverfolgen.
• Statusaktualisierungen alle 1 bis 5 Sekunden abfragen: Fahren Sie mit der Abfrage fort, bis ein eindeutiger Nachrichtenstatus, 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 eine exponentielle Backoff-Strategie für die Abfrage: Erhöhen Sie die Verzögerung zwischen Abfragen auf maximal eine Minute. Dadurch werden unnötige Anforderungen für lange ausgeführte Abfragen reduziert und gleichzeitig eine geringe Latenz für schnelle Abfragen ermöglicht.
• Beginnen Sie eine neue Unterhaltung für jede Sitzung: Vermeiden Sie die Wiederverwendung 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 Raum 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.
• Beachten Sie das Abfrageergebnislimit: Die Genie-API gibt maximal 5.000 Zeilen pro Abfrageergebnis zurück. Wenn ihre Datenanalyse mehr Zeilen erfordert, sollten Sie ihre Frage verfeinern, um sich auf eine bestimmte Teilmenge von Daten zu konzentrieren, oder verwenden Sie Filter, um die Ergebnisse einzugrenzen.

Durchsatzgrenze

Während des Public Preview-Zeitraums sind die Durchsatzraten für die kostenlose Ebene der Genie-API auf Best-Effort-Basis und hängen von der Systemkapazität ab. Unter normalen oder niedrigen Datenverkehrsbedingungen beschränkt die API Anforderungen auf 5 Abfragen pro Minute pro Arbeitsbereich. Während der Spitzenauslastung verarbeitet das System Anforderungen basierend auf verfügbarer Kapazität, was zu einem niedrigeren Durchsatz führen kann.

Überwachen des Raums

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

Ermutigen Sie Die Benutzer, den Raum zu testen, damit Sie mehr über die Arten von Fragen erfahren, die sie wahrscheinlich stellen und welche Antworten sie erhalten. Stellen Sie Benutzern Anleitungen bereit, die ihnen beim Testen des Raums helfen. Verwenden Sie die Registerkarte " Überwachung ", um Fragen und Antworten anzuzeigen. Weitere Informationen finden Sie unter Überwachen des Space.

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