# xmig

**Repository Path**: whisky-ma/xmig

## Basic Information

- **Project Name**: xmig
- **Description**: Build a heterogeneous integrated XPU migration capability to achieve AI computing power decoupling and seamless migration of training tasks, supporting scenarios such as AI training fault recovery, service scheduling, and resource integration.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 6
- **Created**: 2025-09-29
- **Last Updated**: 2026-01-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# <center>xMIG (xPU 迁移技术)</center>
<br>

## 一&nbsp;&nbsp;整体介绍：
![alt png](assets/overview.jpg )
&nbsp;&nbsp;&nbsp;&nbsp;xMig 是一个为大规模语言模型训练/推理设计的轻量级、快速且透明的错误恢复框架，采用即时（Just-In-Time）方式进行错误处理。其核心目标是通过高效的机制减少训练过程中的错误恢复开销，同时保持系统的稳定性和性能。
<br>

### 核心特点
- 透明性与无周期检查点：Mnemosyne 继承了微软即时检查点技术的优势，无需周期性保存检查点，从而降低了训练过程中的性能开销；
- 定制化错误恢复机制：通过优化的恢复流程，最大限度地减少日常训练中的额外开销；
- 支持运行时调整通信组：提供灵活的集合通信CC组调整功能，适应动态训练需求；

### 技术实现
- 设备代理进行故障监控和故障拦截
    xPU 相关的错误会通过API进行钩子捕获，检测到错误后，设备代理停止向上层框架继续传播错误，进入故障恢复状态；

- 故障恢复工作流
    对于可重启恢复的软件/驱动错误，进行原地恢复，重启故障节点并进行日志重放、CCL 重建、DP 参数拉取；对于不可恢复的错误（如硬件故障），使用CRIU保存CPU进程状态，迁移CPU状态到新节点，随后恢复GPU状态恢复时，使用 Flexible CCL 加速集合通信重建；

- 恢复完成后，设备代理正确响应上层框架；
<br>

## 二&nbsp;&nbsp;安装教程：
1. 设置环境变量
```bash
$ export CUDA_HOME=\<cuda-path\>
$ export NCCL_HOME=\<xmig-path\>/GPU/target/nccl-2.27.7-1
$ export PATH=$CUDA_HOME/bin:$PATH
$ export LD_LIBRARY_PATH=$NCCL_HOME/build/lib:$CUDA_HOME/lib64:$LD_LIBRARY_PATH
```

2. 编译 NCCL 和 xMIG
```bash
$ cd ./GPU/
$ make
```

3. 运行测试脚本
```bash
$ cd ./test/
# 指定run.sh脚本使用的GPU设备和数量，默认配置如下：
# CUDA_VISIBLE_DEVICES=0,1,2,3
# torchrun --nproc_per_node=4
$ bash run.sh
```
<br>

## 三&nbsp;&nbsp;使用场景：
&nbsp;&nbsp;&nbsp;&nbsp;适用于需要高效错误恢复的大规模分布式训练任务，尤其是在训练大规模语言模型时，能够显著减少因错误导致的时间和资源浪费:
- 原地恢复：通过集合通信修复，原地就行修复；
- 容器迁移：通过CRIU进行容器迁移，进行容器迁移修复；
<br>

## 四&nbsp;&nbsp;参考链接：
1. [Mnemosyne: Lightweight and Fast Error Recovery for LLM Training in a Just-In-Time Manner](https://zhangmenghao.github.io/papers/APNet2025-Mnemosyne.pdf)
2. [PhoenixOS: Concurrent OS-level GPU Checkpoint and Restore with Validated Speculation](https://arxiv.org/pdf/2405.12079)
3. [Just-In-Time Checkpointing: Low Cost Error Recovery from Deep Learning Training Failures](https://dl.acm.org/doi/pdf/10.1145/3627703.3650085)
4. [Singularity: Planet-Scale, Preemptive and Elastic Scheduling of AI Workloads](https://arxiv.org/pdf/2202.07848)