通义千问通用对话接口文档

概述

本文档介绍如何通过 gravitex 的 OpenAI 兼容接口调用通义千问（Qwen）对话模型，支持深度思考（enable_thinking）、搜索与语音识别等扩展参数的透传与规范放置。

基础信息

项目	内容
Base URL	`https://api.gravitex.ai/v1/chat/completions`
认证方式	API Key (Token)
请求头	`Authorization: Bearer sk-xxxx`、`Content-Type: application/json`

参考通义千问官方对话 API（扩展参数需放入 parameters）：https://bailian.console.aliyun.com/?tab=api#/api/?type=model&url=2712576

支持的模型（示例）

qwen3-omni-flash

其他通义千问对话模型（按你在控制台中开启的路由为准）

API 接口

1. 最小示例（非流式）

2. 开启深度思考（流式 SSE）

深度思考需要流式输出配合：enable_thinking: true 且 stream: true

若你设置了 enable_thinking: true 但 stream: false，为避免上游报错，系统会自动关闭深度思考

可选：将推理过程内联到 content

加开关："gravitex_thinking_to_content": true（仅影响下行展示，不透传上游、不影响计费）

效果：推理内容会以 <think>...</think> 包裹，并与普通内容共同出现在 content 中，适合仅展示 content 的终端或 SDK

3. Qwen 扩展参数放置规范

所有通义千问扩展参数需放入 parameters 对象：

推理/搜索：enable_thinking、incremental_output、search_options、enable_search

语音识别：asr_options

采样/控制：temperature、top_p、top_k、seed、stop、max_tokens

约束/惩罚：presence_penalty、frequency_penalty 等（以官方文档为准）

结构化输出：response_format（text/json_object/json_schema）、json_schema

示例：

响应与用量说明

流式：以 SSE 分片返回，末尾可能包含 usage；上游通常不提供 reasoning_tokens 明细，故即使开启深度思考该值也可能为 0

非流式：一次性返回文本；与 enable_thinking: true 同用时，为避免上游报错会自动关闭深度思考

示例（任一分片）：

{
  "id": "chatcmpl-...",
  "object": "chat.completion.chunk",
  "created": 1762153960,
  "model": "qwen3-omni-flash",
  "choices": [ ... ],
  "usage": {
    "prompt_tokens": 53,
    "completion_tokens": 2123,
    "total_tokens": 2176,
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

常见问题（FAQ）

开了深度思考没看到过程？

请确认 stream: true；若客户端不展示 reasoning_content，可加 gravitex_thinking_to_content: true 让推理内联到 content。

为什么 reasoning_tokens 为 0？

兼容模式下上游常不返回推理 token 明细，我们不会臆测拆分，显示为 0 属正常。

报错 “This model does not support non-streaming output.”？

深度思考需要流式输出，请改为 stream: true 或移除 enable_thinking。

最佳实践

合理设置 top_p/top_k/temperature，并结合 incremental_output 提升交互体验

搜索/ASR 参数一律放在 parameters；错误地放在顶层会被自动规整，但建议按规范传参

流式下前端请使用事件流解析，注意最后一个包含 usage 的分片

通义千问通用对话接口文档

概述#

基础信息#

支持的模型（示例）#

API 接口#

1. 最小示例（非流式）#

2. 开启深度思考（流式 SSE）#

可选：将推理过程内联到 content#

3. Qwen 扩展参数放置规范#

响应与用量说明#

常见问题（FAQ）#

最佳实践#

概述