QwQ

💜 通义千问聊天   |   🤗 Hugging Face   |   🤖 魔搭社区   |   📑 博客  
🖥️ 演示   |   💬 微信   |   🫨 Discord   |   📑 API  

简介

QwQ 是通义千问系列中专注于推理能力的模型。与传统的指令微调模型不同，QwQ 凭借其先进的推理和批判性思维能力，在下游任务中表现出色，尤其在复杂问题解决方面表现突出。我们最新发布的 QwQ-32B 是一款中等规模的模型，能够与 DeepSeek-R1 和 o1-mini 等顶级推理模型相媲美，提供强大且具有竞争力的结果。

注意： 在部署 QwQ 模型之前，请务必阅读 使用指南，尤其是当您遇到 无限循环或显著性能问题 时。

性能

如需复现结果，请参阅 我们的评估代码。

使用 HuggingFace 的 transformers 快速入门

QwQ 基于 Qwen2.5，该版本已包含在最新的 HuggingFace transformers 中。我们建议您使用最新版本的 transformers。

如果使用 transformers<4.37.0，您可能会遇到以下错误：

KeyError: 'qwen2'

以下是一个包含 apply_chat_template 的代码片段，展示了如何加载分词器和模型，并生成内容。

from transformers import AutoModelForCausalLM, AutoTokenizer
model_name = "Qwen/QwQ-32B"
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype="auto",
    device_map="auto"
)
tokenizer = AutoTokenizer.from_pretrained(model_name)
prompt = "单词 'strawberry' 中有多少个 r？"
messages = [
    {"role": "user", "content": prompt}
]
text = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True
)
model_inputs = tokenizer([text], return_tensors="pt").to(model.device)
generated_ids = model.generate(
    **model_inputs,
    max_new_tokens=32768
)
generated_ids = [
    output_ids[len(input_ids):] for input_ids, output_ids in zip(model_inputs.input_ids, generated_ids)
]
response = tokenizer.batch_decode(generated_ids, skip_special_tokens=True)[0]
print(response)

使用指南

为获得最佳性能，我们建议采用以下设置：

1. 强制生成思考内容：确保模型以“\n”开头，以防止生成空的思考内容，这会降低输出质量。如果您使用 apply_chat_template 并设置 add_generation_prompt=True，此功能将自动实现，但可能会导致响应开头缺少 <think> 标签。这是正常现象。

2. 采样参数：

   • 我们推荐使用 Temperature=0.6、TopP=0.95、MinP=0、TopK=40，且不使用重复惩罚，以达到最佳性能。
   • 请勿在任何情况下使用贪婪解码！这会导致无限循环。
   • 您可以将 TopK 值调整至 20 到 40 之间，以平衡过滤罕见词元和增强生成内容的多样性。
   • 对于支持的框架，您可以将 presence_penalty 参数调整至 0 到 2 之间，以减少无限循环。然而，较高的值有时可能导致语言混杂，并略微降低性能。

3. 历史记录中不含思考内容：在多轮对话中，历史模型输出应仅包含最终输出部分，无需包含思考内容。此功能已在 apply_chat_template 中实现。

4. 标准化输出格式：我们建议在基准测试时使用提示来标准化模型输出。

   • 数学问题：在提示中加入“请逐步推理，并将最终答案放在 \boxed{} 内。”
   • 选择题：在提示中添加以下 JSON 结构以标准化回答：“请在 answer 字段中仅填写选项字母，例如 \"answer\": \"C\"。”

5. 处理长输入：对于超过 8,192 个 token 的输入，启用 YaRN，以提高模型有效捕捉长序列信息的能力。

   对于支持的框架，您可以在 config.json 中添加以下内容以启用 YaRN：

   {
       ...,
       "rope_scaling": {
           "factor": 4.0,
           "original_max_position_embeddings": 32768,
           "type": "yarn"
       }
   }
   

   在部署时，我们建议使用 vLLM。如果您不熟悉 vLLM，请参阅我们的 文档 了解使用方法。 目前，vLLM 仅支持静态 YARN，这意味着缩放因子无论输入长度如何都保持不变，可能会影响短文本的性能。我们建议仅在需要处理长上下文时才添加 rope_scaling 配置。

Ollama 和 Llama.cpp

要使用 Ollama 运行 Qwen/QwQ-32B-GGUF 模型，请使用以下命令。

ollama run hf.co/Qwen/QwQ-32B-GGUF:Q4_K_M # 可选 Q8_0; Q6_K; Q5_K_M; Q5_0; Q4_K_M; Q4_0; Q3_K_M; Q2_K.
# 对于魔搭用户
ollama run modelscope.cn/Qwen/QwQ-32B-GGUF:Q4_K_M

如果您使用 Llama.cpp，可以使用以下命令运行模型。本示例使用 Q4_K_M 量化：

./llama-cli \
    --model QwQ-32B-GGUF/qwq-32b-q4_k_m.gguf \
    --threads 32 \
    --ctx-size 32768 \
    --seed 1234 \
    --temp 0.6 \
    --min-p 0.0 \
    --top-k 40 \
    --top-p 0.95 \
    -no-cnv \
    --samplers "top_k;top_p;min_p;temperature;" \
    --prompt "<|im_start|>user\n单词 'strawberry' 中有多少个 r？<|im_end|>\n<|im_start|>assistant\n<think>\n"

您还可以参考 Unsloth 的指南 来查看他们的方法是否符合您的需求。（感谢 Unsloth 团队！）

使用 API 试用 QwQ

如果您在部署 QwQ 时遇到问题，我们鼓励您试用由 阿里云 Model Studio 提供的 API 服务。

from openai import OpenAI
import os

# 初始化 OpenAI 客户端
client = OpenAI(
    # 如果未配置环境变量，请将 api_key 替换为您的 API 密钥：api_key="sk-xxx"
    # 获取 API 密钥的方法：https://help.aliyun.com/zh/model-studio/developer-reference/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"
)

reasoning_content = ""
content = ""

is_answering = False

completion = client.chat.completions.create(
    model="qwq-32b",
    messages=[
        {"role": "user", "content": "9.9 和 9.11 哪个更大？"}
    ],
    stream=True,
    # 取消注释以下行以在最后一个数据块中返回 token 使用情况
    # stream_options={
    #     "include_usage": True
    # }
)

print("\n" + "=" * 20 + "推理内容" + "=" * 20 + "\n")

for chunk in completion:
    # 如果 chunk.choices 为空，则打印使用情况
    if not chunk.choices:
        print("\n使用情况：")
        print(chunk.usage)
    else:
        delta = chunk.choices[0].delta
        # 打印推理内容
        if hasattr(delta, 'reasoning_content') and delta.reasoning_content is not None:
            print(delta.reasoning_content, end='', flush=True)
            reasoning_content += delta.reasoning_content
        else:
            if delta.content != "" and is_answering is False:
                print("\n" + "=" * 20 + "内容" + "=" * 20 + "\n")
                is_answering = True
            # 打印内容
            print(delta.content, end='', flush=True)
            content += delta.content

引用

如果您在研究中发现我们的论文和代码很有用，请考虑给项目点赞 :star: 并引用 :pencil: ：

@misc{qwq32b,
    title = {QwQ-32B：拥抱强化学习的力量},
    url = {https://qwenlm.github.io/blog/qwq-32b/},
    author = {通义实验室团队},
    month = {三月},
    year = {2025}
}

@article{qwen2.5,
      title={Qwen2.5 技术报告}, 
      author={An Yang、Baosong Yang、Beichen Zhang、Binyuan Hui、Bo Zheng、Bowen Yu、Chengyuan Li、Dayiheng Liu、Fei Huang、Haoran Wei、Huan Lin、Jian Yang、Jianhong Tu、Jianwei Zhang、Jianxin Yang、Jiaxi Yang、Jingren Zhou、Junyang Lin、Kai Dang、Keming Lu、Keqin Bao、Kexin Yang、Le Yu、Mei Li、Mingfeng Xue、Pei Zhang、Qin Zhu、Rui Men、Runji Lin、Tianhao Li、Tianyi Tang、Tingyu Xia、Xingzhang Ren、Xuancheng Ren、Yang Fan、Yang Su、Yichang Zhang、Yu Wan、Yuqiong Liu、Zeyu Cui、Zhenru Zhang、Zihan Qiu},
      journal={arXiv 预印本 arXiv:2412.15115},
      year={2024}
}

QwQ 快速上手指南

QwQ 是通义千问系列中专注于推理能力的模型，擅长处理复杂问题解决任务。最新发布的 QwQ-32B 在性能上可与 DeepSeek-R1 和 o1-mini 等顶级推理模型媲美。

环境准备

• 系统要求：支持 Linux、macOS 或 Windows（建议使用 Linux 以获得最佳兼容性）。
• Python 版本：建议 Python 3.8 及以上。
• 核心依赖：
  • transformers >= 4.37.0（低于此版本会报错 KeyError: 'qwen2'）。
  • torch (PyTorch)。
  • accelerate (用于自动设备映射)。
• 显存建议：运行 QwQ-32B 全精度模型建议显存大于 64GB；若使用量化版本（如 GGUF），可根据量化等级降低显存需求。

安装步骤

推荐使用 pip 安装最新版的 transformers 以兼容 QwQ 模型架构。

pip install -U transformers accelerate torch

若需使用 Ollama 或 llama.cpp 运行量化版本，请分别参考其官方文档进行安装。国内用户可通过 ModelScope 获取模型文件以加速下载。

基本使用

方法一：使用 Hugging Face Transformers (Python)

以下代码展示了如何加载模型并进行推理。注意：QwQ 需要特定的采样参数以避免重复输出，且推荐开启思维链（Think）模式。

from transformers import AutoModelForCausalLM, AutoTokenizer

# 指定模型名称，国内用户也可使用 ModelScope 路径
model_name = "Qwen/QwQ-32B"

# 加载模型
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype="auto",
    device_map="auto"
)

# 加载分词器
tokenizer = AutoTokenizer.from_pretrained(model_name)

# 构建提示词
prompt = "How many r's are in the word \"strawberry\""
messages = [
    {"role": "user", "content": prompt}
]

# 应用聊天模板，add_generation_prompt=True 会自动处理 <|im_start|> 等标记
text = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True
)

# 编码输入
model_inputs = tokenizer([text], return_tensors="pt").to(model.device)

# 生成响应
# 关键参数设置：Temperature=0.6, TopP=0.95, TopK=40, MinP=0
# 严禁使用 Greedy decoding (do_sample=False)，否则会导致无限重复
generated_ids = model.generate(
    **model_inputs,
    max_new_tokens=32768,
    do_sample=True,
    temperature=0.6,
    top_p=0.95,
    top_k=40,
    min_p=0.0
)

# 解码输出
generated_ids = [
    output_ids[len(input_ids):] for input_ids, output_ids in zip(model_inputs.input_ids, generated_ids)
]
response = tokenizer.batch_decode(generated_ids, skip_special_tokens=True)[0]

print(response)

方法二：使用 Ollama (命令行)

Ollama 提供了便捷的量化模型运行方式，支持直接从 HuggingFace 或 ModelScope 拉取。

# 从 HuggingFace 拉取并运行 (推荐 Q4_K_M 量化版)
ollama run hf.co/Qwen/QwQ-32B-GGUF:Q4_K_M

# 国内用户推荐从 ModelScope 拉取
ollama run modelscope.cn/Qwen/QwQ-32B-GGUF:Q4_K_M

方法三：使用 API (阿里云百炼)

若本地部署困难，可直接调用阿里云提供的 API 服务。

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"), # 替换为您的 API Key
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"
)

completion = client.chat.completions.create(
    model="qwq-32b",
    messages=[
        {"role": "user", "content": "Which is larger, 9.9 or 9.11?"}
    ],
    stream=True
)

for chunk in completion:
    if chunk.choices:
        delta = chunk.choices[0].delta
        # 打印推理过程内容
        if hasattr(delta, 'reasoning_content') and delta.reasoning_content:
            print(delta.reasoning_content, end='', flush=True)
        # 打印最终回答内容
        elif delta.content:
            print(delta.content, end='', flush=True)

关键使用建议

1. 采样参数：务必设置 temperature=0.6, top_p=0.95, top_k=40。不要使用贪婪解码（Greedy decoding），否则会产生无限重复。
2. 思维标签：模型默认会以 <think> 开始输出推理过程。在使用 apply_chat_template 时，这一行为已自动处理。
3. 长文本支持：若输入超过 8,192 tokens，建议在配置中启用 YaRN (rope_scaling) 以提升长上下文理解能力。
4. 多轮对话：历史记录中只需保留最终回答部分，无需包含 <think> 内部的推理过程。