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

前提条件

• 使用预置服务：在“在线推理”页面的“预置服务”页签，已领取免费Token，且额度未使用完毕，或者已开通商用服务（付费状态为“开通”）。具体操作，请参见免费体验MaaS预置服务和在ModelArts Studio（MaaS）预置服务中开通商用服务。
• 使用我的服务：在“在线推理”页面的“我的服务”页签，服务列表存在运行中、更新中或升级中的模型服务。具体操作，请参见使用ModelArts Studio（MaaS）部署模型服务。

步骤一：获取API Key

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

1. 登录ModelArts Studio控制台，在顶部导航栏选择目标区域。
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左侧导航栏，选择“在线推理”。
2. 在“在线推理”页面，单击“我的服务”页签，在目标服务右侧，单击操作列的“更多 > 调用说明”。
3. 在“关闭内容审核服务”对话框，选择是否启用内容审核（默认启用）。
   • 启用内容审核，可以阻止在线推理中的输入输出中出现不合规的内容，但可能会对接口性能产生较大影响。
   • 关闭内容审核服务，将不会审核在线推理中的输入输出，模型服务可能会有违规风险，请谨慎关闭。

     关闭“内容审核”开关，需要在弹窗中确认是否停用内容审核服务，勾选“我已阅读并同意上述说明”后，单击“确定”关闭。

4. 在“调用说明”页面，选择接口类型，复制调用示例，修改接口信息和API Key后用于业务环境调用模型服务API。

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

   • Rest API示例代码如下所示：
     • 使用Python调用示例。

       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)

     • 使用cURL调用示例。

       curl -X POST "https://example.com/v1/chat/completions" \
         -H "Content-Type: application/json" \
         -H "Authorization: Bearer $API_KEY" \
         -d '{ 
           "model": "DeepSeek-R1",
           "messages": [
             {"role": "system", "content": "You are a helpful assistant."},
             {"role": "user", "content": "你好"}
           ],
           "stream": true,
           "stream_options": { "include_usage": true },
           "temperature": 0.6
         }'

   • 使用OpenAI SDK调用示例。

     # 安装环境命令。
     pip install --upgrade "openai>=1.0"

     # 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 /v1/completions
   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、curl命令的返回示例如下所示：

     {
         "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	服务内部错误。

内容审核说明

• 流式请求
  • 如果触发内容审核，则会返回错误：错误码403。您可以通过错误码ModelArts.4910来判断。返回内容如下：

    {
        "error_code": "ModelArts.4910",
        "error_msg": "May contain sensitive information, please try again."
    }

    图1 报错示例
    
  • 如果未触发内容审核，则使用postman调用返回参考如下，返回码200。
    图2 正常返回示例
    
  • 如果输出有敏感信息，则会在输出流后面拼接如下数据：

    data: {"id":"chatcmpl-*********************","object":"chat.completion","created":1678067605,"model":"******","choices":[{"delta":{"content":"这是流式响应的开始。"},"index":0}]
    data: {"id":"chatcmpl-*********************","object":"chat.completion","created":1678067605,"model":"******","choices":[{"delta":{"content":" 继续输出结果。"},"index":0}]
    data: {"id":"chatcmpl-*********************","object":"chat.completion","created":1678067605,"model":"******","choices":[{"finish_reason":"content_filter","index":0}]}
    data: [DONE]

    触发内容审核之后，"finish_reason"是"content_filter"；正常的流式停止是 "finish_reason":"stop"。

• 非流式请求
  • 如果触发内容审核，则会返回错误：错误码403。您可以通过错误码ModelArts.4910来判断。

    返回内容如下：

    {
        "error_code": "ModelArts.4910",
        "error_msg": "May contain sensitive information, please try again."
    }
    

    图3 报错示例
    
  • 如果未触发，则正常返回，示例如下：
    图4 正常返回示例
    

接口调用说明

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

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

注意：

• /v1/models使用GET方法不需要请求体，而/v1/chat/completions与/v1/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
}

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

{
  "model": "******",
  "prompt": "Tell me a story about a brave knight.",
  "max_tokens": 150,
  "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
  }
}

{
  "id": "******",
  "object": "text_completion",
  "choices": [
    {
      "text": "Once upon a time, a brave knight embarked on a perilous journey...",
      "index": 0
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 90,
    "total_tokens": 100
  }
}