AI_EMBEDDING

概述

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

语法

AI_EMBEDDING
AI_EMBEDDING
支持两种调用形式：

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

参数说明

model（可选）

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

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

SELECT AI_EMBEDDING('hello', JSON '{"input":"text","dimensions":"64"}');

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

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

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

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

通过 

ALTER WORKSPACE
ALTER WORKSPACE
设置工作区默认模型，对所有使用该工作区的 session 生效：

ALTER WORKSPACE <workspace_name> SET PROPERTIES ( 'cz.sql.ai.embedding.default.model' = '<connection>:<model>' );

方式三：会话级 SET 覆盖

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

SET cz.sql.ai.embedding.default.model=conn:model; SELECT AI_EMBEDDING('文本', JSON '{"input":"text","dimensions":"64"}');

方式四：API Connection 连接对象

通过 

CREATE 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_EMBEDDING('conn_bailian:text-embedding-v4', 'hello', JSON '{"input":"text","dimensions":"64"}');

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
调用服务所需的认证密钥

input（必需）

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

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'
。较高的维度通常能保留更丰富的语义信息，但会占用更多存储空间和计算资源。
embeddings.batch_size
embeddings.batch_size
INTEGER
10
10
单次请求处理的最大文本条数。
embeddings.batch_max_tokens
embeddings.batch_max_tokens
INTEGER
8000
8000
单次请求的最大 token 数限制。设为 
0
0
时仅按条数（
batch_size
batch_size
）控制。

返回值

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

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"
    ，可提升检索精度。
  • input
    input
    和 
    dimensions
    dimensions
    参数必填    ：
    model_parameters
    model_parameters
    中的 
    input
    input
    和 
    dimensions
    dimensions
    为必填项。若未指定这两个参数，函数将返回 
    NULL
    NULL
    。
  • 批量处理过滤 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 条输入（可通过 
    embeddings.batch_size
    embeddings.batch_size
    参数调整）。

模型规格（text-embedding-v4）

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

示例

基础用法（省略 model 参数）

-- 使用工作区默认模型 SELECT AI_EMBEDDING('Hello', JSON '{"input":"text","dimensions":"64"}') AS embedding;

指定连接和模型

SELECT AI_EMBEDDING( 'conn_bailian:text-embedding-v4', '中国的首都是北京' ) AS embedding;

获取向量维度

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

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

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

指定输出维度

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

组合参数

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

计算文本语义相似度

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

批量向量化表数据

SELECT id, content, AI_EMBEDDING('conn_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( 'conn_bailian:text-embedding-v4', '实时数据处理', JSON '{"input": "query"}' ) AS q ) SELECT d.id, d.content, COSINE_SIMILARITY( AI_EMBEDDING('conn_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;

AI_MASK
AI_SIMILARITY
Yunqi © 2024 Yunqi, Inc. All Rights Reserved.
联系我们
预约咨询
微信咨询
电话咨询
邮件咨询