【Models】add fleet model fallback

[xiaoguoguo626807]

Motivation

新增 PaddleFleet 作为模型推理后端（--model-impl paddlefleet），通过将 PaddleFleet
TransformerLayer 中的 core_attention 替换为 FastDeploy Attention 内核，实现在
PaddleFleet 模型结构上复用 FastDeploy 的 KV Cache 和高性能 Attention 计算。

Modifications

• config.py: 新增 paddlefleet 到 ModelImpl 类型定义
• engine/args_utils.py: 支持 --model-impl paddlefleet CLI 参数
• model_executor/models/paddleformers/base_fleet.py: 新增 PaddleFleetModelBase 基类和 FastDeployAttention 替换逻辑
• model_executor/models/paddleformers/__init__.py: 注册 PaddleFleetForCausalLM 模型类
• worker/worker_process.py: 同步新增 paddlefleet 选项

Usage or Command

python -m fastdeploy.entrypoints.openai.api_server \
    --model /path/to/model \
    --model-impl paddlefleet

Accuracy Tests

Checklist

• Add at least a tag in the PR title.
  • Tag list: [[FDConfig],[APIServer],[Engine], [Scheduler], [PD Disaggregation], [Executor], [Graph Optimization], [Speculative Decoding], [RL], [Models], [Quantization], [Loader], [OP], [KVCache], [DataProcessor], [BugFix], [Docs], [CI], [Optimization], [Feature], [Benchmark], [Others], [XPU], [HPU], [GCU], [DCU], [Iluvatar], [Metax]]
  • You can add new tags based on the PR content, but the semantics must be clear.
• Format your code, run pre-commit before commit.
• Add unit tests. Please write the reason in this PR if no unit tests.
• Provide accuracy results.
• If the current PR is submitting to the release branch, make sure the PR has been submitted to the develop branch, then cherry-pick it to the release branch with the [Cherry-Pick] PR tag.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
29 out of 31 committers have signed the CLA.

✅ Deleter-D
✅ EmmonsCurse
✅ xjkmfa
✅ ChowMingSing
✅ cmcamdy
✅ plusNew001
✅ wuyujiji
✅ chang-wenbin
✅ juncaipeng
✅ Jiang-Jia-Jun
✅ iosmers
✅ BingooYang
✅ ApplEOFDiscord
✅ jackyYang6
✅ kevincheng2
✅ zhoutianzi666
✅ zoooo0820
✅ qwes5s5
✅ Dryoung95
✅ zhupengyang
✅ ckl117
✅ liyonghua0910
✅ lizhenyun01
✅ Jiajun-Ji
✅ luukunn
✅ xyxinyang
✅ xiaoguoguo626807
✅ gongshaotian
✅ K11OntheBoat
❌ rain7996
❌ Copilot
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[paddle-bot]

Thanks for your contribution!

[PaddlePaddle-bot]

🤖 Paddle-CI-Agent | pr_review | 2026-05-07 14:30:35

📋 Review 摘要

PR 概述：新增 PaddleFleet 作为模型推理后端（--model-impl paddlefleet），通过替换 TransformerLayer 中的 core_attention 为 FastDeploy Attention 内核，实现 KV Cache 与高性能 Attention 复用。

变更范围：model_executor/models/paddleformers/、config.py、engine/args_utils.py、worker/worker_process.py、requirements.txt

影响面 Tag：[Models] [FDConfig] [Engine]

---

📝 PR 规范检查

标题使用了中文全角括号 【Models】，不符合 D1 规范要求的 ASCII 方括号格式 [Models]；Accuracy Tests 段仅保留了注释占位符，内容为空，但 Checklist 中已勾选"Provide accuracy results"，存在矛盾。

标题建议（可直接复制）：

• [Models] add PaddleFleet model fallback backend

PR 描述建议（可直接复制，必须复刻 checklist §D2 模板的完整结构）：

## Motivation
新增 PaddleFleet 作为模型推理后端（`--model-impl paddlefleet`），通过将 PaddleFleet TransformerLayer 中的 core_attention 替换为 FastDeploy Attention 内核，实现在 PaddleFleet 模型结构上复用 FastDeploy 的 KV Cache 和高性能 Attention 计算。

## Modifications
- `config.py`: 新增 `paddlefleet` 到 `ModelImpl` 类型定义
- `engine/args_utils.py`: 支持 `--model-impl paddlefleet` CLI 参数，更新合法值列表与文档字符串
- `model_executor/models/paddleformers/base_fleet.py`: 新增 `PaddleFleetModelBase` 基类和 `FastDeployAttention` 替换逻辑，实现 `patch_paddlefleet_core_attention` 函数
- `model_executor/models/paddleformers/__init__.py`: 注册 `PaddleFleetForCausalLM` 模型类
- `model_executor/graph_optimization/decorator.py`: 修复 `__call__` 支持位置参数 `*args`
- `model_executor/layers/rotary_embedding.py`: `get_rope_impl` 新增对 `PaddleFleetForCausalLM` 的架构名称解析
- `worker/worker_process.py`: 同步新增 `paddlefleet` 选项

## Usage or Command
```bash
python -m fastdeploy.entrypoints.openai.api_server \
    --model /path/to/model \
    --model-impl paddlefleet
```

## Accuracy Tests
N/A（本 PR 为新增后端框架集成，尚无精度对比数据；后续需补充与原生 FastDeploy 后端的 logits 对齐测试）

## Checklist

- [x] Add at least a tag in the PR title.
  - Tag list: [`[FDConfig]`,`[APIServer]`,`[Engine]`, `[Scheduler]`, `[PD Disaggregation]`, `[Executor]`, `[Graph Optimization]`, `[Speculative Decoding]`, `[RL]`, `[Models]`, `[Quantization]`, `[Loader]`, `[OP]`, `[KVCache]`, `[DataProcessor]`, `[BugFix]`, `[Docs]`, `[CI]`, `[Optimization]`, `[Feature]`, `[Benchmark]`, `[Others]`, `[XPU]`, `[HPU]`, `[GCU]`, `[DCU]`, `[Iluvatar]`, `[Metax]`]
  - You can add new tags based on the PR content, but the semantics must be clear.
- [x] Format your code, run `pre-commit` before commit.
- [ ] Add unit tests. Please write the reason in this PR if no unit tests.
- [ ] Provide accuracy results.
- [x] If the current PR is submitting to the `release` branch, make sure the PR has been submitted to the `develop` branch, then cherry-pick it to the `release` branch with the `[Cherry-Pick]` PR tag.

---

问题

级别	文件	概述
🔴 Bug	base_fleet.py:119	assert 用于运行时校验，-O 优化模式下断言被跳过，forward_meta=None 时静默传递引发后续难以定位的错误
🟡 建议	base_fleet.py:372,395	print() 遗留在 forward 热路径，每次推理均产生控制台输出，严重影响吞吐性能
❓ 疑问	requirements.txt	将 paddleformers 锁定到特定 nightly 离线 whl（cu126 only），不适合长期维护
❓ 疑问	base_fleet.py	layer_number 注释说明"PaddleFleet 从 1 开始"，但直接赋值 fd_layer_id = layer_number（注释又说"0-indexed"），存在 off-by-one 风险

---

🔴 base_fleet.py:119 — assert 用于运行时校验

assert 在 Python -O 优化模式下会被完全跳过，forward_meta is None 时 None 会静默流入 fd_attention.forward()，产生难以定位的 AttributeError。参照同目录 base.py:285 的模式改为显式 raise ValueError。

🟡 base_fleet.py:372,395 — print() 遗留热路径

两处 print() 遗留在 @paddle.no_grad() def forward() 热路径中，每次推理都会触发字符串格式化与控制台 I/O（line 395 还会序列化整个 Tensor）。请删除或替换为 logger.debug()：

# line 372: 删除或改为
logger.debug("forward_meta: %s", forward_meta)
# line 395: 删除或改为
logger.debug("position_ids: %s", position_ids)

❓ requirements.txt — nightly wheel 锁定问题

paddleformers[paddlefleet] @https://paddle-whl.bj.bcebos.com/nightly/cu126/paddleformers/paddleformers-1.1.0.post20260430-py3-none-any.whl 存在以下问题：

1. 硬编码 URL，链接失效后无法安装
2. 仅覆盖 CUDA 12.6，其他 CUDA 版本用户无法使用
3. nightly 版本不具备版本保证，不适合生产环境

建议改为正式 release 版本，或在 PR 描述中说明此为临时措施并提出后续计划。

❓ layer_number off-by-one 疑问

注释 # Get layer_number (PaddleFleet starts from 1) 表明 layer_number 从 1 起，但随后 fd_layer_id = layer_number 的注释是 # Get FastDeploy layer ID (0-indexed)，两者矛盾。若 FastDeploy KV Cache 按 0-indexed 分配（layer 0 ~ N-1），则 fd_layer_id 应为 layer_number - 1，否则 layer 0 的 KV Cache 永远不会被使用，最后一层可能越界。请确认 Attention(fd_config, layer_id=fd_layer_id) 中 layer_id 的预期取值范围。

---

总体评价

整体方案清晰，通过 patch_paddlefleet_core_attention 将 FastDeploy Attention 无侵入地嵌入 PaddleFleet 模型结构，思路合理。但有一处 P0 问题（assert 替代 raise ValueError）必须修复，另有两处 print() 调试输出遗留在热路径中影响性能，以及 requirements.txt 的 nightly wheel 锁定和 layer_number 索引的疑问需作者确认后方可合入。

[PaddlePaddle-bot]

🔴 Bug assert 被用于运行时校验，Python -O 优化模式下断言会被完全跳过，导致 forward_meta is None 时 None 静默流入 fd_attention.forward()，引发难以定位的 AttributeError。

参照同目录 base.py:285 的做法，改为显式 raise ValueError：

if forward_meta is None:
    raise ValueError("forward_meta must be provided")

[PaddlePaddle-bot]

🤖 Paddle-CI-Agent | ci_status_monitor | 2026-05-07 14:53:06

CI报告基于以下代码生成（30分钟更新一次）:

• PR commit: bc5cc29
• Merge base: 978484c (branch: develop)
• 查看完整 Diff
• CI 详情

---

1 任务总览

无 Required 检查配置，当前无失败任务；1 个可选任务运行中，CI 尚未全部完成。

总执行（rerun次数）	总任务	✅ 通过	❌ 失败	⏳ 运行中	⏸️ 等待中	跳过
3(0)	3	1	0	1	0	1

2 任务状态汇总

2.1 Required任务 : 0/0 通过

当前未配置必选任务（Branch Protection Rules 未设置 Required Checks），无阻塞合并的任务。

2.2 可选任务 — 1/3 通过

可选任务不阻塞合并，失败仅供参考。

状态	任务	耗时	日志	重跑
⏳	Trigger Jenkins for PR	-	Job	-
✅	Remove skip-ci labels on new commits	5s	-	-
⏭️	cherry-pick（已跳过）	-	-	-

---

3 失败详情（仅 required）

无 required 失败任务。