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_。

限制 端点 的主机

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 端点。

可观测性

可通过 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;

aiClassify

引入版本：v26.4.0

使用 LLM 提供商将给定文本分类到所提供类别中的某一类。

该函数会将文本连同固定的分类提示以及 JSON schema 响应格式一并发送， 从而约束模型严格返回所提供标签中的一个。当响应以 JSON 对象 {"category": "..."} 的形式返回时，会提取其中的标签并返回该标签字符串。

第一个参数是一个命名集合，用于指定提供商、模型、端点和 API 密钥。

语法

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

别名: AIClassify

参数

• collection — 包含提供商凭据和设置的命名集合名称。String
• text — 要分类的文本。String
• categories — 候选类别标签的常量列表。Array(String)
• temperature — 控制随机性的采样温度。默认值：0.0。Float64

返回值

提供的类别标签之一；如果请求失败且禁用了 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 提供商从非结构化文本中提取结构化信息。

第三个参数既可以是自由形式的自然语言指令 (例如 'the main complaint') ，也可以是 JSON 编码的 schema，格式如 '{"field_a": "description of field a", "field_b": "description of field b"}'。

在指令模式下，函数返回提取出的值 (纯字符串) ；如果未找到任何内容，则返回空字符串。 在 schema 模式下，函数返回一个 JSON 对象字符串，其键与所请求的 schema 一致；缺失字段为 null。

第一个参数是一个命名集合，用于指定提供商、模型、端点和 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 — 可选的固定系统级指令，用于引导模型的行为 (例如角色设定、输出格式) ，并会随每次提示一同发送。String
• temperature — 控制随机性的采样温度。默认值：0.7。Float64

返回值

生成的文本响应；如果请求失败且禁用了 ai_function_throw_on_error，则返回该列类型的默认值 (空字符串) 。String

示例

简单问题

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

4

使用系统提示

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 提供商将给定文本翻译为指定的目标语言。

还可以通过第四个参数传入额外的风格或方言说明 (例如 'keep technical terms untranslated') 。

第一个参数是一个命名集合，用于指定提供商、模型、端点和 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