《Qwen 本地部署教程：基于 Transformers 在 Ubuntu 上快速跑通第一个中文大模型 Demo》

三无推导

689人浏览 · 2026-06-05 09:42:28

三无推导 · 2026-06-05 09:42:28 发布

在这里插入图片描述

如果你最近在看中文大模型，Qwen 基本绕不过去。
但大模型这类项目有个很现实的问题：看起来很强，真正动手时，往往不是代码先拦你，而是环境、显存、依赖版本先给你上一课。
这篇文章不聊热度，也不空谈能力边界，直接走最实用的路线：先把 Qwen 在本地跑通，拿到第一轮中文输出再说。

一、项目背景

Qwen 是阿里开源的通义千问大语言模型仓库，提供了基础模型、对话模型、量化模型，以及基于 Transformers 的推理、微调和部署示例。对于普通开发者来说，它最大的价值不是“概念上很强”，而是有清晰的官方仓库、有明确的推理样例、也有比较完整的部署路径。

如果你只是想快速体验中文大模型，本地跑一个最小 Demo，Qwen 是比较合适的选择。它既支持基于 Transformers 的直接调用，也提供了量化模型、API、Web Demo、Docker 等延伸路线，后续扩展空间比较大。

官方GitHub的项目地址:
https://github.com/QwenLM/Qwen

不过这里有一个必须提前说明的点：

官方仓库 README 已明确提示：Qwen2 已发布，当前 QwenLM/Qwen 仓库已不再积极维护。
所以本文更适合作为 Qwen 经典仓库的上手部署教程。如果你后续要追新版本，建议进一步关注 Qwen2 对应仓库和文档。

这篇文章的目标也很明确：

在 Ubuntu 上准备 Python 环境
安装 Qwen 推理依赖
使用官方示例代码跑通一次中文对话
验证模型是否成功加载
总结几个最常见的报错处理方式

二、本文环境说明

本文采用的是保守、容易复现的最小部署路径。
在这里插入图片描述

操作系统：Ubuntu 22.04
Python 版本：Python 3.10
PyTorch 版本：建议 2.x
Transformers 版本：官方 README 提示建议 4.32+
部署方式：本地 Python 虚拟环境 + Transformers 推理
是否为简化方案：是

本文优先使用最简单的本地推理方式，不展开 vLLM、FastChat、Docker API 等进阶部署。
硬件要求：
- 推荐有 NVIDIA GPU
- 如果显存有限，建议优先尝试小模型或量化模型
- CPU 也能跑，但官方也明确提醒：纯 CPU 推理效率会非常低

关于模型选择的建议

为了尽量让普通开发者更容易跑通，本文建议优先尝试：

Qwen/Qwen-1_8B-Chat 或仓库中可用的小体量聊天模型
如果你机器条件更好，再尝试 7B 及以上

注意：官方 README 中不同位置出现了 1.8B 和 1_8B 这类命名差异，实际拉取时请以 Hugging Face / ModelScope 对应模型页名称为准。
如果模型名拉不下来，不是你人不行，大概率是模型仓库命名或网络源不同。

三、安装前准备

1. 检查 Python 版本

python3 --version

如果没有 Python 3.8 以上版本，先安装：

sudo apt update
sudo apt install -y python3 python3-pip python3-venv git

2. 创建虚拟环境

建议不要直接污染系统 Python 环境。

python3 -m venv qwen-env
source qwen-env/bin/activate

激活后，终端前面一般会出现 (qwen-env)。

3. 升级 pip

pip install --upgrade pip

4. 获取项目代码

git clone https://github.com/QwenLM/Qwen.git
cd Qwen

5. 安装依赖

官方 README 给出的核心方式是：

pip install -r requirements.txt

如果你是 GPU 环境，通常还需要确保 PyTorch 与 CUDA 版本匹配。
更稳妥的做法是先按你的 CUDA 环境安装对应版本的 PyTorch，再安装仓库依赖。

例如：

pip install torch torchvision torchaudio
pip install -r requirements.txt

如果你对 CUDA 版本比较敏感，建议先去 PyTorch 官网按你的驱动/CUDA 版本选安装命令。
这一步最容易翻车，别一上来全怪 Qwen，很多时候是本地 Torch 和 CUDA 根本没对上。

6. 可选：安装 flash-attention

官方说明里提到，如果设备支持 fp16 或 bf16，可以安装 flash-attention 提升效率，但它是可选项，不是必须。

如果你只是想先跑通，可以先不装。
先拿到结果，再谈加速，这个顺序会更友好。

四、安装与部署

这一部分我们走官方 README 中最基础、最稳定的路线：Transformers 直接加载聊天模型。

1. 新建最小 Demo 脚本

在项目根目录下创建一个文件，比如 demo_qwen_chat.py：

from transformers import AutoModelForCausalLM, AutoTokenizer

MODEL_NAME = "Qwen/Qwen-7B-Chat"

tokenizer = AutoTokenizer.from_pretrained(
    MODEL_NAME,
    trust_remote_code=True
)

model = AutoModelForCausalLM.from_pretrained(
    MODEL_NAME,
    device_map="auto",
    trust_remote_code=True
).eval()

response, history = model.chat(tokenizer, "你好，介绍一下你自己。", history=None)
print("模型回复：")
print(response)

2. 先根据你的硬件条件调整模型名

如果你显存不够，建议不要一上来就上 7B。可以先尝试更小的聊天模型。

例如你可以把：

MODEL_NAME = "Qwen/Qwen-7B-Chat"

改成更小规格的模型名。
但这里要强调一句：

具体模型名请以官方模型仓库页面为准。
官方 GitHub README 中展示了多个模型，但实际下载名称可能因 Hugging Face / ModelScope 目录规则有所差异。

3. 运行脚本

python demo_qwen_chat.py

如果一切顺利，第一次运行会发生两件事：

自动下载模型权重和相关代码
初始化 tokenizer 与模型

首次下载时间可能比较久，取决于：

网络环境
模型大小
存储速度

4. 如果 Hugging Face 下载慢或失败

官方 README 明确给出了一条替代路线：用 ModelScope 先下载到本地，再从本地目录加载。

你可以先安装：

pip install modelscope

然后参考官方方式写成本地加载脚本：

from modelscope import snapshot_download
from transformers import AutoModelForCausalLM, AutoTokenizer

model_dir = snapshot_download('qwen/Qwen-7B-Chat')

tokenizer = AutoTokenizer.from_pretrained(
    model_dir,
    trust_remote_code=True
)

model = AutoModelForCausalLM.from_pretrained(
    model_dir,
    device_map="auto",
    trust_remote_code=True
).eval()

response, history = model.chat(tokenizer, "你好，请用中文做个自我介绍。", history=None)
print(response)

运行：

python demo_qwen_chat.py

这一条路线对国内网络环境通常更友好一些。

五、配置说明

Qwen 这个最小部署路径本身不依赖复杂配置文件，但有几个关键点必须说明清楚。

1. `trust_remote_code=True`

这是官方示例里一直保留的参数，因为 Qwen 依赖仓库自定义代码来加载模型和 tokenizer。

示例：

trust_remote_code=True

如果你删掉它，很多情况下会直接报：

tokenizer 类找不到
模型结构无法识别
remote code 未被信任

所以这不是“可有可无”的装饰参数。

2. `device_map="auto"`

device_map="auto"

这个参数会让 Transformers 自动尝试选择设备并分配模型。

适合：

单卡 GPU
多卡机器
想尽量少写设备映射逻辑的场景

如果你明确只想 CPU 跑，也可以写成：

device_map="cpu"

但还是那句话：能跑，不等于能愉快地跑。CPU 推理通常慢得很诚实。

3. 精度设置

官方示例中也给出了：

bf16=True
fp16=True

例如：

model = AutoModelForCausalLM.from_pretrained(
    MODEL_NAME,
    device_map="auto",
    trust_remote_code=True,
    fp16=True
).eval()

如果你知道自己的 GPU 支持半精度，可以尝试这样做来降低显存占用。
但如果你只是想快速复现，建议先用最基础写法跑通，再逐步优化。

4. 量化模型

官方 README 也支持 Int4 / Int8 模型，例如：

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen-7B-Chat-Int4",
    device_map="auto",
    trust_remote_code=True
).eval()

如果你显存有限，这条路其实很有价值。
但量化模型依赖链也更复杂一些，尤其涉及 auto-gptq、optimum 等版本适配。
所以本文先不把主线放在量化部署上，避免第一篇教程就把读者送进版本地狱。

六、跑通第一个 Demo

最小闭环不是“成功 import 了包”，而是真正拿到模型输出。

下面给一个更完整一点的 Demo。
在这里插入图片描述

1. 准备脚本

创建 demo_qwen_dialog.py：

from transformers import AutoModelForCausalLM, AutoTokenizer

MODEL_NAME = "Qwen/Qwen-7B-Chat"

tokenizer = AutoTokenizer.from_pretrained(
    MODEL_NAME,
    trust_remote_code=True
)

model = AutoModelForCausalLM.from_pretrained(
    MODEL_NAME,
    device_map="auto",
    trust_remote_code=True
).eval()

response, history = model.chat(tokenizer, "你好", history=None)
print("第1轮回复：")
print(response)

response, history = model.chat(
    tokenizer,
    "给我讲一个适合程序员看的简短励志故事。",
    history=history
)
print("\n第2轮回复：")
print(response)

response, history = model.chat(
    tokenizer,
    "请给这个故事起一个标题。",
    history=history
)
print("\n第3轮回复：")
print(response)

2. 执行命令

python demo_qwen_dialog.py

3. 成功后应该看到什么

如果部署成功，你会看到类似这样的输出结构：

第1轮回复：
你好！很高兴为你提供帮助。

第2轮回复：
......

第3轮回复：
......

不用一字不差和官方示例一致。
只要满足下面几个条件，就说明最小闭环已经打通：

模型能成功加载
能处理中文输入
能连续对话并保留上下文
没有在推理阶段直接崩掉

七、效果验证

部署完别急着宣布胜利，至少做下面 3 类验证。

验证方式 1：观察模型是否成功返回自然语言结果

这是最直接的。

如果返回的是正常中文回答，而不是报错、空输出、卡死，说明推理链路基本可用。

验证方式 2：确认模型下载缓存是否已生成

一般 Hugging Face 模型会缓存在用户目录下，例如：

ls ~/.cache/huggingface/

如果使用 ModelScope，也会有对应缓存目录。
能看到模型文件、配置文件、tokenizer 文件，说明模型资源已经拉到本地。

验证方式 3：检查 GPU 是否真的被使用

如果你是 GPU 环境，可以另开终端执行：

nvidia-smi

观察是否有 Python 进程占用显存。

什么现象说明成功：

出现 Python 进程
显存明显上涨
推理期间 GPU 利用率有波动

如果你本来想走 GPU，结果 nvidia-smi 一看风平浪静，那模型很可能悄悄跑到 CPU 上去了。

验证方式 4：看日志与报错信息是否停留在模型加载阶段

如果程序卡在下载阶段，多半是网络问题。
如果卡在加载阶段，多半是：

显存不够
Torch / CUDA 版本不匹配
远程代码加载异常

这和“模型会不会说话”是两回事，别混着排查。

八、常见报错与解决方案

这一节保留，而且必须说人话。很多大模型部署问题，真不是项目本身有多离谱，而是环境太喜欢埋雷。
在这里插入图片描述

1. `ModuleNotFoundError` 或依赖安装失败

现象

运行脚本时报缺少 transformers、torch、modelscope 等包。

解决方案

先确认你已经激活虚拟环境：

source qwen-env/bin/activate

然后重新安装：

pip install -r requirements.txt

如果还缺包，就按报错补装，例如：

pip install transformers modelscope

2. 模型下载失败、超时或卡住

现象

拉取 Hugging Face 模型时报网络超时，或者下载速度极慢。

解决方案

优先改走官方 README 提供的 ModelScope 路线：

pip install modelscope

使用 snapshot_download() 先把模型拉到本地，再从本地目录加载。
这通常比硬扛外网下载更省时间。

3. 显存不足，出现 OOM

现象

程序运行到模型加载或生成阶段直接报显存不足。

解决方案

按优先级处理：

先换更小模型
尝试量化模型（Int4 / Int8）
使用 fp16 / bf16
关闭其他占显存进程
必要时改 CPU 测试链路

例如尝试半精度：

model = AutoModelForCausalLM.from_pretrained(
    MODEL_NAME,
    device_map="auto",
    trust_remote_code=True,
    fp16=True
).eval()

如果还是炸，那就别硬扛 7B 了。
环境条件不够时，降模型规模比反复重装靠谱得多。

4. `Tokenizer class QWenTokenizer does not exist` 之类错误

现象

加载 tokenizer 时提示类不存在，或者远程代码未导入。

解决方案

先检查是否保留了：

trust_remote_code=True

如果你是在做 LoRA/PEFT 相关加载，官方 README 还特别提到某些 peft>=0.8.0 版本会触发这类问题，建议：

降级 peft
或按官方建议规避 tokenizer 自动加载问题

如果你只是跑最小 Demo，一般先别上 PEFT，那是后话。

5. CUDA 可见但模型还是跑在 CPU

现象

脚本能跑，但很慢，nvidia-smi 看不到有效显存占用。

解决方案

先在 Python 里检查 Torch 是否识别 GPU：

import torch
print(torch.cuda.is_available())

如果输出是 False，那不是 Qwen 的锅，是你的 Torch/CUDA 环境没打通。
需要重新安装匹配的 PyTorch 版本。

6. `trust_remote_code` 相关安全或加载报错

现象

模型或 tokenizer 无法识别，提示需要信任远程代码。

解决方案

确认加载代码中包含：

trust_remote_code=True

Qwen 官方示例就是这么写的，别擅自删。

7. 运行很慢，看起来像“卡死”

现象

脚本没报错，但半天没结果。

解决方案

先判断它是在：

下载模型
加载模型
还是实际推理

排查顺序建议：

看终端日志是否还在下载
看磁盘与网络是否有活动
看 nvidia-smi 是否有显存占用
如果是 CPU 跑大模型，慢是正常的，不是“死机”

大模型部署里最常见的误会之一，就是把“很慢”误判成“坏了”。

九、进阶说明

如果你已经跑通最小 Demo，后面可以往这些方向继续深入。

1. 使用量化模型

适合显存有限但想跑更大模型的场景。
官方 README 提供了 Int4 / Int8 路线，不过依赖版本更敏感。

2. 使用 vLLM 做高性能推理

官方明确建议在部署和快速推理场景下优先考虑 vLLM。
如果你要做服务化接口或更高吞吐，这条路线更值得看。

3. 使用 FastChat 或官方脚本搭建 Web/API

README 里提供了：

Web UI Demo
CLI Demo
OpenAI 风格 API

如果你后续要做本地服务接入业务系统，这部分价值会更高。

4. 使用 Docker 预构建镜像

官方给了预构建镜像 qwenllm/qwen，适合想减少环境折腾的人。
不过 Docker 路线通常更适合第二篇文章单独展开。

5. 微调与 LoRA / Q-LoRA

如果你不是只想体验，而是要做业务定制，后续可以研究官方的：

Full Finetune
LoRA
Q-LoRA

但这一块对显存、依赖和训练数据都有更高要求，不建议和“入门部署”混在一篇里。

十、总结

这篇文章走的是一条很务实的路线：不追求一上来就最强，只追求先把 Qwen 跑起来。

我们完成了这些事：

准备 Ubuntu 下的 Python 环境
安装 Qwen 基础依赖
用 Transformers 加载官方聊天模型
跑通最小中文对话 Demo
用日志、缓存和 GPU 占用验证部署结果
梳理了几类高频报错

如果你只是想先感受一下 Qwen，本地能正常回一句“你好”，其实已经够用了。

加入AMD AI开发者计划！

免费领 150 小时云算力，进群参与显卡、AI PC 幸运抽奖

更多推荐

读懂 ROCm 分层：HIP → ROCr → libhsakmt 核心概念对照表

AMD开发者中国社区

30 分钟，手把手带你从 0 到 1 跑通一个高性能 Token 服务

AMD开发者中国社区

【本地部署 BAAI/bge-m3 嵌入服务，Dify 私有知识库接入教程】

本文基于 vLLM+Docker 部署 BGE-M3 向量服务，详解参数、调优，手把手完成 Dify 知识库集成落地

AMD开发者中国社区

所有评论(0)

查看更多评论

三无推导

@2502_91558627

已为社区贡献4条内容

《Qwen 本地部署教程：基于 Transformers 在 Ubuntu 上快速跑通第一个中文大模型 Demo》

三无推导

一、项目背景

二、本文环境说明

关于模型选择的建议

三、安装前准备

1. 检查 Python 版本

2. 创建虚拟环境

3. 升级 pip

4. 获取项目代码

5. 安装依赖

6. 可选：安装 flash-attention

四、安装与部署

1. 新建最小 Demo 脚本

2. 先根据你的硬件条件调整模型名

3. 运行脚本

4. 如果 Hugging Face 下载慢或失败

五、配置说明

1. trust_remote_code=True

2. device_map="auto"

3. 精度设置

4. 量化模型

六、跑通第一个 Demo

1. 准备脚本

2. 执行命令

3. 成功后应该看到什么

七、效果验证

验证方式 1：观察模型是否成功返回自然语言结果

验证方式 2：确认模型下载缓存是否已生成

验证方式 3：检查 GPU 是否真的被使用

验证方式 4：看日志与报错信息是否停留在模型加载阶段

八、常见报错与解决方案

1. ModuleNotFoundError 或依赖安装失败

现象

解决方案

2. 模型下载失败、超时或卡住

现象

解决方案

3. 显存不足，出现 OOM

现象

解决方案

4. Tokenizer class QWenTokenizer does not exist 之类错误

现象

解决方案

5. CUDA 可见但模型还是跑在 CPU

现象

解决方案

6. trust_remote_code 相关安全或加载报错

现象

解决方案

7. 运行很慢，看起来像“卡死”

现象

解决方案

九、进阶说明

1. 使用量化模型

2. 使用 vLLM 做高性能推理

3. 使用 FastChat 或官方脚本搭建 Web/API

4. 使用 Docker 预构建镜像

5. 微调与 LoRA / Q-LoRA

十、总结

所有评论(0)

温馨提示：您尚未绑定手机号

三无推导

1. `trust_remote_code=True`

2. `device_map="auto"`

1. `ModuleNotFoundError` 或依赖安装失败

4. `Tokenizer class QWenTokenizer does not exist` 之类错误

6. `trust_remote_code` 相关安全或加载报错