# 推理服务_HTTP协议
# 1. 接口说明
协议 :HTTP 请求方法:POST 默认请求地址如下: (请根据服务发布时间及在线推理页面展示,选择对应的接口地址)
https://maas-api.cn-huabei-1.xf-yun.com/v2(2026年1月10日及后发布服务的用户,请直接使用此新地址)
http://maas-api.cn-huabei-1.xf-yun.com/v1(2026年1月10日前已发布服务的存量用户,无需修改接口地址,仍可继续使用旧地址)
部分模型因为部署原因可能略有差异,具体可参考服务管控 > 模型服务列表右侧调用信息。技术咨询可直接提交工单 (opens new window)
# 2. 接口请求
# 2.1 请求示例
下面是一个通用的 HTTP 请求 Python Demo 示例,展示了包括普通对话、流式对话和 JSON Mode 在内的多种调用方式。
from openai import OpenAI
# 必填:从服务管控页面获取对应服务的APIKey和API Base
api_key = "<YOUR_API_KEY>"
api_base = "http://maas-api.cn-huabei-1.xf-yun.com/v1"
client = OpenAI(api_key=api_key, base_url=api_base)
def unified_chat_test(model_id, messages, use_stream=False, extra_body={}):
"""
一个统一的函数,用于演示多种调用场景。
:param model_id: 要调用的模型ID。
:param messages: 对话消息列表。
:param use_stream: 是否使用流式输出。
:param extra_body: 包含额外请求参数的字典,如 response_format。
"""
try:
response = client.chat.completions.create(
model=model_id,
messages=messages,
stream=use_stream,
temperature=0.7,
max_tokens=4096,
extra_headers={"lora_id": "0"}, # 调用微调大模型时,对应替换为模型服务卡片上的resourceId
stream_options={"include_usage": True},
extra_body=extra_body
)
if use_stream:
# 处理流式响应
full_response = ""
print("--- 流式输出 ---")
for chunk in response:
if hasattr(chunk.choices[0].delta, 'content') and chunk.choices[0].delta.content:
content = chunk.choices[0].delta.content
print(content, end="", flush=True)
full_response += content
print("\n\n--- 完整响应 ---")
print(full_response)
else:
# 处理非流式响应
print("--- 非流式输出 ---")
message = response.choices[0].message
print(message.content)
except Exception as e:
print(f"请求出错: {e}")
if __name__ == "__main__":
model_id = "<YOUR_MODEL_ID>" # 必填:调用大模型时,对应为推理服务的模型卡片上对应的modelId
# 1. 普通非流式调用
print("********* 1. 普通非流式调用 *********")
plain_messages = [{"role": "user", "content": "你好,请介绍一下自己。"}]
unified_chat_test(model_id, plain_messages, use_stream=False)
# 2. 普通流式调用
print("\n********* 2. 普通流式调用 *********")
stream_messages = [{"role": "user", "content": "写一首关于夏天的诗。"}]
unified_chat_test(model_id, stream_messages, use_stream=True)
# 3. JSON Mode 调用
print("\n********* 3. JSON Mode 调用 *********")
json_messages = [{"role": "user", "content": "请给我一个关于上海的JSON对象,包含城市名称(city)和人口数量(population)。"}]
json_extra_body = {
"response_format": {"type": "json_object"},
"search_disable": True # JSON Mode下建议关闭搜索
}
unified_chat_test(model_id, json_messages, use_stream=False, extra_body=json_extra_body)
# 4. 测试stop和前缀续写功能
print("\n********* 4. 测试stop和前缀续写功能 *********")
print("设置stop词: ['。', '!'] - 模型遇到句号或感叹号时会停止生成")
stream_messages = [{"role": "user", "content": "给我解释下1加1等于多少。"}]
unified_chat_test(model_id, stream_messages, use_stream=True, extra_body={"stop": ["。","!"],"continue_final_message":True})
# 5. Tools/Function Calling 调用示例
print("\n********* 5. Tools/Function Calling 调用示例 *********")
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "获取指定城市的天气信息",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市名称,例如:北京、上海"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "温度单位"
}
},
"required": ["location"]
}
}
}
]
tool_messages = [{"role": "user", "content": "北京今天天气怎么样?"}]
response = client.chat.completions.create(
model=model_id,
messages=tool_messages,
tools=tools,
tool_choice="auto"
)
message = response.choices[0].message
if message.tool_calls:
print(f"模型请求调用工具: {message.tool_calls[0].function.name}")
print(f"参数: {message.tool_calls[0].function.arguments}")
else:
print(message.content)
注意:在使用demo之前,请务必替换 api_key 为您的API Key。
# 2.2 请求参数
| 参数 | 类型 | 是否必填 | 要求 | 说明 |
|---|---|---|---|---|
| model | string | 是 | 指定要调用的对话生成模型ID | |
| messages | array | 是 | [{"role": "user", "content":"用户输入内容"}] | 表示对话上下文的消息列表,支持多轮对话交互。其中,role 用于标识消息发送方(例如 user 表示用户、assistant 表示模型回复),content 则为实际文本内容。 注意:仅限DeepSeekV3&R1使用对话前缀续写时,用户需确保 messages 列表里最后一条消息的 role 为 assistant |
| stream | boolean | 否 | 取值为 true 或 false,默认值为 false | 指定是否采用流式响应模式。若设置为 true,系统将逐步返回生成的回复内容;否则,将一次性返回完整响应 |
| temperature | float | 否 | 取值为[0,1],默认值为0.7 | 核采样阈值。用于决定结果随机性,取值越高随机性越强即相同的问题得到的不同答案的可能性越高 |
| max_tokens | int | 否 | 取值为[1,32768],默认值为2048 | 限制生成回复的最大 token 数量,不同模型限制生成内容的最大 token 数有差异,DeepSeekV3&R1 支持最大 32k,其他模型默认上限 8K。 |
| reasoning_effort | string | 否 | low, medium, high, 默认high | 指导模型在对提示做出响应之前应生成多少推理内容。low 优先考虑速度和节省token,high 优先考虑更完整的推理。仅针对OpenAI开源的OSS模型生效。注意:使用 OpenAI SDK 时,此参数需放在 extra_body 对象中。 |
lora_id | string | 否 | 调用微调模型时使用,对应模型服务卡片上的 resourceId。注意:使用 OpenAI SDK 时,此参数需放在 extra_headers 对象中。 | |
| stop | string[] | 否 | 仅限DeepSeekV3&R1支持 | 模型遇到 stop 字段所指定的字符串时将停止继续生成,这个词语本身不会输出。最多支持4个字符串如["你好”,"天气”] |
| continue_final_message | boolean | 否 | 仅限DeepSeekV3&R1支持,取值为 true 或 false,默认值为 false | 指定是否开启对话前缀续写功能,若设置为true,系统将对 messages 列表里最后一条消息的 role 为 assistant的内容进行续写。 |
search_disable | boolean | 否 | true 或 false,默认 true | 关闭联网搜索。注意:使用 OpenAI SDK 时,此参数需放在 extra_body 对象中。 |
show_ref_label | boolean | 否 | 默认为 false。true 表示在联网搜索时返回信源信息。注意:使用 OpenAI SDK 时,此参数需放在 extra_body 对象中。 | |
enable_thinking | boolean | 否 | 默认为 false。true 表示开启深度思考模式(仅部分模型支持)。注意:使用 OpenAI SDK 时,此参数需放在 extra_body 对象中。 | |
response_format | object | 否 | 用于指定模型的输出为 JSON 对象格式。设置为 {"type": "json_object"} 即可。仅支持 DeepSeek R1 和 V3 模型。详情见 2.2.2 response_format 参数说明。 | |
| tools | array | 否 | 工具列表,支持 function 类型的工具定义 | 模型可能会调用的工具列表,用于 Function Calling 功能。注意:目前仅支持 DeepSeek V3.2 和 GLM-4.7 系列模型。详情见 2.2.3 tools 参数说明。 |
| tool_choice | string | 否 | auto、none、required,默认为 auto | 控制模型如何选择和使用工具。auto 表示模型自主决策;none 表示禁用工具调用;required 表示必须调用至少一个工具。 |
| stream_options | object | 否 | 默认值为{"include_usage": True} | 针对流式响应模式的扩展配置,如控制是否在响应中包含API调用统计信息等附加数据。 |
# 2.2.1 messages 参数说明
messages 参数用于传递对话内容,包括用户输入和 AI 回复
| 字段 | 含义 | 数据类型 | 取值范围 | 默认值 | 说明 |
|---|---|---|---|---|---|
| role | 角色 | string | system,user,assistant,tool | 通过system设置对话背景信息,user表示用户的问题,assistant表示AI的回复,tool表示工具调用的返回结果 | |
| content | 文本内容 | string or array | -- | 该角色的对话内容。支持字符串格式或数组格式。数组格式可用于传递多模态内容(如文本和图片的组合),数组中的每个元素可以是文本对象 {"type": "text", "text": "内容"} 或其他类型的内容对象 |
示例:单轮交互 单轮交互只需要传递一个user角色的数据
[
{"role": "user", "content": "你会做什么?"}
]
示例:多轮交互 多轮交互需要将之前的交互历史按照user->assistant->user->assistant规则进行拼接,并保证最后一条是user的当前问题。
[
{"role": "system", "content": "你是一个乐于助人的AI助手。"},
{"role": "user", "content": "你好,你是谁?"},
{"role": "assistant", "content": "我是AI助手,有什么可以帮您?"},
{"role": "user", "content": "你会做什么?"}
]
示例:content 数组格式 content 字段支持数组格式,可用于传递多模态内容或结构化内容。
[
{
"role": "user",
"content": [
{"type": "text", "text": "请分析这张图片"},
{"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
]
}
]
示例:工具调用交互 当使用 tools 功能时,需要在 messages 中包含 tool 角色的消息,用于传递工具执行结果。
[
{"role": "user", "content": "北京今天天气怎么样?"},
{
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_123",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"location\": \"北京\"}"
}
}
]
},
{
"role": "tool",
"content": "北京今天晴天,温度25度",
"tool_call_id": "call_123"
}
]
# 2.2.2 response_format 参数说明
response_format 参数用于强制模型输出严格符合 RFC 8259 规范的 JSON 对象。
开启方法
将 response_format 参数设置为 {"type": "json_object"}。
功能优势
- 可靠性:确保模型输出的是一个语法正确的 JSON 对象。
- 简化开发:无需在 prompt 中反复强调输出 JSON,也无需对模型输出进行复杂的后处理和校验。
支持模型
目前仅 DeepSeek R1 和 V3 模型支持 json_object 模式。
Prompt 建议
为了让模型更好地理解您的意图并生成符合期望的 JSON,建议在 Prompt 中明确指示模型输出 JSON。例如:
[
{"role": "user", "content": "请给我一个关于上海的JSON对象,包含城市名称(city)和人口数量(population)。"}
]
错误处理
如果 Prompt 的内容与 JSON 输出要求存在冲突,或模型无法生成有效的 JSON,可能会导致输出不完整或返回错误。请确保 Prompt 的引导内容清晰、无歧义。
# 2.2.3 tools 参数说明
tools 参数用于定义模型可以调用的工具列表,支持 Function Calling 功能。
支持模型
目前 tools 功能仅支持部分模型,暂时仅支持以下模型系列:
- DeepSeek V3.2 系列
- GLM-4.7 系列
其他模型暂不支持 tools 功能,使用不支持的工具功能可能会导致请求失败。
工具类型
目前支持 function 类型的工具,用于定义可被模型调用的函数。
工具定义格式
{
"type": "function",
"function": {
"name": "function_name",
"description": "函数的描述信息,帮助模型理解何时调用此函数",
"parameters": {
"type": "object",
"properties": {
"param_name": {
"type": "string",
"description": "参数描述"
}
},
"required": ["param_name"]
}
}
}
参数说明
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| type | string | 是 | 工具类型,目前支持 function |
| function | object | 是 | 函数定义对象 |
| function.name | string | 是 | 函数名称,必须是字母、数字或下划线组成,长度不超过32个字符 |
| function.description | string | 是 | 函数功能描述,用于帮助模型判断何时调用此函数 |
| function.parameters | object | 是 | 函数参数定义,必须符合 JSON Schema 格式,用于描述函数所需的参数及其类型 |
tool_choice 参数说明
tool_choice 参数用于控制模型如何选择和使用工具:
auto(默认):模型自主决策是否调用工具none:禁用工具调用功能required:要求模型必须调用至少一个工具
使用示例
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "获取指定城市的天气信息",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市名称"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "温度单位"
}
},
"required": ["location"]
}
}
}
]
response = client.chat.completions.create(
model=model_id,
messages=[{"role": "user", "content": "北京今天天气怎么样?"}],
tools=tools,
tool_choice="auto"
)
注意事项
- 当模型决定调用工具时,响应中的
message.tool_calls字段会包含工具调用信息 - 需要在后续请求中将工具执行结果以
tool角色的消息添加到messages中 tool角色的消息需要包含tool_call_id字段,对应tool_calls中的id
# 3. 接口响应
# 3.1 响应示例
# 3.1.1 成功响应示例
关闭联网检索或不返回检索信源时,返回结构如下:
Response: ChatCompletion(
id='cht000b920a@dx194e0205ccbb8f3700',
choices=[
Choice(
finish_reason='stop',
index=0,
logprobs=None,
message=ChatCompletionMessage(
content='大模型回复',
refusal=None,
role='assistant',
audio=None,
function_call=None,
tool_calls=None
)
)
],
created=1738927005,
model=None,
object='chat.completion',
service_tier=None,
system_fingerprint=None,
usage=CompletionUsage(
completion_tokens=42,
prompt_tokens=44,
total_tokens=86,
completion_tokens_details=None,
prompt_tokens_details=None
)
开启联网检索且返回检索信源时,返回结构如下:
ChatCompletion(
id='cht000b8e42@dx19590107ba3b8f2700',
choices=[
Choice(
finish_reason='stop',
index=0,
logprobs=None,
message=ChatCompletionMessage(
content='大模型回复',
refusal=None,
role='assistant',
audio=None,
function_call=None,
tool_calls=None,
reasoning_content='',
plugins_content=[
{
'name': 'ifly_search',
'content': '[{"index":1,"url":"https://xxx.com/xxx/doc.html","title":"信源标题"}]'
}
]
)
)
],
created=1741878776,
model='xdeepseekv3',
object='chat.completion',
service_tier=None,
system_fingerprint=None,
usage=CompletionUsage(
completion_tokens=346,
prompt_tokens=1124,
total_tokens=1470,
completion_tokens_details=None,
prompt_tokens_details=None
)
)
调用工具(Function Calling)时,返回结构如下:
ChatCompletion(
id='cht000b8e43@dx19590107ba3b8f2701',
choices=[
Choice(
finish_reason='tool_calls',
index=0,
logprobs=None,
message=ChatCompletionMessage(
content=None,
refusal=None,
role='assistant',
audio=None,
function_call=None,
tool_calls=[
ChatCompletionMessageToolCall(
id='call_123',
type='function',
function=Function(
name='get_weather',
arguments='{"location": "北京"}'
)
)
],
reasoning_content='',
plugins_content=None
)
)
],
created=1741878777,
model='xopdeepseekv32',
object='chat.completion',
service_tier=None,
system_fingerprint=None,
usage=CompletionUsage(
completion_tokens=15,
prompt_tokens=120,
total_tokens=135,
completion_tokens_details=None,
prompt_tokens_details=None
)
)
# 3.1.2 异常结果示例
Error: Error code: 403 - {'error': {'message': '该令牌无权使用模型:xqwen257bxxx (request id: 2025020809381060443349905703260)', 'type': 'one_api_error'}}
# 3.2 响应数据参数
字段说明如下:
| 字段名 | 类型 | 字段说明 |
|---|---|---|
| id | string | 唯一标识符,标识本次对话调用的唯一ID,用于跟踪和调试 |
| choices | array | 包含模型生成回复候选项的数组 |
| •finish_reason | string | 指示回复生成结束的原因,如"stop"(正常结束)、"tool_calls"(需要调用工具)、"length"(达到最大长度限制)等 |
| •index | int | 回复候选项在数组中的索引位置,从0开始 |
| •logprobs | object | 如启用token概率日志,则返回具体信息 |
| •message | object | 描述回复消息内容的对象,其内部字段如下 |
| ◦content | string | 模型生成的回复文本内容 |
| ◦reasoning_content | string | 模型生成的思考文本内容(支持深度思考的模型才有此字段) |
| ◦plugins_content | array | 联网检索的信源结果列表(支持联网检索的模型才有此字段) |
| ◦name | string | 联网检索插件名称ifly_search等 |
| ◦name | string | 联网检索插件结果,此为信源结果列表,index序号,url信源地址,title信源标题 |
| ◦refusal | object | 模型拒绝回答时返回拒绝信息 |
| ◦role | string | 消息发送方,通常为"assistant" |
| ◦audio | object | 如支持语音回复则返回音频数据 |
| ◦function_call | object | 模型调用外部函数时返回调用信息(已废弃,建议使用 tool_calls) |
| ◦tool_calls | array | 模型调用工具时返回调用详情,包含工具调用列表。每个工具调用包含 id(调用标识)、type(类型,通常为 function)、function(函数信息,包含 name 和 arguments) |
| created | int | 响应生成时间的Unix时间戳(秒级) |
| model | string | 实际调用的模型名称 |
| object | string | 表示响应对象类型 |
| service_tier | string | 表示调用所属的服务层级 |
| system_fingerprint | string | 系统指纹或配置标识 |
| usage | object | 包含token使用统计信息,其内部字段如下: |
| •completion_tokens | int | 回复文本消耗的token数量 |
| •prompt_tokens | int | 输入prompt消耗的token数量 |
| •total_tokens | int | prompt与回复消耗token数量的总和 |
| •completion_tokens_details | object | 回复生成过程中token的详细统计信息,若无则为null |
| •prompt_tokens_details | object | prompt部分token的详细统计信息 |
# 4 . 错误码列表
| 错误码 | 原因 | 解决方案 |
|---|---|---|
| 401-无效的身份验证 | 身份验证无效。 | 确保使用正确的API密钥及请求组织。 |
| 401-提供的API密钥不正确 | 请求的API密钥不正确。 | 检查所用API密钥是否正确,清除浏览器缓存或生成新的密钥。 |
| 403-不支持的国家、地区或领土 | 您正在从不支持的国家、地区或领土访问API。 | 请参考相关页面获取更多信息。 |
| 429-请求速率限制已达上限 | 您发送请求过快。 | 控制请求频率,阅读速率限制指南。 |
| 429-超出当前配额,请检查计划和计费详情 | 您的额度已用尽或已达到每月最高消费限制。 | 购买更多额度或了解如何提高使用限制。 |
| 500-服务器处理请求时发生错误 | 服务器内部出现问题。 | 稍后重试请求;若问题持续,请联系我们查看状态页面。 |
| 503-引擎当前过载,请稍后重试 | 服务器流量过大。 | 稍候重试您的请求。 |