通义千问是阿里云推出的大语言模型系列，qwen-plus作为其中的主力型号，在效果和成本之间取得了不错的平衡，适合绝大多数业务场景的推理调用。要在自己的应用里用上这个模型，核心就是通过DashScope平台提供的OpenAI兼容接口或原生SDK发起请求。本文把从零开始接入到参数调优的完整流程讲清楚，包括密钥管理、SDK安装、推理参数含义、流式输出写法以及常见报错排查。
调用前的准备工作：密钥与SDK
调用任何模型之前，首先要有一个可用的API Key。前往阿里云百炼控制台（DashScope的控制台），在左侧菜单中找到API-KEY管理页面，点击创建新的密钥。密钥只会完整展示一次，务必及时保存到安全的地方，不要写死在代码里提交到代码仓库，更不要放在前端页面中暴露给浏览器。推荐的做法是通过环境变量注入，例如在Linux或macOS下执行export DASHSCOPE_API_KEY=sk-xxxxxxxx，Windows下可以在系统环境变量设置里添加同名变量。
SDK方面有两种选择。第一种是安装阿里云原生的dashscope包，执行pip install dashscope即可，它封装了通义千问的专有调用格式。第二种是使用OpenAI兼容模式，直接安装openai库，把base_url指向DashScope的兼容端点，这样如果你之前的项目已经基于OpenAI SDK开发，几乎不需要改动业务代码就能切换到通义千问。两种方式的底层能力一致，选哪种主要看团队现有的技术栈。
qwen-plus模型的调用方式与推理参数详解
先看最基础的非流式调用。使用OpenAI兼容模式时，代码结构如下：
from openai import OpenAI
import os
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"
)
response = client.chat.completions.create(
model="qwen-plus",
messages=[
{"role": "system", "content": "你是一个专业的技术助手"},
{"role": "user", "content": "用一句话解释什么是反向代理"}
]
)
print(response.choices[0].message.content)
如果用原生SDK，写法略有不同，通过dashscope.Generation.call或dashscope.MultiModalConversation完成调用，model参数同样填qwen-plus。messages数组中system消息用于设定模型的角色和行为约束，user消息承载实际问题，模型会严格参考这段上下文生成回答。
真正影响输出质量的是推理参数。temperature控制随机性，取值范围一般是0到2，默认值1左右。值越低回答越稳定、越适合问答和代码生成这类需要确定性的任务；值越高越发散，适合创意写作和头脑风暴。经验上，代码类任务建议设为0.1到0.3，通用对话保持0.7即可。
top_p是核采样参数，模型只会从累计概率达到top_p的候选词中做选择。阿里云官方建议temperature和top_p不要同时大幅调整，固定其中一个再调另一个，否则效果难以评估。一般固定top_p=0.8，然后通过temperature微调。
max_tokens限制单次回复的最大长度，注意这个长度是按token计算的，中文大约一个汉字消耗一到两个token。qwen-plus支持较长的输出上限，如果任务需要生成完整的长文，记得把该值调大，否则回复会被中途截断。此外还有presence_penalty和frequency_penalty两个惩罚系数，分别抑制重复话题和重复用词，当模型输出车轱辘话时可以适当提高。
流式输出与生产环境的注意事项
非流式调用要等模型把整段内容生成完才返回，长回答场景下用户等待时间明显。开启流式输出后，内容会一块一块地推送过来，前端可以逐字渲染，体验好很多。开启方式很简单，加上stream=True参数即可：
stream = client.chat.completions.create(
model="qwen-plus",
messages=[
{"role": "user", "content": "写一段介绍消息队列的短文"}
],
stream=True,
temperature=0.7,
top_p=0.8,
max_tokens=1024
)
for chunk in stream:
delta = chunk.choices[0].delta
if delta.content:
print(delta.content, end="", flush=True)
写流式代码时要注意两个细节。一是每个chunk的delta.content可能为空，特别是第一个和最后一个chunk，它们分别只携带role信息和finish_reason，所以必须做非空判断。二是Web服务中要把流式响应透传给前端，比如FastAPI里用StreamingResponse包装生成器，不要在服务端把流拼接完再一次性返回，那就失去意义了。
生产环境还需要考虑并发与限流。DashScope对每个模型有每分钟请求数和每分钟token数的限制，具体额度与账号等级有关。遇到限流时会返回429错误，正确做法是实现指数退避重试，而不是立刻放弃请求。计费方面qwen-plus按输入和输出的token总量计费，控制max_tokens、精简prompt内容都能直接降低成本。常见报错还包括401（密钥无效或未传对header）、400（参数格式错误，比如messages里role拼写错误）、模型名不存在（确认写的是qwen-plus而不是自己臆造的名字）。把密钥管理、参数调优、流式处理和错误重试这四件事做扎实，通义千问的接入基本就稳了。