AI_SIMILARITY

概述

AI_SIMILARITY

与

AI_COMPLETE

AI_SIMILARITY

云器将 AI 计算下沉至存储层与执行引擎，数据在平台内部即可完成智能处理，无需流转至外部环境，在保障数据安全的同时大幅降低任务延迟。

语法

AI_SIMILARITY

-- 使用工作区默认模型（推荐） AI_SIMILARITY(<text1>, <text2> [, json '{}']) -- 或手动指定连接 AI_SIMILARITY('<connection>:<model>', <text1>, <text2> [, json '{}'])

参数说明

model（可选）

指定要调用的 Embedding 模型。从 2026 年 9 月起，该参数可以省略——模型通过工作区默认模型自动路由，无需在每次调用时显式传入。

省略 model 参数时调用方式最简洁：

SELECT AI_SIMILARITY('白色上衣', '白色衬衫');

工作区默认模型可通过以下方式配置：

方式一：创建新工作区时开启开关（推荐）

2026 年 9 月起新建的工作区，在创建时打开 "启用 AI Function" 开关，系统将自动配置默认模型，调用时无需传入 model 参数。对于此之前创建的工作区，需通过下方方式手动配置。

方式二：工作区级别 ALTER WORKSPACE 配置

通过

ALTER WORKSPACE

ALTER WORKSPACE <workspace_name> SET PROPERTIES ( 'cz.sql.ai.similarity.default.model' = '<connection>:<model>' ); SELECT AI_SIMILARITY('白色上衣', '白色衬衫');

方式三：会话级 SET 覆盖

在当前会话中临时指定默认模型，优先级高于工作区属性，仅当前 session 生效：

SET cz.sql.ai.similarity.default.model=conn_bailian:text-embedding-v4; SELECT AI_SIMILARITY('白色上衣', '白色衬衫');

方式四：API Connection 连接对象

通过

CREATE API CONNECTION

CREATE API CONNECTION conn_bailian TYPE ai_function PROVIDER = 'bailian' BASE_URL = 'https://dashscope.aliyuncs.com/api/v1' API_KEY = 'sk-xxxxxxxxxxxxxxxxxxxxxxxx'; SELECT AI_SIMILARITY('conn_bailian:text-embedding-v4', '白色上衣', '白色衬衫');

CREATE API CONNECTION

TYPE

ai_function

PROVIDER

'bailian'

'openai'

'anthropic'

BASE_URL

API_KEY

text1（必需）

第一段输入文本，类型为 STRING。支持中文、英文等多语言。

text2（必需）

第二段输入文本，类型为 STRING。支持中文、英文等多语言。

options（可选）

JSON 字面量，用于控制输出格式、模型参数、超时和并发度：

JSON '{"output.behavior":"formatted_json","model.params": {"dimensions": 2048}, "response.timeout": "300", "task.concurrency": "12"}'

输出格式控制

output.behavior

formatted_json

formatted_json

raw_string

fail_on_error

三种输出模式对比：

formatted_json

{"value":0.8097}

{"value":0,"error_message":"..."}

raw_string

fail_on_error

output.behavior

_

.

-

formatted_json

formatted.json

json

raw_string

raw.string

raw

fail_on_error

fail.on.error

fail-on-error

fail

模型参数

model.params.dimensions

运行时参数

embeddings.batch_size

task.concurrency

"1"

response.timeout

"300"

返回值

FLOAT 类型。基于余弦相似度计算，理论范围为 [-1, 1]，实际使用中通常落在 [0, 1] 区间。

错误行为

默认情况下，若函数无法处理输入，返回

0

''

使用说明

• 结果具有确定性：相同输入永远返回相同结果，适合用于需要稳定排序的业务场景（如搜索结果排序）。
• 函数具有对称性：

  AI_SIMILARITY(model, a, b)

  AI_SIMILARITY(model, a, b)
  与

  AI_SIMILARITY(model, b, a)

  AI_SIMILARITY(model, b, a)
  结果完全相同。
• 支持多语言及跨语言：支持中文、英文等多语言文本，也支持跨语言相似度计算（如中文与英文语义对比）。
• 仅支持文本输入：

  AI_SIMILARITY

  AI_SIMILARITY
  不支持图像输入，图像处理请使用

  AI_EXTRACT

  AI_EXTRACT
  。
• 合理设置阈值：根据业务场景调整过滤阈值，精确匹配建议 > 0.9，高度相关建议 > 0.7，有一定关联建议 > 0.5。
• 注意配额消耗：每次调用消耗 text1 + text2 的 token 数。批量 CROSS JOIN 场景 token 消耗 = 行数² × 平均 token 数，请提前评估。
• 先过滤再计算：对大表使用时，建议先用

  WHERE

  WHERE
  缩小范围，再计算相似度，避免不必要的 API 调用。

示例

使用默认模型

省略

model

-- 使用工作区默认模型计算相似度 SELECT AI_SIMILARITY('你好', '世界');

基础用法

-- 语义相近的文本 SELECT AI_SIMILARITY('conn_bailian:text-embedding-v4', '白色上衣', '白色衬衫'); -- 返回：约 0.8097 -- 语义无关的文本 SELECT AI_SIMILARITY('conn_bailian:text-embedding-v4', '白色上衣', '蓝牙耳机'); -- 返回：约 0.2640 -- 完全相同的文本 SELECT AI_SIMILARITY('conn_bailian:text-embedding-v4', '白色上衣', '白色上衣'); -- 返回：1.0

跨语言相似度

-- 中英文语义匹配 SELECT AI_SIMILARITY('conn_bailian:text-embedding-v4', '我喜欢这道菜', 'I like this dish'); -- 返回：约 0.7513

语义搜索（按相似度排序）

SELECT product_name, AI_SIMILARITY('conn_bailian:text-embedding-v4', product_name, '白色上衣') AS score FROM products ORDER BY score DESC LIMIT 5;

相似度阈值过滤

-- 只返回与查询词高度相关的商品 SELECT product_name FROM products WHERE AI_SIMILARITY('conn_bailian:text-embedding-v4', product_name, '白色上衣') > 0.7;

文本去重（找近似重复）

SELECT a.title, b.title, AI_SIMILARITY('conn_bailian:text-embedding-v4', a.title, b.title) AS sim FROM articles a JOIN articles b ON a.id < b.id WHERE AI_SIMILARITY('conn_bailian:text-embedding-v4', a.title, b.title) > 0.95;

使用 CTE 避免重复调用

WITH scored AS ( SELECT product_id, product_name, AI_SIMILARITY('conn_bailian:text-embedding-v4', product_name, '运动鞋') AS score FROM products ) SELECT * FROM scored WHERE score > 0.6 ORDER BY score DESC;

使用 output.behavior 控制输出格式

-- formatted_json（默认） SELECT AI_SIMILARITY('conn_bailian:text-embedding-v4', '白色上衣', '白色衬衫'); -- 返回：{"value":0.8097} -- raw_string SELECT AI_SIMILARITY( 'conn_bailian:text-embedding-v4', '白色上衣', '白色衬衫', json '{"output.behavior":"raw_string"}' ); -- 返回：0.8097

限制说明

• model 参数可选：省略 model 参数时将使用工作区默认模型；若未配置默认模型且未指定 model，会报错

  AI function must have at least two arguments

  AI function must have at least two arguments
  。
• model 格式错误会报错：model 必须使用

  '<连接名称>:<模型名称>'

  '<连接名称>:<模型名称>'
  格式，格式不符时报错

  Invalid model coordinates

  Invalid model coordinates
  。
• 仅支持文本输入：不支持图像输入，图像处理请使用

  AI_EXTRACT

  AI_EXTRACT
  。
• 输入长度受模型限制：输入文本长度受底层 Embedding 模型 context window 限制。
• 配额限制：受 AI Gateway 租户月度 token 配额限制，配额超限时整个查询失败，错误信息为

  Tenant quota exceeded: Monthly quota limit...

  Tenant quota exceeded: Monthly quota limit...
  。
• ** API Connection 不存在时报错**：错误信息为

  模型未指定且租户未配置默认模型

  模型未指定且租户未配置默认模型
  ，请检查 API Connection 名称是否正确。