Skip to main content
AI 函数是 ClickHouse 中的内置函数,可用于调用 AI 或生成嵌入向量,以处理数据、提取信息、对数据进行分类等……
AI 函数处于 Experimental 阶段。设置 allow_experimental_ai_functions 以启用它们。AI 函数可能会返回不可预测的输出。结果在很大程度上取决于提示词的质量和所使用的模型。
提示词注入输入文本会被发送到模型,并可能引导其输出 (提示词注入) 。来自外部、未经验证或未经清理的来源的文本可能包含指令,使模型返回受攻击者控制的内容、忽略所请求的格式或输出恶意载荷。请将 AI 函数输出视为不可信:在将其用于构建 SQL、shell 命令、后续查询或访问控制决策等下游步骤之前,先对其进行验证或清理。
所有函数共用一套通用基础设施,提供:

配置

AI 函数会引用一个命名集合,其中存储了提供商凭据和配置信息。可以针对不同的函数或函数调用创建并使用不同的命名集合。例如,你可能希望为文本函数 (aiGenerateaiClassifyaiFilteraiExtractaiTranslateaiRedact) 定义一个命名集合,而为嵌入向量函数 (aiEmbedaiSimilarity) 定义另一个,因为它们需要不同的端点,通常也会使用不同的模型。 以下是创建包含提供商凭据的命名集合的示例语句:一个用于聊天端点,另一个用于 embedding 端点:

命名集合参数

provider 设为 'openai',并把 endpoint 指向你的服务,即可使用任何与 OpenAI 兼容的 API (例如 vLLM、Ollama、LiteLLM) 。

选择凭据

函数会按以下顺序确定要使用的命名集合:
  1. 参数映射中的 credentials 键 (如果存在) ;
  2. 否则,使用适用的默认凭据设置:
如果两者都未设置,调用就会失败。文本函数和嵌入向量函数分别使用不同的默认设置,因为聊天补全所用的端点与嵌入向量所用的端点不同。
使用 aiFilter 通过自然语言条件过滤行;该函数返回 UInt8,可直接用于 WHERE

参数映射

每个函数都接受一个可选的末尾 Map(String, String) 参数映射。所有值都必须是字符串 (数字也要加引号,例如 '0.2') 。未知键会被拒绝。已提供的键会覆盖对应的命名集合值;未提供的键则回退到命名集合 (对于 model/max_tokens) 或内置默认值。例外情况是嵌入向量函数 (aiEmbedaiSimilarity),它们将 model 作为必需的位置参数 (例如 aiEmbed(text, model[, params])aiSimilarity(text1, text2, model[, params])) 传入;如果改为在参数映射或命名集合中设置,则会报错。这是为了确保嵌入向量可复现。 以下参数是所有 AI 函数通用的: 各个函数还接受额外的函数专用参数 (例如 max_tokenstemperaturesystem_promptinstructionsdimensions) 。有关每个函数支持的参数及其默认值,请参阅下方各函数的参考说明。

查询级别设置

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

限制端点主机

AI 命名集合中的 endpoint URL 是服务器以自身身份连接的出站目标端,并可能 (如果已指定) 在请求头中携带该命名集合的 api_key。默认情况下,ClickHouse 允许连接任意主机。要将函数限制为一组特定的提供商,请在服务器配置中设置 remote_url_allow_hosts,例如:
请注意,此设置对整个服务器生效,并适用于所有使用 HTTP 的功能。

传输安全 (HTTP 与 HTTPS)

传输方式完全由 endpoint URL 的 scheme 决定。请求载荷本身没有应用层加密;传输中数据的保护完全取决于所使用的 scheme:
  • https:// — 连接使用 TLS。请求体 (输入文本、提示词) 以及请求头中的 api_key 都会在传输过程中加密,并且会验证提供商的证书。对于任何远程提供商,都应使用此方式。
  • http:// — 连接不加密。请求体和 api_key 会以明文发送。仅应在私网中的可信提供商上使用此方式 (例如本地的 vLLMOllama 实例) 。
默认情况下,AI 函数会拒绝将数据以明文发送到远程主机的 endpoint:任何主机不是回环地址的非 HTTPS 端点都会引发异常。回环主机 (localhost127.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 函数活动: 查询这些事件:

aiClassify

引入版本:v26.4.0 使用 LLM 提供商将给定文本归类到所提供类别中的某一类。 凭据 (一个用于指定提供商、模型、端点,以及可选的 API 密钥的命名集合) 取自可选参数映射中的 credentials 键,或者在该映射省略此项时, 取自 ai_function_text_default_credentials 设置。 语法
别名: AIClassify 参数
  • text — 待分类的文本。String
  • categories — 候选类别标签的常量列表。Array(String)
  • params — 可选的常量 Map(String, String) 参数映射。函数特定键包括:temperature (用于控制随机性的采样温度;默认值 0.0) 、max_tokens (每次调用的最大输出标记数;默认值 1024) 。通用参数 credentialsmodel 同样适用 (参见 AI 函数) 。Map(String, String)
返回值 返回提供的类别标签之一;如果请求失败且禁用了 ai_function_throw_on_error,则返回该列类型的默认值 (空字符串) 。String 示例 情感分类
Query
Response
使用显式凭据对列进行分类
Query

aiEmbed

引入于: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 — 要嵌入的文本。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)
Query
显式指定维度
Query
嵌入文本列
Query

aiExtract

引入于: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 — 要从中提取信息的文本。String
  • instruction_or_schema — 自由格式的提取指令,或用于描述待提取字段的常量 JSON 对象。const String
  • params — 可选的常量 Map(String, String) 参数映射。函数特定键包括:temperature (用于控制随机性的采样温度;默认值 0.0) ,max_tokens (每次调用的最大输出标记数;默认值 1024) 。通用参数 credentialsmodel 也适用 (参见 AI Functions) 。Map(String, String)
返回值 单个提取值 (指令模式) ,或 JSON 对象字符串 (schema 模式) 。如果请求失败且禁用了 ai_function_throw_on_error,则返回该列类型的默认值 (空字符串) 。String 示例 自由格式指令
Query
Response
Schema 提取
Query

aiFilter

引入版本:v26.8.0 使用 LLM 提供商根据给定文本评估自然语言条件,并返回适用于 WHEREPREWHEREJOIN ... ON 的布尔值 (UInt8) 。 该函数要求模型仅以小写 truefalse 作答。失败的请求 (当 ai_function_throw_on_error 被禁用时) 和无法识别的响应都会映射为 0,因此会过滤掉该行。 Warning: 请勿在未经审查的情况下信任 aiFilter 的结果。基于 LLM 的谓词可能不正确 或不一致;仅应在可以接受假阳性和假阴性的场景中使用。 凭据 (指定提供商、模型、端点以及可选 API 密钥的命名集合) 取自可选参数映射中的 credentials 键;如果映射中未指定该键,则取自 ai_function_text_default_credentials 设置。 注意:在 JOIN ... ON 中使用 aiFilter 时,会针对每个候选对调用一次 LLM,因此成本可能很高。 语法
别名AIFilter 参数
  • text — 要评估的文本。String
  • condition — 文本必须满足的固定自然语言条件。String
  • params — 可选的固定 Map(String, String) 参数映射。函数特定键:temperature (控制随机性的采样温度;默认值为 0.0) 和 max_tokens (每次调用允许的最大输出标记数;默认值为 1024) 。通用参数 credentialsmodel 同样适用 (请参阅 AI 函数) 。Map(String, String)
返回值 文本符合条件时返回 1,否则返回 0。如果请求失败且禁用了 ai_function_throw_on_error,则返回默认值 (0) 。UInt8 示例 过滤愤怒评论
Query
使用显式凭据筛选列
Query

aiGenerate

引入版本:v26.4.0 使用 LLM 提供商根据提示生成自由形式的文本内容。 该函数会将提示发送给已配置的 AI 提供商,并返回生成的文本。 凭据 (一个 命名集合,用于指定提供商、模型、端点,以及可选的 API 密钥) 取自可选参数映射中的 credentials 键;如果该映射中未提供,则取自 ai_function_text_default_credentials 设置。 可选参数映射还可设置 system_prompt (用于引导模型行为的指令, 例如语气、格式、角色) 、temperaturemax_tokensmodel。如果未设置 system_prompt, 默认值为:You are a helpful assistant. Provide a clear and concise response. 语法
别名: AIGenerate 参数
  • prompt — 发送给模型的用户提示词或问题。String
  • params — 可选的常量 Map(String, String) 参数映射。此函数特有的键包括:temperature (控制随机性的采样温度;默认值为 0.7) 、max_tokens (每次调用可生成的最大输出标记数;默认值为 1024) 、system_prompt (用于引导模型行为的常量系统级指令;默认值为通用助手提示词) 。通用参数 credentialsmodel 也同样适用 (参见 AI 函数) 。Map(String, String)
返回值 生成的文本响应;如果请求失败且 ai_function_throw_on_error 被禁用,则返回该列类型的默认值 (空字符串) 。String 示例 简单问题
Query
Response
使用明确指定的凭据和系统提示
Query
汇总列中的值
Query

aiRedact

引入版本:v26.8.0 使用 LLM 提供商检测并脱敏给定文本中的个人身份信息 (PII) 。
aiRedact 使用 LLM 尽力检测和脱敏 PII,其输出并不 可靠。能否检测和移除 PII 取决于所选模型、提示词和输入:模型可能遗漏 标识符、仅部分脱敏,或修改周围文本。它最适合处理 格式规范的英文文本;对于其他语言或存在大量拼写、 标点或语法错误的文本,结果可能较差。aiRedact 不保证其输出不含 PII,因此不得 单独将其视为安全或充分的匿名化机制。在向不受信任方暴露数据之前,务必审查输出,以确保其 符合您组织的数据隐私和合规政策。
每个检测到的 PII span 都会被替换为脱敏标记 (默认为 [REDACTED],可通过 replacement 参数配置) 。categories 数组用于限制要脱敏的 PII 类型;空数组 会回退到一组常见类别的默认集合 (姓名、电子邮件、电话号码、地址、信用卡、IP 地址) 。 aiRedact 会指示模型仅修改检测到的 PII span,但保留周围文本只能 尽力而为,模型仍可能对其进行修改 (请参阅上方警告) 。除制表符、 换行符和回车符外,其他控制字符也会在发送请求前归一化为空格,因此对于包含这些字符的输入,输出 不会与输入按字节完全相同。 由于 aiRedact 返回替换 PII 后的完整输入文本,输出长度大致与输入相同。 请将 max_tokens (默认值为 1024) 设置为大于输入的标记数;因限制过低而被截断的回复 将不完整。 语法
别名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]) 。通用参数 credentialsmodel 同样适用 (请参阅 AI 函数) 。Map(String, String)
返回值 将检测到的 PII 替换为脱敏标记后的文本;如果请求失败且禁用了 ai_function_throw_on_error,则返回列类型的默认值 (空字符串) 。String 示例 对特定类别进行脱敏
Query
Response
使用自定义标记对默认 PII 类别进行脱敏
Query

aiSimilarity

引入版本: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 — 第一个文本。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)
Query
按与查询的相似度对评论排序
Query
通过自连接实现语义去重
Query

aiTranslate

引入版本:v26.4.0 使用 LLM 提供商将给定文本翻译成指定的目标语言。 还可以通过参数映射中的 instructions 键传入额外的风格或语言变体说明 (例如:'保留技术术语不翻译') 。 凭据 (一个命名集合,用于指定提供商、模型、端点,以及可选的 API 密钥) 取自可选参数映射中的 credentials 键;如果该映射中未提供此项, 则取自 ai_function_text_default_credentials 设置。 语法
别名: AITranslate 参数
  • text — 要翻译的文本。String
  • target_language — 目标语言名称或 BCP-47 代码 (例如 'French''es-MX') 。String
  • params — 可选的常量 Map(String, String) 参数映射。此函数特有的键包括:temperature (控制随机性的采样温度;默认值为 0.3) 、max_tokens (每次调用可生成的最大输出标记数;默认值为 1024) 、instructions (给翻译器的附加风格或方言说明) 。通用参数 credentialsmodel 同样适用 (参见 AI 函数) 。Map(String, String)
返回值 翻译后的文本;如果请求失败且 ai_function_throw_on_error 被禁用,则返回列类型的默认值 (空字符串) 。String 示例 翻译成法语
Query
Response
根据风格说明翻译成日语
Query
最后修改于 2026年8月14日