跳到主要内容

AI 模型管理

版本提示

自 v5.2.0 起新增此模块。通过 app.aiModel 访问，提供云开发环境下 AI 模型分组的配置、查询、更新与删除能力，支持接入 OpenAI 兼容网关（如 DeepSeek、混元、Moonshot 等）。

AiModelService 围绕 AI 模型分组（AIModelGroup） 进行管理，每个分组包含：

  • GroupName：分组名，自定义分组不允许以 cloudbase 为前缀
  • BaseUrl：模型服务地址（需为 OpenAI 兼容网关）
  • Models：分组下的模型列表（数组，更新时为全量替换）
  • Secret：访问模型服务的密钥，支持 SecretId / SecretKey 或 ApiKey
  • Status：分组状态，1 开启 / 2 关闭
  • Type：分组类型，builtin（云开发内置）/ custom（用户自定义）

初始化​

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  secretId: 'Your SecretId',
  secretKey: 'Your SecretKey',
  envId: 'Your envId'
})

const aiModel = app.aiModel

createAIModel​

1. 接口描述​

接口功能：创建一个自定义 AI 模型配置分组。

接口声明：app.aiModel.createAIModel(options): Promise<CreateAIModelResp>

注意

groupName 不允许以 cloudbase 为前缀，该前缀为系统保留。 云端会对 baseUrl + secret 做联通性校验，请确保填写真实可达的模型服务地址与有效密钥。

2. 输入参数​

字段必填类型说明
groupName是String分组名，不允许以 cloudbase 为前缀
baseUrl否String模型服务地址（OpenAI 兼容网关），示例 https://api.deepseek.com/v1
models否AIModel[]模型列表，见下方 AIModel 字段说明
remark否String分组备注
status否1 | 2模型状态，1 开启，2 关闭
secret否AIModelSecret模型密钥，见下方 AIModelSecret 字段说明
envId否String环境 ID，不传则使用当前环境 ID

AIModel

字段必填类型说明
Model否String模型名，示例 deepseek-chat
EnableMCP否Boolean是否开启 MCP，默认 false
Tags否String[]标签

AIModelSecret

字段必填类型说明
SecretSource否String密钥来源，固定 custom
SecretId否String密钥 ID，与 SecretKey 配对使用
SecretKey否String密钥 Key，与 SecretId 配对使用
ApiKey否StringAPI Key，与 SecretId/SecretKey 二选一

3. 返回结果​

字段类型说明
CountNumber创建数量
RequestIdString请求唯一标识

4. 示例代码​

const res = await app.aiModel.createAIModel({
  groupName: 'custom-deepseek',
  baseUrl: 'https://api.deepseek.com/v1',
  models: [
    { Model: 'deepseek-chat', EnableMCP: false }
  ],
  remark: 'DeepSeek 自定义分组',
  status: 1,
  secret: {
    SecretSource: 'custom',
    ApiKey: 'sk-xxxxxxxxxxxxxxxx'
  }
})

console.log(res.Count, res.RequestId)

updateAIModel​

1. 接口描述​

接口功能：更新已有的 AI 模型配置分组。

接口声明：app.aiModel.updateAIModel(options): Promise<UpdateAIModelResp>

注意

models 字段采用全量替换语义，如需保留原有模型，请在更新时将其一并传入。

2. 输入参数​

字段必填类型说明
groupName是String待更新的分组名
baseUrl否String模型服务地址
models否AIModel[]模型列表，全量替换
remark否String备注
status否1 | 2模型状态，1 开启，2 关闭
secret否AIModelSecret模型密钥
envId否String环境 ID，不传则使用当前环境 ID

AIModel / AIModelSecret 字段定义同 createAIModel。

3. 返回结果​

字段类型说明
CountNumber更新数量
RequestIdString请求唯一标识

4. 示例代码​

const res = await app.aiModel.updateAIModel({
  groupName: 'custom-deepseek',
  models: [
    { Model: 'deepseek-chat', EnableMCP: true },
    { Model: 'deepseek-reasoner', EnableMCP: true }
  ],
  status: 1
})

console.log(res.Count)

deleteAIModel​

1. 接口描述​

接口功能：批量删除 AI 模型配置分组。

接口声明：app.aiModel.deleteAIModel(options): Promise<DeleteAIModelResp>

2. 输入参数​

字段必填类型说明
groupNames是String[]分组名列表，至少 1 项，元素非空字符串
envId否String环境 ID，不传则使用当前环境 ID

3. 返回结果​

字段类型说明
CountNumber成功删除数量
RequestIdString请求唯一标识

4. 示例代码​

const res = await app.aiModel.deleteAIModel({
  groupNames: ['custom-deepseek', 'custom-hunyuan']
})

console.log(res.Count)

describeAIModels​

1. 接口描述​

接口功能：查询当前环境下已配置的 AI 模型分组列表（含内置分组与自定义分组）。

接口声明：app.aiModel.describeAIModels(options?): Promise<DescribeAIModelsResp>

2. 输入参数​

字段必填类型说明
envId否String环境 ID，不传则使用当前环境 ID

3. 返回结果​

字段类型说明
AIModelsAIModelGroup[] | null模型分组列表，可能为 null
RequestIdString请求唯一标识

AIModelGroup

字段类型说明
GroupNameString分组名，如 hunyuan-exp / deepseek / cloudbase / custom-xxx
ModelsAIModel[] | null模型列表
Type'builtin' | 'custom'分组类型
OriginType'builtin' | 'custom'原始分组类型
RemarkString备注
BaseUrlString模型地址
Status1 | 2模型状态，1 开启 / 2 关闭
SecretAIModelSecret | null模型密钥（敏感字段，返回可能脱敏或为 null）
CreateTimeString创建时间，ISO8601 格式
UpdateTimeString更新时间，ISO8601 格式

4. 示例代码​

const res = await app.aiModel.describeAIModels()

for (const group of res.AIModels || []) {
  console.log(group.GroupName, group.Type, group.Status, group.Models?.length)
}

describeManagedAIModelList​

1. 接口描述​

接口功能：查询云开发平台支持的托管类型 AI 模型列表（即由云开发平台统一计费、无需用户自备密钥的模型）。

接口声明：app.aiModel.describeManagedAIModelList(options?): Promise<DescribeManagedAIModelListResp>

2. 输入参数​

字段必填类型说明
envId否String环境 ID，不传则使用当前环境 ID

3. 返回结果​

字段类型说明
ManagedAIModelListManagedAIModelGroup[] | null托管模型分组列表
RequestIdString请求唯一标识

ManagedAIModelGroup

字段类型说明
GroupNameString分组名，示例 cloudbase
ModelsManagedAIModel[] | null模型列表
RemarkString备注

ManagedAIModel

字段类型说明
ModelString模型名，示例 hy3
EnableMCPBoolean是否开启 MCP
ModelSpecManagedAIModelSpec模型规格（上下文长度、Token 限制）
ModelChargingInfoManagedAIModelChargingInfo[]计费信息（按段计费 / 固定计费）

ManagedAIModelSpec

字段类型说明
MaxInputTokenString最大输入 Token，示例 192k
MaxOutputTokenString最大输出 Token，示例 32k
ContextLengthString上下文长度，示例 128k

ManagedAIModelChargingInfo

字段类型说明
Type'Uniform' | 'Tiered'计费类型：固定计费 / 分段计费
NameString分段名称，示例 0-16k
InputPriceString输入 Token 价格
OutputPriceString输出 Token 价格
CachePriceString命中缓存价格
InputOutputUnitString计费单位，示例 千tokens

4. 示例代码​

const res = await app.aiModel.describeManagedAIModelList()

for (const group of res.ManagedAIModelList || []) {
  console.log(group.GroupName, group.Remark)
  for (const model of group.Models || []) {
    console.log('  -', model.Model, model.ModelSpec?.ContextLength)
  }
}