文本生成 - 千问云

文本生成模型接收自然语言输入，生成问答、写作、摘要、翻译、结构化输出等文本内容。

请求结构

文本生成请求通常以 messages 数组的形式发送，每条消息包含 role（角色）和 content（内容）两个字段。

System message：设定模型行为的全局指令。
User message：用户的输入或任务描述。
Assistant message：模型的回复内容。

一个典型的请求至少包含一条 user 消息，可选地附带一条 system 消息以获得更稳定、可控的输出。

system 消息非必需，但如果你希望模型表现更一致，建议添加。

[
  {"role": "system", "content": "You are a helpful assistant. Answer clearly and concisely."},
  {"role": "user", "content": "用三个要点概括太阳能的优势。"}
]

模型会以 assistant 消息返回回复。

{
  "role": "assistant",
  "content": "- 减少对化石燃料的依赖。\n- 降低长期用电成本。\n- 运行过程中几乎不产生排放。"
}

发起第一次调用

开始之前，请先获取 API Key、将其设为环境变量，并按需安装 OpenAI 或 DashScope SDK。根据你的技术栈选择合适的 API 风格：

新项目建议使用 OpenAI Compatible -- Responses API。
已有 OpenAI 兼容代码需要迁移时，使用 OpenAI Compatible -- Chat Completions API。
偏好原生 SDK 时，使用 DashScope。

OpenAI Compatible -- Responses API
OpenAI Compatible -- Chat Completions API
DashScope
DashScope -- Qwen3.5/3.6

接口说明、代码示例和迁移指南请参见 OpenAI compatible - Responses。

import os
from openai import OpenAI

try:
  client = OpenAI(
    # 如果未设置环境变量，请将下行替换为：api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1",
  )

  response = client.responses.create(
    model="qwen3.6-plus",
    input="用三个要点概括太阳能的优势。"
  )

  print(response)
except Exception as e:
  print(f"错误信息：{e}")

响应响应包含以下主要字段：

id：响应 ID。
output：输出列表，包含 reasoning（思考过程）和 message（回复内容）。
reasoning 字段仅在开启深度思考时出现（例如 Qwen3.5 和 Qwen3.6 系列默认开启）。
usage：Token 用量统计。

示例文本输出：

- 减少对化石燃料的依赖。
- 降低长期用电成本。
- 运行过程中几乎不产生排放。

完整 JSON 响应

{
  "created_at": 1772249518,
  "id": "7ad48c6b-3cc4-904f-9284-5f419c6c5xxx",
  "model": "qwen3.6-plus",
  "object": "response",
  "output": [
    {
      "id": "msg_94805179-2801-45da-ac1c-a87e8ea20xxx",
      "summary": [
        {
          "text": "The user wants a concise answer in exactly three bullet points. Focus on the most broadly useful benefits of solar energy: reduced reliance on fossil fuels, long-term cost savings, and lower operating emissions. Keep the wording simple and direct.\n",
          "type": "summary_text"
        }
      ],
      "type": "reasoning"
    },
    {
      "content": [
        {
          "annotations": [],
          "text": "- 减少对化石燃料的依赖。\n- 降低长期用电成本。\n- 运行过程中几乎不产生排放。",
          "type": "output_text"
        }
      ],
      "id": "msg_35be06c6-ca4d-4f2b-9677-7897e488dxxx",
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "parallel_tool_calls": false,
  "status": "completed",
  "tool_choice": "auto",
  "tools": [],
  "usage": {
    "input_tokens": 54,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 662,
    "output_tokens_details": {
      "reasoning_tokens": 447
    },
    "total_tokens": 716,
    "x_details": [
      {
        "input_tokens": 54,
        "output_tokens": 662,
        "output_tokens_details": {
          "reasoning_tokens": 447
        },
        "total_tokens": 716,
        "x_billing_type": "response_api"
      }
    ]
  }
}

import os
from openai import OpenAI

try:
  client = OpenAI(
    # 如果未设置环境变量，请将下行替换为：api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
  )

  completion = client.chat.completions.create(
    model="qwen3.6-plus",
    messages=[
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "用三个要点概括太阳能的优势。"},
    ],
  )
  print(completion.choices[0].message.content)
  # 查看完整响应，取消注释下行
  # print(completion.model_dump_json())
except Exception as e:
  print(f"错误信息：{e}")

响应

- 减少对化石燃料的依赖。
- 降低长期用电成本。
- 运行过程中几乎不产生排放。

完整 JSON 响应

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "- 减少对化石燃料的依赖。\n- 降低长期用电成本。\n- 运行过程中几乎不产生排放。"
      },
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null
    }
  ],
  "object": "chat.completion",
  "usage": {
    "prompt_tokens": 26,
    "completion_tokens": 66,
    "total_tokens": 92
  },
  "created": 1726127645,
  "system_fingerprint": null,
  "model": "qwen3.6-plus",
  "id": "chatcmpl-81951b98-28b8-9659-ab07-xxxxxx"
}

Qwen3.5 和 Qwen3.6 系列使用多模态接口（MultiModalConversation）。本标签页的示例使用 qwen-plus，仍通过 Generation 接口调用。如需使用 Qwen3.5/3.6，请参见 Qwen3.5/3.6 标签页。

import json
import os
from dashscope import Generation
import dashscope

dashscope.base_http_api_url = "https://dashscope.aliyuncs.com/api/v1"

messages = [
  {"role": "system", "content": "You are a helpful assistant."},
  {"role": "user", "content": "用三个要点概括太阳能的优势。"},
]
response = Generation.call(
  # 如果未设置环境变量，请将下行替换为：api_key = "sk-xxx",
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  model="qwen-plus",
  messages=messages,
  result_format="message",
)

if response.status_code == 200:
  print(response.output.choices[0].message.content)
  # 查看完整响应，取消注释下行
  # print(json.dumps(response, default=lambda o: o.__dict__, indent=4))
else:
  print(f"HTTP 状态码：{response.status_code}")
  print(f"错误码：{response.code}")
  print(f"错误信息：{response.message}")

响应

- 减少对化石燃料的依赖。
- 降低长期用电成本。
- 运行过程中几乎不产生排放。

完整 JSON 响应

{
  "output": {
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": "- 减少对化石燃料的依赖。\n- 降低长期用电成本。\n- 运行过程中几乎不产生排放。"
        }
      }
    ]
  },
  "usage": {
    "total_tokens": 92,
    "output_tokens": 66,
    "input_tokens": 26
  },
  "request_id": "09dceb20-ae2e-999b-85f9-xxxxxx",
  "model": "qwen-plus"
}

Qwen3.5 和 Qwen3.6 系列使用 MultiModalConversation 接口，而非 Generation。用户消息的 content 必须是对象数组。

import os
import dashscope
from dashscope import MultiModalConversation

dashscope.base_http_api_url = "https://dashscope.aliyuncs.com/api/v1"

messages = [
  {"role": "system", "content": "You are a helpful assistant."},
  {
    "role": "user",
    "content": [{"text": "用三个要点概括太阳能的优势。"}],
  },
]
response = MultiModalConversation.call(
  # 如果未设置环境变量，请将下行替换为：api_key="sk-xxx",
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  model="qwen3.6-plus",
  messages=messages,
)

if response.status_code == 200:
  print(response.output.choices[0].message.content[0]["text"])
  # 查看完整响应，取消注释下行
  # import json; print(json.dumps(response, default=lambda o: o.__dict__, indent=4))
else:
  print(f"HTTP 状态码：{response.status_code}")
  print(f"错误码：{response.code}")
  print(f"错误信息：{response.message}")

响应

- 减少对化石燃料的依赖。
- 降低长期用电成本。
- 运行过程中几乎不产生排放。

完整 JSON 响应

{
  "output": {
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": [
            {
              "text": "- 减少对化石燃料的依赖。\n- 降低长期用电成本。\n- 运行过程中几乎不产生排放。"
            }
          ]
        }
      }
    ]
  },
  "usage": {
    "input_tokens": 25,
    "output_tokens": 613,
    "total_tokens": 638
  },
  "request_id": "1486945b-ebc7-93a1-af4d-651f8e18e76f"
}

异步调用

同步调用跑通后，可通过异步调用提升高并发场景下的吞吐量。

OpenAI Compatible -- Chat Completions API
DashScope

import os
import asyncio
from openai import AsyncOpenAI
import platform

# 创建异步客户端实例
client = AsyncOpenAI(
  # 如果未设置环境变量，请将下行替换为：api_key="sk-xxx",
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"
)

# 定义异步任务
async def task(question):
  print(f"发送问题：{question}")
  response = await client.chat.completions.create(
    messages=[
      {"role": "user", "content": question}
    ],
    model="qwen3.6-plus",
  )
  print(f"模型回复：{response.choices[0].message.content}")

# 主异步函数
async def main():
  questions = [
    "用三个要点概括太阳能的优势。",
    "为产品发布邮件写一个主题行。",
    '将"欢迎使用我们的平台"翻译成西班牙语。'
  ]
  tasks = [task(q) for q in questions]
  await asyncio.gather(*tasks)

if __name__ == '__main__':
  # 设置事件循环策略
  if platform.system() == 'Windows':
    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
  # 运行主协程
  asyncio.run(main(), debug=False)

DashScope SDK 仅在 Python 中支持异步文本生成调用。

# DashScope Python SDK 版本须 >= 1.19.0
import asyncio
import platform
from dashscope.aigc.generation import AioGeneration
import os
import dashscope
dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

# 定义异步任务
async def task(question):
  print(f"发送问题：{question}")
  response = await AioGeneration.call(
    # 如果未设置环境变量，请将下行替换为：api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    model="qwen-plus",
    messages=[{"role": "system", "content": "You are a helpful assistant."},
                  {"role": "user", "content": question}],
    result_format="message",
  )
  print(f"模型回复：{response.output.choices[0].message.content}")

# 主异步函数
async def main():
  questions = [
    "用三个要点概括太阳能的优势。",
    "为产品发布邮件写一个主题行。",
    '将"欢迎使用我们的平台"翻译成西班牙语。'
  ]
  tasks = [task(q) for q in questions]
  await asyncio.gather(*tasks)

if __name__ == '__main__':
  # 设置事件循环策略
  if platform.system() == 'Windows':
    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
  # 运行主协程
  asyncio.run(main(), debug=False)

响应

由于调用是异步的，响应顺序可能与示例不同。

发送问题：用三个要点概括太阳能的优势。
发送问题：为产品发布邮件写一个主题行。
发送问题：将"欢迎使用我们的平台"翻译成西班牙语。
模型回复：- 减少对化石燃料的依赖。
- 降低长期用电成本。
- 运行过程中几乎不产生排放。
模型回复：Meet our newest product launch
模型回复：Bienvenido a nuestra plataforma.

生产优化

构建更优质的上下文

将原始数据直接输入大语言模型会因上下文长度限制导致成本上升、质量下降。上下文工程通过动态加载精准知识来提升输出质量和效率。核心技术包括：

Prompt 工程：设计和优化提示词，引导模型生成预期的输出。详见文本生成 Prompt 指南。
检索增强生成（RAG）：当模型需要基于产品文档、技术手册等外部知识库回答问题时使用。
工具调用：让模型获取天气、交通等实时数据，或执行调用 API、发送邮件等操作。
记忆机制：为模型提供短期和长期记忆，使其理解对话历史。

调整生成行为

temperature 和 top_p 参数控制生成文本的多样性。值越高，多样性越强；值越低，可预测性越高。建议每次只调整其中一个参数，以便准确评估效果。

temperature：取值范围 [0, 2)，用于调节随机性。
top_p：取值范围 (0, 1.0]，按概率阈值过滤候选 Token。

以下示例展示不同参数设置对输出的影响。提示词为："写一个三句话的故事，主角是一只猫和一束阳光。"

高多样性（如 temperature=0.9）：适用于创意写作、头脑风暴或营销文案等需要新颖和想象力的场景。

阳光穿过窗户切开了午后，橘猫蹑手蹑脚走向那片金色方块，皮毛瞬间镀上蜂蜜般的光泽。
它用爪子轻拍光斑，沉入温暖之中，仿佛踏入了一汪日光池塘，金色的潮水沿脊背涌上来。
午后渐沉——猫蜷在液态黄金中，听见时间在它的呼噜声里悄悄融化。

高可预测性（如 temperature=0.1）：适用于事实问答、代码生成或法律文本等对准确性和一致性要求高的场景。

老猫趴在窗台上打盹，数着阳光。
日光跳过它斑驳的背脊，像翻动一本旧相册的页面。
灰尘升起又落下，低语：你曾经年轻，而我曾经炽烈。

原理说明

temperature：

较高的 temperature 使 Token 概率分布趋于平坦。高概率 Token 被选中的可能性降低，低概率 Token 的可能性升高，模型选择下一个 Token 时更具随机性。
较低的 temperature 使 Token 概率分布更加尖锐。高概率 Token 更容易被选中，低概率 Token 更不容易，模型倾向于选择高概率 Token。

top_p：Top-p 采样从概率最高的 Token 开始，累加概率直到超过指定阈值（如 0.8），然后从这个最小集合中随机选择一个 Token。

较高的 top_p 值纳入更多候选 Token，增加多样性。
较低的 top_p 值纳入更少候选 Token，增加聚焦性和可预测性。

常见场景的参数设置

# 不同场景的推荐参数设置
SCENARIO_CONFIGS = {
  # 创意写作
  "creative_writing": {
    "temperature": 0.9,
    "top_p": 0.95
  },
  # 代码生成
  "code_generation": {
    "temperature": 0.2,
    "top_p": 0.8
  },
  # 事实问答
  "factual_qa": {
    "temperature": 0.1,
    "top_p": 0.7
  },
  # 翻译
  "translation": {
    "temperature": 0.3,
    "top_p": 0.8
  }
}

# OpenAI 用法示例
# completion = client.chat.completions.create(
#     model="qwen3.6-plus",
#     messages=[{"role": "user", "content": "写一首关于月亮的诗"}],
#     **SCENARIO_CONFIGS["creative_writing"]
# )
# DashScope 用法示例
# response = Generation.call(
#     # 如果未设置环境变量，请将下行替换为：api_key = "sk-xxx",
#     api_key=os.getenv("DASHSCOPE_API_KEY"),
#     model="qwen-plus",
#     messages=[{"role": "user", "content": "写一个 Python 函数，检查输入的 n 是否为质数。只输出代码。"}],
#     result_format="message",
#     **SCENARIO_CONFIGS["code_generation"]
# )

探索更多文本生成功能

适用于复杂场景：

多轮对话：适用于追问、信息采集等需要连续对话的场景。
流式输出：适用于聊天机器人或实时代码生成，提升用户体验并避免长响应导致的超时。
深度思考：适用于复杂推理或政策分析等需要高质量结构化回答的场景。
结构化输出：当需要模型以稳定的 JSON 格式回复，用于程序化处理或数据解析时使用。
续写模式：适用于代码补全或长文写作，让模型从现有文本继续生成。

参考

完整的模型调用参数列表，请参见 OpenAI Compatible API 参考和 DashScope API 参考。

常见问题

为什么 Qwen API 无法解析网页链接？ Qwen API 无法直接访问或解析网页链接。你可以使用工具调用，或结合 Python Beautiful Soup 等网页抓取工具来读取网页内容。 为什么通义千问 Web 端和 API 的回复不同？ 通义千问 Web 端在 Qwen API 基础上做了额外的工程优化，支持网页解析、联网搜索、绘图、PPT 生成等功能。这些能力不属于大语言模型 API 本身，你可以通过工具调用来实现类似效果。 模型能直接生成 Word、Excel、PDF 或 PPT 文件吗？ 不能。千问云文本生成模型仅输出纯文本，你可以通过代码或第三方库将文本转换为所需格式。

​请求结构

​发起第一次调用

​异步调用

​生产优化

​构建更优质的上下文

​调整生成行为

​探索更多文本生成功能

​参考

​常见问题

请求结构

发起第一次调用

异步调用

生产优化

构建更优质的上下文

调整生成行为

探索更多文本生成功能

参考

常见问题