调用ModelArts Studio（MaaS）部署的模型服务

操作场景

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

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

前提条件

在“在线推理”页面的“我的服务”页签，服务列表存在运行中、更新中或升级中的模型服务。具体操作，请参见使用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	请求输入的问题。
   messages.role	是	无	Str	不同的role对应不同的消息类型。 system：开发人员输入的指令，例如模型应遵循的答复格式、扮演的角色等。 user：用户输入的消息，包括提示词和上下文信息。 assistant：模型生成的回复内容。 tool：模型调用工具返回的信息。
   messages.content	是	无	Str	当role为system时：给AI模型设定的人设。 {"role": "system","content": "你是一个乐于助人的AI助手"} 当role为user时：用户输入的问题。 {"role": "user","content": "9.11和9.8哪个大？"} 当role为assistant时：AI模型输出的答复内容。 {"role": "assistant","content": "9.11大于9.8"} 当role为tool时：AI模型调用的工具响应信息。 {"role": "tool", "content": "上海今天天气晴，气温10度"}
   stream_options	否	无	Object	该参数用于配置在流式输出时是否展示使用的token数目。只有当stream为True的时候该参数才会激活生效。如果您需要统计流式输出模式下的token数目，可将该参数配置为stream_options={"include_usage":True}。
   max_tokens	否	16	Int	当前任务允许的生成Token数上限，包括模型输出的Tokens和深度思考的Reasoning Tokens。
   top_k	否	-1	Int	在生成过程中，候选集大小限定了采样的范围。以取值50为例，这意味着每一步仅会考虑得分排在前50位的Token构成候选集进行随机抽样。增大此值将提高输出的随机性，减小此值会增强输出的确定性。
   top_p	否	1.0	Float	模型核采样（nucleus sampling）。仅保留累计概率刚好超过阈值p的那一部分词，其余全部屏蔽，最后在这份候选词里重新归一化并采样。 设置值越小，候选词越少，模型输出越集中和保守；设置值越大，候选词越多，模型输出越开放和多样。 通常情况只建议调整temperature或top_p，不要同时修改两个参数。 取值范围：0~1，设置为“1”表示考虑所有Tokens。
   temperature	否	0.6	Float	模型采样温度。设置的值越高，模型输出越随机；设置的值越低，输出越确定。 通常情况只建议调整temperature或top_p，不要同时修改两个参数。 temperature取值建议：DeepSeek-R1、DeepSeek-V3、Qwen3系列建议值为0.6，Qwen2.5-VL系列建议值为0.2。
   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

   • 普通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。

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在创建后不会立即生效，通常需要等待几分钟才能生效。

相关文档

• ModelArts Studio（MaaS） API调用规范
• 使用ModelArts Studio（MaaS）创建多轮对话