# PR #7453 完整报告

- 仓库：`PaddlePaddle/FastDeploy`
- 标题：[Iluvatar] fix ci error and update readme
- 合并时间：2026-04-17 20:42
- 原文链接：http://prhub.com.cn/PaddlePaddle/FastDeploy/pull/7453

---

# 执行摘要

- 一句话：修复 Iluvatar 后端 MoE 层接口签名不一致问题并更新安装文档。
- 推荐动作：该 PR 值得快速浏览，重点关注 MoE 层接口对齐的设计决策，了解如何通过添加可选参数来保持向后兼容性；同时可参考文档更新模式，学习如何同步维护中英文技术文档。

# 功能与动机

根据 PR 标题和 AI Code Review 摘要，动机是“修复 Iluvatar CI 报错，更新 README 安装文档，对齐 MoE backend 基类接口”。具体来说，Iluvatar 后端的 `apply_tp` 函数签名缺少 `fc1_latent_proj` 和 `fc2_latent_proj` 参数，与基类 `MoEMethodBase` 不一致，导致 CI 测试失败；同时安装文档存在过时或错误信息，需要同步更新以确保用户能正确部署。

# 实现拆解

1. **修复 MoE 层接口签名**：在 `fastdeploy/model_executor/layers/backends/iluvatar/moe/fuse_moe_cutlass_iluvatar_backend.py` 的 `apply_tp` 函数中，新增 `fc1_latent_proj` 和 `fc2_latent_proj` 两个可选参数，并在函数逻辑中调用它们，以对齐基类接口，避免 CI 报错。
2. **更新中文安装文档**：修改 `docs/zh/get_started/installation/iluvatar_gpu.md`，添加 `--extra-index-url` 参数到 pip 安装命令，将 `git clone` 改为 `--recursive` 以拉取子模块，新增 `pip3 install -r requirements_iluvatar.txt` 步骤，修正 PaddleOCR-VL 示例中的 `device` 参数为 `"iluvatar_gpu"`，并修复笔误（如连续逗号）。
3. **更新英文安装文档**：同步修改 `docs/get_started/installation/iluvatar_gpu.md`，内容与中文文档对应，确保国际化一致性。
4. **更新依赖文件**：在 `requirements_iluvatar.txt` 末尾新增 `paddleocr[doc-parser]==3.3.2` 依赖，以支持文档解析功能。

关键文件：
- `fastdeploy/model_executor/layers/backends/iluvatar/moe/fuse_moe_cutlass_iluvatar_backend.py`（模块 MoE 后端；类别 source；类型 core-logic；符号 apply_tp）: 修复 Iluvatar 后端 MoE 层接口签名不一致的核心文件，确保与基类对齐，避免 CI 失败。
- `docs/zh/get_started/installation/iluvatar_gpu.md`（模块 中文文档；类别 docs；类型 documentation）: 更新中文安装文档，修正安装命令和配置，确保用户能正确部署 Iluvatar 平台。
- `docs/get_started/installation/iluvatar_gpu.md`（模块 英文文档；类别 docs；类型 documentation）: 同步更新英文安装文档，保持与中文文档一致，支持国际化用户。
- `requirements_iluvatar.txt`（模块 依赖配置；类别 config；类型 configuration）: 新增 paddleocr 依赖，支持文档解析功能，完善 Iluvatar 环境配置。

关键符号：apply_tp


## 关键源码片段

### `fastdeploy/model_executor/layers/backends/iluvatar/moe/fuse_moe_cutlass_iluvatar_backend.py`

修复 Iluvatar 后端 MoE 层接口签名不一致的核心文件，确保与基类对齐，避免 CI 失败。

```python
def apply_tp(
    x: paddle.Tensor,
    gate: nn.Layer,
    topk_ids_hookfunc: Callable = None,
    fc1_latent_proj: nn.Layer = None,  # 新增参数：用于 MoE 计算前的投影层
    fc2_latent_proj: nn.Layer = None,  # 新增参数：用于 MoE 计算后的投影层
) -> paddle.Tensor:
    """
    Paddle Cutlass compute Fused MoE.
    """
    gate_out = gate(x)
    gate_out = gate_out.cast("float32")

    if fc1_latent_proj is not None:
        x = fc1_latent_proj(x)  # 在 MoE 计算前应用投影，支持 latent MoE 模型

    # 原有的 MoE 计算逻辑（例如 get_moe_scores、fused_moe_cutlass 等）
    # ...

    if fc2_latent_proj is not None:
        fused_moe_out = fc2_latent_proj(fused_moe_out)  # 在 MoE 计算后应用投影

    return fused_moe_out
```

# 评论区精华

AI Code Review 指出 PR 标题中 Tag 拼写错误（`[Iiluvatar]` 应为 `[Iluvatar]`），并建议在 PR 描述中补充具体修改内容以便追溯。同时，在中文文档中发现连续逗号的笔误，建议修复。维护者 EmmonsCurse 批准了 PR，并指示跳过 Iluvatar 相关检查。讨论焦点集中在代码规范性和文档准确性上，无重大设计争议。

- PR 标题和描述规范性 (style): 维护者未直接回应，但 PR 已合并；建议未来提交时注意规范。
- 中文文档笔误修复 (documentation): PR 中已修正该笔误，确保文档准确性。

# 风险与影响

- 风险：技术风险较低：
- **回归风险**：MoE 层接口变更仅添加可选参数，不影响现有调用，但需确保所有使用该后端的代码已适配新签名；文档更新不涉及核心逻辑。
- **兼容性风险**：新增依赖 `paddleocr[doc-parser]==3.3.2` 可能引入版本冲突，但该依赖为可选组件，影响有限。
- **安全风险**：无。
- 影响：影响范围有限：
- **用户影响**：Iluvatar GPU 用户需按照更新后的文档进行安装和配置，避免因文档错误导致部署失败；MoE 层接口对齐后，确保模型推理功能正常。
- **系统影响**：仅影响 Iluvatar 后端的 MoE 计算和文档部署流程，不涉及其他平台或核心引擎。
- **团队影响**：修复 CI 报错有助于提升开发效率，文档更新减少用户咨询负担。
- 风险标记：接口签名变更 , 依赖更新

# 关联脉络

- PR #7428 [Feature] Support MOE Cutlass backend for latent MOE: 都涉及 MoE Cutlass 后端的接口扩展，7428 为 GPU 平台添加了 fc1_latent_proj 和 fc2_latent_proj 支持，本 PR 在 Iluvatar 平台进行类似对齐。
- PR #7413 [Others] modify flash_mask version: 都涉及依赖文件（requirements_iluvatar.txt）的更新，属于基础设施维护。