Använda API:et Genie Agents

Integrera Genie-agenter i din egen chattrobot, agent eller program med Genie Agents-API:et. API:et tillhandahåller chattläges-API:er för tillståndsfull naturlig språklig datasökning (med uppföljningsfrågor och historik) samt Management-API:er för CI/CD-arbetsflöden som skapar, konfigurerar och distribuerar Genie Agents över arbetsytor.

Översikt

Genie API erbjuder följande typer av funktioner:

• Chattläges-API:er: Möjliggör naturlig språklig datasökning i applikationer, chattbotar och agentramverk. Dessa API:er stödjer tillståndsfulla konversationer skapade i chattläge där användare kan ställa följdfrågor och utforska data naturligt över tid.
• API:er i agentläge: Gör det möjligt för utvecklare att programmatiskt skicka prompts i agentläge, strömma resonemang och SQL-resultat samt ta emot slutrapporter med referenser.
• Hanterings-API:er: Aktivera programmatiskt skapande, konfiguration och distribution av Genie-agenter på arbetsytor. Använd dessa API:er för CI/CD-pipelines, versionskontroll och automatiserad agenthantering.

Den här sidan förklarar hur man förbereder en väl kurerad Genie-agent och hanterar agenter över arbetsytor så att API:et ger tillförlitliga resultat. Agenten tillhandahåller den kontext som Genie använder för att tolka frågor och generera svar. Om agenten är ofullständig eller oprövad kan användarna fortfarande få felaktiga resultat även med en korrekt API-integrering. För körtidsändpunkter, förfrågningsformat och svarsformat, se REST API-referensen som är länkad i Genie API-referensen.

Setup-exemplen på denna sida 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 en Genie-agent

En välstrukturerad Genie-agent 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 din agent 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 Benchmarks.

Mer information om hur du skapar en agent finns i Skapa och hantera en Genie-agent och Kurera en effektiv Genie-agent.

Du kan antingen skapa en ny Genie-agent eller använda en befintlig:

Skapa en ny agent

Skapa en Genie Agent programmatiskt med hjälp av API:et Skapa Genie-agent. I följande exempel visas en välstrukturerad agent 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 en befintlig agent

Om du redan har en Genie-agent kan du hitta utrymmes-ID:t med List Genie Agents API. Du kan även hitta och kopiera space-ID:t från Genie Agent-fliken Inställningar.

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 genie-agenten. 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: Agentkonfiguration, inklusive:
  • 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 agenten:
  • 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 agenten:
  • 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 agenten.
  • 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 agentkvalitet, var och en med ett SQL-svar med grundsanning.

Den ej kapslade versionen av serialized_space fältet från exemplet med skapa agenten 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 din agent 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 api-referensen Skapa Genie-agent.

Verifieringsregler för serialized_space

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

Version

• Versionsfält: Obligatoriskt. Använd 2 för nya agenter. 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 i agenten.

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 agent.
• 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.

Genie API-referens

De föregående avsnitten visar hur man förbereder en Genie Agent och hanterar agenter över arbetsytor. För att starta konversationer, skicka meddelanden och hämta resultat från Genie Agents, se REST API-referensen:

• API:er i agentläge: Skicka prompts i agentläge, strömma dess resonemang och SQL-resultat samt ta emot slutrapporter med källhänvisningar. Se Agent mode API-referensen.
• API:er i chattläge: Starta en chattkonversation, ställ följdfrågor och hämta genererad SQL, frågeresultat och visualiseringar. Se referensen för Conversation API.

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 och undvika onödiga upprepade begäranden 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-ändpunkten för att se alla befintliga konversationstrådar i en agent.
  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.

Övervaka agenten

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

Uppmuntra användarna att testa agenten 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 agenten. Använd fliken Övervakning för att visa frågor och svar. Se Övervaka agenten.

Du kan också använda granskningsloggar för att övervaka aktivitet i en Genie-agent. Se Genie Agent-händelser.