Qwen3-4B-Thinking模型Ubuntu 20.04部署保姆级教程：从系统安装到模型运行

本文介绍了如何在星图GPU平台上自动化部署Qwen3-4B-Thinking-2507-GPT-5-Codex-Distill-GGUF镜像，快速搭建AI模型运行环境。该镜像集成了经过优化的Qwen大语言模型，用户可轻松将其应用于智能对话、代码生成与解释等场景，显著降低部署门槛，提升开发效率。

芦苇毛

92人浏览 · 2026-03-18 01:01:25

芦苇毛 · 2026-03-18 01:01:25 发布

Qwen3-4B-Thinking模型Ubuntu 20.04部署保姆级教程：从系统安装到模型运行

如果你对AI大模型感兴趣，想亲手部署一个能“思考”的模型来玩玩，那Qwen3-4B-Thinking绝对是个不错的起点。它体积适中，对硬件要求相对友好，但功能却不含糊。不过，万事开头难，尤其是当你面对一个全新的Ubuntu系统时，可能会觉得无从下手。

别担心，这篇教程就是为你准备的。我会带你从零开始，一步一步完成整个部署过程。我们不谈复杂的理论，只关注怎么把东西跑起来。从安装Ubuntu 20.04系统，到配置好所有环境，最后成功启动模型服务，整个过程我都会讲得明明白白。即使你之前没怎么接触过Linux，跟着做也能搞定。

1. 第一步：准备好你的“舞台”——安装Ubuntu 20.04

部署模型就像搭积木，地基不稳，后面全白搭。我们的地基就是Ubuntu 20.04操作系统。这里我假设你是在一台全新的物理机或者虚拟机上操作。

1.1 制作系统安装U盘

首先，你需要准备一个至少8GB的U盘，用来制作系统启动盘。

下载系统镜像：去Ubuntu官网找到20.04 LTS版本的桌面版ISO镜像文件，把它下载到你的电脑上。LTS代表长期支持版，更稳定。
制作启动盘：在Windows上可以用Rufus，在macOS上可以用balenaEtcher。这两个都是免费工具，操作很简单，基本就是选择你下载的ISO文件，选择你的U盘，然后点击“开始”或“Flash”。制作过程会清空U盘里的所有数据，记得提前备份。

1.2 安装Ubuntu系统

把制作好的U盘插到你要安装系统的电脑上，开机进入BIOS设置从U盘启动。不同电脑进入BIOS的按键不同，常见的是F2、F12、Delete键，开机时留意屏幕提示。

启动安装程序：成功从U盘启动后，你会看到Ubuntu的安装界面。选择“Install Ubuntu”。
选择语言和键盘布局：按你的习惯来选就行。
安装类型：这里要小心。如果你是给整台电脑装系统，可以选择“清除整个磁盘并安装Ubuntu”。如果你是想和Windows共存（双系统），请选择“其他选项”进行手动分区。对于新手，如果电脑没有重要数据，直接选“清除整个磁盘”最省事。
设置时区、用户名和密码：创建一个你的用户名和密码，这个密码以后会经常用到，请牢记。
等待安装：点击“继续”，系统就会开始自动安装。喝杯咖啡，等个十几二十分钟。
重启：安装完成后，提示你重启。拔掉U盘，然后按回车重启，你就进入全新的Ubuntu系统了。

2. 第二步：给系统“打基础”——基础配置与环境准备

系统装好了，但还是个“毛坯房”。我们需要安装一些必要的工具，并配置好网络。

2.1 系统更新与基础工具安装

打开终端（快捷键 Ctrl+Alt+T），我们开始敲命令。别怕，一行一行来。

首先，更新一下系统的软件包列表，并升级已有的软件。这能确保我们安装的是最新最稳定的版本。

sudo apt update && sudo apt upgrade -y

输入命令后，会提示你输入密码（就是你安装时设的那个），输入时光标不会动，这是正常的，输完按回车就行。

接着，安装一些后续步骤必备的工具，比如用于下载文件的 wget、curl，解压工具 unzip，还有代码版本管理工具 git。

sudo apt install -y wget curl git unzip

2.2 安装NVIDIA驱动和CUDA

这是最关键的一步，因为我们要用GPU来跑模型。Qwen3-4B-Thinking在CPU上也能跑，但速度会慢很多。

检查显卡：先确认你的电脑有NVIDIA显卡。
```
lspci | grep -i nvidia
```
如果能看到显卡信息，比如“NVIDIA Corporation GP106 [GeForce GTX 1060]”之类的，就说明识别到了。
安装驱动：Ubuntu提供了一个比较省心的方法，通过附加驱动来安装。
- 打开“软件和更新”应用。
- 切换到“附加驱动”标签页。
- 系统会自动检测可用的NVIDIA驱动，选择一个带“proprietary”（专有）和“tested”（已测试）标识的推荐版本，然后点击“应用更改”。系统会自动下载并安装。
- 安装完成后，必须重启电脑。
验证驱动：重启后打开终端，输入：
```
nvidia-smi
```
如果看到显卡信息、驱动版本和CUDA版本（比如CUDA 12.4），就说明驱动安装成功了。这个命令以后会经常用来看GPU状态。

安装CUDA Toolkit：CUDA是NVIDIA的并行计算平台。我们可以通过系统包管理器安装一个稳定版本。对于Ubuntu 20.04，CUDA 11.x或12.x都是常见选择。这里以CUDA 11.8为例（请根据你nvidia-smi显示的推荐版本调整）：

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2004/x86_64/cuda-ubuntu2004.pin
sudo mv cuda-ubuntu2004.pin /etc/apt/preferences.d/cuda-repository-pin-600
sudo apt-key adv --fetch-keys https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2004/x86_64/3bf863cc.pub
sudo add-apt-repository "deb https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2004/x86_64/ /"
sudo apt update
sudo apt install -y cuda-11-8

安装完成后，将CUDA添加到环境变量，让系统能找到它：

echo 'export PATH=/usr/local/cuda-11.8/bin${PATH:+:${PATH}}' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-11.8/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}' >> ~/.bashrc
source ~/.bashrc

验证CUDA安装：nvcc --version，应该能看到版本信息。

2.3 安装Miniconda（Python环境管理）

我们强烈建议使用Conda来管理Python环境，它可以为不同的项目创建独立的运行环境，避免包冲突。

下载安装脚本：

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh

运行安装脚本：
```
bash Miniconda3-latest-Linux-x86_64.sh
```
安装过程中，一直按回车阅读许可协议，输入“yes”同意。安装路径用默认的就行（/home/你的用户名/miniconda3）。最后会问你是否初始化Conda，选择“yes”。这样每次打开终端，Conda环境就会自动激活。
生效配置：关闭当前终端，再重新打开一个新的终端。你会发现命令行前面多了个 (base)，这表示你已经在Conda的base环境里了。

3. 第三步：搭建模型的“工作间”——创建专属环境

现在基础打好了，我们为Qwen模型创建一个专属的Python环境。

创建新环境：我们起个名字叫 qwen_env，并指定Python版本为3.10（一个兼容性很好的版本）。
```
conda create -n qwen_env python=3.10 -y
```
激活环境：创建好后，进入这个环境。
```
conda activate qwen_env
```
看到命令行提示符从 (base) 变成 (qwen_env)，就说明切换成功了。之后所有操作都要在这个环境下进行。
安装PyTorch：这是深度学习的基础框架。去PyTorch官网根据你的CUDA版本选择安装命令。假设你是CUDA 11.8：
```
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
```
安装模型运行依赖：主要是Hugging Face的 transformers 库和 accelerate（用于优化推理）。
```
pip install transformers accelerate
```
根据模型的具体要求，可能还需要 sentencepiece 或 tiktoken 等分词器库，我们可以先装上常用的：
```
pip install sentencepiece tiktoken
```

4. 第四步：请“主角”登场——获取并运行模型

环境齐备，终于可以请出我们的主角Qwen3-4B-Thinking模型了。

4.1 下载模型文件

模型文件通常比较大（几个GB），我们可以直接从Hugging Face Hub下载。这里假设我们要下载 Qwen/Qwen2.5-4B-Instruct 这个指令微调版本（请根据实际模型名称替换）。

使用git-lfs：大文件需要用 git-lfs 来拉取。先安装它：
```
sudo apt install -y git-lfs
git lfs install
```
克隆模型仓库：找一个空间足够的目录，比如在用户目录下创建一个 models 文件夹。
```
mkdir ~/models && cd ~/models
git clone https://huggingface.co/Qwen/Qwen2.5-4B-Instruct
```
这个过程会比较久，因为要下载模型权重文件。耐心等待，可以去看看nvidia-smi，有时候下载工具也会用到一点GPU。

4.2 编写一个简单的推理脚本

模型下载好了，我们写一个最简单的Python脚本来测试它是否能正常运行。

在你喜欢的位置（比如 ~/models 目录下）创建一个文件，叫 run_qwen.py：

from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

# 指定模型路径，就是你刚才git clone下来的文件夹路径
model_path = "./Qwen2.5-4B-Instruct"

# 加载分词器和模型
print("正在加载分词器...")
tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True)

print("正在加载模型到GPU...这可能需要几分钟，请耐心等待。")
model = AutoModelForCausalLM.from_pretrained(
    model_path,
    torch_dtype=torch.float16,  # 使用半精度浮点数，节省显存
    device_map="auto",          # 自动将模型层分配到可用的GPU/CPU上
    trust_remote_code=True
)
print("模型加载完成！")

# 将模型设置为评估模式
model.eval()

# 准备对话
messages = [
    {"role": "system", "content": "你是一个乐于助人的AI助手。"},
    {"role": "user", "content": "请用一句话介绍一下你自己。"}
]

# 将对话格式化为模型接受的输入
text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
model_inputs = tokenizer([text], return_tensors="pt").to(model.device)

# 生成回复
print("\n正在生成回复...")
with torch.no_grad():  # 禁用梯度计算，推理时不需要
    generated_ids = model.generate(
        **model_inputs,
        max_new_tokens=512,  # 最多生成512个新token
        do_sample=True,      # 使用采样方式，让输出更有创造性
        temperature=0.7,     # 采样温度，控制随机性
        top_p=0.9            # 核采样参数，控制输出多样性
    )

# 解码并打印结果
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("\n=== 模型回复 ===")
print(response)
print("================\n")

4.3 运行测试脚本

确保你的终端当前在 qwen_env 环境下，并且位于 run_qwen.py 脚本所在的目录。

运行它：

python run_qwen.py

第一次运行会需要一些时间加载模型到显存中。如果一切顺利，你会看到加载进度条，最后模型会输出一段自我介绍。看到这个，恭喜你，模型已经成功跑起来了！

5. 总结

走完这一整套流程，你可能觉得步骤不少，但每一步都是在为最终能顺畅运行模型铺路。从给电脑装上Ubuntu系统，到安装显卡驱动和CUDA，再到用Conda管理Python环境，最后下载模型并运行测试脚本，我们就像完成了一次从零搭建一个小型AI实验室的旅程。

过程中最可能出问题的地方就是驱动和CUDA的安装，如果 nvidia-smi 命令能正确显示信息，后面就成功了一大半。另外，下载模型需要良好的网络环境和足够的磁盘空间，如果遇到中断，可以使用 git lfs pull 在模型目录内继续拉取。

这个教程给你的是一个最基础的、能跑通的流程。真正要用起来，你可能会考虑用更高效的推理框架（比如vLLM），或者为模型提供一个Web API接口方便调用。但无论如何，第一步“跑起来”是最重要的。希望这篇详细的指南能帮你扫清最初的障碍，让你能更专注于探索模型本身的能力。动手试试吧，看着自己部署的模型生成第一句话，那种感觉还是挺棒的。