[feat] add Liger-Kernel doc

index.rst

@@ -290,6 +290,13 @@
          <div class="card-footer"><a href="https://gitcode.com/Ascend/triton-ascend">官方链接</a><span class="split">|</span><a href="sources/_generated/sources/triton-ascend/installation_guide.html">安装指南</a><span class="split">|</span><a href="sources/_generated/sources/triton-ascend/quick_start.html">快速上手</a></div>
       </div>
 
+      <!-- Liger-Kernel -->
+      <div class="project-card">
+         <div class="card-top"><div class="card-icon" style="background-image: url('_static/images/Liger-Kernel.png')"></div><h3 class="card-title">Liger-Kernel</h3></div>
+         <p class="card-desc">面向 LLM 训练的高效 Triton 融合算子库，v0.8.0 起支持昇腾 NPU。</p>
+         <div class="card-footer"><a href="https://github.com/linkedin/Liger-Kernel">官方链接</a><span class="split">|</span><a href="sources/liger-kernel/install.html">安装指南</a><span class="split">|</span><a href="sources/liger-kernel/quick_start.html">快速上手</a></div>
+      </div>
+
    </div>
 
    <h2 class="scene-header">🎨 多模态应用、评测与工具</h2>
@@ -416,6 +423,7 @@
    :caption: ⚙️ 算子开发与编程
 
    sources/triton-ascend/index.rst
+   sources/liger-kernel/index.rst
 
 .. toctree::
    :maxdepth: 1

sources/liger-kernel/index.rst

@@ -0,0 +1,8 @@
+Liger-Kernel
+============
+
+.. toctree::
+   :maxdepth: 2
+
+   install.rst
+   quick_start.rst

sources/liger-kernel/install.rst

@@ -0,0 +1,54 @@
+安装指南
+==============
+
+本教程面向在昇腾 NPU 上使用 `Liger-Kernel <https://github.com/linkedin/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，且无报错。

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 官方文档 <https://linkedin.github.io/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 <https://github.com/hiyouga/LLaMA-Factory>`_：训练参数中设置 ``--use_liger_kernel true``
+- `VeOmni <https://github.com/ByteDance-Seed/VeOmni>`_：模型 Patch 中启用 Liger-Kernel
+- `verl <https://github.com/volcengine/verl>`_：配置 ``model.use_liger=true``