阿里云百炼实战（一）：平台总览与第一个请求

只要你的产品涉及中文用户，迟早要调一次百炼模型。Qwen-Max 是拿到 GPT-4 级别中文理解的最便宜稳妥方式，万相视频是国内能开人民币发票的唯一生产级文生视频 API，Qwen-TTS-Flash 是唯一能把粤语和四川话讲得不像海关广播的 TTS。在某 AI 营销平台跑了一年生产之后，这个系列是我希望第一天就有人塞给我的那本书。

第一篇是地理课：百炼是什么、模型家族、两种 endpoint，跑通一个请求把后续不再重复的基础铺好。

百炼是什么，DashScope 是什么

命名确实容易混，因为阿里中途改过名。官方 “DashScope” 文档从 API 角度讲，“百炼” 文档从控制台角度讲。同一个产品，两个名字。

文档里你会同段落看到两个名字。当作"控制台 vs API"理解。说"部署百炼应用"指的是控制台；说"DashScope 报错"指的是 API 返回非 200。

你真正在意的模型目录

百炼挂着上百个模型。一年生产里我只为这些付过钱：

家族	代表 model_id	用途
Qwen LLM（文本）	`qwen-max`, `qwen-plus`, `qwen-turbo`, `qwen3-max`, `qwen3-coder-plus`	对话、推理、工具调用、代码
Qwen-Omni（多模态）	`qwen3-omni-flash`, `qwen3.5-omni-plus`	视频 / 音频 / 图像理解
Qwen-VL（视觉）	`qwen3-vl-plus`	仅图像理解（比 Omni 便宜）
万相（视频）	`wan2.5-t2v-plus`, `wan2.5-i2v-plus`	文生视频、图生视频
Qwen-TTS	`qwen3-tts-flash`	语音合成，40+ 音色
向量	`text-embedding-v3`, `text-embedding-v4`	向量检索

不在表里的要么已弃用、要么是薄变体、要么是研究预览。盯着这些用，就不会上线 6 周后被模型 EOL 坑。

计费一段话讲完

LLM 按 token 计费（输入和输出分开定价，输出贵 2-4 倍），TTS 按音频秒数，万相按视频秒数，向量按调用次数。每个模型有免费额度——通常 100 万 token 或 100 次生成——新版本上线会重置，意思是你只要愿意切版本几乎可以白嫖原型。生产流量必须用独立 API key 配预算告警；我吃过一次四位数账单，因为有人晚上忘关 debug 循环。

API key：别提交到 git

控制台左侧 API-KEY 拿。有一个默认空间 key 加每个工作空间的 key；任何生产项目用工作空间 key，能轮换不影响 dev。然后：

1
export DASHSCOPE_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"

本系列每段代码都读 os.environ['DASHSCOPE_API_KEY']。别硬编码，别提交 .env，生产环境请丢到密钥管理器后面。DashScope 团队会撤销泄露的 key，但只在公开爬虫扫到之后，那时已经晚了。

两个 endpoint：OpenAI 兼容 vs DashScope 原生

整篇文章最重要的事实。按 Qwen API reference，百炼的每个文本/多模态模型都有两个 HTTP 入口。

OpenAI-compatible endpoint

Base URL：https://dashscope.aliyuncs.com/compatible-mode/v1（中国大陆），或 https://dashscope-intl.aliyuncs.com/compatible-mode/v1（新加坡）。

走的是 OpenAI 协议。把官方 openai Python SDK 指向这里，95% 的现有 OpenAI 代码原样能跑。这是我的默认。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ['DASHSCOPE_API_KEY'],
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

resp = client.chat.completions.create(
    model="qwen-plus",
    messages=[
        {"role": "system", "content": "你是一个资深后端工程师。"},
        {"role": "user", "content": "用两句话解释幂等性 key。"},
    ],
)
print(resp.choices[0].message.content)

DashScope 原生 endpoint

Base URL：https://dashscope.aliyuncs.com/api/v1/...——按模态分路径（/services/aigc/text-generation/generation、/services/aigc/multimodal-generation/generation、/services/aigc/text2video/...）。

阿里自家的协议——请求 shape 不一样、字段名不一样（input.messages 不是 messages、有 parameters 块等等）。用 dashscope SDK，或者直接 HTTP。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
import os
import dashscope

dashscope.api_key = os.environ['DASHSCOPE_API_KEY']

resp = dashscope.Generation.call(
    model="qwen-plus",
    messages=[
        {"role": "system", "content": "你是一个资深后端工程师。"},
        {"role": "user", "content": "用两句话解释幂等性 key。"},
    ],
    result_format="message",
)
print(resp.output.choices[0].message.content)

什么时候用哪个

我血泪经验提炼的规则：

OpenAI-compatible：默认。普通对话、function calling、JSON mode、streaming。一行代码就能 A/B GPT-4。
DashScope 原生：万相视频必须、Qwen-TTS 必须、Qwen-Omni 多模态推荐（兼容层会丢部分视频参数）、需要异步任务模式时必须、最新功能没回灌到兼容层时必须。

常见坑：以为"OpenAI-compatible" 意味着所有模型都这么用。错。wan2.5-t2v-plus 只能原生。qwen3-tts-flash 只能原生。第四第五篇会反复打这件事。

经验： 收到 400 + parameter X is not supported 类报错，第一反应去查是不是把"原生 only"模型走了兼容 endpoint。我修过的"百炼坏了"工单里大约一半是这个。

三个反复出现的概念

model_id

每次调用以 qwen-plus 或 wan2.5-t2v-plus 这样的字符串为 key。没有版本号——阿里在同一 ID 下发新权重，在 changelog 里告诉你。要锁版本就用模型卡里列出的日期别名（qwen-plus-2025-09-11）。任何面向客户的场景请锁日期——没锁的别名我见过一夜之间换风格。

异步任务

任何超过 ~30 秒的事（视频生成、大批量 embedding、长文 TTS）都是异步。模式永远是：

POST 到 create endpoint，加 header X-DashScope-Async: enable。
拿回 task_id。
轮询 GET /api/v1/tasks/{task_id} 直到 SUCCEEDED 或 FAILED。
24 小时内下载输出 URL——会过期。

第四篇有完整的退避轮询实现。

流式

LLM 和 Qwen-Omni 支持 SSE 流式。Qwen3 配 enable_thinking=True 时必须流式——非流式会拒绝。Qwen-Omni 流式是必须的（第三篇细讲）。早点习惯 stream=True，你用得会比想象多。

跑通的第一个请求

存为 hello_bailian.py。能打印一句话就说明账号、key、网络都对，可以去第二篇了。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
import os
from openai import OpenAI

def main():
    api_key = os.environ.get("DASHSCOPE_API_KEY")
    if not api_key:
        raise SystemExit("先 export DASHSCOPE_API_KEY")

    client = OpenAI(
        api_key=api_key,
        base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    )

    stream = client.chat.completions.create(
        model="qwen-plus",
        messages=[
            {"role": "user", "content": "用一段话解释百炼是什么。"},
        ],
        stream=True,
    )

    for chunk in stream:
        delta = chunk.choices[0].delta.content
        if delta:
            print(delta, end="", flush=True)
    print()

if __name__ == "__main__":
    main()

想确认原生 endpoint 也能用，把上面 dashscope 那段代码替换跑一遍。两个都该成功，账单一致。

第二篇深挖 Qwen LLM 家族——按延迟和成本选模型、function calling、JSON mode、还有那个让我个人调试了大约四小时的 enable_thinking 参数。第三篇 Qwen-Omni 的流式必填和真实视频理解例子。第四篇万相视频端到端，第五篇 Qwen-TTS 多语种叙述。

只读一篇就读第二篇——里面"文档没告诉你"的密度最高。