StarRocks ai_complete 函数实战指南从 SQL 调用 LLM 生成文本的完整配置与源码解析【免费下载链接】starrocksThe worlds 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 的前提下从 BEBackend向管理员配置的 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 MAPVARCHAR, 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✅ 默认该失败行返回 NULL查询继续执行fail-直接中止整个查询需要特别说明的是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 模型配置管理员操作管理员通过以下三个可变mutableFE 参数配置 SYSTEM 模型。其中 endpoint 与 provider 是每次调用都必需的默认模型仅在“仅 prompt”重载下必需。参数默认值要求ai_default_chat_endpoint空字符串必需。chat-completions 端点的完整 HTTPS POST URL。ai_default_chat_model空字符串仅 prompt 重载必需当每次调用都显式提供 model 时可留空。ai_default_chat_provider空字符串必需。唯一合法值为openai_compatible。结合 user_query_loading.md 中## Query engine一节的参数描述可以补充以下细节endpoint 约束URL 必须包含 host不能包含用户信息、fragment 或控制字符省略端口时使用 HTTPS 默认端口显式端口必须在 165535 范围内。endpoint 为空会禁用 SYSTEMai_complete的分析直到配置完成。model 约束值不能包含 C0 控制字符U0000–U001F或 DELU007F。provider 约束必须精确等于openai_compatible空值或包含任何多余字符包括控制字符都会导致分析失败。快照语义关键机制每个查询计划都会捕获这些值的一份快照。动态修改只对修改之后才被分析与规划的新查询生效已构建完成的计划会继续沿用规划时捕获的旧快照。这也意味着修改 FE endpoint 后还必须同步更新每个受影响 BE 的环境变量并重启 BE新 AI 查询才能在新的绑定下运行。5.2 BE 本地凭据绑定API Key 不是 FE 配置项也不会进入查询计划。每个 BE 需要在其本地进程环境中设置环境变量说明AI_FUNCTION_MODEL_API_KEYBE 本地读取作为 Bearer 凭据发送。AI_FUNCTION_MODEL_ENDPOINT必须与ai_default_chat_endpoint完全相同的完整 HTTPS URL。这两个环境变量名在源码中有明确的常量定义见 ai_project_runtime.cppconstexpr 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 参数默认值作用ai_function_rate_limit_qps_chat128每个 BE 上按 endpoint、凭据、能力分桶的请求准入 QPS 上限requests/s。降低可遵守提供商配额、减少出站负载。ai_function_max_inflight512进程级并发在飞请求上限admission 限制非每查询配额用于约束 HTTP 与响应内存压力。ai_function_max_retries3普通可重试传输/提供商失败的重试次数上限初始尝试不计入与限流重试共享同一序数。设为0关闭。ai_function_max_retries_on_throttle5提供商限流如 HTTP 429时的重试上限初始尝试不计入与普通重试共享同一序数。ai_function_on_errorignore行级失败策略ignore返回 NULL 继续或fail中止查询。ai_function_request_timeout_ms600000单个 AI 任务的独立最大生命周期含准入、首次尝试、全部重试与退避、完成分类任务级固定、不随重试重启0表示禁用独立限制。ai_function_connect_timeout_ms10000单次 HTTP 尝试的连接建立上限。ai_function_max_response_bytes8388608单个 HTTP 响应体的硬性大小上限超出即在提供商解析前拒绝以约束 BE 内存。ai_function_worker_thread_num16处理 AI HTTP 完成与响应分类的工作线程数。ai_function_sub_chunk_size64一个 AI 执行子块的最大行数影响调度与取消粒度。需要重点理解的几个运行机制均来自 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执行管线在请求未完成时施加背压backpressureai_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的完整调用链帮助读者理解各配置项实际作用的阶段FE 分析阶段AIFunctionAnalyzer与AIFunctionUsageAnalyzerfe/fe-core/src/main/java/com/starrocks/sql/analyzer/负责校验函数重载、Options MAP 规则、使用位置限制并读取ai_default_chat_*参数快照写入计划。BE 执行阶段AI 投影算子由 ai_project_factory.cpp 创建ai_project_operator/ai_project_processor完成子块划分ai_function_sub_chunk_size与异步调度ai_project_runtime维护任务生命周期、准入、重试与超时。协议层ai_http_client.cpp 负责 DNS 校验、连接与 TLSopenai_compatible_provider.cpp 按openai_compatible协议组装 chat-completions 请求并解析choices[0].message.content。这也解释了为什么 FE 的ai_default_chat_provider目前唯一合法取值就是openai_compatible。凭据注入API Key 在 BE 进程内从AI_FUNCTION_MODEL_API_KEY环境变量读取并作为 Bearer 凭据注入从不进入查询计划或 SQL 文本。九、关键词AI_COMPLETE、AI、LLM延伸阅读仓库内相关文档AI functions 总览与输入行裁剪TopN pushdownFE 参数ai_default_chat_endpoint / model / providerBE 参数ai_function_* 系列【免费下载链接】starrocksThe worlds 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 StarRocks ai_complete 函数实战指南：从 SQL 调用 LLM 生成文本的完整配置与源码解析
StarRocks ai_complete 函数实战指南从 SQL 调用 LLM 生成文本的完整配置与源码解析【免费下载链接】starrocksThe worlds 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 的前提下从 BEBackend向管理员配置的 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 MAPVARCHAR, 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✅ 默认该失败行返回 NULL查询继续执行fail-直接中止整个查询需要特别说明的是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 模型配置管理员操作管理员通过以下三个可变mutableFE 参数配置 SYSTEM 模型。其中 endpoint 与 provider 是每次调用都必需的默认模型仅在“仅 prompt”重载下必需。参数默认值要求ai_default_chat_endpoint空字符串必需。chat-completions 端点的完整 HTTPS POST URL。ai_default_chat_model空字符串仅 prompt 重载必需当每次调用都显式提供 model 时可留空。ai_default_chat_provider空字符串必需。唯一合法值为openai_compatible。结合 user_query_loading.md 中## Query engine一节的参数描述可以补充以下细节endpoint 约束URL 必须包含 host不能包含用户信息、fragment 或控制字符省略端口时使用 HTTPS 默认端口显式端口必须在 165535 范围内。endpoint 为空会禁用 SYSTEMai_complete的分析直到配置完成。model 约束值不能包含 C0 控制字符U0000–U001F或 DELU007F。provider 约束必须精确等于openai_compatible空值或包含任何多余字符包括控制字符都会导致分析失败。快照语义关键机制每个查询计划都会捕获这些值的一份快照。动态修改只对修改之后才被分析与规划的新查询生效已构建完成的计划会继续沿用规划时捕获的旧快照。这也意味着修改 FE endpoint 后还必须同步更新每个受影响 BE 的环境变量并重启 BE新 AI 查询才能在新的绑定下运行。5.2 BE 本地凭据绑定API Key 不是 FE 配置项也不会进入查询计划。每个 BE 需要在其本地进程环境中设置环境变量说明AI_FUNCTION_MODEL_API_KEYBE 本地读取作为 Bearer 凭据发送。AI_FUNCTION_MODEL_ENDPOINT必须与ai_default_chat_endpoint完全相同的完整 HTTPS URL。这两个环境变量名在源码中有明确的常量定义见 ai_project_runtime.cppconstexpr 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 参数默认值作用ai_function_rate_limit_qps_chat128每个 BE 上按 endpoint、凭据、能力分桶的请求准入 QPS 上限requests/s。降低可遵守提供商配额、减少出站负载。ai_function_max_inflight512进程级并发在飞请求上限admission 限制非每查询配额用于约束 HTTP 与响应内存压力。ai_function_max_retries3普通可重试传输/提供商失败的重试次数上限初始尝试不计入与限流重试共享同一序数。设为0关闭。ai_function_max_retries_on_throttle5提供商限流如 HTTP 429时的重试上限初始尝试不计入与普通重试共享同一序数。ai_function_on_errorignore行级失败策略ignore返回 NULL 继续或fail中止查询。ai_function_request_timeout_ms600000单个 AI 任务的独立最大生命周期含准入、首次尝试、全部重试与退避、完成分类任务级固定、不随重试重启0表示禁用独立限制。ai_function_connect_timeout_ms10000单次 HTTP 尝试的连接建立上限。ai_function_max_response_bytes8388608单个 HTTP 响应体的硬性大小上限超出即在提供商解析前拒绝以约束 BE 内存。ai_function_worker_thread_num16处理 AI HTTP 完成与响应分类的工作线程数。ai_function_sub_chunk_size64一个 AI 执行子块的最大行数影响调度与取消粒度。需要重点理解的几个运行机制均来自 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执行管线在请求未完成时施加背压backpressureai_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的完整调用链帮助读者理解各配置项实际作用的阶段FE 分析阶段AIFunctionAnalyzer与AIFunctionUsageAnalyzerfe/fe-core/src/main/java/com/starrocks/sql/analyzer/负责校验函数重载、Options MAP 规则、使用位置限制并读取ai_default_chat_*参数快照写入计划。BE 执行阶段AI 投影算子由 ai_project_factory.cpp 创建ai_project_operator/ai_project_processor完成子块划分ai_function_sub_chunk_size与异步调度ai_project_runtime维护任务生命周期、准入、重试与超时。协议层ai_http_client.cpp 负责 DNS 校验、连接与 TLSopenai_compatible_provider.cpp 按openai_compatible协议组装 chat-completions 请求并解析choices[0].message.content。这也解释了为什么 FE 的ai_default_chat_provider目前唯一合法取值就是openai_compatible。凭据注入API Key 在 BE 进程内从AI_FUNCTION_MODEL_API_KEY环境变量读取并作为 Bearer 凭据注入从不进入查询计划或 SQL 文本。九、关键词AI_COMPLETE、AI、LLM延伸阅读仓库内相关文档AI functions 总览与输入行裁剪TopN pushdownFE 参数ai_default_chat_endpoint / model / providerBE 参数ai_function_* 系列【免费下载链接】starrocksThe worlds 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考