[BugFix]fix missing kv shard helper in QKVGateParallelLinear

[blueblueberry123]

Modifications

• Add missing _get_kv_shard_id helper in QKVGateParallelLinear
• Fix kv shard id calculation for kv heads sharding

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[PaddlePaddle-bot]

🤖 Paddle-CI-Agent | pr_review | 2026-06-16 15:23:38

📋 Review 摘要

PR 概述：为 QKVGateParallelLinear 补齐 KV shard helper，修复 TP 下 KV heads 分片计算。
变更范围：fastdeploy/model_executor/layers/linear.py 中 QKVGateParallelLinear 权重加载辅助逻辑。
影响面 Tag：[OP]

问题

级别	文件	概述
🟡 建议	fastdeploy/model_executor/layers/linear.py:1221	缺少覆盖 TP/KV 分片映射的回归测试

📝 PR 规范检查

当前标题缺少官方 Tag，PR 描述缺少 Motivation、Usage or Command、Accuracy Tests 和 Checklist 必填结构。

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

• [BugFix] Fix missing KV shard helper in QKVGateParallelLinear

PR 描述建议（点击展开，可直接复制）

## Motivation
`QKVGateParallelLinear` 在 TP 场景下加载 K/V shard 时缺少 `_get_kv_shard_id` helper，导致 KV heads 分片计算无法复用正确的 shard id 逻辑。

## Modifications
- Add `_get_kv_shard_id` to `QKVGateParallelLinear`.
- Use local TP rank and KV head replication relationship to calculate KV shard id for K/V weight loading.

## Usage or Command
N/A

## Accuracy Tests
N/A

## 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.

总体评价

代码实现与现有 QKVParallelLinear._get_kv_shard_id() 公式保持一致，未发现阻塞性逻辑问题。建议补充 TP/KV shard 回归测试，并按仓库模板补全 PR 标题和描述。

[PaddlePaddle-bot]

🟡 建议 建议给这个 helper 补一个 TP/KV 分片回归测试。

这次修复的行为只在 kv_num_heads < tp_size 且 loaded_shard_id 为 k/v 时通过 qkv_weight_loader() 调用；现有 PR 没有新增测试覆盖这个加载路径，后续很容易只验证初始化而漏掉实际切片。建议在 tests/layers/test_qkvg_parallel_linear.py 增加用例：构造 tp_size=8、kv_num_heads=4，分别断言 rank 0/1 映射到 KV shard 0、rank 2/3 映射到 shard 1，并通过 weight_loader(..., "k"/"v") 验证切片内容或 offset。

[codecov-commenter]

Codecov Report

❌ Patch coverage is 25.00000% with 3 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (develop@4ba6625). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
fastdeploy/model_executor/layers/linear.py	25.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             develop    #8056   +/-   ##
==========================================
  Coverage           ?   67.79%           
==========================================
  Files              ?      475           
  Lines              ?    66672           
  Branches           ?    10287           
==========================================
  Hits               ?    45198           
  Misses             ?    18582           
  Partials           ?     2892           

Flag	Coverage Δ
GPU	77.81% <25.00%> (?)
XPU	6.98% <0.00%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[chang-wenbin]

LGTM