Model-Management SDK

场景介绍

Model-Management SDK提供管理模型提供商、模型服务和模型代理的命令行工具，支持模型提供商和模型服务的创建、查询、更新、删除，以及模型代理的创建、更新、列表查询、批量解绑等功能。

前提条件

• 已开通AgentArts。

• 登录控制台获取AK/SK，详情请参考如何获取华为云AK/SK。

  export HUAWEICLOUD_SDK_AK="your-access-key"
  export HUAWEICLOUD_SDK_SK="your-secret-key"

• 已安装Python，且版本不低于3.10。查看Python版本的命令示例：

  python --version

模型提供商管理

• 创建模型提供商

  def create_model_provider(
      self,
      name: str,
      base_url: str,
      credential_configuration: dict[str, Any],
      network_configuration: dict[str, Any] | None = None,
      description: str | None = None,
      tags: list[dict[str, str]] | None = None
  ) -> RequestResult

  表1 创建模型提供商参数说明

  参数	类型	是否必选	默认值	说明
  name	String	是	-	模型提供商名称
  base_url	String	是	-	模型提供商的默认API基础地址
  credential_configuration	Dict[String, Any]	是	-	凭证配置
  network_configuration	Dict[String, Any]	否	{"network_mode": "public"}	出站网络配置
  description	String	否	-	模型提供商的详细描述
  tags	List[Dict[String, String]]	否	-	资源标签列表

• 查询模型提供商信息

  def get_model_provider(self, model_provider_id: str) -> RequestResult

  表2 查询模型提供商参数说明

  参数	类型	是否必选	说明
  model_provider_id	String	是	要查询的模型提供商的唯一标识符

• 更新指定的模型提供商信息

  def update_model_provider(
      self,
      model_provider_id: str,
      name: str | None = None,
      base_url: str | None = None,
      credential_configuration: dict[str, Any] | None = None,
      network_configuration: dict[str, Any] | None = None,
      description: str | None = None,
      tags: list[dict[str, str]] | None = None
  ) -> RequestResult

  表3 更新模型提供商参数说明

  参数	类型	是否必选	说明
  model_provider_id	String	是	要更新的模型提供商的唯一标识符
  name	String	否	模型提供商名称
  base_url	String	否	模型提供商的默认API基础地址
  credential_configuration	Dict[String, Any]	否	凭证配置
  network_configuration	Dict[String, Any]	否	出站网络配置
  description	String	否	模型提供商的详细描述
  tags	List[Dict[String, String]]	否	资源标签列表

  

  更新操作为增量更新，只传入需要更新的字段，未传入的字段将保持原值不变。如果所有可选参数均为None，将抛出ValueError异常。

• 删除指定的模型提供商信息

  def delete_model_provider(self, model_provider_id: str) -> RequestResult

  表4 删除模型提供商参数说明

  参数	类型	是否必选	说明
  model_provider_id	String	是	要删除的模型提供商的唯一标识符

• 获取模型提供商列表

  def list_model_providers(
      self,
      name: str | None = None,
      model_provider_id: str | None = None,
      tag_key_exists: list[str] | None = None,
      tag_key_matches: list[str] | None = None,
      tag_value_matches: list[str] | None = None,
      tag_match_policy: str | None = None,
      limit: int | None = None,
      offset: int | None = None) -> RequestResult

  表5 获取模型提供商实例列表参数说明

  参数	类型	是否必选	默认值	说明
  name	String	否	-	按名称过滤模型提供商，支持模糊匹配
  model_provider_id	String	否	-	按模型提供商ID过滤，支持多个ID（最多20个），用逗号分隔
  tag_key_exists	List[String]	否	-	按标签键存在过滤（逗号分隔）
  tag_key_matches	List[String]	否	-	按标签键值对过滤-键（逗号分隔）
  tag_value_matches	List[String]	否	-	按标签键值对过滤-值（逗号分隔）
  tag_match_policy	String	否	ALL	标签匹配模式（ALL/ANY）
  limit	Int	否	50	返回结果的最大数量（1-100）
  offset	Int	否	0	返回结果的偏移量

模型服务管理

• 在指定的模型提供商下创建新的模型服务

  def create_model(
      self,
      model_provider_id: str,
      model: str,
      model_service_name: str,
      type_: list[str],
      protocol: str,
      description: str | None = None) -> RequestResult

  表6 创建模型服务参数说明

  参数	类型	是否必选	默认值	说明
  model_provider_id	String	是	-	模型提供商ID
  model	String	是	-	模型名称
  model_service_name	String	是	-	模型服务显示名称
  type_	List[String]	是	-	模型类型，可选值：completions、responses、embeddings、rerank、messages、realtime、token_count
  protocol	String	是	-	API接口协议，可选值：openai、anthropic、maas_v1
  description	String	否	-	模型的详细描述

• 查询指定模型提供商下的特定模型服务信息

  def get_model(self, model_provider_id: str, model_id: str) -> RequestResult

  表7 查询模型服务参数说明

  参数	类型	是否必选	说明
  model_provider_id	String	是	模型服务所属模型提供商的唯一标识符
  model_id	String	是	要查询的模型服务的唯一标识符

• 更新指定模型提供商下的特定模型服务

  def update_model(
      self,
      model_provider_id: str,
      model_id: str,
      model: str | None = None,
      model_service_name: str | None = None,
      type_: list[str] | None = None,
      protocol: str | None = None,
      description: str | None = None) -> RequestResult

  表8 更新模型服务参数信息

  参数	类型	是否必选	说明
  model_provider_id	String	是	模型服务所属模型提供商的唯一标识符
  model_id	String	是	要更新的模型服务的唯一标识符
  model	String	否	模型名称
  model_service_name	String	否	模型服务显示名称
  type_	List[String]	否	模型类型
  protocol	String	否	API接口协议
  description	String	否	模型的详细描述

  

  更新操作为增量更新，只传入需要更新的字段，未传入的字段将保持原值不变。如果所有可选参数均为None，将抛出ValueError异常。

• 删除指定模型提供商下的特定模型服务

  def delete_model(self, model_provider_id: str, model_id: str) -> RequestResult

  表9 删除模型服务参数说明

  参数	类型	是否必选	说明
  model_provider_id	String	是	模型服务所属模型提供商的唯一标识符
  model_id	String	是	要删除的模型服务的唯一标识符

• 查询指定模型提供商下的所有模型服务列表

  def list_models(
      self,
      model_provider_id: str,
      model_service_name: str | None = None,
      model_id: str | None = None,
      limit: int | None = None,
      offset: int | None = None) -> RequestResult

  表10 查询指定模型提供商下的模型服务列表参数说明

  参数	类型	是否必选	默认值	说明
  model_provider_id	String	是	-	要查询模型服务的模型提供商的唯一标识符
  model_service_name	String	否	-	按模型服务显示名称过滤
  model_id	String	否	-	按模型服务ID过滤
  limit	Int	否	50	每页返回的最大结果数量（1~100）
  offset	Int	否	0	返回结果的偏移量

模型代理管理

• 创建模型代理

  def create_model_proxy(
      self,
      custom_model_provider_id: str,
      name: str | None = None,
      description: str | None = None,
      inbound_authorizer_type: str | None = "iam",
      agency_name: str | None = None,
      inbound_authorizer_configuration: dict[str, Any] | None = None,
      agent_gateway_id: str | None = None,
      tags: list[dict[str, str]] | None = None
  ) -> RequestResult

  表11 创建模型代理参数说明

  参数	类型	是否必选	默认值	说明
  custom_model_provider_id	String	是	-	模型提供商ID
  name	String	否	model-proxy-{8个随机字符后缀}	模型代理名称
  description	String	否	-	模型代理的详细描述
  inbound_authorizer_type	String	否	iam	入站认证类型，可选值：iam、api_key
  agency_name	String	否	AgentArtsCoreGateway	委托名称。未提供时，SDK会自动创建名为AgentArtsCoreGateway的委托
  inbound_authorizer_configuration	Dict[String, Any]	否	-	入站认证配置
  agent_gateway_id	String	否	-	AgentGateway ID，关联底层AgentGateway实例
  tags	List[Dict[String, String]]	否	-	资源标签列表

  入站认证配置要求：

  • 当inbound\_authorizer\_type = 'api\_key' 时，必须提供key\_auth配置。
  • 当inbound\_authorizer\_type = 'iam' 时，此字段为空。
  • 如果委托创建失败且未提供agency\_name，将抛出ValueError异常。
• 更新指定的模型代理信息

  def update_model_proxy(
      self,
      gateway_id: str,
      tags: list[dict[str, str]] | None = None
  ) -> RequestResult

  表12 更新模型代理参数说明

  参数	类型	是否必选	说明
  gateway_id	String	是	要更新的模型代理的Gateway唯一标识符
  tags	List[Dict[String, String]]	否	资源标签列表

  

  更新操作为增量更新，只传入需要更新的字段，未传入的字段将保持原值不变。如果tags为None，将抛出ValueError异常。

• 获取模型代理列表

  def list_model_proxies(
      self,
      name: str | None = None,
      gateway_id: str | None = None,
      tag_key_exists: list[str] | None = None,
      tag_key_matches: list[str] | None = None,
      tag_value_matches: list[str] | None = None,
      tag_match_policy: str | None = None,
      limit: int | None = None,
      offset: int | None = None) -> RequestResult

  表13 获取模型代理实例列表参数说明

  参数	类型	是否必选	默认值	说明
  name	String	否	-	按名称过滤模型代理，支持模糊匹配
  gateway_id	String	否	-	按模型代理的Gateway ID过滤，支持多个ID（最多20个），用逗号分隔
  tag_key_exists	List[String]	否	-	按标签键存在过滤（逗号分隔）
  tag_key_matches	List[String]	否	-	按标签键值对过滤-键（逗号分隔）
  tag_value_matches	List[String]	否	-	按标签键值对过滤-值（逗号分隔）
  tag_match_policy	String	否	ALL	标签匹配模式（ALL/ANY）
  limit	Int	否	50	返回结果的最大数量（1~100）
  offset	Int	否	0	返回结果的偏移量

• 批量解绑模型代理

  def batch_disassociate_model_proxies(
      self,
      unbindings: list[dict[str, str]]
  ) -> RequestResult

  表14 批量解绑模型代理参数说明

  参数	类型	是否必选	说明
  unbindings	List[Dict[String, String]]	是	解绑关系列表，每项为{"custom_model_provider_id": "...", "gateway_id": "..."}

配额查询

def list_model_management_quotas(
    self,
    custom_model_provider_id: str | None = None,
    gateway_id: str | None = None) -> RequestResult

参数说明

• 请求参数

  表16 CoreModelProviderCredentialConfiguration

  参数	类型	说明
  provider_configuration	CoreModelProviderCredentialProviderConfiguration	模型提供商的凭证提供者配置

  表17 表17 CoreModelProviderCredentialProviderConfiguration

  参数	类型	说明
  credential_provider_type	String	凭证提供者类型 取值范围： iam: 使用IAM角色 api_key: 使用API密钥
  credential_provider	CoreModelProviderCredentialProvider	凭证提供者配置

  表18 表18 CoreModelProviderCredentialProvider

  参数	类型	说明
  api_key_credential_provider	CoreGatewayApiKeyCredentialProvider	API KEY凭证提供者配置
  iam_credential_provider	CoreGatewayIamCredentialProvider	IAM凭证提供者配置

  表19 表19 CoreGatewayApiKeyCredentialProvider

  参数	类型	说明
  provider_name	String	凭证提供者名称
  credential_location	String	凭证传递位置 取值范围： header：通过HTTP请求头传递API密钥 query：通过URL查询参数传递API密钥
  credential_parameter_name	String	凭证参数名称
  credential_prefix	String	凭证前缀（如 "Bearer "）

  表20 表20 CoreGatewayIamCredentialProvider

  参数	类型	说明
  provider_name	String	凭证提供者名称

  表21 表21 CoreModelProviderOutboundNetworkConfiguration

  参数	类型	说明
  network_mode	String	网络模式。 取值范围： public vpc
  vpc_config	CoreGatewayVpcConfig	VPC网络配置

  表22 表22 CoreGatewayVpcConfig

  参数	类型	说明
  vpc_id	String	VPC ID，VPC网络的唯一标识
  subnet_id	String	子网ID，VPC子网的唯一标识
  security_group_ids	Array	安全组ID列表

  表23 表23 CoreModelProviderTag

  参数	类型	说明
  key	String	标签键。
  value	String	标签值。

  表24 表24 CoreModelProxyAuthorizerConfiguration

  参数	类型	说明
  key_auth	CoreGatewayKeyAuthAuthorizerConfiguration	API密钥认证配置

  表25 表25 CoreGatewayKeyAuthAuthorizerConfiguration

  参数	类型	说明
  api_keys	Array	API 密钥列表

  表26 表26 CoreModelProxyDetails

  参数	类型	说明
  custom_model_provider_id	String	模型提供商ID
  gateway_id	String	模型代理Gateway ID

• 响应参数

  表27 表27 ListCustomModelProvidersResponseBody

  字段	类型	说明
  model_providers	List[CreateCustomModelProviderResponseBody]	模型提供商列表
  size	Integer	当前页返回的模型提供商数量
  total	Integer	模型提供商总数量

  表28 表28 CreateCustomModelProviderResponseBody

  字段	类型	说明
  id	String	模型提供商ID
  name	String	模型提供商名称
  base_url	String	模型提供商的默认API基础地址
  credential_configuration	Object	凭证配置
  network_configuration	Object	出站网络配置
  description	String	模型提供商的详细描述
  tags	Array	资源标签列表。取值范围：数组长度为0~20
  created_at	String	创建时间戳
  updated_at	String	更新时间戳

  表29 表29 ShowCustomModelProviderResponseBody

  字段	类型	说明
  id	String	模型提供商ID
  name	String	模型提供商名称
  base_url	String	模型提供商的默认API基础地址
  credential_configuration	Object	凭证配置
  network_configuration	Object	出站网络配置
  description	String	模型提供商的详细描述
  tags	Array	资源标签列表。取值范围：数组长度为0-20
  gateways	List[ShowCustomModelProviderGatewayDetails]	模型提供商关联的网关列表
  created_at	String	创建时间戳
  updated_at	String	更新时间戳

  表30 表30 ShowCustomModelProviderGatewayDetails

  字段	类型	说明
  id	String	网关的唯一标识符
  name	String	网关名称
  endpoint_url	String	访问网关的URL端点
  inbound_authorizer_type	String	入站认证类型。 取值范围： iam: 使用IAM认证 api_key：使用API Key认证
  workload_identity_urn	String	工作负载标识的统一资源名称
  log_delivery_configuration	Object	日志投递配置
  agent_gateway_id	String	AgentGateway ID，关联底层AgentGateway实例
  description	String	详细描述
  tags	Array	资源标签列表。取值范围：数组长度为0-20

  表31 表31 ListCustomModelProviderModelsResponseBody

  字段	类型	说明
  models	List[CreateCustomModelProviderModelResponseBody]	模型配置列表
  size	Integer	当前页返回的模型配置数量
  total	Integer	模型配置总数

  表32 表32 CreateCustomModelProviderModelResponseBody

  字段	类型	说明
  id	String	模型配置ID
  model	String	模型名称
  model_service_name	String	模型服务显示名称
  type	Array	模型类型列表。取值范围：completions、responses、embeddings、rerank、messages、realtime、token_count
  protocol	String	API接口协议。取值范围：openai、anthropic、maas_v1
  description	String	模型的详细描述
  created_at	String	创建时间戳
  updated_at	String	更新时间戳

  表33 表33 ListModelProxiesResponseBody

  字段	类型	说明
  model_proxies	List[ListModelProxiesItem]	模型代理详情列表
  size	Integer	当前页返回的模型代理数量
  total	Integer	模型代理总数

  表34 表34 ListModelProxiesItem

  字段	类型	说明
  gateway_id	String	模型代理Gateway ID
  name	String	模型代理名称
  description	String	模型代理的详细描述
  endpoint_url	String	访问模型代理的URL端点
  inbound_authorizer_type	String	入站认证类型。 取值范围： iam: 使用IAM认证 api_key：使用API Key认证
  tags	Array	资源标签列表。取值范围：数组长度为0-20
  created_at	String	创建时间戳
  updated_at	String	更新时间戳

  表35 表35 CreateModelProxyResponseBody

  字段	类型	说明
  gateway_id	String	模型代理Gateway ID
  custom_model_provider_id	String	模型提供商ID
  name	String	模型代理名称
  description	String	模型代理的详细描述
  endpoint_url	String	访问模型代理的URL端点
  inbound_authorizer_type	String	入站认证类型 取值范围： iam: 使用IAM认证 api_key：使用API Key认证
  tags	Array	资源标签列表。取值范围：数组长度为0-20
  created_at	String	创建时间戳
  updated_at	String	更新时间戳

  表36 表36 UpdateModelProxyResponseBody

  字段	类型	说明
  gateway_id	String	模型代理Gateway ID
  log_delivery_configuration	Object	日志投递配置
  tags	Array	资源标签列表。取值范围：数组长度为0-20
  created_at	String	创建时间戳
  updated_at	String	更新时间戳

  表37 表37 BatchDisassociateModelProxiesResponseBody

  字段	类型	说明
  success_details	List[CoreModelProxyDetails]	成功详情列表
  failed_details	List[CodeModelProxyFailedItem]	失败详情列表

  表38 表38 CodeModelProxyFailedItem

  字段	类型	说明
  custom_model_provider_id	String	模型提供商ID
  gateway_id	String	模型代理Gateway ID
  failed_reason	String	失败原因

  表39 表39 ListModelManagementQuotasResponseBody

  字段	类型	说明
  quotas	List[ModelManagementQuota]	配额列表
  size	Integer	当前页返回的配额数量
  total	Integer	配额总数

  表40 表40 ModelManagementQuota

  字段	类型	说明
  type	String	配额类型。取值范围： model_providers_count: 模型提供商数量配额 total_model_proxies_count: 模型代理总数量配额 model_proxies_count_per_model_provider: 每个模型提供商关联的模型代理数量配额 models_count_per_model_provider: 每个模型提供商关联的模型数量配额
  min	Integer	最小允许值
  max	Integer	最大允许值
  quota	Integer	当前配置的配额值
  used	Integer	已使用数量（实时计算）

快速入门

1. 创建模型提供商。

   # Client模式
   result = client.create_model_provider(
       name="my-provider",
       base_url="https://example.com/v1",
       credential_configuration={
           "provider_configuration": {
               "credential_provider_type": "api_key",
               "credential_provider": {
                   "api_key_credential_provider": {
                       "provider_name": "my-key",
                       "credential_location": "header"
                   }
               }
           }
       }
   )
   model_provider_id = result.data.get("id")
   
   # CLI模式
   agentarts model-provider create-provider my-provider https://example.com/v1 \
       --credential-configuration '{"provider_configuration": {"credential_provider_type": "api_key", "credential_provider": {"api_key_credential_provider": {"provider_name": "my-key", "credential_location": "header"}}}}'

2. 创建模型服务。

   # Client模式
   model_result = client.create_model(
       model_provider_id=model_provider_id,
       model="qwen2.5-72b",
       model_service_name="my-model",
       type_=["completions"],
       protocol="openai"
   )
   model_id = model_result.data.get("id")
   
   # CLI模式
   agentarts model-provider create-model <model-provider-id> \
       --model qwen2.5-72b \
       --model-service-name my-model \
       --type completions \
       --protocol openai

3. 创建模型代理。

   # Client模式
   proxy_result = client.create_model_proxy(
       custom_model_provider_id=model_provider_id,
       name="my-proxy",
       description="我的模型代理",
       inbound_authorizer_type="iam"
   )
   gateway_id = proxy_result.data.get("gateway_id")
   
   # CLI模式
   agentarts model-provider create-proxy \
       --custom-model-provider-id <model-provider-id> \
       --name my-proxy \
       --description "我的模型代理" \
       --inbound-authorizer-type iam

4. 查询信息。

   # Client模式
   provider_info = client.get_model_provider(model_provider_id)
   model_info = client.get_model(model_provider_id, model_id)
   
   # CLI模式
   agentarts model-provider get-provider <model-provider-id>
   agentarts model-provider get-model <model-provider-id> <model-id>

示例代码

from typing import Optional, List
from agentarts.sdk.model_provider import ModelProviderClient

# 初始化客户端
client = ModelProviderClient()

# 创建模型提供商
result = client.create_model_provider(
    name="production-provider",
    base_url="https://example.com/v1",
    credential_configuration={
        "provider_configuration": {
            "credential_provider_type": "api_key",
            "credential_provider": {
                "api_key_credential_provider": {
                    "provider_name": "my-key",
                    "credential_location": "header"
                }
            }
        }
    },
    network_configuration={"network_mode": "public"},
    description="生产环境模型提供商"
)
model_provider_id = result.data.get("id")
print(f"创建的模型提供商ID: {model_provider_id}")

# 查询模型提供商信息
result = client.get_model_provider(model_provider_id)
provider_info = result.data
print(f"模型提供商状态: {provider_info.get('name')}")

# 更新模型提供商描述
result = client.update_model_provider(
    model_provider_id=model_provider_id,
    description="更新后的模型提供商描述"
)
updated_provider = result.data
print(f"更新后的描述: {updated_provider.get('description')}")

# 在模型提供商下创建模型服务
result = client.create_model(
    model_provider_id=model_provider_id,
    model="qwen2.5-72b",
    model_service_name="my-model",
    type_=["completions"],
    protocol="openai",
    description="生产环境模型服务"
)
model_id = result.data.get("id")
print(f"模型服务创建成功，ID: {model_id}")

# 查询模型服务信息
result = client.get_model(model_provider_id, model_id)
model_info = result.data
print(f"模型服务状态: {model_info.get('model_service_name')}")

# 列出模型提供商下的所有模型服务
result = client.list_models(model_provider_id)
models = result.data
print(f"模型提供商下有 {models.get('total')} 个模型服务")

# 更新模型服务描述
result = client.update_model(
    model_provider_id=model_provider_id,
    model_id=model_id,
    description="更新后的模型服务描述"
)
updated_model = result.data
print(f"更新后的描述: {updated_model.get('description')}")

# 创建模型代理
result = client.create_model_proxy(
    custom_model_provider_id=model_provider_id,
    name="production-proxy",
    description="生产环境模型代理",
    inbound_authorizer_type="iam"
)
gateway_id = result.data.get("gateway_id")
print(f"模型代理创建成功，Gateway ID: {gateway_id}")

# 列出所有模型代理
result = client.list_model_proxies()
proxies = result.data
print(f"共有 {proxies.get('total')} 个模型代理")

# 查询模型管理配额
result = client.list_model_management_quotas()
quotas = result.data
print(f"共有 {quotas.get('total')} 条配额信息")

# 批量解绑模型代理
result = client.batch_disassociate_model_proxies(
    unbindings=[
        {
            "custom_model_provider_id": model_provider_id,
            "gateway_id": gateway_id
        }
    ]
)
print("模型代理已解绑")

# 删除模型服务
client.delete_model(model_provider_id, model_id)
print("模型服务已删除")

# 删除模型提供商
client.delete_model_provider(model_provider_id)
print("模型提供商已删除")