服务提供者

AI 服务提供者用于将可调用的上游服务接入 Beacon，供模型网关路由使用。服务来源包括平台外部的 AI 服务和集群内部的模型部署。

schema 支持 OpenAI、AzureOpenAI、AWSBedrock、GCPVertexAI、Anthropic、Cohere；端点通过 endpointUrl 指定。visibility 是历史 API 字段，表示服务接入类型而非资源可见性：public 表示外部 AI 服务，private 表示集群内部模型部署，缺省为 public。外部服务要求 credential.value 非空，内部服务的凭据可省略。

凭据内容不在详情中返回。PUT credential 轮换凭据成功返回 204。被路由引用的服务删除受到引用检查。

models 为尽力探测；后端不可达时可能返回 200、models=[]、unreachable=true。

方法	路径（产品接口统一前缀 /api/v1）	功能
GET	/ai-service-providers	查询 AI 服务提供者
POST	/ai-service-providers	创建 AI 服务提供者
GET	/ai-service-providers/{id}	获取 AI 服务提供者详情
GET	/ai-service-providers/{id}/models	探测服务端模型列表
PATCH	/ai-service-providers/{id}	更新 AI 服务提供者
DELETE	/ai-service-providers/{id}	删除 AI 服务提供者
PUT	/ai-service-providers/{id}/credential	轮换 AI 服务提供者凭据

查询 AI 服务提供者

功能介绍

查询 AI 服务提供者。结果可同时包含外部 AI 服务和集群内部模型部署。

访问要求：有效 Token；需要对应资源读权限，并受项目、所有者、公共或共享资源规则限制。

URI

GET /api/v1/ai-service-providers

查询参数

参数	类型	必选	描述
page	integer	否	页码，从 1 开始
page_size	integer	否	每页数量；建议显式传入，例如 20；省略时部分列表返回全部

请求消息

无请求体。

响应消息

参数	参数类型	描述
items	array<provider.response>	结果列表
total	integer	匹配总数
page	integer	页码，从 1 开始
page_size	integer	每页数量

请求示例

GET https://{endpoint}/api/v1/ai-service-providers?page=1&page_size=20
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "items": [
    {
      "id": "id-example",
      "name": "示例资源",
      "description": "",
      "status": "ready",
      "projectId": "projectId-example",
      "ownerUserId": "ownerUserId-example",
      "backend": {
        "catalog": "",
        "type": "",
        "id": "id-example"
      },
      "spec": {
        "providerKey": "",
        "schema": "OpenAI",
        "endpoint": "https://service.example.com",
        "credentialRef": "",
        "status": "ready"
      },
      "inUse": true,
      "createdAt": "2026-09-21T00:00:00Z",
      "updatedAt": "2026-09-21T00:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 1
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
500	internal_error	failed to list providers
401	unauthorized	authentication required

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

创建 AI 服务提供者

功能介绍

创建 AI 服务提供者。

访问要求：有效 Token；需要对应资源写权限，并受项目、所有者、公共或共享资源规则限制。

URI

POST /api/v1/ai-service-providers

请求消息

Content-Type: application/json。

参数	参数类型	是否必选	描述
name	string	否	显示名称
schema	string	是	服务协议类型；OpenAI / AzureOpenAI / AWSBedrock / GCPVertexAI / Anthropic / Cohere
visibility	string	否	服务接入类型，public 表示外部 AI 服务，private 表示集群内部模型部署；缺省为 public。该字段不表示资源的可见范围。
endpointUrl	string	是	服务端点 URL；内部服务可根据所选部署自动填充，但请求中仍须提供。
credential	provider.credential	条件必选	外部服务（visibility=public）必选，须提供非空密钥；内部服务（visibility=private）可不设置密钥。
labels	map<string, string>	否	标签键值对

参数	参数类型	是否必选	描述
credential.type	string	条件必选	提供 API Key 凭据时使用 APIKey。
credential.value	string	条件必选	外部服务（visibility=public）的 API Key，不能为空。

部署选择与厂商预设用于生成端点、协议等参数，不作为 deploymentId 或 vendor 字段发送。

响应消息

参数	参数类型	描述
id	string	资源唯一标识
name	string	显示名称
description	string	描述
status	string	资源状态；具体取值见业务规则
projectId	string	所属项目 ID
projectName	string	项目名称；空值时可能省略
domainId	string	所属部门 ID；空值时可能省略
domainName	string	部门名称；空值时可能省略
ownerUserId	string	创建者用户 ID
ownerName	string	创建者名称；空值时可能省略
backend	provider.backendRef	后端资源标识
spec	provider.Spec	资源配置快照
inUse	boolean	是否正被其他资源引用
usedBy	array	引用方信息；空值时可能省略
usedByRoutes	array<provider.routeRef>	引用该服务的路由；空值时可能省略
labels	map<string, string>	标签键值对；空值时可能省略
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339

请求示例

POST https://{endpoint}/api/v1/ai-service-providers
x-keystone-token: <Keystone Token>
Content-Type: application/json

{
  "name": "示例服务",
  "schema": "OpenAI",
  "visibility": "public",
  "endpointUrl": "https://provider.example.com/v1",
  "credential": {
    "type": "APIKey",
    "value": "REPLACE_WITH_PROVIDER_KEY"
  }
}

正常响应示例

HTTP/1.1 201
Content-Type: application/json

{
  "id": "id-example",
  "name": "示例资源",
  "description": "",
  "status": "ready",
  "projectId": "projectId-example",
  "ownerUserId": "ownerUserId-example",
  "backend": {
    "catalog": "",
    "type": "",
    "id": "id-example"
  },
  "spec": {
    "providerKey": "",
    "schema": "OpenAI",
    "endpoint": "https://service.example.com",
    "credentialRef": "",
    "status": "ready"
  },
  "inUse": true,
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:00:00Z"
}

状态码与错误码

成功状态码：201。

HTTP	error	说明
400	invalid_request	malformed JSON body
502	backend_unavailable	kubernetes not configured; cannot project provider
401	unauthorized	missing project-scoped token; re-authenticate with a project scope
409	conflict	详细原因由 message 返回。
500	internal_error	failed to persist provider
403	forbidden	write permission required
404	not_found	provider not found
422	invalid_request	详细原因由 message 返回。

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

获取 AI 服务提供者详情

功能介绍

获取 AI 服务提供者详情。

访问要求：有效 Token；需要对应资源读权限，并受项目、所有者、公共或共享资源规则限制。

URI

GET /api/v1/ai-service-providers/{id}

参数	类型	必选	描述
id	string	是	目标资源 ID

请求消息

无请求体。

响应消息

参数	参数类型	描述
id	string	资源唯一标识
name	string	显示名称
description	string	描述
status	string	资源状态；具体取值见业务规则
projectId	string	所属项目 ID
projectName	string	项目名称；空值时可能省略
domainId	string	所属部门 ID；空值时可能省略
domainName	string	部门名称；空值时可能省略
ownerUserId	string	创建者用户 ID
ownerName	string	创建者名称；空值时可能省略
backend	provider.backendRef	后端资源标识
spec	provider.Spec	资源配置快照
inUse	boolean	是否正被其他资源引用
usedBy	array	引用方信息；空值时可能省略
usedByRoutes	array<provider.routeRef>	引用该服务的路由；空值时可能省略
labels	map<string, string>	标签键值对；空值时可能省略
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339

请求示例

GET https://{endpoint}/api/v1/ai-service-providers/resource-id
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "id": "id-example",
  "name": "示例资源",
  "description": "",
  "status": "ready",
  "projectId": "projectId-example",
  "ownerUserId": "ownerUserId-example",
  "backend": {
    "catalog": "",
    "type": "",
    "id": "id-example"
  },
  "spec": {
    "providerKey": "",
    "schema": "OpenAI",
    "endpoint": "https://service.example.com",
    "credentialRef": "",
    "status": "ready"
  },
  "inUse": true,
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:00:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	authentication required
404	not_found	provider not found
409	conflict	provider already exists
500	internal_error	internal server error

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

探测服务端模型列表

功能介绍

探测服务端模型列表。

访问要求：有效 Token；需要对应资源读权限，并受项目、所有者、公共或共享资源规则限制。

URI

GET /api/v1/ai-service-providers/{id}/models

参数	类型	必选	描述
id	string	是	目标资源 ID

请求消息

无请求体。

响应消息

参数	参数类型	描述
models	array	模型路由列表或模型名称列表，按类型区分
unreachable	boolean / null	是否未能访问后端

请求示例

GET https://{endpoint}/api/v1/ai-service-providers/resource-id/models
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "models": [
    ""
  ],
  "unreachable": false
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	authentication required
404	not_found	provider not found
409	conflict	provider already exists
500	internal_error	internal server error

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

更新 AI 服务提供者

功能介绍

更新 AI 服务提供者。

访问要求：有效 Token；需要对应资源写权限，并受项目、所有者、公共或共享资源规则限制。

URI

PATCH /api/v1/ai-service-providers/{id}

参数	类型	必选	描述
id	string	是	目标资源 ID

请求消息

Content-Type: application/json。

参数	参数类型	是否必选	描述
name	string / null	否	显示名称
schema	string / null	否	服务协议类型；OpenAI / AzureOpenAI / AWSBedrock / GCPVertexAI / Anthropic / Cohere
endpointUrl	string / null	否	服务端点 URL

响应消息

参数	参数类型	描述
id	string	资源唯一标识
name	string	显示名称
description	string	描述
status	string	资源状态；具体取值见业务规则
projectId	string	所属项目 ID
projectName	string	项目名称；空值时可能省略
domainId	string	所属部门 ID；空值时可能省略
domainName	string	部门名称；空值时可能省略
ownerUserId	string	创建者用户 ID
ownerName	string	创建者名称；空值时可能省略
backend	provider.backendRef	后端资源标识
spec	provider.Spec	资源配置快照
inUse	boolean	是否正被其他资源引用
usedBy	array	引用方信息；空值时可能省略
usedByRoutes	array<provider.routeRef>	引用该服务的路由；空值时可能省略
labels	map<string, string>	标签键值对；空值时可能省略
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339

请求示例

PATCH https://{endpoint}/api/v1/ai-service-providers/resource-id
x-keystone-token: <Keystone Token>
Content-Type: application/json

{
  "name": "更新后的名称"
}

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "id": "id-example",
  "name": "示例资源",
  "description": "",
  "status": "ready",
  "projectId": "projectId-example",
  "ownerUserId": "ownerUserId-example",
  "backend": {
    "catalog": "",
    "type": "",
    "id": "id-example"
  },
  "spec": {
    "providerKey": "",
    "schema": "OpenAI",
    "endpoint": "https://service.example.com",
    "credentialRef": "",
    "status": "ready"
  },
  "inUse": true,
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:00:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
400	invalid_request	malformed JSON body
500	internal_error	failed to resolve provider references
409	conflict	详细原因由 message 返回。
403	forbidden	write permission required
401	unauthorized	authentication required
404	not_found	provider not found
422	invalid_request	详细原因由 message 返回。
502	backend_unavailable	kubernetes API unavailable

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

删除 AI 服务提供者

功能介绍

删除 AI 服务提供者。

访问要求：有效 Token；需要对应资源写权限，并受项目、所有者、公共或共享资源规则限制。

URI

DELETE /api/v1/ai-service-providers/{id}

参数	类型	必选	描述
id	string	是	目标资源 ID

请求消息

无请求体。

响应消息

成功返回 204 No Content，无响应体。

请求示例

DELETE https://{endpoint}/api/v1/ai-service-providers/resource-id
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 204 No Content

状态码与错误码

成功状态码：204。

HTTP	error	说明
500	internal_error	failed to resolve provider references
409	conflict	详细原因由 message 返回。
403	forbidden	write permission required
401	unauthorized	authentication required
404	not_found	provider not found
422	invalid_request	详细原因由 message 返回。
502	backend_unavailable	kubernetes API unavailable

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

轮换 AI 服务提供者凭据

功能介绍

轮换 AI 服务提供者凭据。

访问要求：有效 Token；需要对应资源写权限，并受项目、所有者、公共或共享资源规则限制。

URI

PUT /api/v1/ai-service-providers/{id}/credential

参数	类型	必选	描述
id	string	是	目标资源 ID

请求消息

Content-Type: application/json。

参数	参数类型	是否必选	描述
credential	provider.credential	否	访问凭据对象

参数	参数类型	是否必选	描述
credential.type	string	是	凭据类型，APIKey。
credential.value	string	是	新的 API Key，不能为空。

响应消息

成功返回 204 No Content，无响应体。

请求示例

PUT https://{endpoint}/api/v1/ai-service-providers/resource-id/credential
x-keystone-token: <Keystone Token>
Content-Type: application/json

{
  "credential": {
    "type": "APIKey",
    "value": "REPLACE_WITH_PROVIDER_KEY"
  }
}

正常响应示例

HTTP/1.1 204 No Content

状态码与错误码

成功状态码：204。

HTTP	error	说明
400	invalid_request	malformed JSON body
502	backend_unavailable	kubernetes not configured
403	forbidden	write permission required
401	unauthorized	authentication required
404	not_found	provider not found
409	conflict	provider already exists
500	internal_error	internal server error
422	invalid_request	详细原因由 message 返回。

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。