通义千问 API 实战：Qwen 系列模型能力全解析

AINative软件工程
5 阅读9分钟

本文面向有 Python/Node.js 基础的开发者，系统梳理阿里云百炼平台的接入方式，覆盖 Qwen 全系列模型能力——从文本对话、超长上下文到多模态图像理解，以及与 DeepSeek 的互补使用建议。

一、阿里云百炼平台简介

阿里云百炼平台地址：bailian.console.aliyun.com

通义千问（Qwen）是阿里云研发的大模型系列，覆盖从轻量到旗舰的完整模型梯队，并在多模态、超长上下文、代码生成等方向有专项模型。通过百炼平台可以统一调用所有 Qwen 模型，也支持 Llama、Qwen-VL 等开源模型的 API 调用。

核心特点：

  • 模型梯队完整：从 qwen-turbo（低成本）到 qwen-max（旗舰），按需选择
  • 超长上下文：qwen-long 支持最高 1000 万 token 的上下文，适合长文档处理
  • 多模态能力：qwen-vl-max 支持图片+文字混合输入
  • 兼容模式：提供兼容 OpenAI 的接口路径，迁移成本低

二、注册和获取 API Key

Step 1：访问 bailian.console.aliyun.com，使用阿里云账号登录（可用支付宝扫码）。

Step 2：首次使用需要开通「百炼」服务，点击「立即开通」，完成实名认证。

Step 3：进入控制台后，点击右上角账号头像 → 「API-KEY 管理」。

Step 4：点击「创建 API-KEY」，选择所属业务空间，复制生成的 Key。

百炼平台提供新用户免费额度（各模型有不同数量的免费 token），适合开发测试阶段使用。

配置环境变量：

export DASHSCOPE_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

三、Qwen 模型家族

3.1 文本模型

模型 ID定位上下文特点
qwen-max旗舰通用32K最强综合能力
qwen-plus均衡128K性价比高，能力接近旗舰
qwen-turbo轻量快速1M低延迟、低成本
qwen-long超长文档10M专为海量文档检索设计

3.2 代码模型

模型 ID定位
qwen-coder-plus代码生成、理解、重构
qwen-coder-turbo轻量代码补全

3.3 视觉模型

模型 ID能力
qwen-vl-max旗舰视觉理解（图片+文本）
qwen-vl-plus均衡视觉模型

3.4 向量模型

模型 ID维度适用场景
text-embedding-v31024/768/512（可选）语义搜索、RAG 召回
text-embedding-async-v21536批量离线向量化

四、快速上手：三种调用方式

百炼平台提供两种接入路径：

# 兼容模式（推荐，可直接用 openai SDK）
Base URL: https://dashscope.aliyuncs.com/compatible-mode/v1

# 原生 DashScope SDK（Python 专用，功能更完整）
pip install dashscope

本文以兼容模式为主，只需一个 openai 包即可覆盖大多数场景。

4.1 curl

curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -d '{
    "model": "qwen-plus",
    "messages": [
      {"role": "system", "content": "你是一个专业的技术助手。"},
      {"role": "user", "content": "解释一下 Redis 的 LRU 淘汰策略"}
    ],
    "max_tokens": 1024
  }'

4.2 Python

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["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": "解释一下 Redis 的 LRU 淘汰策略"},
    ],
    max_tokens=1024,
)

print(response.choices[0].message.content)

4.3 Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DASHSCOPE_API_KEY,
  baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1",
});

const response = await client.chat.completions.create({
  model: "qwen-plus",
  messages: [
    { role: "system", content: "你是一个专业的技术助手。" },
    { role: "user", content: "用 TypeScript 实现一个 LRU Cache 类" },
  ],
  max_tokens: 2048,
});

console.log(response.choices[0].message.content);

五、Qwen 特有能力详解

5.1 超长上下文：qwen-long

qwen-long 支持高达 1000 万 token 的上下文，约等于 7500 本《哈利波特》全集的文字量。适合：

  • 分析整个代码仓库
  • 处理完整的法律合同文档集
  • 跨多文档的语义问答
# 读取一个大型 PDF 或代码文件后传入
with open("codebase_dump.txt", "r") as f:
    large_content = f.read()

response = client.chat.completions.create(
    model="qwen-long",
    messages=[
        {
            "role": "system",
            "content": "你是一个代码审查专家，请分析以下代码库中的潜在安全问题。",
        },
        {
            "role": "user",
            "content": large_content + "\n\n请列出所有可能的 SQL 注入风险点。",
        },
    ],
    max_tokens=4096,
)

print(response.choices[0].message.content)

超长上下文不等于万能。token 数越多，推理时间越长，成本也越高。建议先用 RAG 召回相关片段，只有确实需要全量上下文时才用 qwen-long。

5.2 多模态能力：qwen-vl-max

qwen-vl-max 支持图片+文字混合输入，可处理截图分析、图表理解、OCR 识别等任务：

import base64

# 方式一：传入图片 URL
response = client.chat.completions.create(
    model="qwen-vl-max",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/architecture-diagram.png"
                    },
                },
                {
                    "type": "text",
                    "text": "请描述这张架构图的主要组件和数据流向。",
                },
            ],
        }
    ],
)

print(response.choices[0].message.content)

# 方式二：传入 Base64 编码的本地图片
with open("screenshot.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")

response = client.chat.completions.create(
    model="qwen-vl-max",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/png;base64,{image_data}"
                    },
                },
                {
                    "type": "text",
                    "text": "提取图中所有的文字内容，保持原有格式。",
                },
            ],
        }
    ],
)

5.3 代码能力：qwen-coder 系列

qwen-coder-plus 在代码补全、重构、Bug 定位上有专项优化：

response = client.chat.completions.create(
    model="qwen-coder-plus",
    messages=[
        {
            "role": "system",
            "content": "你是一个资深 Python 工程师，专注代码质量和性能优化。",
        },
        {
            "role": "user",
            "content": """
请 review 以下代码并指出问题：

```python
def get_user_data(user_ids):
    results = []
    for uid in user_ids:
        row = db.query(f"SELECT * FROM users WHERE id = {uid}")
        results.append(row)
    return results

""", }, ], )


### 5.4 Embedding：text-embedding-v3

`text-embedding-v3` 是百炼平台当前最新的向量模型，支持灵活的输出维度配置，适合 RAG 系统构建：

```python
# 单条文本向量化
response = client.embeddings.create(
    model="text-embedding-v3",
    input="阿里云对象存储 OSS 的核心优势是什么？",
    dimensions=1024,  # 可选 1024 / 768 / 512，维度越低成本越低
)

embedding = response.data[0].embedding
print(f"向量维度: {len(embedding)}")  # 1024

# 批量向量化（适合离线建索引）
texts = [
    "Redis 的 AOF 持久化原理",
    "MySQL InnoDB 的 MVCC 实现",
    "Kafka 消息保序机制",
]

response = client.embeddings.create(
    model="text-embedding-v3",
    input=texts,
    dimensions=1024,
)

embeddings = [item.embedding for item in response.data]
print(f"批量处理 {len(embeddings)} 条，每条维度 {len(embeddings[0])}")

5.5 结构化输出：json_schema 支持

Qwen 支持通过 response_format 传入 JSON Schema，强制模型输出符合 Schema 的 JSON：

schema = {
    "type": "object",
    "properties": {
        "bugs": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "line": {"type": "integer"},
                    "severity": {"type": "string", "enum": ["low", "medium", "high"]},
                    "description": {"type": "string"},
                },
                "required": ["line", "severity", "description"],
            },
        },
        "summary": {"type": "string"},
    },
    "required": ["bugs", "summary"],
}

response = client.chat.completions.create(
    model="qwen-plus",
    messages=[
        {"role": "system", "content": "你是代码审查助手，以 JSON 格式输出审查结果。"},
        {"role": "user", "content": "审查这段代码：def div(a, b): return a / b"},
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {"name": "code_review", "schema": schema, "strict": True},
    },
)

import json
result = json.loads(response.choices[0].message.content)
print(result)

六、定价对比

文本模型

模型输入输出
qwen-turbo¥0.3 / 百万 token¥0.6 / 百万 token
qwen-plus¥0.8 / 百万 token¥2 / 百万 token
qwen-max¥40 / 百万 token¥120 / 百万 token
qwen-long¥0.5 / 百万 token¥2 / 百万 token

向量模型

模型价格
text-embedding-v3¥0.7 / 百万 token

百炼平台不定期有新用户免费 token 活动，正式接入前建议先确认当前促销政策。

七、Qwen vs DeepSeek 定位差异与互补建议

两个平台在能力和定位上有明显互补性，实际项目中可以组合使用：

维度DeepSeekQwen（百炼）
复杂推理R1 显式思维链，数学推理顶级qwen-max 能力强但无思维链暴露
超长上下文最高 64Kqwen-long 支持 10M，优势明显
多模态暂无图片理解qwen-vl-max 图片+文字
Embedding暂无text-embedding-v3 完整支持
价格（通用模型）V3 ¥1 输入，成本极低qwen-turbo ¥0.3，qwen-plus ¥0.8
代码专项deepseek-coder 历史积累深qwen-coder-plus 持续更新

推荐组合策略：

  1. RAG 系统：text-embedding-v3（向量化）+ qwen-plus（生成）；文档库超大时用 qwen-long 直接处理
  2. 数学/逻辑推理：优先 deepseek-reasoner，看 reasoning_content 辅助调试
  3. 日常对话/内容生成：deepseek-chat（成本最低）或 qwen-turbo（延迟更稳定）
  4. 图片分析：qwen-vl-max，DeepSeek 暂无替代
  5. 代码审查/补全：两个平台的 coder 模型各有优势，建议 A/B 测试

如果想让 DeepSeek 和 Qwen 的切换在代码层完全透明，笔者开发的 TheRouter 支持配置自动 fallback——主模型不可用或限流时，自动切到备选模型，业务代码无需感知，只对接一个统一的 API 端点即可。

八、生产环境配置最佳实践

8.1 统一客户端封装

项目中建议对模型调用做一层封装，方便切换模型和统一错误处理：

from openai import OpenAI
from dataclasses import dataclass
from typing import Literal
import os


@dataclass
class ModelConfig:
    provider: Literal["qwen", "deepseek"]
    model: str
    max_tokens: int = 2048


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

DEEPSEEK_CLIENT = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com/v1",
)


def get_client(config: ModelConfig) -> OpenAI:
    return QWEN_CLIENT if config.provider == "qwen" else DEEPSEEK_CLIENT


def chat(config: ModelConfig, messages: list) -> str:
    client = get_client(config)
    response = client.chat.completions.create(
        model=config.model,
        messages=messages,
        max_tokens=config.max_tokens,
    )
    return response.choices[0].message.content

8.2 流式输出（含多模态）

def stream_chat(messages: list, model: str = "qwen-plus"):
    stream = QWEN_CLIENT.chat.completions.create(
        model=model,
        messages=messages,
        stream=True,
    )
    for chunk in stream:
        content = chunk.choices[0].delta.content
        if content:
            yield content


# 使用示例
for token in stream_chat([{"role": "user", "content": "写一篇关于 k8s 网络插件的技术文章"}]):
    print(token, end="", flush=True)

8.3 限流与重试

百炼平台的 API 有 QPM（每分钟请求数）和 TPM（每分钟 token 数）限制，根据套餐档位不同：

import time
import random
from openai import RateLimitError


def chat_with_retry(messages: list, model: str = "qwen-plus", max_retries: int = 5):
    for attempt in range(max_retries):
        try:
            return QWEN_CLIENT.chat.completions.create(
                model=model,
                messages=messages,
                max_tokens=2048,
            )
        except RateLimitError:
            if attempt == max_retries - 1:
                raise
            # 指数退避：1s, 2s, 4s, 8s...
            wait = (2 ** attempt) + random.uniform(0, 0.5)
            time.sleep(wait)

8.4 多模态请求的注意事项

  • 单张图片建议不超过 10MB，支持 JPG、PNG、BMP、WEBP 格式
  • qwen-vl-max 单次请求最多传入 10 张图片
  • Base64 传输适合本地文件；URL 传输适合已上传到 OSS 等可公开访问的图片
# 批量图片分析示例
def analyze_images(image_urls: list[str], question: str) -> str:
    content = [
        {"type": "image_url", "image_url": {"url": url}}
        for url in image_urls[:10]  # 最多 10 张
    ]
    content.append({"type": "text", "text": question})

    response = QWEN_CLIENT.chat.completions.create(
        model="qwen-vl-max",
        messages=[{"role": "user", "content": content}],
        max_tokens=2048,
    )
    return response.choices[0].message.content

九、总结

通义千问 API 通过百炼平台提供了完整的模型梯队，核心优势在于：

  1. 超长上下文是真正的差异化：qwen-long 的 1000 万 token 在处理大型文档时几乎没有竞争对手
  2. 多模态闭环：文本、视觉、向量在同一平台统一管理，适合构建多模态应用
  3. 兼容模式降低迁移成本：已有 OpenAI 集成的项目，改一个 base_url 即可切换

与 DeepSeek 的建议搭配是：DeepSeek 做推理密集型任务（尤其是需要暴露思维链的场景），Qwen 做多模态、超长文档和向量化任务，两者并不互斥，按场景选择比在「哪个更好」上纠结更有价值。

作者：TheRouter 开发者，专注 AI 模型路由网关。项目主页：therouter.ai

avatar
文章
阅读
粉丝