AI 函数

AI 函数是 ClickHouse 中的内置函数，可用于调用 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 函数会引用一个命名集合，其中存储了提供商凭据和配置信息。可以针对不同的函数或函数调用创建并使用不同的命名集合。例如，你可能希望为文本函数 (aiGenerate、aiClassify、aiFilter、aiExtract、aiTranslate、aiRedact) 定义一个命名集合，而为嵌入向量函数 (aiEmbed、aiSimilarity) 定义另一个，因为它们需要不同的端点，通常也会使用不同的模型。

以下是创建包含提供商凭据的命名集合的示例语句：一个用于聊天端点，另一个用于 embedding 端点：

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

-- The embedding functions (`aiEmbed`, `aiSimilarity`) do not read `model` from the named collection,
-- pass it as a positional argument instead. Defining `model` in an embedding 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-...';

函数会按以下顺序确定要使用的命名集合：

1. 参数映射中的 credentials 键 (如果存在) ；
2. 否则，使用适用的默认凭据设置：
   • 文本函数 (aiGenerate、aiClassify、aiFilter、aiExtract、aiTranslate、aiRedact) 使用 ai_function_text_default_credentials；
   • 嵌入向量函数 (aiEmbed、aiSimilarity) 使用 ai_function_embedding_default_credentials。

如果两者都未设置，调用就会失败。文本函数和嵌入向量函数分别使用不同的默认设置，因为聊天补全所用的端点与嵌入向量所用的端点不同。

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'));

使用 aiFilter 通过自然语言条件过滤行；该函数返回 UInt8，可直接用于 WHERE：

SELECT * FROM reviews
WHERE aiFilter(body, 'the customer is angry about shipping');

每个函数都接受一个可选的末尾 Map(String, String) 参数映射。所有值都必须是字符串 (数字也要加引号，例如 '0.2') 。未知键会被拒绝。已提供的键会覆盖对应的命名集合值；未提供的键则回退到命名集合 (对于 model/max_tokens) 或内置默认值。例外情况是嵌入向量函数 (aiEmbed、aiSimilarity)，它们将 model 作为必需的位置参数 (例如 aiEmbed(text, model[, params])、aiSimilarity(text1, text2, model[, params])) 传入；如果改为在参数映射或命名集合中设置，则会报错。这是为了确保嵌入向量可复现。

以下参数是所有 AI 函数通用的：

各个函数还接受额外的函数专用参数 (例如 max_tokens、temperature、system_prompt、instructions 和 dimensions) 。有关每个函数支持的参数及其默认值，请参阅下方各函数的参考说明。

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

所有与 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 的功能。

传输方式完全由 endpoint URL 的 scheme 决定。请求载荷本身没有应用层加密；传输中数据的保护完全取决于所使用的 scheme：

• https:// — 连接使用 TLS。请求体 (输入文本、提示词) 以及请求头中的 api_key 都会在传输过程中加密，并且会验证提供商的证书。对于任何远程提供商，都应使用此方式。
• http:// — 连接不加密。请求体和 api_key 会以明文发送。仅应在私网中的可信提供商上使用此方式 (例如本地的 vLLM 或 Ollama 实例) 。

默认情况下，AI 函数会拒绝将数据以明文发送到远程主机的 endpoint：任何主机不是回环地址的非 HTTPS 端点都会引发异常。回环主机 (localhost、127.0.0.0/8、::1) 不受此限制，因此本地 http://localhost 模型服务器开箱即用。若要允许远程主机上的明文 http:// 端点，请将 ai_function_allow_insecure_endpoint 设置为 1。此检查独立于 remote_url_allow_hosts：该设置是主机允许列表，不会检查 URL scheme，因此指向允许主机的 http:// 端点仍然可以通过。

请注意，无论哪种情况，TLS 终止后提供商都会以明文接收输入数据；TLS 仅保护 服务器 与提供商之间网络路径上的数据。

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

查询这些事件：

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;

引入版本：v26.4.0

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

凭据 (一个用于指定提供商、模型、端点，以及可选的 API 密钥的命名集合) 取自可选参数映射中的 credentials 键，或者在该映射省略此项时， 取自 ai_function_text_default_credentials 设置。

语法

aiClassify(text, categories[, params])

别名: AIClassify

参数

• text — 待分类的文本。String
• categories — 候选类别标签的常量列表。Array(String)
• params — 可选的常量 Map(String, String) 参数映射。函数特定键包括：temperature (用于控制随机性的采样温度；默认值 0.0) 、max_tokens (每次调用的最大输出标记数；默认值 1024) 。通用参数 credentials 和 model 同样适用 (参见 AI 函数) 。Map(String, String)

返回值

返回提供的类别标签之一；如果请求失败且禁用了 ai_function_throw_on_error，则返回该列类型的默认值 (空字符串) 。String

示例

情感分类

SET allow_experimental_ai_functions = 1;
SELECT aiClassify('I love this product!', ['positive', 'negative', 'neutral'])

positive

使用显式凭据对列进行分类

SET allow_experimental_ai_functions = 1;
CREATE TABLE issues (body String) ENGINE = Memory;
INSERT INTO issues VALUES ('The application exits unexpectedly after login.');
SELECT body, aiClassify(body, ['bug', 'question', 'feature'], map('credentials', 'ai_text_credentials')) AS kind FROM issues LIMIT 5

引入于：v26.6.0

使用已配置的 AI 提供商为给定文本生成嵌入向量。

该函数会将文本发送到已配置的 embedding 端点，并以 Array(Float32) 形式返回结果向量。 在单个数据块内，输入会按批次分组，每个 HTTP 请求最多包含 ai_function_embedding_max_batch_size 个条目，以减少每次调用的额外开销。

凭据 (一个指定提供商、端点以及可选 API 密钥 的命名集合) 取自参数映射中的 credentials 键；如果映射中省略了该键，则使用 ai_function_embedding_default_credentials 设置。请注意，aiEmbed 使用的是一个 独立于文本函数的默认凭据设置，因为 embedding 端点与聊天端点不同。

model 是必需的位置参数 (一个常量 String) 。与文本函数不同， aiEmbed 不会从命名集合或参数映射中读取 model。如果某个命名集合 定义了 model，则会被拒绝。

可选的 dimensions 参数在模型支持时 (例如 OpenAI's text-embedding-3-*) 会请求返回指定大小的向量；否则将返回该模型的原生维度。

语法

aiEmbed(text, model[, params])

别名：AIEmbed

参数

• text — 要嵌入的文本。String
• model — 嵌入模型名称。const String
• params — 可选的常量参数映射。此函数特有的键为：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)

SET allow_experimental_ai_functions = 1;
SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials'))

显式指定维度

SET allow_experimental_ai_functions = 1;
SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256'))

嵌入文本列

SET allow_experimental_ai_functions = 1;
CREATE TABLE articles (title String) ENGINE = Memory;
INSERT INTO articles VALUES ('ClickHouse is a fast analytical database.');
SELECT aiEmbed(title, 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256')) FROM articles LIMIT 10

引入于：v26.4.0

使用 LLM 提供商从非结构化文本中提取结构化信息。

第三个参数既可以是自由形式的自然语言指令 (例如 '主要诉求') ，也可以是如下形式的 JSON 编码 schema：'{"field_a": "字段 a 的描述", "field_b": "字段 b 的描述"}'。

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

凭据 (用于指定提供商、模型、端点以及可选 API 密钥的命名集合) 取自可选参数映射中的 credentials 键；如果映射中未提供， 则取自 ai_function_text_default_credentials 设置。

语法

aiExtract(text, instruction_or_schema[, params])

别名: AIExtract

参数

• text — 要从中提取信息的文本。String
• instruction_or_schema — 自由格式的提取指令，或用于描述待提取字段的常量 JSON 对象。const String
• params — 可选的常量 Map(String, String) 参数映射。函数特定键包括：temperature (用于控制随机性的采样温度；默认值 0.0) ，max_tokens (每次调用的最大输出标记数；默认值 1024) 。通用参数 credentials 和 model 也适用 (参见 AI Functions) 。Map(String, String)

返回值

单个提取值 (指令模式) ，或 JSON 对象字符串 (schema 模式) 。如果请求失败且禁用了 ai_function_throw_on_error，则返回该列类型的默认值 (空字符串) 。String

示例

自由格式指令

SET allow_experimental_ai_functions = 1;
SELECT aiExtract('The package arrived late and was damaged.', 'the main complaint')

late and damaged package

Schema 提取

SET allow_experimental_ai_functions = 1;
CREATE TABLE reviews (review String) ENGINE = Memory;
INSERT INTO reviews VALUES ('The screen is bright, but the battery lasts only two hours.');
SELECT aiExtract(review, '{"sentiment": "positive, negative or neutral", "topic": "main topic of the review"}') FROM reviews LIMIT 5

引入版本：v26.8.0

使用 LLM 提供商根据给定文本评估自然语言条件，并返回适用于 WHERE、PREWHERE 和 JOIN ... ON 的布尔值 (UInt8) 。

该函数要求模型仅以小写 true 或 false 作答。除 true 以外的任何完整响应 (包括 false 和无法识别的文本) 都会映射为 0，因此会过滤掉该行。提供商标记为不完整的回复——被截断、经过内容过滤或需要进一步操作——则会被 视为错误：启用 ai_function_throw_on_error (默认值) 时，查询会中止；禁用该设置时， 该行会映射为 0 并被过滤掉。

Warning： 请勿在未经审查的情况下信任 aiFilter 的结果。基于 LLM 的谓词可能不正确 或不一致；仅应在可以接受假阳性和假阴性的场景中使用。

凭据 (指定提供商、模型、端点以及可选 API 密钥的命名集合) 取自可选参数映射中的 credentials 键；如果映射中未指定该键，则取自 ai_function_text_default_credentials 设置。

注意：在 JOIN ... ON 中使用 aiFilter 时，会针对每个候选对调用一次 LLM，因此成本可能很高。

语法

aiFilter(text, condition[, params])

别名：AIFilter

参数

• text — 要评估的文本。String
• condition — 文本必须满足的固定自然语言条件。String
• params — 可选的固定 Map(String, String) 参数映射。函数特定键：temperature (控制随机性的采样温度；默认值为 0.0) 和 max_tokens (每次调用允许的最大输出标记数；默认值为 1024) 。通用参数 credentials 和 model 同样适用 (请参阅 AI 函数) 。Map(String, String)

返回值

文本符合条件时返回 1，否则返回 0。如果请求失败且禁用了 ai_function_throw_on_error，则返回默认值 (0) 。UInt8

示例

过滤愤怒评论

SET allow_experimental_ai_functions = 1;
CREATE TABLE reviews (body String) ENGINE = Memory;
INSERT INTO reviews VALUES ('The package arrived three days late.');
SELECT * FROM reviews WHERE aiFilter(body, 'the customer is angry about shipping')

使用显式凭据筛选列

SET allow_experimental_ai_functions = 1;
CREATE TABLE issues (body String) ENGINE = Memory;
INSERT INTO issues VALUES ('The application exits unexpectedly after login.');
SELECT body, aiFilter(body, 'describes a bug', map('credentials', 'ai_text_credentials')) AS is_bug FROM issues LIMIT 5

引入版本：v26.4.0

使用 LLM 提供商根据提示词生成自由形式的文本内容。

该函数会将提示词发送给已配置的 AI 提供商，并返回生成的文本。

凭据 (一个 命名集合，用于指定提供商、模型、端点，以及可选的 API 密钥) 取自可选参数映射中的 credentials 键；如果该映射中未提供，则取自 ai_function_text_default_credentials 设置。

可选参数映射还可设置 system_prompt (用于引导模型行为的指令， 例如语气、格式、角色) 、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 (每次调用可生成的最大输出标记数；默认值为 1024) 、system_prompt (用于引导模型行为的常量系统级指令；默认值为通用助手提示词) 。通用参数 credentials 和 model 也同样适用 (参见 AI 函数) 。Map(String, String)

返回值

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

示例

简单问题

SET allow_experimental_ai_functions = 1;
SELECT aiGenerate('What is 2 + 2? Reply with just the number.')

4

使用明确指定的凭据和系统提示词

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

汇总列中的值

SET allow_experimental_ai_functions = 1;
CREATE TABLE articles (article_title String, article_body String) ENGINE = Memory;
INSERT INTO articles VALUES ('ClickHouse', 'ClickHouse is an open-source column-oriented database for online analytical processing.');
SELECT article_title, aiGenerate(concat('Summarize in one sentence: ', article_body)) AS summary FROM articles LIMIT 5

引入版本：v26.8.0

使用 LLM 提供商检测并脱敏给定文本中的个人身份信息 (PII) 。

每个检测到的 PII span 都会被替换为脱敏标记 (默认为 [REDACTED]，可通过 replacement 参数配置) 。categories 数组用于限制要脱敏的 PII 类型；空数组 会回退到一组常见类别的默认集合 (姓名、电子邮件、电话号码、地址、信用卡、IP 地址) 。

aiRedact 会指示模型仅修改检测到的 PII span，但保留周围文本只能 尽力而为，模型仍可能对其进行修改 (请参阅上方警告) 。除制表符、 换行符和回车符外，其他控制字符也会在发送请求前归一化为空格，因此对于包含这些字符的输入，输出 不会与输入按字节完全相同。

由于 aiRedact 返回替换 PII 后的完整输入文本，输出长度大致与输入相同。 请将 max_tokens (默认值为 1024) 设置为大于输入的标记数；因限制过低而被截断的回复 会被拒绝并返回 AI_PROVIDER_RESPONSE_TRUNCATED (或在禁用 ai_function_throw_on_error 时返回列默认值) ，而不会返回部分脱敏的文本。

语法

aiRedact(text, categories[, params])

别名：AIRedact

参数

• text — 要脱敏的文本。String
• categories — 要脱敏的 PII 类别常量列表 (例如 ['name', 'ssn', 'credit_card']) 。空数组会使用一组默认的常见类别 (姓名、电子邮件、电话号码、地址、信用卡、IP 地址) 。Array(String)
• params — 可选的常量 Map(String, String) 参数映射。函数专用键包括：temperature (控制随机性的采样温度；默认值为 0.0) 、max_tokens (每次调用的最大输出标记数；默认值为 1024——由于 aiRedact 返回完整文本，应将其设为大于输入标记数的值；因限制过低而被截断的回复会被拒绝，而不会返回仅部分脱敏的文本) 、replacement (用于替换每个检测到的 PII span 的标记；默认值为 [REDACTED]) 。通用参数 credentials 和 model 同样适用 (请参阅 AI 函数) 。Map(String, String)

返回值

将检测到的 PII 替换为脱敏标记后的文本；如果请求失败且禁用了 ai_function_throw_on_error，则返回列类型的默认值 (空字符串) 。String

示例

对特定类别进行脱敏

SET allow_experimental_ai_functions = 1;
SELECT aiRedact('Purchase was done by customer John Doe with email test@test.org', ['email', 'credit_card', 'name'])

Purchase was done by customer [REDACTED] with email [REDACTED]

使用自定义标记对默认 PII 类别进行脱敏

SET allow_experimental_ai_functions = 1;
CREATE TABLE tickets (body String) ENGINE = Memory;
INSERT INTO tickets VALUES ('Contact Jane Doe at jane@example.com.');
SELECT aiRedact(body, [], map('replacement', '***')) FROM tickets LIMIT 5

引入版本：v26.8.0

使用已配置的嵌入向量提供商计算两段文本的语义相似度。

计算两段文本的嵌入向量，并返回其 余弦相似度。得分为 -1 表示 嵌入向量方向相反；在语义上，这意味着得分接近 -1 的文本含义相反。 得分为 0 表示向量正交：在语义上毫不相关。最后，得分为 1 表示嵌入向量指向相同方向，得分接近 1 的文本 含义相似。这与基于相同嵌入向量计算的 cosineDistance 互为补集 (aiSimilarity = 1 - cosineDistance(embedding1, embedding2))。

批处理、凭据和 dimensions 参数均与 aiEmbed 相同，包括 ai_function_embedding_default_credentials 默认凭据设置。

与 aiEmbed 一样，model 是必需的位置参数 (常量 String) ，不会从 命名集合或参数映射中读取。

语法

aiSimilarity(text1, text2, model[, params])

别名：AISimilarity

参数

• text1 — 第一个文本。String
• text2 — 第二个文本。String
• model — 嵌入模型名称。const String
• params — 可选的常量参数映射。该函数专用的键：dimensions (嵌入向量的目标维度；0 或省略时使用模型的原生维度) 。通用参数 credentials 也适用 (参见 AI 函数) 。Map(String, String)

返回值

[-1, 1] 范围内的余弦相似度。如果任一文本为 NULL 或为空、嵌入请求失败且禁用了 ai_function_throw_on_error，或者超出配额且禁用了 ai_function_throw_on_quota_exceeded，则返回 NULL。Nullable(Float32)

示例

比较两个字符串 (如果设置了 ai_function_embedding_default_credentials，则可省略 credentials)

SET allow_experimental_ai_functions = 1;
SELECT aiSimilarity('cat', 'kitten', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials'))

按与查询的相似度对评论排序

SET allow_experimental_ai_functions = 1;
CREATE TABLE product_reviews (review String) ENGINE = Memory;
INSERT INTO product_reviews VALUES ('It works well under rain.');
SELECT review FROM product_reviews ORDER BY aiSimilarity(review, 'It works well under rain', 'text-embedding-3-small') DESC LIMIT 100

通过自连接实现语义去重

SET allow_experimental_ai_functions = 1;
CREATE TABLE docs (id UInt64, title String) ENGINE = Memory;
INSERT INTO docs VALUES (1, 'ClickHouse documentation'), (2, 'ClickHouse database guide');
SELECT a.id, b.id FROM docs a, docs b WHERE a.id < b.id AND aiSimilarity(a.title, b.title, 'text-embedding-3-small') > 0.9

引入版本：v26.4.0

使用 LLM 提供商将给定文本翻译成指定的目标语言。

还可以通过参数映射中的 instructions 键传入额外的风格或语言变体说明 (例如：'保留技术术语不翻译') 。

凭据 (一个命名集合，用于指定提供商、模型、端点，以及可选的 API 密钥) 取自可选参数映射中的 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 (每次调用可生成的最大输出标记数；默认值为 1024) 、instructions (给翻译器的附加风格或方言说明) 。通用参数 credentials 和 model 同样适用 (参见 AI 函数) 。Map(String, String)

返回值

翻译后的文本；如果请求失败且 ai_function_throw_on_error 被禁用，则返回列类型的默认值 (空字符串) 。String

示例

翻译成法语

SET allow_experimental_ai_functions = 1;
SELECT aiTranslate('Hello, world!', 'French')

Bonjour le monde!

根据风格说明翻译成日语

SET allow_experimental_ai_functions = 1;
CREATE TABLE articles (body String) ENGINE = Memory;
INSERT INTO articles VALUES ('ClickHouse processes analytical queries quickly.');
SELECT aiTranslate(body, 'Japanese', map('instructions', 'Use polite form (desu/masu)')) FROM articles LIMIT 5