操作場(chǎng)景

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

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

計(jì)費(fèi)說明

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

約束限制

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

前提條件

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

步驟一：獲取API Key

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

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

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

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

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

4. 在“您的密鑰”對(duì)話框，復(fù)制密鑰并保存至安全位置。
5. 保存完畢后，單擊“關(guān)閉”。

   單擊“關(guān)閉”后將無法再次查看密鑰。

步驟二：調(diào)用MaaS模型服務(wù)進(jìn)行預(yù)測(cè)

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

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

4. 在“調(diào)用說明”頁面，選擇接口類型，復(fù)制調(diào)用示例，修改接口信息和API Key后用于業(yè)務(wù)環(huán)境調(diào)用模型服務(wù)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)用時(shí)的模型名稱。
               "max_tokens": 1024,  # 最大輸出token數(shù)。
               "messages": [
                   {"role": "system", "content": "You are a helpful assistant."},
                   {"role": "user", "content": "hello"}
               ],
               # 是否開啟流式推理，默認(rèn)為False,表示不開啟流式推理。
               "stream": False,
               # 在流式輸出時(shí)是否展示使用的token數(shù)目。只有當(dāng)stream為True時(shí)該參數(shù)才會(huì)生效。
               # "stream_options": {"include_usage": True},
               # 控制采樣隨機(jī)性的浮點(diǎn)數(shù)，值較低時(shí)模型更具確定性，值較高時(shí)模型更具創(chuàng)造性。"0"表示貪婪取樣。默認(rèn)為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)

   模型服務(wù)的API與vLLM相同，表2僅介紹關(guān)鍵參數(shù)，詳細(xì)參數(shù)解釋請(qǐng)參見vLLM官網(wǎng)。使用昇騰云909 鏡像 的模型，開啟流式輸出時(shí)，需要新增stream_options參數(shù)，值為{"include_usage":true}，才會(huì)打印token數(shù)。

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

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

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

   表4 常見錯(cuò)誤碼

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

內(nèi)容審核說明

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

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

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

    data: {"id":"chatcmpl-*********************","object":"chat.completion","created":1678067605,"model":"******","choices":[{"delta":{"content":"這是流式響應(yīng)的開始。"},"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"。

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

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

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

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

接口調(diào)用說明

假設(shè)API地址為https://example.com/v1/infers/937cabe5-d673-47f1-9e7c-2b4de06*****/{endpoint} ，其中{endpoint}僅支持如下接口：

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

注意：

• /v1/models使用GET方法不需要請(qǐng)求體，而/v1/chat/completions需要POST請(qǐng)求方式和對(duì)應(yīng)的JSON請(qǐng)求體。
• 通用請(qǐng)求頭為Authorization: Bearer YOUR_API_KEY，對(duì)于POST請(qǐng)求，還需包含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": "性價(jià)比較高的替代方案"
    }
  ]
}

{
  "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)建后不會(huì)立即生效，通常需要等待幾分鐘才能生效。

相關(guān)文檔

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