feat(nvidia): add reusable GGUF Route B support for Qwen3.5

[xindongliu594]

Summary

• 在 csrc/layers/quantization/gguf.* 中增加可复用的 GGUF Route B 权重加载和线性计算支持。
• 将 GGUF 量化权重接入 BaseLinear、Linear、融合线性层以及 Qwen3.5 / Qwen3-Next 模型实现。
• 通过 InfiniCore 的 linear_gguf 算子原生支持 Q8_0、Q4_K、Q5_K 和 Q6_K GGUF block。
• 增加当前 Qwen3.5 集成所需的 FP8 量化路径。
• 保留并整理 scripts/gguf_mapping.py、scripts/gguf_to_infinilm.py 和 scripts/gguf_transforms.py 三个可复用的 GGUF 映射、转换和变换工具。
• 增加 test/scripts/test_gguf_routeb.py，覆盖权重重排、BF16 转换、量化配置和 packed checkpoint 校验。
• 针对当前 Mamba cache 不支持 prefix caching 的限制，增加 Qwen3.5 benchmark 条件处理。
• 在 GGUF_ROUTE_B_QWEN38.md 中记录 Route B 的设计、转换方式、验证结果和当前限制。
• 删除 23 个一次性诊断和研究脚本，移除机器相关路径，并将新增代码中的注释、日志和错误信息统一整理为英文。
• 减少 GGUF 运行时重复日志，同时保留首次 packed forward 和 value-head permutation 等关键诊断信息。

Motivation

InfiniLM 此前无法直接执行目标 Qwen3.8-27B 模型使用的原生 GGUF 量化权重。

本 PR 增加可复用的 GGUF Route B 路径，而不是为单个模型实现完整的运行前反量化流程。受支持的 GGUF 线性层权重在 checkpoint 中继续保持原生 block bytes，并在执行时由 GPU 算子直接解析。当前不受原生算子支持的 IQ 格式 tensor，以及 embedding/lm-head 路径，会在权重打包阶段显式转换为 BF16，不存在静默的运行时 fallback。

本 PR 将 GGUF 适配拆分为公共量化层、模型权重映射层和转换工具层，使相关能力可以继续复用于其他 GGUF 模型，而不局限于当前 Qwen3.5 / Qwen3-Next 模型。

所需的 InfiniCore 算子通过独立 PR 提交：InfiniCore #1545。

默认情况下，本 PR 不会启用或修改已有的非 GGUF 执行路径。

Type of Change

• feat — new feature / new model
• fix — bug fix
• perf — performance improvement (no behavioral change)
• refactor — code restructuring without behavior change
• test — adding or fixing tests only
• docs — documentation only
• build / ci — build system or CI configuration
• chore — tooling, formatting, or other non-code changes
• Breaking change

Test Results of Involved Models on Supported Platforms (Please attach screenshots)

Platform	Model	Test	Result
NVIDIA RTX 5090 / CUDA 13.0 / SM120	Qwen3.8-27B-GGUF-native-v2	examples/test_infer.py	通过；最终提交生成 8 个 token
NVIDIA RTX 5090 / CUDA 13.0 / SM120	Qwen3.8-27B-GGUF-native-v2	examples/bench.py	通过；prefill 和 decode 均完成
NVIDIA RTX 5090 / CUDA 13.0 / SM120	Qwen3.8-27B-GGUF-native-v2	test/bench/test_benchmark.py	使用一个固定的本地 MMLU-format smoke sample 完成执行链路
NVIDIA RTX 5090 / CUDA 13.0 / SM120	Qwen3.8-27B-GGUF-native-v2	inference server + scripts/test_perf.py	通过；64/64 个流式请求成功
NVIDIA RTX 5090 / CUDA 13.0 / SM120	_infinilm	fresh xmake build -y _infinilm	通过；独立 worktree 从零构建成功
CPU / NumPy	GGUF Route B utilities	test/scripts/test_gguf_routeb.py	通过；5/5
CPU	Qwen3.8-27B GGUF	scripts/gguf_to_infinilm.py --dry-run	通过；947 个映射条目

Single request

在当前 Qwen3.5 Mamba-cache 实现要求下，关闭 prefix caching 并启用 paged attention，examples/test_infer.py 在最终提交 c643e7af 上运行成功。

Model shards: 6 loaded
Generated tokens: 8
Total time: 12413.03 ms
Exit code: 0
GGUF configuration summary logs: 1
GGUF activation-rule summary logs: 1
Repeated layout-match info logs: 0

首个原生 GGUF block 前向为：

M=63, N=2048, K=5120, ggml_type=8

这表明真实 prefill 已进入 GGUF Route B。

Offline performance entry point

最终提交 c643e7af 的测试结果：

Batch size: 1
Input length: 64
Output length: 8
Prefill TTFT: 10663.48 ms
Prefill throughput: 6.0 tokens/s
Decode average ITL: 191.36 ms
Decode throughput: 5.23 tokens/s
Total time: 12004.19 ms
Exit code: 0

这是一个没有 benchmark warmup 的小规模功能验证 case，不作为最终后端性能对比结果。

Sanity entry point

Samples: 1
Input tokens: 122
New tokens: 5
Total latency: 11.59 seconds
Exit code: 0

验证服务器无法连接 Hugging Face，底层错误为 [Errno 101] Network is unreachable。因此使用一个固定的本地 MMLU-format smoke sample，验证数据加载、模型执行、答案解析、统计和资源销毁的完整链路。

该测试得到的 1/1 结果不作为正式 MMLU 准确率声明。如需正式准确率结果，仍需在能够访问 Hugging Face 或已经缓存正式 MMLU 数据集的环境中重新运行。

Service

使用只绑定回环地址、最大输出长度为 8 token 的临时服务运行 scripts/test_perf.py。

Concurrency: 20
Total requests: 64
Successful requests: 64
Failed requests: 0
Total time: 125.13 seconds
Request rate: 0.51 requests/s
Average latency: 37.55 seconds
Average TTFT: 14.52 seconds

全部服务端请求均返回 HTTP 200。临时服务只配置了 64 个 KV-cache block，因此部分请求被调度器暂时延后，但随后均正常完成。

64/64 请求成功汇总后，客户端的 httpcore2 在事件循环退出阶段输出了异步生成器清理告警，但没有影响服务端响应、成功请求数量或最终退出状态。

Benchmark / Performance Impact

本 PR 主要增加新的功能和可复用 GGUF 支持，不声明最终性能提升。

最终提交在一张 RTX 5090 上的初始离线性能基线为：

Batch size: 1
Input length: 64
Output length: 8
Prefill TTFT: 10663.48 ms
Prefill throughput: 6.0 tokens/s
Decode average ITL: 191.36 ms
Decode throughput: 5.23 tokens/s

以上结果使用短输出、有限 KV-cache 容量且没有 benchmark warmup。由于 InfiniLM 此前没有对应的 GGUF Route B 执行路径，因此不存在可直接比较的旧 GGUF 基线。

针对 dense backend、其他量化 backend 或 llama.cpp 的受控性能比较，以及 prefill kernel、decode GEMV、权重加载和调度优化，留待后续工作完成。

Notes for Reviewers

• 本 PR 依赖 InfiniCore #1545。
• 当前原生支持的 GGUF block 类型为 Q8_0、Q4_K、Q5_K 和 Q6_K。
• IQ4_XS、IQ4_NL tensor 以及当前 embedding/lm-head 路径会在打包阶段显式转换为 BF16。
• 当前版本不支持 GGUF tensor parallelism；检测到相关配置时会显式失败。
• 由于当前 Mamba cache 不支持 prefix caching，Qwen3.5/Qwen3.5-MoE 路径会禁用该功能。
• 严格跨后端比较目前达到 27/32 个 prompt 完全匹配、920/1024 个 token 匹配。本 PR 不将 llama.cpp 的 bitwise 一致或全部 token 一致作为功能正确性的必要条件。
• 真实 GGUF converter dry-run 检测到 64 层、947 个映射条目，其中 packed/dense 为 491/456，预计输出总大小为 23.264 GiB。
• 新增轻量单元测试覆盖 value-head 重排、v_tail 保持、BF16 位模式、量化规则和 packed checkpoint 校验，结果为 5/5 通过。
• 已删除 23 个一次性诊断和研究脚本，仅保留生产代码、通用转换工具、测试和技术文档。
• 新增生产代码中的注释、日志和错误信息已经统一整理为英文。
• 建议重点审查 GGUF metadata/row-byte 校验、blob ownership、fused-shard dispatch、Qwen3.5 QKV 布局、activation V-head permutation，以及 Python/C++ shape 边界。

CI / ChatOps

本地已经完成以下检查：

scripts/format.py --ref upstream/main --check   PASS
git diff --check                               PASS
Python compileall                              PASS
GGUF Route B unit tests                        5/5 PASS
Fresh _infinilm build                          PASS
Single request test                            PASS
Offline performance test                       PASS
Sanity execution chain                         PASS
Service test                                   PASS
Converter dry-run                              PASS

独立 worktree 中的 _infinilm 全新构建从 0% 到 100% 成功完成，用时 365.203 秒。由于验证服务器无法通过 GitHub 443 端口重新下载 submodule，构建时使用了主工作区中相同提交版本的 json 和 spdlog submodule 内容，没有复用已有的 InfiniLM 编译产物。

最终日志优化提交完成后，再次执行增量构建并成功完成，用时 97.089 秒。

GitHub Actions 尚未声明为通过。需要从 Actions 页面针对分支 feat/gguf-routeb-qwen38 启动 CI workflow，或者由维护者在本 PR 中执行 /retest 或 /test。

---

Checklist

Title, Branch, and Commits

• PR title follows Conventional Commits.
• Branch name follows <type>/xxx-yyyy-zzzz.
• Each commit message follows Conventional Commits.
• Every commit is meaningful, well-formed, and independently reviewable.
• No stray merge commits from main.
• No fixup! / squash! / wip commits remain.
• N/A — No legacy issue-formatted PR, branch, or commit is reused.

Scope and Design

• Changes are limited to GGUF support, Qwen3.5 integration, reusable conversion tools, tests, and documentation.
• No dead code, debug output, or unowned experimental follow-up remains.
• Formatting changes were produced by the repository formatter and are limited to files already changed by this branch.
• Public API changes are intentional and documented.

General Code Hygiene (applies to all languages)

• The final manual self-explanatory-code review has been completed.
• Modified files pass the repository format and whitespace checks.
• No trailing whitespace was reported by git diff --check.
• All identifiers in comments and errors follow the required Markdown convention.
• All comments and error messages are in English.
• All comments and error messages have been manually checked for sentence style.

C++ Specific (if C++ files changed)

• All C++ changes have received a final manual Google-style review.
• All error and warning messages satisfy the LLVM wording requirements.
• Constructor initializer order has been manually checked.
• The complete change has been manually audited for ownership and pointer-safety requirements.
• Changed files are formatted by scripts/format.py.
• No changes/reference to csrc/models/llama_legacy/.

Python Specific (if Python files changed)

• Changed Python files pass the repository Ruff/format checks.
• All comments are complete English sentences.
• All new docstrings have received a final PEP 257 review.
• Changed files are formatted by scripts/format.py.
• No changes/reference to python/infinilm/auto_config.py.

Testing

• A reviewer with access to the official MMLU dataset still needs to be tagged if a formal accuracy run is required.
• Passed single request test (examples/test_infer.py).
• Passed offline performance test (examples/bench.py).
• Passed the sanity execution chain (test/bench/test_benchmark.py) using the explicitly documented local smoke sample.
• Passed service test (inference_server.py + scripts/test_perf.py).
• Passed GGUF Route B unit tests (test/scripts/test_gguf_routeb.py).

Build, CI, and Tooling

• A fresh-directory build completed successfully on the affected NVIDIA platform.
• CI has been triggered manually, or /retest was requested.

Documentation

• GGUF Route B behavior, conversion, limitations, and validation results are documented in GGUF_ROUTE_B_QWEN38.md.
• N/A — No user-visible breaking change is introduced.

Security and Safety

• Final security and sensitive-data audit is pending.
• Third-party license compatibility has received final review.
• The complete native-code diff has received a final memory-safety audit.