在这里插入图片描述

如果你最近在看中文大模型，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

现象

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

解决方案

按优先级处理：

  1. 先换更小模型
  2. 尝试量化模型（Int4 / Int8）
  3. 使用 fp16 / bf16
  4. 关闭其他占显存进程
  5. 必要时改 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. 运行很慢，看起来像“卡死”

现象

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

解决方案

先判断它是在：

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

排查顺序建议：

  1. 看终端日志是否还在下载
  2. 看磁盘与网络是否有活动
  3. 看 nvidia-smi 是否有显存占用
  4. 如果是 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，本地能正常回一句“你好”，其实已经够用了。

# ubuntu # 运维 # python # pytorch
Logo
亚马逊云科技技术品牌专区

更多推荐

区块链系统设计思考

区块链技术自诞生以来，以其去中心化、不可篡改和透明性等特性，重塑了金融、供应链、物联网等领域的信任机制。本文将围绕区块链系统设计的核心问题，从共识机制、智能合约、隐私保护、可扩展性以及跨链互操作性五个方面展开探讨，为读者提供系统化的设计思路。设计时需根据场景需求权衡，例如联盟链可采用PBFT（实用拜占庭容错），在有限节点下实现快速共识。智能合约的自动化执行是区块链的重要功能，但其安全性至关重要。吞

avatar 亚马逊云科技技术品牌专区

分布式监控嵌入式架构

在物联网和工业4.0的浪潮下，嵌入式设备正以前所未有的规模接入网络，传统的集中式监控架构已难以应对海量数据和高并发需求。分布式监控嵌入式架构应运而生，它通过将计算、存储和通信能力下沉到边缘节点，实现了高效、弹性和低延迟的系统管理。例如，在工业生产线中，每个嵌入式传感器可独立完成异常检测，仅将关键数据上传至中心服务器，大幅提升了响应速度。某智慧农业项目中，系统通过实时分析土壤传感器负载，自动平衡边缘

avatar 亚马逊云科技技术品牌专区

软件活动网络图管理化的依赖分析

软件活动网络图管理化的依赖分析，正是通过可视化任务节点及其关联性，帮助团队优化资源分配、识别关键路径并降低风险。通过依赖分析，团队可以准确识别关键路径上的任务，并集中资源确保其按时完成。例如，若某开发任务延迟，网络图会实时反映其对后续测试和发布的影响，促使团队提前调整计划。例如，当多个模块依赖同一名开发人员时，网络图可以提示资源冲突，帮助管理者重新分配人力或调整任务顺序。未来，随着人工智能技术的融

avatar 亚马逊云科技技术品牌专区