> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > AI 関数のドキュメント # AI 関数 AI 関数は ClickHouse の組み込み関数で、AI の呼び出しや埋め込みの生成に使用でき、データの処理、情報の抽出、データの分類などを行えます。 AI 関数は Experimental です。有効にするには [`allow_experimental_ai_functions`](/ja/reference/settings/session-settings/allow-experimental#allow_experimental_ai_functions) を設定してください。 AI 関数は予測不能な出力を返す場合があります。結果は、プロンプトの品質と使用するモデルに大きく依存します。 **プロンプトインジェクション** 入力テキストはモデルに送信され、その出力を誘導する可能性があります (プロンプトインジェクション) 。外部の未検証または未サニタイズのソースからのテキストには、モデルに攻撃者が制御するコンテンツを返させたり、要求されたフォーマットを無視させたり、悪意のあるペイロードを出力させたりする指示が含まれている可能性があります。AI 関数の出力は信頼できないものとして扱ってください。SQL の構築、シェルコマンド、追加のクエリ、アクセス制御の判断など、後続のステップで使用する前に検証またはサニタイズしてください。 すべての関数は、以下を提供する共通のインフラストラクチャを利用しています。 * **クォータの適用**: トークン ([`ai_function_max_input_tokens_per_query`](/ja/reference/settings/session-settings/ai-function#ai_function_max_input_tokens_per_query), [`ai_function_max_output_tokens_per_query`](/ja/reference/settings/session-settings/ai-function#ai_function_max_output_tokens_per_query)) および API 呼び出し ([`ai_function_max_api_calls_per_query`](/ja/reference/settings/session-settings/ai-function#ai_function_max_api_calls_per_query)) に対するクエリ単位の上限。 * **バックオフ付き再試行**: 一時的な障害は、指数バックオフ ([`ai_function_retry_initial_delay_ms`](/ja/reference/settings/session-settings/ai-function#ai_function_retry_initial_delay_ms)) を使用して再試行 ([`ai_function_max_retries`](/ja/reference/settings/session-settings/ai-function#ai_function_max_retries)) されます。
## Configuration
AI 関数は、プロバイダーの認証情報と設定を格納した **名前付きコレクション** を参照します。関数ごと、または関数呼び出しごとに、異なる 名前付きコレクション を作成して使い分けることができます。たとえば、テキスト関数 (`aiGenerate`、`aiClassify`、`aiFilter`、`aiExtract`、`aiTranslate`、`aiRedact`) で使用する 名前付きコレクション と、異なるエンドポイントが必要で通常は異なるモデルを使用する埋め込み関数 (`aiEmbed`、`aiSimilarity`) で使用する 名前付きコレクション を、別々に定義したい場合があります。 プロバイダーの認証情報を含む 名前付きコレクション を作成するための例のステートメントを以下に示します。1 つはチャット用エンドポイント、もう 1 つは埋め込み用エンドポイントです。 ```sql theme={null} CREATE NAMED COLLECTION ai_text_credentials AS provider = 'openai', endpoint = 'https://api.openai.com/v1/chat/completions', model = 'gpt-4o-mini', api_key = 'sk-...'; -- The embedding functions (`aiEmbed`, `aiSimilarity`) do not read `model` from the named collection, -- pass it as a positional argument instead. Defining `model` in an embedding collection is an error, -- not silently ignored. CREATE NAMED COLLECTION ai_embedding_credentials AS provider = 'openai', endpoint = 'https://api.openai.com/v1/embeddings', api_key = 'sk-...'; ```
### 名前付きコレクションのパラメータ
| パラメータ | 型 | デフォルト | 説明 | | ------------- | ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | `provider` | String | — | モデルプロバイダー。サポート対象: `'openai'`, `'anthropic'`。以下の注記を参照してください。 | | `endpoint` | String | — | API エンドポイント URL。 | | `model` | String | — | モデル名 (例: `'gpt-4o-mini'`)。テキスト関数で使用されます。埋め込み関数 (`aiEmbed`、`aiSimilarity`) では `model` を位置引数として指定する必要があり、名前付きコレクションで `model` を指定するとエラーになります。 | | `api_key` | String | — | プロバイダーの認証用キー。省略可能: 省略した場合、認証ヘッダーは送信されないため、認証を必要としない OpenAI 互換サーバーを対象にできます。 | | `max_tokens` | UInt64 | `1024` | API 呼び出しごとの出力トークン数の上限。 | | `api_version` | String | — | API バージョン文字列。Anthropic で使用されます (`'2023-06-01'`) 。 | `provider = 'openai'` を設定し、`endpoint` を利用するサービスに向けることで、任意の OpenAI 互換 API (例: vLLM、Ollama、LiteLLM) を使用できます。
### 認証情報の選択
関数は、使用する `名前付きコレクション` を次の順序で特定します。 1. 存在する場合は、パラメータマップの `credentials` キー。 2. それ以外の場合は、該当するデフォルト認証情報の設定。 * テキスト関数 (`aiGenerate`、`aiClassify`、`aiFilter`、`aiExtract`、`aiTranslate`、`aiRedact`) では [`ai_function_text_default_credentials`](/ja/reference/settings/session-settings/ai-function#ai_function_text_default_credentials)。 * 埋め込み関数 (`aiEmbed`、`aiSimilarity`) では [`ai_function_embedding_default_credentials`](/ja/reference/settings/session-settings/ai-function#ai_function_embedding_default_credentials)。 どちらも設定されていない場合、呼び出しは失敗します。テキスト関数と埋め込み関数でデフォルト設定が分かれているのは、chat-completions のエンドポイントが embeddings 用のものとは異なるためです。 ```sql theme={null} SET ai_function_text_default_credentials = 'ai_text_credentials'; -- Uses ai_text_credentials from the setting: SELECT aiGenerate('What is 2 + 2? Reply with just the number.'); -- Overrides the default for this call: SELECT aiGenerate('Bonjour', map('credentials', 'other_credentials')); ``` `UInt8` を返し、`WHERE` 句で直接使用できる `aiFilter` を使って、自然言語の条件で行をフィルタリングします。 ```sql theme={null} SELECT * FROM reviews WHERE aiFilter(body, 'the customer is angry about shipping'); ```
### パラメータマップ
各関数は、末尾に任意の `Map(String, String)` のパラメータマップを受け取れます。すべての値は文字列です (数値も `'0.2'` のようにクォートしてください) 。不明なキーは受け付けられません。指定されたキーは、対応する 名前付きコレクション の値を上書きします。指定されていないキーは、名前付きコレクション (`model`/`max_tokens` の場合) または組み込みのデフォルト値が使われます。例外は埋め込み関数 (`aiEmbed`、`aiSimilarity`) で、`model` を必須の位置引数として受け取り (例: `aiEmbed(text, model[, params])`、`aiSimilarity(text1, text2, model[, params])`)、代わりにパラメータマップや 名前付きコレクション に設定するとエラーになります。これは再現可能な埋め込みを保証するためです。 以下のパラメータは、すべての AI 関数に共通です。 | キー | 説明 | | ------------- | ----------------------------------------------------------------------------------------------------------------- | | `credentials` | 使用する 名前付きコレクション (上記を参照) 。 | | `model` | コレクションの `model` を上書きします (テキスト関数のみ。埋め込み関数 (`aiEmbed`、`aiSimilarity`) は `model` を必須の位置引数として受け取り、マップキーとしては受け取りません) 。 | 各関数は、これに加えて関数固有の追加パラメータ (`max_tokens`、`temperature`、`system_prompt`、`instructions`、`dimensions` など) を受け付けます。受け付けるパラメータとそのデフォルト値については、以下の各関数のリファレンスを参照してください。 ```sql theme={null} SELECT aiGenerate(body, map('temperature', '0.2', 'system_prompt', 'You are terse.')) FROM articles; ```
### クエリレベルの設定
すべての AI 関連の設定は、`ai_function_` プレフィックスで [Settings](/ja/reference/settings/session-settings) に一覧表示されています。
### エンドポイントホストの制限
AI 名前付きコレクション の `endpoint` URL は、サーバーが自身の identity で接続する送信先であり、リクエストヘッダーに 名前付きコレクション の `api_key` を (指定されている場合に) 含めて送信する可能性があります。デフォルトでは、ClickHouse はすべてのホストへの接続を許可します。関数を特定の provider 群のみに制限するには、サーバー設定で [`remote_url_allow_hosts`](/ja/reference/settings/server-settings/settings/remote#remote_url_allow_hosts) を設定します。例: ```xml theme={null} api.openai.com api.anthropic.com ``` この設定はサーバー全体に適用され、HTTP を使用するすべての機能に適用されることに注意してください。
### 転送のセキュリティ (HTTP と HTTPS)
転送方式は、`endpoint` URL のスキームのみによって決まります。リクエストのペイロード自体がアプリケーションレベルで暗号化されることはなく、転送中データの保護はスキームに完全に依存します。 * `https://` — 接続に TLS が使用されます。リクエストボディ (入力テキスト、プロンプト) と、リクエストヘッダー内の `api_key` は転送中に暗号化され、プロバイダー の certificate も検証されます。リモートの プロバイダー には必ずこちらを使用してください。 * `http://` — 接続は**暗号化されません**。リクエストボディと `api_key` は平文で送信されます。これは、private network 上の信頼できる プロバイダー (例: ローカルの `vLLM` または `Ollama` インスタンス) に対してのみ使用してください。 デフォルトでは、AI 関数はリモート host に平文でデータを送信する `endpoint` を拒否します。host がループバックでない HTTPS 以外のエンドポイント は例外を発生させます。ループバック host (`localhost`、`127.0.0.0/8`、`::1`) は対象外のため、ローカルの `http://localhost` モデル server はそのまま動作します。リモート host で平文の `http://` エンドポイント を許可するには、[`ai_function_allow_insecure_endpoint`](/ja/reference/settings/session-settings/ai-function#ai_function_allow_insecure_endpoint) を `1` に設定します。この check は [`remote_url_allow_hosts`](/ja/reference/settings/server-settings/settings/remote#remote_url_allow_hosts) とは独立しています。この設定は host の allowlist であり、URL スキームは検査しないため、許可された host を指す `http://` エンドポイント は引き続き許可されます。 いずれの場合も、プロバイダー は TLS 終端後の入力データを平文で受け取る点に注意してください。TLS が保護するのは、server と プロバイダー の間のネットワーク経路上のデータのみです。
## サポートされているプロバイダー
| プロバイダー | `provider` の値 | チャット関数 | 注記 | | --------- | ------------- | ------ | ------------------------------- | | OpenAI | `'openai'` | はい | デフォルトのプロバイダーです。 | | Anthropic | `'anthropic'` | はい | `/v1/messages` endpoint を使用します。 |
## オブザーバビリティ
AI 関数のアクティビティは、ClickHouse の [ProfileEvents](/ja/reference/system-tables/query_log) で追跡できます。 | ProfileEvent | Description | | ----------------- | ----------------------------------------------------------------- | | `AIAPICalls` | AI provider に送信された HTTP リクエスト数。 | | `AIInputTokens` | 消費された入力トークンの合計数。 | | `AIOutputTokens` | 消費された出力トークンの合計数。 | | `AIRowsProcessed` | 結果が返された行数。 | | `AIRowsSkipped` | スキップされた行数 (クォータ超過、または `ai_function_throw_on_error = 0` の場合のエラー) 。 | これらのイベントをクエリします。 ```sql theme={null} SELECT ProfileEvents['AIAPICalls'] AS api_calls, ProfileEvents['AIInputTokens'] AS input_tokens, ProfileEvents['AIOutputTokens'] AS output_tokens FROM system.query_log WHERE query_id = 'query_id' AND type = 'QueryFinish' ORDER BY event_time DESC; ```
## aiClassify
導入バージョン: v26.4.0 指定されたテキストを、LLMプロバイダーを使用して、与えられたカテゴリのいずれか 1 つに分類します。 認証情報 (プロバイダー、モデル、エンドポイント、および必要に応じて API key を指定する 名前付きコレクション) は、オプションの パラメータマップ の `credentials` キーから取得されるか、その map で省略されている場合は `ai_function_text_default_credentials` 設定から取得されます。 **構文** ```sql theme={null} aiClassify(text, categories[, params]) ``` **別名**: `AIClassify` **引数** * `text` — 分類するテキスト。[`String`](/ja/reference/data-types/string) * `categories` — 候補となるカテゴリラベルの定数リスト。[`Array(String)`](/ja/reference/data-types/array) * `params` — オプションの定数 `Map(String, String)` パラメータ。関数固有のキー: `temperature` (ランダム性を制御するサンプリング温度。デフォルト `0.0`)、`max_tokens` (1 回の呼び出しあたりの最大出力トークン数。デフォルト `1024`)。共通パラメータ `credentials` と `model` も適用されます ([AI 関数](/ja/reference/functions/regular-functions/ai-functions) を参照)。[`Map(String, String)`](/ja/reference/data-types/map) **戻り値** 指定されたカテゴリラベルのいずれか、またはリクエストが失敗し、`ai_function_throw_on_error` が無効になっている場合はカラム型のデフォルト値 (空文字列) 。[`String`](/ja/reference/data-types/string) **例** **感情を分類** ```sql title=Query theme={null} SELECT aiClassify('I love this product!', ['positive', 'negative', 'neutral']) ``` ```response title=Response theme={null} positive ``` **明示的に指定した認証情報を使用してカラムを分類する** ```sql title=Query theme={null} SELECT body, aiClassify(body, ['bug', 'question', 'feature'], map('credentials', 'ai_text_credentials')) AS kind FROM issues LIMIT 5 ```
## aiEmbed
導入バージョン: v26.6.0 設定済みの AI プロバイダー を使用して、指定されたテキストの埋め込みベクトルを生成します。 この関数はテキストを設定済みの埋め込み用エンドポイントに送信し、生成されたベクトルを `Array(Float32)` として返します。 1つの block 内の行については、呼び出しごとのオーバーヘッドを減らすため、入力は 1回の HTTP リクエスト あたり最大 [`ai_function_embedding_max_batch_size`](/ja/reference/settings/session-settings/ai-function#ai_function_embedding_max_batch_size) エントリの batches にグループ化されます。 認証情報 (プロバイダー、エンドポイント、必要に応じて API key を指定する 名前付きコレクション) は、パラメータマップ の `credentials` キーから取得されるか、 map で省略されている場合は `ai_function_embedding_default_credentials` 設定から取得されます。`aiEmbed` では テキスト関数とは別のデフォルト認証情報設定が使われる点に注意してください。これは、埋め込み用エンドポイントが chat エンドポイント とは異なるためです。 `model` は必須の位置引数 (定数の `String`) です。テキスト関数とは異なり、 `aiEmbed` は 名前付きコレクション や パラメータマップ から `model` を読み取りません。`model` を定義する 名前付きコレクション は、 拒否されます。 オプションの `dimensions` パラメータ は、モデルが対応している場合 (たとえば OpenAI's `text-embedding-3-*`) 、 指定したサイズのベクトルを要求します。対応していない場合は、モデル本来のサイズが返されます。 **構文** ```sql theme={null} aiEmbed(text, model[, params]) ``` **別名**: `AIEmbed` **引数** * `text` — 埋め込み対象のテキスト。[`String`](/ja/reference/data-types/string) * `model` — 埋め込みモデル名。[`const String`](/ja/reference/data-types/string) * `params` — 省略可能な定数 `Map(String, String)` パラメータ。関数固有のキー: `dimensions` (出力ベクトルの目標次元数。`0` または省略時はモデルのネイティブのサイズを意味します) 。共通パラメータ `credentials` も使用できます ([AI 関数](/ja/reference/functions/regular-functions/ai-functions) を参照) 。[`Map(String, String)`](/ja/reference/data-types/map) **戻り値** 埋め込みベクトル。入力が NULL または空の場合、リクエストが失敗して `ai_function_throw_on_error` が無効になっている場合、あるいは `ai_function_throw_on_quota_exceeded` が無効になっている状態でクォータを超過した場合は、空の配列を返します。[`Array(Float32)`](/ja/reference/data-types/array) **例** **単一の文字列を埋め込む (`ai_function_embedding_default_credentials` が設定されている場合、`credentials` は省略できます) ** ```sql title=Query theme={null} SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials')) ``` **次元を明示する場合** ```sql title=Query theme={null} SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256')) ``` **テキストを含むカラムを埋め込む** ```sql title=Query theme={null} SELECT aiEmbed(title, 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256')) FROM articles LIMIT 10 ```
## aiExtract
導入バージョン: v26.4.0 LLMプロバイダーを使用して、非構造化テキストから構造化情報を抽出します。 3 番目の引数には、自由形式の自然言語による指示 (例: `'主な訴え'`) または `'{"field_a": "field a の説明", "field_b": "field b の説明"}'` の形式の JSON エンコードされたスキーマを指定できます。 指示モードでは、この関数は抽出した値をプレーンな文字列として返し、何も見つからなかった場合は空文字列を返します。 スキーマモードでは、この関数は要求されたスキーマに対応するキーを持つ JSON オブジェクト文字列を返します。存在しないフィールドは `null` になります。 認証情報 (プロバイダー、model、エンドポイント、および必要に応じて API key を指定する 名前付きコレクション) は、省略可能な パラメータマップ の `credentials` キーから取得されるか、 map で省略されている場合は `ai_function_text_default_credentials` setting から取得されます。 **構文** ```sql theme={null} aiExtract(text, instruction_or_schema[, params]) ``` **別名**: `AIExtract` **引数** * `text` — 情報を抽出するテキスト。[`String`](/ja/reference/data-types/string) * `instruction_or_schema` — 自由形式の抽出指示、または抽出するフィールドを記述した定数の JSONオブジェクト。[`const String`](/ja/reference/data-types/string) * `params` — オプションの定数 `Map(String, String)` パラメーター。関数固有のキー: `temperature` (ランダム性を制御するサンプリング温度。デフォルト `0.0`)、`max_tokens` (1 回の呼び出しあたりの最大出力トークン数。デフォルト `1024`)。共通パラメーターである `credentials` と `model` も適用されます ([AI 関数](/ja/reference/functions/regular-functions/ai-functions) を参照)。[`Map(String, String)`](/ja/reference/data-types/map) **戻り値** 単一の抽出結果 (指示モード) または JSONオブジェクト文字列 (スキーマモード) 。リクエストが失敗し、`ai_function_throw_on_error` が無効になっている場合は、カラム型のデフォルト値 (空文字列) を返します。[`String`](/ja/reference/data-types/string) **例** **自由形式の指示** ```sql title=Query theme={null} SELECT aiExtract('The package arrived late and was damaged.', 'the main complaint') ``` ```response title=Response theme={null} late and damaged package ``` **スキーマ抽出** ```sql title=Query theme={null} SELECT aiExtract(review, '{"sentiment": "positive, negative or neutral", "topic": "main topic of the review"}') FROM reviews LIMIT 5 ```
## aiFilter
導入バージョン: v26.8.0 LLMプロバイダー を使用して指定されたテキストに対する自然言語の条件を評価し、`WHERE`、`PREWHERE`、`JOIN ... ON` で使用できるブール値 (`UInt8`) を返します。 この関数は、モデルに小文字の `true` または `false` のみで応答するよう求めます。失敗したリクエスト (`ai_function_throw_on_error` が無効な場合) および認識できない応答は `0` にマッピングされるため、行は除外されます。 **警告:** `aiFilter` の結果を無批判に信用しないでください。LLM ベースの述語は不正確であったり、一貫性を欠いたりする可能性があります。偽陽性や偽陰性が許容される場合にのみ使用してください。 認証情報 (provider、model、endpoint、および必要に応じて API key を指定する 名前付きコレクション) は、任意の パラメータマップ の `credentials` キーから取得されます。このキーが map で省略されている場合は、`ai_function_text_default_credentials` 設定から取得されます。 注: `JOIN ... ON` で `aiFilter` を使用すると、候補ペアごとに LLM が一度評価されるため、コストが高くなる可能性があります。 **構文** ```sql theme={null} aiFilter(text, condition[, params]) ``` **別名**: `AIFilter` **引数** * `text` — 評価対象のテキスト。[`String`](/ja/reference/data-types/string) * `condition` — テキストが満たす必要がある、定数の自然言語条件。[`String`](/ja/reference/data-types/string) * `params` — 任意の定数 `Map(String, String)` 型パラメータ。関数固有のキー: `temperature` (ランダム性を制御するサンプリング温度、デフォルトは `0.0`) 、`max_tokens` (呼び出しあたりの最大出力トークン数、デフォルトは `1024`) 。共通パラメータの `credentials` と `model` も適用されます ([AI 関数](/ja/reference/functions/regular-functions/ai-functions)を参照) 。[`Map(String, String)`](/ja/reference/data-types/map) **戻り値** テキストが条件に一致する場合は `1`、それ以外の場合は `0`。リクエストが失敗し、`ai_function_throw_on_error` が無効の場合は、デフォルト値 (`0`) を返します。[`UInt8`](/ja/reference/data-types/int-uint) **例** **怒りを含むレビューをフィルタリングする** ```sql title=Query theme={null} SELECT * FROM reviews WHERE aiFilter(body, 'the customer is angry about shipping') ``` **認証情報を明示的に指定してカラムをフィルタリングする** ```sql title=Query theme={null} SELECT body, aiFilter(body, 'describes a bug', map('credentials', 'ai_text_credentials')) AS is_bug FROM issues LIMIT 5 ```
## aiGenerate
導入バージョン: v26.4.0 LLMプロバイダーを使用して、プロンプトから自由形式のテキストコンテンツを生成します。 この関数は、プロンプトを設定済みのAIプロバイダーに送信し、生成されたテキストを返します。 認証情報 (provider、model、endpoint、および必要に応じて API key を指定する名前付きコレクション) は、任意のパラメータマップの `credentials` キーから取得されるか、 パラメータマップで省略されている場合は `ai_function_text_default_credentials` 設定から取得されます。 任意のパラメータマップでは、`system_prompt` (モデルの 動作 (例: tone、format、role) を導く指示) 、`temperature`、`max_tokens`、`model` も設定できます。`system_prompt` が 設定されていない場合のデフォルト値は次のとおりです: `You are a helpful assistant. Provide a clear and concise response.` **構文** ```sql theme={null} aiGenerate(prompt[, params]) ``` **別名**: `AIGenerate` **引数** * `prompt` — モデルに送信する、ユーザーのプロンプトまたは質問。[`String`](/ja/reference/data-types/string) * `params` — 省略可能な定数 `Map(String, String)` パラメータ。関数固有のキーは次のとおりです: `temperature` (ランダム性を制御するサンプリング温度。デフォルトは `0.7`) 、`max_tokens` (1 回の呼び出しで生成できる最大トークン数。デフォルトは `1024`) 、`system_prompt` (モデルの振る舞いを導く定数のシステムレベル命令。デフォルトは汎用的なアシスタント用プロンプト) 。共通パラメータの `credentials` と `model` も利用できます ([AI 関数](/ja/reference/functions/regular-functions/ai-functions) を参照) 。[`Map(String, String)`](/ja/reference/data-types/map) **戻り値** 生成されたテキスト応答。リクエストが失敗し、`ai_function_throw_on_error` が無効になっている場合は、カラム型のデフォルト値 (空文字列) が返されます。[`String`](/ja/reference/data-types/string) **例** **単純な質問** ```sql title=Query theme={null} SELECT aiGenerate('What is 2 + 2? Reply with just the number.') ``` ```response title=Response theme={null} 4 ``` **明示的に指定した認証情報とシステムプロンプト** ```sql title=Query theme={null} SELECT aiGenerate('Explain ClickHouse', map('credentials', 'ai_text_credentials', 'system_prompt', 'You are a database expert. Be concise.')) ``` **カラムの値を要約する** ```sql title=Query theme={null} SELECT article_title, aiGenerate(concat('Summarize in one sentence: ', article_body)) AS summary FROM articles LIMIT 5 ```
## aiRedact
導入バージョン: v26.8.0 LLMプロバイダーを使用して、指定されたテキスト内の個人を特定できる情報 (PII) を検出し、マスキングします。 `aiRedact` は LLM を使用してベストエフォートで PII を検出・マスキングするため、その出力は 信頼できません。PII が検出・削除されるかどうかは、選択したモデル、プロンプト、入力によって異なります。モデルが 識別子を見落としたり、一部だけをマスキングしたり、周囲のテキストを変更したりする可能性があります。整形式の 英語テキストで最も適切に機能しますが、他の言語のテキストや、スペル、句読点、文法の誤りが多いテキストでは、 結果が悪くなる可能性があります。`aiRedact` は出力に PII が含まれないことを保証せず、単独で安全または十分な 匿名化手段として扱ってはなりません。信頼できない第三者にデータを公開する前に、必ず出力を確認し、 組織'のデータプライバシーおよびコンプライアンスポリシーを満たしていることを確認してください。 検出された各 PII span は、マスキングトークン (デフォルトでは `[REDACTED]`、`replacement` parameter で設定可能) に置き換えられます。`categories` Array は、マスキングする PII の種類を制限します。空の Array を指定した場合は、 一般的なカテゴリ (名前、メールアドレス、電話番号、住所、クレジットカード、IP アドレス) からなるデフォルトのセットにフォールバックします。 `aiRedact` は、検出された PII span のみを変更するようモデルに指示しますが、周囲のテキストの保持は ベストエフォートであり、モデルが変更する可能性があります (上記の警告を参照) 。タブ、 改行、復帰以外の制御文字もリクエスト前にスペースへ正規化されるため、これらを含む入力では出力が バイト単位で同一にはなりません。 `aiRedact` は PII を置き換えた入力テキスト全体を返すため、出力は入力とほぼ同じ長さになります。 `max_tokens` (デフォルトは `1024`) を、トークン単位の入力長より大きく設定してください。上限が低すぎて切り詰められた応答は 不完全になります。 **構文** ```sql theme={null} aiRedact(text, categories[, params]) ``` **別名**: `AIRedact` **引数** * `text` — マスキング対象のテキスト。[`String`](/ja/reference/data-types/string) * `categories` — マスキングする PII カテゴリの定数リスト (例: `['name', 'ssn', 'credit_card']`) 。空の配列を指定すると、一般的なカテゴリ (名前、メールアドレス、電話番号、住所、クレジットカード、IP アドレス) のデフォルトセットが使用されます。[`Array(String)`](/ja/reference/data-types/array) * `params` — 任意の定数 `Map(String, String)` パラメータ。関数固有のキー: `temperature` (ランダム性を制御するサンプリング温度、デフォルト `0.0`) 、`max_tokens` (呼び出しごとの最大出力トークン数、デフォルト `1024` — `aiRedact` はテキスト全体を返すため、入力のトークン数より大きい値に設定してください。そうしないと、応答が切り詰められて不完全になる可能性があります) 、`replacement` (検出された各 PII span を置き換えるトークン、デフォルト `[REDACTED]`) 。共通パラメータの `credentials` と `model` も適用されます ([AI 関数](/ja/reference/functions/regular-functions/ai-functions)を参照) 。[`Map(String, String)`](/ja/reference/data-types/map) **戻り値** 検出された PII をマスキングトークンで置き換えたテキスト。リクエストが失敗し、`ai_function_throw_on_error` が無効の場合は、カラム型のデフォルト値 (空文字列) 。[`String`](/ja/reference/data-types/string) **例** **特定のカテゴリをマスキングする** ```sql title=Query theme={null} SELECT aiRedact('Purchase was done by customer John Doe with email test@test.org', ['email', 'credit_card', 'name']) ``` ```response title=Response theme={null} Purchase was done by customer [REDACTED] with email [REDACTED] ``` **カスタムトークンを使用してデフォルトのPIIカテゴリをマスキングする** ```sql title=Query theme={null} SELECT aiRedact(body, [], map('replacement', '***')) FROM tickets LIMIT 5 ```
## aiSimilarity
導入バージョン: v26.8.0 設定された埋め込みプロバイダーを使用して、2つのテキスト間の意味的な類似度を計算します。 両方のテキストのベクトル埋め込みを計算し、それらの [コサイン類似度](https://en.wikipedia.org/wiki/Cosine_similarity)を返します。`-1` のスコアは 反対方向の埋め込みベクトルに与えられ、意味的には、スコアが `-1` に近いテキストは意味が反対であることを示します。 `0` のスコアはベクトルが直交している、つまり意味的に無関係であることを示します。最後に、`1` のスコアは 埋め込みベクトルが同じ方向を向いていることを意味し、スコアが `1` に近いテキストは 意味が類似しています。これは、同じ埋め込みに対する `cosineDistance` の補数です (`aiSimilarity = 1 - cosineDistance(embedding1, embedding2)`) 。 バッチ処理、認証情報、`dimensions` パラメータは `aiEmbed` と同じであり、 `ai_function_embedding_default_credentials` のデフォルト認証情報設定も含まれます。 `aiEmbed` と同様に、`model` は必須の位置引数 (定数の `String`) であり、名前付きコレクションや パラメータマップからは読み取られません。 **構文** ```sql theme={null} aiSimilarity(text1, text2, model[, params]) ``` **別名**: `AISimilarity` **引数** * `text1` — 1つ目のテキスト。[`String`](/ja/reference/data-types/string) * `text2` — 2つ目のテキスト。[`String`](/ja/reference/data-types/string) * `model` — 埋め込みモデル名。[`const String`](/ja/reference/data-types/string) * `params` — 任意の定数 `Map(String, String)` 型パラメータ。関数固有のキー: `dimensions` (埋め込みの目標次元数。`0` または省略した場合はモデル本来の次元数) 。共通パラメータ `credentials` も適用されます ([AI 関数](/ja/reference/functions/regular-functions/ai-functions)を参照) 。[`Map(String, String)`](/ja/reference/data-types/map) **戻り値** `[-1, 1]` のコサイン類似度。いずれかのテキストが NULL または空の場合、埋め込みリクエストが失敗し `ai_function_throw_on_error` が無効な場合、または `ai_function_throw_on_quota_exceeded` が無効な状態でクォータを超過した場合は NULL。[`Nullable(Float32)`](/ja/reference/data-types/nullable) **例** **2つの文字列を比較 (`ai_function_embedding_default_credentials` 設定が指定されている場合、`credentials` は省略できます) ** ```sql title=Query theme={null} SELECT aiSimilarity('cat', 'kitten', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials')) ``` **クエリとの類似度に基づいてレビューをランク付けする** ```sql title=Query theme={null} SELECT review FROM product_reviews ORDER BY aiSimilarity(review, 'It works well under rain', 'text-embedding-3-small') DESC LIMIT 100 ``` **自己結合による意味的重複排除** ```sql title=Query theme={null} SELECT a.id, b.id FROM docs a, docs b WHERE a.id < b.id AND aiSimilarity(a.title, b.title, 'text-embedding-3-small') > 0.9 ```
## aiTranslate
導入バージョン: v26.4.0 指定されたテキストを、LLMプロバイダーを使用して指定した対象言語に翻訳します。 文体や方言に関する追加の指示は、パラメータマップの `instructions` キーで渡すことができます (例: `'技術用語は翻訳しない'`) 。 認証情報 (provider、model、endpoint、および必要に応じて API key を指定する 名前付きコレクション) は、省略可能なパラメータマップの `credentials` キーから取得され、マップでこれが省略されている場合は `ai_function_text_default_credentials` 設定から取得されます。 **構文** ```sql theme={null} aiTranslate(text, target_language[, params]) ``` **別名**: `AITranslate` **引数** * `text` — 翻訳するテキスト。 [`String`](/ja/reference/data-types/string) * `target_language` — 対象言語名または BCP-47 コード (例: `'French'`, `'es-MX'`) 。 [`String`](/ja/reference/data-types/string) * `params` — 省略可能な定数 `Map(String, String)` パラメータ。関数固有のキー: `temperature` (ランダム性を制御するサンプリング温度。デフォルトは `0.3`) 、`max_tokens` (1 回の呼び出しで生成される出力トークンの最大数。デフォルトは `1024`) 、`instructions` (翻訳向けの追加のスタイルまたは方言に関する指示) 。共通パラメータの `credentials` と `model` も使用できます ([AI 関数](/ja/reference/functions/regular-functions/ai-functions) を参照) 。 [`Map(String, String)`](/ja/reference/data-types/map) **戻り値** 翻訳されたテキスト。リクエストが失敗し、`ai_function_throw_on_error` が無効な場合は、カラム型のデフォルト値 (空文字列) を返します。 [`String`](/ja/reference/data-types/string) **例** **フランス語に翻訳** ```sql title=Query theme={null} SELECT aiTranslate('Hello, world!', 'French') ``` ```response title=Response theme={null} Bonjour le monde! ``` **スタイル指示に従って日本語に翻訳** ```sql title=Query theme={null} SELECT aiTranslate(body, 'Japanese', map('instructions', 'Use polite form (desu/masu)')) FROM articles LIMIT 5 ```