Delen via

De Genie-API gebruiken om Genie te integreren in uw toepassingen

Belangrijk

Deze functie bevindt zich in openbare preview-versie.

Op deze pagina wordt uitgelegd hoe u de Genie-API gebruikt om Genie-mogelijkheden in te schakelen in uw eigen chatbot, agent of toepassing.

Overzicht

De Genie-API biedt twee soorten mogelijkheden:

  • Gespreks-API's: Zorg voor gegevensopvraging in natuurlijke taal in toepassingen, chatbots en AI-agentframeworks. Deze API's ondersteunen gesprekken met toestandbeheer waarin gebruikers vervolgvragen kunnen stellen en gegevens op een natuurlijke manier kunnen verkennen.
  • Beheer-API's: programmatisch maken, configureren en implementeren van Genie-ruimten in verschillende werkruimten inschakelen. Gebruik deze API's voor CI/CD-pijplijnen, versiebeheer en geautomatiseerd ruimtebeheer.

Op deze pagina worden zowel gespreks- als beheer-API's beschreven. Voordat u de gespreks-API's aanroept, bereidt u een goed gecureerde Genie-ruimte voor. De ruimte biedt de context die Genie gebruikt om vragen te interpreteren en antwoorden te genereren. Als de ruimte onvolledig of niet is getest, ontvangen gebruikers mogelijk nog steeds onjuiste resultaten, zelfs met een juiste API-integratie. In deze handleiding wordt uitgelegd welke minimale installatie nodig is om een ruimte te maken die effectief werkt met de Genie-API.

Vereiste voorwaarden

Als u de Genie-API wilt gebruiken, moet u het volgende hebben:

  • Toegang tot een Azure Databricks-werkruimte met het Databricks SQL-recht.
  • Ten minste KAN BEVOEGDHEDEN GEBRUIKEN voor een SQL Pro- of serverloze SQL Warehouse.

Aan de slag

Azure Databricks-verificatie configureren

Gebruik OAuth voor gebruikers (OAuth U2M) voor gebruiksscenario's waarin een gebruiker met toegang tot een browser aanwezig is. In situaties waarin verificatie op basis van een browser niet mogelijk is, gebruikt u een service-principal om te verifiëren met de API. Zie OAuth voor serviceprincipals (OAuth M2M). Service-principals moeten machtigingen hebben voor toegang tot de vereiste gegevens en SQL-warehouses.

Details verzamelen

  • Naam van werkruimte-exemplaar: zoek en kopieer de naam van het werkruimte-exemplaar uit de URL van uw Databricks-werkruimte. Voor meer informatie over de werkruimte-id's in uw URL, zie Id's ophalen voor werkruimteobjecten.

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

  • Warehouse-id: u hebt de id nodig van een SQL-warehouse waarvoor u ten minste BEVOEGDHEDEN KUNT GEBRUIKEN. Ga als volgende te werk om uw magazijn-id te vinden:

    1. Ga naar SQL Warehouses in uw werkruimte.
    2. Selecteer het magazijn dat u wilt gebruiken.
    3. Kopieer de magazijn-ID van de URL of de magazijndetailpagina.

    U kunt ook het eindpunt GET /api/2.0/sql/warehouses gebruiken om programmatisch een lijst op te halen met alle SQL-warehouses waartoe u toegangsmachtigingen hebt. Het antwoord bevat de magazijn-id.

Een Genie-ruimte maken of selecteren

Een goed gestructureerde Genie-ruimte heeft de volgende kenmerken:

  • Maakt gebruik van goed geannoteerde gegevens: Genie is afhankelijk van tabelmetagegevens en kolomopmerkingen. Controleer of uw Unity Catalog-gegevensbronnen duidelijke, beschrijvende opmerkingen bevatten.
  • Is de gebruiker getest: Test uw ruimte door vragen te stellen die u van eindgebruikers verwacht. Gebruik tests om voorbeeldquery's voor SQL te maken en te verfijnen.
  • Bevat bedrijfsspecifieke context: Voeg instructies, voorbeeld-SQL en functies toe. Zie SQL-voorbeelden en -instructies toevoegen. Richt u op ten minste vijf geteste SQL-query's.
  • Gebruikt benchmarks om de nauwkeurigheid te testen: Voeg ten minste vijf benchmarkvragen toe op basis van verwachte gebruikersvragen. Zie Benchmarks gebruiken in een Genie-ruimte.

Zie Een AI/BI Genie-ruimte instellen en beheren en een effectieve Genie-ruimte cureren voor meer informatie over het maken van een ruimte.

U kunt een nieuwe Genie-ruimte maken of een bestaande gebruiken:

Een nieuwe ruimte maken

Maak programmatisch een Genie-ruimte met behulp van de Create Genie space-API. In het volgende voorbeeld ziet u een goed gestructureerde ruimte die de aanbevolen procedures volgt. Vervang de tijdelijke aanduidingen door uw waarden:

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

Een bestaande ruimte gebruiken

Als u al een Genie-ruimte hebt, kunt u de ruimte-id vinden met behulp van de List Genie spaces-API. U kunt de ruimte-id ook vinden en kopiëren op het tabblad Genie-ruimteinstellingen .

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

Gebruik het space_id uit de respons in volgende API-aanroepen.

Informatie over het serialized_space veld

Het serialized_space veld is een JSON-tekenreeks die de configuratie en gegevensbronnen voor uw Genie-ruimte definieert. In de API-aanvraag moet deze JSON worden geëscaped als een tekenreeks. Het veld bevat:

  • versie: Schemaversie (momenteel 1)

  • configuratie: Ruimteconfiguratie, waaronder:

    • sample_questions: Voorbeeldvragen om gebruikers te helpen. Voor elke vraag is het volgende vereist:

      • id: Een unieke id voor de vraag. U kunt elke unieke tekenreeks genereren (zoals korte alfanumerieke tekenreeksen of UUID's). Het systeem normaliseert deze tot 32 tekens.
      • vraag: Een matrix met de vraagtekst.

      Neem ten minste vijf verschillende vragen op die veelvoorkomende use cases vertegenwoordigen.

  • data_sources: Gegevensbronnen die beschikbaar zijn voor de ruimte, waaronder:

    • tabellen: Matrix van tabelobjecten in naamruimteindeling op drie niveaus (catalog.schema.table). Elke tabel kan het volgende bevatten:
      • identifier: vereist. De volledige tabelnaam.
      • beschrijving: Optioneel. Matrix met beschrijvingstekst over de tabel.
      • column_configs: Optioneel. Matrix van kolomconfiguratieobjecten met:
        • column_name: de kolomnaam.
        • get_example_values: Booleaanse waarde. Of u voorbeeldwaarden uit deze kolom wilt bekijken.
        • build_value_dictionary: Booleaanse waarde. Hiermee wordt aangegeven of u een waardewoordenlijst voor categorische kolommen wilt maken.

  • instructies: Optioneel. Gestructureerde instructies voor de ruimte, waaronder:

    • text_instructions: de tekstinstructies voor de ruimte.
    • example_question_sqls: Matrix van sql-queryobjecten.
    • join_specs: matrix waarmee joinrelaties tussen tabellen worden gedefinieerd.
    • sql_snippets: Object met filters, expressies en metingen.

De niet-gescaped versie van het serialized_space veld uit het voorbeeld van de create space ziet er als volgt uit:

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

Wanneer u uw ruimte maakt, maakt u deze JSON-structuur en escapet u deze als een tekenreeks voor de API-aanvraag. Zie de API-referentie voor het maken van Genie-ruimte voor volledige schemadetails.

De gespreks-API gebruiken

Nadat u een Genie-ruimte hebt geconfigureerd, gebruikt u de eindpunten van de gespreks-API om vragen te stellen, resultaten op te halen en gesprekken met meerdere paden met context te onderhouden.

Een gesprek starten

Het Start conversation endpointPOST /api/2.0/genie/spaces/{space_id}/start-conversation start een nieuw gesprek in uw Genie-ruimte.

Vervang de plaatsaanduidingen door uw Databricks-exemplaar, Genie-ruimte-ID en verificatietoken. Een voorbeeld van een succesvol antwoord volgt op het verzoek. Het bevat details die u kunt gebruiken om dit gesprek opnieuw te openen voor vervolgvragen.

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

Gegenereerde SQL ophalen

Gebruik conversation_id en message_id in de reactie om de generatiestatus van het bericht te controleren en de gegenereerde SQL van Genie op te halen. Zie GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id} voor volledige aanvraag- en antwoorddetails.

Opmerking

Alleen POST aanvragen tellen mee voor de doorvoerlimiet voor query's per minuut. GET aanvragen die worden gebruikt om resultaten te peilen, zijn niet onderhevig aan deze limiet.

Vervang uw waarden in de volgende aanvraag:

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

In het volgende voorbeeldantwoord worden de berichtdetails gerapporteerd:

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
}

Wanneer het status veld COMPLETED is, wordt het antwoord ingevuld in de attachments array.

Queryresultaten ophalen

De attachments matrix bevat het antwoord van Genie. Het bevat het gegenereerde tekstantwoord (text), de query-instructie als deze bestaat (query) en een id die u kunt gebruiken om de bijbehorende queryresultaten (attachment_id) op te halen. Vervang de tijdelijke aanduidingen in het volgende voorbeeld om de gegenereerde queryresultaten op te halen:

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

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

Vervolgvragen stellen

Nadat u een antwoord hebt ontvangen, gebruikt u de conversation_id opdracht om door te gaan met het gesprek. Context van eerdere berichten wordt bewaard en gebruikt in vervolgreacties. Zie POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messagesvoor volledige aanvraag- en antwoorddetails.

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

Ruimte- en gespreksgegevens ophalen

De Genie-API biedt extra eindpunten voor het ophalen van configuratie en historische gegevens uit bestaande ruimten en gesprekken.

Ruimteconfiguratie ophalen

Wanneer u ruimtegegevens opvragen met behulp van de Get Genie Space-API, kunt u het serialized_space veld in het antwoord opnemen door de include_serialized_space parameter in te stellen op true. Het serialized_space veld bevat de geserialiseerde tekenreeksweergave van de Genie-ruimte, inclusief instructies, benchmarks, joins en andere configuratiedetails.

Gebruik deze geserialiseerde weergave met de Create Genie Space API en Update Genie Space API om Genie-ruimten te promoten in werkruimten of back-ups van ruimteconfiguraties te maken.

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

Verwijzen naar oude gespreksthreads

Als u wilt toestaan dat gebruikers naar oude gespreksthreads verwijzen, gebruikt u het eindpuntGET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages gespreksberichten weergeven om alle berichten op te halen uit een specifieke gespreksthread.

Gespreksgegevens ophalen voor analyse

Ruimtebeheerders kunnen programmatisch alle eerdere berichten ophalen die door alle gebruikers van een ruimte voor analyse worden gevraagd. Ga als volgt te werk om deze gegevens op te halen:

  1. Gebruik het GET /api/2.0/genie/spaces/{space_id}/conversations eindpunt om alle bestaande gespreksthreads in een ruimte op te halen.
  2. Gebruik voor elke geretourneerde gespreks-id het GET /api/2.0/genie/spaces/{space_id}/conversations eindpunt om de lijst met berichten voor dat gesprek op te halen.

Best practices en beperkingen

Aanbevolen procedures voor het gebruik van de Genie-API

Prestaties en betrouwbaarheid behouden bij het gebruik van de Genie-API:

  • Logica voor opnieuw proberen implementeren met exponentieel uitstel: De API probeert mislukte aanvragen niet opnieuw voor u uit te voeren, dus voeg uw eigen wachtrijen en exponentieel uitstel toe. Dit helpt uw toepassing tijdelijke fouten af te handelen, onnodige herhalingsaanvragen te voorkomen en binnen de doorvoerlimieten te blijven naarmate deze groeit.
  • Log API-antwoorden: Implementeer uitgebreide logboekregistratie van API-aanvragen en -antwoorden om te helpen fouten op te sporen, gebruikspatronen te bewaken en kosten bij te houden.
  • Peiling voor statusupdates om de 1 tot 5 seconden: Ga door met peilen totdat een overtuigende berichtstatus, zoals COMPLETED, FAILEDof CANCELLED, is ontvangen. Beperk polling tot 10 minuten voor de meeste query's. Als er na 10 minuten geen overtuigend antwoord is, stopt u met pollen en retourneert u een time-outfout of vraagt u de gebruiker om de querystatus later handmatig te controleren.
  • Exponentieel uitstel gebruiken voor polling: Verhoog de vertraging tussen polls tot maximaal één minuut. Dit vermindert onnodige aanvragen voor langlopende query's, terwijl er nog steeds lage latentie voor snelle query's is toegestaan.
  • Start een nieuw gesprek voor elke sessie: Vermijd het hergebruik van gespreksthreads in sessies, omdat dit de nauwkeurigheid kan verminderen door onbedoelde contexthergebruik.
  • Gesprekslimieten behouden: Oude gesprekken beheren en onder de limiet van 10.000 gesprekken blijven:
    1. Gebruik het GET /api/2.0/genie/spaces/{space_id}/conversations eindpunt om alle bestaande gespreksthreads in een ruimte te bekijken.
    2. Identificeer gesprekken die niet meer nodig zijn, zoals oudere gesprekken of testgesprekken.
    3. Gebruik het DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id} eindpunt om gesprekken programmatisch te verwijderen.
  • Let op de limiet voor queryresultaten: de Genie-API retourneert maximaal 5000 rijen per queryresultaat. Als voor uw gegevensanalyse meer rijen nodig zijn, kunt u overwegen om uw vraag te verfijnen om zich te richten op een specifieke subset van gegevens of filters te gebruiken om de resultaten te beperken.

Doorvoerlimiet

Tijdens de openbare preview-periode zijn de doorvoersnelheden voor de gratis laag van de Genie-API het beste en zijn ze afhankelijk van de systeemcapaciteit. Onder normale of weinig verkeersomstandigheden beperkt de API aanvragen tot 5 query's per minuut per werkruimte. Tijdens piekperioden verwerkt het systeem aanvragen op basis van de beschikbare capaciteit, wat kan leiden tot een lagere doorvoer.

De ruimte bewaken

Nadat uw toepassing is ingesteld, kunt u vragen en antwoorden bewaken in de Databricks-gebruikersinterface.

Moedig gebruikers aan om de ruimte te testen, zodat u meer weet over de typen vragen die ze waarschijnlijk zullen stellen en de antwoorden die ze ontvangen. Geef gebruikers richtlijnen om hen te helpen met het testen van de ruimte. Gebruik het tabblad Bewaking om vragen en antwoorden weer te geven. Zie De ruimte bewaken.

U kunt ook auditlogboeken gebruiken om activiteiten in een Genie-ruimte te bewaken. Bekijk AI/BI Genie-gebeurtenissen.

  • Last updated on