diff --git a/_static/images/Liger-Kernel.png b/_static/images/Liger-Kernel.png new file mode 100644 index 00000000..fe69d004 Binary files /dev/null and b/_static/images/Liger-Kernel.png differ diff --git a/index.rst b/index.rst index 614d208e..eeba478e 100644 --- a/index.rst +++ b/index.rst @@ -290,6 +290,13 @@
官方链接|安装指南|快速上手
+ +
+

Liger-Kernel

+

面向 LLM 训练的高效 Triton 融合算子库，v0.8.0 起支持昇腾 NPU。

+
官方链接|安装指南|快速上手
+
+

🎨 多模态应用、评测与工具

@@ -416,6 +423,7 @@ :caption: ⚙️ 算子开发与编程 sources/triton-ascend/index.rst + sources/liger-kernel/index.rst .. toctree:: :maxdepth: 1 diff --git a/sources/liger-kernel/index.rst b/sources/liger-kernel/index.rst new file mode 100644 index 00000000..4132bdf8 --- /dev/null +++ b/sources/liger-kernel/index.rst @@ -0,0 +1,8 @@ +Liger-Kernel +============ + +.. toctree:: + :maxdepth: 2 + + install.rst + quick_start.rst diff --git a/sources/liger-kernel/install.rst b/sources/liger-kernel/install.rst new file mode 100644 index 00000000..bb3d69e4 --- /dev/null +++ b/sources/liger-kernel/install.rst @@ -0,0 +1,54 @@ +安装指南 +============== + +本教程面向在昇腾 NPU 上使用 `Liger-Kernel `_ 的开发者，帮助完成 NPU 环境下的安装与验证。 + +Liger-Kernel 从 **v0.8.0** 起正式支持昇腾 NPU 后端，通过 Triton-Ascend 提供 RMSNorm、RoPE、SwiGLU、CrossEntropy 等融合算子，用于加速 LLM 训练并降低显存占用。 + +昇腾环境安装 +--------------- + +请根据已有昇腾产品型号及 CPU 架构等，按照 :doc:`快速安装昇腾环境指引 <../ascend/quick_install>` 完成 CANN、驱动与固件的安装。 + +.. warning:: + + 安装 CANN 时请同时安装 ops 算子包。torch_npu 与 CANN 版本需匹配，详见 :doc:`PyTorch 安装指引 <../pytorch/install>`。 + + +安装依赖 +--------------- + +安装 Liger-Kernel +------------------- + +从源码安装： + +.. code-block:: shell + + git clone https://github.com/linkedin/Liger-Kernel.git + cd Liger-Kernel + pip install -e ".[dev]" + +源码安装时，``setup.py`` 会自动检测昇腾 NPU 并安装对应依赖（``torch==2.6.0``、``torch_npu==2.6.0``、``triton-ascend==3.2.0``）。 + + +验证安装 +--------------- + +使用以下脚本验证环境是否就绪： + +.. code-block:: python + + import torch + import torch_npu + from liger_kernel.transformers import LigerRMSNorm + + assert torch.npu.is_available(), "NPU 不可用" + print("NPU device:", torch.npu.current_device()) + + norm = LigerRMSNorm(128).npu() + x = torch.randn(2, 16, 128, dtype=torch.bfloat16, device="npu") + y = norm(x) + print("LigerRMSNorm output shape:", y.shape) + +正确回显应包含 NPU 设备号与张量 shape，且无报错。 diff --git a/sources/liger-kernel/quick_start.rst b/sources/liger-kernel/quick_start.rst new file mode 100644 index 00000000..4c99da68 --- /dev/null +++ b/sources/liger-kernel/quick_start.rst @@ -0,0 +1,80 @@ +快速上手 +============== + +.. note:: + + 阅读本篇前，请确保已按照 :doc:`安装指南 <./install>` 完成昇腾环境与 Liger-Kernel 的安装。 + +Liger-Kernel 提供面向 LLM 训练的高效 Triton 融合算子。在昇腾 NPU 上，只需一行 Patch 代码即可将 Hugging Face 模型中的关键算子替换为 Liger-Kernel 优化实现，从而提升训练吞吐并降低显存占用。 + + +方式一：模型 Patch API +------------------------------------------------ + +如需更细粒度控制启用的算子，可在加载模型前调用对应 Patch 函数： + +.. code-block:: python + + import torch + import torch_npu + from transformers import AutoModelForCausalLM + from liger_kernel.transformers import apply_liger_kernel_to_qwen3 + + # 在实例化模型前调用，自动替换 RoPE、RMSNorm、SwiGLU、CrossEntropy 等算子 + apply_liger_kernel_to_qwen3( + rope=True, + rms_norm=True, + swiglu=True, + cross_entropy=True, + fused_linear_cross_entropy=False, + ) + + model = AutoModelForCausalLM.from_pretrained( + "/home/model/Qwen3-0.6B", + dtype=torch.bfloat16, + device_map="npu", + ) + +# 打印模型结构，检查是否替换成功 +print(model) + +其他常用模型可使用对应的 Patch API，例如 ``apply_liger_kernel_to_llama``、``apply_liger_kernel_to_qwen3``、``apply_liger_kernel_to_mistral`` 等，完整列表见 `Liger-Kernel 官方文档 `_。 + +.. hint:: + + 使用 ``device_map="npu"`` 需要安装 ``accelerate``（``pip install accelerate``）。也可在加载模型后手动迁移：``model = model.to("npu")``。 + +方式二：单独使用算子模块 +------------------------------------------------ + +也可以将单个 Liger 算子嵌入自定义模型： + +.. code-block:: python + + import torch + import torch_npu + from liger_kernel.transformers import LigerRMSNorm, LigerFusedLinearCrossEntropyLoss + + hidden_size = 4096 + vocab_size = 32000 + + norm = LigerRMSNorm(hidden_size).npu() + loss_fn = LigerFusedLinearCrossEntropyLoss() + + x = torch.randn(4, 128, hidden_size, dtype=torch.bfloat16, device="npu", requires_grad=True) + target = torch.randint(vocab_size, (4, 128), device="npu") + weight = torch.randn(vocab_size, hidden_size, dtype=torch.bfloat16, device="npu", requires_grad=True) + + hidden = norm(x) + # LigerFusedLinearCrossEntropyLoss 的输入需为二维张量 (batch*seq, hidden_size) + loss = loss_fn(weight, hidden.reshape(-1, hidden_size), target.reshape(-1)) + loss.backward() + +训练框架集成 +------------------------------------------------ + +Liger-Kernel 已集成到多个训练框架，在 NPU 上可通过框架配置启用： + +- `LLaMA-Factory `_：训练参数中设置 ``--use_liger_kernel true`` +- `VeOmni `_：模型 Patch 中启用 Liger-Kernel +- `verl `_：配置 ``model.use_liger=true``