AI_SIMILARITY

概述

AI_SIMILARITY

AI_SIMILARITY

是云器 Lakehouse 提供的语义相似度计算函数，基于 Embedding 模型将两段文本转换为向量，并计算其余弦相似度，返回一个 FLOAT 值。可用于语义搜索、商品推荐、文本去重、内容匹配等场景。

与

AI_COMPLETE

AI_COMPLETE

等 LLM 函数不同，

AI_SIMILARITY

AI_SIMILARITY

基于 Embedding 模型，结果具有确定性——相同输入永远返回相同结果，且速度更快。

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

语法

AI_SIMILARITY( <model>, <text1>, <text2> [, <options>] )

参数说明

必需参数

model

model

指定用于计算 Embedding 的模型，支持两种来源：

来源一：API Gateway Endpoint（推荐）

平台管理员在 API Gateway 中预先配置模型服务，普通用户通过

endpoint:

endpoint:

前缀引用，无需关心底层连接细节。

'endpoint:<endpoint名称>' -- 示例 'endpoint:text-embedding-v4'

来源二：API Connection 连接对象

用户通过

CREATE API CONNECTION

CREATE API CONNECTION

自行创建连接对象，适用于需要自定义服务地址、认证密钥或对接私有化部署模型的场景。

-- 创建连接对象 CREATE API CONNECTION cz_bailian TYPE ai_function PROVIDER = 'bailian' BASE_URL = 'https://dashscope.aliyuncs.com/api/v1' API_KEY = 'sk-xxxxxxxxxxxxxxxxxxxxxxxx'; -- 引用时使用 <连接名称>:<模型名称> 格式 SELECT AI_SIMILARITY('cz_bailian:text-embedding-v4', '白色上衣', '白色衬衫');

CREATE API CONNECTION

CREATE API CONNECTION

各字段说明：

字段	说明
`TYPE` TYPE	固定为 `ai_function` ai_function
`PROVIDER` PROVIDER	模型供应商标识，如 `'bailian'` 'bailian' 、 `'openai'` 'openai' 、 `'anthropic'` 'anthropic' 等
`BASE_URL` BASE_URL	模型服务的 API 基础地址
`API_KEY` API_KEY	调用服务所需的认证密钥

text1

text1

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

text2

text2

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

可选参数

options

options

JSON 字面量，用于控制模型参数、超时和并发度。

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

参数	说明
`model.params.dimensions` model.params.dimensions	Embedding 向量维度（默认 1024，可设为 2048 等，取决于模型支持）
`response.timeout` response.timeout	HTTP 请求超时时间（秒）
`task.concurrency` task.concurrency	批量处理时的并发度

返回值

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

值域	含义
1.0	两段文本完全相同（或语义完全一致）
> 0.7	高度相似
0.3 ~ 0.7	有一定关联
< 0.3	基本无关
0	任一输入为 NULL，或一个为空字符串而另一个非空

错误行为

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

，不报错。具体边界行为见下表：

输入情况	返回值
任一参数为 NULL	0
两个都是空字符串 `''` ''	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 调用。

示例

基础用法

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

跨语言相似度

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

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

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

相似度阈值过滤

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

文本去重（找近似重复）

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

使用 CTE 避免重复调用

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

使用 API Connection 来源

SELECT AI_SIMILARITY('cz_bailian:text-embedding-v4', '白色上衣', '白色衬衫'); -- 返回：约 0.8097（与 endpoint 来源结果一致）

限制说明

model 参数必填：省略 model 参数会报错
```
AI function must have at least two arguments
```
AI function must have at least two arguments
。
model 格式错误会报错：model 必须使用
```
'endpoint:<名称>'
```
'endpoint:<名称>'
或
```
'<连接名称>:<模型名称>'
```
'<连接名称>:<模型名称>'
格式，格式不符时报错
```
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...
。
Endpoint 不存在时报错：错误信息为
```
模型未指定且租户未配置默认模型
```
模型未指定且租户未配置默认模型
或
```
No available endpoints found
```
No available endpoints found
，请检查 endpoint 名称是否正确。

联系我们