> For the complete documentation index, see [llms.txt](https://book.ncrnalab.org/teaching/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.ncrnalab.org/teaching/getting-started/run-gpu-jobs-advanced.md).

# Run GPU jobs \[Advanced]

### 一、GPU使用注意事项

#### **1.1 多人共享使用方式和注意事项**

资源占用原则：多人使用CPU/GPU集群时需合理分配资源，避免长时间独占所有CPU/GPU核心；若需运行耗时较长的任务，建议避开服务器使用高峰时段（如工作日白天），优先选择夜间、周末运行。

**第一步：检查 GPU 状态，寻找空闲资源**

在终端输入 `nvidia-smi` 命令

```bash
nvidia-smi
```

> 会输出一张当前 GPU 的状态表。寻找空闲 GPU 时，只需重点看以下 4 个参数：\
> 1\. **GPU 编号 (GPU ID)**：表格最左侧的数字（如 0、1）。找到空闲卡后，后续运行代码需通过这个数字来指定显卡（例如指定用 0 号卡）。\
> 2\. **显存占用 (Memory-Usage)**：**最核心的指标**（格式如 `0MiB / 24564MiB`）。如果已用显存接近总量，说明卡被占满，强行去挤会导致显存溢出（OOM）报错崩溃；如果已用显存为 0 或极小，说明容量充足。\
> 3\. **算力利用率 (GPU-Util)**：表格右侧的百分比。`0%` 代表显卡核心正在闲置，高百分比（如 `99%`）代表正在满负荷计算。\
> 4\. **底部进程列表 (Processes)**：表格最下方会列出当前正在运行的程序占用了哪张卡。如果某张卡的编号没有出现在这里，说明它是完全纯净、无人在用的。\
> **💡 选卡总结**：挑选 GPU 时，尽量满足\*\*“显存占用极小 + 利用率接近 0% + 底部进程列表中没有该卡编号”\*\*这三个条件。

**第二步：合理分配 GPU 并提交后台任务**

在第一步观察好 GPU 状态后，我们需要在运行代码时明确指定使用哪几张卡，并将任务挂载到后台，以防断网或关闭电脑导致训练中断。推荐的标准命令格式如下：

```python
# 以使用 0 号和 1 号卡为例的python code 
model = torch.nn.DataParallel(model, device_ids=[0, 1])
# 以使用 0 号卡为例的python code 
model = torch.nn.DataParallel(model, device_ids=[0])
```

> **🔍** 详细的python 脚本见下文 [**2.1 Python脚本**](#id-2.1-python-jiao-ben)\
> **🔍** 也可以在bash、zsh等环境变量中定义可见的GPU，例如：\
> `CUDA_VISIBLE_DEVICES=0,2`\
> 但注意不要和python code中定义的冲突，除非特殊需要，一般建议就**不要**在环境变量里加限制了。

```bash
# run the python file: train.py
nohup python train.py > train.log 2>&1 &
```

> **🔍 后台无间断运行:** `nohup python train.py > train.log 2>&1 &` 训练任务通常耗时较长，如果直接运行，一旦你的电脑休眠或 SSH 终端断开，任务就会立刻终止。将 nohup 放在命令最前，& 放在最后，就能让程序在服务器后台持续运行，哪怕你关掉终端窗口也不受影响。任务转入后台后，屏幕上就不再显示打印信息了。加上这段命令，程序的所有正常输出（如进度条）和报错信息，都会自动写入到 train.log 文件中，方便你随时复盘。\
> **💡 提交后操作：**敲击回车执行后，终端会返回一个进程号（PID）。你可以随时输入 tail -f train.log 来实时滚动查看训练进度，按 Ctrl+C 即可退出日志查看（此时后台训练仍在安全进行）。

**第三步：检查与监视任务运行状态**

任务提交到后台后，不要立刻关闭终端。建议先通过以下几个常用命令，确认程序是否已经顺利跑起来了，并在后续随时监控或管理该任务。

**🔍 核心监视命令与操作说明：**

1. **实时查看训练日志 (`tail -f`)：**
   1. **命令**：`tail -f train.log`
   2. **作用**：这是最直观的监视方式。它会像放电影一样，实时滚动显示程序的输出（如 loss 变化、进度条）。如果代码一开始就有报错（比如缺包、路径写错、显存溢出），也会立刻在这里显示出来。按 `Ctrl+C` 即可退出查看界面（此操作**不会**中断后台训练）。
2. **确认 GPU 是否正常工作 (`nvidia-smi`)**：
   1. **命令**：再次输入 `nvidia-smi`
   2. **作用**：重点核对两件事：一是你刚才指定的 GPU（如 0、2 号卡）的**显存**和**算力利用率**是否已经升上去了；二是底部的进程列表里是否出现了你的 Python 任务。如果显存占满了但利用率长时间是 0%，说明程序可能卡死了，或者正在用 CPU 龟速处理数据，需要检查代码。
3. **查找后台进程号 (`ps` 命令)**：
   1. **命令**：`ps -ef | grep python`
   2. **作用**：如果你忘记了提交任务时系统返回的进程号（PID），或者想看看自己当前挂了几个后台任务，可以用这个命令查找。在输出的结果中，找到你对应的训练命令那一行，**第二列的数字**就是该任务的 PID。
4. **中止/结束任务 (`kill` 命令)**：
   1. **命令**：`kill -9 PID #(PID: 你的进程号)`
   2. **作用**：如果发现参数写错了、代码报错卡死，或者想提前结束训练，**直接关闭终端是没用的**（因为你用了 `nohup`）。必须通过 `kill -9` 加上你的 PID 来强制杀掉进程，这样才能彻底释放被你占用的 GPU 资源，方便自己或他人下次使用。

> **💡 监视避坑指南**：深度学习任务在刚启动的前 5 分钟最容易崩溃（通常是因为显存溢出 OOM 或读取数据报错）。强烈建议提交任务后，先用 `tail -f train.log` 盯一会儿，直到看见模型成功打印出第一个 Epoch 或 Step 的训练指标（如 Loss），确认跑通了，再放心去忙别的事情。

#### **1.2 其他事项**

1. 数据存储规范：登录服务器后，务必在 `/home/data/` 路径下创建以个人姓名/账号命名的专属文件夹，所有个人数据、项目文件、脚本均存储在该文件夹内，严禁在 `/home/` 根路径下直接创建文件夹或存储文件，避免占用公共空间、干扰服务器正常运行。
2. 权限与安全：请勿修改、删除他人文件夹及文件，不得擅自更改服务器系统设置、安装无关软件；退出服务器时请正常关闭运行中的任务，避免后台进程持续占用GPU资源。
3. 备份要求：重要数据请定期备份至本地设备或实验室云存储，服务器不保证数据永久安全，因误操作、系统故障导致的数据丢失，责任由个人承担。

### 二、GPU使用Python脚本示例

在Python、Shell等脚本中调用GPU时，需明确指定GPU设备，避免默认占用所有GPU，常用框架的调用方式如下：

#### 2.1 Python脚本

PyTorch框架，同时使用多个GPU的示例

```python
import torch
# 方法1：指定单个GPU（如编号为0的GPU）
device = torch.device("cuda:0" if torch.cuda.is_available() else "cpu")
model = model.to(device)
data = data.to(device)

# 方法2：指定多个GPU（如编号0、1的GPU），使用DataParallel
if torch.cuda.device_count() > 1:
    model = torch.nn.DataParallel(model, device_ids=[0, 1])
model = model.cuda()
```

> 说明：GPU编号从0开始，可通过后续命令查看服务器GPU编号及状态。

#### 2.2 脚本运行时指定GPU

也可在运行脚本时通过环境变量临时指定GPU，命令如下：

```bash
python your_script.py  
```

### 三、GPU使用常用命令

以下命令用于查看GPU状态、筛选空闲GPU、管理GPU任务，涵盖日常使用核心场景，建议熟练掌握。

#### 3.1 查看GPU整体使用情况

```bash
nvidia-smi
```

输出内容说明：

* GPU：GPU编号（0、1、2...），后续调用需使用该编号。
* Fan：风扇转速（%），反映GPU负载情况。
* Temp：GPU温度，超过85℃需注意，可能影响性能或硬件安全。
* Perf：性能状态，从P0（最高性能）到P12（最低性能）。
* Memory Usage：GPU内存占用情况，剩余内存不足时需更换空闲GPU。
* Processes：当前占用GPU的进程，包含进程ID（PID）、占用GPU编号、内存使用量、运行用户。

#### 3.2 实时监控GPU状态

```bash
watch -n 1 nvidia-smi
```

说明：-n 1 表示每1秒刷新一次显示，按Ctrl+C退出监控。

#### 3.3 筛选空闲GPU

通过命令快速识别无进程占用、内存空闲率高的GPU，适合批量任务调度：

```bash
# 查看空闲GPU编号（无进程占用、内存使用率低于10%）
nvidia-smi --query-gpu=index,memory.used,memory.total --format=csv,noheader,nounits | awk -F ',' '{if($2/$3 < 0.1) print "空闲GPU编号："$1}'
```

补充判断标准：优先选择内存剩余多、温度低、无其他用户占用的GPU。

#### 3.4 其他重要命令

* 查看GPU详细信息（型号、内存、驱动版本）：

`nvidia-smi --query-gpu=all --format=csv,noheader,nounits`

* 查看CUDA版本（适配深度学习框架版本）：

`nvcc -V # 或 nvcc --version`

### 四、GPU使用参考资料

#### 4.1 官方文档

* NVIDIA官方GPU命令手册：<https://docs.nvidia.com/deploy/nvidia-smi/index.html>
* PyTorch GPU使用指南：<https://pytorch.org/docs/stable/notes/cuda.html>

#### 4.2 实用技巧补充

* 调用空闲GPU时，建议在脚本开头添加GPU状态检测逻辑，自动选择空闲设备，避免手动指定错误。
* 若服务器GPU数量较多，可使用工具（如gpustat）简化状态查看，安装命令：`pip install gpustat`，运行：`gpustat`。
* 长时间运行任务时，建议使用`nohup`命令后台运行，避免终端断开导致任务终止，示例：`nohup python your_script.py` &。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://book.ncrnalab.org/teaching/getting-started/run-gpu-jobs-advanced.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.