AI 関数

AI 関数は ClickHouse に組み込まれている関数で、データに対して AI を呼び出したり、埋め込みを生成したり、情報を抽出したり、データを分類したりするために使用できます。

注記

AI 関数は予測不能な出力を返すことがあります。結果は、プロンプトの品質や使用するモデルに大きく左右されます。

すべての関数は共通のインフラストラクチャを使用しており、次の機能を提供します。

クォータの適用: クエリごとのトークン数制限 (ai_function_max_input_tokens_per_query、ai_function_max_output_tokens_per_query) および API 呼び出し数制限 (ai_function_max_api_calls_per_query) 。
backoff を伴う再試行: 一時的な障害が発生した場合は再試行され (ai_function_max_retries) 、指数 backoff が適用されます (ai_function_retry_initial_delay_ms) 。

設定

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	—	プロバイダーの認証キー。
`max_tokens`	UInt64	`1024`	API 呼び出しごとに出力できるトークンの最大数。
`api_version`	String	—	API バージョン文字列。Anthropic で使用されます (`'2023-06-01'`) 。

注記

provider = 'openai' を設定し、endpoint を対象のサービスに向けることで、任意の OpenAI 互換 API (例: vLLM, Ollama, LiteLLM) を使用できます。

クエリレベルの設定

AI 関連の設定はすべて、設定の ai_function_ プレフィックス配下に記載されています。

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

AI の名前付きコレクションにおける endpoint URL は、サーバーが自身の資格情報で接続する送信先であり、リクエストヘッダーにはその名前付きコレクションの api_key が含まれます。デフォルトでは、ClickHouse はすべてのホストを許可します。関数が接続できる先を特定のプロバイダ群に限定するには、サーバー設定で 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` エンドポイントを使用します。

オブザーバビリティ

AI 関数のアクティビティは、ClickHouse の ProfileEvents を通じて追跡されます。

ProfileEvent	Description
`AIAPICalls`	AI プロバイダーに送信された 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 つに分類します。

この関数は、固定の分類用プロンプトと JSON schema のレスポンス形式とともにテキストを送信し、モデルが指定されたラベルのうち正確に 1 つだけを返すよう制約します。レスポンスが {"category": "..."} 形式の JSON オブジェクトとして返された場合は、ラベルを取り出して、そのラベル文字列を返します。

最初の引数は、プロバイダー、モデル、エンドポイント、および API キーを指定する名前付きコレクションです。

構文

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

別名: AIClassify

引数

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

戻り値

指定されたカテゴリラベルのいずれか 1 つ、またはリクエストが失敗し、ai_function_throw_on_error が無効になっている場合は、カラム型の既定値 (空文字列) 。 String

例

感情を分類する

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

positive

カラムを分類する

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

aiExtract

導入バージョン: v26.4.0

LLMプロバイダーを使用して、非構造化テキストから構造化情報を抽出します。

3 番目の引数には、自由形式の自然言語の指示 (例: 'the main complaint') または '{"field_a": "description of field a", "field_b": "description of field b"}' 形式の JSON エンコードされた schema を指定できます。

指示モードでは、この関数は抽出された値をプレーンな文字列として返し、何も見つからなかった場合は空文字列を返します。 schema モードでは、この関数は要求した schema に対応するキーを持つ JSON オブジェクト文字列を返します。欠落しているフィールドは null になります。

最初の引数は、プロバイダー、model、エンドポイント、API キーを指定する名前付きコレクションです。

構文

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

別名: AIExtract

引数

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

戻り値

単一の抽出値 (指示モード) または JSON オブジェクト文字列 (schema モード) 。リクエストが失敗し、ai_function_throw_on_error が無効な場合は、カラム型のデフォルト値 (空文字列) を返します。String

例

自由形式の指示

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

late and damaged package

schema の抽出

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

aiGenerate

導入バージョン: v26.4.0

LLMプロバイダーを使用して、提示から自由形式のテキストコンテンツを生成します。

この関数は、設定されたAIプロバイダーに提示を送信し、生成されたテキストを返します。モデルの動作 (たとえば、口調、フォーマット、役割) を調整するために、任意のシステムプロンプトを指定できます。システムプロンプトが指定されていない場合、デフォルトのシステムプロンプトは次のとおりです: You are a helpful assistant. Provide a clear and concise response.

最初の引数は、プロバイダー、モデル、エンドポイント、API キーを指定する名前付きコレクションです。

構文

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

別名: AIGenerate

引数

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

戻り値

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

例

簡単な質問

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

システムプロンプト付き

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

カラム値の要約

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

aiTranslate

導入バージョン: v26.4.0

指定した対象言語に、指定した LLM プロバイダーを使用してテキストを翻訳します。

追加のスタイルやダイアレクトに関する指示は、4 番目の引数として渡すことができます (例: '技術用語は翻訳しない') 。

最初の引数は、プロバイダー、model、エンドポイント、API キーを指定する名前付きコレクションです。

構文

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

別名: AITranslate

引数

collection — プロバイダーの認証情報と設定を含む名前付きコレクションの名前。 String
text — 翻訳するテキスト。 String
target_language — 翻訳先言語の名前または BCP-47 コード (例: 'French', 'es-MX') 。 String
instructions — 翻訳に対する追加の指示 (省略可能な定数) 。 String
temperature — ランダム性を制御するサンプリング温度。既定値: 0.3。 Float64

戻り値

翻訳後のテキスト。リクエストが失敗し、ai_function_throw_on_error が無効な場合は、カラム型の既定値 (空文字列) を返します。 String

例

フランス語に翻訳

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

Bonjour le monde!

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

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

設定​

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

クエリレベルの設定​

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

サポート対象のプロバイダー​

オブザーバビリティ​

aiClassify​

aiExtract​

aiGenerate​

aiTranslate​

設定

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

クエリレベルの設定

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

サポート対象のプロバイダー

オブザーバビリティ

aiClassify

aiExtract

aiGenerate

aiTranslate