[WIP] feat: add functional MiniMax-M2.5 baseline

[QwertyJack]

MiniMax-M2.5 在 xLLM 上的 CANN 8.5 基线进展

一、当前结论

本 PR 现在以 CANN 8.5 / torch-npu 2.7.1 上可复现、可启动、可服务的 MiniMax-M2.5 基线为主，而不再只是早期 bring-up 过程记录。

当前已经验证的基线是：

• 模型：MiniMax-M2.5
• 运行权重：/models/MiniMax-M2.5-bf16
• 并行拓扑：dp=1, ep=1, attn_tp=16, moe_tp=16
• 运行开关：
  • XLLM_MINIMAX_NATIVE_DECODE_ATTN=1
  • XLLM_MINIMAX_NATIVE_DECODE_MOE=1
  • XLLM_MINIMAX_EP_MOE_REFERENCE=0
  • --enable_graph=true
  • --enable_chunked_prefill=true
  • --enable_prefix_cache=true
• ACL graph warmup：prefill 1024 tokens，decode bucket 预热 1/2/4/8/16

在这套配置下，服务已经能够稳定启动、完成 ACL graph warmup，并正常对外提供 http://127.0.0.1:18994/v1 的 OpenAI-compatible 接口。

二、本 PR 已完成的核心工作

1. MiniMax 专属执行路径

• 保持 MiniMax 适配与共享 Qwen3 路径隔离，避免对已有模型产生副作用。
• 完成 MiniMax 专属模型注册、NPU decoder/loader 接入，以及 native MiniMax 模型路径。
• 实现 MiniMax-native attention：
  • per-layer Q/K RMSNorm
  • rotary_dim=64 只作用于真实 rotary slice
  • decode 阶段走 MiniMax-native paged-attention / graph-safe 路径
• 实现 MiniMax-native router 语义：
  • sigmoid(router_logits)
  • e_score_correction_bias 仅用于 expert choice
  • 从 pre-bias routing score gather/renorm expert 权重
• 实现 MiniMax-native decode MoE 路径，并保留 correctness-first fallback 作为对照。
• 接入 reasoning parser，使 --reasoning_parser auto 能识别 <think>...</think>。

2. CANN 8.5 / torch-npu 2.7.1 基线补齐

• 加入 bf16 友好的 streaming safetensor 加载路径，避免 bf16 checkpoint 在加载期保留全部 shard mmap。
• 提供离线 fp8 -> bf16 转换工具：tools/dequant_minimax_fp8.py。
• 修正 run/mm.sh：
  • 默认优先使用 freshly built 的 build/xllm/core/server/xllm
  • 使用 repo-root 的绝对日志路径，避免误写到旧目录
• 明确新容器里的一个重要现象：
  早期“fresh build 启动即 crash”并不是坏二进制，而是后台 workers 必须从持久 shell 启动；否则测试 harness 可能在日志落盘前回收后台进程，造成假崩溃信号。

3. 基线验证结果

在最新 CANN 8.5 容器中，使用 fresh build server binary + bf16 checkpoint + tp=16 基线，已经验证：

• 16 个 rank 全部成功启动并完成 HCCL 初始化
• bf16 权重能够按 shard 正常流式加载
• KV cache 初始化成功
• ACL graph warmup 成功完成
• decode bucket 1/2/4/8/16 都被预捕获
• API server 在 18994 正常启动
• 多次 smoke request 能正常返回，不会触发重启/崩溃

最近一次实测日志（logs/persist_test/node_0.log）中的单请求指标：

• ttft ~= 5.2-5.9s
• avg tpot ~= 18.0-18.5ms
• generation speed ~= 54.7-55.9 tok/s

这说明当前 PR 已经具备一个可复现、可测量、可继续优化的 MiniMax CANN 8.5 基线。

三、仍然存在的已知问题

1. 输出仍保留 reasoning trace

当前 API 路径已经稳定，但对于 reasoning model，请求返回中仍可能包含原始 <think> 内容，短 token budget 下也容易先耗尽在 thinking phase，出现 finish_reason=length。

这不是当前基线的启动/算子正确性阻塞问题，但仍需要在 response path 上继续清理。

2. dp=2, ep=2 不是当前基线

当前 CANN 8.5 的稳定基线是 pure TP16。

dp=2, ep=2 的 grouped EP MoE 路径在新软件栈上仍需要重新 debug。之前旧容器里的 grouped-path 修复结论不能直接沿用到当前 CANN 8.5 / torch-npu 2.7.1 环境。

3. 直接 fp8 运行路径仍待重新确认

当前推荐运行方式仍是离线转换后的 bf16 checkpoint。

fp8 原始 checkpoint 在新栈上的直接运行路径还需要单独 re-validate，避免把 loader / dequant / runtime path 的问题与当前已验证的 bf16 基线混在一起。

四、下一步计划

下一阶段工作围绕这条新基线展开：

1. 清理 reasoning 输出链路，避免最终 API 输出携带原始 thinking 文本。
2. 重新调通并验证 dp=2, ep=2 grouped EP MoE 路径。
3. 在当前 bf16 tp=16 稳定基线上继续做 decode 性能优化。
4. 单独回归 fp8 直接运行路径，确认其在新软件栈上的可用性。

五、PR 定位

因此，这个 PR 当前的定位是：

• 已完成 MiniMax-M2.5 在 xLLM 上的 CANN 8.5 可运行基线
• 已具备 可复现启动、可服务、可测性能 的状态
• 后续工作重点转入：
  • correctness 收尾
  • dp/ep 路径重新收敛
  • 基于当前基线做性能优化

[gemini-code-assist]

Code Review

这个 PR 引入了 MiniMax-M2.5 模型的功能基线，包含了大量的代码添加和修改，以支持该模型在 xLLM 上的适配。整体来看，这次改动非常全面，从构建系统、环境设置到核心的分布式运行时、模型层实现都做了相应的调整。特别是针对 NPU 环境下的多卡稳定性和正确性进行了诸多修复和优化，例如改进了进程组的创建方式、修复了 ParallelArgs 拷贝导致的崩溃、以及对 ACL graph 捕获逻辑的调整等，这些都体现了对细节的深入思考。

我主要关注了代码的可维护性和安全性，并提出了几点建议：

1. 在 CMakeLists.txt 和 env.py 中，避免硬编码 Ascend 驱动路径，建议使用环境变量以提高可移植性。
2. 在新增的 minimax_compare_modules.py 工具中，torch.load 的使用存在安全风险，建议开启 weights_only=True 选项。

这些修改将有助于提升代码的健壮性和安全性。总体而言，这是一次高质量且内容丰富的提交。

[gemini-code-assist]

在这里硬编码了 Ascend 驱动的路径 (/usr/local/Ascend/driver/...)，这会降低构建系统的可移植性和可维护性。建议引入一个新的环境变量（例如 ASCEND_DRIVER_PATH），并在这里使用该变量，这与其他路径（如 NPU_TOOLKIT_HOME）的处理方式保持一致。

[gemini-code-assist]

在 LD_LIBRARY_PATH 中添加了硬编码的 Ascend 驱动路径。这使得环境设置变得脆弱，并依赖于特定的安装布局。更健壮的做法是定义一个环境变量（如 ASCEND_DRIVER_PATH）来构造这些路径，这与 NPU_TOOLKIT_HOME 等其他环境变量的使用方式也更一致。在 141-142 行的 LIBRARY_PATH 中也存在同样的问题。

[gemini-code-assist]

torch.load 在 weights_only=False 的情况下使用存在安全风险，因为它会执行任意代码。考虑到这个工具可能会处理来自不同来源的文件，这是一个潜在的安全漏洞。强烈建议将 weights_only 设置为 True 以降低此风险。如果文件包含的不仅仅是权重，请考虑使用更安全的格式（如 safetensors）来保存和加载所有相关文件。

Suggested change

	obj = torch.load(str(path), map_location="cpu", weights_only=False)
	obj = torch.load(str(path), map_location="cpu", weights_only=True)