AI_COMPLETE 構造化出力¶
AI_COMPLETE を使用すると、補完応答が従う必要がある JSON スキーマまたは SQL 型リテラルを提供して、構造化出力を作成できます。構造化された出力により、 AI データパイプラインでの後処理が不要になり、決定論的応答を必要とするシステムとのシームレスな統合が可能になります。 AI_COMPLETE は、生成された各トークンを構造化出力定義に対して確認することで、確実に応答が指定された型構造に準拠するようにします。
AI_COMPLETE でサポートされているモデルはすべて構造化出力をサポートしていますが、最も強力なモデルは通常、より質の高い応答を生成します。
型リテラルと AI_COMPLETE の使用¶
型リテラルを使用すると、Snowflakeの SQL および JSON 型間の組み込みマッピングを利用して、 SQL を使用して AI_COMPLETE の構造化出力を定義できます。型リテラルを TYPE キーワードで開始し、トップレベルの型として SQL OBJECT を使用します。トップレベルオブジェクトのプロパティは、 JSON へのマッピングがサポートされている SQL 型のいずれかです。
注釈
型リテラルは、 AI_COMPLETE の単一文字列テキストプロンプトバージョンでのみサポートされています。詳細については、 AI_COMPLETE (単一文字列) をご参照ください。
次の例では、型リテラルを使用して、プロンプトの構造化出力を生成します。プロンプトには、モデルへの指示と処理するデータの両方が含まれます。response_format 型リテラルは、モデルの応答を date、address、items_count``を含むトップレベル ``note、および価格を含む price 配列を持つ JSON オブジェクトとして生成します。
以下は、このクエリに対する完全な応答を示しています。
型リテラルの注意点と制限事項¶
構造化出力スキーマを型リテラルとして指定する場合は、次の規則に従います。
STRING および VARCHAR 型は JSON 文字列にマッピングされます。
VARCHAR 型では、特定の長さの出力が保証されません。
スケールのない FIXED 型は JSON 整数にマッピングされます。他のすべての数値型は JSON 数値にマッピングされます。
型リテラルには、サポートされる型に関する制限があります。
空のオブジェクト OBJECT() は型リテラルとして許可されません。
SQL 型のすべてに、構造化出力のマッピングがあるわけではあります。これらには以下が含まれますが、以下には限定されません。
VARIANT
MAP
サポートされていないデータ型を使用するとエラーが返されます。
JSON スキーマで AI_COMPLETE の使用¶
構造化出力をより詳細に制御したい場合は、 response_format の値として `JSON スキーマ<https://json-schema.org/>`_ を使用します。提供された JSON スキーマは、必須フィールドを含め、生成されたテキストが準拠しなければならない構造、データ型、および制約を定義します。
単純なタスクの場合は、出力形式の詳細を指定したり、モデルに「JSON で応答するように」指示したりする必要はありません。より複雑なタスクの場合、 JSON で応答するようモデルに促すことで精度を向上させることができます。 JSON アドヒアランス精度の最適化 をご覧ください。
次は、 JSON スキーマを使用して構造化された出力形式を指定する AI_COMPLETE 関数呼び出しの構文を示しています。スキーマは、文字列型の property_name プロパティを持つ最上位オブジェクト properties を定義します。このフィールドは応答で必須です。
重要
OpenAI(GPT)モデルの場合、次の要件が適用されます。
additionalProperties フィールドは、スキーマのすべてのノードで``false``に設定する必要があります。
`必須<https://json-schema.org/understanding-json-schema/reference/object#required>`_ のフィールドは含まれる必要があり、スキーマにあるすべてのプロパティの名前が含まれている必要があります。
他のモデルはこれらのフィールドを必須としませんが、含めることでOpenAIモデルに対する別のスキーマの必要がなくなります。
SQL 例¶
次の例は、単一の文字列入力を使用した AI_COMPLETE の使用のより完全なデモです。
応答:
次の例は、 response_format 引数を使用してレスポンスに JSON スキーマを指定し、 show_details 引数を使用して推論メタデータを返す方法を示しています。
応答:
Pythonの例¶
注釈
構造化出力は、 snowflake-ml-python バージョン 1.8.0 以降でサポートされています。
次の例は、 response_format 引数を使用して、レスポンスに JSON スキーマを指定する方法を示しています。
応答:
Pydanticの例¶
PydanticはPython用のデータ検証およびセット管理ライブラリです。この例ではPydanticを使って応答形式のスキーマを定義しています。コードは以下のステップを実行します:
Pydanticを使ってスキーマを定義します。
model_json_schemaメソッドを使って Pydantic モデルを JSON スキーマに変換します。response_format引数としてcomplete関数に JSON スキーマを渡します。
注釈
この例はSnowsight Pythonワークシートで実行することを想定しており、すでにSnowflakeに接続しています。別の環境で実行するには、 Snowflake Connector for Python を使用して Snowflake への接続を確立する必要があるかもしれません。
応答:
REST API の例¶
Snowflake Cortex LLM REST API を使用して、 COMPLETE を LLM で呼び出すことができます。以下は、Cortex LLM REST API を使ってスキーマを供給する例です:
応答:
JSON スキーマ定義の作成¶
COMPLETE 構造化出力から最高の精度を得るには、以下のガイドラインに従ってください:
スキーマの "required "フィールド の必須フィールドを指定してください。COMPLETE は、必須フィールドを抽出できない場合にエラーを発生させます。
次の例では、スキーマは COMPLETE で、ドキュメントで言及されている人物を検索するよう指示しています。
peopleのフィールドは、人物の識別を確実にするために必須とマークされています。応答:
モデルがより正確にフィールドを識別できるように、抽出するフィールドの 詳細な説明を提供 します。例えば、以下のスキーマには、
people:name、age、およびisAdultのフィールドごとに説明が含まれています。
JSON 参照の使用¶
スキーマ参照は、Cortex COMPLETE 構造化出力を使用する際の実際的な問題を解決します。$ref で表される参照を使用すると、住所や価格などの共通オブジェクトを一度定義してから、スキーマ全体でそれらを再利用することができます。このようにして、検証ロジックを更新したり、フィールドを追加したりする必要があるときに、複数の場所ではなく1つの場所で変更することができます。
参照を使用すると、コーディングの手間が減り、一貫性のない実装によるバグが減り、コードのレビューが簡単になります。参照コンポーネントは、データモデル内のエンティティ関係をより適切に表現するクリーナー階層を作成します。プロジェクトがより複雑になるにつれて、このモジュール化されたアプローチは、スキーマの整合性を維持しながら技術的負債を管理するのに役立ちます。
Pydantic のようなサードパーティライブラリは Python ネイティブでリファレンスの仕組みをサポートしており、コードでのスキーマの使用を簡素化します。
JSON スキーマにおけるリファレンスの使用には、以下のガイドラインが適用されます。
範囲の制限: ユーザーのスキーマだけに
$refメカニズムは限定されています。HTTP URLs のような外部スキーマ・リファレンスはサポートされていません。定義の配置: オブジェクト定義はスキーマのトップレベル、特に定義または
$defsキーの下に配置する必要があります。強制: JSON スキーマ仕様では、定義に
$defsキーを使用することを推奨していますが、Snowflake の検証メカニズムではこの構造を厳格に適用しています。これは有効な$defsオブジェクトの例です:
JSON リファレンスを使用した例¶
この SQL の例は、 JSON スキーマにおけるリファレンスの使い方を示しています。
応答:
JSON アドヒアランス精度の最適化¶
COMPLETE 構造化出力は通常、プロンプトを必要としません。構造化出力は、その応答があなたが指定したスキーマに従うべきであることをすでに理解しています。しかし、タスクの複雑さは、 LLMs 、 JSON の回答形式に従う能力に大きく影響します。タスクが複雑であればあるほど、プロンプトを指定することで結果の精度を高めることができます。
テキスト分類、エンティティ抽出、言い換え、要約など、複雑な推論を必要としない 単純なタスク は、一般的に追加のプロンプトを必要としません。知能の低い小さなモデルでは、構造化出力を使用するだけで、 JSON の遵守精度が大幅に向上します。
中複雑度タスク には、分類決定の根拠を示すなど、モデルに追加の推論を求める単純なタスクが含まれます。このような大文字と小文字を使用する場合は、パフォーマンスを最適化するために、プロンプトに「Respond in JSON」を追加することをお勧めします。
複雑な推論タスク モデルには、回答の関連性、専門性、忠実性に基づいて電話の品質を評価し、採点するような、よりオープンエンドのあいまいなタスクの実行を促します。これらのユースケースでは、Anthropic の
claude-3-5-sonnetや Mistral AI のmistral-large2のような最も強力なモデルを使用し、プロンプトに "Respond in JSON" と生成したいスキーマの詳細を追加することをお勧めします。
最も安定した結果を得るには、タスクやモデルに関係なく、 COMPLETE を呼び出すときに temperature オプションを 0 にセットします。
Tip
モデルによって発生する可能性のあるエラーを処理するには、 COMPLETE ではなく TRY_COMPLETE を使用します。
コストの考慮事項¶
Cortex COMPLETE 構造化出力では、処理されるトークンの数に応じた計算コストが発生しますが、提供された JSON スキーマに対して各トークンを検証するオーバーヘッドに対する追加の計算コストは発生しません。しかし、トークンの処理数(および請求数)はスキーマの複雑さとともに増加します。一般的に、提供されるスキーマが大きく複雑であればあるほど、より多くの入力および出力トークンが消費されます。深い入れ子を持つ高度に構造化されたレスポンス (階層データなど) は、単純なスキーマよりも多くのトークンを消費します。
制限事項¶
スキーマのキーにスペースを使用することはできません。
プロパティ名に使用できる文字は、文字、数字、ハイフン、アンダースコアです。名前の長さは最大64文字です。
$refまたは$dynamicRefを使用して外部スキーマをアドレス指定することはできません。
以下の制約キーワードはサポートされていません。サポートされていない制約キーワードを使用するとエラーになります。
型 |
キーワード |
|---|---|
integer |
|
number |
|
string |
|
array |
|
object |
|
これらの制限は、将来のリリースで対処される可能性があります。
エラー条件¶
状況 |
メッセージ例 |
HTTP ステータスコード |
|---|---|---|
リクエストの検証に失敗しました。モデルが有効なレスポンスを生成できないため、クエリはキャンセルされました。これは不正なリクエストによって引き起こされる可能性があります。 |
|
400 |
入力スキーマの検証に失敗しました。モデルが有効なレスポンスを生成できないため、クエリはキャンセルされました。これは、リクエストのペイロードに必要なプロパティが含まれていなかったり、 制約のようなサポートされていない JSON スキーマの機能を使用していたり、 $ref メカニズムを不適切に使用していたり (例えば、スキーマの外側に達している) することで発生します。 |
以下のいずれかの
|
400 |
モデル出力の検証に失敗しました。モデルはスキーマに一致する応答を生成できませんでした。 |
以下のいずれかの
|
422 |