ByteHouse AISQL 将大模型、Embedding、多模态处理能力封装为 SQL 语句和函数，使用户可以在数仓查询流程中完成文本摘要、文本生成、分类、情感分析、向量化、相似度判断、图片向量化等任务。本文重点说明模型配置、默认模型设置、函数语法、参数含义、返回值和使用注意事项。
本文适用于已经具备 ByteHouse 查询权限，并需要通过 SQL 调用 ARK 模型或系统内置 AI Function 的用户。模型可用性、Endpoint、API Key、默认 token 限制等以当前 ByteHouse 环境和模型服务配置为准。

• AISQL 通用函数仅在 2.3.4 及以上引擎版本 支持，低于该版本无法使用相关函数。
• system.ai_models 系统元表查询仅在 2.3.5 及以上引擎版本 支持，2.3.4 版本暂不提供该能力。

创建模型 #

通过 CREATE MODEL 语句可以在 ByteHouse 中注册 AI 模型。模型类型包括 Embedding、LLM_Chat 等。对于 Embedding 模型，需要关注向量维度；对于推理模型，需要关注 thinking 与 reasoning_effort 的组合约束。

CREATE MODEL text_embedding_model 
TYPE Embedding
SETTINGS
    api_type = 'ARK',
    base_url = 'https://ark.cn-beijing.volces.com/api/v3/embeddings',
    api_key = '<api_key>',
    endpoint = '<endpoint>',
    embedding_length = 2048;

如果模型为推理模型，可配置 is_reasoning、thinking 与 reasoning_effort。当 thinking = 'disabled' 时，reasoning_effort 必须设置为 minimal。

CREATE MODEL chat_reasoning_model 
TYPE LLM_Chat
SETTINGS
    api_type = 'ARK',
    base_url = 'https://ark.cn-beijing.volces.com/api/v3/chat/completions',
    api_key = '<api_key>',
    endpoint = '<endpoint>',
    is_reasoning = 1,
    thinking = 'disabled',
    reasoning_effort = 'minimal';

删除模型 #

使用 DROP MODEL 删除模型。部分版本执行时可能抛出 exception，但 drop 操作本身仍会正常执行；如果遇到该现象，建议先通过 system.ai_models 确认模型是否已经被删除。

DROP MODEL model_name; 

查询模型列表 #

模型注册后可通过系统表查询。返回字段通常包括模型名称、模型类型和模型配置。密钥类字段会以隐藏或加密形式展示。

SELECT * FROM system.ai_models; 

设置默认模型 #

默认模型用于省略函数入参中的 model 参数时自动选型。文本 Embedding、图片 Embedding 与对话模型分别设置，建议在任务执行前显式设置，避免使用到非预期模型。

SET default_embedding_img_model = 'Doubao-embedding-vision'; 
SET default_embedding_text_model = 'Doubao-embedding-text';
SET default_llm_chat_model = 'Doubao-Seed-1_6';

AI Functions 通常支持可选 model 参数。当 model 被省略时，函数会使用对应的默认模型。由于返回结果由大模型生成，文本类结果并不保证每次完全一致；当输入参数中存在 NULL 时，多数函数会返回 NULL。文本生成类函数的最大输出 token 默认值为 100，可通过 llm_max_tokens 参数调整。

AI_SUMMARIZE #

用于提炼输入文本的核心信息，并生成简明摘要。

语法 #

SELECT AI_SUMMARIZE([<model>], <text>)

参数说明 #

返回值 #

返回输入文本的摘要内容。

• 当任一输入参数为 NULL 时，返回 NULL。
• 摘要由大模型生成，返回内容不固定。
• 最大输出 token 默认为 100，可通过 llm_max_tokens 参数调整。

示例 #

SELECT AI_SUMMARIZE('ByteHouse是火山引擎数智平台VeDI旗下的一款云原生数仓产品，以 ClickHouse 技术路线为基础，为用户提供极速分析体验，能够支撑实时数据分析和海量数据离线分析，具备便捷的弹性扩缩容能力，极致分析性能和丰富的企业级特性，为海量数据规模下的聚合性分析提供支撑。');
-- 返回结果
AI_SUMMARIZE
---
火山引擎 VeDI 旗下云原生数仓 ByteHouse，基于 ClickHouse 技术，提供极速分析体验，支撑实时与海量离线数据分析，具备便捷弹性扩缩容、极致性能及丰富企业级特性，为海量数据聚合分析提供支撑。

--建表
CREATE TABLE t1
(
    `a` String
)
ENGINE = CnchMergeTree
ORDER BY tuple();

insert into t1 values('ByteHouse是火山引擎数智平台VeDI旗下的一款云原生数仓产品，以 ClickHouse 技术路线为基础，为用户提供极速分析体验，能够支撑实时数据分析和海量数据离线分析，具备便捷的弹性扩缩容能力，极致分析性能和丰富的企业级特性，为海量数据规模下的聚合性分析提供支撑。'),('ByteHouse 是新一代云原生数仓，兼具极速分析、灵活扩展与企业级可靠性。无论是广告投放监测、实时指标看板，还是离线数仓建模，ByteHouse 都能在秒级响应中释放数据价值，让企业决策真正做到“数据驱动、即时洞察”。');

select ai_summarize(a) from t1;
-- 返回结果
┌─ai_summarize(a)───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ ByteHouse是火山引擎数智平台VeDI旗下基于ClickHouse的云原生数仓产品，提供极速分析体验，支撑实时及海量数据离线分析，具备便捷弹性扩缩容、极致分析性能和丰富企业级特性，为海量数据聚合性分析提供支撑。 │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
┌─ai_summarize(a)────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ ByteHouse 是新一代云原生数仓，兼具极速分析、灵活扩展与企业级可靠性，适用于广告投放监测、实时指标看板、离线数仓建模等场景，能以秒级响应释放数据价值，助力企业实现“数据驱动、即时洞察”决策。 │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

2 rows in set. Elapsed: 8.045 sec.

AI_CHUNK #

对长文本进行分段（切片）

语法 #

SELECT AI_CHUNK(<text>, [<chunk_size>, <chunk_overlap>, <separators>])

参数说明 #

返回值 #

返回Array(String)类型，表示分割好的Chunks列表。若参数值为 NULL 时，则返回 NULL。

示例 #

SELECT AI_CHUNK('ByteHouse是火山引擎数智平台VeDI旗下的一款云原生数仓产品，以 ClickHouse 技术路线为基础，为用户提供极速分析体验，能够支撑实时数据分析和海量数据离线分析，具备便捷的弹性扩缩容能力，极致分析性能和丰富的企业级特性，为海量数据规模下的聚合性分析提供支撑。',40,10);
-- 返回结果
AI_CHUNK
---
["ByteHouse 是火山引擎数智平台 VeDI 旗下的一款云原生数仓产品，以 ClickHouse 技术路线为基础，", "ClickHouse 技术路线为基础，为用户提供极速分析体验，能够支撑实时数据分析和海量数据离线分析，", "分析和海量数据离线分析，具备便捷的弹性扩缩容能力，极致分析性能和丰富的企业级特性，", "性能和丰富的企业级特性，为海量数据规模下的聚合性分析提供支撑。"]

AI_GENERATE #

基于输入的提示文本生成相应内容

语法 #

AI_GENERATE([<model>], <prompt>) -- 处理文本理解
AI_GENERATE([<model>], <prompt>，<img_url>) -- 图片理解

参数说明 #

返回值 #

返回基于提示生成的文本内容。当输入有值为 NULL 时返回 NULL。
结果为大模型生成，所以返回内容并不固定。
返回结果最大 token 默认为 100， 可通过 llm_max_tokens 参数来设定

示例 #

SELECT AI_GENERATE('Describe Bytehouse in a few words') AS Result

Query id: 0765ed20-f8ca-43d7-b0f0-bb31d7aaa749

┌─Result─────────────────────────────────────────────────────────────────────────────────┐
│ Cloud-native real-time analytics data warehouse with high performance and scalability. │
└────────────────────────────────────────────────────────────────────────────────────────┘

AI_CLASSIFY #

用于将文本分类到指定的标签集合中

语法 #

AI_CLASSIFY([<model>], <text>, <labels>)

参数说明 #

返回值 #

返回文本最匹配的单个标签字符串。当输入有值为 NULL 时返回 NULL。
结果为大模型生成，所以返回内容并不固定。

示例 #

SELECT AI_CLASSIFY('Bytehouse is a databases system.', ['useage', 'introduce']) AS Result;

SELECT AI_CLASSIFY('Bytehouse is a databases system.', ['useage', 'introduce']) AS Result

Query id: 5c4e6a5a-36c1-48b8-987f-d4a747192a8b

┌─Result────┐
│ introduce │
└───────────┘

AI_SENTIMENT #

用于分析文本的情感倾向

语法 #

AI_SENTIMENT([<model>], <text>)

参数 #

返回值 #

返回情感分析结果，可能的值包括：

• positive（积极）
• negative（消极）
• neutral（中性）
• mixed（混合）

当输入有值为 NULL 时返回 NULL
结果为大模型生成，所以返回内容并不固定

示例 #

set default_llm_chat_model ='xxx';

SELECT AI_SENTIMENT('I hate sunny days.') AS Result

Query id: 6198e451-3d79-48f9-a690-f6d0b0b9863c

┌─Result───┐
│ negative │
└──────────┘

AI_EMBED_TEXT #

对输入文本进行向量化

语法 #

AI_EMBED_TEXT([<model>], <content>)

参数说明 #

返回值 #

返回文本生成的向量，默认 2048 维，可以通过 embedding_length 设置进行裁剪

AI_TRANSLATE #

用于将文本翻译为特定语言。

语法 #

AI_TRANSLATE([<model>], <text>, <target_language>)

参数说明 #

返回值 #

返回翻译后的文本字符串。当输入有值为 NULL 时返回 NULL。结果为大模型生成，所以返回内容并不固定

AI_SIMILARITY #

判断两个文本之间的语义相似性。

语法 #

AI_SIMILARITY([<model>], <text_1>, <text_2>)

参数说明 #

返回值 #

返回一个 0 - 10 之间的浮点数。0 表示无相似性，10 表示强相似性。当输入有值为 NULL 时返回 NULL。结果为大模型生成，所以返回内容并不固定。

AI_RANK #

对给定的文档进行相关性打分。

语法 #

AI_RANK(<model>, <source_sentence>, <sentence_to_compare>);

参数说明 #

返回值 #

返回一个 0 - 1 之间的浮点数。0 表示无相似性，1 表示强相似性。当输入有值为 NULL 时返回 NULL。结果为大模型生成，所以返回内容并不固定。Embedding 与相关性函数

AI_EMBED_IMG_URL #

对输入图片 url 进行向量化

语法 #

AI_EMBED_IMG_URL([<model>], <image_url>)

参数说明 #

返回值 #

返回生成的向量，默认 2048 维，可以通过 embedding_length 设置进行裁剪

AI_EMBED_IMG_URL_WITH_TEXT #

对输入图片 url 结合给出的文本进行向量化

语法 #

AI_EMBED_IMG_URL_WITH_TEXT([<model>], <image_url>, <text>)

参数说明 #

返回值 #

返回生成的向量，默认 2048 维，可以通过 embedding_length 设置进行裁剪

AI_EMBED_IMG_BASE64 #

对输入图片内容（base64 表示）进行向量化

语法 #

AI_EMBED_IMG_BASE64([<model>], <image_content>, <format>，[<text>])

参数说明 #

返回值 #

返回生成的向量，默认 2048 维，可以通过 embedding_length 设置进行裁剪

AI_EMBED_IMG_BASE64_WITH_TEXT #

对输入图片内容结合给出的文本进行向量化

语法 #

AI_EMBED_IMG_BASE64_WITH_TEXT([<model>], <image_content>, <format>, <text>)

参数说明 #

返回值 #

返回生成的向量，默认 2048 维，可以通过 embedding_length 设置进行裁剪

• 先设置默认模型，再调用函数。 对于批量 SQL 任务，建议在查询开始前设置 default_llm_chat_model、default_embedding_text_model 和 default_embedding_img_model，降低函数入参重复度，也避免使用到错误模型。
• 把长文本先切片，再做生成或向量化。 对超过模型上下文或语义过长的文本，可先使用 AI_CHUNK 分段，再分别做摘要、Embedding 或相关性计算。中文文本建议显式传入中文分隔符。
• 将生成式结果视为非确定输出。 摘要、生成、分类、翻译和情感分析由大模型返回，结果可能随模型版本、prompt 和参数变化而不同；对稳定性要求高的任务，应增加抽样校验或业务规则兜底。
• 妥善处理密钥与 Endpoint。 文档示例中的 api_key 和 endpoint 仅代表配置形态，生产环境应使用当前租户授权的模型服务配置，不要在公共文档、SQL 日志或截图中暴露完整密钥。

下面示例展示从配置默认模型到执行摘要、切片和图片向量化的基本链路。实际模型名称需以 system.ai_models 查询结果为准。

-- 1. 查看可用模型 
SELECT * FROM system.ai_models;

-- 2. 设置默认模型
SET default_llm_chat_model = 'Doubao-Seed-1_6';
SET default_embedding_text_model = 'Doubao-embedding-text';
SET default_embedding_img_model = 'Doubao-embedding-vision';

-- 3. 文本摘要
SELECT AI_SUMMARIZE('ByteHouse 是新一代云原生数仓，兼具极速分析、灵活扩展与企业级可靠性。') AS summary;

-- 4. 长文本切片
SELECT AI_CHUNK('需要处理的长文本内容', 300, 50, ['\n\n', '\n', '。', '！', '？', '；', '，', ' ']) AS chunks;

-- 5. 图片向量化
SELECT AI_EMBED_IMG_URL('https://example.com/image.jpeg') AS image_embedding;