Använda Genie-API:et för att integrera Genie i dina program

Den här sidan förklarar hur du använder Genie API för att aktivera Genie-funktioner i din egen chattrobot, agent eller program.

Översikt

Genie-API:et innehåller två typer av funktioner:

• Konversations-API:er: Aktivera datafrågor på naturligt språk i program, chattrobotar och AI-agentramverk. Dessa API:er stöder tillståndskänsliga konversationer där användare kan ställa uppföljningsfrågor och utforska data naturligt över tid.
• Hanterings-API:er: Aktivera programmatiskt skapande, konfiguration och distribution av Genie Spaces på arbetsytor. Använd dessa API:er för CI/CD-pipelines, versionskontroll och automatiserad utrymmeshantering.

På den här sidan beskrivs både konversations- och hanterings-API:er. Innan du anropar konversations-API:erna förbereder du ett väl curerat Genie Space. Utrymmet ger den kontext som Genie använder för att tolka frågor och generera svar. Om utrymmet är ofullständigt eller otestat kan användarna fortfarande få felaktiga resultat även med en korrekt API-integrering. Den här guiden förklarar den minsta konfiguration som krävs för att skapa ett utrymme som fungerar effektivt med Genie-API:et.

Exemplen på den här sidan använder REST-API:et direkt. Du kan också anropa dessa API:er med hjälp av Azure Databricks SDK:er. Se Databricks SDKs.

Förutsättningar

Om du vill använda Genie-API:et måste du ha:

• Åtkomst till en Azure Databricks arbetsyta med Databricks SQL-berättigande.
• Du kan åtminstone använda behörigheter på ett SQL Pro- eller serverlöst SQL-lager.

Komma igång

Konfigurera Azure Databricks-autentisering

För produktionsanvändningsfall där en användare med åtkomst till en webbläsare finns använder du OAuth för användare (OAuth U2M). I situationer där webbläsarbaserad autentisering inte är möjlig använder du tjänstens huvudnamn för att autentisera med API:et. Se OAuth för tjänstehuvudmän (OAuth M2M). Tjänsteprinciper måste ha behörighet för åtkomst till nödvändiga data och till SQL-lager.

Samla in detaljer

• Namn på arbetsytans instans: Leta upp och kopiera instansnamnet för arbetsytan från url:en för Databricks-arbetsytan. Mer information om arbetsyteidentifierarna i url:en finns i Hämta identifierare för arbetsyteobjekt.

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

• Lager-ID: Du behöver ID:t för ett SQL-lager som du har minst KAN ANVÄNDA behörigheter på. Så här hittar du ditt lager-ID:

  1. Gå till SQL Warehouses på din arbetsyta.
  2. Välj det lager som du vill använda.
  3. Kopiera lager-ID:t från URL:en eller lagerdetaljsidan.

  Du kan också använda slutpunkten GET /api/2.0/sql/warehouses för att programmatiskt hämta en lista över alla SQL-lager som du har behörighet att komma åt. Svaret innehåller lager-ID:t.

Skapa eller välj ett Genie-utrymme

Ett välstrukturerat Genie Space har följande egenskaper:

• Använder väl annoterad data: Genie förlitar sig på tabellmetadata och kolumnkommentarer. Kontrollera att dina Unity Catalog-datakällor har tydliga, beskrivande kommentarer.
• Är användaren testad: Testa ditt utrymme genom att ställa frågor som du förväntar dig av slutanvändarna. Använd testning för att skapa och förfina SQL-exempelfrågor.
• Innehåller företagsspecifik kontext: Lägg till instruktioner, till exempel SQL och funktioner. Se Lägga till SQL-exempel och instruktioner. Sikta på minst fem testade SQL-exempelfrågor.
• Använder benchmarks för att testa noggrannhet: Lägg till minst fem benchmark-frågor baserat på förväntade användarfrågor. Se Använda benchmarks i ett Genie-utrymme.

Mer information om hur du skapar ett utrymme finns i Konfigurera och hantera ett Genie-utrymme och Kurera ett effektivt Genie-utrymme.

Du kan antingen skapa ett nytt Genie-utrymme eller använda ett befintligt:

Skapa ett nytt utrymme

Skapa ett Genie Space programmatiskt med hjälp av Create Genie Space API. I följande exempel visas ett välstrukturerat utrymme som följer metodtipsen. Ersätt platshållarna med dina värden:

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

Använda ett befintligt utrymme

Om du redan har en Genie Space kan du hitta space-ID:t med hjälp av API:et List Genie Spaces. Du kan också hitta och kopiera utrymmes-ID:t från fliken Inställningar för Genie Space.

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

space_id Använd svaret från i efterföljande API-anrop.

Att förstå fältet serialized_space

Fältet serialized_space är en JSON-sträng som definierar konfigurations- och datakällorna för ditt Genie Space. I API-begäran måste denna JSON vara escapead som en sträng. Fältet innehåller:

• version: Schemaversionsnummer för bakåtkompatibilitet. Använd 2 som du ser i exemplet nedan.
• konfiguration: Utrymmeskonfiguration som inkluderar:
  • sample_questions: Exempelfrågor som vägleder användarna. Varje fråga kräver ett ID (hexsträng med 32 tecken) och en fråga (matris med strängar).
• data_sources: Datakällor som är tillgängliga för utrymmet:
  • tabeller: Matris med tabellobjekt med identifierare (namnområde på tre nivåer), valfri beskrivning och valfri column_configs.
  • metric_views: Matris med måttvyobjekt (samma struktur som tabeller).
• instruktioner: Strukturerade instruktioner för utrymmet:
  • text_instructions: Vägledning på hög nivå för LLM.
  • example_question_sqls: Exempelfrågor med SQL-svar, valfritt med parametrar och usage_guidance.
  • sql_functions: Referenser till SQL-funktioner som är tillgängliga för utrymmet.
  • join_specs: Fördefinierade kopplingsrelationer mellan tabeller. Fältet sql kräver exakt två element: kopplingsvillkoret med hjälp av backtick-citerade aliasreferenser och en relationstypanteckning, till exempel "--rt=FROM_RELATIONSHIP_TYPE_MANY_TO_ONE--". Se Format för kopplingsspecifikationer.
  • sql_snippets: Återanvändbara filter, uttryck och mått.
• benchmarks: Frågor för att utvärdera utrymmeskvalitet, var och en med ett SQL-svar med grundsanning.

Den okapade versionen av fältet serialized_space från exemplet på att skapa utrymme ser ut så här:

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

När du skapar ditt utrymme skapar du den här JSON-strukturen och tar sedan bort den som en sträng för API-begäran. Fullständig schemainformation finns i referensen skapa Genie Space API.

Verifieringsregler för serialized_space

serialized_space JSON måste följa följande verifieringsregler. JSON som inte är giltig avvisas när utrymme skapas eller uppdateras.

Utgåva

• Versionsfält: Obligatoriskt. Använd 2 för nya utrymmen. Versionsnumret finns för bakåtkompatibilitet.

ID-format

Alla ID-fält måste vara 32 tecken långa hexadecimala strängar (UUID-format utan bindestreck).

• Giltigt: a1b2c3d4e5f60000000000000000000a
• Ogiltigt: a1b2c3d4e5f6 (för kort), A1B2C3D4E5F60000000000000000000A (stora bokstäver), a1b2c3d4-e5f6-0000-0000-00000000000a (innehåller bindestreck)

ID:t krävs för:

• config.sample_questions[].id
• instructions.text_instructions[].id
• instructions.example_question_sqls[].id
• instructions.join_specs[].id
• instructions.sql_snippets.filters[].id
• instructions.sql_snippets.expressions[].id
• instructions.sql_snippets.measures[].id
• benchmarks.questions[].id (om prestandamätningar omfattas)

Du kan använda följande kommando för att generera ett giltigt ID:

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

Detta genererar en tidsbeställd UUID. ID:n som genereras i en sekventiell ordning sorteras automatiskt alfabetiskt i den ordning de skapades, vilket uppfyller sorteringskraven.

Sorteringskrav

Samlingar som innehåller ID:er eller identifierare måste vara försorterade. Systemet verifierar att matriser redan är sorterade och avvisar osorterade indata.

Begränsningar för unikhet

• Fråge-ID: Alla ID:er i config.sample_questions och benchmarks.questions måste vara unika för båda samlingarna.
• Instruktions-ID: Alla ID:er i text_instructions, example_question_sqls, sql_functions, join_specsoch alla sql_snippets typer måste vara unika.
• Kolumnkonfigurationer: Kombinationen av (table_identifier, column_name) måste vara unik inom utrymmet.

Storleks- och längdgränser

• Stränglängd: Enskilda strängelement är begränsade till 25 000 tecken.
• Matrisstorlek: Upprepade fält är begränsade till 10 000 objekt.
• Textinstruktioner: Högst 1 textinstruktion tillåts per utrymme.
• Tabeller och måttvyer: Omfattas av arbetsytespecifika gränser.
• SQL-innehåll: Frågetext i sql och join_specs.sql fält omfattas av längdgränser.

Format för kopplingsspecifikationer

Fältet sql i varje kopplingsspecifikation måste innehålla exakt två element:

1. Kopplingsvillkoret med hjälp av backtick-citerade aliasreferenser:

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

2. En relationstypanteckning i följande format:

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

   Giltiga kardinalitetsvärden:

   • FROM_RELATIONSHIP_TYPE_MANY_TO_ONE
   • FROM_RELATIONSHIP_TYPE_ONE_TO_MANY
   • FROM_RELATIONSHIP_TYPE_ONE_TO_ONE
   • FROM_RELATIONSHIP_TYPE_MANY_TO_MANY

Om du utelämnar relationstypanteckningen avvisas begäran av API:et med ett parsningsfel. För flerkolumnskopplingar skapar du en separat kopplingsspecifikation för varje relation.

Övriga krav

• Tabellidentifierare: Måste använda namnområdesformat på tre nivåer (catalog.schema.table).
• Benchmark-svar: Varje referensfråga måste ha exakt ett svar med formatet inställt på SQL.
• SQL-kodfragment: Filter, uttryck och mått för SQL-fält får inte vara tomma.

Använda konversations-API:et

När du har konfigurerat ett Genie Space använder du konversations-API-slutpunkterna för att ställa frågor, hämta resultat och underhålla konversationer med flera omgångar och hålla kvar kontexten.

Starta en konversation

Starta konversation-slutpunktPOST /api/2.0/genie/spaces/{space_id}/start-conversation startar en ny konversation i ditt Genie Space.

Ersätt platshållarna med din Databricks-instans, Genie Space ID och autentiseringstoken. Exempel på ett lyckat svar följer efter begäran. Den innehåller information som du kan använda för att få åtkomst till den här konversationen igen för uppföljningsfrågor.

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

Hämta genererad SQL

Använd conversation_id och message_id i svaret för att kontrollera statusen för meddelandets generering och hämta den genererade SQL från Genie. Se GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id} för fullständig information om begäran och svar.

Ersätt dina värden med följande begäran:

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

Följande exempelsvar rapporterar meddelandeinformationen:

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
}

När fältet status är COMPLETED fylls svaret i matrisen attachments .

Om du vill ta reda på om ett svar genererades med hjälp av en betrodd tillgång kontrollerar du attachments fältet i svaret för ett query.parameters objekt. Dess närvaro indikerar att svaret kom från en betrodd tillgång.

Om du vill komma åt Genie-resonemangsspårningar kontrollerar du fältet attachments efter ett query_attachments objekt av typen GenieQueryAttachments. När den finns innehåller den det stegvisa resonemanget Genie som används för att generera svaret. Fullständig fältinformation finns i Get message API-referens.

Hämta frågeresultat

Matrisen attachments innehåller Genie-svaret. Den innehåller det genererade textsvaret (text), frågeuttrycket om det finns (query) och en identifierare som du kan använda för att hämta associerade frågeresultat (attachment_id). Ersätt platshållarna i följande exempel för att hämta det genererade frågeresultatet:

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

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

Ställ uppföljningsfrågor

När du har fått ett svar använder conversation_id du för att fortsätta konversationen. Kontext från tidigare meddelanden behålls och används i uppföljningssvar. Fullständig information om begäran och svar finns i 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?",
}

Lägga till kommentarer i meddelanden

Du kan lägga till textkommenterar i meddelanden och visa en lista över befintliga kommentarer med hjälp av API-slutpunkterna för meddelandekommentar.

Om du vill lägga till en kommentar i ett meddelande använder du slutpunkten 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>"
}

Om du vill lista befintliga kommentarer i ett meddelande använder du slutpunkten för att lista meddelandekommentarer.

Hämta utrymmes- och konversationsdata

Genie-API:et innehåller ytterligare slutpunkter för att hämta konfiguration och historiska data från befintliga utrymmen och konversationer.

Hämta utrymmeskonfiguration

När du hämtar utrymmesinformation med api:et Get Genie Space kan du inkludera serialized_space fältet i svaret genom att ange parametern include_serialized_space till true. Fältet serialized_space innehåller den serialiserade strängrepresentationen av Genie Space, inklusive instruktioner, benchmarks, kopplingar och annan konfigurationsinformation.

Använd den här serialiserade representationen med CREATE Genie Space API och Update Genie Space API för att höja upp Genie Spaces mellan arbetsytor eller skapa säkerhetskopior av utrymmeskonfigurationer.

Exempel begäran 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\"]}]}}}"
}

Referera till gamla konversationstrådar

Om du vill tillåta användare att referera till gamla konversationstrådar använder du slutpunkten GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages för att hämta alla meddelanden från en specifik konversationstråd.

Hämta konversationsdata för analys

Utrymmeshanterare kan programmatiskt hämta alla tidigare meddelanden som frågas över alla användare av ett utrymme för analys. Så här hämtar du dessa data:

1. Använd slutpunkt för att hämta alla befintliga konversationstrådar i ett utrymme.
2. För varje konversations-ID som returneras använder du GET /api/2.0/genie/spaces/{space_id}/conversations slutpunkten för att hämta listan med meddelanden för konversationen.

Metodtips och begränsningar

Metodtips för att använda Genie-API:et

Så här underhåller du prestanda och tillförlitlighet när du använder Genie-API:et:

• Implementera återförsökslogik med exponentiell backoff: API:et försöker inte skicka misslyckade begäranden igen, så lägg till en egen köhantering och exponentiell backoff. Detta hjälper ditt program att hantera tillfälliga fel, undvika onödiga upprepade begäranden och hålla sig inom dataflödesgränserna när det växer.
• Log API-svar: Implementera omfattande loggning av API-begäranden och svar för att hjälpa till med felsökning, övervakning av användningsmönster och spårningskostnader.
• Sök efter statusuppdateringar var 1:e till 5:e sekund: Fortsätt avsökningen tills en avgörande meddelandestatus, till exempel COMPLETED, FAILEDeller CANCELLED, tas emot. Begränsa frågeintervallen till maximalt 10 minuter för de flesta frågor. Om det inte finns något avgörande svar efter 10 minuter stoppar du avsökningen och returnerar ett timeout-fel eller uppmanar användaren att kontrollera frågestatusen manuellt senare.
• Använd exponentiell backoff för avsökning: Öka fördröjningen mellan omröstningar upp till högst en minut. Detta minskar onödiga begäranden för tidskrävande frågor samtidigt som snabbare frågor fortfarande kan hanteras med låg latens.
• Starta en ny konversation för varje session: Undvik att återanvända konversationstrådar mellan sessioner, eftersom detta kan minska noggrannheten på grund av oavsiktlig återanvändning av kontext.
• Upprätthålla konversationsgränser: Så här hanterar du gamla konversationer och håller dig under gränsen på 10 000 konversationer:
  1. Använd GET /api/2.0/genie/spaces/{space_id}/conversations endpoint för att se alla befintliga konversationstrådar i en plats.
  2. Identifiera konversationer som inte längre behövs, till exempel äldre konversationer eller testkonversationer.
  3. Använd DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}-slutpunkten för att ta bort konversationer programmässigt.
• Tänk på frågeresultatgränsen: Genie-API:et returnerar högst 5 000 rader per frågeresultat. Om dataanalysen kräver fler rader kan du överväga att förfina din fråga för att fokusera på en specifik delmängd av data eller använda filter för att begränsa resultatet.

Överväganden för genomströmning

Dataflödeshastigheter för den kostnadsfria nivån för Genie-konversations-API:et är bästa möjliga och beror på systemkapacitet. För att minimera missbruk och förhindra missbruk under perioder med hög användning bearbetar systemet begäranden baserat på tillgänglig kapacitet. Under normala eller låga trafikförhållanden stöder API:et begäranden till fem frågor per minut per arbetsyta. Kontakta databricks-kontoteamet om du vill ha mer dataflödessupport.

Övervaka utrymmet

När programmet har konfigurerats kan du övervaka frågor och svar i Databricks-användargränssnittet.

Uppmuntra användarna att testa utrymmet så att du lär dig mer om vilka typer av frågor de sannolikt kommer att ställa och vilka svar de får. Ge användarna vägledning som hjälper dem att börja testa utrymmet. Använd fliken Övervakning för att visa frågor och svar. Se Övervaka utrymmet.

Du kan också använda granskningsloggar för att övervaka aktivitet i ett Genie-utrymme. Se Genie Space-händelser.