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

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 Spaces in 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 Space 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.

In de voorbeelden op deze pagina wordt de REST API rechtstreeks gebruikt. U kunt deze API's ook aanroepen met behulp van de Azure Databricks SDK's. Zie Databricks SDK's.

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 Space heeft de volgende kenmerken:

• Gebruikt 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: Instructies toevoegen, voorbeeld-SQL en functies. 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 Space.

Zie Een 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 Space maken of een bestaande maken:

Een nieuwe ruimte maken

Maak programmatisch een Genie Space 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 Space hebt, kunt u de ruimte-id vinden met behulp van de List Genie Spaces-API. U kunt de space-ID ook vinden en kopiëren in het tabblad Genie Space Instellingen.

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 Space definieert. In de API-aanvraag moet deze JSON worden geëscaped als een tekenreeks. Het veld bevat:

• versie: Schemaversienummer voor compatibiliteit met eerdere versies. Gebruik 2 zoals wordt weergegeven in het onderstaande voorbeeld.
• configuratie: Ruimteconfiguratie, waaronder:
  • sample_questions: Voorbeeldvragen om gebruikers te helpen. Elke vraag vereist een id (hextekenreeks van 32 tekens) en een vraag (matrix met tekenreeksen).
• data_sources: Gegevensbronnen die beschikbaar zijn voor de ruimte:
  • tabellen: Matrix van tabelobjecten met id (naamruimte op drie niveaus), optionele beschrijving en optionele column_configs.
  • metric_views: Matrix met metrische weergaveobjecten (dezelfde structuur als tabellen).
• instructies: Gestructureerde instructies voor de ruimte:
  • text_instructions: Richtlijnen op hoog niveau voor de LLM.
  • example_question_sqls: Voorbeeldvragen met SQL-antwoorden, optioneel met parameters en usage_guidance.
  • sql_functions: verwijzingen naar SQL-functies die beschikbaar zijn voor de ruimte.
  • join_specs: Vooraf gedefinieerde joinrelaties tussen tabellen. Voor het sql veld zijn precies twee elementen vereist: de joinvoorwaarde, met behulp van aliasverwijzingen omsloten door backticks en een aantekening van het relatietype, bijvoorbeeld "--rt=FROM_RELATIONSHIP_TYPE_MANY_TO_ONE--". Zie Join-specificatie-indeling.
  • sql_snippets: Herbruikbare filters, expressies en metingen.
• benchmarks: Vragen voor het evalueren van de kwaliteit van de ruimte, ieder met een grondwaarheid SQL-antwoord.

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

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

Wanneer u uw ruimte maakt, maakt u deze JSON-structuur en escapet u deze als een tekenreeks voor de API-aanvraag. Zie de naslaginformatie over de Create Genie Space-API voor volledige schemagegevens.

Validatieregels voor serialized_space

De serialized_space JSON moet voldoen aan de volgende validatieregels. Niet-geldige JSON wordt tijdens het aanmaken of bijwerken van een ruimte geweigerd.

Versie

• Het versieveld: verplicht. Gebruik 2 voor nieuwe spaties. Het versienummer bestaat voor compatibiliteit met eerdere versies.

Id-indeling

Alle id-velden moeten een hexadecimale tekenreeks van 32 tekens (UUID-indeling zonder afbreekstreepjes) zijn.

• Geldig: a1b2c3d4e5f60000000000000000000a
• Ongeldig: a1b2c3d4e5f6 (te kort), A1B2C3D4E5F60000000000000000000A (hoofdletters) a1b2c3d4-e5f6-0000-0000-00000000000a (bevat afbreekstreepjes)

Id's zijn vereist voor:

• 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 (als benchmarks zijn opgenomen)

U kunt de volgende opdracht gebruiken om een geldige id te genereren:

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

Hiermee wordt een op tijd geordende UUID gegenereerd. Id's die gesorteerd zijn in de volgorde waarin ze zijn gemaakt, sorteren alfabetisch automatisch volgens de sorteervereisten.

Sorteervereisten

Verzamelingen met ID's of identificatoren moeten vooraf worden gesorteerd. Het systeem valideert dat matrices al zijn gesorteerd en niet-gesorteerde invoer weigert.

Beperkingen voor uniekheid

• Vraag-id's: alle id's in config.sample_questions en benchmarks.questions moeten uniek zijn in beide verzamelingen.
• Instructie-id's: Alle id's tussen text_instructions, example_question_sqls, sql_functions, en join_specs, en alle sql_snippets typen moeten uniek zijn.
• Kolomconfiguraties: De combinatie van (table_identifier, column_name) moet uniek zijn binnen de ruimte.

Grootte- en lengtelimieten

• Tekenreekslengte: Afzonderlijke tekenreekselementen zijn beperkt tot 25.000 tekens.
• Matrixgrootte: herhaalde velden zijn beperkt tot 10.000 items.
• Tekstinstructies: maximaal 1 tekstinstructie is toegestaan per spatie.
• Tabellen en metrische weergaven: onderhevig aan werkruimtespecifieke limieten.
• SQL-inhoud: querytekst in sql en join_specs.sql velden zijn onderhevig aan lengtelimieten.

De opmaak van join-specificaties

Het sql veld in elke joinspecificatie moet exact twee elementen bevatten:

1. De joinvoorwaarde, gebruikmakend van met backticks gequote aliasverwijzingen:

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

2. Een aantekening van het relatietype in het volgende formaat:

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

   Geldige kardinaliteitswaarden:

   • FROM_RELATIONSHIP_TYPE_MANY_TO_ONE
   • FROM_RELATIONSHIP_TYPE_ONE_TO_MANY
   • FROM_RELATIONSHIP_TYPE_ONE_TO_ONE
   • FROM_RELATIONSHIP_TYPE_MANY_TO_MANY

Als u de annotatie van het relatietype weglaat, weigerde de API de aanvraag met een parsefout. Maak voor joins met meerdere kolommen een afzonderlijke joinspecificatie voor elke relatie.

Overige vereisten

• Tabel-id's: moet een naamruimteindeling met drie niveaus (catalog.schema.table) gebruiken.
• Benchmarkantwoorden: elke benchmarkvraag moet precies één antwoord hebben met de indeling ingesteld op SQL.
• SQL-fragmenten: Sql-velden filteren, expressies en meten mogen niet leeg zijn.

De gespreks-API gebruiken

Nadat u een Genie Space 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 eindpuntPOST /api/2.0/genie/spaces/{space_id}/start-conversation van het gesprek starten start een nieuw gesprek in uw Genie Space.

Vervang de tijdelijke aanduidingen door uw Databricks-exemplaar, Genie Space 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.

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.

Als u wilt bepalen of een antwoord is gegenereerd met behulp van een vertrouwde asset, controleert u het attachments veld in het antwoord voor een query.parameters object. De aanwezigheid geeft aan dat het antwoord afkomstig is van een vertrouwde asset.

Als u de redeneringstraceringen van Genie wilt openen, controleert u het attachments veld op een object van het query_attachments type GenieQueryAttachments. Als deze aanwezig is, bevat het de stapsgewijze redenering die Genie heeft gebruikt om het antwoord te genereren. Voor volledige velddetails, zie de API-referentie voor Bericht ophalen.

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

Opmerkingen toevoegen aan berichten

U kunt tekstopmerkingen toevoegen aan berichten en bestaande opmerkingen weergeven met behulp van de API-eindpunten voor berichtopmerkingen.

Als u een opmerking aan een bericht wilt toevoegen, gebruikt u het eindpunt POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/comments:

POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/comments
HOST= <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>
{
  "comment": "<your comment text>"
}

Als u bestaande opmerkingen in een bericht wilt weergeven, gebruikt u het eindpunt opmerkingen van het lijstbericht.

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 Space, waaronder instructies, benchmarks, joins en andere configuratiedetails.

Gebruik deze geserialiseerde weergave met de Create Genie Space API en Update Genie Space API om Genie Spaces 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>",
  "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:

• Implementeer logica voor opnieuw proberen met exponentieel uitstel: de API probeert mislukte aanvragen niet opnieuw voor u, 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 fouten op te sporen, gebruikspatronen te bewaken en kosten bij te houden.
• Poll voor statusupdates elke 1 tot 5 seconden: Ga door met peilen totdat een overtuigende berichtstatus, zoals COMPLETED, FAILEDof CANCELLED, wordt 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.
• Gebruik exponentieel uitstel 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.

Overwegingen voor prestaties

Doorvoersnelheden voor de gratis tier van de Genie Conversation API zijn op basis van best effort en afhankelijk van de systeemcapaciteit. Om misbruik te beperken en misbruik te voorkomen tijdens piekperioden van gebruik, verwerkt het systeem aanvragen op basis van de beschikbare capaciteit. Onder normale of weinig verkeersomstandigheden ondersteunt de API aanvragen tot vijf vragen per minuut per werkruimte. Als u ondersteuning voor hogere doorvoer zoekt, neemt u contact op met uw Databricks-accountteam.

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 Space te bewaken. Zie Genie Space-gebeurtenissen.