执行摘要

• 一句话：修复 Gemma4 位置张量原地修改导致的潜在 bug
• 推荐动作：该 PR 本质是防御性修复，review 中建议直接无条件切换的意见值得采纳。建议合并后尽快将 SGLANG_GEMMA_OUT_OF_PLACE_POSITION_MUTATION 默认值改为 True，并在一段观察期后完全移除该环境变量。

功能与动机

positions 是一个可能被多个调用者共享的小张量（例如来自 ForwardBatch），原地 += 1 会直接修改同一块内存，当该张量被复用或在 CUDA graph 中捕获时，可能产生难以追踪的 side effect。PR 希望通过环境变量逐步验证 out-of-place 方案，再决定是否默认启用。

实现拆解

1. 声明环境变量：在 python/sglang/srt/environ.py 的 Envs 类中新增 SGLANG_GEMMA_OUT_OF_PLACE_POSITION_MUTATION = EnvBool(False)，默认关闭。
2. 导入环境变量：在 python/sglang/srt/models/gemma4_mm.py 中增加 from sglang.srt.environ import envs。
3. 修改 forward 逻辑：将原来 positions += 1 替换为一个条件分支：当环境变量开启时使用 positions = positions + 1（非原地），否则保留原地语义，保持向后兼容。

关键文件：

• python/sglang/srt/models/gemma4_mm.py（模块 模型桥接；类别 source；类型 data-contract）: 核心改动位置：在 forward 中增加条件分支，根据环境变量选择原地或非原地加法。
• python/sglang/srt/environ.py（模块 配置层；类别 source；类型 configuration）: 新增环境变量声明，是控制开关的配置源。

关键符号：Gemma4ForConditionalGeneration.forward

关键源码片段

python/sglang/srt/models/gemma4_mm.py

核心改动位置：在 forward 中增加条件分支，根据环境变量选择原地或非原地加法。

# python/sglang/srt/models/gemma4_mm.py
from sglang.srt.environ import envs
​
# ... 在 forward 方法中：
if envs.SGLANG_GEMMA_OUT_OF_PLACE_POSITION_MUTATION.get():
    # 非原地加法：生成新张量，不修改输入的 positions
    positions = positions + 1
else:
    # 原地加法：保持旧行为，但可能产生 side effect
    positions += 1

评论区精华

review 中 gemini-code-assist[bot] 指出，原地修改输入张量存在共享 tensor 副作用风险，且 positions 是 1D 小张量，out-of-place 开销可忽略。建议直接无条件改为非原地方式，并去掉该环境变量，以降低配置链路复杂度。PR 作者未就此发表回应。

• 是否应无条件使用 out-of-place 而非环境变量 (design): PR 作者未回应，当前实现保持环境变量开关，默认原地行为。

风险与影响

• 风险：当前实现默认关闭新行为，不影响已有用户，风险极低。未来若启用 out-of-place 并移除环境变量，需确认所有调用路径（包括 pipeline parallel、tensor parallel、CUDA graph）均不受影响。由于没有引入新测试，回归覆盖不足。
• 影响：影响范围限定于 Gemma4ForConditionalGeneration.forward 中的 positions 操作。默认行为不变，仅当显式设置环境变量时才切换到非原地方式。对系统整体无影响，团队需要决定是否逐步推广到无条件启用。
• 风险标记：缺少测试覆盖, review建议未采纳

关联脉络

• PR #26809 Add the KV-canary install API and forward-path wiring: KV-canary 在 forward 路径中会注入 canary 逻辑，与 positions 共享张量相关，本 PR 的改动可能与之交互。
• PR #26814 Add rids/bootstrap-room int-hash plumbing for deterministic per-request identification: 也修改了 forward_batch_info.py，涉及 positions 等张量的传递方式，存在潜在影响。