StarRocks ai_complete 函数实战指南：从 SQL 调用 LLM 生成文本的完整配置与源码解析

StarRocks ai_complete 函数实战指南：从 SQL 调用 LLM 生成文本的完整配置与源码解析

【免费下载链接】starrocksThe world's fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks

本文围绕 StarRocks 内置的ai_complete标量函数展开，讲解如何在不离开 SQL 的前提下，从 BE（Backend）向管理员配置的 SYSTEM 级 OpenAI 兼容 chat 模型发起非流式生成请求并取回文本。文章既覆盖函数语法、参数约束、Options MAP 规则、FE/BE 双层配置与行级错误处理等全部实操要素，也结合仓库中的 FE 分析器、BE AI pipeline 与 OpenAI 兼容 provider 源码，解释这些行为背后的实现原理。读完本文，你将能够独立完成 SYSTEM 模型配置、BE 本地凭据绑定、限流与重试调优，并在EXPLAIN验证下安全使用ai_complete。

一、函数概述：SQL 里的文本生成

ai_complete是 StarRocks 提供的 SYSTEM 级 AI 函数之一，其行为定义在 ai_complete.md：调用管理员预先配置的 SYSTEM chat 模型，返回模型生成的文本。调用时，StarRocks 会从 BE 发送一个**非流式（non-streaming）**的 OpenAI 兼容chat/completions请求。

从源码结构看，该能力在 BE 侧由一套专门的 AI 执行链路承载：be/src/exec/pipeline/ai/目录下的ai_project_operator、ai_project_processor、ai_project_runtime负责 AI 投影算子的调度与运行时，而be/src/platform/llm/下的ai_http_client.cpp、openai_compatible_provider.cpp实现了 HTTP 客户端与 OpenAI 兼容协议封装。这意味着ai_complete的请求发出、限流、重试、超时全部发生在 BE 进程内，与 FE 的查询规划解耦。

安全警告（文档原文）：该函数会把模型名、提示词和选项发送到配置的端点。请只使用可信的、必须启用 HTTPS 的端点；除非提供商获准接收机密数据，否则不要把密钥或敏感数据放入 prompt；调用可能离开 StarRocks 集群、产生提供商费用，并受提供商数据保留政策约束。

二、语法与重载形式

ai_complete提供四种重载：

ai_complete(<prompt>) ai_complete(<prompt>, <options>) ai_complete(<model>, <prompt>) ai_complete(<model>, <prompt>, <options>)

• 前两种为“仅 prompt”形式，模型取自 FE 参数ai_default_chat_model；
• 后两种为“显式 model”形式，允许按行指定不同模型（显式 model 可以逐行变化）。

三、参数详解

3.1prompt

一个 VARCHAR 表达式，即用户提示词。空字符串是合法输入。

3.2model

一个 VARCHAR 表达式，用于为本次调用选择模型。省略时使用 FE 参数ai_default_chat_model（见下文配置章节）。显式 model 可以逐行不同，但常量 model 不能为空或仅含空白字符（仅含空白同样非法）。

3.3options

一个可选的常量 MAP，用于向提供商请求追加额外字段。类型化的 NULL MAP 按空 MAP 处理。

Options MAP 规则

• MAP 必须是常量；在任何顶层或嵌套 MAP 内，键必须唯一、非 NULL、非空 VARCHAR。
• 值必须是 JSON 兼容类型：NULL、BOOLEAN、有限数值、字符串、JSON、ARRAY、MAP 或 STRUCT；嵌套 MAP 的键也必须是 VARCHAR。
• 顶层键model、messages、stream为保留字（大小写敏感），不允许用户提供——这三个字段由 StarRocks 自行构造，且始终发送非流式请求。
• 两参形式中的裸 NULL 会被解析为ai_complete(<model>, NULL)；若想把 NULL 作为options传入，需要显式强转类型，例如：

CAST(NULL AS MAP<VARCHAR, JSON>)

在 FE 侧，这些规则的解析与合法性校验由 AIFunctionAnalyzer.java 及配套的ResolvedAIFunctionDetector等分析器组件完成，任何保留键或非常量 MAP 都会在分析阶段直接报错。

四、返回值与错误处理

4.1 返回值

函数返回一个可空的 VARCHAR，取值为成功响应中的choices[0].message.content。

• 若prompt为 NULL，函数直接返回 NULL，不提交提供商请求；
• 对于显式model的重载，若model为 NULL，同样返回 NULL 且不发请求。

4.2 行级错误控制（ai_function_on_error）

行级失败由 BE 配置ai_function_on_error控制：

需要特别说明的是，ignore不会抑制以下错误：分析错误（analysis errors）、配置错误、查询取消（cancellation）、截止时间（deadline）超时以及 BE 关闭（shutdown）等系统级事件。

4.3 非确定性

ai_complete是非确定性函数：相同参数可能因提供商状态、模型行为和运行时条件不同而返回不同文本，甚至以不同方式失败。因此，任何依赖该函数结果可复现的优化（如物化视图、SPM 重写）都不适用（详见第七节）。

4.4 AI 查询优化参考

对于需要控制 AI 输入行数的场景，文档建议参考 Reducing AI input rows：当查询为ORDER BY ... LIMIT（正 LIMIT、无 OFFSET）且排序列能穿过 AI 投影时，StarRocks 会通过ai_topn_pushdown_max_global_limit（默认1000）选择全局候选 TopN 或本地候选 TopN 策略，在 AI 投影执行前裁剪候选行，从而减少远程调用次数。

五、配置指南：FE 与 BE 双层体系

ai_complete的配置分为 FE 侧 SYSTEM 模型配置与 BE 侧本地凭据两部分，缺一不可。

5.1 FE SYSTEM 模型配置（管理员操作）

管理员通过以下三个可变（mutable）FE 参数配置 SYSTEM 模型。其中 endpoint 与 provider 是每次调用都必需的；默认模型仅在“仅 prompt”重载下必需。

结合 user_query_loading.md 中## Query engine一节的参数描述，可以补充以下细节：

• endpoint 约束：URL 必须包含 host，不能包含用户信息、fragment 或控制字符；省略端口时使用 HTTPS 默认端口，显式端口必须在 1～65535 范围内。endpoint 为空会禁用 SYSTEMai_complete的分析，直到配置完成。
• model 约束：值不能包含 C0 控制字符（U+0000–U+001F）或 DEL（U+007F）。
• provider 约束：必须精确等于openai_compatible；空值或包含任何多余字符（包括控制字符）都会导致分析失败。

快照语义（关键机制）：每个查询计划都会捕获这些值的一份快照。动态修改只对修改之后才被分析与规划的新查询生效；已构建完成的计划会继续沿用规划时捕获的旧快照。这也意味着：修改 FE endpoint 后，还必须同步更新每个受影响 BE 的环境变量并重启 BE，新 AI 查询才能在新的绑定下运行。

5.2 BE 本地凭据绑定

API Key 不是 FE 配置项，也不会进入查询计划。每个 BE 需要在其本地进程环境中设置：

这两个环境变量名在源码中有明确的常量定义，见 ai_project_runtime.cpp：

constexpr std::string_view kApiKeyEnvironment = "AI_FUNCTION_MODEL_API_KEY"; constexpr std::string_view kEndpointEnvironment = "AI_FUNCTION_MODEL_ENDPOINT";

BE 端点校验逻辑：BE 会拒绝 endpoint 与本地绑定不一致的计划；会校验每一个 DNS 地址、屏蔽 link-local 地址，并将校验通过的 DNS 快照固定（pin）用于本次请求。精确的本地绑定机制也允许管理员有意授权私有网络内的模型端点。修改任一环境变量后必须重启对应 BE。切勿把凭据写入 SQL 文本或 options MAP——从源码可以看出，凭据只经由进程环境注入 HTTP 请求头，不参与 FE 的查询计划序列化。

5.3 运行时限流、重试与超时（BE 参数）

所有ai_function_*参数均可在运行时动态修改（无需重启 BE），相关完整说明见 BE 参数 query_loading.md。核心参数汇总如下：

需要重点理解的几个运行机制（均来自 BE 参数 query_loading.md 与 ai_complete 文档）：

• 双准入机制：QPS 限流与在飞限制在每个 BE 上独立生效；QPS 按 endpoint、凭据、能力桶维护，在飞限制为进程级。每次初始或重试的 HTTP 尝试都必须同时获得两个准入许可。WorkGroup 与查询感知的准入会在排队请求间共享可用限额。
• 非精确一次语义：StarRocks 无法向模型提供商保证 exactly-once。超时或失败的尝试可能已经到达提供商，因此重试可能重复提供商工作并产生额外费用——需要根据提供商的计费策略来权衡ai_function_max_retries与ai_function_max_retries_on_throttle。
• 内存与背压：请求与响应负载计入查询内存跟踪器（memory tracker），执行管线在请求未完成时施加背压（backpressure）；ai_function_max_response_bytes是每个响应体的硬上限。
• 超时不重启：独立任务超时在任务生命周期内固定，不随每次重试重新计时；异步执行全程感知查询取消与截止时间更新。

六、使用限制与安全边界

ai_complete具有严格的语法位置限制，这些约束在 FE 分析阶段强制执行：

不能出现的位置：

• GROUP BY、SELECT DISTINCT、聚合函数参数、窗口函数表达式中；
• IF、IFNULL、NULLIF、COALESCE、CASE等条件表达式中，也不能作为表函数（table function）参数；
• 物化视图定义、生成列表达式中；
• lambda 表达式体或 SQL UDF 函数体中。

规划与执行层面的特殊行为：

• 包含ai_complete的语句不能创建或绑定 SQL plan baseline，查询规划时不经过 SPM 重写；
• PREPARE受支持，但包含ai_complete的语句在每次EXECUTE时都会完全重新规划，执行计划不复用（对应 FE 侧 PrepareStmtPlanner.java 中对该类语句的特殊处理路径）；
• 在相关（correlated）查询块中，AI 表达式被禁止出现在SELECT列表、WHERE、HAVING、ORDER BY、JOIN ON中——即使 AI 表达式本身只引用本地列也不行；AI 表达式仅支持出现在INNER JOIN与CROSS JOIN的连接条件中。

成本提醒：每个非 NULL 输入行都可能产生一次远程请求。在大量行上使用前，必须评估网络延迟、提供商配额、查询截止时间、费用与数据出口（data-egress）政策。

七、实战示例：用 EXPLAIN 安全验证

文档推荐使用EXPLAIN验证：它只分析与规划语句，不会执行函数、也不会发送 HTTP 请求。但注意：分析期间仍要求 SYSTEM 配置合法有效（endpoint、provider 等必需项已配置）。

-- 仅 prompt，使用 ai_default_chat_model EXPLAIN SELECT ai_complete('Summarize this local test prompt.'); -- 仅 prompt + options（传递温度参数） EXPLAIN SELECT ai_complete( 'Classify this local test prompt.', map{'temperature': 0.0} ); -- 显式 model + prompt EXPLAIN SELECT ai_complete( 'local-test-model', 'Summarize this local test prompt.' ); -- 显式 model + prompt + options（要求返回 JSON 对象） EXPLAIN SELECT ai_complete( 'local-test-model', 'Return a JSON object for this local test prompt.', map{'response_format': map{'type': 'json_object'}} );

NULL prompt 不会提交提供商请求：

SELECT ai_complete(CAST(NULL AS VARCHAR)) AS answer;

八、源码级延伸：从 SQL 到 LLM 的完整链路

从仓库结构可以还原ai_complete的完整调用链，帮助读者理解各配置项实际作用的阶段：

1. FE 分析阶段：AIFunctionAnalyzer与AIFunctionUsageAnalyzer（fe/fe-core/src/main/java/com/starrocks/sql/analyzer/）负责校验函数重载、Options MAP 规则、使用位置限制，并读取ai_default_chat_*参数快照写入计划。
2. BE 执行阶段：AI 投影算子由 ai_project_factory.cpp 创建，ai_project_operator/ai_project_processor完成子块划分（ai_function_sub_chunk_size）与异步调度，ai_project_runtime维护任务生命周期、准入、重试与超时。
3. 协议层：ai_http_client.cpp 负责 DNS 校验、连接与 TLS；openai_compatible_provider.cpp 按openai_compatible协议组装 chat-completions 请求并解析choices[0].message.content。这也解释了为什么 FE 的ai_default_chat_provider目前唯一合法取值就是openai_compatible。
4. 凭据注入：API Key 在 BE 进程内从AI_FUNCTION_MODEL_API_KEY环境变量读取并作为 Bearer 凭据注入，从不进入查询计划或 SQL 文本。

九、关键词

AI_COMPLETE、AI、LLM

延伸阅读（仓库内相关文档）：

• AI functions 总览与输入行裁剪（TopN pushdown）
• FE 参数：ai_default_chat_endpoint / model / provider
• BE 参数：ai_function_* 系列

【免费下载链接】starrocksThe world's fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks