通义千问是阿里云推出的大语言模型服务，底层通过DashScope平台对外开放API。相比直接拼HTTP请求，官方提供的DashScope SDK封装了鉴权、重试、流式解析等细节，上手门槛低了不少。这篇文章将从零开始演示如何获取密钥、安装SDK，然后重点讲解多模型切换与参数配置这两个最容易踩坑的环节，最后给出多轮对话和流式输出的完整代码。
准备工作：获取API Key并安装DashScope SDK
使用通义千问API的第一步是开通阿里云百炼模型服务（原DashScope）。登录阿里云控制台后，进入百炼平台，在页面右上角的API-KEY管理中创建一个密钥。这个密钥只会在创建时完整显示一次，务必妥善保存，泄露后需要立即禁用重建。
拿到密钥后，建议通过环境变量方式配置，避免硬编码到代码仓库里造成安全隐患。以Linux或macOS为例，可以在终端执行以下命令：
export DASHSCOPE_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx" # 想让配置永久生效，可以追加到 ~/.bashrc 或 ~/.zshrc echo 'export DASHSCOPE_API_KEY="sk-xxxxxxxx"' >> ~/.zshrc
Windows用户可以在系统设置里添加环境变量，或者在PowerShell中用$env:DASHSCOPE_API_KEY="sk-xxx"临时设置。接着安装Python版SDK：
pip install dashscope
DashScope同时支持Python和Java两种语言的SDK，本文以更主流的Python为例。安装完成后可以先跑一个最简单的请求验证环境是否正常，如果返回了模型回复，说明密钥和网络都没问题。
多模型调用：qwen-turbo、qwen-plus与qwen-max怎么选
通义千问家族提供了多个规格的模型，调用时只需要修改model参数即可切换，代码结构完全一致。三者的定位差异比较明显：qwen-turbo速度快、价格低，适合客服问答、内容摘要等对质量要求不高的场景；qwen-plus是均衡型选手，推理能力和成本居中，适合大多数日常任务；qwen-max能力最强，适合复杂推理、长文写作等高要求场景，但相应地延迟和费用也最高。
来看一段支持动态切换模型的调用代码：
import dashscope
from dashscope import Generation
import os
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")
def ask_qwen(question, model="qwen-plus"):
response = Generation.call(
model=model,
messages=[
{"role": "system", "content": "你是一个严谨的技术助手"},
{"role": "user", "content": question}
]
)
if response.status_code == 200:
print(f"[{model}] 回复：", response.output.choices[0].message["content"])
else:
print("调用失败：", response.code, response.message)
# 分别用三个模型提问，对比效果
for m in ["qwen-turbo", "qwen-plus", "qwen-max"]:
ask_qwen("用一句话解释什么是向量数据库", m)
代码里的messages数组采用角色机制，system用于设定模型人设和行为约束，user是用户输入。实际项目中常见的做法是把模型名放进配置文件，根据任务类型路由到不同规格的模型，比如简单分类任务走turbo，写作任务走max，这样能有效控制成本。
需要注意的一点是，不同模型支持的上下文长度和计费单价不同，切换模型前最好到官方文档确认当前版本的限额。另外每个账号的并发数和每分钟请求数都有配额限制，批量调用时要加入重试和限流逻辑，否则容易触发Throttling报错。
核心参数配置：temperature、top_p与max_tokens
模型调用效果好坏，参数配置占了一大半。这几个参数直接决定输出的随机性、长度和稳定性，理解它们的含义比记住代码重要得多。
temperature控制输出的随机程度，取值范围一般是0到2。值越低，模型越倾向于选择概率最高的词，回答稳定、保守，适合知识问答、代码生成这类要求确定性的任务；值越高，回答越发散、有创意，适合文案创作、头脑风暴。实践经验里，技术场景通常设为0.1到0.3，创意场景可以放到0.8以上。
top_p是核采样参数，指模型只从累计概率前p的候选词中挑选。它和temperature的作用有重叠，官方建议二选一调整，不要同时大幅改动，否则很难判断效果变化来自哪个参数。max_tokens限制单次回复的最大长度，超过部分会被截断。如果想拿到完整长文，除了调大这个值，还可以在提示词里明确要求字数。
response = Generation.call(
model="qwen-plus",
messages=[{"role": "user", "content": "写一段产品发布会的开场白"}],
temperature=0.9, # 创意写作场景调高随机性
top_p=0.95,
max_tokens=1024, # 限制回复长度
result_format="message" # 使用消息格式返回，推荐
)
print(response.output.choices[0].message["content"])
除了这三个，还有seed参数值得一提。设置固定的seed后，相同输入会得到相同输出，这在调试提示词和做自动化测试时非常有用，能排除随机因素对结果的干扰。
进阶场景：流式输出与多轮对话
默认调用是同步阻塞式的，要等模型生成完整个回复才返回。生成长内容时用户会盯着空白页面等待，体验很差。开启流式输出后，内容会像打字机一样逐段推送回来，前端体验明显更好：
responses = Generation.call(
model="qwen-plus",
messages=[{"role": "user", "content": "写一篇关于缓存策略的技术博客"}],
result_format="message",
stream=True, # 开启流式输出
incremental_output=True # 增量返回，只推新增内容
)
for resp in responses:
if resp.status_code == 200:
print(resp.output.choices[0].message["content"], end="", flush=True)
多轮对话则需要自己维护消息历史。DashScope本身不存储会话状态，每次请求都要把之前的对话完整传过去：
history = [
{"role": "system", "content": "你是Python编程助手"}
]
def chat(user_input):
history.append({"role": "user", "content": user_input})
resp = Generation.call(
model="qwen-plus",
messages=history,
result_format="message"
)
reply = resp.output.choices[0].message["content"]
history.append({"role": "assistant", "content": reply})
return reply
chat("什么是装饰器")
chat("给我一个带参数的装饰器例子")
这里有个容易被忽视的细节：随着对话轮数增加，history会越来越长，很快就会撑爆上下文窗口，费用也水涨船高。生产环境一般要做截断或者摘要压缩，比如只保留最近十轮对话，更早的内容用模型生成摘要替代原文。
常见问题与调试建议
入门阶段最常见的报错是401鉴权失败，基本都是环境变量没生效或者密钥复制时带上了空格，可以先打印os.getenv("DASHSCOPE_API_KEY")确认。其次是计费相关的问题，新账号通常有免费额度，超出后需要开通付费，遇到Arrearage错误就是余额不足了。
调试提示词时建议固定seed、把temperature调到最低，先保证输出稳定再逐步调优。如果遇到偶发的超时，SDK内置了自动重试机制，也可以在业务层加上指数退避重试兜底。把模型调用封装成统一的函数，加上日志记录每次的输入输出和耗时，后续排查问题和统计成本都会轻松很多。
总的来说，DashScope SDK把通义千问的接入难度降到了很低的水位，真正决定应用效果的是模型选择、参数调优和会话管理这些设计层面的功夫。先把本文的示例跑通，再结合自己的业务场景逐步迭代，是比较稳妥的路径。
通义千问APIDashScope SDK大模型调用修改时间：2026-09-15 16:48:46