操作場景

在企業(yè)AI應用開發(fā)過程中，開發(fā)人員通常需要將訓練好的模型部署到實際業(yè)務環(huán)境中。然而，傳統(tǒng)方法需要手動配置環(huán)境、處理依賴關系、編寫部署腳本，整個過程耗時且容易出錯，且存在環(huán)境復雜、遷移困難、維護成本高、版本更新麻煩等問題。

ModelArts Studio（MaaS）大模型即服務平臺提供了一站式解決方案，提供統(tǒng)一的API接口方便業(yè)務系統(tǒng)調(diào)用，并提供監(jiān)控和日志功能便于運維管理。

計費說明

在調(diào)用模型推理服務的過程中，輸入內(nèi)容首先會被分詞（tokenize），轉(zhuǎn)換為模型可識別的Token。在調(diào)用MaaS預置服務時，將根據(jù)實際使用的Tokens數(shù)量進行計費。計費詳情請參見計費說明。

約束限制

對于支持圖片上傳的模型，單個圖片文件的大小不超過10MB。如果以Base64編碼形式上傳圖片，需確保編碼后的圖片小于10MB。

前提條件

• 使用預置服務：在“在線推理”頁面的“預置服務”頁簽，使用有效期內(nèi)的免費服務或者已開通商用服務（付費狀態(tài)為“開通”）。具體操作，請參見ModelArts Studio（MaaS）在線推理服務。
• 使用我的服務：在“在線推理”頁面的“我的服務”頁簽，服務列表存在運行中、更新中或升級中的模型服務。具體操作，請參見使用ModelArts Studio（MaaS）部署模型服務。
• 使用自定義接入點：已創(chuàng)建自定義接入點。具體操作，請參見在ModelArts Studio（MaaS）創(chuàng)建自定義接入點。

步驟一：獲取API Key

在調(diào)用MaaS部署的模型服務時，需要填寫API Key用于接口的鑒權(quán)認證。最多可創(chuàng)建30個密鑰。每個密鑰僅在創(chuàng)建時顯示一次，請確保妥善保存。如果密鑰丟失，無法找回，需要重新創(chuàng)建API Key以獲取新的訪問密鑰。更多信息，請參見在ModelArts Studio（MaaS）管理API Key。

1. 登錄ModelArts Studio（MaaS）控制臺，在頂部導航欄選擇目標區(qū)域。
2. 在左側(cè)導航欄，單擊“API Key管理”。
3. 在“API Key管理”頁面，單擊“創(chuàng)建API Key”，填寫標簽和描述信息后，單擊“確定”。

   標簽和描述信息在創(chuàng)建完成后，不支持修改。

   表1 創(chuàng)建API Key參數(shù)說明

   參數(shù)	說明
   標簽	自定義API Key的標簽。標簽具有唯一性，不可重復。僅支持大小寫英文字母、數(shù)字、下劃線、中劃線，長度范圍為1~100個字符。
   描述	自定義API Key的描述，長度范圍為1~100個字符。

4. 在“您的密鑰”對話框，復制密鑰并保存至安全位置。
5. 保存完畢后，單擊“關閉”。

   單擊“關閉”后將無法再次查看密鑰。

步驟二：調(diào)用MaaS模型服務進行預測

1. 在ModelArts Studio（MaaS）控制臺左側(cè)導航欄，選擇“在線推理”。
2. 在“在線推理”頁面，單擊“我的服務”頁簽，在目標服務右側(cè)，單擊操作列的“更多 > 調(diào)用說明”。
3. 在“關閉 內(nèi)容審核 服務”對話框，選擇是否啟用內(nèi)容審核（默認啟用）。
   • 啟用內(nèi)容審核，可以阻止在線推理中的輸入輸出中出現(xiàn)不合規(guī)的內(nèi)容，但可能會對接口性能產(chǎn)生較大影響。
   • 關閉內(nèi)容審核服務，將不會審核在線推理中的輸入輸出，模型服務可能會有違規(guī)風險，請謹慎關閉。

     關閉“內(nèi)容審核”開關，需要在彈窗中確認是否停用內(nèi)容審核服務，勾選“我已閱讀并同意上述說明”后，單擊“確定”關閉。

4. 在“調(diào)用說明”頁面，選擇接口類型，復制調(diào)用示例，修改接口信息和API Key后用于業(yè)務環(huán)境調(diào)用模型服務API。

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

   • Rest API示例代碼如下所示：
     • 使用Python調(diào)用示例。

       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": "******",  # 調(diào)用時的模型名稱。
               "max_tokens": 1024,  # 最大輸出token數(shù)。
               "messages": [
                   {"role": "system", "content": "You are a helpful assistant."},
                   {"role": "user", "content": "hello"}
               ],
               # 是否開啟流式推理，默認為False,表示不開啟流式推理。
               "stream": False,
               # 在流式輸出時是否展示使用的token數(shù)目。只有當stream為True時該參數(shù)才會生效。
               # "stream_options": {"include_usage": True},
               # 控制采樣隨機性的浮點數(shù)，值較低時模型更具確定性，值較高時模型更具創(chuàng)造性。"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調(diào)用示例。

       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調(diào)用示例。

     # 安裝環(huán)境命令。
     pip install --upgrade "openai>=1.0"

     # OpenAI SDK調(diào)用示例。
     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僅介紹關鍵參數(shù)，詳細參數(shù)解釋請參見vLLM官網(wǎng)。使用昇騰云909 鏡像 的模型，開啟流式輸出時，需要新增stream_options參數(shù)，值為{"include_usage":true}，才會打印token數(shù)。

   表2 請求參數(shù)說明

   參數(shù)	是否必選	默認值	參數(shù)類型	描述
   url	是	無	Str	調(diào)用時的API地址。假設URL為https://example.com/v1/infers/937cabe5-d673-47f1-9e7c-2b4de06*****/{endpoint} ， 其中{endpoint}僅支持如下接口，詳細介紹請參見接口調(diào)用說明。 /v1/chat/completions /v1/models
   model	是	無	Str	調(diào)用時的模型名稱。 在ModelArts Studio大模型即服務平臺的“在線推理”頁面，選擇調(diào)用的模型服務，單擊操作列的“更多 > 調(diào)用”，在調(diào)用頁面可以獲取“模型名稱”。
   messages	是	-	Array	請求輸入的問題。
   messages.role	是	無	Str	不同的role對應不同的消息類型。 system：開發(fā)人員輸入的指令，例如模型應遵循的答復格式、扮演的角色等。 user：用戶輸入的消息，包括提示詞和上下文信息。 assistant：模型生成的回復內(nèi)容。 tool：模型調(diào)用工具返回的信息。
   messages.content	是	無	Str	當role為system時：給AI模型設定的人設。 {"role": "system","content": "你是一個樂于助人的AI助手"} 當role為user時：用戶輸入的問題。 {"role": "user","content": "9.11和9.8哪個大？"} 當role為assistant時：AI模型輸出的答復內(nèi)容。 {"role": "assistant","content": "9.11大于9.8"} 當role為tool時：AI模型調(diào)用的工具響應信息。 {"role": "tool", "content": "上海今天天氣晴，氣溫10度"}
   stream_options	否	無	Object	該參數(shù)用于配置在流式輸出時是否展示使用的token數(shù)目。只有當stream為True的時候該參數(shù)才會激活生效。如果您需要統(tǒng)計流式輸出模式下的token數(shù)目，可將該參數(shù)配置為stream_options={"include_usage":True}。
   max_tokens	否	16	Int	當前任務允許的生成Token數(shù)上限，包括模型輸出的Tokens和深度思考的Reasoning Tokens。
   top_k	否	-1	Int	在生成過程中，候選集大小限定了采樣的范圍。以取值50為例，這意味著每一步僅會考慮得分排在前50位的Token構(gòu)成候選集進行隨機抽樣。增大此值將提高輸出的隨機性，減小此值會增強輸出的確定性。
   top_p	否	1.0	Float	模型核采樣（nucleus sampling）。僅保留累計概率剛好超過閾值p的那一部分詞，其余全部屏蔽，最后在這份候選詞里重新歸一化并采樣。 設置值越小，候選詞越少，模型輸出越集中和保守；設置值越大，候選詞越多，模型輸出越開放和多樣。 通常情況只建議調(diào)整temperature或top_p，不要同時修改兩個參數(shù)。 取值范圍：0~1，設置為“1”表示考慮所有Tokens。
   temperature	否	0.6	Float	模型采樣溫度。設置的值越高，模型輸出越隨機；設置的值越低，輸出越確定。 通常情況只建議調(diào)整temperature或top_p，不要同時修改兩個參數(shù)。 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	為每個輸入的消息生成的響應數(shù)。 不使用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替換采樣。 使用該參數(shù)時，如下參數(shù)必須按要求設置。 n：大于1 top_p：1.0 top_k：-1 temperature：0.0
   presence_penalty	否	0.0	Float	presence_penalty表示會根據(jù)當前生成的文本中新出現(xiàn)的詞語進行獎懲。取值范圍[-2.0,2.0]。
   frequency_penalty	否	0.0	Float	frequency_penalty會根據(jù)當前生成的文本中各個詞語的出現(xiàn)頻率進行獎懲。取值范圍[-2.0,2.0]。
   length_penalty	否	1.0	Float	length_penalty表示在beam search過程中，對于較長的序列，模型會給予較大的懲罰。 使用該參數(shù)時，必須添加如下三個參數(shù)，且必須按要求設置。 top_k：-1 use_beam_search：true best_of：大于1

   • 普通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 返回參數(shù)說明

   參數(shù)	參數(shù)類型	描述
   id	Str	請求ID。
   object	Str	請求任務。
   created	Int	請求生成的時間戳。
   model	Str	調(diào)用的模型名。
   choices	Array	模型生成內(nèi)容。
   usage	Object	請求輸入長度、輸出長度和總長度。 prompt_tokens：輸入Tokens數(shù)。 completion_tokens：輸出Tokens數(shù)。 total_tokens：總Tokens數(shù)。 總Tokens數(shù) = 輸入Tokens數(shù) + 輸出Tokens數(shù)
   reasoning_content	Str	當模型支持思維鏈時，模型的思考內(nèi)容。對于支持思維鏈的模型，開啟流式輸出時，會首先在reasoning_content字段輸出思考內(nèi)容，然后在content中輸出回答內(nèi)容。
   content	Str	模型的回答內(nèi)容。

   當調(diào)用失敗時，可以根據(jù)錯誤碼調(diào)整腳本或運行環(huán)境。

   表4 常見錯誤碼

   錯誤碼	錯誤內(nèi)容	說明
   400	Bad Request	請求包含語法錯誤。
   403	Forbidden	服務器拒絕執(zhí)行。
   404	Not Found	服務器找不到請求的網(wǎng)頁。
   500	Internal Server Error	服務內(nèi)部錯誤。

內(nèi)容審核說明

• 流式請求
  • 如果觸發(fā)內(nèi)容審核，則會返回錯誤：錯誤碼403。您可以通過錯誤碼ModelArts.81011來判斷。返回內(nèi)容如下：

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

    圖1 報錯示例
    
  • 如果未觸發(fā)內(nèi)容審核，則使用postman調(diào)用返回參考如下，返回碼200。
    圖2 正常返回示例
    
  • 如果輸出有敏感信息，則會在輸出流后面拼接如下數(shù)據(jù)：

    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":" 繼續(xù)輸出結(jié)果。"},"index":0}]
    data: {"id":"chatcmpl-*********************","object":"chat.completion","created":1678067605,"model":"******","choices":[{"finish_reason":"content_filter","index":0}]}
    data: [DONE]

    觸發(fā)內(nèi)容審核之后，"finish_reason"是"content_filter"；正常的流式停止是 "finish_reason":"stop"。

• 非流式請求
  • 如果觸發(fā)內(nèi)容審核，則會返回錯誤：錯誤碼403。您可以通過錯誤碼ModelArts.81011來判斷。

    返回內(nèi)容如下：

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

  • 如果未觸發(fā)，則正常返回，示例如下：
    圖3 正常返回示例
    

接口調(diào)用說明

假設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） 創(chuàng)建API Key后需要等待多久才能生效？

MaaS API Key在創(chuàng)建后不會立即生效，通常需要等待幾分鐘才能生效。

相關文檔

• ModelArts Studio（MaaS） API調(diào)用規(guī)范
• 使用ModelArts Studio（MaaS）創(chuàng)建多輪對話
• 在ModelArts Studio（MaaS）查看在線推理的調(diào)用數(shù)據(jù)和監(jiān)控指標