通义千问快速上手：从账号申请到首次调用

通义千问是阿里云推出的大语言模型服务，面向需要自然语言处理能力的开发者与企业，常见用途包括智能问答、对话式客服、文本生成与内容摘要等。它既提供网页端体验入口，也提供 API 供程序调用。本文整理一条从零开始的路径：准备账号、开通模型服务、拿到调用凭证、写出第一段可运行的请求代码，并说明调用过程中容易踩到的坑。如果你只是想先感受一下模型效果，可以直接使用站内的 通义千问 工具页做简单对话；如果要把它接进自己的系统，则按下面的步骤走一遍 API 流程。

准备工作

在写第一行代码之前，需要先把账号和权限这条链路打通。通义千问的 API 能力依托阿里云的模型服务平台提供，因此前置条件主要围绕阿里云账号展开。

账号与实名认证

• 一个阿里云账号。个人开发者用个人账号即可，企业场景建议使用已完成企业认证的账号，部分模型或额度在企业认证后可用范围更广。
• 完成实名认证。未实名的账号通常无法开通按量付费的模型服务，也无法正常调用 API。
• 确认账号没有欠费。模型服务多为后付费或需要先领取免费额度，账号处于异常状态时开通会失败。

开通模型服务并获取 API Key

通义千问的调用凭证是 API Key，它绑定在模型服务的控制台上。大致流程如下：

1. 登录阿里云控制台，进入模型服务（百炼 / DashScope 相关入口）的控制台页面。
2. 在控制台中开通模型服务。首次开通一般需要同意服务条款，部分账号会同时获得一定量的免费调用额度。
3. 在控制台的「API-KEY 管理」页面创建一个新的 API Key。创建后请立即复制保存，页面关闭后通常无法再次完整查看。
4. 把 API Key 放到环境变量里，不要硬编码进源码，也不要提交到代码仓库。

设置环境变量的方式，Linux 或 macOS 下可以这样写：

export DASHSCOPE_API_KEY="你的APIKey"

Windows PowerShell 下用：

$env:DASHSCOPE_API_KEY="你的APIKey"

开发环境

• Python 3.8 及以上版本。官方 SDK 对 Python 版本有最低要求，版本过低会在安装阶段报错。
• pip 包管理工具可用。
• 能正常访问外网，调用时需要连通模型服务的接口地址。

安装官方 SDK：

pip install dashscope

如果项目里已经用 OpenAI 兼容风格的客户端，也可以直接复用，通义千问提供了兼容模式的接口地址，具体地址与可用模型请以控制台当前展示为准。

操作步骤

第一步：确认可用模型名称

调用前必须先知道模型名。通义千问有多个版本，覆盖不同能力与价格档位，例如通用对话模型、长文本模型、代码模型等。模型名是调用参数里的必填项，写错会直接返回模型不存在的错误。

获取方式是在控制台的模型列表页面查看当前账号可用的模型标识，把需要的那个名字记下来。模型列表会随平台更新而变化，不要凭记忆写死一个名字。

第二步：发起一次最简单的调用

用 Python SDK 发起一次单轮对话，代码结构如下：

import dashscope
from dashscope import Generation

response = Generation.call(
    model="通义千问模型名",
    messages=[
        {"role": "system", "content": "你是一个简洁的助手。"},
        {"role": "user", "content": "用一句话解释什么是大语言模型。"},
    ],
    result_format="message",
)

if response.status_code == 200:
    print(response.output.choices[0].message.content)
else:
    print("调用失败:", response.status_code, response.message)

这段代码里有几个关键点：

• model：填控制台里查到的模型标识，不要照抄示例里的占位文字。
• messages：对话消息数组，每条消息包含 role 和 content。role 可取 system、user、assistant 三种。system 用来设定角色与风格，user 是用户输入，assistant 是模型此前的回复，多轮对话时要把历史消息按顺序带上。
• result_format：设为 message 时，返回结果按消息结构组织，便于直接取 content 字段；不设或设为 text 时返回结构不同，取值方式也要相应调整。
• status_code：200 表示成功，其他值表示出错，出错信息在 response.message 里。

第三步：处理多轮对话

模型本身不保存会话状态，多轮对话需要调用方自己维护消息列表。典型做法是把历史消息追加进 messages 再整体发出去：

history = [
    {"role": "system", "content": "你是一个耐心的技术助手。"},
]

def chat(user_input):
    history.append({"role": "user", "content": user_input})
    response = Generation.call(
        model="通义千问模型名",
        messages=history,
        result_format="message",
    )
    if response.status_code != 200:
        raise RuntimeError(response.message)
    reply = response.output.choices[0].message.content
    history.append({"role": "assistant", "content": reply})
    return reply

需要注意上下文长度上限。历史消息越长，占用的 token 越多，超过模型上限时会报错。生产环境里通常需要做截断或摘要，把较早的对话压缩掉。

第四步：控制生成行为

调用时可以传入若干参数来影响输出，常用的有：

参数	作用
temperature	控制随机性。值越低输出越稳定保守，值越高越发散。事实类问答建议调低，创意写作可以调高。
top_p	核采样阈值，与 temperature 配合使用，一般只调其中一个。
max_tokens	限制本次回复的最大生成长度，防止输出过长导致费用与等待时间上升。
stream	设为 True 时以流式方式返回，适合需要边生成边展示的聊天界面。
seed	在支持的模型上用于提高结果的可复现性，相同种子与参数下输出更接近。

这些参数的取值范围与默认值会随模型不同而变化，使用前请以控制台或接口文档当前说明为准。

第五步：流式输出

聊天类应用通常希望文字逐段出现，而不是等整段生成完再显示。开启流式后，返回的是一个可迭代对象，逐块读取即可：

responses = Generation.call(
    model="通义千问模型名",
    messages=[{"role": "user", "content": "写一段关于秋天的短句。"}],
    result_format="message",
    stream=True,
    incremental_output=True,
)

for chunk in responses:
    if chunk.status_code == 200:
        print(chunk.output.choices[0].message.content, end="")
    else:
        print("出错:", chunk.message)

流式模式下每个分片只包含增量内容，需要自行拼接。若把 incremental_output 关掉，分片里可能是累积内容，拼接逻辑要相应调整。

第六步：错误处理与重试

线上调用必须处理失败情况。常见错误类型包括：

• 鉴权失败：API Key 错误、被删除或未正确传入环境变量。
• 模型不存在或无权限：模型名写错，或该模型未在当前账号开通。
• 限流：请求频率或并发超过账号配额，需要退避重试。
• 参数非法：消息格式不对、超出长度上限、参数取值越界。
• 服务端错误：平台侧临时故障，适合做有限次数的重试。

重试时建议采用指数退避，并给重试次数设上限，避免在持续限流时把请求量放大。

一个完整示例

下面把前面的内容串成一个可运行的最小脚本：读取环境变量中的密钥，维护多轮上下文，带流式输出与基本错误处理。

import os
import time
import dashscope
from dashscope import Generation

MODEL = "通义千问模型名"  # 替换为控制台中查到的模型标识

def build_messages(history, user_input):
    history.append({"role": "user", "content": user_input})
    return history

def ask(history, user_input, retries=3):
    messages = build_messages(history, user_input)
    for attempt in range(retries):
        response = Generation.call(
            model=MODEL,
            messages=messages,
            result_format="message",
            temperature=0.7,
            max_tokens=800,
        )
        if response.status_code == 200:
            reply = response.output.choices[0].message.content
            history.append({"role": "assistant", "content": reply})
            return reply
        # 服务端错误或限流时退避重试
        if response.status_code in (429, 500, 503):
            time.sleep(2 ** attempt)
            continue
        raise RuntimeError(f"调用失败 {response.status_code}: {response.message}")
    raise RuntimeError("重试次数用尽")

if __name__ == "__main__":
    if not os.getenv("DASHSCOPE_API_KEY"):
        raise SystemExit("请先设置 DASHSCOPE_API_KEY 环境变量")

    history = [{"role": "system", "content": "你是一个简洁的中文技术助手。"}]
    while True:
        text = input("你: ").strip()
        if text in ("exit", "quit"):
            break
        print("模型:", ask(history, text))

运行前确认三件事：环境变量已设置、模型名已替换为账号下真实可用的标识、依赖已安装。跑通之后，把 ask 函数接到自己的业务逻辑里即可。

注意事项

• 模型名与可用范围会变：平台会持续上线新模型、下线旧模型，示例代码里的模型名只是占位，务必以控制台当前列表为准。
• 计费方式：模型服务通常按输入与输出的 token 量计费，不同模型单价不同。免费额度、赠送额度、单价与结算方式都可能调整，具体以官网当前公布的信息为准。
• 配额与限流：账号存在请求频率与并发上限，超出后会被限流。高并发场景需要提前评估配额，并做好退避重试。
• 上下文长度上限：每个模型都有最大上下文 token 数，历史消息加本次输入超过上限会直接报错，需要做截断或摘要。
• 密钥安全：API Key 等同于账号在模型服务上的凭证，泄露后可能被他人消耗额度。不要写进前端代码、不要提交到公开仓库，怀疑泄露时立即在控制台删除并重建。
• 输出不可全信：大语言模型可能生成看似合理但实际错误的内容，涉及事实、数字、法律或医疗等场景时，必须由人工复核后再使用。
• 内容合规：调用需遵守平台的内容安全规范，涉及敏感内容的请求可能被拦截，业务侧应准备相应的兜底提示。
• 接口兼容性：若使用 OpenAI 兼容模式，部分参数名称与返回结构存在差异，迁移时需逐项核对。

把上面几步走完，基本就能在自己的项目里跑通通义千问的调用链路。后续的优化方向主要是提示词设计、上下文管理、失败重试与成本控制，这几项决定了应用在真实流量下的表现。