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-..."
);
相关文档
ALTER AI PROVIDER——修改已有 provider 的属性。DROP AI PROVIDER——删除 provider。SHOW AI PROVIDERS——列出 provider(可按TYPE过滤)。DESC AI PROVIDER——查看单个 provider 的完整配置。SET DEFAULT AI PROVIDER——设置某类型的默认 provider。
本文来自 StarRocks 文档贡献者,按 Apache 2.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。
