一、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, test2WHERE ai_filter('Both {} and {} are related to security?', test.string_col, test2.string_col)ORDER BY test.id;SELECT test.id FROM test, test2WHERE ai_filter('Both {} and {} are related to security?', test.string_col, test2.string_col) AND test.string_col < test2.string_colORDER BY test.id;
不会触发 LLM NESTLOOP JOIN 的示例（存在等值条件，优化器选择 HashJoin）：
SELECT test.id FROM test, test2WHERE ai_filter('Both {} and {} are related to security?', test.string_col, test2.string_col) AND test.string_col = test2.string_colORDER BY test.id;
21、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_';
22、8.2 DESCRIBE ENDPOINT
查看单个 Endpoint 的详细属性。
语法
DESCRIBE ENDPOINT '<name>';
示例
DESCRIBE ENDPOINT 'test_ep_llm';