# 模型API调用指南
ModelArts平台提供功能丰富的在线推理能力，支持用户选取模型在专属实例上进行自部署。本文介绍对话Chat相关API的调用规范。
#### 约束限制
对于支持图片上传的模型，单个图片文件的大小不超过10MB。如果以Base64编码形式上传图片，需确保编码后的图片小于10MB。
#### 接口信息
表1接口信息 
| 名称      | 说明                                                                                                                            | 取值                                                                                                                                                                                                                                                                        |
|:---|:---|:---|
| API地址   | 调用模型服务的API地址。                                                                                                                 | - 在线服务调用地址：在[ModelArts管理控制台](https://console.huaweicloud.com/modelarts/)"模型推理\>在线推理"页面，单击已部署完成的服务，进入详情页，获取服务的"公网调用URL"。   |
| model参数 | model参数调用名称。  | 参见[支持一键部署的模型列表](https://support.huaweicloud.com/model-call-modelarts/model-call-modelarts-0001.html#ZH-CN_TOPIC_0000002548104305__section36038213186)的model参数。                                                                                                            |
   
#### 思维链说明
思维链（Chain of Thought，简称CoT）是指模型在解决复杂问题时，能够生成一系列中间推理步骤的能力。这种能力使得模型不仅能够给出最终答案，还能展示出其推理过程，从而提高模型的可解释性和透明度。
 #### 创建对话请求
- 鉴权说明 推理服务支持使用API Key鉴权，鉴权头采用如下格式：
  ```
  'Authorization': 'Bearer 该服务所在Region的ApiKey'
  ```
  
- 请求参数和响应参数说明如下：
  表2请求参数说明 
  | 参数名称                                 | 是否必选 | 默认值   | 参数类型          | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
  |:---|:---|:---|:---|:---|
  | model                                | 是    | 无     | Str           | 调用时的模型名称。取值请参见[快速调用预置模型](https://support.huaweicloud.com/model-call-modelarts/model-call-modelarts-0001.html)的model参数。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
  | messages                             | 是    | -     | Array         | 请求输入的问题，其中role为角色，content为对话内容。示例如下： ``` "messages": [ {"role": "system","content": "你是一个乐于助人的AI助手"}, {"role": "user","content": "9.11和9.8哪个大？"} ] ``` 更多信息，请参见[表3]。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
  | messages.prefix                      | 否    | false | Boolean       | 控制是否开启续写模式：用户提供assistant开头的消息，让模型基于该开头和输入指令来补全其余的部分。 使用该功能时，需确保messages列表里最后一条消息的role为assistant，并设置最后一条消息的prefix参数为True，示例如下： ``` messages = [ {"role": "user", "content": "写一段python代码"}, {"role": "assistant", "content": "```python\n", "prefix": True} ] ```                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
  | stream_options                       | 否    | 无     | Object        | 该参数用于配置在流式输出时是否展示使用的Token数目。只有当"stream"为"True"时，该参数才会激活生效。如果您需要统计流式输出模式下的Token数目，可将该参数配置为stream_options={"include_usage":True}。更多信息，请参见[表4]。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
  | max_tokens                           | 否    | 无     | 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                          | 否    | 1.0   | Float         | 模型采样温度。设置的值越高，模型输出越随机；设置的值越低，输出越确定。 通常情况只建议调整temperature或top_p，不要同时修改两个参数。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
  | 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         | 表示会根据当前生成的文本中新出现的词语进行奖惩。取值范围\[-2.0,2.0\]。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
  | frequency_penalty                    | 否    | 0.0   | Float         | 会根据当前生成的文本中各个词语的出现频率进行奖惩。取值范围\[-2.0,2.0\]。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
  | length_penalty                       | 否    | 1.0   | Float         | 表示在beam search过程中，对于较长的序列，模型会给予较大的惩罚。 使用该参数时，必须添加如下三个参数，且必须按要求设置。 - top_k：-1  - use_beam_search：true  - best_of：大于1                                                                                                                                 |
  | chat_template_kwargs.thinking        | 否    | false | Bool          | 是否开启思维链。部分模型支持在发起推理请求时，通过增加模板参数： "thinking": true的方式来开启思维链。 开启思维链示例如下： ``` { "model": "DeepSeek-V31", "messages": [{ "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "你好" }], "chat_template_kwargs": { "thinking": true } } ```                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
  | chat_template_kwargs.enable_thinking | 否    | true  | Bool          | 是否开启思维链。部分模型支持在发起推理请求时，通过增加模板参数： "enable_thinking": false的方式来关闭思维链。 关闭思维链示例如下： ``` { "model": "qwen3-32b", "messages": [{ "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "你好" }], "chat_template_kwargs": { "enable_thinking": false } } ```                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
     
   表3请求参数messages说明 
  | 参数名称    | 是否必选 | 默认值 | 参数类型 | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
  |:---|:---|:---|:---|:---|
  | role    | 是    | 无   | Str  | 不同的role对应不同的消息类型。 - system：开发人员输入的指令，例如模型应遵循的答复格式、扮演的角色等。  - user：用户输入的消息，包括提示词和上下文信息。  - assistant：模型生成的回复内容。  - tool：模型调用工具返回的信息。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
  | content | 是    | 无   | Str  | - 当role为system时：给AI模型设定的人设。 ``` { "role": "system", "content": "你是一个乐于助人的AI助手" } ```   - 当role为user时：用户输入的问题。 - 文本对话： ``` { "role": "user", "content": "9.11和9.8哪个大？" } ```   - 图像理解： 支持图片格式：png、jpeg、jpg、webp、bmp、tiff。 支持使用图片的Base64编码内容或者公网可访问的图片地址。以下是两种方式的代码示例： - 使用图片的Base64编码内容： ``` { "role": "user", "content": [ { "type": "image_url", "image_url": { "url": f"data:image/png;base64,{base64_image}" } }, { "type": "text", "text": "图像显示的是什么内容？" } ] } ``` Base64编码的图像格式（即image/{format}）需要与支持的图片列表中的Content Type保持一致。"f"是字符串格式化的方法，用于将Base64编码的图像数据嵌入到URL中。示例如下： ``` # PNG图像 f"data:image/png;base64,{base64_image}" # JPEG图像 f"data:image/jpeg;base64,{base64_image}" # WEBP图像： f"data:image/webp;base64,{base64_image}" ```   - 使用公网可访问的图片地址： ``` { "role": "user", "content": [ { "type": "image_url", "image_url": { "url": "https://example.com/xxx.jpeg" } }, { "type": "text", "text": "图像显示的是什么内容？" } ] } ```        - 当role为assistant时：AI模型输出的答复内容。 ``` {"role": "assistant","content": "9.11大于9.8"} ```   - 当role为tool时：AI模型调用的工具响应信息。 ``` {"role": "tool", "content": "上海今天天气晴，气温10度"} ```    |
     
   表4请求参数stream_options说明 
  | 参数名称          | 是否必选 | 默认值  | 参数类型 | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
  |:---|:---|:---|:---|:---|
  | include_usage | 否    | true | Bool | 流式响应是否输出Token用量信息： - true：是，在每一个chunk会输出一个usage字段，显示累计消耗的Token统计信息。  - false：否，不显示消耗的Token统计信息。   |
     
  表5响应参数说明 
  | **参数名称**        | **类型** | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
  |:---|:---|:---|
  | id              | Str    | 该次请求的唯一标识。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
  | object          | Str    | 类型-chat.completion：多轮对话返回。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
  | created         | Int    | 时间戳。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
  | model           | Str    | 调用时的模型名称。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
  | choices         | Array  | 模型答复的内容，包含index和message两个参数，message中： - content为模型的正式答复内容。  - reasoning content为模型的深度思考内容（仅限DeepSeek系列模型）。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
  | usage           | Object | 请求消耗的Token统计信息： - 非流式请求默认返回。  - 流式请求默认返回，在每一个chunk会输出一个usage字段，显示消耗的Token统计信息。   参数说明： - prompt tokens：输入Token数量。  - completion tokens: 输出Token数量。  - total tokens：总Token数量。   |
  | prompt_logprobs | Float  | 对数概率。用户可以借此衡量模型对其输出内容的置信度，或者探索模型给出的其他选项。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
     
  
 
#### DeepSeek-V3.1文本生成请求示例
此处以使用DeepSeek-V3.1模型通过Python脚本、cURL命令和OpenAI SDK请求生成文本响应为例，展示文本生成模型的基础用法。
- Python请求示例：
  ```
  import requests
  import json
  if __name__ == '__main__':
      url = ""https://***/v2/infer/***/v1/chat/completions""  # API地址
      api_key = "API_KEY"  # 把API_KEY替换成已获取的API Key
      # Send request.
      headers = {
          'Content-Type': 'application/json',
          'Authorization': f'Bearer {api_key}'
      }
      data = {
          "model": "DeepSeek-V31",  # model参数
          "messages": [
              {"role": "system", "content": "You are a helpful assistant."},
              {"role": "user", "content": "你好"}
          ],
          "chat_template_kwargs": {
              "thinking": True  # 是否开启深度思考模式，默认关闭
          }
      }
      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://***/v2/infer/***/v1/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $API_KEY" \
    -d '{
      "model": "DeepSeek-V31",
      "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "你好"}
      ],
       "chat_template_kwargs": {
         "thinking": true
       }
    }'
  ```
  
- OpenAI SDK请求示例：
  ```
  from openai import OpenAI
  base_url = "https://***/v2/infer/***/v1/chat/completions"  # API地址
  api_key = "API_KEY"  # 把API_KEY替换成已获取的API Key
  client = OpenAI(api_key=api_key, base_url=base_url)
  response = client.chat.completions.create(
      model="DeepSeek-V31",  # model参数
      messages=[
          {"role": "system", "content": "You are a helpful assistant"},
          {"role": "user", "content": "你好"},
      ],
      extra_body={
          "chat_template_kwargs": {
              "thinking": True  # 是否开启深度思考模式，默认关闭
          }
      }
  )
  print(response.choices[0].message.content)
  ```
  
 
#### Qwen3-VL-30-A3B图像理解请求示例
此处以使用Qwen3-VL-30B-A3B模型通过Python脚本、cURL命令和OpenAI SDK请求进行图像理解为例，展示图像理解模型的基础用法。
- Python请求示例：
  ```
  import requests
  import json
  import base64
  #  图片转Base64编码格式
  def encode_image(image_path):
      with open(image_path, "rb") as image_file:
          return base64.b64encode(image_file.read()).decode("utf-8")
  base64_image = encode_image("test.png")
  if __name__ == '__main__':
      url = "https://***/v2/infer/***/v1/chat/completions" # API地址
      api_key = "API_KEY"  # 把API_KEY替换成已获取的API Key 
      # Send request.
      headers = {
          'Content-Type': 'application/json',
          'Authorization': f'Bearer {api_key}' 
      }
      data = {
          "model": "qwen3_vl_30b_a3b", # model参数
          "messages": [
              {
                "role": "user",
                "content": [
                  {
                    "type": "text",
                    "text": "描述下图片里的内容"
                  },
                  {
                    "type": "image_url",
                    # 需要注意，Base64编码的图像格式（即image/{format}）需要与支持的图片列表中的Content Type保持一致。"f"是字符串格式化的方法。
                    # Base64编码的PNG图像：  f"data:image/png;base64,{base64_image}"
                    # Base64编码的JPEG图像： f"data:image/jpeg;base64,{base64_image}"
                    # Base64编码的WEBP图像： f"data:image/webp;base64,{base64_image}"
                    # 公网图像地址： "https://example/xxx.png"
                    "image_url": {
                      "url": f"data:image/png;base64,{base64_image}"
                    }
                  }
                ]
              }
          ]
      }
      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://***/v2/infer/***/v1/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $API_KEY" \
    -d '{ 
      "model": "qwen3_vl_30b_a3b",
      "messages": [
        {
          "role": "user",
          "content": [
            {"type": "text", "text": "描述下图片里的内容"},
            {"type": "image_url", "image_url": {"url": "data:image/png;base64,$BASE64_IMAGE"}}
          ]
        }
      ]
    }'
  ```
  
 
- OpenAI SDK请求示例：
  ```
  import base64
  from openai import OpenAI
  base_url = "https://***/v2/infer/***/v1/chat/completions" # API地址
  api_key = "API_KEY" # 把API_KEY替换成已获取的API Key
  #  图片转Base64编码格式
  def encode_image(image_path):
      with open(image_path, "rb") as image_file:
          return base64.b64encode(image_file.read()).decode("utf-8")
  base64_image = encode_image("test.png")
  client = OpenAI(api_key=api_key, base_url=base_url)
  response = client.chat.completions.create(
      model = "qwen3_vl_30b_a3b", # model参数
      messages = [
          {
              "role": "user",
              "content": [
                  {"type": "text", "text": "描述下图片里的内容"},
                  {
                      "type": "image_url",
                      # 需要注意，Base64编码的图像格式（即image/{format}）需要与支持的图片列表中的Content Type保持一致。"f"是字符串格式化的方法。
                      # Base64编码的PNG图像：  f"data:image/png;base64,{base64_image}"
                      # Base64编码的JPEG图像： f"data:image/jpeg;base64,{base64_image}"
                      # Base64编码的WEBP图像： f"data:image/webp;base64,{base64_image}"
                      # 公网图像地址： "https://example/xxx.png"
                      "image_url": {
                          "url": f"data:image/png;base64,{base64_image}"
                      }
                  }
              ]
          }
      ]
  )
  print(response.choices[0].message.content)
  ```
  
 
#### 响应示例
文本生成模型的响应示例如下。
```
{
    "id":"chat-71406e38b0d248c9b284709f8435****",
    "object":"chat.completion",
    "created":1740809549,
    "model":"DeepSeek-V31",
    "choices":[
        {
            "index":0,
            "message":{
                "role":"assistant",
                "content":"\n\n比较两个小数9.11和9.8的大小：\n\n1. **比较整数部分**：两者的整数部分都是9，相等。\n2. **比较十分位**： \n - 9.11的十分位是 **1** \n - 9.8可以看作是9.80，其十分位是 **8** \n - **8 > 1**，因此在这一位上已经能分出大小。\n\n**结论**： \n**9.8 > 9.11** \n（小数值比较时需对齐位数，直接比较对应数位的数字即可）",
                "reasoning_content":"嗯，我现在需要比较9.11和9.8哪个大。首先，我得回忆一下小数比较的方法。记得比较小数的时候，应该先比较整数部分，如果整数部分相同，再依次比较小数部分的十分位、百分位，直到分出大小。\n\n这两个数的整数部分都是9，所以整数部分相同。接下来比较十分位。9.11的十分位是1，而9.8的十分位是8。这里可能会有问题，因为有时候可能会有同学直接把9.8当作9.80来看，或者考虑十分位上的数字大小对比。\n\n现在比较的话，9.8的十分位是8，而9.11的十分位是1，明显8比1大，所以这时候是不是应该认为9.8比9.11大呢？\n\n不过要注意到，有的同学可能误以为小数位数越多数值越大，但实际并非如此，比如0.9比0.8999要大，所以位数多不一定数值大。\n\n另外，可以把两个数的小数部分统一成相同的位数来比较。例如，9.8可以写成9.80，这样十分位是8，百分位是0，而9.11的十分位是1，百分位是1。那么在十分位的时候，8比1大，所以9.80（即9.8）大于9.11。\n\n因此，最终结论是9.8比9.11大。\n",
                "tool_calls":[]
                },
                "logprobs":null,
                "finish_reason":"stop",
                "stop_reason":null        
        }
    ],
    "usage":{
        "prompt_tokens":21,
        "total_tokens":437,
        "completion_tokens":416
        },
    "prompt_logprobs":null
}
```