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) 施加限制。
• 带退避时间的重试：对瞬时故障进行重试 (ai_function_max_retries) ，并采用指数级退避时间 (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') 。

注意

任何兼容 OpenAI 的 API (例如 vLLM、Ollama、LiteLLM) 都可通过将 provider 设为 'openai'，并将 endpoint 指向你的服务来使用。

查询级设置

所有与 AI 相关的设置均列在设置中，前缀为 ai_function_。

支持的提供商

提供商	provider 值	聊天功能	说明
OpenAI	'openai'	是	默认提供商。
Anthropic	'anthropic'	是	使用 /v1/messages 端点。

可观测性

可通过 ClickHouse ProfileEvents 跟踪 AI 函数活动：

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;