腾讯云数据仓库 TCHouse-X AI Function 高级

本文适用于腾讯云数据仓库 TCHouse-X 的 AI Function 的推理优化（Cascade / Distill）、OPTIONS 参数、AI Filter 批处理以及 Endpoint 管理语法等进阶用法。
1. 概述
本文面向已经掌握 AI Function 基础用法的用户，介绍三类进阶能力：
推理优化：在保证准确率的前提下，用小模型 / 向量分类头替代大部分大模型调用，显著降低成本与延迟（Cascade、Distill）。
OPTIONS 参数：对单次调用的限流、重试、提示词、模型请求体做细粒度控制。
AI Filter 批处理：把多行数据合并进一次模型请求，减少调用次数与端到端耗时。
本文同时给出 Endpoint 管理语法（SHOW ENDPOINTS / DESCRIBE ENDPOINT）与用量审计系统表说明。函数的基础语法请参见 AI Function 函数列表。
2. 推理优化
Cascade 与 Distill 是两条独立的 AI 函数优化路径，命名空间隔离，可共存于同一列。两者的本质区别在于“快路径”的产物形态：
维度
Cascade
Distill
快路径产物
训练一个 router，决策“走 proxy 还是 base”
训练一个 LR 分类头，可直接产出预测
快路径每样本成本
1 次 proxy 小 LLM 调用
1 次 embedding 调用 + 本地打分（近乎零开销）
训练成本
高（proxy LLM 全量推理 + 训 router）
低（一次 embedding 全量 + 训 LR，分钟级）
依赖端点
PROXY（scene = TEXT_GENERATION）
EMBED（scene = EMBEDDING）
Fallback 触发
proxy 置信度不足或 router 拒绝
LR head top-1 概率 < distill_confidence_threshold
准确率上限
接近 base（proxy 也是 LLM，长尾覆盖强）
受 embedding 表征与线性可分性约束
选型建议
优先 Distill：语义边界清晰、类别有限的分类型任务（情感、意图、简单标签体系），训练样本量适中（≥ 1k）。加速比大、成本低，在语义边界清晰的情况下准确率甚至可超过 base 模型。
优先 Cascade：难以用 embedding 线性区分的任务，例如文本内容边界模糊的场景。
双头共存：Distill 作为第一层兜快、Cascade 作为第二层兜准。Distill fallback 的样本先交给 Cascade 的 proxy 处理，proxy 再兜不住才回落 base，适合“大部分样本简单、少数样本复杂”的长尾分布。
不确定选哪个：从 Distill 起步，成本最低；用一批线上样本验证准确率下降在可接受范围内即可锁定，否则叠加 Cascade 或退回原始 base 路径。
说明：
推理优化当前仅支持判别式函数：ai_sentiment / ai_classify / ai_filter。其他函数（生成式函数、AI.FORECAST 等）显式设置 ai_optimizer 会被拒绝。
3. Cascade
Cascade 先训练一个小 LLM router，查询时命中 router 的走 proxy（小 / 快模型），未命中的回落 base（基础模型）。
3.1 训练
ANALYZE ai_sentiment(t.col)
  USING BASE ENDPOINT '<base>', PROXY ENDPOINT '<proxy>';
﻿
ANALYZE ai_classify(t.col, ARRAY['pos','neg','neu'])
  USING BASE ENDPOINT '<base>', PROXY ENDPOINT '<proxy>';
﻿
ANALYZE ai_filter('{} is about a positive experience', t.col)
  USING BASE ENDPOINT '<base>', PROXY ENDPOINT '<proxy>'
  SAMPLE_SIZE=2000;
PROXY ENDPOINT 是 Cascade 的唯一入场关键字。约束如下：
PROXY 端点的 scene 必须是 TEXT_GENERATION。
BASE 与 PROXY 不能是同一个 endpoint。
对表数据的引用必须是单列（bare column），表达式会被拒绝。
换谓词、换 labels 即为另一份 router，需要重新 ANALYZE。
3.2 推理
SELECT ai_sentiment(
  ENDPOINT '<base>',
  OPTIONS  '{"ai_optimizer":"cascade"}',
  col
) FROM t;
说明：
推理时的 ENDPOINT 必须与训练时的 BASE 同名。更换 base 名称会导致 modelKey 变化，直接报错 no router trained。
4. Distill
Distill 先训练一个 LR 分类头（embedding + logistic regression head），查询时对目标列做 embedding 后直接产出预测，无需再调用大模型。
4.1 训练
ANALYZE ai_sentiment(t.col)
  USING BASE ENDPOINT '<base>', EMBED ENDPOINT '<embed>';
﻿
ANALYZE ai_classify(t.col, ARRAY['pos','neg','neu'])
  USING BASE ENDPOINT '<base>', EMBED ENDPOINT '<embed>';
﻿
ANALYZE ai_filter('{} is about a positive experience', t.col)
  USING BASE ENDPOINT '<base>', EMBED ENDPOINT '<embed>';
EMBED ENDPOINT 是 Distill 的唯一入场关键字。PROXY 与 EMBED 互斥，一条 ANALYZE 语句中只能出现其中一个。约束如下：
EMBED 端点的 scene 必须是 EMBEDDING。
BASE 与 EMBED 不能是同一个 endpoint。
对表数据的引用必须是单列——LR head 是按单个物理列训练的，表达式会被拒绝。
换谓词、换 labels 即为另一份 head，需要重新 ANALYZE。
4.2 推理
SELECT ai_sentiment(
  ENDPOINT '<base>',
  OPTIONS  '{"ai_optimizer":"distill"}',
  col
) FROM t;
说明：
推理时的 ENDPOINT 必须与训练时的 BASE 同名。更换 base 名称会导致 modelKey 变化，直接报错 no LR head trained。
5. 双头共存
同一 (base, column, paramSig) 可以先后训练 Cascade router 与 Distill LR head，两者命名空间独立、互不覆盖。SELECT 时传入数组即可同时启用：
SELECT ai_sentiment(
  ENDPOINT '<base>',
  OPTIONS  '{"ai_optimizer":["distill","cascade"]}',
  col
) FROM t;
效果是：Distill 路径 fallback 的样本，还可以继续由 Cascade 优化兜底，只有 Cascade 也兜不住的样本才回落 base。
6. OPTIONS 参数参考
OPTIONS 是一段随 AI 函数一同传入的 JSON 字符串，用于控制推理行为、限流与优化器路由。所有 key 大小写敏感，未识别的 key 会被丢弃。
典型示例（以 Distill 为例，同时使用三类 key）：
SELECT ai_classify(
  ENDPOINT '<base>',
  OPTIONS  '{
    "ai_optimizer": "distill",
    "distill_confidence_threshold": 0.8,
    "distill_embed_max_qps": 50,
    "max_qps": 20,
    "hint": "only output lowercase labels"
  }',
  col, ARRAY['pos','neg','neu']
) FROM t;
上例中：ai_optimizer / distill_confidence_threshold / distill_embed_max_qps 走 Distill 路径——分类头置信度 ≥ 0.8 时直接采纳其结果，否则回落基础模型；max_qps 与 distill_embed_max_qps 分别限流“基础模型”与“embedding”两段调用，互不影响；hint 只对最终基础模型的 prompt 生效。
字段分三类：通用可调（所有 AI 函数可用）、优化器专属可调（仅启用对应优化器时生效）、planner-owned（由 SQL 前端在语句改写阶段自动填入，用户显式写会报错）。
6.1 通用可调 key
Key
类型
默认值
说明
ai_optimizer
string 或 string 数组
未设置
启用推理优化。取值 cascade / distill，或数组 ["cascade","distill"] 同时启用。未设置时走原始基础模型路径。仅 ai_classify / ai_filter / ai_sentiment 支持，其他函数显式设置会被拒绝
max_qps
int
instance 默认值
基础模型 endpoint 的 QPS 上限，用于保护共享 endpoint 在大批量查询下不被打爆
max_concurrency
int
instance 默认值
基础模型 endpoint 的在途请求数上限
max_retries
int
instance 默认值
遇到暂时性错误（5xx / 超时）时的重试次数，设为 0 关闭重试
hint
string 或 string 数组
无
附加到系统提示词末尾的自由文本，作为控制模型输出的规则约束；数组时按行拼接。AI.FORECAST 不支持
kwargs
JSON 对象
{}
追加进基础模型请求体的自由字段（OpenAI Chat Completions 兼容），用于 endpoint 支持但函数未显式建模的参数。AI.FORECAST 的远端走私有 /infer 协议，kwargs 转发至该协议请求体；本地推理分支不消费 kwargs
6.2 Cascade 专属可调 key
仅在 "ai_optimizer":"cascade" 时生效。所有 proxy_* 作用于 Cascade 路由的 proxy（小 / 快模型）分支。
Key
类型
默认值
说明
cascade_type
string
ml
路由策略：threshold（proxy 的 top-1 logprob ≥ confidence_threshold 时采纳 proxy 答案）或 ml（由训练好的 router 决定）
confidence_threshold
float
0.95
threshold 策略下的 proxy 置信度下限，取值 [0, 1]
target_accuracy
float
0.90
ml 策略下的端到端准确率目标，router 据此选择 proxy / base 分流比例，取值 (0, 1]
proxy_max_qps
int
无
Proxy endpoint 的 QPS 上限，与基础模型的 max_qps 相互独立，≥ 1
proxy_max_concurrency
int
无
Proxy endpoint 的在途请求数上限，≥ 1
proxy_max_retries
int
无
Proxy endpoint 的重试次数，≥ 0
proxy_kwargs
JSON 对象
{}
Proxy 请求体的自由字段，语义与 kwargs 一致，作用对象换成 proxy
6.3 Distill 专属可调 key
仅在 "ai_optimizer":"distill" 时生效。所有 distill_embed_* 作用于蒸馏分类头依赖的 embedding 调用。
Key
类型
默认值
说明
distill_confidence_threshold
float
0.0
蒸馏分类头 top-1 概率下限，低于此值回落到基础模型，取值 [0, 1]；默认 0.0 等价于 argmax（分类头始终作答）
distill_embed_max_qps
int
无
Embedding endpoint 的 QPS 上限
distill_embed_max_concurrency
int
无
Embedding endpoint 的在途请求数上限
distill_embed_max_retries
int
无
Embedding endpoint 的重试次数
distill_embed_kwargs
JSON 对象
{}
Embedding 请求体的自由字段，用于兼容 endpoint 白名单较严、需要额外或替换字段的场景
6.4 planner-owned key（禁写）
以下 key 由 SQL 前端在语句改写阶段自动填入，来源有两类：来自 ENDPOINT 对象（基础模型、proxy、embedding 三条链路的连接信息，以 ENDPOINT '<name>' 引用后由 catalog 解析注入），以及来自 ANALYZE 训练产物（cascade router、蒸馏分类头的模型引用，SELECT 时由前端按 (base endpoint, column, param signature) 查表填入）。
来源
禁写 key
BASE 端点
base_url、model、api_key
PROXY 端点
proxy_base_url、proxy_model、proxy_api_key
EMBED 端点
distill_embed_base_url、distill_embed_model、distill_embed_api_key
ANALYZE 产物
cascade_model_uri、distill_model_uri
说明：
在 OPTIONS 中显式写上述任意一个 key 都会直接报错。
7. AI Filter 批处理
批处理是针对 AI_FILTER 的专项优化：执行时将多行数据合并到一次模型请求内，从而减少整体模型调用次数、缩短查询执行时间。
7.1 开启与关闭
由变量 enable_batch_llm_function 控制是否允许启动 AI Filter 的批处理，默认为 TRUE。
+---------------------------+-------+
﻿
| Variable_name             | Value |
﻿
+---------------------------+-------+
﻿
| enable_batch_llm_function | true  |
﻿
+---------------------------+-------+
7.2 指定 Batch Size
可在 SQL 中通过 OPTIONS 显式指定 batch_size（要求为正整数）：
EXPLAIN SELECT ai_filter(
  ENDPOINT 'test_ep_llm',
  OPTIONS '{"kwargs": {"temperature": 0.5}, "batch_size": 15}',
  'is {} security related?', txt
) FROM test_endpoint_rows;
未显式指定时，优化器会为每个 AI_FILTER 自动计算合适的 batch_size（默认上限为 20），但需同时满足：
enable_batch_llm_function = true
统计信息完整（AI_FILTER 的输入表需经过 COMPUTE STATS）
用户未指定 cascade / distill 优化
说明：
设置建议：模型单次处理的数据量过大将导致结果质量不稳定，因此 batch_size 不宜设置过大。
7.3 语义 JOIN 的批处理
两参数形态的 AI_FILTER 具备 JOIN 语义，因此有独立的批处理方式，专门设计了新的 Join 类型：LLM NESTLOOP JOIN。
由 enable_batch_llm_function 与 enable_llm_nestloop_join 两个变量共同控制：
+---------------------------+-------+
﻿
| Variable_name             | Value |
﻿
+---------------------------+-------+
﻿
| enable_llm_nestloop_join  | true  |
| enable_batch_llm_function | true  |
﻿
+---------------------------+-------+
优化器会为这类 AI_FILTER 自动选择 LLM NESTLOOP JOIN，并计算合适的 left batch_size 与 right batch_size，需满足：
enable_batch_llm_function = true
enable_llm_nestloop_join = true
统计信息完整（AI_FILTER 的输入表需经过 COMPUTE STATS）
AI_FILTER 中除 prompt 外的列参数必须是裸列，且类型为 STRING
不存在可触发 HashJoin 的等值连接条件（优化器会优先选择 HashJoin）
会触发 LLM NESTLOOP JOIN 的示例：
SELECT test.id FROM test, test2
WHERE ai_filter('Both {} and {} are related to security?', test.string_col, test2.string_col)
ORDER BY test.id;
﻿
SELECT test.id FROM test, test2
WHERE ai_filter('Both {} and {} are related to security?', test.string_col, test2.string_col)
  AND test.string_col < test2.string_col
ORDER BY test.id;
不会触发 LLM NESTLOOP JOIN 的示例（存在等值条件，优化器选择 HashJoin）：
SELECT test.id FROM test, test2
WHERE ai_filter('Both {} and {} are related to security?', test.string_col, test2.string_col)
  AND test.string_col = test2.string_col
ORDER BY test.id;
8. Endpoint 管理语法
8.1 SHOW ENDPOINTS
列出当前实例下所有已注册的 Endpoint。
语法
SHOW ENDPOINTS;
SHOW ENDPOINTS LIKE '<pattern>';
LIKE 后接 Hive 风格通配符：% 匹配任意字符，_ 匹配单字符。
未指定 LIKE 时返回全部 endpoint。
示例
-- 全量
SHOW ENDPOINTS;
﻿
-- 前缀过滤（推荐用于测试 / 大规模环境）
SHOW ENDPOINTS LIKE 'test_ep_%';
﻿
-- 单字符占位
SHOW ENDPOINTS LIKE 'prod_ep_v_';
8.2 DESCRIBE ENDPOINT
查看单个 Endpoint 的详细属性。
语法
DESCRIBE ENDPOINT '<name>';
示例
DESCRIBE ENDPOINT 'test_ep_llm';

AI Function 高级用法

本页目录：

1. 概述

2. 推理优化

选型建议

3. Cascade

3.1 训练

3.2 推理

4. Distill

4.1 训练

4.2 推理

5. 双头共存

6. OPTIONS 参数参考

6.1 通用可调 key

6.2 Cascade 专属可调 key

6.3 Distill 专属可调 key

6.4 planner-owned key（禁写）

7. AI Filter 批处理

7.1 开启与关闭

7.2 指定 Batch Size

7.3 语义 JOIN 的批处理

8. Endpoint 管理语法

8.1 SHOW ENDPOINTS

8.2 DESCRIBE ENDPOINT

维度	Cascade	Distill
快路径产物	训练一个 router，决策“走 proxy 还是 base”	训练一个 LR 分类头，可直接产出预测
快路径每样本成本	1 次 proxy 小 LLM 调用	1 次 embedding 调用 + 本地打分（近乎零开销）
训练成本	高（proxy LLM 全量推理 + 训 router）	低（一次 embedding 全量 + 训 LR，分钟级）
依赖端点	PROXY（scene = TEXT_GENERATION）	EMBED（scene = EMBEDDING）
Fallback 触发	proxy 置信度不足或 router 拒绝	LR head top-1 概率 < distill_confidence_threshold
准确率上限	接近 base（proxy 也是 LLM，长尾覆盖强）	受 embedding 表征与线性可分性约束

Key	类型	默认值	说明
`ai_optimizer`	string 或 string 数组	未设置	启用推理优化。取值 `cascade` / `distill`，或数组 `["cascade","distill"]` 同时启用。未设置时走原始基础模型路径。仅 `ai_classify` / `ai_filter` / `ai_sentiment` 支持，其他函数显式设置会被拒绝
`max_qps`	int	instance 默认值	基础模型 endpoint 的 QPS 上限，用于保护共享 endpoint 在大批量查询下不被打爆
`max_concurrency`	int	instance 默认值	基础模型 endpoint 的在途请求数上限
`max_retries`	int	instance 默认值	遇到暂时性错误（5xx / 超时）时的重试次数，设为 0 关闭重试
`hint`	string 或 string 数组	无	附加到系统提示词末尾的自由文本，作为控制模型输出的规则约束；数组时按行拼接。AI.FORECAST 不支持
`kwargs`	JSON 对象	{}	追加进基础模型请求体的自由字段（OpenAI Chat Completions 兼容），用于 endpoint 支持但函数未显式建模的参数。AI.FORECAST 的远端走私有 /infer 协议，kwargs 转发至该协议请求体；本地推理分支不消费 kwargs

来源	禁写 key
BASE 端点	`base_url`、`model`、`api_key`
PROXY 端点	`proxy_base_url`、`proxy_model`、`proxy_api_key`
EMBED 端点	`distill_embed_base_url`、`distill_embed_model`、`distill_embed_api_key`
ANALYZE 产物	`cascade_model_uri`、`distill_model_uri`