De Genie Agents-API gebruiken

Integreer Genie Agents in uw eigen chatbot, agent of toepassing met de Genie Agents-API. De API biedt API’s voor de chatmodus voor statusbehoudende gegevensquery’s in natuurlijke taal (met vervolgvragen en geschiedenis) en Management API’s voor CI/CD-workflows die Genie Agents maken, configureren en implementeren in verschillende werkruimtes.

Overzicht

De Genie API biedt de volgende soorten mogelijkheden:

• API's voor chatmodus: maken het mogelijk om in applicaties, chatbots en agentframeworks gegevens op te vragen met natuurlijke taal. Deze API's ondersteunen gesprekken met statusbehoud die in de chatmodus worden gevoerd, waarbij gebruikers vervolgvragen kunnen stellen en gegevens in de loop van de tijd op een natuurlijke manier kunnen verkennen.
• Agentmodus-API's: Stel ontwikkelaars in staat om programmatisch prompts in Agent-modus te sturen, de redenering en SQL-resultaten te streamen en eindrapporten met citaties te ontvangen.
• Beheer-API's: programmatisch maken, configureren en implementeren van Genie Agents in verschillende werkruimten inschakelen. Gebruik deze API's voor CI/CD-pijplijnen, versiebeheer en geautomatiseerd agentbeheer.

Deze pagina legt uit hoe je een goed samengestelde Genie Agent voorbereidt en agenten over werkplekken heen beheert, zodat de API betrouwbare resultaten oplevert. De agent biedt de context die Genie gebruikt om vragen te interpreteren en antwoorden te genereren. Als de agent onvolledig of niet getest is, ontvangen gebruikers mogelijk nog steeds onjuiste resultaten, zelfs met een juiste API-integratie. Voor de runtime-eindpunten, verzoekformaten en responsformaten, zie de REST API-referentie die gelinkt is in de Genie API-referentie.

De setup-voorbeelden op deze pagina gebruiken direct de REST API. U kunt deze API's ook aanroepen met behulp van de Azure Databricks SDK's. Zie Databricks SDK's.

Vereisten

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-agent maken of selecteren

Een goed gestructureerde Genie Agent 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 agent 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.

Zie Een Genie Agent maken en beheren voor meer informatie over het maken van een agent en het beheren van een effectieve Genie-agent.

U kunt een nieuwe Genie-agent maken of een bestaande maken:

Een nieuwe agent maken

Maak programmatisch een Genie Agent met behulp van de Create Genie Agent-API. In het volgende voorbeeld ziet u een goed gestructureerde agent 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 agent gebruiken

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

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-agent 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: Agentconfiguratie, 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 agent:
  • 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 agent:
  • 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 agent.
  • 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 om de kwaliteit van agents te evalueren, elke vraag met een referentie-SQL-antwoord.

De niet-geëscapeerde versie van het veld serialized_space uit het voorbeeld voor het aanmaken van een agent 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 agent maakt, maakt u deze JSON-structuur en escapet u deze als een tekenreeks voor de API-aanvraag. Voor volledige schemadetails, zie de API-referentie voor Create Genie Agent.

Validatieregels voor serialized_space

De serialized_space JSON moet voldoen aan de volgende validatieregels. JSON die niet geldig is, wordt geweigerd tijdens het maken of bijwerken van de agent.

Versie

• Het versieveld: verplicht. Gebruik 2 voor nieuwe agenten. 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 agent.

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

Genie API-naslagwerk

De voorgaande secties laten zien hoe je een Genie Agent voorbereidt en agenten over werkplekken heen beheert. Voor het starten van gesprekken, het verzenden van berichten en het ophalen van resultaten van Genie Agents, zie de REST API-referentie:

• Agentmodus API's: Stuur prompts in Agentmodus, stream de redenering en SQL-resultaten, en ontvang eindrapporten met citaties. Zie de Agent Mode API-referentie.
• Chatmodus API's: Start een chatmodus conversatief, stel vervolgvragen en haal gegenereerde SQL, queryresultaten en visualisaties op. Zie de Conversation API-referentie.

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 en onnodige herhalingsaanvragen te voorkomen 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 agent weer te geven.
  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.

De agent bewaken

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

Moedig gebruikers aan om de agent 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 de agent te testen. Gebruik het tabblad Bewaking om vragen en antwoorden weer te geven. Zie De agent bewaken.

U kunt ook auditlogboeken gebruiken om activiteiten in een Genie-agent te bewaken. Zie Genie Agent-gebeurtenissen.