LLM Gateway API
面向项目的 LLM 网关数据面与管理面:OpenAI 兼容 chat/completions 与 embeddings、Anthropic Messages 兼容 messages、rerank;上游 provider(openai / anthropic / dashscope / theta)连接、模型清单、健康检查、网关子密钥与平台试用 provider 绑定。
服务与资源边界
LLM Gateway API(/v1/llm-gateway/*)是项目内统一托管大模型供应商凭证(如展示项目配置的阿里云百炼 dashscope-prod)并提供标准化模型推理的数据面与管理面接口:
多协议推理数据面:原生提供 OpenAI 兼容的
/chat/completions(如调用qwen-plus、qwen-turbo、qwen-vl-max)与/embeddings(如调用 1024 维text-embedding-v3)、Anthropic 兼容的/messages、以及 RAG 检索专用的/rerank(如调用qwen3.7-text-rerank)。Provider 托管与预置目录:内置 24 家主流模型厂商预置目录(
/provider-presets)、DashScope 可用模型自动发现与分类(/provider-model-discoveries)、模型级健康探针、网关子密钥(Keys)配额控制以及平台试用模型绑定。
资源与基础路径
Base URL:
https://<your-endpoint>/v1,路径前缀/llm-gateway。资源:
provider({providerId},项目内connectionName唯一)、key({keyId},网关子密钥)、trialProviderBinding({bindingId})。与 ai-gateway 并存:本服务面向 LLM 推理/Embedding/重排;AI Gateway 提供 MCP、A2A 和 HTTP Agent 等工具入口。
认证与权限
认证与请求头约定见 通用约定。scope 四类:
llm-gateway.execute:数据面(chat / messages / embeddings / rerank / models);llm-gateway.providers.read/llm-gateway.providers.write:provider、健康、模型发现、试用绑定管理;llm-gateway.keys.read/llm-gateway.keys.write:网关子密钥管理。
数据面限流独立于普通管理面:chat / messages / rerank 每分钟 60 次,embeddings 每分钟 120 次。provider 开启 allowByok 时,调用方可带 X-Provider-Key 头自带上游 API Key(BYOK)。
端点总览
LLM Gateway 共提供 26 个端点,分为:模型推理与向量/重排数据面(6 个)、Provider 凭证 CRUD 与健康检查/模型发现/预置目录(10 个)、网关子密钥管理(4 个)以及平台试用 Provider 绑定管理(6 个)。
端点清单
| 方法 + 路径 | 用途 |
|---|---|
POST /llm-gateway/chat/completions | Chat Completions(OpenAI 兼容) |
POST /llm-gateway/messages | Messages(Anthropic 兼容) |
POST /llm-gateway/embeddings | 文本向量化 |
POST /llm-gateway/rerank | 文档重排 |
GET /llm-gateway/models / GET .../models/{modelId} | 可用模型列表/详情 |
GET|POST /llm-gateway/providers、GET|PATCH|DELETE .../providers/{providerId} | provider CRUD |
GET .../providers/{providerId}/health | provider 健康 |
POST .../providers/{providerId}/health-checks | 校验 provider 全部已配模型 |
GET .../providers/{providerId}/models | 上游实际可用模型 |
POST .../providers/cache/refresh | 刷新 provider 缓存 |
POST /llm-gateway/provider-model-discoveries | 发现并分类 DashScope 凭证可用模型 |
GET /llm-gateway/provider-presets | 厂商预置模型目录(2.9.0:24 厂商 / 313 模型,含 Base URL 与按模型参数) |
GET|POST /llm-gateway/keys、PATCH|DELETE .../keys/{keyId} | 网关子密钥管理 |
GET|POST /llm-gateway/trial-provider-bindings、GET|DELETE .../trial-provider-bindings/{bindingId}、POST .../{bindingId}/health-checks | 平台试用 provider 绑定与绑定健康检查 |
GET /llm-gateway/trial-providers | 可绑定的平台试用 provider 清单 |
端点详解
内部服务联动标识:项目内的知识库(Embedding / Rerank / Wiki / GraphRAG)、记忆系统(抽取 / 画像 / 蒸馏)与智能体工作台均通过
project:<providerId>(如project:dashscope-prod)或trial:<bindingId>引用本模块托管的模型连接。流式与非流式双模:
/chat/completions与/messages支持stream: true返回标准text/event-streamSSE 增量分片,并在流结束时自动将输入/输出 Token 归集至项目、模型与子密钥三级计量账本。
请求与响应
以下按端点给出完整规格:输入(path / query / body 字段级表格)、输出(返回模型与关键字段)、调用示例(可复制的 curl)与响应示例。标注「泛化 schema any」的端点,响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准。
数据面
POST /v1/llm-gateway/chat/completions
以 OpenAI Chat Completions 兼容格式创建对话补全:网关按请求体 model 路由到活跃 Provider,透传原生消息字段,记录项目 / 模型 / 网关子密钥三级用量。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
model | body | string | 是 | — | 用于补全的模型 ID,必须与某活跃 Provider 的模型清单精确匹配(不支持 provider/model 前缀)。 |
messages | body | object[] | 是 | — | 上游原生对话消息数组,字段原样透传:文本、多模态(content 为分段数组)与 tool-calling(role: tool、tool_calls)均支持。 |
temperature | body | number | 否 | — | 采样温度,0–2,缺省用上游默认值。 |
maxTokens | body | integer | 否 | — | 最大生成 token 数。 |
stream | body | boolean | 否 | — | 是否以 SSE 流式返回;true 时响应为 text/event-stream 分片(chat.completion.chunk)。 |
tools | body | object[] | 否 | — | OpenAI 兼容的工具定义数组(type: function + function.{name,parameters}),透传给上游。 |
tool_choice | body | object | 否 | — | 工具选择策略:"auto" / "none" 或 {"type":"function","function":{"name":"..."}} 强制指定。 |
输出:返回上游原生补全(经网关透传):非流式为完整 chat.completion JSON(含 choices[].message 与 usage 计量字段);stream=true 时为 SSE 分片序列。用量按 UTC 日归集到项目 / 模型 / 子密钥三级。
Provider 未就绪或模型无可用路由时返回
404+llm_gateway_model_not_found/llm_gateway_provider_not_found;上游全部失败时网关返回上游错误并附 provider 归因。数据面限流独立于管理面:本端点 60 次/分钟,超限返回
429+llm_gateway_rate_limit_exceeded。用网关子密钥认证且
allowedModels不含请求模型时返回403+GENERAL_ACCESS_FORBIDDEN;子密钥认证时无需X-Appwrite-Project(密钥内嵌项目)。Provider 开启
allowByok时可加-H "X-Provider-Key: <上游密钥>"自带上游 API Key。
调用示例:
curl -X POST "https://<your-endpoint>/v1/llm-gateway/chat/completions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [
{ "role": "system", "content": "你是一个简洁的中文助手。" },
{ "role": "user", "content": "用一句话介绍 TablesDB。" }
],
"temperature": 0.7,
"maxTokens": 1024,
"stream": false
}'
# 流式:将 stream 设为 true,响应为 SSE(data: {"choices":[{"delta":{...}}]} 分片,以 data: [DONE] 结束)响应示例:
{
"id": "chatcmpl-8f2a9c1d",
"object": "chat.completion",
"created": 1757491200,
"model": "gpt-4o-mini",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "TablesDB 是 Agentbase 提供的结构化表格存储服务,支持行级权限与事务。"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 28,
"completion_tokens": 33,
"total_tokens": 61
}
}POST /v1/llm-gateway/messages
以 Anthropic Messages 兼容格式创建消息:路由时优先选择 anthropic 类型 Provider,必要时回退通用模型路由,返回 Anthropic Messages 结构。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
model | body | string | 是 | — | 目标模型 ID;anthropic 模型优先路由到 anthropic Provider。 |
messages | body | object[] | 是 | — | Anthropic 原生消息数组(role: user|assistant,content 为字符串或分段数组),原样透传。 |
maxTokens | body | integer | 是 | — | 最大生成 token 数,必填;不传时网关按 1024 处理。 |
system | body | string | 否 | — | 系统提示词;网关将其前插为 system 消息后再透传。 |
temperature | body | number | 否 | — | 采样温度,0–1。 |
stream | body | boolean | 否 | — | 是否以 SSE 流式返回分片。 |
输出:返回 Anthropic Messages 兼容结构:content[](type: text 等分段)、stop_reason、usage(input_tokens / output_tokens);流式时为 SSE 分片。
与 chat/completions 同一套路由、BYOK(
X-Provider-Key)与子密钥allowedModels校验;限流 60 次/分钟。网关子密钥不含请求模型时返回
403+GENERAL_ACCESS_FORBIDDEN。
调用示例:
curl -X POST "https://<your-endpoint>/v1/llm-gateway/messages" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-3-5-sonnet-20241022",
"maxTokens": 1024,
"system": "你是客服质检助手,只输出 JSON。",
"messages": [
{ "role": "user", "content": "检查这条回复是否包含承诺赔付的表述。" }
],
"temperature": 0.5,
"stream": false
}'
# Gateway Key 认证:Authorization: Bearer abk_... (可省略 X-Appwrite-Project)响应示例:
{
"id": "msg_01XFDUDYJgAACzvnptvVoaEL",
"type": "message",
"role": "assistant",
"model": "claude-3-5-sonnet-20241022",
"content": [
{
"type": "text",
"text": "{\"contains_compensation\": false, \"confidence\": 0.92}"
}
],
"stop_reason": "end_turn",
"usage": {
"input_tokens": 42,
"output_tokens": 28
}
}POST /v1/llm-gateway/embeddings
对一批文本生成向量:按 embedding 模型 ID 路由到活跃 Provider,返回 OpenAI 兼容的向量数组与 token 用量。不支持流式。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
model | body | string | 是 | — | embedding 模型 ID,须在 Provider 的 embeddingModels 中。 |
input | body | string[] | 是 | — | 输入文本数组,每个元素生成一条向量;结果 data[].index 与数组顺序对应。 |
输出:返回 llmGatewayEmbeddingResponse:
| 字段 | 类型 | 说明 |
|---|---|---|
object | string | 对象类型,恒为 list(OpenAI 兼容字段)。 |
model | string | 实际生成向量的模型。 |
data | object[] | 向量对象数组,每项含 object、index 与 embedding 浮点数组,顺序与 input 一一对应。 |
usage | object | token 用量:prompt_tokens / total_tokens。 |
限流 120 次/分钟(高于 chat/messages/rerank 的 60 次/分钟)。
上游模型支持时可附带
dimensions控制维度,但须与下游 VectorsDB collection 维度一致,否则写入向量时对不上。作为 Memory / 知识库 embedding 配置引用的模型,修改 Provider 前先看
memoryEmbeddingReferenced/immutableFields。
调用示例:
curl -X POST "https://<your-endpoint>/v1/llm-gateway/embeddings" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"model": "text-embedding-3-small",
"input": [
"Agentbase 是一个 BaaS 平台",
"TablesDB 提供结构化数据存储"
]
}'响应示例:
{
"object": "list",
"model": "text-embedding-3-small",
"data": [
{
"object": "embedding",
"index": 0,
"embedding": [
0.0023,
-0.0091,
0.0154
]
},
{
"object": "embedding",
"index": 1,
"embedding": [
0.0031,
-0.0087,
0.0149
]
}
],
"usage": {
"prompt_tokens": 24,
"total_tokens": 24
}
}POST /v1/llm-gateway/rerank
按查询相关性对候选文档重排:返回按相关性降序的输入下标与得分,可选携带文档原文。不支持流式。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
model | body | string | 是 | — | rerank 模型 ID,须在 Provider 的 rerankModels 中。 |
query | body | string | 是 | — | 用于相关性判定的查询文本。 |
documents | body | string[] | 是 | — | 候选文档文本数组;返回结果中的 index 指向该数组的下标。 |
topN | body | integer | 否 | — | 只返回前 N 条结果。 |
returnDocuments | body | boolean | 否 | — | 是否在结果中附带文档原文(document 字段)。 |
输出:返回 llmGatewayRerankResponse:
| 字段 | 类型 | 说明 |
|---|---|---|
model | string | 执行重排的模型。 |
results | object[] | 按相关性降序的结果数组,每项含 index(输入 documents 下标)与 relevance_score(0–1);returnDocuments=true 时附带 document 原文。 |
usage | object | token 用量:total_tokens。 |
知识库检索(如 rerankProviderRef)复用本能力;平台试用 Provider 以
trial:<bindingId>形式参与路由。限流 60 次/分钟;BYOK 与子密钥
allowedModels校验同 chat。
调用示例:
curl -X POST "https://<your-endpoint>/v1/llm-gateway/rerank" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"model": "gte-rerank",
"query": "如何创建 Agentbase 用户",
"documents": [
"使用 Account API 创建邮箱密码用户。",
"TablesDB 提供结构化数据存储。"
],
"topN": 2,
"returnDocuments": false
}'响应示例:
{
"model": "gte-rerank",
"results": [
{
"index": 0,
"relevance_score": 0.97
},
{
"index": 1,
"relevance_score": 0.31
}
],
"usage": {
"total_tokens": 45
}
}GET /v1/llm-gateway/models
列出项目内当前可路由的全部模型:对各活跃 Provider 的 chatModels / embeddingModels / rerankModels / vlmModels 汇总去重。
输入:无 path/query/body 参数。
输出:返回 llmGatewayModelList(total + models[]),数组元素为 llmGatewayModel:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 模型 ID(即请求体 model 需要精确匹配的值)。 |
object | string | 对象类型,恒为 model(OpenAI 兼容字段)。 |
created | integer | 上游模型创建时间(Unix 秒)。 |
ownedBy | string | 归属 Provider(类型或连接标识)。 |
capabilities | string[] | 支持能力:chat / embedding / rerank / vlm。 |
active | boolean | 当前是否可路由(Provider 须为 active)。 |
source | string,可选 | 模型来源:project(项目 Provider)/ platformTrial(平台试用)/ mixed。 |
sources | object[],可选 | 来源安全投影列表。 |
trialQuota | object,可选 | 存在平台试用来源时,账号-模型维度的试用配额。 |
数据面端点,scope 为
llm-gateway.execute;Provider 管理类模型发现则用GET .../providers/{providerId}/models(providers.read)。source=platformTrial时关注trialQuota:试用额度与账号级配额联动。
调用示例:
curl "https://<your-endpoint>/v1/llm-gateway/models" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 2,
"models": [
{
"$id": "gpt-4o-mini",
"object": "model",
"created": 1721174400,
"ownedBy": "openai",
"capabilities": [
"chat"
],
"active": true,
"source": "project",
"sources": [
"project"
]
},
{
"$id": "gte-rerank",
"object": "model",
"created": 1719043200,
"ownedBy": "dashscope",
"capabilities": [
"rerank"
],
"active": true,
"source": "platformTrial",
"sources": [
"platformTrial"
],
"trialQuota": {
"remainingTokens": 480000
}
}
]
}GET /v1/llm-gateway/models/{modelId}
读取单个可用模型详情;模型必须被某个活跃 Provider 显式声明或经通配路由命中。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
modelId | path | string | 是 | — | 模型 ID,与列表端点返回的 $id 一致。 |
输出:返回 llmGatewayModel:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 模型 ID(即请求体 model 需要精确匹配的值)。 |
object | string | 对象类型,恒为 model(OpenAI 兼容字段)。 |
created | integer | 上游模型创建时间(Unix 秒)。 |
ownedBy | string | 归属 Provider(类型或连接标识)。 |
capabilities | string[] | 支持能力:chat / embedding / rerank / vlm。 |
active | boolean | 当前是否可路由(Provider 须为 active)。 |
source | string,可选 | 模型来源:project(项目 Provider)/ platformTrial(平台试用)/ mixed。 |
sources | object[],可选 | 来源安全投影列表。 |
trialQuota | object,可选 | 存在平台试用来源时,账号-模型维度的试用配额。 |
调用示例:
curl "https://<your-endpoint>/v1/llm-gateway/models/gpt-4o-mini" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "gpt-4o-mini",
"object": "model",
"created": 1721174400,
"ownedBy": "openai",
"capabilities": [
"chat"
],
"active": true,
"source": "project",
"sources": [
"project"
]
}Provider 管理
GET /v1/llm-gateway/providers
列出项目内全部 Provider 连接:按路由优先级排序,用于检视已配置上游、模型清单、状态与健康度。
输入:无 path/query/body 参数。
输出:返回 llmGatewayProviderList(total + providers[]),元素为 llmGatewayProvider:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | Provider ID。 |
$createdAt | string | 创建时间(ISO 8601)。 |
$updatedAt | string | 最近更新时间(ISO 8601)。 |
connectionName | string | 连接名,项目内唯一。 |
providerType | string | 上游类型:openai / anthropic / dashscope / theta。 |
baseUrl | string | 上游 API base URL。 |
apiKeySet | boolean | 是否已配置上游密钥;响应永不回显 apiKey 本体。 |
defaultModel | string | 该连接的默认模型。 |
allowedCapabilities | string[] | 放行能力:chat / embedding / rerank / vlm(由各模型清单派生)。 |
supportedModels | string[] | 兼容字段:全部支持模型 ID 的汇总(服务端派生)。 |
chatModels | string[] | 可用于 chat completions 的模型 ID。 |
embeddingModels | string[] | 可用于 embeddings 的模型 ID。 |
rerankModels | string[] | 可用于 rerank 的模型 ID。 |
vlmModels | string[] | 可用于视觉理解的模型 ID(复用 chat completions 端点)。 |
description | string | 连接描述。 |
status | string | 运行状态:active / paused。 |
isDefault | boolean | 是否为同类型默认 Provider。 |
priority | integer | failover 优先级,数值越小越优先。 |
timeoutMs | integer | 上游请求超时(毫秒)。 |
maxRetries | integer | 最大重试次数。 |
maxInputTokens | integer | 最大输入 token;null 表示不限。 |
allowByok | boolean | 是否允许调用方经 X-Provider-Key 头自带上游密钥(BYOK)。 |
healthStatus | string | 健康状态:HEALTHY / UNHEALTHY / UNKNOWN。 |
healthMessage | string | 最近一次模型校验失败的摘要。 |
lastValidatedAt | string | 最近一次健康校验时间。 |
lastUsedAt | string | 最近一次被路由使用的时间。 |
memoryEmbeddingReferenced | boolean | 是否已被项目 Memory embedding 配置引用;null 表示本次响应未评估约束。 |
immutableFields | string[] | 被 Memory 引用期间不可修改的字段列表。 |
deleteAllowed | boolean | 当前是否允许删除;null 表示未评估。 |
credentialPolicy | string | 凭据变更策略:mutable / rotate-only;空表示未评估。 |
调用示例:
curl "https://<your-endpoint>/v1/llm-gateway/providers" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 1,
"providers": [
{
"$id": "openai-prod",
"$createdAt": "2026-08-01T03:12:45.231+00:00",
"$updatedAt": "2026-08-01T03:12:45.231+00:00",
"connectionName": "openai-production",
"providerType": "openai",
"baseUrl": "https://api.openai.com",
"apiKeySet": true,
"defaultModel": "gpt-4o-mini",
"allowedCapabilities": [
"chat",
"embedding"
],
"supportedModels": [
"gpt-4o-mini",
"text-embedding-3-small"
],
"chatModels": [
"gpt-4o-mini"
],
"embeddingModels": [
"text-embedding-3-small"
],
"rerankModels": [],
"vlmModels": [],
"description": "生产 OpenAI 连接",
"status": "active",
"isDefault": true,
"priority": 0,
"timeoutMs": 60000,
"maxRetries": 3,
"maxInputTokens": 128000,
"allowByok": false,
"healthStatus": "HEALTHY",
"healthMessage": "",
"lastValidatedAt": "2026-08-01T03:13:02.884+00:00",
"lastUsedAt": "2026-09-01T08:00:11.102+00:00",
"memoryEmbeddingReferenced": false,
"immutableFields": [],
"deleteAllowed": true,
"credentialPolicy": "mutable"
}
]
}POST /v1/llm-gateway/providers
创建 Provider 连接:推荐用四个能力模型清单声明各能力可用模型,服务端派生 allowedCapabilities 与兼容字段 supportedModels,保存前逐一验证全部模型。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerId | body | string | 是 | — | Provider ID,自定义或 ID.unique()。 |
connectionName | body | string | 是 | — | 连接名,项目内唯一,重复创建返回 409。 |
providerType | body | string | 是 | 枚举 openai, anthropic, dashscope, theta | 上游类型枚举:openai / anthropic / dashscope / theta。 |
baseUrl | body | string | 是 | — | 上游 API base URL,须为合法 HTTP(S) 地址。 |
apiKey | body | string | 否 | — | 上游密钥或令牌;加密存储,任何读取端点只回显 apiKeySet,不返回原文。 |
defaultModel | body | string | 否 | — | 该连接的默认模型。 |
allowedCapabilities | body | string[] | 否 | — | 放行能力数组;通常不传,由四个模型清单派生。 |
supportedModels | body | string[] | 否 | — | 兼容旧客户端的字段;与四个清单同传时以清单派生结果为准。不接受 * 通配符。 |
chatModels | body | string[] | 否 | — | chat 能力模型清单;VLM 复用 chat completions 端点,视觉模型登记在 vlmModels。 |
embeddingModels | body | string[] | 否 | — | embedding 能力模型清单。 |
rerankModels | body | string[] | 否 | — | rerank 能力模型清单。 |
vlmModels | body | string[] | 否 | — | 视觉语言模型清单。 |
chatCompletionsPath | body | string | 否 | — | 上游 chat completions 路径覆盖,默认 /v1/chat/completions。 |
embeddingsPath | body | string | 否 | — | 上游 embeddings 路径覆盖,默认 /v1/embeddings。 |
rerankPath | body | string | 否 | — | 上游 rerank 路径覆盖;留空表示该 Provider 不支持 rerank。 |
description | body | string | 否 | — | Provider 连接描述。 |
isDefault | body | boolean | 否 | — | 设为同类型默认 Provider。 |
isActive | body | boolean | 否 | — | 创建后是否立即参与路由。 |
timeoutMs | body | integer | 否 | — | 上游请求超时(毫秒)。 |
maxRetries | body | integer | 否 | — | 最大重试次数。 |
priority | body | integer | 否 | — | failover 优先级,越小越优先;主 Provider 失败时按升序尝试。 |
maxInputTokens | body | integer | 否 | — | 最大输入 token;null 不限。 |
allowByok | body | boolean | 否 | — | 允许调用方经 X-Provider-Key 头自带上游密钥。 |
输出:返回 201 + llmGatewayProvider:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | Provider ID。 |
$createdAt | string | 创建时间(ISO 8601)。 |
$updatedAt | string | 最近更新时间(ISO 8601)。 |
connectionName | string | 连接名,项目内唯一。 |
providerType | string | 上游类型:openai / anthropic / dashscope / theta。 |
baseUrl | string | 上游 API base URL。 |
apiKeySet | boolean | 是否已配置上游密钥;响应永不回显 apiKey 本体。 |
defaultModel | string | 该连接的默认模型。 |
allowedCapabilities | string[] | 放行能力:chat / embedding / rerank / vlm(由各模型清单派生)。 |
supportedModels | string[] | 兼容字段:全部支持模型 ID 的汇总(服务端派生)。 |
chatModels | string[] | 可用于 chat completions 的模型 ID。 |
embeddingModels | string[] | 可用于 embeddings 的模型 ID。 |
rerankModels | string[] | 可用于 rerank 的模型 ID。 |
vlmModels | string[] | 可用于视觉理解的模型 ID(复用 chat completions 端点)。 |
description | string | 连接描述。 |
status | string | 运行状态:active / paused。 |
isDefault | boolean | 是否为同类型默认 Provider。 |
priority | integer | failover 优先级,数值越小越优先。 |
timeoutMs | integer | 上游请求超时(毫秒)。 |
maxRetries | integer | 最大重试次数。 |
maxInputTokens | integer | 最大输入 token;null 表示不限。 |
allowByok | boolean | 是否允许调用方经 X-Provider-Key 头自带上游密钥(BYOK)。 |
healthStatus | string | 健康状态:HEALTHY / UNHEALTHY / UNKNOWN。 |
healthMessage | string | 最近一次模型校验失败的摘要。 |
lastValidatedAt | string | 最近一次健康校验时间。 |
lastUsedAt | string | 最近一次被路由使用的时间。 |
memoryEmbeddingReferenced | boolean | 是否已被项目 Memory embedding 配置引用;null 表示本次响应未评估约束。 |
immutableFields | string[] | 被 Memory 引用期间不可修改的字段列表。 |
deleteAllowed | boolean | 当前是否允许删除;null 表示未评估。 |
credentialPolicy | string | 凭据变更策略:mutable / rotate-only;空表示未评估。 |
模型清单必须是可枚举的具体模型 ID:保存前会逐个实测验证,含通配符或不存在的模型会导致创建失败。
创建后调用
POST .../providers/cache/refresh可让当前 Worker 的路由缓存立即生效。
调用示例:
curl -X POST "https://<your-endpoint>/v1/llm-gateway/providers" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"providerId": "openai-prod",
"connectionName": "openai-production",
"providerType": "openai",
"baseUrl": "https://api.openai.com",
"apiKey": "sk-xxxxxxxxxxxxxxxx",
"defaultModel": "gpt-4o-mini",
"chatModels": ["gpt-4o-mini"],
"embeddingModels": ["text-embedding-3-small"],
"priority": 0,
"timeoutMs": 60000,
"maxRetries": 3,
"isActive": true,
"description": "生产 OpenAI 连接"
}'响应示例:
{
"$id": "openai-prod",
"$createdAt": "2026-08-01T03:12:45.231+00:00",
"$updatedAt": "2026-08-01T03:12:45.231+00:00",
"connectionName": "openai-production",
"providerType": "openai",
"baseUrl": "https://api.openai.com",
"apiKeySet": true,
"defaultModel": "gpt-4o-mini",
"allowedCapabilities": [
"chat",
"embedding"
],
"supportedModels": [
"gpt-4o-mini",
"text-embedding-3-small"
],
"chatModels": [
"gpt-4o-mini"
],
"embeddingModels": [
"text-embedding-3-small"
],
"rerankModels": [],
"vlmModels": [],
"description": "生产 OpenAI 连接",
"status": "active",
"isDefault": true,
"priority": 0,
"timeoutMs": 60000,
"maxRetries": 3,
"maxInputTokens": 128000,
"allowByok": false,
"healthStatus": "HEALTHY",
"healthMessage": "",
"lastValidatedAt": "2026-08-01T03:13:02.884+00:00",
"lastUsedAt": "2026-09-01T08:00:11.102+00:00",
"memoryEmbeddingReferenced": false,
"immutableFields": [],
"deleteAllowed": true,
"credentialPolicy": "mutable"
}GET /v1/llm-gateway/providers/{providerId}
按 ID 读取单个 Provider:返回路由配置与健康元数据,永不暴露上游密钥原文。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerId | path | string | 是 | — | Provider ID。 |
输出:返回 llmGatewayProvider:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | Provider ID。 |
$createdAt | string | 创建时间(ISO 8601)。 |
$updatedAt | string | 最近更新时间(ISO 8601)。 |
connectionName | string | 连接名,项目内唯一。 |
providerType | string | 上游类型:openai / anthropic / dashscope / theta。 |
baseUrl | string | 上游 API base URL。 |
apiKeySet | boolean | 是否已配置上游密钥;响应永不回显 apiKey 本体。 |
defaultModel | string | 该连接的默认模型。 |
allowedCapabilities | string[] | 放行能力:chat / embedding / rerank / vlm(由各模型清单派生)。 |
supportedModels | string[] | 兼容字段:全部支持模型 ID 的汇总(服务端派生)。 |
chatModels | string[] | 可用于 chat completions 的模型 ID。 |
embeddingModels | string[] | 可用于 embeddings 的模型 ID。 |
rerankModels | string[] | 可用于 rerank 的模型 ID。 |
vlmModels | string[] | 可用于视觉理解的模型 ID(复用 chat completions 端点)。 |
description | string | 连接描述。 |
status | string | 运行状态:active / paused。 |
isDefault | boolean | 是否为同类型默认 Provider。 |
priority | integer | failover 优先级,数值越小越优先。 |
timeoutMs | integer | 上游请求超时(毫秒)。 |
maxRetries | integer | 最大重试次数。 |
maxInputTokens | integer | 最大输入 token;null 表示不限。 |
allowByok | boolean | 是否允许调用方经 X-Provider-Key 头自带上游密钥(BYOK)。 |
healthStatus | string | 健康状态:HEALTHY / UNHEALTHY / UNKNOWN。 |
healthMessage | string | 最近一次模型校验失败的摘要。 |
lastValidatedAt | string | 最近一次健康校验时间。 |
lastUsedAt | string | 最近一次被路由使用的时间。 |
memoryEmbeddingReferenced | boolean | 是否已被项目 Memory embedding 配置引用;null 表示本次响应未评估约束。 |
immutableFields | string[] | 被 Memory 引用期间不可修改的字段列表。 |
deleteAllowed | boolean | 当前是否允许删除;null 表示未评估。 |
credentialPolicy | string | 凭据变更策略:mutable / rotate-only;空表示未评估。 |
调用示例:
curl "https://<your-endpoint>/v1/llm-gateway/providers/openai-prod" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "openai-prod",
"$createdAt": "2026-08-01T03:12:45.231+00:00",
"$updatedAt": "2026-08-01T03:12:45.231+00:00",
"connectionName": "openai-production",
"providerType": "openai",
"baseUrl": "https://api.openai.com",
"apiKeySet": true,
"defaultModel": "gpt-4o-mini",
"allowedCapabilities": [
"chat",
"embedding"
],
"supportedModels": [
"gpt-4o-mini",
"text-embedding-3-small"
],
"chatModels": [
"gpt-4o-mini"
],
"embeddingModels": [
"text-embedding-3-small"
],
"rerankModels": [],
"vlmModels": [],
"description": "生产 OpenAI 连接",
"status": "active",
"isDefault": true,
"priority": 0,
"timeoutMs": 60000,
"maxRetries": 3,
"maxInputTokens": 128000,
"allowByok": false,
"healthStatus": "HEALTHY",
"healthMessage": "",
"lastValidatedAt": "2026-08-01T03:13:02.884+00:00",
"lastUsedAt": "2026-09-01T08:00:11.102+00:00",
"memoryEmbeddingReferenced": false,
"immutableFields": [],
"deleteAllowed": true,
"credentialPolicy": "mutable"
}PATCH /v1/llm-gateway/providers/{providerId}
更新 Provider:仅修改显式传入的字段;能力模型清单可单独更新,服务端重新派生 allowedCapabilities 与 supportedModels。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerId | path | string | 是 | — | Provider ID。 |
connectionName | body | string | 否 | — | 连接名(唯一性校验同创建)。 |
providerType | body | string | 否 | 枚举 openai, anthropic, dashscope, theta | 上游类型;仅改类型时保留显式自定义路径,若 rerankPath 为旧类型内置默认值则迁移为新类型默认。 |
baseUrl | body | string | 否 | — | 上游 base URL。 |
apiKey | body | string | 否 | — | 传空字符串清除已存密钥;省略字段保持现有密钥不变。 |
defaultModel | body | string | 否 | — | 默认模型。 |
allowedCapabilities | body | string[] | 否 | — | 兼容字段,一般不直接传。 |
supportedModels | body | string[] | 否 | — | 仅传旧字段时沿用旧版兼容语义。 |
chatModels | body | string[] | 否 | — | 单独更新 chat 清单时,其他三个能力清单保持不变。 |
embeddingModels | body | string[] | 否 | — | 单独更新 embedding 清单。 |
rerankModels | body | string[] | 否 | — | 单独更新 rerank 清单。 |
vlmModels | body | string[] | 否 | — | 单独更新 VLM 清单。 |
chatCompletionsPath | body | string | 否 | — | chat completions 路径覆盖。 |
embeddingsPath | body | string | 否 | — | embeddings 路径覆盖。 |
rerankPath | body | string | 否 | — | rerank 路径覆盖。 |
description | body | string | 否 | — | 连接描述。 |
isDefault | body | boolean | 否 | — | 设为同类型默认。 |
isActive | body | boolean | 否 | — | false 使 Provider 退出路由。 |
timeoutMs | body | integer | 否 | — | 上游超时(毫秒)。 |
maxRetries | body | integer | 否 | — | 最大重试次数。 |
priority | body | integer | 否 | — | failover 优先级。 |
maxInputTokens | body | integer | 否 | — | 最大输入 token。 |
allowByok | body | boolean | 否 | — | 是否允许 BYOK。 |
输出:返回更新后的 llmGatewayProvider:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | Provider ID。 |
$createdAt | string | 创建时间(ISO 8601)。 |
$updatedAt | string | 最近更新时间(ISO 8601)。 |
connectionName | string | 连接名,项目内唯一。 |
providerType | string | 上游类型:openai / anthropic / dashscope / theta。 |
baseUrl | string | 上游 API base URL。 |
apiKeySet | boolean | 是否已配置上游密钥;响应永不回显 apiKey 本体。 |
defaultModel | string | 该连接的默认模型。 |
allowedCapabilities | string[] | 放行能力:chat / embedding / rerank / vlm(由各模型清单派生)。 |
supportedModels | string[] | 兼容字段:全部支持模型 ID 的汇总(服务端派生)。 |
chatModels | string[] | 可用于 chat completions 的模型 ID。 |
embeddingModels | string[] | 可用于 embeddings 的模型 ID。 |
rerankModels | string[] | 可用于 rerank 的模型 ID。 |
vlmModels | string[] | 可用于视觉理解的模型 ID(复用 chat completions 端点)。 |
description | string | 连接描述。 |
status | string | 运行状态:active / paused。 |
isDefault | boolean | 是否为同类型默认 Provider。 |
priority | integer | failover 优先级,数值越小越优先。 |
timeoutMs | integer | 上游请求超时(毫秒)。 |
maxRetries | integer | 最大重试次数。 |
maxInputTokens | integer | 最大输入 token;null 表示不限。 |
allowByok | boolean | 是否允许调用方经 X-Provider-Key 头自带上游密钥(BYOK)。 |
healthStatus | string | 健康状态:HEALTHY / UNHEALTHY / UNKNOWN。 |
healthMessage | string | 最近一次模型校验失败的摘要。 |
lastValidatedAt | string | 最近一次健康校验时间。 |
lastUsedAt | string | 最近一次被路由使用的时间。 |
memoryEmbeddingReferenced | boolean | 是否已被项目 Memory embedding 配置引用;null 表示本次响应未评估约束。 |
immutableFields | string[] | 被 Memory 引用期间不可修改的字段列表。 |
deleteAllowed | boolean | 当前是否允许删除;null 表示未评估。 |
credentialPolicy | string | 凭据变更策略:mutable / rotate-only;空表示未评估。 |
被 Memory embedding 配置引用时受
immutableFields限制;credentialPolicy=rotate-only时只允许轮换凭据,删除前检查deleteAllowed。批量变更后调用
POST .../providers/cache/refresh立即刷新路由缓存。
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/llm-gateway/providers/openai-prod" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"priority": 10,
"timeoutMs": 30000,
"maxRetries": 2
}'响应示例:
{
"$id": "openai-prod",
"$createdAt": "2026-08-01T03:12:45.231+00:00",
"$updatedAt": "2026-08-01T03:12:45.231+00:00",
"connectionName": "openai-production",
"providerType": "openai",
"baseUrl": "https://api.openai.com",
"apiKeySet": true,
"defaultModel": "gpt-4o-mini",
"allowedCapabilities": [
"chat",
"embedding"
],
"supportedModels": [
"gpt-4o-mini",
"text-embedding-3-small"
],
"chatModels": [
"gpt-4o-mini"
],
"embeddingModels": [
"text-embedding-3-small"
],
"rerankModels": [],
"vlmModels": [],
"description": "生产 OpenAI 连接",
"status": "active",
"isDefault": true,
"priority": 0,
"timeoutMs": 60000,
"maxRetries": 3,
"maxInputTokens": 128000,
"allowByok": false,
"healthStatus": "HEALTHY",
"healthMessage": "",
"lastValidatedAt": "2026-08-01T03:13:02.884+00:00",
"lastUsedAt": "2026-09-01T08:00:11.102+00:00",
"memoryEmbeddingReferenced": false,
"immutableFields": [],
"deleteAllowed": true,
"credentialPolicy": "mutable"
}DELETE /v1/llm-gateway/providers/{providerId}
删除 Provider 连接:从路由中移除,之后不再承接该项目的模型请求。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerId | path | string | 是 | — | Provider ID。 |
输出:204 No Content,无响应体。
Memory embedding 配置引用中的 Provider:
deleteAllowed=false时先调整 Memory 配置再删除。
调用示例:
curl -X DELETE "https://<your-endpoint>/v1/llm-gateway/providers/openai-prod" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:204 No Content:无响应体(删除成功)。
GET /v1/llm-gateway/providers/{providerId}/health
对 Provider 全部 (能力, 模型) 组合执行实时校验并更新健康状态;兼容接口,仍返回最新 Provider 对象。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerId | path | string | 是 | — | Provider ID。 |
输出:返回携带最新健康状态的 llmGatewayProvider(关注 healthStatus / healthMessage / lastValidatedAt):
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | Provider ID。 |
$createdAt | string | 创建时间(ISO 8601)。 |
$updatedAt | string | 最近更新时间(ISO 8601)。 |
connectionName | string | 连接名,项目内唯一。 |
providerType | string | 上游类型:openai / anthropic / dashscope / theta。 |
baseUrl | string | 上游 API base URL。 |
apiKeySet | boolean | 是否已配置上游密钥;响应永不回显 apiKey 本体。 |
defaultModel | string | 该连接的默认模型。 |
allowedCapabilities | string[] | 放行能力:chat / embedding / rerank / vlm(由各模型清单派生)。 |
supportedModels | string[] | 兼容字段:全部支持模型 ID 的汇总(服务端派生)。 |
chatModels | string[] | 可用于 chat completions 的模型 ID。 |
embeddingModels | string[] | 可用于 embeddings 的模型 ID。 |
rerankModels | string[] | 可用于 rerank 的模型 ID。 |
vlmModels | string[] | 可用于视觉理解的模型 ID(复用 chat completions 端点)。 |
description | string | 连接描述。 |
status | string | 运行状态:active / paused。 |
isDefault | boolean | 是否为同类型默认 Provider。 |
priority | integer | failover 优先级,数值越小越优先。 |
timeoutMs | integer | 上游请求超时(毫秒)。 |
maxRetries | integer | 最大重试次数。 |
maxInputTokens | integer | 最大输入 token;null 表示不限。 |
allowByok | boolean | 是否允许调用方经 X-Provider-Key 头自带上游密钥(BYOK)。 |
healthStatus | string | 健康状态:HEALTHY / UNHEALTHY / UNKNOWN。 |
healthMessage | string | 最近一次模型校验失败的摘要。 |
lastValidatedAt | string | 最近一次健康校验时间。 |
lastUsedAt | string | 最近一次被路由使用的时间。 |
memoryEmbeddingReferenced | boolean | 是否已被项目 Memory embedding 配置引用;null 表示本次响应未评估约束。 |
immutableFields | string[] | 被 Memory 引用期间不可修改的字段列表。 |
deleteAllowed | boolean | 当前是否允许删除;null 表示未评估。 |
credentialPolicy | string | 凭据变更策略:mutable / rotate-only;空表示未评估。 |
会真实访问外部上游:单模型探测最多等 10 秒,整批最多 30 秒;全部模型校验成功才置
HEALTHY。需要逐模型结果时改用
POST .../providers/{providerId}/health-checks。
调用示例:
curl "https://<your-endpoint>/v1/llm-gateway/providers/openai-prod/health" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "openai-prod",
"$createdAt": "2026-08-01T03:12:45.231+00:00",
"$updatedAt": "2026-08-01T03:12:45.231+00:00",
"connectionName": "openai-production",
"providerType": "openai",
"baseUrl": "https://api.openai.com",
"apiKeySet": true,
"defaultModel": "gpt-4o-mini",
"allowedCapabilities": [
"chat",
"embedding"
],
"supportedModels": [
"gpt-4o-mini",
"text-embedding-3-small"
],
"chatModels": [
"gpt-4o-mini"
],
"embeddingModels": [
"text-embedding-3-small"
],
"rerankModels": [],
"vlmModels": [],
"description": "生产 OpenAI 连接",
"status": "active",
"isDefault": true,
"priority": 0,
"timeoutMs": 60000,
"maxRetries": 3,
"maxInputTokens": 128000,
"allowByok": false,
"healthStatus": "UNHEALTHY",
"healthMessage": "Model validation failed: 1 invalid, 0 unavailable, 0 skipped.",
"lastValidatedAt": "2026-09-14T02:00:11.400+00:00",
"lastUsedAt": "2026-09-01T08:00:11.102+00:00",
"memoryEmbeddingReferenced": false,
"immutableFields": [],
"deleteAllowed": true,
"credentialPolicy": "mutable"
}POST /v1/llm-gateway/providers/{providerId}/health-checks
对 Provider 已配置的全部模型做统一合法性校验,返回 Provider、汇总统计与逐模型结果;以 sparse update 方式回写健康字段。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerId | path | string | 是 | — | Provider ID。 |
输出:返回 llmGatewayProviderHealthCheck:
| 字段 | 类型 | 说明 |
|---|---|---|
provider | object | 携带最新持久化健康状态的 Provider 对象(字段同 llmGatewayProvider,见 Provider 管理小节,此处不重复列出)。 |
summary | object | 校验汇总(字段见下)。 |
summary.total | integer | 校验结果总数。 |
summary.valid | integer | 校验通过数量。 |
summary.invalid | integer | 校验失败(配置非法)数量。 |
summary.unavailable | integer | 上游暂不可用数量。 |
summary.skipped | integer | 跳过数量。 |
summary.durationMs | integer | 整批校验总耗时(毫秒)。 |
results | llmGatewayProviderValidationResult[] | 逐 (capability, model) 校验结果(字段见下)。 |
results[].capability | string | 该校验针对的能力。 |
results[].model | string | 被校验的模型 ID。 |
results[].status | string | 结果:valid / invalid / unavailable / skipped。 |
results[].code | string | 稳定机器可读结果码(如 ok)。 |
results[].retryable | boolean | 不做配置变更、稍后重试是否可能成功。 |
results[].latencyMs | integer | 单次探测耗时(毫秒)。 |
响应不含上游正文或凭据;
results[].retryable=true表示稍后重试可能成功,无需改配置。回写字段:
healthStatus、healthMessage、lastHealthCheck。
调用示例:
curl -X POST "https://<your-endpoint>/v1/llm-gateway/providers/openai-prod/health-checks" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"provider": {
"$id": "openai-prod",
"$createdAt": "2026-08-01T03:12:45.231+00:00",
"$updatedAt": "2026-08-01T03:12:45.231+00:00",
"connectionName": "openai-production",
"providerType": "openai",
"baseUrl": "https://api.openai.com",
"apiKeySet": true,
"defaultModel": "gpt-4o-mini",
"allowedCapabilities": [
"chat",
"embedding"
],
"supportedModels": [
"gpt-4o-mini",
"text-embedding-3-small"
],
"chatModels": [
"gpt-4o-mini"
],
"embeddingModels": [
"text-embedding-3-small"
],
"rerankModels": [],
"vlmModels": [],
"description": "生产 OpenAI 连接",
"status": "active",
"isDefault": true,
"priority": 0,
"timeoutMs": 60000,
"maxRetries": 3,
"maxInputTokens": 128000,
"allowByok": false,
"healthStatus": "HEALTHY",
"healthMessage": "",
"lastValidatedAt": "2026-08-01T03:13:02.884+00:00",
"lastUsedAt": "2026-09-01T08:00:11.102+00:00",
"memoryEmbeddingReferenced": false,
"immutableFields": [],
"deleteAllowed": true,
"credentialPolicy": "mutable"
},
"summary": {
"total": 2,
"valid": 1,
"invalid": 1,
"unavailable": 0,
"skipped": 0,
"durationMs": 256
},
"results": [
{
"capability": "chat",
"model": "gpt-4o-mini",
"status": "valid",
"code": "ok",
"retryable": false,
"latencyMs": 128
},
{
"capability": "embedding",
"model": "text-embedding-3-small",
"status": "invalid",
"code": "model_not_allowed",
"retryable": false,
"latencyMs": 94
}
]
}GET /v1/llm-gateway/providers/{providerId}/models
直接从上游拉取实际可用模型清单(模型发现):当前面向 dashscope Provider;其他兼容类型需手工维护模型清单。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerId | path | string | 是 | — | Provider ID。 |
输出:返回纯 ID 形态 { "models": string[], "total": number }(不是 llmGatewayModel 对象数组)。
scope 为
llm-gateway.providers.read,比数据面llm-gateway.execute更窄。发现结果可作为
POST /llm-gateway/provider-model-discoveries之外的轻量探测;两者都不自动改写 Provider 配置。
调用示例:
curl "https://<your-endpoint>/v1/llm-gateway/providers/openai-prod/models" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"models": [
"qwen-plus",
"qwen-max",
"text-embedding-v3"
],
"total": 3
}POST /v1/llm-gateway/providers/cache/refresh
强制重载当前项目在内存中的 Provider 路由缓存:批量变更 Provider 后让新路由快照在当前 Worker 立即生效。
输入:无 path/query/body 参数。
输出:204 No Content,无响应体。
调用示例:
curl -X POST "https://<your-endpoint>/v1/llm-gateway/providers/cache/refresh" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:204 No Content:无响应体(缓存已刷新)。
POST /v1/llm-gateway/provider-model-discoveries
用百炼 DashScope 凭证拉取账号可用模型,并按内置模型目录预分类为 Chat / Embedding / Rerank / VLM,供创建或编辑 Provider 时取用。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerId | body | string | 否 | — | 已有 Provider ID;编辑语境使用,复用已保存凭证。 |
providerType | body | string | 否 | 枚举 openai, anthropic, dashscope, theta | 创建语境使用(无 providerId 时必填),枚举同 Provider。 |
baseUrl | body | string | 否 | — | 非空时覆盖已存 Provider 的 base URL。 |
apiKey | body | string | 否 | — | 非空时覆盖已存 Provider 的密钥。 |
输出:返回发现结果:按 chat / embedding / rerank / vlm 预分类的模型清单与未分类预览。
未分类模型不会被自动归入 Chat;暂不支持的图片、音视频、语音与多模态 embedding 模型仅在预览中展示,不自动写入 Provider。
providerId与providerType二选一:编辑已有 Provider 用前者,新建语境用后者。
调用示例:
curl -X POST "https://<your-endpoint>/v1/llm-gateway/provider-model-discoveries" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"providerType": "dashscope",
"baseUrl": "https://dashscope.aliyuncs.com/compatible-mode",
"apiKey": "sk-xxxxxxxxxxxxxxxx"
}'响应示例:响应为发现结果 JSON(按能力预分类的模型清单 + 未分类预览,字段以实际响应为准):仅作预览,不自动写入任何 Provider。
GET /v1/llm-gateway/provider-presets(2.9.0 新增)
厂商预置模型目录:返回内置厂商预设清单(24 个厂商、313 个预置模型)与每个模型的按模型参数(上下文窗口、最大输出、Embedding 维度与输入上限、工具调用、多模态 Embedding),供创建 / 编辑 Provider 时选择厂商预设并导入模型清单。
输入:无 path/query/body 参数。
输出:返回 llmGatewayProviderPresetList(total + presets[]),元素为 llmGatewayProviderPreset:
| 字段 | 类型 | 说明 |
|---|---|---|
providerType | string | 预设对应的 Provider 类型(如 volcengine、openai-official、openai-compatible、ollama 等)。 |
name / description | string | 厂商展示名与说明。 |
baseUrl | string | 预设固定的上游 Base URL。 |
models | array | 预置模型清单(llmGatewayProviderPresetModel:模型 ID、能力标注与按模型参数 metadata)。 |
手动配置时仍只指定协议类型;选中预设后 Base URL 与模型清单可直接带入
POST /llm-gateway/providers。
调用示例:
curl "https://<your-endpoint>/v1/llm-gateway/provider-presets" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 24,
"presets": [
{
"providerType": "volcengine",
"name": "火山方舟(豆包)",
"baseUrl": "https://ark.cn-beijing.volces.com/api/v3",
"models": [
{
"model": "doubao-seed-2-1-pro-260915",
"capabilities": ["chat", "vlm"],
"metadata": { "contextWindow": 262144 }
}
]
}
]
}网关子密钥
GET /v1/llm-gateway/keys
列出当前项目的网关子密钥:永不返回明文,用 keyPrefix、名称、启停、过期时间与最近使用时间识别密钥。
输入:无 path/query/body 参数。
输出:返回 llmGatewayKeyList(total + keys[]),元素为 llmGatewayKey(其中 key 明文恒为空/不回显):
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | Key ID。 |
$createdAt | string | 创建时间(ISO 8601)。 |
$updatedAt | string | 最近更新时间(ISO 8601)。 |
key | string | 完整明文密钥(abk_ 前缀),仅在创建响应中出现一次,之后任何读取端点都不再返回。 |
keyPrefix | string | 密钥展示前缀(非敏感),用于在列表中识别密钥。 |
name | string | 密钥名称。 |
description | string | 密钥描述。 |
allowedModels | string[] | 允许调用的模型 ID 白名单;["*"] 表示放行全部模型。 |
monthlyTokenBudget | integer | 月度 token 预算;null 表示不限。按三级用量 UTC 日归集数据滚动累计,耗尽后该密钥的请求被拒。 |
monthlyTokensUsed | integer | 当前计费周期已消耗 token 数。 |
budgetResetAt | string | 下一个月度预算重置时间。 |
rateLimit | integer | 每分钟请求上限;null 使用项目级默认限流。 |
isActive | boolean | 是否启用;false 时该密钥立即不可用。 |
expiresAt | string | 过期时间(ISO 8601);null 表示永不过期。 |
lastUsedAt | string | 最近一次使用时间。 |
调用示例:
curl "https://<your-endpoint>/v1/llm-gateway/keys" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 1,
"keys": [
{
"$id": "key_mobile_chat",
"$createdAt": "2026-08-12T09:20:00.000+00:00",
"$updatedAt": "2026-08-12T09:20:00.000+00:00",
"key": "",
"keyPrefix": "abk_proj6789_aB3xK9",
"name": "mobile-app-chat",
"description": "移动端聊天功能专用",
"allowedModels": [
"gpt-4o-mini"
],
"monthlyTokenBudget": 1000000,
"monthlyTokensUsed": 45230,
"budgetResetAt": "2026-09-01T00:00:00.000+00:00",
"rateLimit": 60,
"isActive": true,
"expiresAt": null,
"lastUsedAt": "2026-09-10T14:02:33.000+00:00"
}
]
}POST /v1/llm-gateway/keys
签发网关子密钥:面向下游应用的受限凭据,只能调用数据面端点,受 allowedModels / 预算 / 限流 / 有效期约束。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
keyId | body | string | 是 | — | 子密钥 ID,自定义或 ID.unique()。 |
name | body | string | 是 | — | 密钥名称。 |
description | body | string | 否 | — | 密钥描述。 |
allowedModels | body | string[] | 否 | — | 模型白名单;["*"] 放行全部。请求模型不在白名单时数据面返回 403。 |
monthlyTokenBudget | body | integer | 否 | — | 月度 token 预算;null 不限。耗尽后该密钥请求被拒,直到下次重置。 |
rateLimit | body | integer | 否 | — | 每分钟请求上限;null 使用全局默认。 |
expiresAt | body | string | 否 | — | 过期时间(ISO 8601);null 永不过期。 |
输出:返回 201 + llmGatewayKey,仅此次响应包含明文 key(abk_ 前缀),之后只能看到 keyPrefix:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | Key ID。 |
$createdAt | string | 创建时间(ISO 8601)。 |
$updatedAt | string | 最近更新时间(ISO 8601)。 |
key | string | 完整明文密钥(abk_ 前缀),仅在创建响应中出现一次,之后任何读取端点都不再返回。 |
keyPrefix | string | 密钥展示前缀(非敏感),用于在列表中识别密钥。 |
name | string | 密钥名称。 |
description | string | 密钥描述。 |
allowedModels | string[] | 允许调用的模型 ID 白名单;["*"] 表示放行全部模型。 |
monthlyTokenBudget | integer | 月度 token 预算;null 表示不限。按三级用量 UTC 日归集数据滚动累计,耗尽后该密钥的请求被拒。 |
monthlyTokensUsed | integer | 当前计费周期已消耗 token 数。 |
budgetResetAt | string | 下一个月度预算重置时间。 |
rateLimit | integer | 每分钟请求上限;null 使用项目级默认限流。 |
isActive | boolean | 是否启用;false 时该密钥立即不可用。 |
expiresAt | string | 过期时间(ISO 8601);null 表示永不过期。 |
lastUsedAt | string | 最近一次使用时间。 |
子密钥不能管理 Provider / 密钥 / 用量统计,只能访问执行类端点。
子密钥认证调用数据面时无需
X-Appwrite-Project(密钥内嵌项目 ID)。
调用示例:
curl -X POST "https://<your-endpoint>/v1/llm-gateway/keys" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"keyId": "key_mobile_chat",
"name": "mobile-app-chat",
"description": "移动端聊天功能专用",
"allowedModels": ["gpt-4o-mini"],
"monthlyTokenBudget": 1000000,
"rateLimit": 60,
"expiresAt": null
}'响应示例:
{
"$id": "key_mobile_chat",
"$createdAt": "2026-08-12T09:20:00.000+00:00",
"$updatedAt": "2026-08-12T09:20:00.000+00:00",
"key": "abk_proj6789_aB3xK9mN2pQ7wR4tY8vF1jH5cE0iU6oL3sA9bD2gX7zW4nM",
"keyPrefix": "abk_proj6789_aB3xK9",
"name": "mobile-app-chat",
"description": "移动端聊天功能专用",
"allowedModels": [
"gpt-4o-mini"
],
"monthlyTokenBudget": 1000000,
"monthlyTokensUsed": 45230,
"budgetResetAt": "2026-09-01T00:00:00.000+00:00",
"rateLimit": 60,
"isActive": true,
"expiresAt": null,
"lastUsedAt": "2026-09-10T14:02:33.000+00:00"
}PATCH /v1/llm-gateway/keys/{keyId}
更新子密钥:改名、调整模型白名单、限流、预算、启停或过期时间;仅修改显式传入的字段。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
keyId | path | string | 是 | — | 子密钥 ID。 |
name | body | string | 否 | — | 密钥名称。 |
description | body | string | 否 | — | 密钥描述。 |
allowedModels | body | string[] | 否 | — | 模型白名单。 |
monthlyTokenBudget | body | integer | 否 | — | 月度 token 预算。 |
rateLimit | body | integer | 否 | — | 每分钟请求上限。 |
isActive | body | boolean | 否 | — | false 立即禁用。 |
expiresAt | body | string | 否 | — | 过期时间(ISO 8601)。 |
输出:返回更新后的 llmGatewayKey:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | Key ID。 |
$createdAt | string | 创建时间(ISO 8601)。 |
$updatedAt | string | 最近更新时间(ISO 8601)。 |
key | string | 完整明文密钥(abk_ 前缀),仅在创建响应中出现一次,之后任何读取端点都不再返回。 |
keyPrefix | string | 密钥展示前缀(非敏感),用于在列表中识别密钥。 |
name | string | 密钥名称。 |
description | string | 密钥描述。 |
allowedModels | string[] | 允许调用的模型 ID 白名单;["*"] 表示放行全部模型。 |
monthlyTokenBudget | integer | 月度 token 预算;null 表示不限。按三级用量 UTC 日归集数据滚动累计,耗尽后该密钥的请求被拒。 |
monthlyTokensUsed | integer | 当前计费周期已消耗 token 数。 |
budgetResetAt | string | 下一个月度预算重置时间。 |
rateLimit | integer | 每分钟请求上限;null 使用项目级默认限流。 |
isActive | boolean | 是否启用;false 时该密钥立即不可用。 |
expiresAt | string | 过期时间(ISO 8601);null 表示永不过期。 |
lastUsedAt | string | 最近一次使用时间。 |
rateLimit、monthlyTokenBudget、expiresAt一旦设置过就不能清回未设置状态:传null或省略都保持现值。
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/llm-gateway/keys/key_mobile_chat" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"rateLimit": 30,
"isActive": false
}'响应示例:
{
"$id": "key_mobile_chat",
"$createdAt": "2026-08-12T09:20:00.000+00:00",
"$updatedAt": "2026-09-14T02:10:00.000+00:00",
"key": "abk_proj6789_aB3xK9mN2pQ7wR4tY8vF1jH5cE0iU6oL3sA9bD2gX7zW4nM",
"keyPrefix": "abk_proj6789_aB3xK9",
"name": "mobile-app-chat",
"description": "移动端聊天功能专用",
"allowedModels": [
"gpt-4o-mini"
],
"monthlyTokenBudget": 1000000,
"monthlyTokensUsed": 45230,
"budgetResetAt": "2026-09-01T00:00:00.000+00:00",
"rateLimit": 30,
"isActive": false,
"expiresAt": null,
"lastUsedAt": "2026-09-10T14:02:33.000+00:00"
}DELETE /v1/llm-gateway/keys/{keyId}
永久删除子密钥(硬删除,不经过软吊销):文档立即移除,密钥随即无法调用执行端点。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
keyId | path | string | 是 | — | 子密钥 ID。 |
输出:204 No Content,无响应体。
调用示例:
curl -X DELETE "https://<your-endpoint>/v1/llm-gateway/keys/key_mobile_chat" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:204 No Content:无响应体(密钥已吊销)。
试用 Provider 绑定
GET /v1/llm-gateway/trial-providers
列出平台提供的可绑定试用 Provider 清单:绑定前先在此确认平台 provider ID 与试用额度。
输入:无 path/query/body 参数。
输出:返回试用 provider 清单(泛化 schema any:元素含平台 provider ID、能力与试用额度信息,字段以实际响应为准)。
调用示例:
curl "https://<your-endpoint>/v1/llm-gateway/trial-providers" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:响应为试用 provider 数组文档(泛化 schema,字段以实际响应为准);把其中的平台 provider ID 用于创建绑定。
GET /v1/llm-gateway/trial-provider-bindings
列出当前项目生效的平台试用 Provider 绑定。
输入:无 path/query/body 参数。
输出:返回绑定列表(泛化 schema any:每条含 bindingId、平台 provider 与项目关联、额度状态等信息,字段以实际响应为准)。
绑定后的 Provider 在模型路由中以
trial:<bindingId>形式出现(如知识库 rerank 的rerankProviderRef)。
调用示例:
curl "https://<your-endpoint>/v1/llm-gateway/trial-provider-bindings" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:响应为绑定数组文档(泛化 schema,字段以实际响应为准)。
POST /v1/llm-gateway/trial-provider-bindings
把一个平台试用 Provider 绑定到账号名下项目:绑定成功(201)后以 trial:<bindingId> 参与模型路由。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerId | body | string | 是 | — | 平台 provider ID(来自 GET /llm-gateway/trial-providers)。 |
输出:返回 201 + 绑定对象(泛化 schema any,字段以实际响应为准)。
试用额度与账号级配额联动;同一账号的额度在多项目间共享。
调用示例:
curl -X POST "https://<your-endpoint>/v1/llm-gateway/trial-provider-bindings" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{ "providerId": "trial-dashscope-gte-rerank" }'响应示例:201:响应为绑定对象 JSON(泛化 schema,字段以实际响应为准),记下 bindingId 供后续端点使用。
GET /v1/llm-gateway/trial-provider-bindings/{bindingId}
读取单个试用 Provider 绑定的详情与额度状态。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
bindingId | path | string | 是 | — | 试用绑定 ID。 |
输出:返回绑定对象(泛化 schema any,字段以实际响应为准)。
调用示例:
curl "https://<your-endpoint>/v1/llm-gateway/trial-provider-bindings/<BINDING_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:响应为绑定对象 JSON(泛化 schema,字段以实际响应为准)。
DELETE /v1/llm-gateway/trial-provider-bindings/{bindingId}
解除试用 Provider 绑定:trial:<bindingId> 路由随即失效。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
bindingId | path | string | 是 | — | 试用绑定 ID。 |
输出:204 No Content,无响应体。
调用示例:
curl -X DELETE "https://<your-endpoint>/v1/llm-gateway/trial-provider-bindings/<BINDING_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:204 No Content:无响应体(已解绑)。
POST /v1/llm-gateway/trial-provider-bindings/{bindingId}/health-checks
对绑定的平台试用 Provider 实测可用性:验证凭证、网络与模型通路。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
bindingId | path | string | 是 | — | 试用绑定 ID。 |
输出:返回实测结果(泛化 schema any:含健康状态与逐模型校验信息,字段以实际响应为准)。
调用示例:
curl -X POST "https://<your-endpoint>/v1/llm-gateway/trial-provider-bindings/<BINDING_ID>/health-checks" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:响应为健康检查结果 JSON(泛化 schema,字段以实际响应为准)。
错误与边界
模型不存在或无可用 provider:
404+llm_gateway_model_not_found/llm_gateway_provider_not_found;上游全部失败:网关返回上游错误并附 provider 归因。数据面限流独立(chat/messages/rerank 60 次/分、embeddings 120 次/分):超限返回
429+llm_gateway_rate_limit_exceeded;子密钥另有自身rateLimit。子密钥
monthlyTokenBudget耗尽:请求被拒且密钥内不再放行;预算按三级用量 UTC 日归集数据滚动累计。allowedModels未包含请求模型:即使上游可用也被拒;supportedModels不接受通配符,逐个校验后保存。apiKey仅创建/更新时写入,任何读取端点不回显;BYOK(X-Provider-Key)仅在allowByok=true时生效。failover 按
priority升序尝试;isActive=false的 provider 不参与路由,isDefault仅在同类型内生效。
与 Server SDK 的对应
| service.method | 端点 |
|---|---|
LLMGateway.createChatCompletion | POST /llm-gateway/chat/completions |
LLMGateway.createMessage | POST /llm-gateway/messages |
LLMGateway.createEmbeddings | POST /llm-gateway/embeddings |
LLMGateway.createRerank | POST /llm-gateway/rerank |
LLMGateway.listModels / getModel | /llm-gateway/models* |
LLMGateway.listProviders / createProvider / getProvider / updateProvider / deleteProvider | /llm-gateway/providers* |
LLMGateway.getProviderHealth / createProviderHealthCheck / listProviderModels / refreshProviderCache | .../health*、.../models、.../cache/refresh |
LLMGateway.createProviderModelDiscovery | POST /llm-gateway/provider-model-discoveries |
LLMGateway.listKeys / createKey / updateKey / deleteKey | /llm-gateway/keys* |
LLMGateway.listTrialProviders / listTrialProviderBindings / createTrialProviderBinding / getTrialProviderBinding / deleteTrialProviderBinding / createTrialProviderBindingHealthCheck | /llm-gateway/trial-provider* |
2.12.0 接口与兼容增量
以下路径相对于 /v1。服务端请求携带 X-Appwrite-Project 与 X-Appwrite-Key;Key 仅留在服务端。Scope 是下表的必要条件;数据集、归属和资源状态还会追加校验。HTTP 202 只表示接受,须使用返回的任务标识查询终态。
| HTTP | Scope | SDK |
|---|---|---|
POST /llm-gateway/rerank | llm-gateway.execute | llmGateway.createRerank |
POST /llm-gateway/rerank
对文档进行重排
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
model | body | 是 | string | — | 重排模型 ID。 |
query | body | 是 | string | — | 用于对文档重排的查询文本。 |
documents | body | 是 | array[string] | — | 待重排的文档。 |
topN | body | 否 | integer | format=int32 | 仅返回前 N 条结果。 |
returnDocuments | body | 否 | boolean | default=false | 响应中包含文档文本。 |
instruct | body | 否 | string | default="" | 可选的原生排序指令,适用于支持该参数的 DashScope 重排模型;为空时不传递。 |
成功响应:HTTP 200 — llmGatewayRerankResponse.
返回字段:model (string), results (array), usage (object).
错误与重试边界
400/422:核对类型、枚举与规则;401/403:核对身份与 Scope,数据集分析还要求 traces.read 和 datasets.read;404:确认资源仍存在且属于当前项目;409:重新读取当前状态后决定是否重试;429:按 Retry-After 等待;5xx 或断网后先读取任务状态。涉及幂等键的写入重试保留同一个键,主动重新执行才换键。删除与清空前确认目标,禁止通过循环重试扩大写入。