chatPPT/metax：vLLM-metax 开源贡献参赛材料归档

# vLLM-metax 开源贡献参赛项目

项目简介

本项目围绕 vLLM-metax 进行开源贡献实践，目标是在沐曦 GPU 适配方向完成真实 issue 调研、代码贡献、PR 提交、运行验证和比赛材料归档。

目标上游项目：

GitHub upstream: https://github.com/MetaX-MACA/vLLM-metax
GitHub fork: https://github.com/xzh25/vLLM-metax
GitLink 项目镜像: https://www.gitlink.org.cn/metax-maca/vLLM-metax

参赛账号：

GitHub: xzh25
GitLink: chatPPT

当前贡献状态

最后核验时间：2026-07-25 UTC

本项目曾根据维护者建议，从旧 v0.19.0 issue #220 转向当时的 latest master / vLLM 0.23 对齐方向。两个真实上游 PR 和对应验证材料仍然有效，但上游 master 已继续演进，因此这里把“历史贡献结果”和“当前版本状态”明确分开。

维护者沟通：https://github.com/MetaX-MACA/vLLM-metax/issues/220#issuecomment-4611181960
技术 PR #292：https://github.com/MetaX-MACA/vLLM-metax/pull/292
文档 PR #293：https://github.com/MetaX-MACA/vLLM-metax/pull/293
GPUApps 提交 issue：https://www.gitlink.org.cn/ccf-ai-infra/GPUApps/issues/212

当前上游状态：

对象	状态	判断
PR #292	Open、未合并、`mergeable=true`；GitHub head `425a769`；相对当前 master ahead 2 / behind 27	仍是本项目的主技术贡献，但范围是 vLLM 0.23 测试 API 对齐；本轮已生成并验证待推送 commit `ed9cf8a`，修复 HMA 测试假阳性
PR #293	Open、未合并；GitHub head `b3e0aee`；ahead 1 / behind 27；`mergeable=false`	当前 master 已 supersede 原始修复语义；本轮已生成并验证待推送 commit `bf71867`，将说明限定为 v0.23 版本线
vLLM-metax master	`setup.py` 为 `0.24.0`；`pyproject.toml` 固定 `torch==2.10.0+metax3.8.0.7`	当前基线已不是本项目 2026-06 验证使用的 vLLM 0.23 / MACA 3.5 组合
PR #326	Open	上游正在继续推进 vLLM 0.25.0 升级

PR #292 是主技术贡献：同步 v1 KV cache 相关 CPU 测试到 vLLM 0.23 API，并修复 MetaX 环境中的测试收集与 cleanup 兼容问题。Gemini Code Assist 指出的 ModelConfig(max_model_len=...) 问题已通过 follow-up commit 425a769 修复。2026-07-25 进一步发现 helper 直接把 HMA 开关设为 False，使一个本应验证真实 VllmConfig 解析的用例恒通过；待推送 commit ed9cf8a 已恢复 None → False 的真实测试语义，并完成 1 passed semantic guard 和 63 passed / 3 deselected 目标集合复验。

PR #293 是独立文档贡献：将 MACA source build 文档中的 vLLM 分支从 releases/v0.22.0 对齐到当时 master 使用的 releases/v0.23.0。Gemini Code Assist 没有提出修改意见；截至最后核验时间，这一修改已被上游版本推进自然覆盖，不应再描述为当前 master 的待合并修复。v0.23.0-dev 分支仍保留旧文档，因此 retarget 后仍有维护价值。待推送 commit bf71867 已把 “current master” 改为不随 master 演进而失真的 “vLLM-metax v0.23 line”。

两条新 commit 已在远端独立 clean worktree 中使用 signoff 提交，并制作 complete-history bundle 回传；本机缺少发布流程要求的 gh 前置工具，因此尚未推送到 GitHub。这里不把“已验证、待推送”写成“PR 当前 head”。

上游版本演进与生态位

vLLM 官方首页已将 MetaX 列入硬件插件生态；硬件插件协作政策也说明 out-of-tree platform plugin 是保持核心仓库硬件无关的正式协作路径。
MetaX 官方仓库要求 vLLM 与插件版本匹配；官方 quickstart 进一步给出 MACA、mcoplib 和镜像的配套关系。因此验证对象必须是完整软件栈，不能只写一个 vLLM 版本。
vLLM v0.24.0 引入了与设备适配直接相关的变化，包括设备选择改用 device_ids、不再由框架内部设置 CUDA_VISIBLE_DEVICES，以及 _C 扩展向 libtorch stable ABI 的迁移。
vLLM v0.25.0 将 Model Runner V2 扩大为所有 dense models 的默认路径，并移除 legacy PagedAttention；v0.25.1 是随后发布的稳定补丁版本。
vLLM-metax 已有自己的 MRV2 适配工作，因此不能简单归纳为“缺少 MRV2”；更准确的判断是，0.24/0.25 的默认执行路径、扩展 ABI 和设备管理变化持续提高后端跟进成本。
本项目的生态位是“小而真实的上游兼容贡献 + 可审计的 C500 验证证据”。它证明了 vLLM 0.23 阶段的测试迁移、review 闭环和历史环境功能 smoke，但不是一个独立后端发行版，也没有证明 0.24/0.25 当前路径已经通过同等验证。
详细价值判断与优化优先级见 docs/01_project_research.md；本轮完整执行结果见 docs/13_20260725_c500_revalidation_and_pr_hardening.md。

关键证据

总索引（Claim → commit → command/log → result → caveat）：EVIDENCE_INDEX.md
PR #292 初始验证日志：logs/remote_validation/044_final_verify_vllm023_kv_cache_tests.txt
PR #292 review 修复验证：logs/remote_validation/058_verify_pr292_modelconfig_followup_scheduler_tokens.txt
PR #292 C500 clean worktree 验证：logs/remote_validation/061_verify_pr292_local_core_tests_clean_worktree.txt
PR #293 探测与验证日志：logs/remote_validation/050_pr2_source_probe.txt
2026-07-25 新实例 C500/软件基线：logs/remote_validation/079_current_c500_base_environment.txt
PR #292 HMA 语义修正验证：logs/remote_validation/085_pr292_hma_semantics_fix_validation.txt
PR #293 branch-specific 措辞修正：logs/remote_validation/086_pr293_branch_specific_wording_fix.txt
current master 静态版本门：logs/remote_validation/087_current_master_static_compatibility_gate.txt
updated PR #292 C500 safetensors 推理：logs/remote_validation/088_updated_pr292_tiny_real_weight_inference_c500.txt
C500 OpenAI server/client：logs/remote_validation/089_openai_server_tiny_random_c500.txt、090_openai_client_tiny_random_c500.txt、091_openai_server_client_summary_c500.txt
新日志 SHA256 与待推送 commit inventory：logs/remote_validation/093_new_validation_logs_sha256.txt、094_pending_push_commit_bundles.txt
C500 运行补充验证：logs/remote_validation/064_c500_torch_compute_and_metax_imports.txt
C500 tiny dummy vLLM 推理成功日志：logs/remote_validation/075_tiny_dummy_inference_with_complete_accelerator_shim.txt
C500 tiny real-weight vLLM 推理成功日志：logs/remote_validation/078_real_weight_tiny_llama_inference_c500_generate_api.txt
GPUApps 提交记录：records/gpuapps_issue_submission.md
可视化证据快照：screenshots/01_pr_and_validation_snapshot.svg、screenshots/02_c500_runtime_snapshot.svg

C500 验证结果与边界

2026-06 与 2026-07-25 的运行使用同一历史版本线：MACA 3.5.3.20、 torch 2.8.0+metax3.5.3.9、vLLM 0.23.0 和旧版本 MetaX op bundle。 2026-07-25 新实例有两张 C500，并重新完成设备计算、测试、LLM.generate 和 OpenAI-compatible /v1/completions。这些结果是功能 smoke、问题定位和实验性 workaround 证据，不构成 current master 的 MACA 3.5 支持声明，也不代表 0.24/0.25、生产模型、语言质量或性能目标已经验证。

PR #292 clean-worktree 目标测试摘要：

Commit: 425a76942c6ee48ccb78a1460d22fdb54d366f17
GPU: MetaX C500 64GB
torch: 2.8.0+metax3.5.3.9
vLLM: 0.23.0
collect: 63/66 tests collected, 3 deselected
pytest: 63 passed, 3 deselected, 5 warnings

这组测试在 C500 主机上运行，但本身属于 CPU-safe tests，不应表述为 GPU kernel 回归。3 个 deselected 用例均为真实 ModelConfig("Qwen/Qwen1.5-7B", ...) 外部模型配置解析路径；未过滤运行已收集 66 tests，并在外部 HuggingFace 配置请求处等待后人工中断，停止前为 33 passed，记录见 logs/remote_validation/059_verify_pr292_full_core_tests_clean_worktree.txt。

2026-07-25 在待推送 commit ed9cf8a 上重新执行：

HMA semantic guard: 1 passed
collect: 63/66 tests collected, 3 deselected
pytest: 63 passed, 3 deselected, 6 warnings

这次测试恢复了真实 VllmConfig 的 HMA 配置解析，而不是由 stub 预先写入期望值；证据见 logs/remote_validation/085_pr292_hma_semantics_fix_validation.txt。

C500 运行补充验证：

vLLM-metax key imports: OK
torch.cuda device: MetaX C500
float16 matmul: 1024 x 1024, cuda:0, checksum recorded

最小 vLLM dummy inference 已完成，日志为 logs/remote_validation/075_tiny_dummy_inference_with_complete_accelerator_shim.txt。当时环境没有现成模型缓存，因此使用本地 tiny Llama config + load_format="dummy"，并在 vLLM 0.23 隔离环境中补齐运行依赖和进程级 runtime shim。最终结果：

LLM engine initialized on MetaX C500
generated_token_ids [8]
finish_reason length

随后进一步生成本地 HF safetensors 随机权重模型，不依赖外网下载，在同一 C500 环境中完成权重文件加载和 token generation，日志为 logs/remote_validation/078_real_weight_tiny_llama_inference_c500_generate_api.txt。这里的“真实权重加载”指实际读取 safetensors，而不是有语言质量的预训练权重；最终结果：

Loading safetensors checkpoint shards: 100%
Model loading took 0.0 GiB memory and 0.191696 seconds
GPU KV cache size: 32,519,616 tokens
prompt_token_ids [1, 10, 11, 12]
generated_token_ids [7, 75, 31, 89]
finish_reason length

2026-07-25 在新实例、PR #292 待推送验证 commit ed9cf8a 上复验得到相同 token 结果，见 logs/remote_validation/088_updated_pr292_tiny_real_weight_inference_c500.txt。随后生成确定性 WordLevel tokenizer，将 "Hello MetaX GPU" 编码为 [4, 5, 6]，并在仅绑定 loopback 的 server 上成功调用：

POST /v1/completions: PASS
prompt_tokens: 3
completion_tokens: 4
response_text: " token_97 token_97 token_97 token_83"
finish_reason: length
single_request_elapsed_ms: 643

这是随机权重、单请求、eager mode 的 API compatibility smoke。输出没有语言质量意义，643 ms 没有预热和重复样本，不能作为 benchmark。server/client、 SHA256 和清理证据分别见日志 089–093。

仓库内容

docs/: 调研、设计、部署、验证、性能报告
records/: issue、PR、commit、review 记录
logs/: 本地调研、远端验证、C500 推理与 server/client 原始日志
scripts/: 已执行或归档的模型、tokenizer、服务烟测和材料审计脚本
env/: 沐曦 GPU 与软件环境记录
benchmarks/: 性能测试结果表
screenshots/: 当前为生成的日志摘要 SVG；真实终端与 PR/Merge 截图待补
demo/: 演示视频链接或说明
references/: 开源项目来源与参考说明

后续待完成

在本会话采用的合规 gh 发布流程可用后推送 ed9cf8a、bf71867；当前推荐并计划把两条 PR retarget 到 v0.23.0-dev，若维护者不再维护该线则关闭为 superseded。
更新 PR 正文中的精确基线、C500 手工验证和 caveat，正式请求维护者 review。
在匹配 torch 2.10 / MACA 3.8 的镜像上验证 current master；不要把单纯解决 27 个落后提交等同于完成适配。
使用有语言语义的小模型补 chat/completions、并发、长上下文、多卡和重复性能样本。
补真实浏览器/终端截图，并在 PR 合并或关闭后归档最终 review、checks 和 merge/close commit。

参考来源说明

本项目基于 vLLM-metax 开源项目进行贡献，不直接复制为参赛作品；参赛产出是针对上游项目的真实 issue 分析、代码 PR、测试验证、文档和性能记录。