`ai_classify` 関数

適用対象: 「はい」のチェックマーク Databricks SQL Databricks Runtime

ai_classify()関数は、指定したカスタムラベルに従ってテキストコンテンツを分類します。基本的な分類には単純なラベル名を使用するか、ラベルの説明と指示を追加して、カスタマーサポートのルーティング、ドキュメントの分類、コンテンツ分析などのユースケースの精度を向上させることができます。

この関数は、VARIANTなどの他の AI 関数からのテキストまたはai_parse_document出力を受け取り、構成可能なワークフローを可能にします。

ai_classifyで反復処理する UI バージョンについては、「分類」を参照してください。

データのセキュリティ

ドキュメントデータは、Databricks セキュリティ境界内で処理されます。 DatabricksはAI関数呼び出しに渡されるパラメータを保存しませんが、Databricksランタイムバージョンなどのメタデータ実行の詳細は保持します。

要件

Apache 2.0 ライセンス

Databricks では、該当する使用条件に準拠するために、これらのライセンスを確認することをお勧めしています。 Databricks の内部ベンチマークに従ってパフォーマンスが向上するモデルが将来出現した場合、Databricks によってモデルが変更される可能性があります (および、このページで提供されている該当するライセンスの一覧)。

この関数を利用するモデルは、Model Serving Foundation Model API を使用して使用できるようになります。 Databricks で使用できるモデルと、それらのモデルの使用を管理するライセンスとポリシーについては、該当するモデルの用語を参照してください。

Azure Databricksの内部ベンチマークに従ってパフォーマンスが向上するモデルが出現した場合、Databricks によってモデルが変更され、ドキュメントが更新される可能性があります。

この関数は、一部のリージョンでのみ使用できます。 AI 関数の可用性に関するページを参照してください。
セキュリティとコンプライアンスの強化アドオンを使用するワークスペースの場合は、
- 適切なai_classifyについては、の地域サポートを参照してください。
- ワークスペースで有効にする方法については、「Azure Databricksプレビューの管理」を参照してください。
この関数は、Pro または Classic SQL ウェアハウスでは使用できません。
Databricks Runtime 15.4 LTS以上のものが必要です。最高のパフォーマンスと最新機能へのアクセスのために、Databricks Runtime 18.2以上が推奨されます。
ノートブックと Databricks ワークフローには、サーバーレスコンピューティングが必要です。
Databricks SQL の価格ページを確認してください。

Tip

Databricks では、を使用することをお勧めします。バージョン 1.0 は、これらの機能をサポートしていないレガシインターフェイスであり、新規または運用環境のワークロードには推奨されません。

バージョン 2.0 では、次の機能がサポートされています。

精度を向上させるラベルの説明
複数ラベル分類
グローバルな手順
バージョン 1.0 の 20 と比較して、最大 500 個のラベル
VARIANT のようなアップストリーム AI 関数からの入力 ai_parse_document
エラー情報を含む構造化 VARIANT を返します。

バージョン 2.1 では、次の機能もサポートされています。

返された各ラベルの信頼度スコア (有効) enableConfidenceScores
返される各ラベルを説明する根拠(ゝ〚〘) enableRationales

バージョン 2.1 では、 response の各分類は、プレーンラベル文字列ではなく、 value キーを持つラベルごとのオブジェクトです。この出力形状の変更は、新しいオプションが無効になっている場合でも、すべてのバージョン 2.1 呼び出しに適用されます。バージョン 2.0 から 2.1 への移行は、出力互換ではありません。直接読み取るのではなく、 value キーからラベルを読み取るためにクエリとダウンストリームコードを更新します。

バージョンを明示的にピン留めするには、 options => map('version', '2.1')渡します。

構文

バージョン 2.1 (推奨)

ai_classify(content, labels [, options])

バージョン 2

ai_classify(content, labels [, options])

バージョン 1 (レガシ)

ai_classify(content, labels [, options])

議論

バージョン 2.1 (推奨)

content: VARIANT または STRING 式。以下のいずれかを受け入れます:
- 生テキスト STRING
- 別の AI 関数によって生成される VARIANT ( ai_parse_document や ai_extractなど)
labels: 分類ラベルを定義する STRING 式。これには、文字列リテラル、または Delta テーブル列を含む、 STRINGに評価される任意の SQL 式を指定できます。ラベルは次のようになります。
- 単純なラベル: ラベル名の JSON 配列。
```
["urgent", "not_urgent"]
```
- 説明付きのラベル: ラベル名を説明にマッピングする JSON オブジェクト。ラベルの説明は 0 ~ 1000 文字にする必要があります。
```
{
  "billing_error": "Payment, invoice, or refund issues",
  "product_defect": "Any malfunction, bug, or breakage",
  "account_issue": "Login failures, password resets"
}
```
各ラベルは 1 ~ 100 文字にする必要があります。 labels には、少なくとも 2 つのラベルと 500 個以下のラベルを含む必要があります。 500 を超える分類については、「500 以上のラベルを含む分類」を参照してください。
options: 構成オプションを含む省略可能な MAP<STRING, STRING> :
- version: 移行をサポートするバージョン切り替え ("1.0"、 "2.0"、または "2.1")。既定値は入力の種類に基づいていますが、 "1.0"にフォールバックします。
- instructions:分類の品質を向上させるためのタスクとドメインのグローバルな説明。 20,000 文字未満にする必要があります。
- multilabel: 複数のカテゴリが適用されたときに複数のラベルを返す "true" に設定します。既定値は "false" (単一ラベル分類) です。
- enableConfidenceScores: "true" に設定すると、返されるラベルごとに confidence_score (0 ~ 1) が含まれます。バージョン "2.1"が必要です。既定値は "false" です。
- enableRationales: "true" に設定すると、返された各ラベルを説明する短い根拠が入力テキストに含まれます。バージョン "2.1"が必要です。既定値は "false" です。

バージョン 2

content: VARIANT または STRING 式。以下のいずれかを受け入れます:
- 生テキスト STRING
- 別の AI 関数によって生成される VARIANT ( ai_parse_document や ai_extractなど)
labels: 分類ラベルを定義する STRING 式。これには、文字列リテラル、または Delta テーブル列を含む、 STRINGに評価される任意の SQL 式を指定できます。ラベルは次のようになります。
- 単純なラベル: ラベル名の JSON 配列。
```
["urgent", "not_urgent"]
```
- 説明付きのラベル: ラベル名を説明にマッピングする JSON オブジェクト。ラベルの説明は 0 ~ 1000 文字にする必要があります。
```
{
  "billing_error": "Payment, invoice, or refund issues",
  "product_defect": "Any malfunction, bug, or breakage",
  "account_issue": "Login failures, password resets"
}
```
各ラベルは 1 ~ 100 文字にする必要があります。 labels には、少なくとも 2 つのラベルと 500 個以下のラベルを含む必要があります。 500 を超える分類については、「500 以上のラベルを含む分類」を参照してください。
options: 構成オプションを含む省略可能な MAP<STRING, STRING> :
- version: 移行をサポートするバージョンスイッチ (v1 動作の場合は"1.0" 、v2 動作の場合は "2.0" )。既定値は入力の種類に基づいていますが、 "1.0"にフォールバックします。
- instructions:分類の品質を向上させるためのタスクとドメインのグローバルな説明。 20,000 文字未満にする必要があります。
- multilabel: 複数のカテゴリが適用されたときに複数のラベルを返す "true" に設定します。既定値は "false" (単一ラベル分類) です。

バージョン 1 (レガシ)

content: 分類するテキストを含む STRING 式。
labels: 予期される出力分類ラベルを持つ ARRAY<STRING> リテラル。 2 個以上 20 個以下の要素を含む必要があります。各ラベルは 1 ~ 50 文字にする必要があります。
options: 構成オプションを含む省略可能な MAP<STRING, STRING> :
- version: 移行をサポートするバージョンスイッチ (v1 動作の場合は"1.0" 、v2 動作の場合は "2.0" )。既定値は入力の種類に基づいていますが、 "1.0"にフォールバックします。

戻り値

バージョン 2.1 (推奨)

次を含む VARIANT を返します。

{
  "response": [{ "value": "label_name", "confidence_score": 0.97, "rationale": "Short justification for the label." }],
  "metadata": {
    "version": "2.1"
  },
  "error_message": null // null on success, or error message on failure
}

response内の各要素は、プレーンなラベル文字列ではなく、value キーを持つラベルごとのオブジェクトです。 enableConfidenceScoresが"true"されると、各オブジェクトにもconfidence_score (0 から 1) が含まれます。 enableRationalesが"true"されると、各オブジェクトにもrationaleが含まれます。両方のオプションを有効にすると、各オブジェクトのキーの順序が value、 confidence_score、 rationaleされます。

response フィールドには次のものが含まれます。

単一ラベルモード (既定): 最適に一致するラベルを含む 1 つの要素を含む配列
複数ラベルモード (multilabel: "true"): 複数のカテゴリが適用される場合に複数のラベルを持つ配列
ラベル名は、 labels パラメーターで指定されているものと完全に一致します

NULLがcontentされている場合、またはコンテンツを分類できない場合は、NULLを返します。

バージョン 2

次を含む VARIANT を返します。

{
  "response": ["label_name"], // Array with single label (or multiple if multilabel=true)
  "metadata": {
    "version": "2.0"
  },
  "error_message": null // null on success, or error message on failure
}

response フィールドには次のものが含まれます。

単一ラベルモード (既定): 最適に一致するラベルを含む 1 つの要素を含む配列
複数ラベルモード (multilabel: "true"): 複数のカテゴリが適用される場合に複数のラベルを持つ配列
ラベル名は、 labels パラメーターで指定されているものと完全に一致します

NULLがcontentされている場合、またはコンテンツを分類できない場合は、NULLを返します。

バージョン 1 (レガシ)

STRINGを返します。この値は、labels 引数で指定された文字列のいずれかとマッチします。

NULLがcontentされている場合、またはコンテンツを分類できない場合は、NULLを返します。

例

バージョン 2.1 (推奨)

単純なラベル - ラベル名のみ

バージョン 2.1 では、新しいオプションが無効になっている場合でも、各分類はプレーン文字列ではなく value キーを持つラベルごとのオブジェクトです。

> SELECT ai_classify(
    'My password is leaked.',
    '["urgent", "not_urgent"]',
    MAP('version', '2.1')
  );
 {
   "response": [{"value": "urgent"}],
   "metadata": {
     "version": "2.1"
   },
   "error_message": null
 }

信頼度スコア付き

> SELECT ai_classify(
    'My password is leaked.',
    '["urgent", "not_urgent"]',
    MAP('version', '2.1', 'enableConfidenceScores', 'true')
  );
 {
   "response": [{"value": "urgent", "confidence_score": 0.97}],
   "metadata": {
     "version": "2.1"
   },
   "error_message": null
 }

合理性を持つ

> SELECT ai_classify(
    'My password is leaked.',
    '["urgent", "not_urgent"]',
    MAP('version', '2.1', 'enableRationales', 'true')
  );
 {
   "response": [{"value": "urgent", "rationale": "A leaked password is a security incident requiring immediate action."}],
   "metadata": {
     "version": "2.1"
   },
   "error_message": null
 }

信頼度スコアと合理性 (マルチラベル)

> SELECT ai_classify(
    'Customer wants refund and reports product arrived broken.',
    '{
      "billing_issue": "Payment or refund requests",
      "product_defect": "Damaged or malfunctioning items"
    }',
    MAP('version', '2.1', 'multilabel', 'true', 'enableConfidenceScores', 'true', 'enableRationales', 'true')
  );
 {
   "response": [
     {"value": "billing_issue", "confidence_score": 0.91, "rationale": "Customer explicitly requests a refund."},
     {"value": "product_defect", "confidence_score": 0.88, "rationale": "Reports the product arrived broken."}
   ],
   "metadata": {
     "version": "2.1"
   },
   "error_message": null
 }

を使用したコンポーザビリティ `ai_parse_document`

> WITH parsed_docs AS (
    SELECT
      path,
      ai_parse_document(
        content,
        MAP('version', '2.0')
      ) AS parsed_content
    FROM READ_FILES('/Volumes/support/tickets/', format => 'binaryFile')
  )
  SELECT
    path,
    ai_classify(
      parsed_content,
      '["billing_error", "product_defect", "account_issue", "feature_request"]',
      MAP('version', '2.1', 'instructions', 'Customer support ticket classification.')
    ) AS ticket_category
  FROM parsed_docs;

バッチ分類

> SELECT
    description,
    ai_classify(
      description,
      '["clothing", "shoes", "accessories", "furniture", "electronics"]',
      MAP('version', '2.1')
    ) AS category
  FROM products
  LIMIT 10;

500 以上のラベルを使用した分類

500 を超えるラベルで分類するには、ドキュメントとラベルを埋め込み、ドキュメントごとに上位 k 個のラベルを取得してから、小さなサブセットで ai_classify を実行することをお勧めします。

詳細なチュートリアルについては、「チュートリアル: 500 以上のラベルを持つドキュメントを分類する」を参照してください。

バージョン 2

単純なラベル - ラベル名のみ

> SELECT ai_classify(
    'My password is leaked.',
    '["urgent", "not_urgent"]'
  );
 {
   "response": ["urgent"],
   "metadata": {
     "version": "2.0"
   },
   "error_message": null
 }

説明付きのラベル

> SELECT ai_classify(
    'Customer cannot complete checkout due to payment processing error.',
    '{
      "billing_error": "Payment, invoice, or refund issues",
      "product_defect": "Any malfunction, bug, or breakage",
      "account_issue": "Login failures, password resets",
      "feature_request": "Customer suggestions for improvements"
    }'
  );
 {
   "response": ["billing_error"],
   "metadata": {
     "version": "2.0"
   },
   "error_message": null
 }

デルタテーブルのラベル

デルタテーブルからラベルを JSON 文字列に変換して渡します。たとえば、スキーマ news_topics(topic STRING, description STRING)を持つラベルテーブルを指定すると、次のようにラベルを ai_classify に渡すことができます。

SELECT
  ai_classify(
    "Leicester City Wins Premier League Title at 5000-1 Odds",
    l.labels,
    MAP('version', '2.0')
  ) AS classification
FROM (
  SELECT to_json(map_from_entries(collect_list(struct(topic, description)))) AS labels
  FROM news_topics
) l;

グローバル命令の使用

> SELECT ai_classify(
    'User reports app crashes on startup after update.',
    '["critical", "high", "medium", "low"]',
    MAP('instructions', 'Classify bug severity based on user impact and frequency.')
  );
 {
   "response": ["critical"],
   "metadata": {
     "version": "2.0"
   },
   "error_message": null
 }

複数ラベル分類

> SELECT ai_classify(
    'Customer wants refund and reports product arrived broken.',
    '{
      "billing_issue": "Payment or refund requests",
      "product_defect": "Damaged or malfunctioning items",
      "shipping_issue": "Delivery problems"
    }',
    MAP('version', '2.0','multilabel', 'true')
  );
 {
   "response": ["billing_issue", "product_defect"],
   "metadata": {
     "version": "2.0"
   },
   "error_message": null
 }

バージョン 1 (レガシ)

> SELECT ai_classify("My password is leaked.", ARRAY("urgent", "not urgent"));
  urgent

> SELECT
    description,
    ai_classify(description, ARRAY('clothing', 'shoes', 'accessories', 'furniture')) AS category
  FROM
    products
  LIMIT 10;

制限事項

バージョン 2.1 (推奨)

バージョン 2.1 の制限事項:

この関数は、Azure Databricks SQL クラシックでは使用できません。
この関数は Views では使用できません。
ラベル名はそれぞれ 1 ~ 100 文字にする必要があります。
labels パラメーターには、2 ~ 500 個の一意のラベルが含まれている必要があります。
ラベルの説明はそれぞれ 0 ~ 1,000 文字にする必要があります。
最大コンテキストサイズは100万トークンです。

バージョン 2

バージョン 2 の制限事項:

この関数は、Azure Databricks SQL クラシックでは使用できません。
この関数は Views では使用できません。
ラベル名はそれぞれ 1 ~ 100 文字にする必要があります。
labels パラメーターには、2 ~ 500 個の一意のラベルが含まれている必要があります。
ラベルの説明はそれぞれ 0 ~ 1,000 文字にする必要があります。
最大コンテキストサイズは100万トークンです。

バージョン 1 (レガシ)

バージョン 1 (レガシ) の制限事項:

この関数は、Azure Databricks SQL クラシックでは使用できません。
この関数は Views では使用できません。
ラベル名はそれぞれ 1 ~ 50 文字にする必要があります。
labels配列には、2 ~ 20 個のラベルが含まれている必要があります。
content入力は、128,000 トークン (約 300,000 文字) 未満である必要があります。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-08-24

ai_classify 関数

データのセキュリティ

要件

構文

バージョン 2.1 (推奨)

バージョン 2

バージョン 1 (レガシ)

議論

バージョン 2.1 (推奨)

バージョン 2

バージョン 1 (レガシ)

戻り値

バージョン 2.1 (推奨)

バージョン 2

バージョン 1 (レガシ)

例

バージョン 2.1 (推奨)

単純なラベル - ラベル名のみ

信頼度スコア付き

合理性を持つ

信頼度スコアと合理性 (マルチラベル)

を使用したコンポーザビリティ ai_parse_document

バッチ分類

500 以上のラベルを使用した分類

バージョン 2

単純なラベル - ラベル名のみ

説明付きのラベル

デルタ テーブルのラベル

グローバル命令の使用

複数ラベル分類

バージョン 1 (レガシ)

制限事項

バージョン 2.1 (推奨)

バージョン 2

バージョン 1 (レガシ)

関連する関数

フィードバック

その他のリソース

`ai_classify` 関数

を使用したコンポーザビリティ `ai_parse_document`

デルタテーブルのラベル