更新时间:2025-07-31 GMT+08:00

调用ModelArts Studio(MaaS)部署的模型服务

在ModelArts Studio大模型即服务平台部署成功的模型服务支持在其他业务环境中调用。本文以我的服务为例,调用部署的模型服务。您也可以调用预置服务-免费服务、预置服务-商用服务或预置服务-自定义接入点。

场景描述

在企业AI应用开发过程中,开发人员通常需要将训练好的模型部署到实际业务环境中。然而,传统方法需要手动配置环境、处理依赖关系、编写部署脚本,整个过程耗时且容易出错,且存在环境复杂、迁移困难、维护成本高、版本更新麻烦等问题。

ModelArts Studio(MaaS)大模型即服务平台提供了一站式解决方案,提供统一的API接口方便业务系统调用,并提供监控和日志功能便于运维管理。

计费说明

在调用模型推理服务的过程中,输入内容首先会被分词(tokenize),转换为模型可识别的Token。在调用MaaS预置服务时,将根据实际使用的Tokens数量进行计费。计费详情请参见计费说明

前提条件

“在线推理”页面的“我的服务”页签,服务列表存在运行中、更新中或升级中的模型服务。具体操作,请参见使用ModelArts Studio(MaaS)部署模型服务

步骤一:获取API Key

在调用MaaS部署的模型服务时,需要填写API Key用于接口的鉴权认证。最多可创建30个密钥。每个密钥仅在创建时显示一次,请确保妥善保存。如果密钥丢失,无法找回,需要重新创建API Key以获取新的访问密钥。更多信息,请参见在ModelArts Studio(MaaS)管理API Key

  1. 登录ModelArts Studio(MaaS)控制台,在顶部导航栏选择目标区域。
  2. 在左侧导航栏,单击“API Key管理”
  3. “API Key管理”页面,单击“创建API Key”,填写标签和描述信息后,单击“确定”

    标签和描述信息在创建完成后,不支持修改。

    表1 创建API Key参数说明

    参数

    说明

    标签

    自定义API Key的标签。标签具有唯一性,不可重复。仅支持大小写英文字母、数字、下划线、中划线,长度范围为1~100个字符。

    描述

    自定义API Key的描述,长度范围为1~100个字符。

  4. “您的密钥”对话框,复制密钥并保存至安全位置。
  5. 保存完毕后,单击“关闭”

    单击“关闭”后将无法再次查看密钥。

步骤二:调用MaaS模型服务进行预测

  1. ModelArts Studio(MaaS)控制台左侧导航栏,选择“在线推理”
  2. “在线推理”页面“我的服务”页签,在目标服务右侧,单击操作列的“更多 > 调用说明”
  3. “调用说明”页面,选择接口类型,复制调用示例,修改接口信息和API Key后用于业务环境调用模型服务API。

    Rest API、OpenAI SDK的示例代码如下。

    • 使用普通requests包调用。
      import requests
      import json
      
      if __name__ == '__main__':
          url = "https:/example.com/v1/infers/937cabe5-d673-47f1-9e7c-2b4de06*****/v1/chat/completions"
          api_key = "<your_apiKey>"  # 把<your_apiKey>替换成已获取的API Key。
      
          # Send request.
          headers = {
              'Content-Type': 'application/json',
              'Authorization': f'Bearer {api_key}'
          }
          data = {
              "model": "******",  # 调用时的模型名称。
              "max_tokens": 1024,  # 最大输出token数。
              "messages": [
                  {"role": "system", "content": "You are a helpful assistant."},
                  {"role": "user", "content": "hello"}
              ],
              # 是否开启流式推理,默认为False,表示不开启流式推理。
              "stream": False,
              # 在流式输出时是否展示使用的token数目。只有当stream为True时该参数才会生效。
              # "stream_options": {"include_usage": True},
              # 控制采样随机性的浮点数,值较低时模型更具确定性,值较高时模型更具创造性。"0"表示贪婪取样。默认为0.6。
              "temperature": 0.6
          }
      	response = requests.post(url, headers=headers, data=json.dumps(data), verify=False)
      	# Print result.     
      	print(response.status_code)     
      	print(response.text)
    • 使用OpenAI SDK调用。
      from openai import OpenAI
      
      if __name__ == '__main__':
      	base_url = "https://example.com/v1/infers/937cabe5-d673-47f1-9e7c-2b4de06******/v1"
      	api_key = "<your_apiKey>"  # 把<your_apiKey>替换成已获取的API Key。
      
      	client = OpenAI(api_key=api_key, base_url=base_url)
      
      	response = client.chat.completions.create(
      		model="******",
      		messages=[
      			{"role": "system", "content": "You are a helpful assistant"},
      			{"role": "user", "content": "Hello"},
      		],
      		max_tokens=1024,
      		temperature=0.6,
      		stream=False
      	)
      	# Print result.     
              print(response.choices[0].message.content)

    模型服务的API与vLLM相同,表2仅介绍关键参数,详细参数解释请参见vLLM官网。使用昇腾云909镜像的模型,开启流式输出时,需要新增stream_options参数,值为{"include_usage":true},才会打印token数。

    表2 请求参数说明

    参数

    是否必选

    默认值

    参数类型

    描述

    url

    Str

    调用时的API地址。假设URL为https://example.com/v1/infers/937cabe5-d673-47f1-9e7c-2b4de06*****/{endpoint} , 其中{endpoint}仅支持如下接口,详细介绍请参见接口调用说明

    • /v1/chat/completions
    • /v1/models

    model

    Str

    调用时的模型名称。

    在ModelArts Studio大模型即服务平台的“在线推理”页面,选择调用的模型服务,单击操作列的“更多 > 调用”,在调用页面可以获取“模型名称”

    messages

    -

    Array

    请求输入的问题。

    stream_options

    Object

    该参数用于配置在流式输出时是否展示使用的token数目。只有当stream为True的时候该参数才会激活生效。如果您需要统计流式输出模式下的token数目,可将该参数配置为stream_options={"include_usage":True}。

    max_tokens

    16

    Int

    每个输出序列要生成的最大Tokens数量。

    top_k

    -1

    Int

    控制要考虑的前几个Tokens的数量的整数。设置为“-1”表示考虑所有Tokens。

    适当降低该值可以减少采样时间。

    top_p

    1.0

    Float

    控制要考虑的前几个Tokens的累积概率的浮点数。

    取值范围:0~1

    设置为“1”表示考虑所有Tokens。

    temperature

    0.6

    Float

    控制采样的随机性的浮点数。较低的值使模型更加确定性,较高的值使模型更加随机。“0”表示贪婪采样。

    stop

    None

    None/Str/List

    用于停止生成的字符串列表。返回的输出将不包含停止字符串。

    例如,设置为["你","好"]时,在生成文本过程中,遇到“你”或者“好”将停止文本生成。

    stream

    False

    Bool

    是否开启流式推理。默认为“False”,表示不开启流式推理。

    n

    1

    Int

    返回多条正常结果。

    • 不使用beam_search场景下,n取值建议为1≤n≤10。如果n>1时,必须确保不使用greedy_sample采样,也就是top_k > 1,temperature > 0。
    • 使用beam_search场景下,n取值建议为1<n≤10。如果n=1,会导致推理请求失败。
    说明:

    n建议取值不超过10,n值过大会导致性能劣化,显存不足时,推理请求会失败。

    use_beam_search

    False

    Bool

    是否使用beam_search替换采样。

    使用该参数时,如下参数必须按要求设置。

    • n:大于1
    • top_p:1.0
    • top_k:-1
    • temperature:0.0

    presence_penalty

    0.0

    Float

    presence_penalty表示会根据当前生成的文本中新出现的词语进行奖惩。取值范围[-2.0,2.0]。

    frequency_penalty

    0.0

    Float

    frequency_penalty会根据当前生成的文本中各个词语的出现频率进行奖惩。取值范围[-2.0,2.0]。

    length_penalty

    1.0

    Float

    length_penalty表示在beam search过程中,对于较长的序列,模型会给予较大的惩罚。

    使用该参数时,必须添加如下三个参数,且必须按要求设置。

    • top_k:-1
    • use_beam_search:true
    • best_of:大于1

    ignore_eos

    False

    Bool

    ignore_eos表示是否忽略EOS并且继续生成Token。

    • 普通requests包、OpenAI SDK的返回示例如下所示:
      {
          "id": "cmpl-29f7a172056541449eb1f9d31c*****",
          "object": "chat.completion",
          "created": 17231*****,
          "model": "******",
          "choices": [
              {
                  "index": 0,
                  "message": {
                      "role": "assistant",
                      "content": "你好!很高兴能为你提供帮助。有什么问题我可以回答或帮你解决吗?"
                  },
                  "logprobs": null,
                  "finish_reason": "stop",
                  "stop_reason": null
              }
          ],
          "usage": {
              "prompt_tokens": 20,
              "total_tokens": 38,
              "completion_tokens": 18
          }
      }
    • 思维链模型的返回示例如下所示:
      messages = [{"role": "user", "content": "9.11 and 9.8, which is greater?"}]
      response = client.chat.completions.create(model=model, messages=messages)
      reasoning_content = response.choices[0].message.reasoning_content
      content = response.choices[0].message.content
      print("reasoning_content:", reasoning_content)
      print("content:", content)
    表3 返回参数说明

    参数

    参数类型

    描述

    id

    Str

    请求ID。

    object

    Str

    请求任务。

    created

    Int

    请求生成的时间戳。

    model

    Str

    调用的模型名。

    choices

    Array

    模型生成内容。

    usage

    Object

    请求输入长度、输出长度和总长度。

    • prompt_tokens:输入Tokens数。
    • completion_tokens:输出Tokens数。
    • total_tokens:总Tokens数。

    总Tokens数 = 输入Tokens数 + 输出Tokens数

    reasoning_content

    Str

    当模型支持思维链时,模型的思考内容。对于支持思维链的模型,开启流式输出时,会首先在reasoning_content字段输出思考内容,然后在content中输出回答内容。

    content

    Str

    模型的回答内容。

    当调用失败时,可以根据错误码调整脚本或运行环境。
    表4 常见错误码

    错误码

    错误内容

    说明

    400

    Bad Request

    请求包含语法错误。

    403

    Forbidden

    服务器拒绝执行。

    404

    Not Found

    服务器找不到请求的网页。

    500

    Internal Server Error

    服务内部错误。

接口调用说明

假设API地址为https://example.com/v1/infers/937cabe5-d673-47f1-9e7c-2b4de06*****/{endpoint} ,其中{endpoint}仅支持如下接口:

  • /v1/chat/completions
  • /v1/models

注意:

  • /v1/models使用GET方法不需要请求体,而/v1/chat/completions需要POST请求方式和对应的JSON请求体。
  • 通用请求头为Authorization: Bearer YOUR_API_KEY,对于POST请求,还需包含Content-Type: application/json。
表5 接口说明

类型/接口

/v1/models

/v1/chat/completions

请求方法

GET

POST

用途

获取当前支持的模型列表。

用于聊天对话型生成调用。

请求体说明

无需请求体,仅需通过请求头传入认证信息。

  • model:使用的模型标识。
  • messages:对话消息数组,每条消息需要包含role(如 "user" 或 "assistant")和content。
  • 其他可选参数:例如temperature(生成温度)、max_tokens等,用于控制生成结果的多样性和长度。

请求示例

GET https://example.com/v1/infers/937cabe5-d673-47f1-9e7c-2b4de06*****/v1/models HTTP/1.1
Authorization: Bearer YOUR_API_KEY
POST https://example.com/v1/infers/937cabe5-d673-47f1-9e7c-2b4de06*****/v1/chat/completions HTTP/1.1
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "model": "******",
  "messages": [
    {"role": "user", "content": "Hello, how are you?"}
  ],
  "temperature": 0.7
}

响应示例

{
  "data": [
    {
      "id": "******",
      "description": "最新一代大模型"
    },
    {
      "id": "******",
      "description": "性价比较高的替代方案"
    }
  ]
}
{
  "id": "******",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "I'm doing well, thank you! How can I help you today?"}
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 25,
    "total_tokens": 40
  }
}

常见问题

在ModelArts Studio(MaaS) 创建API Key后需要等待多久才能生效?

MaaS API Key在创建后不会立即生效,通常需要等待几分钟才能生效。