AI_CONTEXT_LENGTH

功能

在不发起任何 API 调用的情况下，估算调用指定 AI 函数时输入内容所占用的 token 数。

计算完全在本地完成，适合在正式调用前做成本预估、过滤超长文本或监控数据集规模，不会产生 API 费用，也不会触发限流。

语法

AI_CONTEXT_LENGTH(function_name, args...)

参数	类型	说明
`function_name` function_name	STRING 常量	目标 AI 函数名，大小写不敏感，如 `'AI_COMPLETE'` 'AI_COMPLETE'
`args...` args...	同目标函数	与目标函数参数对应，去掉 model 和 options，其余保持一致。AI Functions 现已支持省略 model 参数（由工作区默认模型自动填充），因此 AI_CONTEXT_LENGTH 始终不传 model 的规则与新的可选模型语法完全一致

返回值：

INT

INT

，估算的 token 数；第一个内容参数为 NULL 时返回 NULL；空字符串返回 0。

各函数参数对照

目标函数调用	AI_CONTEXT_LENGTH 写法
`AI_COMPLETE(model, content)` AI_COMPLETE(model, content)	`AI_CONTEXT_LENGTH('AI_COMPLETE', content)` AI_CONTEXT_LENGTH('AI_COMPLETE', content)
`AI_EMBEDDING(model, text)` AI_EMBEDDING(model, text)	`AI_CONTEXT_LENGTH('AI_EMBEDDING', text)` AI_CONTEXT_LENGTH('AI_EMBEDDING', text)
`AI_EXTRACT(model, content, labels)` AI_EXTRACT(model, content, labels)	`AI_CONTEXT_LENGTH('AI_EXTRACT', content, labels)` AI_CONTEXT_LENGTH('AI_EXTRACT', content, labels)
`AI_CLASSIFY(model, content, labels)` AI_CLASSIFY(model, content, labels)	`AI_CONTEXT_LENGTH('AI_CLASSIFY', content, labels)` AI_CONTEXT_LENGTH('AI_CLASSIFY', content, labels)
`AI_SUMMARIZE(model, content, max_words)` AI_SUMMARIZE(model, content, max_words)	`AI_CONTEXT_LENGTH('AI_SUMMARIZE', content, max_words)` AI_CONTEXT_LENGTH('AI_SUMMARIZE', content, max_words)
`AI_SENTIMENT(model, content)` AI_SENTIMENT(model, content)	`AI_CONTEXT_LENGTH('AI_SENTIMENT', content)` AI_CONTEXT_LENGTH('AI_SENTIMENT', content)
`AI_TRANSLATE(model, content, to_lang)` AI_TRANSLATE(model, content, to_lang)	`AI_CONTEXT_LENGTH('AI_TRANSLATE', content, to_lang)` AI_CONTEXT_LENGTH('AI_TRANSLATE', content, to_lang)
`AI_FIX_GRAMMAR(model, content)` AI_FIX_GRAMMAR(model, content)	`AI_CONTEXT_LENGTH('AI_FIX_GRAMMAR', content)` AI_CONTEXT_LENGTH('AI_FIX_GRAMMAR', content)
`AI_MASK(model, content, labels)` AI_MASK(model, content, labels)	`AI_CONTEXT_LENGTH('AI_MASK', content, labels)` AI_CONTEXT_LENGTH('AI_MASK', content, labels)
`AI_SIMILARITY(model, text1, text2)` AI_SIMILARITY(model, text1, text2)	`AI_CONTEXT_LENGTH('AI_SIMILARITY', text1, text2)` AI_CONTEXT_LENGTH('AI_SIMILARITY', text1, text2)

不支持

AI_TRANSCRIBE

AI_TRANSCRIBE

：音频内容无法通过文本方式计算 token 数。传入该函数名会在运行时报错（CZLH-67000）。

使用示例

1. 估算单条文本的 token 数

SELECT AI_CONTEXT_LENGTH('AI_COMPLETE', '你好，请介绍一下向量数据库'); -- 返回: 7

2. 调用前过滤超长文本

避免因超出模型上下文限制而在运行时报错：

SELECT doc_id, AI_SUMMARIZE('conn_openai:gpt-4o-mini', content, 50) AS summary FROM documents WHERE AI_CONTEXT_LENGTH('AI_SUMMARIZE', content, 50) BETWEEN 10 AND 3000;

3. 统计数据集 token 分布，预估费用

SELECT COUNT(*) AS doc_count, AVG(AI_CONTEXT_LENGTH('AI_COMPLETE', content)) AS avg_tokens, MAX(AI_CONTEXT_LENGTH('AI_COMPLETE', content)) AS max_tokens, SUM(AI_CONTEXT_LENGTH('AI_COMPLETE', content)) AS total_tokens FROM documents;

4. 带 labels 的函数（labels 的 token 一并计入）

SELECT AI_CONTEXT_LENGTH( 'AI_EXTRACT', '张三，25岁，住在北京', ARRAY['name', 'age', 'city'] ); -- 返回: 135

5. 按 token 数路由到不同模型

短文本用小模型节省成本，长文本自动切换大模型：

SELECT doc_id, CASE WHEN AI_CONTEXT_LENGTH('AI_COMPLETE', content) <= 4000 THEN AI_COMPLETE('conn_openai:gpt-4o-mini', content) ELSE AI_COMPLETE('conn_openai:gpt-4o', content) END AS reply FROM documents;

6. 特殊输入行为

-- NULL 输入返回 NULL SELECT AI_CONTEXT_LENGTH('AI_COMPLETE', NULL); -- 返回: NULL -- 空字符串返回 0 SELECT AI_CONTEXT_LENGTH('AI_COMPLETE', ''); -- 返回: 0 -- 大小写不敏感，两者结果相同 SELECT AI_CONTEXT_LENGTH('ai_complete', '测试'), AI_CONTEXT_LENGTH('AI_COMPLETE', '测试'); -- 返回: 3, 3

错误情况

错误场景	错误阶段	错误码	说明
`function_name` function_name 为列名或变量	编译期	CZLH-42000	必须是字面量常量
传入不存在的函数名（如 `'AI_UNKNOWN'` 'AI_UNKNOWN' ）	编译期	CZLH-42000	仅支持上表中列出的函数
传入 `'AI_TRANSCRIBE'` 'AI_TRANSCRIBE'	运行时	CZLH-67000	音频 token 无法文本计数

注意事项

注意点	说明
`function_name` function_name 必须是常量	不能是列名或变量，必须在 SQL 中硬编码字符串
去掉 model 和 options	AI_CONTEXT_LENGTH 只估算内容参数的 token，始终不传 model 名和 options。这与 AI Functions 新的可选模型语法（工作区默认模型）完全一致
误差范围	使用内置本地 tokenizer 估算，与模型实际计费误差通常 < 5%
确定性函数	相同输入始终返回相同结果，可安全用于物化视图、缓存、分区裁剪等场景
零 API 开销	完全本地计算，不发请求，大表全量扫描也不会触发限流或产生费用
不支持 AI_TRANSCRIBE	传入该函数名会在运行时（非编译期）报错 CZLH-67000

验证示例

用例	SQL	实际结果
基础用法	`AI_CONTEXT_LENGTH('AI_COMPLETE', '你好，请介绍一下向量数据库')` AI_CONTEXT_LENGTH('AI_COMPLETE', '你好，请介绍一下向量数据库')	7
NULL 输入	`AI_CONTEXT_LENGTH('AI_COMPLETE', NULL)` AI_CONTEXT_LENGTH('AI_COMPLETE', NULL)	NULL
空字符串	`AI_CONTEXT_LENGTH('AI_COMPLETE', '')` AI_CONTEXT_LENGTH('AI_COMPLETE', '')	0
AI_EMBEDDING	`AI_CONTEXT_LENGTH('AI_EMBEDDING', 'hello world')` AI_CONTEXT_LENGTH('AI_EMBEDDING', 'hello world')	2
AI_EXTRACT + labels	`AI_CONTEXT_LENGTH('AI_EXTRACT', '张三，25岁，住在北京', ARRAY['name','age','city'])` AI_CONTEXT_LENGTH('AI_EXTRACT', '张三，25岁，住在北京', ARRAY['name','age','city'])	135
AI_CLASSIFY + labels	`AI_CONTEXT_LENGTH('AI_CLASSIFY', '这是一篇科技文章', ARRAY['科技','体育','娱乐'])` AI_CONTEXT_LENGTH('AI_CLASSIFY', '这是一篇科技文章', ARRAY['科技','体育','娱乐'])	78
AI_SUMMARIZE + max_words	`AI_CONTEXT_LENGTH('AI_SUMMARIZE', '这是一段需要摘要的文字内容', 50)` AI_CONTEXT_LENGTH('AI_SUMMARIZE', '这是一段需要摘要的文字内容', 50)	38
AI_SENTIMENT	`AI_CONTEXT_LENGTH('AI_SENTIMENT', '今天天气真好，心情很愉快')` AI_CONTEXT_LENGTH('AI_SENTIMENT', '今天天气真好，心情很愉快')	61
AI_TRANSLATE	`AI_CONTEXT_LENGTH('AI_TRANSLATE', 'Hello world', 'zh')` AI_CONTEXT_LENGTH('AI_TRANSLATE', 'Hello world', 'zh')	31
AI_FIX_GRAMMAR	`AI_CONTEXT_LENGTH('AI_FIX_GRAMMAR', 'He go to school yesterday')` AI_CONTEXT_LENGTH('AI_FIX_GRAMMAR', 'He go to school yesterday')	40
AI_MASK + labels	`AI_CONTEXT_LENGTH('AI_MASK', '张三的电话是13800138000', ARRAY['name','phone'])` AI_CONTEXT_LENGTH('AI_MASK', '张三的电话是13800138000', ARRAY['name','phone'])	60
AI_SIMILARITY	`AI_CONTEXT_LENGTH('AI_SIMILARITY', '向量数据库', '向量检索')` AI_CONTEXT_LENGTH('AI_SIMILARITY', '向量数据库', '向量检索')	7
大小写不敏感	`AI_CONTEXT_LENGTH('ai_complete', '测试大小写')` AI_CONTEXT_LENGTH('ai_complete', '测试大小写') = `AI_CONTEXT_LENGTH('AI_COMPLETE', '测试大小写')` AI_CONTEXT_LENGTH('AI_COMPLETE', '测试大小写')	3 = 3 ✓
AI_TRANSCRIBE（应报错）	`AI_CONTEXT_LENGTH('AI_TRANSCRIBE', ...)` AI_CONTEXT_LENGTH('AI_TRANSCRIBE', ...)	运行时报错 CZLH-67000 ✓
未知函数名（应报错）	`AI_CONTEXT_LENGTH('AI_UNKNOWN_FUNC', 'test')` AI_CONTEXT_LENGTH('AI_UNKNOWN_FUNC', 'test')	编译期报错 CZLH-42000 ✓
非常量函数名（应报错）	`AI_CONTEXT_LENGTH(col, 'test')` AI_CONTEXT_LENGTH(col, 'test')	编译期报错 CZLH-42000 ✓

联系我们