tensor_parallel

🚀  在 Kaggle 上试用全新的 40B 参数 LLM 演示

只需一行代码，即可在多块 GPU 上运行大型 PyTorch 模型，并有望实现线性加速。

import transformers
import tensor_parallel as tp
tokenizer = transformers.AutoTokenizer.from_pretrained("facebook/opt-13b")
model = transformers.AutoModelForCausalLM.from_pretrained("facebook/opt-13b")  # 使用 opt-125m 进行测试

model = tp.tensor_parallel(model, ["cuda:0", "cuda:1"])  # <- 每块 GPU 只持有模型参数的一半

inputs = tokenizer("A cat sat", return_tensors="pt")["input_ids"].to("cuda:0")
outputs = model.generate(inputs, num_beams=5)
print(tokenizer.decode(outputs[0])) # A cat sat on my lap for a few minutes ...

model(input_ids=inputs, labels=inputs).loss.backward()  # 训练过程与平常无异

安装

最新稳定版（推荐）：

pip install tensor_parallel

开发版：

pip install https://github.com/BlackSamorez/tensor_parallel/archive/main.zip

使用方法

只需将你的 PyTorch 模型包裹在 tp.tensor_parallel 中，即可像往常一样使用。为获得最佳内存效率，请在模型仍位于 CPU 上时调用 tp.tensor_parallel。

以下是一些使用场景：

• examples/training_flan-t5-xl.ipynb - 在文本摘要任务上微调完整的 FLAN-T5 模型
• tensor_parallel int8 LLM - 使用 LLM.8bit + tensor_parallel 对大型语言模型进行适配器微调
• 待定 - 自定义并行策略的定义

tensor_parallel 的高级参数：

• device_ids: List[device] - 指定使用的设备；默认为所有可用的 GPU
• output_device: device - 模型输出将位于该设备上
• tensor_parallel_config: tp.Config - 使用自定义并行策略，详见 slicing_configs.py
• distributed: bool - 如果为 True，则使用 torch.distributed 后端而非多线程（需要 torchrun）
• sharded: bool - 如果为 True，将查找所有未被 Tensor Parallelism 划分的可训练参数，并使用 ZeRO-3 算法 进行划分。
  • 权重将在各 GPU 之间分割，并在每次前向传播前重新组合
  • 简而言之：训练时使用此选项可避免参数重复（默认启用！）
  • sharded_param_names: List[str] - 需要以这种方式划分的参数名称，默认为自动检测

保存模型

若要保存一个可在非 tensor_parallel 环境中使用的模型，应使用 save_tensor_parallel 上下文包装器。

import torch
import transformers
import tensor_parallel as tp

model = tp.tensor_parallel(
    transformers.AutoModelForCausalLM.from_pretrained("facebook/opt-13b"), 
)

# 大量训练...

with tp.save_tensor_parallel(model):
    torch.save(model.state_dict(), "/tmp/")
    # 或者
    model.save_pretrained("/tmp/")

这段代码会将模型保存为未经过分割的状态。其原理是在创建 state_dict 时收集模型各部分的数据。

内存高效的调度

通常情况下，要正常创建和调度一个 tensor_parallel 模型，需要将整个模型加载到内存中。这可能会带来一些麻烦，但其实还有另一种方法。

可以使用辅助函数 convert_state_dict 将基础模型的 state_dict 转换为对应的 tensor_parallel state_dict，然后将其调度并加载到模型中：

import accelerate
import transformers

import tensor_parallel as tp

# 从 MyModel 初始化一个无权重的 tensor_parallel 模型
with accelerate.init_empty_weights():
    model = tp.TensorParallel(
        MyModel(),
        device_ids=[0, 1] # 并准备将其放置在 GPU 0 和 1 上
    )

# 加载 MyModel 的部分 state_dict
state_dict = torch.load("my_model_part_1_of_5.bin")

# 将其转换为 tensor_parallel 的 state_dict
tensor_parallel_state_dict = tp.convert_state_dict(
    state_dict,
    tensor_parallel_config=model.tensor_parallel_config,
    world_size=len(model.devices),
)

# 调度部分 state_dict（由于 meta 不支持 load_state_dict，这里使用 accelerate）
device_map = tp.infer_sharded_device_map(model)
for param_name, param in state_dict.items():
    module_name = param_name
    while len(module_name) > 0 and module_name not in device_map:
        module_name = ".".join(module_name.split(".")[:-1])
    param_device = device_map[module_name]
    accelerate.utils.set_module_tensor_to_device(model, param_name, param_device, value=param)

通过这种方法，每次只需将模型的一部分加载到内存中即可。

常见问题解答

• 问： 我没有多GPU服务器，可以在Google Colab中使用tensor_parallel吗？

• 答： Colab只有一块GPU，因此使用张量并行没有意义。不过，Kaggle为所有通过手机验证的账户免费提供两块T4显卡。

• 问： 什么是张量并行？

• 答： 将每一层的权重分成若干部分，在不同的GPU上分别进行矩阵乘法运算，最后再将结果汇总。更多内容请参阅这里。

• 问： 我应该使用TensorParallel还是DataParallel？

• 答： 对于大型模型使用TensorParallel，对于较小的模型则使用DataParallel。

• 问： 它与FullyShardedDataParallel和ZeRO相比如何？

• 答： 如果能容纳较大的批次，ZeRO更好；而对于小批次，TensorParallel更优。

为什么使用tensor_parallel……

• 与DeepSpeed和FairScale相比：
  • DeepSpeed提供了多种并行化策略，但需要仔细配置。
  • tensor_parallel只需一行代码即可实现一种有效的并行化策略。
  • tensor_parallel可以直接在Jupyter Notebook中运行。
• 与MegatronLM相比：
  • MegatronLM针对特定模型架构提供了非常优秀的张量并行支持。
  • tensor_parallel则适用于任何架构，并且安装更加简单。
• 与parallelformers相比：
  • parallelformers仅支持推理，而tensor_parallel支持训练。
• 与alpa相比：
  • alpa是用于JAX框架下自动分布式训练和推理的强大工具。
  • tensor_parallel则基于PyTorch。
• 与Model.parallelize()相比：
  • 两者都易于使用，都能处理大型模型。
  • 在parallelize中，每次只有一个GPU工作。
  • 而在tensor_parallel中，多个GPU可以并行工作。

简而言之，如果只是在单机上快速原型设计，建议使用tensor_parallel。如果是大规模、耗资巨大的训练任务，则应选择DeepSpeed+Megatron或alpa。

故障排除

如果您遇到NCCL错误或程序随机挂起的情况，可能是代码中存在未被正确显示的错误。 为了调试这些问题，我们建议您通过设置export TENSOR_PARALLEL_USE_NATIVE=1来重启，或者直接在单个设备上运行。

如果您发现了bug或遇到了问题，请将其报告至我们的问题追踪器。 我们将尽最大努力帮助您解决问题，但可能需要一些时间才能处理。请仅在您的问题与tensor_parallel相关时才创建新问题。 例如，如果您需要帮助安装transformers库或优化代码，请尝试在其他地方寻求支持。

代码风格

我们对所有拉取请求均采用black和isort格式化工具。 在提交代码之前，只需运行black . && isort .，即可确保代码符合规范。

---

tensor_parallel 快速上手指南

tensor_parallel 是一个轻量级的 PyTorch 工具，旨在通过一行代码将大型模型拆分到多个 GPU 上进行张量并行（Tensor Parallelism）训练或推理，从而实现近乎线性的加速比。它无需复杂的配置，支持任意模型架构，且兼容标准的 PyTorch 训练流程。

环境准备

• 操作系统: Linux (推荐), macOS, Windows
• Python: 3.7+
• 核心依赖:
  • PyTorch (需安装支持多 GPU 的版本)
  • Transformers (可选，用于加载常见大模型)
• 硬件要求: 至少 2 块 NVIDIA GPU (单卡无法体现张量并行优势，但可运行测试)
• 通信后端: 默认使用多线程，若需高性能分布式训练需确保 NCCL 正常运作。

安装步骤

推荐使用 pip 安装最新稳定版：

pip install tensor_parallel

如需体验最新开发版功能：

pip install https://github.com/BlackSamorez/tensor_parallel/archive/main.zip

提示：国内用户若下载缓慢，可配置清华源或阿里源加速： pip install tensor_parallel -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

1. 最简单的多卡推理/训练

只需将模型包裹在 tp.tensor_parallel 中，指定使用的 GPU 设备列表即可。建议在模型仍在 CPU 上时进行包裹，以获得最佳内存效率。

import transformers
import tensor_parallel as tp

# 1. 加载模型 (此时模型在 CPU 上)
tokenizer = transformers.AutoTokenizer.from_pretrained("facebook/opt-13b")
model = transformers.AutoModelForCausalLM.from_pretrained("facebook/opt-13b")  
# 测试时可替换为小模型: "facebook/opt-125m"

# 2. 应用张量并行 (一行代码)
# 模型权重将被自动拆分到 cuda:0 和 cuda:1 上
model = tp.tensor_parallel(model, ["cuda:0", "cuda:1"])  

# 3. 准备输入 (移至任意一个参与并行的设备，如 cuda:0)
inputs = tokenizer("A cat sat", return_tensors="pt")["input_ids"].to("cuda:0")

# 4. 推理 (生成文本)
outputs = model.generate(inputs, num_beams=5)
print(tokenizer.decode(outputs[0])) 

# 5. 训练 (反向传播与普通用法完全一致)
loss = model(input_ids=inputs, labels=inputs).loss
loss.backward() 

2. 保存模型

若要保存模型以便在非 tensor_parallel 环境下使用（即恢复为完整单模型格式），请使用 save_tensor_parallel 上下文管理器。它会自动收集分散的权重。

import torch
import tensor_parallel as tp

# ... 训练完成后 ...

with tp.save_tensor_parallel(model):
    # 保存为标准 state_dict 或 pretrained 格式
    torch.save(model.state_dict(), "/tmp/model.bin")
    # 或者
    # model.save_pretrained("/tmp/")

3. 高级用法：显存优化 (Sharding)

在训练场景下，为了避免参数重复占用显存，默认启用 sharded=True。这会利用类似 ZeRO-3 的算法，仅在计算前临时重组需要的参数片段。

# 显式开启分片模式（默认已开启，此处仅作演示）
model = tp.tensor_parallel(
    model, 
    ["cuda:0", "cuda:1"], 
    sharded=True 
)

4. 进阶：低显存加载大模型

如果显存不足以一次性加载完整模型，可以先初始化空权重模型，再分块加载权重并转换：

import accelerate
import torch
import tensor_parallel as tp
from my_model import MyModel # 假设这是你的模型类

# 1. 初始化无权重模型
with accelerate.init_empty_weights():
    model = tp.TensorParallel(
        MyModel(),
        device_ids=[0, 1]
    )

# 2. 加载部分权重文件
state_dict = torch.load("my_model_part_1_of_5.bin")

# 3. 将普通 state_dict 转换为 tensor_parallel 格式
tensor_parallel_state_dict = tp.convert_state_dict(
    state_dict,
    tensor_parallel_config=model.tensor_parallel_config,
    world_size=len(model.devices),
)

# 4. 将权重分发到对应设备
device_map = tp.infer_sharded_device_map(model)
for param_name, param in state_dict.items():
    module_name = param_name
    while len(module_name) > 0 and module_name not in device_map:
        module_name = ".".join(module_name.split(".")[:-1])
    param_device = device_map[module_name]
    accelerate.utils.set_module_tensor_to_device(model, param_name, param_device, value=param)