对话Chat/POST
MaaS平台提供功能丰富的在线推理能力，支持用户选取模型在专属实例上进行自部署。本文介绍对话Chat相关API的调用规范。
接口信息
|
名称 |
说明 |
取值 |
|---|---|---|
|
API地址 |
调用模型服务的API地址。 |
https://api.modelarts-maas.com/v1/chat/completions |
|
model参数 |
model参数调用名称。 |
在“调用说明”页面获取。更多信息，请参见调用ModelArts Studio（MaaS）部署的模型服务。 |
创建聊天对话请求
- 鉴权说明
MaaS推理服务支持使用API Key鉴权，鉴权头采用如下格式：
'Authorization': 'Bearer 该服务所在Region的ApiKey'
- 请求参数和响应参数说明如下：
表2 请求参数说明 参数名称
是否必选
默认值
参数类型
说明
model
是
无
Str
调用时的模型名称。取值请参见上方表1。
messages
是
-
Array
请求输入的问题，其中role为角色，content为对话内容。示例如下：
"messages": [ {"role": "system","content": "你是一个乐于助人的AI助手"}, {"role": "user","content": "9.11和9.8哪个大？"} ]更多信息，请参见表3。
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，不要同时修改两个参数。
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值过大会导致性能劣化，显存不足时，推理请求会失败。
- DeepSeek-R1和DeepSeek-V3暂不支持设置n的值大于1。
use_beam_search
否
False
Bool
是否使用beam_search替换采样。
使用该参数时，如下参数必须按要求设置。
- n：大于1
- top_p：1.0
- top_k：-1
- temperature：0.0
说明：
DeepSeek-R1和DeepSeek-V3暂不支持设置n的值大于1。
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
说明：DeepSeek-R1和DeepSeek-V3暂不支持设置length_penalty。
表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哪个大？"} - 当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
对数概率。用户可以借此衡量模型对其输出内容的置信度，或者探索模型给出的其他选项。
文本生成（非流式）请求示例
- Rest API请求示例：
- Python请求示例：
import requests import json if __name__ == '__main__': url = "https://api.modelarts-maas.com/v1/chat/completions" # API地址 api_key = "MAAS_API_KEY" # 把MAAS_API_KEY替换成已获取的API Key # Send request. headers = { 'Content-Type': 'application/json', 'Authorization': f'Bearer {api_key}' } data = { "model":"deepseek-v3", # 模型名称 "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "你好"} ] } 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://api.modelarts-maas.com/v1/chat/completions" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $MAAS_API_KEY" \ -d '{ "model": "deepseek-v3", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "你好"} ] }'
- Python请求示例：
- OpenAI SDK请求示例：
from openai import OpenAI base_url = "https://api.modelarts-maas.com/v1" # API地址 api_key = "MAAS_API_KEY" # 把MAAS_API_KEY替换成已获取的API Key client = OpenAI(api_key=api_key, base_url=base_url) response = client.chat.completions.create( model="deepseek-v3", # 模型名称 messages=[ {"role": "system", "content": "You are a helpful assistant"}, {"role": "user", "content": "你好"} ] ) print(response.choices[0].message.content)
文本生成（流式）请求示例
- Python请求示例：
from openai import OpenAI base_url = "https://api.modelarts-maas.com/v1" # API地址 api_key = "MAAS_API_KEY" # 把MAAS_API_KEY替换成已获取的API Key client = OpenAI(api_key=api_key, base_url=base_url) response = client.chat.completions.create( model="deepseek-v3", # 模型名称 messages=[ {"role": "system", "content": "You are a helpful assistant"}, {"role": "user", "content": "你好"} ], stream = True ) for chunk in response: if not chunk.choices: continue print(chunk.choices[0].delta.content, end="") - cURL请求示例：
curl -X POST "https://api.modelarts-maas.com/v1/chat/completions" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $MAAS_API_KEY" \ -d '{ "model": "deepseek-v3", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "你好"} ], "stream": true, "stream_options": { "include_usage": true } }'
图像理解（非流式）请求示例
- Rest API请求示例：
- 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://api.modelarts-maas.com/v1/chat/completions" # API地址 api_key = "MAAS_API_KEY" # 把MAAS_API_KEY替换成已获取的API Key # Send request. headers = { 'Content-Type': 'application/json', 'Authorization': f'Bearer {api_key}' } data = { "model": "qwen2.5-vl-7b", # model参数 "messages": [ { "role": "user", "content": [ { "type": "text", "text": "描述下图片里的内容" }, { "type": "image_url", # 需要注意，Base64，图像格式（即image/{format}）需要与支持的图片列表中的Content Type保持一致。"f"是字符串格式化的方法。 # PNG图像： f"data:image/png;base64,{base64_image}" # JPEG图像： f"data:image/jpeg;base64,{base64_image}" # WEBP图像： f"data:image/webp;base64,{base64_image}" "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://api.modelarts-maas.com/v1/chat/completions" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $MAAS_API_KEY" \ -d '{ "model": "qwen2.5-vl-72b", "messages": [ { "role": "user", "content": [ {"type": "text", "text": "描述下图片里的内容"}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,$BASE64_IMAGE"}} ] } ] }'
- Python请求示例：
- OpenAI SDK请求示例：
import base64 from openai import OpenAI base_url = "https://api.modelarts-maas.com/v1" # API地址 api_key = "MAAS_API_KEY" # 把MAAS_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 = "qwen2.5-vl-72b", # model参数 messages = [ { "role": "user", "content": [ {"type": "text", "text": "描述下图片里的内容"}, { "type": "image_url", # 需要注意，Base64，图像格式（即image/{format}）需要与支持的图片列表中的Content Type保持一致。"f"是字符串格式化的方法。 # PNG图像： f"data:image/png;base64,{base64_image}" # JPEG图像： f"data:image/jpeg;base64,{base64_image}" # WEBP图像： f"data:image/webp;base64,{base64_image}" "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-R1",
"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
}
