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

当前贡献状态

已根据维护者建议从旧 v0.19.0 issue #220 转向 latest master / vLLM 0.23 对齐方向。

维护者沟通：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, waiting for review/checks
PR #293: open, mergeable=true, waiting for review/checks

PR #292 是主技术贡献：同步 v1 KV cache 相关 CPU 测试到 vLLM 0.23 API，并修复 MetaX 环境中的测试收集与 cleanup 兼容问题。Gemini Code Assist 指出的 ModelConfig(max_model_len=...) 问题已通过 follow-up commit 425a769 修复。

PR #293 是独立文档贡献：将 MACA source build 文档中的 vLLM 分支从 releases/v0.22.0 对齐到当前 master 使用的 releases/v0.23.0。Gemini Code Assist 没有提出修改意见。

关键证据

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

3 个 deselected 用例均为真实 ModelConfig("Qwen/Qwen1.5-7B", ...) 外部模型配置解析路径；未过滤的完整运行已收集 66 tests，并在外部 HuggingFace 配置请求处阻塞前通过 33 passed，记录见 logs/remote_validation/059_verify_pr292_full_core_tests_clean_worktree.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。最终结果：

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

仓库内容

docs/: 调研、设计、部署、验证、性能报告
records/: issue、PR、commit、review 记录
logs/: 本地调研日志、后续真实运行日志
scripts/: 后续用于模型服务调用、测试、benchmark 的脚本
env/: 沐曦 GPU 与软件环境记录
benchmarks/: 性能测试结果表
screenshots/: 运行截图与 PR/Merge 截图
demo/: 演示视频链接或说明
references/: 开源项目来源与参考说明

后续待完成

争取 PR #293 先 merge，形成最低完成线。
继续等待/响应 PR #292 review，争取主技术 PR merge。
如后续可获得 tokenizer 完整真实模型缓存，继续补 OpenAI-compatible server 文本接口调用日志。
归档 PR merge 截图和 merge commit。
如比赛入口要求补充非 GitLink issue 表单，则同步提交同一份材料。

参考来源说明

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