AI_EMBEDDING

概述

将文本转换为嵌入向量（Embedding Vector）。嵌入向量是对文本语义特征的抽象数值表示，可用于衡量文本之间的语义相似程度，适用于语义搜索、文本相似度计算、聚类分析、推荐系统等下游任务。

语法

AI_EMBEDDING( <model>, <input> [, <model_parameters>] )

参数说明

必需参数

model

model

指定用于生成嵌入向量的模型。支持两种引用方式：

方式一：通过 API Gateway 端点调用

'endpoint:<端点名称>'

方式二：通过 API Connection 连接对象调用

需先通过

CREATE API CONNECTION

CREATE API CONNECTION

创建连接对象，再以

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

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

的格式引用：

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

请确保所指定的模型为嵌入模型（Embedding Model），而非对话补全模型（Chat Completion Model）。嵌入模型专门用于将文本映射为固定维度的数值向量，常见的嵌入模型包括 OpenAI 的

text-embedding-3-small

text-embedding-3-small

、

text-embedding-3-large

text-embedding-3-large

，阿里云百炼的

text-embedding-v4

text-embedding-v4

等。

input

input

用于生成嵌入向量的输入文本。可以是单个词语、一个句子、一段文字，也可以是来自数据表中某个字段的值。

可选参数

model_parameters

model_parameters

以 JSON 对象形式传入的模型超参数。不同模型支持的参数可能有所不同，

text-embedding-v4

text-embedding-v4

支持以下参数：

参数类型默认值说明

参数	类型	默认值	说明
`input` input	STRING	`'document'` 'document'	指定输入内容的用途类型。取值为 `'document'` 'document' （文档内容）或 `'query'` 'query' （查询文本）。在检索场景中，文档入库时使用 `'document'` 'document' ，用户查询时使用 `'query'` 'query' ，模型会针对不同用途对向量做优化，可提升检索精度。对于聚类、分类等对称任务，使用默认值 `'document'` 'document' 。
`dimensions` dimensions	STRING	`'1024'` '1024'	指定输出向量的维度。 `text-embedding-v4` text-embedding-v4 支持 8 种维度： `'64'` '64' 、 `'128'` '128' 、 `'256'` '256' 、 `'512'` '512' 、 `'768'` '768' 、 `'1024'` '1024' 、 `'1536'` '1536' 、 `'2048'` '2048' 。较高的维度通常能保留更丰富的语义信息，但会占用更多存储空间和计算资源。

input

input

STRING

'document'

'document'

指定输入内容的用途类型。取值为

'document'

'document'

（文档内容）或

'query'

'query'

（查询文本）。在检索场景中，文档入库时使用

'document'

'document'

，用户查询时使用

'query'

'query'

，模型会针对不同用途对向量做优化，可提升检索精度。对于聚类、分类等对称任务，使用默认值

'document'

'document'

。

dimensions

dimensions

STRING

'1024'

'1024'

指定输出向量的维度。

text-embedding-v4

text-embedding-v4

支持 8 种维度：

'64'

'64'

、

'128'

'128'

、

'256'

'256'

、

'512'

'512'

、

'768'

'768'

、

'1024'

'1024'

、

'1536'

'1536'

、

'2048'

'2048'

。较高的维度通常能保留更丰富的语义信息，但会占用更多存储空间和计算资源。

返回值

由输入文本派生的嵌入向量，类型为

ARRAY<FLOAT>

ARRAY<FLOAT>

。

使用
```
SIZE()
```
SIZE()
函数获取向量维度
使用
```
COSINE_SIMILARITY()
```
COSINE_SIMILARITY()
函数计算两个向量的余弦相似度

使用说明

结果具有确定性：嵌入模型是确定性的，相同的输入文本始终返回相同的向量。
NULL 输入返回 NULL：
```
input
```
input
为
```
NULL
```
NULL
时，函数返回
```
NULL
```
NULL
，不报错。
检索场景区分输入类型：文档入库时使用
```
"input": "document"
```
"input": "document"
，用户查询时使用
```
"input": "query"
```
"input": "query"
，可提升检索精度。
批量处理过滤 NULL：在批量处理场景中，建议提前过滤 NULL 行，避免 NULL 与非 NULL 数据混合导致查询失败。

限制说明

空字符串不支持：
```
input
```
input
为空字符串
```
''
```
''
时，函数报错
```
input.texts should not be null
```
input.texts should not be null
，而非返回 NULL。调用前请过滤空值：
```
WHERE input IS NOT NULL AND LENGTH(input) > 0
```
WHERE input IS NOT NULL AND LENGTH(input) > 0
。
输入长度上限为 8,192 tokens：超出限制时函数报错，不会自动截断。中文文本约对应 26,000 字以内。
每次最多处理 10 条：批量调用时，单次请求最多处理 10 条输入。

模型规格（text-embedding-v4）

属性	规格
模型系列	Qwen3-Embedding
支持维度	64 / 128 / 256 / 512 / 768 / 1024（默认） / 1536 / 2048
最大输入长度	8,192 tokens
支持语言	中文、英文、日文、韩文、德文、法文、西班牙文、葡萄牙文、俄文、印尼文及 100+ 种语言

示例

基础用法

-- 通过 API Connection 调用 SELECT AI_EMBEDDING( 'cz_bailian:text-embedding-v4', '中国的首都是北京' ) AS embedding; -- 通过 API Gateway 端点调用 SELECT AI_EMBEDDING( 'endpoint:text-embedding-v4', '中国的首都是北京' ) AS embedding;

获取向量维度

SELECT SIZE(AI_EMBEDDING('cz_bailian:text-embedding-v4', '你好')) AS dim; -- 返回：1024

指定输入类型（检索场景）

-- 文档入库：使用 input=document SELECT AI_EMBEDDING( 'cz_bailian:text-embedding-v4', '云器Lakehouse是全托管的湖仓一体架构平台', JSON '{"input": "document"}' ) AS embedding; -- 用户查询：使用 input=query SELECT AI_EMBEDDING( 'cz_bailian:text-embedding-v4', '什么是湖仓一体？', JSON '{"input": "query"}' ) AS embedding;

指定输出维度

-- 输出 512 维向量（节省存储） SELECT AI_EMBEDDING( 'cz_bailian:text-embedding-v4', '云器Lakehouse是全托管的湖仓一体架构平台', JSON '{"dimensions": "512"}' ) AS embedding; -- 输出 2048 维向量（更丰富的语义信息） SELECT AI_EMBEDDING( 'cz_bailian:text-embedding-v4', '云器Lakehouse是全托管的湖仓一体架构平台', JSON '{"dimensions": "2048"}' ) AS embedding;

组合参数

SELECT AI_EMBEDDING( 'cz_bailian:text-embedding-v4', '什么是湖仓一体？', JSON '{"input": "query", "dimensions": "512"}' ) AS embedding;

计算文本语义相似度

SELECT COSINE_SIMILARITY( AI_EMBEDDING('cz_bailian:text-embedding-v4', '人工智能'), AI_EMBEDDING('cz_bailian:text-embedding-v4', '机器学习') ) AS similarity;

批量向量化表数据

SELECT id, content, AI_EMBEDDING('cz_bailian:text-embedding-v4', content) AS embedding FROM documents WHERE content IS NOT NULL AND LENGTH(content) > 0;

语义搜索

WITH query_vec AS ( SELECT AI_EMBEDDING( 'cz_bailian:text-embedding-v4', '实时数据处理', JSON '{"input": "query"}' ) AS q ) SELECT d.id, d.content, COSINE_SIMILARITY( AI_EMBEDDING('cz_bailian:text-embedding-v4', d.content, JSON '{"input": "document"}'), q.q ) AS similarity FROM documents d, query_vec q ORDER BY similarity DESC LIMIT 10;

联系我们