メインコンテンツまでスキップ
に最終更新

Genie Agent APIを使用する

Genie Agents APIを使用して、Genie Agentを独自のチャットボット、エージェント、またはアプリケーションに統合します。このAPIは、ステートフルな自然言語データクエリ（フォローアップの質問と履歴を含む）のためのChatモードAPIと、ワークスペース間でGenie Agentを作成、構成、デプロイするためのCI/CDワークフロー向け管理APIを提供します。

注記

Genieエージェントは以前、Genie Spaceとして知られていました。

概要​

Genie APIは、以下の種類の機能を提供します：

  • チャットモード APIs : アプリケーション、チャットボット、エージェントフレームワーク内での自然言語によるデータクエリを可能にします。これらの APIs は、チャットモードで作成されたステートフルな会話をサポートしており、ユーザーはフォローアップの質問を行い、時間をかけて自然にデータを探索できます。
  • Agent モード APIs : 開発者が Agent モードでプロンプトをプログラムから送信し、推論と SQL の結果をストリームし、引用付きの最終レポートを受け取れるようにします。
  • 管理APIs ：ワークスペース全体でのGenie Agentのプログラムによる作成、構成、デプロイを可能にします。これらのAPIsは、CI/CDパイプライン、バージョン管理、および自動化されたエージェント管理に利用できます。

このページでは、よくキュレーションされたGenie Agentの準備方法と、ワークスペース間のエージェント管理方法を説明しています。これによりAPIが信頼できる結果を返すことができるようにします。エージェントはGenieが質問を解釈し答えを生成するための文脈を提供します。エージェントが不完全または未検証の場合、正しいAPI統合があってもユーザーは誤った結果を受け取ることがあります。ランタイムEndpoint、リクエストフォーマット、レスポンス形式については、 Genie APIリファレンスにリンクされたREST APIリファレンスを参照してください。

このページのセットアップ例では、REST APIを直接使用しています。Databricks SDKを使用してこれらのAPIを呼び出すこともできます。Databricks SDKを参照してください。

前提条件​

To send prompts using the Chat mode or Agent mode APIs, you must have:

  • At least CAN VIEW permission on the Genie Agent. See Genie Agent ACLs.
  • At least SELECT privileges on the Unity Catalog data objects that the agent uses. Genie evaluates data access with your own Unity Catalog permissions, so responses include only data you can access.

To create or update agents using the Management APIs, you must have:

  • The Databricks SQL access entitlement. See Access entitlements.
  • At least CAN USE permission on a pro or serverless SQL warehouse.
  • At least SELECT privileges on the Unity Catalog data objects that the agent uses.
  • At least CAN EDIT permission on any existing Genie Agent that you update.

使い始める​

Databricks認証を構成します。​

ブラウザにアクセスできるユーザーが存在する本番運用ユースケースの場合は、ユーザー向けOAuth (OAuth U2M)を使用してください。ブラウザベースの認証が不可能な状況では、Service Principalを使用してAPIで認証します。See OAuth for Service Principals (OAuth M2M)を参照してください。Service Principalは、必要なデータとSQLウェアハウスにアクセスする権限を持っている必要があります。

詳細を収集する​

  • ワークスペースインスタンス名 ：DatabricksワークスペースURLからワークスペースインスタンス名を見つけてコピーします。URL内のワークスペース識別子に関する詳細については、ワークスペースオブジェクトの識別子を取得するを参照してください。

    例： https://cust-success.cloud.databricks.com/

  • warehouse ID: 少なくとも CAN USE 権限を持つ SQLウェアハウスの ID が必要です。warehouse ID を見つけるには:

    1. ワークスペースの SQLウェアハウス に移動します。
    2. 使用するwarehouseを選択します。
    3. URLまたはwarehouseの詳細ページからwarehouse IDをコピーします。

    または、List warehouses Endpoint GET /api/2.0/sql/warehousesを使用して、アクセス権のあるすべてのSQLウェアハウスのリストをプログラムで取得できます。応答にはwarehouse IDが含まれます。

Genie Agentを作成または選択します​

十分に構造化されたGenie Agentには、次の特性があります：

  • 適切にアノテーションが付けられたデータを使用します ：Genieはテーブルのメタデータとカラムコメントに依存しています。Unity Catalogデータソースに明確で分かりやすいコメントがあることを確認してください。
  • ユーザーによるテスト済み ：エンド ユーザーから想定される質問をして、エージェントをテストします。テストを使用して、SQL クエリーの例を作成し、改善します。
  • **会社固有のコンテキストが含まれます**: 指示、SQLの例、および関数を追加します。SQLの例と指示を追加するを参照してください。少なくとも5つのテスト済みSQLクエリーを目指してください。
  • 精度をテストするベンチマークを使用します ：想定されるユーザーの質問に基づいて、少なくとも5つのベンチマーク質問を追加してください。ベンチマークを参照してください。

エージェントの作成に関する詳細は、Genie Agentの作成と管理および効果的なGenie Agentのキュレーションを参照してください。

新しい Genie Agent を作成するか、既存の Genie Agent を使用できます。

Create Genie Agent APIを使用して、プログラムでGenie Agentを作成します。以下の例は、ベストプラクティスに従った適切に構造化されたエージェントを示しています。プレースホルダーを値に置き換えてください：

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

serialized_spaceフィールドの理解​

serialized_spaceフィールドは、Genie Agentの構成とデータソースを定義するJSON文字列です。APIリクエストでは、このJSONは文字列としてエスケープする必要があります。フィールドの内容：

  • バージョン ：下位互換性のためのスキーマバージョン番号。以下の例に示すように、2 を使用します。

  • config ：エージェント構成（以下を含む）：

    • **sample_questions：** ユーザーをガイドするための質問例。各質問には**ID**（32文字の16進数文字列）と**質問**（文字列の配列）が必要です。

  • data_sources ：エージェントが利用できるデータソース：

    • tables ： identifier （3 レベルの名前空間）、任意の description 、および任意の column_configs を持つ table オブジェクトの配列。
    • **メトリクスビュー**: メトリクスビューオブジェクトの配列（テーブルと同じ構造）。

  • 指示 : エージェント向けの構造化された指示:

    • LLM向けの**text_instructions**: 高レベルのガイダンス
    • example_question_sqls : SQL の回答を伴う質問の例で、オプションで パラメーター と usage_guidance を伴います。
    • sql_functions ：エージェントが利用できるSQL関数への参照です。
    • join_specs ：テーブル間の事前定義された結合リレーションシップ。sqlフィールドは、結合条件（バッククォートで囲まれたエイリアス参照を使用）、およびリレーションシップタイプの注釈（例: "--rt=FROM_RELATIONSHIP_TYPE_MANY_TO_ONE--"）という2つの要素を正確に必要とします。「結合仕様の形式」を参照してください。
    • SQLスニペット ：再利用可能な フィルター 、 式 、および メジャー 。

  • **ベンチマーク：**エージェントの品質を評価するための質問で、それぞれに正解SQLの**回答**が含まれます。

エージェント作成例のserialized_spaceフィールドのエスケープされていないバージョンは次のとおりです：

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

エージェントを構築する際は、このJSON構造を作成し、APIリクエストのために文字列としてエスケープしてください。完全なスキーマの詳細については、Genie Agent APIの作成リファレンスを参照してください。

serialized_spaceの検証ルール​

serialized_space JSONは、以下の検証ルールに準拠する必要があります。無効なJSONは、エージェントの作成または更新中に拒否されます。

バージョン​

  • バージョンフィールド ：必須。新しいエージェントには 2 を使用してください。バージョン番号は下位互換性のために存在します。

ID形式​

すべてのIDフィールドは、 32文字の小文字の16進数の文字列 （ハイフンなしのUUID形式）である必要があります。

  • 検証 ： a1b2c3d4e5f60000000000000000000a
  • 無効： a1b2c3d4e5f6（短すぎます）、A1B2C3D4E5F60000000000000000000A（大文字）、a1b2c3d4-e5f6-0000-0000-00000000000a（ハイフンが含まれています）

IDが必要です：

  • 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 (ベンチマークが含まれている場合)

次のコマンドを使用して有効なIDを生成できます：

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

これにより、時系列に並べられたUUIDが生成されます。シーケンスで生成されたIDは、作成順にアルファベット順に並べ替えられ、ソート要件を自動的に満たします。

ソート要件​

IDまたは識別子を含むコレクションは、事前にソートされている必要があります。システムは、配列がすでにソートされていることを検証し、ソートされていない入力を拒否します。

コレクション

並べ替えキー

data_sources.tables

identifier （アルファベット順）

data_sources.metric_views

identifier （アルファベット順）

data_sources.tables[].column_configs

column_name （アルファベット順）

data_sources.metric_views[].column_configs

column_name （アルファベット順）

config.sample_questions

id （アルファベット順）

instructions.text_instructions

id （アルファベット順）

instructions.example_question_sqls

id （アルファベット順）

instructions.sql_functions

(id, identifier) タプル（アルファベット順）

instructions.join_specs

id （アルファベット順）

instructions.sql_snippets.filters

id （アルファベット順）

instructions.sql_snippets.expressions

id （アルファベット順）

instructions.sql_snippets.measures

id （アルファベット順）

benchmarks.questions

id （アルファベット順）

コレクション

並べ替えキー

data_sources.tables

identifier （アルファベット順）

data_sources.metric_views

identifier （アルファベット順）

data_sources.tables[].column_configs

column_name （アルファベット順）

data_sources.metric_views[].column_configs

column_name （アルファベット順）

config.sample_questions

id （アルファベット順）

instructions.text_instructions

id （アルファベット順）

instructions.example_question_sqls

id （アルファベット順）

instructions.sql_functions

(id, identifier) タプル（アルファベット順）

instructions.join_specs

id （アルファベット順）

instructions.sql_snippets.filters

id （アルファベット順）

instructions.sql_snippets.expressions

id （アルファベット順）

instructions.sql_snippets.measures

id （アルファベット順）

benchmarks.questions

id （アルファベット順）

一意性制約​

  • 質問ID : config.sample_questionsとbenchmarks.questionsのすべてのIDは、両方のコレクションで一意である必要があります。
  • 命令ID : text_instructions、example_question_sqls、sql_functions、join_specs、およびすべてのsql_snippetsタイプのすべてのIDは一意である必要があります。
  • 列構成 : (table_identifier, column_name) の組み合わせは、エージェント内で一意である必要があります。

サイズと長さの制限​

  • 文字列の長さ ：個々の文字列要素は 25,000 文字に制限されています。
  • 配列サイズ ：繰り返しフィールドは10,000項目に制限されています。
  • **テキスト指示**: エージェントあたり最大1つのテキスト指示が許可されます。
  • テーブルとメトリクスビュー ：ワークスペース固有の制限が適用されます。
  • SQL ：sqlフィールドとjoin_specs.sqlフィールドのクエリーテキストは、文字数制限の対象となります。

結合仕様の形式​

各結合仕様のsqlフィールドには、 厳密に2つの要素 を含める必要があります。

  1. バッククォートで引用されたエイリアスの参照を使用する結合条件:

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

  2. 次の形式のリレーションシップタイプの注釈：

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

    有効なカーディナリティ値：

    • FROM_RELATIONSHIP_TYPE_MANY_TO_ONE
    • FROM_RELATIONSHIP_TYPE_ONE_TO_MANY
    • FROM_RELATIONSHIP_TYPE_ONE_TO_ONE
    • FROM_RELATIONSHIP_TYPE_MANY_TO_MANY

関係タイプの注釈を省略すると、API は解析エラーでリクエストを拒否します。複数列の結合では、各関係ごとに個別の結合仕様を作成します。

その他の要件​

  • テーブル識別子 ：3レベルの名前空間形式（catalog.schema.table）を使用する必要があります。
  • **ベンチマークの回答**: 各ベンチマーク質問には、フォーマットがSQLに設定された回答が正確に1つ必要です。
  • SQLスニペット : フィルター、式、およびメジャーのSQLフィールドは空にすることはできません。

Genie APIリファレンス​

前述のセクションでは、Genie Agentの準備方法と、ワークスペース間でのエージェントの管理方法について説明しました。Genie Agentでの会話の開始、メッセージの送信、結果の取得については、REST APIリファレンスを参照してください：

  • Agent mode APIs : エージェントモードでプロンプトを送信し、その推論とSQL結果をストリームし、引用付きの最終レポートを受け取ります。エージェントモードAPIリファレンスを参照してください。
  • チャットモードAPIs : チャットモードの会話を起動し、フォローアップの質問を行い、生成されたSQL、クエリー結果、および可視化を取得します。Conversation APIリファレンスを参照してください。

ベストプラクティスと制限​

Genie API を使用するためのベストプラクティス​

Genie API を使用する際に性能と信頼性を維持するには：

  • 指数バックオフによる再試行ロジックの実装 ：APIは失敗したリクエストを自動的に再試行しないため、独自のキューイングと指数バックオフを追加してください。これにより、アプリケーションは一時的な障害を処理し、成長するにつれて不要な繰り返しリクエストを回避できます。
  • Log API responses ：デバッグ、使用パターンのモニタリング、およびコストの追跡に役立てるため、API リクエストと応答の包括的なLog記録を実装します。
  • 1～5秒ごとにステータス更新をポーリング : COMPLETED、FAILED、またはCANCELLEDなどの決定的なメッセージステータスが受信されるまでポーリングを続行します。ほとんどのクエリーでは、ポーリングを10分に制限します。10分後に決定的な応答がない場合は、ポーリングを停止してタイムアウトエラーを返すか、後でクエリーのステータスを手動で確認するようにユーザーに促します。
  • ポーリングに指数関数的バックオフを使用します ：ポーリング間の遅延を最大1分まで増やします。これにより、実行時間の長いクエリーの不要なリクエストが削減され、高速なクエリーでは低遅延が可能です。
  • セッションごとに新しい会話を起動してください。セッション間で会話スレッドを再利用すると、意図しないコンテキストの再利用により精度が低下する可能性があるため、避けてください。
  • 会話の制限の維持 : 古い会話を管理し、200,000 件の会話の制限内に収めるには:
    1. GET /api/2.0/genie/spaces/{space_id}/conversations Endpoint を使用して、エージェント内の既存のすべての会話スレッドを表示します。
    2. 古い会話やテスト会話など、不要になった会話を特定します。
    3. DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id} Endpoint を使用して、プログラムで会話を削除します。

エージェントを監視する​

アプリケーションがセットアップされた後、Databricks UI で質問と応答をモニタリングできます。

ユーザーがエージェントをテストするように促し、ユーザーが尋ねる可能性のある質問の種類と、受け取る応答について学びます。ユーザーがエージェントのテストを開始するのに役立つように、ガイダンスを提供します。質問と応答を表示するには、 モニタリング タブを使用します。エージェントを監視するを参照してください。

Genie Agentのアクティビティを監視するために、監査Logsを使用することもできます。Genie Agent イベントをご覧ください。

このページの見出し