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) されます。

設定

AI 関数は、プロバイダー認証情報と設定を格納する 名前付きコレクション を参照します。各関数の最初の引数は、このコレクションの名前です。プロバイダー認証情報を含む名前付きコレクションを作成するステートメントの例:

CREATE NAMED COLLECTION ai_credentials AS
    provider = 'openai',
    endpoint = 'https://api.openai.com/v1/chat/completions',
    model = 'gpt-4o-mini',
    api_key = 'sk-...';

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

パラメータ	型	デフォルト	説明
`provider`	String	—	モデルプロバイダー。サポート対象: `'openai'`, `'anthropic'`。以下の注記を参照してください。
`endpoint`	String	—	API エンドポイント URL。
`model`	String	—	モデル名 (例: `'gpt-4o-mini'`, `'text-embedding-3-small'`) 。
`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) を使用できます。

クエリレベルの設定

すべての 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 を使用するすべての機能に適用されることに注意してください。

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

プロバイダー	`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 を指定する名前付きコレクションです。構文

aiClassify(collection, text, categories[, temperature])

別名: AIClassify 引数

collection — プロバイダー credentials と設定を含む名前付きコレクションの名前。String
text — 分類するテキスト。String
categories — 候補となるカテゴリラベルの定数リスト。Array(String)
temperature — ランダム性を制御するサンプリング温度。デフォルト: 0.0。Float64

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

Query

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

Response

positive

カラムを分類する

Query

SELECT body, aiClassify('ai_credentials', body, ['bug', 'question', 'feature']) AS kind FROM issues LIMIT 5

Response

aiEmbed

導入バージョン: v26.6.0 設定されたAIプロバイダーを使用して、指定されたテキストの埋め込みベクトルを生成します。この関数は、テキストを設定済みの埋め込みエンドポイントに送信し、結果のベクトルを Array(Float32) として返します。 1つの行ブロック内では、呼び出しごとのオーバーヘッドを減らすため、入力は1回のHTTPリクエストあたり最大 ai_function_embedding_max_batch_size エントリのバッチにまとめられます。第1引数は、プロバイダー、モデル、エンドポイント、および必要に応じて API key を指定する名前付きコレクションです。任意の dimensions 引数は、モデルが対応している場合 (例: OpenAI’s text-embedding-3-*) 、指定したサイズのベクトルを要求します。対応していない場合は、モデル本来のサイズが返されます。構文

aiEmbed(collection, text[, dimensions])

引数

collection — プロバイダーの認証情報と設定を含む名前付きコレクションの名前。String
text — 埋め込み対象のテキスト。String
dimensions — 出力ベクトルの目標次元数 (省略可) 。0 または省略した場合は、モデルのネイティブなサイズになります。UInt64

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

Query

SELECT aiEmbed('ai_credentials', 'Hello world')

Response

明示的な次元を使用する

Query

SELECT aiEmbed('ai_credentials', 'Hello world', 256)

Response

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

Query

SELECT aiEmbed('ai_credentials', title, 256) FROM articles LIMIT 10

Response

aiExtract

導入バージョン: v26.4.0 LLMプロバイダーを使用して、非構造化テキストから構造化情報を抽出します。 3 番目の引数には、自由形式の自然言語による指示 (例: '主な訴え') または '{"field_a": "field a の説明", "field_b": "field b の説明"}' の形式の JSON エンコードされたスキーマを指定できます。指示モードでは、この関数は抽出した値をプレーンな文字列として返し、何も見つからなかった場合は空文字列を返します。スキーマモードでは、この関数は要求されたスキーマに対応するキーを持つ JSON オブジェクト文字列を返します。存在しないフィールドは null になります。 1 番目の引数は、プロバイダー、model、エンドポイント、および必要に応じて API key を指定する名前付きコレクションです。構文

aiExtract(collection, text, instruction_or_schema[, temperature])

別名: AIExtract 引数

collection — プロバイダー credentials と設定を含む名前付きコレクションの名前。String
text — 情報を抽出するテキスト。String
instruction_or_schema — 自由形式の抽出指示、または抽出するフィールドを記述した定数の JSONオブジェクト。const String
temperature — ランダム性を制御するサンプリング温度。デフォルト: 0.0。const Float64

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

Query

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

Response

late and damaged package

スキーマ抽出

Query

SELECT aiExtract('ai_credentials', review, '{"sentiment": "positive, negative or neutral", "topic": "main topic of the review"}') FROM reviews LIMIT 5

Response

aiGenerate

導入バージョン: v26.4.0 LLMプロバイダーを使用して、プロンプトから自由形式のテキストコンテンツを生成します。この関数は、設定されたAIプロバイダーにプロンプトを送信し、生成されたテキストを返します。任意のシステムプロンプトを指定して、モデルの挙動 (例: トーン、フォーマット、ロール) を制御できます。システムプロンプトが指定されていない場合、デフォルトのシステムプロンプトは次のとおりです: You are a helpful assistant. Provide a clear and concise response. 最初の引数は、プロバイダー、model、エンドポイント、必要に応じて API key を指定する名前付きコレクションです。構文

aiGenerate(collection, prompt[, system_prompt[, temperature]])

別名: AIGenerate 引数

collection — プロバイダー credentials と configuration を含む名前付きコレクションの名前。String
prompt — モデルに送信するユーザーのプロンプトまたは質問。String
system_prompt — モデルの動作を導く任意の固定のシステムレベル命令 (例: ペルソナ、出力フォーマット) 。各プロンプトとともに送信されます。String
temperature — ランダム性を制御するサンプリング温度。デフォルト: 0.7。Float64

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

Query

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

Response

システムプロンプトあり

Query

SELECT aiGenerate('ai_credentials', 'Explain ClickHouse', 'You are a database expert. Be concise.')

Response

カラム値を要約

Query

SELECT article_title, aiGenerate('ai_credentials', concat('Summarize in one sentence: ', article_body)) AS summary FROM articles LIMIT 5

Response

aiTranslate

導入バージョン: v26.4.0 指定したテキストを、LLMプロバイダーを使用して指定した対象言語に翻訳します。文体や方言に関する追加の指示は、第4引数として渡せます (例: 'keep technical terms untranslated') 。第1引数は、プロバイダー、model、エンドポイント、および必要に応じて API key を指定する名前付きコレクションです。構文

aiTranslate(collection, text, target_language[, instructions[, temperature]])

別名: AITranslate 引数

collection — プロバイダー credentials と configuration を含む名前付きコレクションの名前。String
text — 翻訳するテキスト。String
target_language — 翻訳先言語の名前または BCP-47 コード (例: 'French'、'es-MX') 。String
instructions — 翻訳者への追加指示 (任意の定数) 。String
temperature — ランダム性を制御するサンプリング温度。デフォルト: 0.3。Float64

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

Query

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

Response

Bonjour le monde!

スタイル指示に従って日本語に翻訳してください

Query

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

Response

​設定

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

​クエリレベルの設定

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

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

​オブザーバビリティ

​aiClassify

​aiEmbed

​aiExtract

​aiGenerate

​aiTranslate

設定

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

クエリレベルの設定

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

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

オブザーバビリティ

aiClassify

aiEmbed

aiExtract

aiGenerate

aiTranslate