OpenAI 兼容文本与视觉模型

本文说明阿里云百炼文本模型、推理模型、第三方文本模型和视觉理解模型在 AI Gateway 中的 OpenAI Chat Completions 调用方式。

一、适用模型

模型家族	模型示例	典型场景
Qwen Max / Plus / Flash	`qwen3.7-max` qwen3.7-max 、 `qwen3.6-max-preview` qwen3.6-max-preview 、 `qwen3-max` qwen3-max 、 `qwen3.6-plus` qwen3.6-plus 、 `qwen3.5-plus` qwen3.5-plus 、 `qwen3.6-flash` qwen3.6-flash 、 `qwen3.5-flash` qwen3.5-flash	通用问答、内容生成、代码、知识库、复杂分析
MiniMax	`MiniMax/MiniMax-M2.7` MiniMax/MiniMax-M2.7 、 `MiniMax-M2.5` MiniMax-M2.5	长文本生成、内容创作、通用对话
DeepSeek	`deepseek-r1` deepseek-r1 、 `deepseek-v3.2` deepseek-v3.2 、 `deepseek-v4-flash` deepseek-v4-flash 、 `deepseek-v4-pro` deepseek-v4-pro	推理、代码、数学、复杂分析
GLM	`glm-4.7` glm-4.7 、 `glm-5` glm-5 、 `glm-5.1` glm-5.1	通用问答、多轮对话、企业知识库
Kimi	`kimi-k2.5` kimi-k2.5 、 `kimi-k2.6` kimi-k2.6	长上下文、文档理解、文本处理

二、请求地址

POST https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/chat/completions

请求头：

Authorization: Bearer <API_KEY> Content-Type: application/json

三、基础请求示例

curl -X POST "https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/chat/completions" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen/qwen3.7-max", "messages": [ { "role": "system", "content": "你是一个专业、准确、简洁的企业 AI 助手。" }, { "role": "user", "content": "请说明 AI Gateway 在企业模型治理中的价值。" } ], "temperature": 0.7, "top_p": 0.8, "max_tokens": 1024, "stream": false }'

Python 示例：

from openai import OpenAI client = OpenAI( base_url="https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1", api_key="<your-api-key>", ) completion = client.chat.completions.create( model="qwen/qwen3.7-max", messages=[ {"role": "system", "content": "你是一个专业、准确、简洁的企业 AI 助手。"}, {"role": "user", "content": "请说明 AI Gateway 在企业模型治理中的价值。"}, ], temperature=0.7, top_p=0.8, max_tokens=1024, ) print(completion.choices[0].message.content)

四、请求字段

字段	类型	必填	说明
`model` model	string	是	模型名称。请以模型广场详情页复制的模型标识为准，例如 `qwen/qwen3.7-max` qwen/qwen3.7-max 、 `deepseek-v4-pro` deepseek-v4-pro 。
`messages` messages	array	是	对话消息列表，按时间顺序排列。每条消息包含 `role` role 和 `content` content 。
`stream` stream	boolean	否	是否使用流式输出。 `true` true 表示以 SSE 方式逐步返回增量内容。
`stream_options` stream_options	object	否	流式输出配置。常用字段为 `include_usage` include_usage ，用于在流式响应末尾返回 Token 用量。
`temperature` temperature	number	否	采样温度。值越高，输出越随机；值越低，输出越稳定。
`top_p` top_p	number	否	核采样参数。通常不要同时大幅调整 `temperature` temperature 和 `top_p` top_p 。
`max_tokens` max_tokens	integer	否	本次响应最多生成的 Token 数。
`stop` stop	string / array	否	停止生成的字符串。模型生成到指定内容时停止。
`presence_penalty` presence_penalty	number	否	话题重复惩罚。值越高，模型越倾向于引入新内容。
`frequency_penalty` frequency_penalty	number	否	词频重复惩罚。值越高，越减少重复词句。
`n` n	integer	否	返回候选结果数量。生产环境通常使用默认值 `1` 1 。
`seed` seed	integer	否	随机种子。用于提升同参数下输出的可复现性；不同模型支持程度可能不同。
`response_format` response_format	object	否	结构化输出配置。常用于要求模型输出 JSON。
`tools` tools	array	否	工具列表。用于函数调用、工具调用等场景。
`tool_choice` tool_choice	string / object	否	工具选择策略，例如 `auto` auto 、 `none` none 或指定某个工具。
`parallel_tool_calls` parallel_tool_calls	boolean	否	是否允许并行工具调用。是否生效取决于模型能力。
`logprobs` logprobs	boolean	否	是否返回 Token 对数概率。是否支持取决于模型。
`top_logprobs` top_logprobs	integer	否	返回每个 Token 的候选概率数量。需要模型支持 `logprobs` logprobs 。
`extra_body` extra_body	object	否	SDK 中传递厂商扩展字段的方式。不同模型支持的扩展字段不同。

建议：

需要稳定、可控输出时，将
```
temperature
```
temperature
设置为
```
0
```
0
到
```
0.3
```
0.3
。
需要创意生成时，可将
```
temperature
```
temperature
设置为
```
0.7
```
0.7
到
```
1.0
```
1.0
。
生产环境建议明确设置
```
max_tokens
```
max_tokens
，避免生成过长导致费用和延迟不可控。
```
seed
```
seed
、
```
logprobs
```
logprobs
、
```
parallel_tool_calls
```
parallel_tool_calls
等字段不是所有模型都支持，接入时应先用目标模型验证。

五、messages 字段

messages

messages

是对话上下文数组。常见

role

role

如下：

role	说明
`system` system	系统指令，用于设定模型身份、任务边界、输出格式和安全约束。
`user` user	用户输入。
`assistant` assistant	模型历史回复。用于多轮对话时传入上下文。
`tool` tool	工具返回结果。用于工具调用闭环。

文本消息示例：

{ "role": "user", "content": "请把下面内容改写成正式公告。" }

多轮对话示例：

{ "model": "qwen/qwen3.7-max", "messages": [ {"role": "system", "content": "你是企业知识库助手，回答必须引用已知信息。"}, {"role": "user", "content": "AI Gateway 支持哪些路由策略？"}, {"role": "assistant", "content": "支持价格优先、吞吐优先、延迟优先等策略。"}, {"role": "user", "content": "请补充 BYOK 不可用时的降级逻辑。"} ] }

六、流式输出

流式输出适合聊天、长文本生成、代码生成等场景，可以降低首字延迟。

curl -N -X POST "https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/chat/completions" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen/qwen3.7-max", "messages": [ {"role": "user", "content": "请分步骤说明如何设计模型调用灰度策略。"} ], "stream": true, "stream_options": { "include_usage": true } }'

流式响应通常以多段

data:

data:

事件返回。客户端需要逐行读取 SSE 数据，并在收到结束事件后关闭连接。

Python 流式示例：

from openai import OpenAI client = OpenAI( base_url="https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1", api_key="<your-api-key>", ) stream = client.chat.completions.create( model="qwen/qwen3.7-max", messages=[{"role": "user", "content": "请写一个模型路由策略说明。"}], stream=True, stream_options={"include_usage": True}, ) for chunk in stream: if chunk.choices and chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="")

七、JSON 结构化输出

当业务需要稳定解析模型输出时，建议使用

response_format

response_format

要求返回 JSON。

curl -X POST "$AI_GATEWAY_OPENAI_BASE_URL/chat/completions" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen/qwen3.7-max", "messages": [ { "role": "system", "content": "你只输出合法 JSON，不要输出 Markdown。" }, { "role": "user", "content": "抽取以下工单的优先级、问题类型和一句话摘要：数据库查询超时，影响线上报表。" } ], "response_format": { "type": "json_object" } }'

注意：

即使使用
```
response_format
```
response_format
，也建议在
```
system
```
system
或
```
user
```
user
中明确输出字段。
JSON 模式是否可用取决于模型能力；如果目标模型不支持，应使用提示词约束并在业务侧做 JSON 校验。

八、工具调用

工具调用适合让模型决定是否调用外部函数，例如查库存、查订单、检索知识库、执行 SQL 等。

请求示例：

{ "model": "qwen/qwen3.7-max", "messages": [ { "role": "user", "content": "查询订单 202606150001 的物流状态。" } ], "tools": [ { "type": "function", "function": { "name": "get_order_status", "description": "根据订单号查询物流状态", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "订单号" } }, "required": ["order_id"] } } } ], "tool_choice": "auto" }

典型处理流程：

客户端发送用户问题和工具定义。
模型返回
```
tool_calls
```
tool_calls
，说明要调用的函数名和参数。
业务系统执行真实函数。
将工具结果以
```
role: "tool"
```
role: "tool"
的消息再次发送给模型。
模型基于工具结果生成最终回答。

并非所有模型都支持工具调用；使用前请在模型详情页确认。

九、视觉理解

支持视觉输入的模型可以在

messages.content

messages.content

中同时传入文本和图片。

curl -X POST "$AI_GATEWAY_OPENAI_BASE_URL/chat/completions" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen/qwen3.6-plus", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "请识别图片中的商品，并输出 JSON：商品类型、颜色、是否有文字。" }, { "type": "image_url", "image_url": { "url": "https://example.com/product.png" } } ] } ], "response_format": { "type": "json_object" } }'

图片输入字段：

字段	类型	必填	说明
`type` type	string	是	固定为 `image_url` image_url 。
`image_url.url` image_url.url	string	是	图片地址。可以使用公网 URL；是否支持 Base64 Data URL 取决于模型能力。
`image_url.detail` image_url.detail	string	否	图片细节级别。是否支持取决于模型能力。

注意：

图片 URL 必须能被模型服务访问。
不要传入本地路径，例如
```
/Users/a123/image.png
```
/Users/a123/image.png
。
视觉理解模型和纯文本模型的模型名不同，调用前请确认模型详情页是否支持图片输入。
图片数量、大小、格式限制以模型详情页为准。

十、响应字段

典型非流式响应结构如下：

{ "id": "chatcmpl-xxx", "object": "chat.completion", "created": 1710000000, "model": "qwen/qwen3.7-max", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "AI Gateway 可以统一管理多模型接入、路由、鉴权和用量统计。" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 32, "completion_tokens": 24, "total_tokens": 56 } }

字段	说明
`id` id	本次请求 ID。排查问题时可结合响应头或错误信息提供给管理员。
`choices` choices	候选结果列表。通常读取 `choices[0].message.content` choices[0].message.content 。
`finish_reason` finish_reason	结束原因，例如正常结束、达到长度限制、触发工具调用等。
`usage.prompt_tokens` usage.prompt_tokens	输入 Token 数。
`usage.completion_tokens` usage.completion_tokens	输出 Token 数。
`usage.total_tokens` usage.total_tokens	输入和输出 Token 总数。

十一、常见问题

为什么同一个请求有时返回不同结果？

大模型默认存在采样随机性。需要更稳定的输出时，可以降低

temperature

temperature

，并在模型支持时设置

seed

seed

。

为什么设置了 JSON 输出仍然解析失败？

请同时在提示词中明确“只输出合法 JSON”，并在业务侧做 JSON 解析校验。部分模型可能不支持严格 JSON 模式。

为什么模型返回被截断？

通常是

max_tokens

max_tokens

过小或上下文过长。可以适当提高

max_tokens

max_tokens

，或减少历史消息长度。

为什么工具调用没有生效？

请确认目标模型支持工具调用，并检查

tools

tools

的 JSON Schema 是否完整、

tool_choice

tool_choice

是否正确。

联系我们