AI 関数 - ClickHouse Documentation

AI 関数は ClickHouse の組み込み関数で、AI の呼び出しや埋め込みの生成に使用でき、データの処理、情報の抽出、データの分類などを行えます。

AI 関数は Experimental です。有効にするには allow_experimental_ai_functions を設定してください。

AI 関数は予測不能な出力を返す場合があります。結果は、プロンプトの品質と使用するモデルに大きく依存します。

すべての関数は、以下を提供する共通のインフラストラクチャを利用しています。

クォータの適用: トークン (ai_function_max_input_tokens_per_query, ai_function_max_output_tokens_per_query) および API 呼び出し (ai_function_max_api_calls_per_query) に対するクエリ単位の上限。
バックオフ付き再試行: 一時的な障害は、指数バックオフ (ai_function_retry_initial_delay_ms) を使用して再試行 (ai_function_max_retries) されます。

Configuration

AI 関数は、プロバイダーの認証情報と設定を格納した 名前付きコレクション を参照します。関数ごと、または関数呼び出しごとに、異なる名前付きコレクションを作成して使い分けることができます。たとえば、テキスト関数 (aiGenerate、aiClassify、aiExtract、aiTranslate) で使用する名前付きコレクションと、異なるエンドポイントが必要で通常は異なるモデルを使用する aiEmbed 関数で使用する名前付きコレクションを、別々に定義したい場合があります。プロバイダーの認証情報を含む名前付きコレクションを作成するための例のステートメントを以下に示します。1 つはチャット用エンドポイント、もう 1 つは埋め込み用エンドポイントです。

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) を使用できます。

認証情報の選択

関数は、使用する 名前付きコレクション を次の順序で特定します。

存在する場合は、パラメータマップの credentials キー。
それ以外の場合は、該当するデフォルト認証情報の設定。
- テキスト関数 (aiGenerate、aiClassify、aiExtract、aiTranslate) では ai_function_text_default_credentials。
- aiEmbed では ai_function_embedding_default_credentials。

どちらも設定されていない場合、呼び出しは失敗します。テキスト関数と埋め込み関数でデフォルト設定が分かれているのは、chat-completions のエンドポイントが embeddings 用のものとは異なるためです。

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 など) を受け付けます。受け付けるパラメータとそのデフォルト値については、以下の各関数のリファレンスを参照してください。

SELECT aiGenerate(body, map('temperature', '0.2', 'system_prompt', 'You are terse.')) FROM articles;

クエリレベルの設定

すべての AI 関連の設定は、ai_function_ プレフィックスで Settings に一覧表示されています。

エンドポイントホストの制限

AI named collection の endpoint URL は、サーバーが自身の identity で接続する送信先であり、リクエストヘッダーに named collection の api_key を (指定されている場合に) 含めて送信する可能性があります。デフォルトでは、ClickHouse はすべてのホストへの接続を許可します。関数を特定の provider 群のみに制限するには、サーバー設定で remote_url_allow_hosts を設定します。例:

<remote_url_allow_hosts>
    <host>api.openai.com</host>
    <host>api.anthropic.com</host>
</remote_url_allow_hosts>

この設定はサーバー全体に適用され、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 は宛先 host のみを制限し、URL スキームは検査しないため、許可された host への http:// エンドポイントは引き続き許可されます。転送を暗号化したい場合は、https:// エンドポイントを使うように名前付きコレクションを設定してください。いずれの場合も、プロバイダーは TLS 終端後の入力データを平文で受け取る点に注意してください。TLS が保護するのは、server とプロバイダーの間のネットワーク経路上のデータのみです。

サポートされているプロバイダー

プロバイダー	`provider` の値	チャット関数	注記
OpenAI	`'openai'`	はい	デフォルトのプロバイダーです。
Anthropic	`'anthropic'`	はい	`/v1/messages` endpoint を使用します。

オブザーバビリティ

AI 関数のアクティビティは、ClickHouse の ProfileEvents で追跡できます。

ProfileEvent	Description
`AIAPICalls`	AI provider に送信された HTTP リクエスト数。
`AIInputTokens`	消費された入力トークンの合計数。
`AIOutputTokens`	消費された出力トークンの合計数。
`AIRowsProcessed`	結果が返された行数。
`AIRowsSkipped`	スキップされた行数 (クォータ超過、または `ai_function_throw_on_error = 0` の場合のエラー) 。

これらのイベントをクエリします。

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 つに分類します。この関数は、固定の分類プロンプトと、モデルが指定されたラベルのうちちょうど 1 つだけを返すよう制約する JSON スキーマのレスポンスフォーマットとともに、テキストを送信します。レスポンスが {"category": "..."} 形式の JSON オブジェクトとして返された場合は、ラベルが取り出され、その文字列が返されます。認証情報 (プロバイダー、モデル、エンドポイント、および必要に応じて API key を指定する名前付きコレクション) は、オプションのパラメータマップの credentials キーから取得されるか、その map で省略されている場合は ai_function_text_default_credentials 設定から取得されます。構文

aiClassify(text, categories[, params])

別名: AIClassify 引数

text — 分類するテキスト。String
categories — 候補となるカテゴリラベルの定数リスト。Array(String)
params — オプションの定数 Map(String, String) パラメーター。関数固有のキー: temperature (ランダム性を制御するサンプリング温度。デフォルト 0.0)、max_tokens (1 回の呼び出しあたりの最大出力トークン数。デフォルト 1024)。共通パラメーター credentials と model も適用されます (AI 関数を参照)。Map(String, String)

戻り値 指定されたカテゴリラベルのいずれか、またはリクエストが失敗し、ai_function_throw_on_error が無効になっている場合はカラム型のデフォルト値 (空文字列) 。String 例 感情を分類

Query

SELECT aiClassify('I love this product!', ['positive', 'negative', 'neutral'])

Response

positive

明示的に指定した認証情報を使用してカラムを分類する

Query

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 エントリの 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-*) 、指定したサイズのベクトルを要求します。対応していない場合は、モデル本来のサイズが返されます。構文

aiEmbed(text, model[, params])

引数

text — 埋め込み対象のテキスト。String
model — 埋め込みモデル名。const String
params — 省略可能な定数 Map(String, String) パラメーター。関数固有のキー: dimensions (出力ベクトルの目標次元数。0 または省略時はモデルのネイティブのサイズを意味します) 。共通パラメーター credentials も使用できます (AI 関数を参照) 。Map(String, String)

戻り値 埋め込みベクトル。入力が NULL または空の場合、リクエストが失敗して ai_function_throw_on_error が無効になっている場合、あるいは ai_function_throw_on_quota_exceeded が無効になっている状態でクォータを超過した場合は、空の配列を返します。Array(Float32) 例 単一の文字列を埋め込む (ai_function_embedding_default_credentials が設定されている場合、credentials は省略できます)

Query

SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials'))

次元を明示する場合

Query

SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256'))

テキストを含むカラムを埋め込む

Query

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 から取得されます。構文

aiExtract(text, instruction_or_schema[, params])

別名: AIExtract 引数

text — 情報を抽出するテキスト。String
instruction_or_schema — 自由形式の抽出指示、または抽出するフィールドを記述した定数の JSONオブジェクト。const String
params — オプションの定数 Map(String, String) パラメーター。関数固有のキー: temperature (ランダム性を制御するサンプリング温度。デフォルト 0.0)、max_tokens (1 回の呼び出しあたりの最大出力トークン数。デフォルト 1024)。共通パラメーターである credentials と model も適用されます (AI 関数を参照)。Map(String, String)

戻り値 単一の抽出結果 (指示モード) または JSONオブジェクト文字列 (スキーマモード) 。リクエストが失敗し、ai_function_throw_on_error が無効になっている場合は、カラム型のデフォルト値 (空文字列) を返します。String 例 自由形式の指示

Query

SELECT aiExtract('The package arrived late and was damaged.', 'the main complaint')

Response

late and damaged package

スキーマ抽出

Query

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. 構文

aiGenerate(prompt[, params])

別名: AIGenerate 引数

prompt — モデルに送信する、ユーザーのプロンプトまたは質問。String
params — 省略可能な定数 Map(String, String) パラメータ。関数固有のキーは次のとおりです: temperature (ランダム性を制御するサンプリング温度。デフォルトは 0.7) 、max_tokens (1 回の呼び出しで生成できる最大トークン数。デフォルトは 1024) 、system_prompt (モデルの振る舞いを導く定数のシステムレベル命令。デフォルトは汎用的なアシスタント用プロンプト) 。共通パラメータの credentials と model も利用できます (AI 関数を参照) 。Map(String, String)

戻り値 生成されたテキスト応答。リクエストが失敗し、ai_function_throw_on_error が無効になっている場合は、カラム型のデフォルト値 (空文字列) が返されます。String 例 単純な質問

Query

SELECT aiGenerate('What is 2 + 2? Reply with just the number.')

Response

明示的に指定した認証情報とシステムプロンプト

Query

SELECT aiGenerate('Explain ClickHouse', map('credentials', 'ai_text_credentials', 'system_prompt', 'You are a database expert. Be concise.'))

カラムの値を要約する

Query

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 設定から取得されます。構文

aiTranslate(text, target_language[, params])

別名: AITranslate 引数

text — 翻訳するテキスト。 String
target_language — 対象言語名または BCP-47 コード (例: 'French', 'es-MX') 。 String
params — 省略可能な定数 Map(String, String) パラメータ。関数固有のキー: temperature (ランダム性を制御するサンプリング温度。デフォルトは 0.3) 、max_tokens (1 回の呼び出しで生成される出力トークンの最大数。デフォルトは 1024) 、instructions (翻訳向けの追加のスタイルまたは方言に関する指示) 。共通パラメータの credentials と model も使用できます (AI 関数を参照) 。 Map(String, String)

戻り値 翻訳されたテキスト。リクエストが失敗し、ai_function_throw_on_error が無効な場合は、カラム型のデフォルト値 (空文字列) を返します。 String 例 フランス語に翻訳

Query

SELECT aiTranslate('Hello, world!', 'French')

Response

Bonjour le monde!

スタイル指示に従って日本語に翻訳

Query

SELECT aiTranslate(body, 'Japanese', map('instructions', 'Use polite form (desu/masu)')) FROM articles LIMIT 5

​Configuration

​名前付きコレクションのパラメータ

​認証情報の選択

​パラメータマップ

​クエリレベルの設定

​エンドポイントホストの制限

​転送のセキュリティ (HTTP と HTTPS)

​サポートされているプロバイダー

​オブザーバビリティ

​aiClassify

​aiEmbed

​aiExtract

​aiGenerate

​aiTranslate

Configuration

名前付きコレクションのパラメータ

認証情報の選択

パラメータマップ

クエリレベルの設定

エンドポイントホストの制限

転送のセキュリティ (HTTP と HTTPS)

サポートされているプロバイダー

オブザーバビリティ

aiClassify

aiEmbed

aiExtract

aiGenerate

aiTranslate