Qwen2.5：阿里通义千问开源大模型本地部署指南

本文基于官方仓库 QwenLM/Qwen2.5 的 README 完整翻译整理。该仓库随通义千问系列持续更新，当前 README 同时覆盖 Qwen3-2507 系列、Qwen3 系列以及 Qwen2.5 系列的权重发布、推理与部署方式，命令、端口、版本号均与官方 README 保持一致。

一、项目官方信息

项目	信息
GitHub 仓库	QwenLM/Qwen2.5
官方在线对话	Qwen Chat
权重托管	Hugging Face · Qwen 与 ModelScope · qwen
技术论文	Qwen3 Technical Report (arXiv:2505.09388)、Qwen2.5 Technical Report (arXiv:2412.15115)
官方博客	Qwen3 发布博客、Qwen2.5 发布博客
官方文档	qwen.readthedocs.io（英文 / 中文）
在线演示	Hugging Face Spaces · Qwen3-Demo
开源协议	Apache License 2.0（所有开放权重模型均采用 Apache 2.0，许可文件见各 Hugging Face 仓库）
社区	Discord、微信群（见仓库 README 中的 wechat 二维码）

官方说明：前往 Hugging Face 或 ModelScope 组织主页，搜索以 Qwen3- 开头的检查点，或浏览 Qwen3 模型合集，即可找到全部可用权重。官方文档分为六个部分：快速开始介绍基础用法与演示；推理部分讲解如何用 Transformers 做批量推理、流式输出等；本地运行部分说明如何用 llama.cpp、Ollama、LM Studio 等框架在 CPU 与 GPU 上本地运行大模型；部署部分演示如何用 SGLang、vLLM、TGI 等框架为 Qwen 做大规模推理服务；量化部分讲解如何用 GPTQ、AWQ 量化大模型，以及如何制作高质量的量化 GGUF 文件；训练部分说明如何用 Axolotl、LLaMA-Factory 等框架做 SFT、RLHF 等后训练；此外还有应用框架部分，介绍如何在 RAG、Agent 等应用场景中使用 Qwen。

二、项目背景与模型介绍

在过去三个月里，团队持续探索 Qwen3 家族的潜力，推出了更新版 Qwen3-2507，分为两个变体：Qwen3-Instruct-2507 与 Qwen3-Thinking-2507，共有 235B-A22B、30B-A3B 和 4B 三种规格。

Qwen3-Instruct-2507 是此前 Qwen3 非思考模式的更新版，主要增强包括：通用能力显著提升，涵盖指令遵循、逻辑推理、文本理解、数学、科学、编程与工具调用；跨多种语言的长尾知识覆盖大幅扩充；在主观与开放式任务上与用户偏好的对齐明显更好，能给出更有帮助的回答和更高质量的文本；256K token 长上下文理解能力增强，可扩展至 100 万 token。

Qwen3-Thinking-2507 是 Qwen3 思考模型的延续，推理质量与深度进一步提升：在逻辑推理、数学、科学、编程以及需要人类专业知识的学术基准上取得显著进步，在开放权重思考模型中达到业界领先水平；指令遵循、工具调用、文本生成与人类偏好对齐等通用能力全面提升；256K 长上下文理解增强，同样可扩展至 100 万 token。

此前的 Qwen3（即 Qwen3-2504） 是 Qwen 家族最新的大语言模型，团队在 QwQ 与 Qwen2.5 的经验之上打造了迄今最先进、最智能的系统，并同时开放稠密模型与混合专家（MoE）模型权重。其亮点包括：提供 0.6B、1.7B、4B、8B、14B、32B、30B-A3B、235B-A22B 多种规格的稠密与 MoE 模型；可在思考模式（复杂逻辑推理、数学、编程）与非思考模式（高效通用对话）之间无缝切换；推理能力较此前 QwQ 思考模式和 Qwen2.5 指令模型显著增强；在创意写作、角色扮演、多轮对话、指令遵循上具有出色的人类偏好对齐；具备专业的智能体能力，可在思考与非思考模式下精确调用外部工具，在复杂 Agent 任务中达到开源模型领先水平；支持 100 多种语言和方言，具备强大的多语言指令遵循与翻译能力。

更新时间线：2025 年 8 月 8 日起，Qwen3-2507 可处理 100 万 token 的超长输入，这意味着模型可以一次性读完数百页文档、整库代码或长篇对话历史；启用方法见更新后的模型卡——235B-A22B-Instruct-2507、235B-A22B-Thinking-2507、30B-A3B-Instruct-2507、30B-A3B-Thinking-2507。8 月 6 日发布 Qwen3-2507 的收官之作 Qwen3-4B-Instruct-2507 与 Qwen3-4B-Thinking-2507。7 月 31 日发布 Qwen3-30B-A3B-Thinking-2507；7 月 30 日发布 Qwen3-30B-A3B-Instruct-2507；7 月 25 日发布 235B-A22B 思考模式更新版 Qwen3-235B-A22B-Thinking-2507；7 月 21 日发布 235B-A22B 非思考模式更新版 Qwen3-235B-A22B-Instruct-2507，较前版显著增强并支持 256K token 长上下文。2025 年 4 月 29 日发布 Qwen3 系列；2024 年 9 月 19 日发布 Qwen2.5 系列，新增 3B、14B、32B 三种规格；2024 年 6 月 6 日发布 Qwen2 系列；2024 年 3 月 28 日发布 Qwen 首个 MoE 模型 Qwen1.5-MoE-A2.7B（初期仅 HF Transformers 与 vLLM 支持，后续补齐 llama.cpp、mlx-lm 等）；2024 年 2 月 5 日发布 Qwen1.5 系列。

在模型规格上，Qwen3 家族提供稠密模型与混合专家模型多种尺寸：稠密侧有 0.6B、1.7B、4B、8B、14B、32B，MoE 侧有 30B-A3B 与 235B-A22B；Qwen3-2507 则覆盖 235B-A22B、30B-A3B、4B 三种规格，且每种都有 Instruct（对话）与 Thinking（思考）两个变体。Qwen2.5 系列在此基础上补充了 3B、14B、32B 等更多可能性，作为 Qwen3 之前一代主力开源模型，它的技术报告（arXiv:2412.15115）系统阐述了预训练、后训练与对齐方法，至今仍是许多下游应用的首选基座。详细评测结果见 Qwen3 博客（Qwen3-2507 评测博客即将发布）；各模型所需的 GPU 显存与对应吞吐数据，见官方速度基准文档。

三、环境要求

Transformers 推理：需要最新版 Transformers，官方要求 transformers>=4.51.0，搭配 PyTorch 使用；GPU 显存按模型规格选择，256K 长上下文可通过 --max-model-len 262144 等参数启用。
模型下载：大陆用户强烈建议使用 ModelScope，其 Python API 与 Transformers 类似，学习成本很低；命令行工具 modelscope download 可以帮助解决检查点下载慢、断连重试等问题；vLLM 与 SGLang 可分别通过环境变量 VLLM_USE_MODELSCOPE=true、SGLANG_USE_MODELSCOPE=true 让框架直接从 ModelScope 拉权重，无需手工下载。
llama.cpp：为完整支持 Qwen3，推荐 llama.cpp>=b5401，可在多种硬件上以极低配置完成推理。
Ollama：建议 Ollama v0.9.0 或更高版本；服务默认端口为 11434，OpenAI 兼容 API 位于 http://localhost:11434/v1/。
MLX LM：Apple Silicon 上运行需 mlx-lm>=0.24.0，在 Hugging Face Hub 上找以 MLX 结尾的模型名。
SGLang 部署：需要 sglang>=0.4.6.post1，启动后 OpenAI 兼容 API 位于 http://localhost:30000/v1。
vLLM 部署：推荐 vllm>=0.9.0，API 位于 http://localhost:8000/v1。
TensorRT-LLM：NVIDIA GPU 上推荐 tensorrt_llm>=0.20.0rc3，使用其重构后的 PyTorch 后端。
其他硬件：Intel CPU/GPU 可用 OpenVINO 工具包；移动端可用阿里 MNN；iOS/Android/Mac/Linux 可用 ExecuTorch；昇腾 NPU 可访问 Modelers 搜索 Qwen3 部署。

四、部署步骤与使用方法

4.1 Transformers 加载（Qwen3-Instruct-2507）

Transformers 是预训练自然语言处理库，用于推理与训练。以下代码演示如何基于 Qwen3-30B-A3B-Instruct-2507 根据输入生成内容：

from transformers import AutoModelForCausalLM, AutoTokenizer

model_name = "Qwen/Qwen3-30B-A3B-Instruct-2507"

# 加载分词器与模型
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype="auto",
    device_map="auto"
)

# 准备模型输入
prompt = "Give me a short introduction to large language model."
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=16384
)
output_ids = generated_ids[0][len(model_inputs.input_ids[0]):].tolist()

content = tokenizer.decode(output_ids, skip_special_tokens=True)

print("content:", content)

官方注意事项：Qwen3-Instruct-2507 只支持非思考模式，输出中不会生成 <think></think> 块，同时也不再需要显式传入 enable_thinking=False。

4.2 Transformers 加载（Qwen3-Thinking-2507）

from transformers import AutoModelForCausalLM, AutoTokenizer

model_name = "Qwen/Qwen3-30B-A3B-Thinking-2507"

tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype="auto",
    device_map="auto"
)

prompt = "Give me a short introduction to large language model."
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
)
output_ids = generated_ids[0][len(model_inputs.input_ids[0]):].tolist()

# 解析思考内容
try:
    # rindex 查找 151668（</think>）
    index = len(output_ids) - output_ids[::-1].index(151668)
except ValueError:
    index = 0

thinking_content = tokenizer.decode(output_ids[:index], skip_special_tokens=True).strip("\n")
content = tokenizer.decode(output_ids[index:], skip_special_tokens=True).strip("\n")

print("thinking content:", thinking_content)  # 没有开头的 <think> 标签
print("content:", content)

官方注意事项：Qwen3-Thinking-2507 只支持思考模式；默认聊天模板会自动带上 <think>，因此模型输出只有 </think> 而没有显式开头标签属于正常现象；该模型思考长度更大，建议在足够大的最大生成长度下用于高度复杂的推理任务。

对于此前的 Qwen3 模型，默认会先思考再回答，可通过两种方式控制：给 tokenizer.apply_chat_template 传 enable_thinking=False 严格阻止思考内容；或在系统/用户消息中写入 /think 与 /no_think 指令，多轮对话中以最新一条指令为准。需要特别留意的是，Qwen3-Thinking-2507 与 Qwen3-Instruct-2507 已经把模式固定：前者只出思考结果、后者只出非思考结果，因此 2507 版本不再需要 enable_thinking 开关，也不支持混合切换。官方强烈建议把 Thinking 模型用在高度复杂的推理任务上，并配置足够大的最大生成长度（示例中为 32768），因为该版本的思考长度比此前模型更长。

4.3 llama.cpp 本地运行

命令行方式：

./llama-cli -hf Qwen/Qwen3-8B-GGUF:Q8_0 --jinja --color -ngl 99 -fa -sm row --temp 0.6 --top-k 20 --top-p 0.95 --min-p 0 -c 40960 -n 32768 --no-context-shift
# 按 CTRL+C 退出

API 服务器方式：

./llama-server -hf Qwen/Qwen3-8B-GGUF:Q8_0 --jinja --reasoning-format deepseek -ngl 99 -fa -sm row --temp 0.6 --top-k 20 --top-p 0.95 --min-p 0 -c 40960 -n 32768 --no-context-shift --port 8080

启动后，简易 Web 前端位于 http://localhost:8080，OpenAI 兼容 API 位于 http://localhost:8080/v1。官方说明：llama.cpp 采用"旋转上下文管理"，通过淘汰早期 token 实现无限生成；上面的命令实际上关闭了这一机制，详见 llama.cpp 文档。

4.4 Ollama 运行

先安装 Ollama，然后启动服务（使用过程中需保持服务常驻）：

ollama serve

拉取并运行模型，可在 qwen3 后加 :8b、:30b-a3b 等后缀指定规格：

ollama run qwen3:8b
# 设置参数：输入 "/set parameter num_ctx 40960" 和 "/set parameter num_predict 32768"
# 退出：输入 "/bye" 回车
# 对于 Qwen3-2504 模型：默认开启思考，输入 "/set think" 开启，输入 "/set nothink" 关闭

也可通过 Ollama 的 OpenAI 兼容 API 访问服务，默认地址 http://localhost:11434/v1/；注意使用 API 时要保持 ollama serve 运行，并且先执行一次 ollama run qwen3:8b 确保检查点就绪。官方提示：Ollama 的命名可能与 Qwen 原名不一致，例如截至 2025 年 8 月 qwen3:30b-a3b 指向 qwen3:30b-a3b-thinking-2507-q4_K_M，使用前请查看 Ollama 模型标签页；Ollama 默认参数（num_ctx 2048、num_predict -1）对 Qwen3 可能带来问题，建议正确设置这两个参数。

4.5 LM Studio、MLX、OpenVINO、MNN、ExecuTorch

LM Studio 已支持 Qwen3，可直接使用官方 GGUF 文件，通过图形界面加载权重、调整参数并开始对话，适合不想写命令行的用户。Apple Silicon 上用 mlx-lm（mlx-lm>=0.24.0），在 Hugging Face Hub 找文件名以 MLX 结尾的模型即可。Intel CPU/GPU 上可用 OpenVINO，参考官方仓库的聊天机器人示例在本地笔记本上运行。移动端导出运行见阿里 MNN，它支持在手机等移动设备上跑 Qwen3；iOS/Android/Mac/Linux 全平台导出运行见 ExecuTorch 示例。

4.6 大规模部署（SGLang / vLLM / TensorRT-LLM）

SGLang 是面向大语言模型与视觉语言模型的高速服务框架：

# Qwen3-Instruct-2507
python -m sglang.launch_server --model-path Qwen/Qwen3-30B-A3B-Instruct-2507 --port 30000 --context-length 262144

# Qwen3-Thinking-2507
python -m sglang.launch_server --model-path Qwen/Qwen3-30B-A3B-Thinking-2507 --port 30000 --context-length 262144 --reasoning-parser deepseek-r1

# Qwen3 通用
python -m sglang.launch_server --model-path Qwen/Qwen3-8B --port 30000 --context-length 131072 --reasoning-parser qwen3

OpenAI 兼容 API 位于 http://localhost:30000/v1。

vLLM 是高吞吐、显存高效的推理服务引擎（推荐 vllm>=0.9.0）：

# Qwen3-Instruct-2507
vllm serve Qwen/Qwen3-30B-A3B-Instruct-2507 --port 8000 --max-model-len 262144

# Qwen3-Thinking-2507
vllm serve Qwen/Qwen3-30B-A3B-Thinking-2507 --port 8000 --max-model-len 262144 --enable-reasoning --reasoning-parser deepseek_r1

# Qwen3 通用
vllm serve Qwen/Qwen3-8B --port 8000 --max-model-len 131072 --enable-reasoning --reasoning-parser qwen3

OpenAI 兼容 API 位于 http://localhost:8000/v1。官方共同提示：由于 SGLang 与 vLLM 对 API 请求的预处理会丢弃所有 reasoning_content 字段，思考模型的多步工具调用质量可能不理想，临时变通方案是不要抽取思考内容、原样传入，由聊天模板正确处理。

TensorRT-LLM 是 NVIDIA 开源的推理引擎，提供自定义注意力 Kernel、量化等优化，Qwen3 已在其重构后的 PyTorch 后端支持：

trtllm-serve Qwen/Qwen3-8B --host localhost --port 8000 --backend pytorch

API 同样位于 http://localhost:8000/v1。对于昇腾 NPU 上的部署，官方建议访问 Modelers 并搜索 Qwen3 即可找到对应方案。此外，也可直接使用阿里云百炼 Model Studio 等推理服务商提供的 Qwen3 模型，免去本地部署与运维成本。

4.7 工具调用与微调

工具调用能力推荐使用 Qwen-Agent，它在 Qwen 系列 API 之上做了封装，支持工具调用/函数调用，并已支持 MCP 协议；也可通过 SGLang、vLLM、Transformers、llama.cpp、Ollama 等框架开启工具支持，具体开启方式见官方文档对应章节。微调方面建议使用成熟训练框架，包括 Axolotl、UnSloth、Swift、LLaMA-Factory 等，配合完成 SFT（监督微调）、DPO（直接偏好优化）、GRPO（组相对策略优化）等后训练流程。官方文档的训练章节还会持续补充 RLHF 等后训练指引。

五、常见问题 FAQ

Qwen3-Instruct 与 Qwen3-Thinking 怎么选？ 前者只做非思考对话，输出不包含思考块，适合高效通用聊天；后者只做深度思考，适合数学、代码、复杂逻辑推理，需留足最大生成长度（如 32768）。
如何启用 256K / 100 万 token 长上下文？ SGLang 用 --context-length 262144，vLLM 用 --max-model-len 262144；100 万 token 用法见对应模型卡（235B-A22B-Instruct-2507、235B-A22B-Thinking-2507、30B-A3B-Instruct/Thinking-2507）。
大陆用户下载慢怎么办？ 使用 ModelScope，vLLM 设 VLLM_USE_MODELSCOPE=true，SGLang 设 SGLANG_USE_MODELSCOPE=true，或用 modelscope download 命令行下载检查点。
Ollama 上找不到对应模型名？ Ollama 的标签名可能带 -thinking-2507-q4_K_M 后缀，以 Ollama 库页面为准；同时务必把 num_ctx 调到 40960 量级，否则默认 2048 上下文会出问题。
多步工具调用时思考模型质量差？ 这是 SGLang/vLLM 预处理丢弃 reasoning_content 导致的已知问题，临时方案是原样传入完整对话内容，不要手工剔除思考段。
llama.cpp 一长段参数都是什么意思？ 命令中 -hf Qwen/Qwen3-8B-GGUF:Q8_0 表示直接从 Hugging Face 拉取 Q8_0 量化的 GGUF 权重；--jinja 启用聊天模板；-ngl 99 把全部层放到 GPU；-fa 开启 FlashAttention；-sm row 为 Split Mode 行布局；--temp 0.6 --top-k 20 --top-p 0.95 --min-p 0 是官方推荐的采样参数；-c 40960 上下文长度；-n 32768 最大生成 token；--no-context-shift 关闭旋转上下文管理。llama.cpp 默认通过淘汰早期 token 实现无限生成，该参数可通过配置调整，详见官方文档。
如何在本地移动端跑 Qwen？ 苹果芯片用 mlx-lm>=0.24.0，在 Hugging Face Hub 找 MLX 后缀的模型即可一键加载；移动端部署用阿里 MNN，已支持 Qwen3 在手机上运行；iOS/Android/Mac/Linux 跨端用 ExecuTorch，参考官方仓库示例完成导出；Intel 平台用 OpenVINO，配合官方 Notebook 即可在笔记本上对话。
可以商用吗？ 官方所有开放权重模型均为 Apache 2.0 许可，许可文件在各 Hugging Face 仓库中。
如何引用？ 论文引用见 Qwen3 (arXiv:2505.09388)、Qwen2.5 (arXiv:2412.15115)、Qwen2 (arXiv:2407.10671) 的 BibTeX（见仓库 README 引用章节）。

六、跳转链接

如果你希望向 Qwen 研究团队或产品团队留言反馈，可加入官方 Discord 或微信群（群二维码见仓库 README 中的 wechat 图片）。以下是本次整理涉及的全部入口：

仓库主页：github.com/QwenLM/Qwen2.5
官方文档：qwen.readthedocs.io
Hugging Face：huggingface.co/Qwen
ModelScope：modelscope.cn/organization/qwen
在线体验：chat.qwen.ai
部署框架：SGLang、vLLM、TensorRT-LLM、llama.cpp、Ollama
智能体框架：Qwen-Agent

Qwen2.5：阿里通义千问开源大模型本地部署指南

Qwen2.5：阿里通义千问开源大模型本地部署指南

一、项目官方信息

二、项目背景与模型介绍

三、环境要求

四、部署步骤与使用方法

4.1 Transformers 加载（Qwen3-Instruct-2507）

4.2 Transformers 加载（Qwen3-Thinking-2507）

4.3 llama.cpp 本地运行

4.4 Ollama 运行

4.5 LM Studio、MLX、OpenVINO、MNN、ExecuTorch

4.6 大规模部署（SGLang / vLLM / TensorRT-LLM）

4.7 工具调用与微调

五、常见问题 FAQ

六、跳转链接

周若琳

文章目录