大网数据广告活动
数据库部署与 SQL 参考

StarRocks 中文参考:CREATE AI PROVIDER

· 52CE 我爱测

在集群中注册一个外部 AI 服务 provider。统一的 AI provider 注册表持有不同**类型(type)**的 provider, 并按**类型各自保留一个默认值**:

CREATE AI PROVIDER

在集群中注册一个外部 AI 服务 provider。统一的 AI provider 注册表持有不同类型(type)的 provider, 并按类型各自保留一个默认值:

  • embedding——OpenAI 兼容的 /v1/embeddings 端点,供 semantic-context 模块在 CONTEXT UPSERT 写入和 query_text 检索时计算 embedding,也供 ai_embed 使用。
  • rerank——Cohere 兼容的 /rerank 端点(Cohere / Jina / Voyage / OpenRouter / 本地 TEI),供 /api/context/search 可选的 cross-encoder 第二阶段重排使用。
  • chat——chat / completion 端点(OpenAI Chat Completions 或 Anthropic Messages)。

每个 provider 还通过 protocol 属性声明其端点使用的协议。省略时按类型取默认值:embedding 和 chat 为 openai,rerank 为 cohere。

ai_complete 和 ai_embed 当前要求 openai 协议。使用其他已注册协议调用这些函数时,会在查询规划阶段报错。

provider 对象(含 api_key 属性)持久化在 FE 元数据 journal 与 image 中,重启和升级后凭证仍保留。 这些设置没有 fe.conf 开关。

注意

任何能读取 FE meta image / BDB journal 目录的人都能看到 api_key;请用文件系统权限保护这些文件。

创建 protocol = "openai" 的 Provider。无论是否配置 API key,端点均支持 HTTP 和 HTTPS。非空 key 生成 Authorization: Bearer ... 请求头。URL 格式、控制字符、DNS 和地址校验仍然生效。请使用可信端点和允许向外传输的数据。

使用 SET <provider_name> AS DEFAULT AI PROVIDER 设置默认值。若对应默认 Provider 未设置,隐式调用在 FE 报错,EXPLAIN 也会报错。每个执行计划固定所选 Provider 的配置快照;ALTER 和默认值切换影响重新规划的查询,预处理语句每次 EXECUTE 都根据当前元数据重新规划。

权限

创建或管理 Provider 需要 SYSTEM OPERATE 权限。通过 AI 函数调用 Provider,同时需要相应的 AI 函数权限和该 AI PROVIDER 的 USAGE 权限。创建 Provider 不会自动授予普通用户使用权限。

语法

CREATE AI PROVIDER [IF NOT EXISTS] <provider_name>
TYPE { embedding | rerank | chat }
[ COMMENT '<comment>' ]
PROPERTIES (
    "endpoint"   = "<url>",
    "model"      = "<model_name>"
    [, "protocol" = "{ openai | anthropic | cohere }" ]
    [, "dimensions" = "<int>" ]      -- 仅 embedding
    [, "max_documents" = "<int>" ]   -- 仅 rerank(可选)
    [, "deadline_ms" = "<int>" ]     -- 仅 rerank(可选)
    [, "timeout_ms" = "<int>" ]
    [, "api_key" = "<key>" ]
)

参数

参数 说明
provider_name provider 名称。用于 SET ... AS DEFAULT AI PROVIDER,并显示在 SHOW AI PROVIDERS 中。
TYPE embedding、rerank 或 chat。决定允许哪些属性,以及该 provider 可成为哪个类型的默认值。
COMMENT 可选注释。
PROPERTIES "key" = "value" 形式的配置。允许的 key 取决于 TYPE(见下)。其它 key 会被拒绝。

PROPERTIES

属性 适用类型 必填 说明
endpoint 全部 是 HTTP(S) 端点 URL,必须以 http:// 或 https:// 开头。
model 全部 是 请求体 model 字段的模型名(如 text-embedding-3-small、cohere/rerank-4-fast)。
protocol 全部 否 端点使用的协议:openai、anthropic 或 cohere。默认值:embedding 和 chat 为 openai,rerank 为 cohere。
dimensions embedding 否 embedding 向量维度(正整数)。必须与 provider 输出及向量索引维度一致。
max_documents rerank 否 每次 rerank 请求发送的最大文档数(正整数;默认 1000)。
deadline_ms rerank 否 整个 rerank 调用(含所有重试)的总时间预算(毫秒,正整数;默认 10000)。用于限制慢/不可达的 rerank 服务最多拖慢搜索多久,超过后降级为融合排序。超时不重试,仅连接失败或 HTTP 5xx 才重试。
timeout_ms 全部 否 单次请求 HTTP 超时(毫秒,正整数)。对 rerank 而言,实际会被剩余的 deadline_ms 预算进一步限制。
api_key 全部 否 Authorization 头的 Bearer token。本地免鉴权 provider 可省略。

示例

注册一个 embedding provider 并设为 embedding 类型的默认:

CREATE AI PROVIDER openai TYPE embedding
PROPERTIES (
    "endpoint"   = "https://api.openai.com/v1/embeddings",
    "model"      = "text-embedding-3-small",
    "dimensions" = "1536",
    "api_key"    = "sk-..."
);
SET openai AS DEFAULT AI PROVIDER;   -- 成为默认 embedding provider

注册一个 rerank provider 并设为 rerank 类型的默认(与 embedding 默认相互独立):

CREATE AI PROVIDER cohere_rerank TYPE rerank
PROPERTIES (
    "endpoint"   = "https://openrouter.ai/api/v1/rerank",
    "model"      = "cohere/rerank-4-fast",
    "timeout_ms" = "15000",
    "api_key"    = "sk-or-..."
);
SET cohere_rerank AS DEFAULT AI PROVIDER;   -- 成为默认 rerank provider

注册一个使用 Anthropic Messages 协议的 chat provider:

CREATE AI PROVIDER claude TYPE chat
PROPERTIES (
    "protocol" = "anthropic",
    "endpoint" = "https://api.anthropic.com/v1/messages",
    "model"    = "claude-sonnet-4-5",
    "api_key"  = "sk-ant-..."
);

相关文档

本文来自 StarRocks 文档贡献者,按 Apache 2.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
StarRocks 文档贡献者
适用范围
main 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
Apache 2.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。