> ## Documentation Index > Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt > Use this file to discover all available pages before exploring further. > AI 関数のドキュメント # AI 関数 AI 関数は ClickHouse の組み込み関数で、AI の呼び出しや埋め込みの生成に使用でき、データの処理、情報の抽出、データの分類などを行えます。 AI 関数は Experimental です。有効にするには [`allow_experimental_ai_functions`](/docs/ja/reference/settings/session-settings#allow_experimental_ai_functions) を設定してください。 AI 関数は予測不能な出力を返す場合があります。結果は、プロンプトの品質と使用するモデルに大きく依存します。 すべての関数は、以下を提供する共通のインフラストラクチャを利用しています。 * **クォータの適用**: トークン ([`ai_function_max_input_tokens_per_query`](/docs/ja/reference/settings/session-settings#ai_function_max_input_tokens_per_query), [`ai_function_max_output_tokens_per_query`](/docs/ja/reference/settings/session-settings#ai_function_max_output_tokens_per_query)) および API 呼び出し ([`ai_function_max_api_calls_per_query`](/docs/ja/reference/settings/session-settings#ai_function_max_api_calls_per_query)) に対するクエリ単位の上限。 * **バックオフ付き再試行**: 一時的な障害は、指数バックオフ ([`ai_function_retry_initial_delay_ms`](/docs/ja/reference/settings/session-settings#ai_function_retry_initial_delay_ms)) を使用して再試行 ([`ai_function_max_retries`](/docs/ja/reference/settings/session-settings#ai_function_max_retries)) されます。
## Configuration
AI 関数は、プロバイダーの認証情報と設定を格納した **名前付きコレクション** を参照します。関数ごと、または関数呼び出しごとに、異なる 名前付きコレクション を作成して使い分けることができます。たとえば、テキスト関数 (`aiGenerate`、`aiClassify`、`aiExtract`、`aiTranslate`) で使用する 名前付きコレクション と、異なるエンドポイントが必要で通常は異なるモデルを使用する `aiEmbed` 関数で使用する 名前付きコレクション を、別々に定義したい場合があります。 プロバイダーの認証情報を含む 名前付きコレクション を作成するための例のステートメントを以下に示します。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-...'; -- `aiEmbed` does not read `model` from the named collection; pass it as a positional argument instead. -- Defining `model` in an `aiEmbed` 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` では `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`、`aiExtract`、`aiTranslate`) では [`ai_function_text_default_credentials`](/docs/ja/reference/settings/session-settings#ai_function_text_default_credentials)。 * `aiEmbed` では [`ai_function_embedding_default_credentials`](/docs/ja/reference/settings/session-settings#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')); ```
### パラメータマップ
各関数は、末尾に任意の `Map(String, String)` のパラメータマップを受け取れます。すべての値は文字列です (数値も `'0.2'` のようにクォートしてください) 。不明なキーは受け付けられません。指定されたキーは、対応する 名前付きコレクション の値を上書きします。指定されていないキーは、名前付きコレクション (`model`/`max_tokens` の場合) または組み込みのデフォルト値が使われます。例外は `aiEmbed` で、`model` を必須の位置引数として受け取り (`aiEmbed(text, model[, params])`)、代わりにパラメータマップや 名前付きコレクション に設定するとエラーになります。 以下のパラメータは、すべての AI 関数に共通です。 | キー | 説明 | | ------------- | ----------------------------------------------------------------------------------------- | | `credentials` | 使用する 名前付きコレクション (上記を参照) 。 | | `model` | コレクションの `model` を上書きします (テキスト関数のみ。`aiEmbed` は `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](/docs/ja/reference/settings/session-settings) に一覧表示されています。
### エンドポイントホストの制限
AI named collection の `endpoint` URL は、サーバーが自身の identity で接続する送信先であり、リクエストヘッダーに named collection の `api_key` を (指定されている場合に) 含めて送信する可能性があります。デフォルトでは、ClickHouse はすべてのホストへの接続を許可します。関数を特定の provider 群のみに制限するには、サーバー設定で [`remote_url_allow_hosts`](/docs/ja/reference/settings/server-settings/settings#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 関数は HTTPS を強制しません。`http://` エンドポイント も受け入れられ、データは暗号化されないまま送信されます。現時点では、平文の AI エンドポイント を拒否する server-side の設定はありません。[`remote_url_allow_hosts`](/docs/ja/reference/settings/server-settings/settings#remote_url_allow_hosts) は宛先 host のみを制限し、URL スキームは検査しないため、許可された host への `http://` エンドポイント は引き続き許可されます。転送を暗号化したい場合は、`https://` エンドポイント を使うように 名前付きコレクション を設定してください。 いずれの場合も、プロバイダー は TLS 終端後の入力データを平文で受け取る点に注意してください。TLS が保護するのは、server と プロバイダー の間のネットワーク経路上のデータのみです。
## サポートされているプロバイダー
| プロバイダー | `provider` の値 | チャット関数 | 注記 | | --------- | ------------- | ------ | ------------------------------- | | OpenAI | `'openai'` | はい | デフォルトのプロバイダーです。 | | Anthropic | `'anthropic'` | はい | `/v1/messages` endpoint を使用します。 |
## オブザーバビリティ
AI 関数のアクティビティは、ClickHouse の [ProfileEvents](/docs/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; ``` {/*AUTOGENERATED_START*/}
## aiClassify
導入バージョン: v26.4.0 指定されたテキストを、LLMプロバイダーを使用して、与えられたカテゴリのいずれか 1 つに分類します。 この関数は、固定の分類プロンプトと、モデルが指定されたラベルのうちちょうど 1 つだけを返すよう制約する JSON スキーマのレスポンスフォーマットとともに、テキストを送信します。レスポンスが `{"category": "..."}` 形式の JSON オブジェクトとして返された場合は、ラベルが取り出され、その文字列が返されます。 認証情報 (プロバイダー、モデル、エンドポイント、および必要に応じて API key を指定する 名前付きコレクション) は、オプションの パラメータマップ の `credentials` キーから取得されるか、その map で省略されている場合は `ai_function_text_default_credentials` 設定から取得されます。 **構文** ```sql theme={null} aiClassify(text, categories[, params]) ``` **別名**: `AIClassify` **引数** * `text` — 分類するテキスト。[`String`](/docs/ja/reference/data-types/string) * `categories` — 候補となるカテゴリラベルの定数リスト。[`Array(String)`](/docs/ja/reference/data-types/array) * `params` — オプションの定数 `Map(String, String)` パラメーター。関数固有のキー: `temperature` (ランダム性を制御するサンプリング温度。デフォルト `0.0`)、`max_tokens` (1 回の呼び出しあたりの最大出力トークン数。デフォルト `1024`)。共通パラメーター `credentials` と `model` も適用されます ([AI 関数](/docs/ja/reference/functions/regular-functions/ai-functions) を参照)。[`Map(String, String)`](/docs/ja/reference/data-types/map) **戻り値** 指定されたカテゴリラベルのいずれか、またはリクエストが失敗し、`ai_function_throw_on_error` が無効になっている場合はカラム型のデフォルト値 (空文字列) 。[`String`](/docs/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 provider を使用して、指定されたテキストの埋め込みベクトルを生成します。 この関数はテキストを設定済みの埋め込み エンドポイント に送信し、生成されたベクトルを `Array(Float32)` として返します。 1つの block 内の行については、呼び出しごとのオーバーヘッドを減らすため、入力は 1回の HTTP request あたり最大 [`ai_function_embedding_max_batch_size`](/docs/ja/reference/settings/session-settings#ai_function_embedding_max_batch_size) エントリの batches にグループ化されます。 認証情報 (provider、エンドポイント、必要に応じて API key を指定する 名前付きコレクション) は、パラメータマップ の `credentials` キーから取得されるか、 map で省略されている場合は `ai_function_embedding_default_credentials` 設定から取得されます。`aiEmbed` では テキスト関数とは別のデフォルト認証情報設定が使われる点に注意してください。これは、embeddings エンドポイント が chat エンドポイント とは異なるためです。 `model` は必須の位置引数 (定数の `String`) です。テキスト関数とは異なり、 `aiEmbed` は 名前付きコレクション や パラメータマップ から `model` を読み取りません。`model` を定義する 名前付きコレクション は、 暗黙的に無視されるのではなく、拒否されます。 オプションの `dimensions` parameter は、モデルが対応している場合 (たとえば OpenAI's `text-embedding-3-*`) 、 指定したサイズのベクトルを要求します。対応していない場合は、モデル本来のサイズが返されます。 **構文** ```sql theme={null} aiEmbed(text, model[, params]) ``` **引数** * `text` — 埋め込み対象のテキスト。[`String`](/docs/ja/reference/data-types/string) * `model` — 埋め込みモデル名。[`const String`](/docs/ja/reference/data-types/string) * `params` — 省略可能な定数 `Map(String, String)` パラメーター。関数固有のキー: `dimensions` (出力ベクトルの目標次元数。`0` または省略時はモデルのネイティブのサイズを意味します) 。共通パラメーター `credentials` も使用できます ([AI 関数](/docs/ja/reference/functions/regular-functions/ai-functions) を参照) 。[`Map(String, String)`](/docs/ja/reference/data-types/map) **戻り値** 埋め込みベクトル。入力が NULL または空の場合、リクエストが失敗して `ai_function_throw_on_error` が無効になっている場合、あるいは `ai_function_throw_on_quota_exceeded` が無効になっている状態でクォータを超過した場合は、空の配列を返します。[`Array(Float32)`](/docs/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`](/docs/ja/reference/data-types/string) * `instruction_or_schema` — 自由形式の抽出指示、または抽出するフィールドを記述した定数の JSONオブジェクト。[`const String`](/docs/ja/reference/data-types/string) * `params` — オプションの定数 `Map(String, String)` パラメーター。関数固有のキー: `temperature` (ランダム性を制御するサンプリング温度。デフォルト `0.0`)、`max_tokens` (1 回の呼び出しあたりの最大出力トークン数。デフォルト `1024`)。共通パラメーターである `credentials` と `model` も適用されます ([AI 関数](/docs/ja/reference/functions/regular-functions/ai-functions) を参照)。[`Map(String, String)`](/docs/ja/reference/data-types/map) **戻り値** 単一の抽出結果 (指示モード) または JSONオブジェクト文字列 (スキーマモード) 。リクエストが失敗し、`ai_function_throw_on_error` が無効になっている場合は、カラム型のデフォルト値 (空文字列) を返します。[`String`](/docs/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 ```
## 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`](/docs/ja/reference/data-types/string) * `params` — 省略可能な定数 `Map(String, String)` パラメータ。関数固有のキーは次のとおりです: `temperature` (ランダム性を制御するサンプリング温度。デフォルトは `0.7`) 、`max_tokens` (1 回の呼び出しで生成できる最大トークン数。デフォルトは `1024`) 、`system_prompt` (モデルの振る舞いを導く定数のシステムレベル命令。デフォルトは汎用的なアシスタント用プロンプト) 。共通パラメータの `credentials` と `model` も利用できます ([AI 関数](/docs/ja/reference/functions/regular-functions/ai-functions) を参照) 。[`Map(String, String)`](/docs/ja/reference/data-types/map) **戻り値** 生成されたテキスト応答。リクエストが失敗し、`ai_function_throw_on_error` が無効になっている場合は、カラム型のデフォルト値 (空文字列) が返されます。[`String`](/docs/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 ```
## 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`](/docs/ja/reference/data-types/string) * `target_language` — 対象言語名または BCP-47 コード (例: `'French'`, `'es-MX'`) 。 [`String`](/docs/ja/reference/data-types/string) * `params` — 省略可能な定数 `Map(String, String)` パラメータ。関数固有のキー: `temperature` (ランダム性を制御するサンプリング温度。デフォルトは `0.3`) 、`max_tokens` (1 回の呼び出しで生成される出力トークンの最大数。デフォルトは `1024`) 、`instructions` (翻訳向けの追加のスタイルまたは方言に関する指示) 。共通パラメータの `credentials` と `model` も使用できます ([AI 関数](/docs/ja/reference/functions/regular-functions/ai-functions) を参照) 。 [`Map(String, String)`](/docs/ja/reference/data-types/map) **戻り値** 翻訳されたテキスト。リクエストが失敗し、`ai_function_throw_on_error` が無効な場合は、カラム型のデフォルト値 (空文字列) を返します。 [`String`](/docs/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 ```