diff --git a/基于AI Agent开发范式的国产GPU大模型推理算子库优化/baselines/Fused MoE Baseline 入门：快速跑通最小闭环教程.md b/基于AI Agent开发范式的国产GPU大模型推理算子库优化/baselines/Fused MoE Baseline 入门：快速跑通最小闭环教程.md
new file mode 100644
index 0000000..a26e6bd
--- /dev/null
+++ b/基于AI Agent开发范式的国产GPU大模型推理算子库优化/baselines/Fused MoE Baseline 入门：快速跑通最小闭环教程.md	
@@ -0,0 +1,666 @@
+# Fused MoE Baseline 入门：快速跑通最小闭环教程
+
+## 一、教程定位
+
+本教程是参赛训练课程的 baseline 入门模块，主要帮助用户快速跑通 Fused MoE 的最小可运行流程。
+
+完成本教程后，用户应能够完成源码编译、正确性测试和 benchmark 测试，并记录一份 baseline 性能结果，为后续算子优化提供对比基准。
+
+## 二、学习目标
+
+完成本模块后，你将能够：
+
+1.  理解 Fused MoE 推理算子及 int8 量化在大模型推理加速中的核心作用与优化意义；
+    
+2.  完成环境配置和 Fused MoE baseline 源码准备；
+    
+3.  跑通 Fused MoE 的最小闭环示例；
+    
+4.  理解基于 Trition 与 MXMACA C++ 写Fused MOE 算子；
+    
+5.  完成数值正确性测试，即验证 reference 计算、pybind 计算、Triton 计算这三种方式计算结果是否数值完全一致。
+    
+    *   reference：基于 PyTorch 架构在 CPU 上运行的**数值基准**实现；
+        
+    *   pybind：将 MXMACA C++ 算子编译并封装为 Python 可调用的动态库，**实现复杂且迁移成本高**；
+        
+    *   Triton：基于 Python 编写的高效 GPU Kernel，可利用 Agent 自动调优，**开发效率高、易于迁移**；
+        
+    *   要求 pybind 和 Triton 结果均与 reference 一致，鼓励参赛选手持续调优 Triton ，使其性能逼近甚至超越 pybind 性能。
+        
+6.  输出 benchmark 结果对比表。
+    
+
+## 三、适用对象
+
+**本模块适合以下人员：**
+
+*   参与基于 AI Agent 开发范式的国产 GPU 大模型推理算子库优化比赛的学生；
+    
+*   对 GPU 推理算子性能优化感兴趣的开发者；
+    
+*   需要了解 Fused MoE 推理性能的研究人员。
+    
+
+**学习本模块前，需掌握以下基础知识：**
+
+*   Python、C++ 编程基础；
+    
+*   PyTorch 基础；
+    
+*   GPU 推理基本概念。
+    
+
+## 四、前置准备
+
+开始实战前，请确认你已经完成以下准备：
+
+**环境准备：**
+
+*   已进入赛事专属镜像环境：
+    
+    1.  获取算力券：[https://developer.metax-tech.com/activities/6](https://developer.metax-tech.com/activities/6)
+        
+    2.  兑换算力和登录平台：[https://ai.gitee.com/](https://ai.gitee.com/)
+        
+        进入 【费用中心】— 【算力券】，点击右上角 【兑换】。
+        
+        ![image.png](https://origin.picgo.net/2026/06/04/image104df0b48e859950a.png)
+        
+    3.  租用算力：点击顶部导航栏【算力市场】，选择【沐曦】，租用算力，建议优先选16G /32G 显存，如下图：
+        
+        ![image.png](https://origin.picgo.net/2026/06/04/image2e973eb9c33b02661.png)
+        
+    4.  创建实例：如图安装专属镜像
+        
+        ![image.png](https://origin.picgo.net/2026/06/04/image37ae95373fa3e2cc5.png)
+        
+    5.  项目创作：进入我的算力容器，刚创建的实例默认开机状态，点击工具-lab开始项目创作，不用时记得关机！
+        
+
+![image.png](https://origin.picgo.net/2026/06/04/image4db7649869ff4db84.png)
+
+小提示：也可以用本地 AI coding 工具 ssh 连接云服务器（能实现和AI对话即可）
+
+**工具准备：**
+
+*   已准备 Agent 工具；
+    
+*   已配置 Token / API Key；
+    
+*   已确认 Agent 可以正常调用模型。
+    
+
+**代码准备：**
+
+*   已获取 Fused MoE Baseline 源码。
+    
+
+## 五、知识预备
+
+### 混合专家模型 MoE 
+
+参考链接：[https://huggingface.co/blog/zh/moe](https://huggingface.co/blog/zh/moe)
+
+混合专家模型（Mixed Expert Models，简称 MoE）是一种稀疏激活的模型结构。与稠密模型不同，MoE 在前向计算时只激活部分参数，从而在相近的计算预算下，获得更大的模型容量和更快的收敛速度。这也是当前大模型扩展参数规模的主流路径之一。
+
+MoE 是一种基于 Transformer 架构的模型，由两个关键部分组成：
+
+*   **稀疏 MoE 层：**这些层代替了传统 Transformer 模型中的前馈网络 (FFN) 层。MoE 层包含若干“专家”(例如 8 个)，每个专家本身是一个独立的神经网络。在实际应用中，这些专家通常是前馈网络 (FFN)，但它们也可以是更复杂的网络结构，甚至可以是 MoE 层本身，从而形成层级式的 MoE 结构。
+    
+*   **门控网络或路由:** 这个部分用于决定哪些令牌 (token) 被发送到哪个专家。例如，在下图中，“More”这个令牌可能被发送到第二个专家，而“Parameters”这个令牌被发送到第一个专家。有时，一个令牌甚至可以被发送到多个专家。令牌的路由方式是 MoE 使用中的一个关键点，因为路由器由学习的参数组成，并且与网络的其他部分一同进行预训练。
+    
+
+![image.png](https://origin.picgo.net/2026/06/04/image552fe46f30dca5fb8.png)
+
+MoE 的主要优势体现在预训练和训练阶段的算力效率上，但在推理阶段带来了新的**挑战**：
+
+*   **显存占用高：**尽管每个 Token 只激活部分专家，但所有专家的参数仍需常驻显存。例如 Mixtral 8×7B 的实际参数量接近 47B，而非 8×7B 的简单叠加，因为除 FFN 外的大多数参数在各专家间是共享的。
+    
+*   **计算不均衡：**不同专家接收的 Token 数量可能不同，导致计算负载不均，容易形成局部瓶颈。
+    
+*   **访存压力大：**专家权重、Token 路由、Permute / Unpermute 都会带来额外的显存读写，而不仅仅是计算量的减少。
+    
+
+因此，在推理阶段对 MoE 算子进行系统级优化​具有非常重要的意义，在不改变模型行为和数值精度的前提下，通过更合理的调度、融合与访存优化，缓解稀疏性带来的碎片化和内存压力。
+
+### INT8 模型量化：
+
+参考链接：[https://www.cnblogs.com/chentiao/p/18315901](https://www.cnblogs.com/chentiao/p/18315901)
+
+INT8 量化是一种用于减少模型大小和计算复杂度的方法，特别是在深度学习模型中。它通过将浮点数（通常是 FP32）转换为 8 位整数 (INT 8)，从而减少内存使用和提高计算效率。
+
+## 六、项目实践1-算力平台 baseline 源码部署
+
+**项目目标：**在算力平台上拉取 fused\_moe 的 baseline 源码，快速跑通最小闭环，完成 pybind 接口对接、正确性验证和 benchmark 测试，并记录一份 baseline 性能结果，为后续算子优化提供对比基准。
+
+### 步骤 1：检查运行环境
+
+**目标：**确认当前环境满足本模块运行要求，包括编译器、MXMACA 工具链及 Python 依赖库。
+
+**操作：**检查 Python、编译工具、MXMACA 编译器及关键 Python 包（numpy、torch、triton）是否存在。
+
+**命令示例：**
+
+```apl
+python --version # 检查Python版本，Python ≥ 3.8
+g++ --version # 确认 C++ 编译器存在
+which mxcc # 确认 MACA 编译器存在
+
+
+# 检查 Python 依赖
+python - << 'EOF'
+import sys
+deps = ["numpy", "torch", "triton"]
+missing = []
+for d in deps:
+    try:
+        __import__(d)
+    except ImportError:
+        missing.append(d)
+if missing:
+    print(f"[ERROR] Missing packages: {missing}")
+    sys.exit(1)
+else:
+    print("[OK] numpy, torch, triton are installed.")
+EOF
+```
+
+**预期结果：**
+
+*   Python 3.12.11
+    
+*   g++ (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0
+    
+*   /opt/maca/mxgpu\_llvm/bin/mxcc
+    
+*   \[OK\] numpy, torch, triton are installed.
+    
+
+**常见问题：**
+
+| 报错 | 原因 | 解决办法 |
+| --- | --- | --- |
+| `g++：command not found` | 未安装 C++ 编译工具 | `apt update && apt install -y build-essential` |
+| `Python 3.6.x/ Python 3.7.x` | Python 版本过低 | `conda install python=3.12` （推荐3.10+) |
+| `ModuleNotFoundError: numpy` | 当前 Python 缺少依赖 | `pip install numpy torch triton` |
+
+### 步骤 2：进入项目目录
+
+**目标：**进入本模块所需的源码目录。
+
+**操作：**切换到指定项目路径。
+
+**命令示例：**
+
+```apl
+cd /root/Project/fused_moe # 这里需要替换成自己的项目路径
+```
+
+**预期结果：**
+
+终端提示符路径显示为 fused\_moe 项目路径：
+
+*   (base) root@0a5a9d0c0f06:~/Project/fused\_moe#
+    
+
+### 步骤 3：pybind 编译
+
+**目标：**将用 C++ 编写的 fused\_moe 算子编译为 Python 可调用的 pybind 模块。
+
+**操作：**运行 `fused_moe/scripts/build_fused_moe_i8_tn_pybind.sh` 脚本
+
+**命令示例：**
+
+```apl
+bash scripts/build_fused_moe_i8_tn_pybind.sh
+```
+
+切换 Python 环境命令示例：
+
+```apl
+PYTHON_BIN=/path/to/python bash scripts/build_fused_moe_i8_tn_pybind.sh
+```
+
+**预期结果：**
+
+编译成功无报错，终端显示：
+
+*   \[SUCCESS\] /root/Project/fused\_moe/standalone/fused\_moe\_i8\_tn/build/fused\_moe\_i8\_tn\_ pybind.so
+    
+    且成功生成 `fused_moe/standalone/fused_moe_i8_tn/build/fused_moe_i8_tn_pybind.cpython-310-x86_64-linux-gnu.so` 文件
+    
+    **常见问题：**
+    
+    | 报错 | 原因 | 解决办法 |
+    | --- | --- | --- |
+    | `Python.h: No such file or directory` | Python 头文件路径未找到 | 确认 `PYTHON_BIN` 路径正确，脚本自动探测 `sysconfig.get_path('include')` |
+    | `libpython3.x.so: cannot find` | 链接时找不到 Python 库 | 1、执行 `find $CONDA_PREFIX -name "libpython3*.so*"`查找绝对路径<br>2、将该路径赋值给 `LIBPYTHON_PATH` |
+    | `recompile with -fPIC` | 编译未开启位置无关代码 | 确保 `mxcc`/ `g++`编译参数中有 `-fPIC` |
+    | `permission denied` | 无脚本执行权限 | `chmod +x scripts/*.sh` |
+    | `undefined reference to Py_...` | Python 版本不匹配 | 确认编译脚本中`PYTHON_BIN`路径与当前运行的 Python 环境完全一致 |
+    
+    ### 步骤 4：正确性测试
+    
+    **目标：**验证 reference 计算、pybind 计算、Triton 计算这三种方式计算结果的数值是否完全一致。
+    
+    **操作：**运行 `fused_moe/scripts/run_fused_moe_i8_tn_pybind_test.sh` 脚本
+    
+    **命令示例：**
+    
+    ```apl
+    bash scripts/run_fused_moe_i8_tn_pybind_test.sh --backend all # 运行全部计算方式
+    
+    # --backend：选择计算方式
+    # 只测 pybind：
+    bash scripts/run_fused_moe_i8_tn_pybind_test.sh --backend pybind
+    # 只测 triton：
+    bash scripts/run_fused_moe_i8_tn_pybind_test.sh --backend triton
+    # 只测 reference:
+    bash scripts/run_fused_moe_i8_tn_pybind_test.sh --backend reference
+    ```
+    
+    **预期结果：**
+    
+    编译成功无报错，输出示例如下：
+    
+    > pybind:fused\_moe\_i8\_tn\_topk1 passed: rows=256, cols=128, sample C\[0\]=0.69531, C\[last\]=-0.44531
+    
+    > pybind:fused\_moe\_i8\_tn\_topk2 passed: rows=512, cols=128, sample C\[0\]=-0.57813, C\[last\]=-0.49805
+    
+    > pybind:fused\_moe\_i8\_tn\_topk3 passed: rows=384, cols=128, sample C\[0\]=-1.08594, C\[last\]=-0.33594
+    
+    > reference:fused\_moe\_i8\_tn\_topk1 passed: rows=256, cols=128, sample C\[0\]=0.6934, C\[last\]=-0.4451
+    
+    > reference:fused\_moe\_i8\_tn\_topk2 passed: rows=512, cols=128, sample C\[0\]=-0.5768, C\[last\]=-0.4975
+    
+    > reference:fused\_moe\_i8\_tn\_topk3 passed: rows=384, cols=128, sample C\[0\]=-1.0875, C\[last\]=-0.3362
+    
+    > triton:fused\_moe\_i8\_tn\_topk1 passed: rows=256, cols=128, sample C\[0\]=0.69337, C\[last\]=-0.44513
+    
+    > triton:fused\_moe\_i8\_tn\_topk2 passed: rows=512, cols=128, sample C\[0\]=-0.57678, C\[last\]=-0.49749
+    
+    > triton:fused\_moe\_i8\_tn\_topk3 passed: rows=384, cols=128, sample C\[0\]=-1.08748, C\[last\]=-0.33618
+    
+    **结果解释：**
+    
+    *   “pybind/reference/Triton”：三种计算方式；
+        
+    *   “fused\_moe\_i8\_tn\_topk1/2/3 passed”：测试算子通过数值校验，数值误差在允许范围内且无明显异常，否则会报错 FAILED；
+        
+    *   ”rows=... , cols=...“：输出 Tensor 的行和列的大小；
+        
+    *   ”sample C\[0\]=... , C\[last\]=...“：首尾采样值，用于辅助定位数值偏差，不作为精度判定依据。
+        
+    
+    **常见问题：**
+    
+    | 报错 | 原因 | 解决办法 |
+    | --- | --- | --- |
+    | `ModuleNotFoundError: fused_moe_i8_tn_pybind` | pybind 模块未编译或未加入 `PYTHONPATH` | 回到步骤 3，确认 `.so`已生成；执行 `export PYTHONPATH=/root/Project/fused_moe:$PYTHONPATH` |
+    | `FAILED: max abs diff too large` | 数值误差超过阈值 | 检查 scale 是否应用位置错误；确认 TopK 索引与权重是否一致 |
+    | `FAILED: shape mismatch` | 输出张量形状不一致 | 检查 Token Permute / Unpermute 逻辑；确认 expert 维度对齐 |
+    | `FAILED: NaN or Inf detected` | 溢出或未初始化内存 | 检查 INT8 乘加是否溢出；确认 GEMM 输出是否反量化 |
+    | 终端长时间无输出 | Kernel 死锁或 Launch 失败 | 减小测试 shape；检查是否触发 MACA 硬件限制 |
+    
+    ### 步骤5：性能测试
+    
+    **目标：**输出 benchmark 结果对比表
+    
+    **操作：**运行 `fused_moe/scripts/run_fused_moe_i8_tn_benchmark.sh` 脚本
+    
+    **命令示例：**
+    
+    ```apl
+    bash scripts/run_fused_moe_i8_tn_benchmark.sh --backend all --warmup 5 --iters 20 
+    # --backend：选择计算方式
+    # --warmup：设置预热次数
+    # --iters：设置迭代次数
+    ```
+    
+    **预期结果：**
+    
+    编译成功无报错，输出示例如下：
+    
+    > pybind:fused\_moe\_i8\_tn\_topk1 benchmark: avg\_ms=0.308978, TOPS=0.027149, warmup=5, iters=20
+    
+    > pybind:fused\_moe\_i8\_tn\_topk2 benchmark: avg\_ms=0.304500, TOPS=0.055098, warmup=5, iters=20
+    
+    > pybind:fused\_moe\_i8\_tn\_topk3 benchmark: avg\_ms=0.297775, TOPS=0.042256, warmup=5, iters=20
+    
+    > reference:fused\_moe\_i8\_tn\_topk1 benchmark: avg\_ms=1685.43, TOPS=0.000005, warmup=5, iters=20
+    
+    > reference:fused\_moe\_i8\_tn\_topk2 benchmark: avg\_ms=3384.52, TOPS=0.000005, warmup=5, iters=20
+    
+    > reference:fused\_moe\_i8\_tn\_topk3 benchmark: avg\_ms=2532.14, TOPS=0.000005, warmup=5, iters=20
+    
+    > triton:fused\_moe\_i8\_tn\_topk1 benchmark: avg\_ms=19.013421, TOPS=0.000441, warmup=5, iters=20
+    
+    > triton:fused\_moe\_i8\_tn\_topk2 benchmark: avg\_ms=16.745914, TOPS=0.001002, warmup=5, iters=20
+    
+    > triton:fused\_moe\_i8\_tn\_topk3 benchmark: avg\_ms=19.630328, TOPS=0.000641, warmup=5, iters=20
+    
+    **结果解释：**
+    
+    *   “pybind/reference/Triton”：三种计算方式；
+        
+    *   “fused\_moe\_i8\_tn\_topk1/2/3”：分别对应选择前 1 / 2 / 3 个专家场景下的 MoE 算子；
+        
+    *   “avg\_ms”：平均算子执行耗时（毫秒），这里不计算预热时间，只计算正式迭代的时间；
+        
+    *   “TOPS”：Tera Operations Per Second，本次 MoE 算子的总运算量 / 实际耗时；
+        
+    *   “warmup=5, iters=20”：预热轮数和正式迭代数。
+        
+
+**常见错误：**
+
+| 报错 | 原因 | 解决办法 |
+| --- | --- | --- |
+| `ModuleNotFoundError: fused_moe_i8_tn_pybind` | pybind 模块未编译或未加入 `PYTHONPATH` | 回到步骤 3，确认 `.so`已生成；执行 `export PYTHONPATH=/root/Project/fused_moe:$PYTHONPATH` |
+| 终端长时间无输出 | Kernel 死锁或 MACA 驱动异常 | 减小测试 shape；重启容器或设备 |
+| avg\_ms 异常抖动（±50%） | 其他进程占用 GPU | 关闭其他占用显存的进程，单机单任务运行 |
+
+## 七、项目实践2-Kernel Swift 智能算子迁移系统自动调优
+
+系统链接：[https://deeplink.org.cn/kernelswift/task](https://deeplink.org.cn/kernelswift/task)
+
+**项目目标：**基于 KernelSwift 智能算子迁移系统，对 fused\_moe 算子进行在线自动调优。通过输入标准 PyTorch 代码，一键生成适配沐曦硬件的高性能实现；并利用算子广场复用与可视化管理功能，高效完成算子优化与全流程追踪。
+
+### 步骤1：复用算子广场的 fused\_moe 算子进行二次优化
+
+**目标：**通过提交算子广场的 fused\_moe 算子代码发起自动优化流程，实现二次优化
+
+**操作：**
+
+1.  进入算子广场：点击左侧导航栏 【算子广场】，进入算子列表页
+    
+    搜索 fused\_moe 算子，复制 `input_code.py` 代码，也可直接复制以下代码：
+    
+    ```python
+    import torch
+    import torch.nn as nn
+    import torch.nn.functional as F
+    
+    
+    class Model(nn.Module):
+        """
+        Reference PyTorch MoE forward (no fused kernels).
+        Expects inputs:
+            hidden_states: (M, in_size)
+            w1: (E, hidden_size, in_size) where hidden_size = 2 * up_dim
+            w2: (E, out_size, up_dim)
+            topk_weights: (M, top_k)
+            topk_idx: (M, top_k)
+            top_k: int
+            renormalize: bool
+        """
+    
+        def __init__(self):
+            super().__init__()
+    
+        def forward(
+            self,
+            hidden_states: torch.Tensor,
+            w1: torch.Tensor,
+            w2: torch.Tensor,
+            topk_weights: torch.Tensor,
+            topk_idx: torch.Tensor,
+            top_k: int,
+            renormalize: bool = True,
+        ) -> torch.Tensor:
+            if renormalize:
+                topk_weights = topk_weights / topk_weights.sum(dim=-1, keepdim=True)
+    
+            seq_len = hidden_states.size(0)
+            out_size = w2.size(1)
+            output = hidden_states.new_zeros(seq_len, out_size)
+            num_experts = w1.size(0)
+    
+            # Accumulate expert contributions
+            for eid in range(num_experts):
+                token_idx, k_idx = torch.where(topk_idx == eid)
+                if token_idx.numel() == 0:
+                    continue
+                gate_proj, up_proj = w1[eid].chunk(2, dim=0)
+                down_proj = w2[eid]
+                tmp = F.linear(hidden_states[token_idx], gate_proj)
+                tmp = F.silu(tmp) * F.linear(hidden_states[token_idx], up_proj)
+                tmp = F.linear(tmp, down_proj)
+                tmp = tmp * topk_weights[token_idx, k_idx, None]
+                output.index_add_(0, token_idx, tmp.to(output.dtype))
+            return output
+    
+    
+    # Hyperparameters
+    seq_len = 128
+    in_size = 128
+    hidden_size = 256  # 2 * up_dim
+    out_size = 128
+    num_experts = 32
+    top_k = 4
+    
+    dtype = torch.float16
+    
+    def get_inputs():
+        hidden_states = (torch.rand(seq_len, in_size, dtype=dtype) - 0.5) / 2
+        w1 = (torch.rand(num_experts, hidden_size, in_size, dtype=dtype) - 0.5) / 2
+        w2 = (torch.rand(num_experts, out_size, hidden_size//2, dtype=dtype) - 0.5) / 2
+        routing_logits = (torch.rand(seq_len, num_experts, dtype=dtype) - 0.5) / 2
+        routing_weights = torch.softmax(routing_logits, dim=-1, dtype=torch.float32)
+        topk_weights, topk_idx = torch.topk(routing_weights, top_k, dim=-1)
+        return [hidden_states, w1, w2, topk_weights, topk_idx, top_k, True]
+    
+    def get_init_inputs():
+        return []
+    ```
+    
+2.  进入新建任务页：点击左侧导航栏【新建任务】 ，进入算子提交页面。
+    
+3.  编写算子代码：在 `model.py` 编辑器中输入刚刚复制的 fused\_moe 算子代码。
+    
+    如果想自行编写算子代码，需严格遵循标准格式规范：输入代码必须包含 `class Model` 定义算子实现，`get_init_inputs` 和 `get_inputs` 定义测试用例，确保优化过程可验证算子正确性。
+    
+4.  配置优化参数
+    
+    *   指定任务名称：支持字母、下划线、数字组合，示例：fused\_moe\_01
+        
+    *   选择适配硬件：算子需要适配的目标硬件厂商及型号，建议：沐曦
+        
+    *   最大演化轮次：优化算法迭代次数，取值范围40-400，建议默认40，复杂算法可提高至100+
+        
+5.  提交优化任务：点击右下角 \[优化\] 按钮，系统将提交任务并进入 \[生成中\] 状态
+    
+
+![image.png](https://origin.picgo.net/2026/06/04/image659a3f15b96be22c1.png)
+
+完成上述步骤将看到如下界面：
+
+![image.png](https://origin.picgo.net/2026/06/04/image75c4ccf75e90cf428.png)
+
+### 步骤2：任务查看与结果管理
+
+**目标：**在新建优化任务后可追踪任务进度，获取优化结果
+
+**操作：**
+
+1.  查看任务列表：点击左侧【任务查看】，可看到所有提交的优化任务
+    
+    *   任务状态：排队中、环境初始化、算子预编译、精度验证、性能调优、已完成、失败
+        
+    *   任务信息：任务名称、进度、创建时间、适配硬件
+        
+    *   操作按钮：查看详情、删除任务
+        
+    
+    ![image.png](https://origin.picgo.net/2026/06/04/image75c4ccf75e90cf428.png)
+    
+2.  追踪任务进度：当前任务状态为【运行中】时，点击任务列表中的【查看详情】按钮，追踪任务进度：
+    
+    *   左侧：原始算子代码（输入的 `input_code.py`）
+        
+    *   右侧：任务进度条，包含以下阶段：
+        
+        1.  环境初始化：准备目标硬件编译环境
+            
+        2.  算子预编译：验证算子代码是可正常编译
+            
+        3.  精度验证：验证优化后算子输出与原始算子误差的可接受范围
+            
+        4.  性能调优：按设定的演化轮次迭代优化算子性能
+            
+    
+    *   顶部：任务名称、创建/更新时间、适配硬件、当前轮次进度
+        
+
+![image.png](https://origin.picgo.net/2026/06/04/image9e9b23d9b25ddfe25.png)
+
+3.  获取优化结果：当前任务状态为【已完成】时，可在详情页查看优化结果：
+    
+    *   优化后算子代码支持一键复制
+        
+    *   算子加速比（基准耗时 / 优化后耗时）、性能数据（如延迟、吞吐量）
+        
+    *   可点击【Diff 对比】查看优化前后代码差异，理解性能提升逻辑
+        
+    
+    ![image.png](https://origin.picgo.net/2026/06/04/image1083021a27904294b1.png)
+    
+4.  任务异常处理
+    
+    *   任务失败：查看错误日志，常见原因包括代码不符合规范、测试用例错误、硬件适配问题，修改后重新提交任务；
+        
+    *   排队时间长：可调整提交时间，或联系平台管理员确认资源状态。
+        
+
+---
+
+## 八、Agent使用说明
+
+在本模块中，Agent可以帮助你完成以下任务：
+
+1.  **环境检查**
+    
+    ```plaintext
+    我正在算力平台部署 fused_moe_baseline 源码。
+    需要的环境信息如下：
+    - Python 3.12
+    - g++ 13.3.0
+    - mxcc 已安装
+    - numpy / torch / triton 已安装
+    
+    请帮我确认：
+    1. 当前环境是否满足编译与运行要求？
+    2. 是否有潜在的不兼容风险（如 Python 与 libpython 版本）？
+    ```
+    
+2.  **运行测试**
+    
+    ```plaintext
+    请帮我运行 scripts/run_fused_moe_i8_tn_pybind_test.sh 脚本 
+    ```
+    
+3.  **分析结果**
+    
+    ```plaintext
+    这是性能测试结果：
+    pybind:    avg_ms=0.30,  TOPS=0.027
+    triton:    avg_ms=19.01, TOPS=0.0004
+    reference: avg_ms=1685,  TOPS=0.000005
+    
+    请分析：
+    1. 为什么 pybind 比 Triton 快这么多？
+    2. TOPS 指标是否可信？
+    3. 当前结果是否已经具备提交价值？
+    ```
+    
+4.  **报错检查**
+    
+    ```plaintext
+    编译 pybind 时出现以下错误：
+    /usr/bin/ld: cannot find -lpython3.10
+    
+    已知：
+    - 使用的是 Conda Python 3.10
+    - mxcc 编译正常
+    
+    请一步一步告诉我：
+    1. 错误原因是什么？
+    2. 如何用 find 命令定位 libpython3.10.so？
+    3. 如何在 build_fused_moe_i8_tn_pybind.sh 中正确指定路径？
+    ```
+    
+5.  **代码理解**
+    
+    ```plaintext
+    请帮我梳理释 benchmark_fused_moe_i8_tn.py 代码整体框架
+    ```
+    
+6.  **KernelSwift 系统搜索算子**
+    
+
+```plaintext
+请帮我在算子广场检索 fused_moe 算子
+```
+
+## 九、常见问题与注意事项
+
+### 算力平台 basline 源码部署项目：
+
+1.  环境准备与依赖问题
+    
+    *   确保算力平台已正确安装 Python 和 C++、MACA 编译器及相关运行时库，避免因环境缺失导致编译失败；
+        
+    *   镜像环境使用 Conda Python​ 作为默认运行环境，避免系统 Python 与 Conda Python 混用，防止 `Python.h`或 `libpython`路径错误。
+        
+2.  pybind 编译与链接
+    
+    *   若`Python.h not found`，请检查脚本中`PYTHON_INCLUDE`是否指向当前 Python 的 `include`目录；
+        
+    *   若`libpython not found`，请直接指定 Conda 下的`**libpython3.x.so**`绝对路径，避免链接系统静态库；
+        
+    *   编译 `pybind`模块时，务必开启 `-fPIC`，否则会出现 `recompile with -fPIC`错误。
+        
+3.  性能测试建议
+    
+    *   benchmark 应在关闭其他占用 GPU 的任务​后执行，避免干扰性能数据；
+        
+    *   多次运行取平均值，避免单次抖动影响结果；
+        
+    *   性能对比应基于相同随机种子、相同 shape、相同 TopK、相同 batch size​的条件下进行，降低误差。
+        
+
+### Kernel Swift 智能算子迁移系统自动调优项目：
+
+1.  代码规范问题
+    
+    输入代码需符合以下标准格式：
+    
+    *   `class Model`，表示待优化的算子实现；
+        
+    *   `def get_init_inputs`，表示 module init 的输入测试样例；
+        
+    *   `def get_inputs`，表示 module forward 的输入测试样例。
+        
+2.  性能优化建议
+    
+    *   对于复杂算子，可适当提高最大演化轮次（如 100-200），获得更高加速比；
+        
+    *   优先选择算子广场中已有优化案例的算子类型，降低适配失败概率。
+        
+3.  硬件适配问题
+    
+    *   提交任务前确认目标硬件支持的算子类型；
+        
+    *   优化失败时，可尝试更换适配硬件，或调整算子实现逻辑。
+        
+
+## 九、下一步学习建议
+
+完成本模块后，建议继续学习以下内容：
+
+1.  **研读 fused\_moe源码：**理解代码的底层逻辑，可尝试修改 `build_fused_moe_i8_tn_pybind.sh`中的编译参数，观察其对 `avg_ms` 的影响；
+    
+2.  **算子优化基础：**了解如何分析 Kernel 性能瓶颈；
+    
+3.  **性能对比分析：**将 baseline 结果与优化后的结果进行对比分析，明确后续优化方向。
\ No newline at end of file