A Anaxagore
← 所有项目

Contribution Tasks

vllm-project/vllm

候选人的 GPU kernel / 训练性能工程专长与 vLLM 高度契合，但当前无 GPU 的硬约束把贡献范围压缩到 CPU 后端、纯逻辑层（调度/内存/权重加载）、构建系统、测试基建、文档，以及可在 Triton 解释器模式或 Colab T4 上验证的 kernel 正确性问题。vLLM 的 csrc/cpu/、vllm/v1/engine、vllm/entrypoints、tests/kernels/、benchmarks/kernels/cpu/、docs/ 是主战场；长期目标是 ownership_target 指向的 CPU 后端 kernel 优化、微基准与 Apple Silicon 支持。

当前方向：vLLM 当前主线是 v1 架构重构（vllm/v1、tests/v1 提交热点）、新模型接入（vllm/models 200+ 架构）、kernel 回归测试（tests/kernels）、batch invariance（Issue #27433，99 条评论，good first issue）、disaggregated prefill/decode、LoRA 与量化（MXFP8/NVFP4/W4A8）。Release 节奏约每两周（v0.29.0 → v0.30.0 → v0.31.0）。CPU 后端（csrc/cpu/）与 Apple Silicon 支持是明确缺口：微基准稀少、缺少 batch-invariant 采样、缺少 CPU vs CUDA 精度对照、缺少 autotune、缺少性能回归 CI。

★ 93192Fork 230004 个候选任务Gemini：LongCat-2.0

更新于 2026-10-08T07:37:23+00:00 · 打开仓库 ↗

一、项目定位

vLLM 是目前最活跃的开源 LLM 推理与服务引擎之一，起源于 UC Berkeley Sky Computing Lab，由 2000+ 贡献者维护。它围绕 PagedAttention 这一核心内存管理技术构建，解决大语言模型推理中 KV cache 内存浪费与吞吐瓶颈问题，同时提供 continuous batching、chunked prefill、prefix caching、CUDA/HIP graph、speculative decoding、disaggregated prefill/decode 等全套高性能 serving 能力。项目处于成熟且快速演进阶段：最近三个 Release（v0.29.0 2026-09-09、v0.30.0 2026-09-22、v0.31.0 2026-10-05）显示约每两周一个版本；提交热点集中在 vllm/models、tests/v1、tests/kernels、vllm/v1、vllm/entrypoints、vllm/lora，说明 v1 架构重构、新模型接入、kernel 回归测试是当前主线。仓库规模可观：csrc/ 322 个文件（CUDA/HIP/C++ 内核）、rust/ 509 个文件（Rust 前端与 runtime）、tests/ 2341 个文件、vllm/ 872 个文件、docs/ 356 个文件、benchmarks/ 138 个文件、examples/ 267 个文件。README 明确列出支持的硬件包括 NVIDIA GPU、AMD GPU、Intel GPU、x86/ARM/PowerPC CPU，以及 TPU、Gaudi、Ascend、Apple Silicon 等插件化后端。对 GPU kernel 工程师而言，这是切入 LLM serving 内核优化的主流入口。

解决什么问题、给谁用

解决 LLM 推理 serving 中的三个核心问题：(1) KV cache 内存效率——通过 PagedAttention 将 KV 内存按需分页分配，避免预留最大长度导致的浪费；(2) 吞吐与延迟——通过 continuous batching、chunked prefill、prefix caching、piecewise/full CUDA graphs、disaggregated prefill/decode 最大化 GPU 利用率；(3) 多硬件与多模型覆盖——统一支持 200+ Hugging Face 架构、多种量化格式（FP8/MXFP8/MXFP4/NVFP4/INT8/INT4/GPTQ/AWQ/GGUF/TorchAO 等）和多种分布式并行策略（TP/PP/DP/EP/CP）。典型场景：部署开源 LLM 做在线推理服务、构建 OpenAI 兼容 API 服务器、多 LoRA 动态切换、MoE 模型分布式推理、多模态模型 serving。

目标用户包括：(1) ML 工程师 / MLE 在云上或本地部署开源 LLM 做在线服务，使用 vLLM 的 OpenAI 兼容 API server；(2) 推理性能工程师优化特定模型或硬件上的吞吐、延迟、内存占用，会深入 vllm/v1/、csrc/、vllm/kernels/ 做 kernel 级调优；(3) 硬件厂商或后端插件开发者，通过 hardware plugin 接口接入新加速器；(4) 学术研究者复现或扩展 PagedAttention、speculative decoding、disaggregated serving 等方向。典型使用场景：单卡/多卡推理、disaggregated prefill-decode 分离部署、MoE expert parallelism、多 LoRA serving、量化模型推理、多模态模型推理。

同类项目与差别

核心能力

能力在哪成熟度
PagedAttention 与 KV cache 内存管理csrc/cache.h、vllm/v1/、vllm/kernels/成熟
Continuous batching / chunked prefill / prefix cachingvllm/engine/、vllm/v1/、tests/v1/成熟
CUDA/HIP graph（piecewise/full graph capture）csrc/、vllm/compilation/、tests/compile/成熟
Optimized attention kernels（FlashAttention、FlashInfer、TRTLLM-GEN、FlashMLA、Triton）csrc/attention/、vllm/kernels/、tests/kernels/成熟
Optimized GEMM/MoE kernels（CUTLASS、TRTLLM-GEN、CuTeDSL）csrc/cutlass_extensions/、csrc/moe/、tools/build_deepgemm_C.py成熟
Quantization（FP8/MXFP8/MXFP4/NVFP4/INT8/INT4/GPTQ/AWQ/GGUF/TorchAO/ModelOpt）csrc/quantization/、vllm/kernels/、tests/quantization/成熟
Speculative decoding（n-gram、suffix、EAGLE、DFlash）tests/spec_decode/、vllm/v1/成熟
Disaggregated prefill/decode/encodeexamples/disaggregated/、vllm/v1/、requirements/kv_connectors.txt成熟
Distributed parallelism（TP/PP/DP/EP/CP）vllm/distributed/、csrc/custom_all_reduce.cuh、tests/distributed/成熟
LoRA 支持（dense + MoE layers）vllm/lora/、tests/lora/、csrc/moe/成熟
Rust 前端 runtime（vllm-rs）rust/（509 文件）、setup.py 中 PRECOMPILED_RUST_FRONTEND_PATH成熟
Multi-hardware plugin（NVIDIA/AMD/Intel/CPU/TPU/Gaudi/Ascend/Apple Silicon）docker/（多 Dockerfile）、requirements/{cuda,rocm,cpu,tpu,xpu}.txt、vllm/_xpu_ops.py、vllm/_aiter_ops.py成熟（部分插件实验性）
torch.compile 自动 kernel 生成与图变换vllm/compilation/、tests/compile/成熟
Structured output（xgrammar/guidance）与 tool callingvllm/v1/、tests/renderers/、examples/tool_calling/成熟
Batch invariance / deterministic 推理tests/ 中 batch invariance 相关测试、最近提交中 batch-invariant 相关修复实验
v1 架构重构（新 engine 核心）vllm/v1/、tests/v1/（提交热点）实验

阶段：成熟且快速演进。v0.29–v0.31 三周三个版本，v1 架构重构主线清晰，2000+ 贡献者，200+ 模型支持，生产级部署广泛使用。

技术栈：Python 3.10–3.14；PyTorch 2.13.0（pyproject.toml 固定 torch == 2.13.0）；C++20（CMakeLists.txt 设置 CMAKE_CXX_STANDARD 20）；CUDA 20（CMAKE_CUDA_STANDARD 20）；HIP/ROCm（CMAKE_HIP_STANDARD 20，支持 gfx906/gfx908/gfx90a/gfx942/gfx950/gfx1250/gfx1030/gfx1100–gfx1153/gfx1200/gfx1201）；Rust（rust-toolchain.toml、rust/ 509 文件、setuptools-rust）；CMake >= 3.26.1 + Ninja（构建系统）；setuptools + setuptools-scm + setuptools-rust（打包）；uv（推荐包管理，AGENTS.md 指定）；Ruff（lint）+ pre-commit（代码检查）；CUTLASS / CuTe / DeepGEMM / FlashInfer / FlashAttention / Triton / TRTLLM-GEN / AITER（内核库）；xgrammar / guidance（结构化输出）；Ray（分布式调度，examples/ray_serving/）；gRPC（entrypoints）；Buildkite（CI，.buildkite/ 225 文件）；MkDocs（文档，mkdocs.yaml、docs/）

规模：贡献者 2000+（README 原文）；支持 200+ 模型架构（README 原文）；csrc/ 322 文件、rust/ 509 文件、tests/ 2341 文件、vllm/ 872 文件、docs/ 356 文件、benchmarks/ 138 文件、examples/ 267 文件、docker/ 多 Dockerfile（NVIDIA/ROCm/CPU/PowerPC/s390x/Intel 等）；最近 Release v0.31.0（2026-10-05）、v0.30.0（2026-09-22）、v0.29.0（2026-09-09），约每两周一个版本；提交热点：vllm/models（6）、tests/v1（4）、tests/kernels（3）、vllm/v1（3）、vllm/entrypoints（3）；star/watch/fork 具体数字需验证（README 嵌入 GitHub buttons 但未给出具体数值）。

二、架构与代码地图

vLLM 的代码组织可以清晰地划分为五层，从上到下依次为：接入层（Entrypoints & Frontend）、调度层（Engine & Scheduler）、执行层（Model Executor & Worker）、Kernel 层（csrc/ + vllm/kernels）、硬件抽象层（Platform/Device Backend）。 1) 接入层：vllm/entrypoints/ 提供 OpenAI 兼容 API server（api_server.py）、CLI（cli/main.py）、gRPC 等入口；rust/ 是 Rust 前端，承担高性能 HTTP 路由与请求解析，通过 PyO3 暴露给 Python。 2) 调度层：vllm/engine/（llm_engine.py、core.py）负责 continuous batching、chunked prefill、prefix caching 调度；vllm/v1/ 是正在重构的 v1 架构（提交热点），将调度逻辑收敛到更清晰的 v1 Engine 中。 3) 执行层：vllm/model_executor/ 定义模型前向逻辑；vllm/worker/（需验证具体路径）管理 GPU worker 与 KV cache 分配；vllm/distributed/ 封装 TP/PP/DP/EP/CP 并行。 4) Kernel 层：csrc/（322 文件）包含 CUDA/HIP/C++ 内核——attention、MoE、quantization、cache 操作、collective 通信；vllm/kernels/ 是 Python 侧 Triton/CuTeDSL 内核封装；csrc/libtorch_stable/ 是基于 torch::stable API 的新一代内核（DeepSeek-V4 MLA 融合 kernel、NVFP4 quant、W8A8 CUTLASS GEMM 等）。 5) 硬件抽象层：vllm/platforms/（需验证）提供多后端抽象；csrc/cpu/ 覆盖 x86/ARM/RISC-V/PowerPC/Apple Silicon；csrc/rocm/ 为 AMD GPU；csrc/attention/ 通过 attention_dtypes.h 做 dtype 分发。 这种分层让同一份调度逻辑可以跑在 NVIDIA、AMD、Intel GPU 以及 Apple Silicon CPU 上，而 kernel 优化只需在对应后端目录下修改。

接入层调度层执行层Kernel 层硬件抽象层其他entrypoints → engine：请求请求rust_frontend → entrypoints：HTTP 请求engine → v1_engine：调度逻辑迁移engine → model_executor：ModelInputModelInputv1_engine → model_executor：ModelInputModelInputmodel_executor → models：forwardmodel_executor → kernels：Python kerPython kermodel_executor → csrc_cuda_kernels：CUDA kerneCUDA kernemodels → lora：LoRA 适配models → config：模型配置模型配置distributed → csrc_cuda_kernels：collectivecollectivecompilation → csrc_cuda_kernels：graph captgraph captcsrc_cuda_kernels → platforms：设备抽象设备抽象kernels → csrc_cuda_kernels：Triton/CuTconfig → engine：调度配置调度配置entrypointsentrypointsrust_frontendrust_frontendengineenginev1_enginev1_engineconfigconfigmodel_executormodel_executormodelsmodelsloraloradistributeddistributedcompilationcompilationkernelskernelscsrc_cuda_kernelscsrc_cuda_kernelsplatformsplatformsteststestsbenchmarksbenchmarkstoolstools
vLLM 五层架构：接入层 → 调度层 → 执行层 → Kernel 层 → 硬件抽象层，展示请求流与模块依赖
模块 / 路径职责 · 入口 · 依赖
entrypoints
vllm/entrypoints/
约 30+ 文件（提交热点）		所有外部入口：OpenAI 兼容 API server、CLI、gRPC server
入口：api_server.py, openai/api_server.py, cli/main.py, grpc/grpc_server.py
依赖：engine, config, distributed
pyproject.toml 注册 vllm = vllm.entrypoints.cli.main:main；最近提交热点，v1 重构重点
engine
vllm/engine/
约 20+ 文件		核心调度引擎：continuous batching、chunked prefill、prefix caching、speculative decoding 编排
入口：llm_engine.py, core.py, scheduler.py（需验证）, output_processor.py（需验证）
依赖：vllm/v1, model_executor, worker, distributed
v0.31.0 仍在 v0/v1 双轨并行；v1 架构在 vllm/v1/ 下重构
v1_engine
vllm/v1/
约 30+ 文件（提交热点）		v1 架构重构中的新 Engine，收敛调度逻辑
入口：engine.py（需验证）, scheduler.py（需验证）, core/（需验证）
依赖：engine, model_executor, worker
tests/v1 是测试热点，说明 v1 是当前主线
model_executor
vllm/model_executor/
约 50+ 文件		模型前向执行逻辑：加载 HuggingFace 模型、定义 forward、管理 LoRA、量化
入口：model_loader.py（需验证）, models/（需验证）, lora/（需验证）
依赖：vllm/models, kernels, config
与 vllm/models/ 紧密配合，提交热点
models
vllm/models/
约 200+ 文件（最大提交热点）		200+ HuggingFace 架构注册与适配
入口：registry.py（需验证）, 各模型目录如 llama.py, qwen.py, deepseek.py, mamba.py
依赖：model_executor, kernels, config
最近提交：Qwen4Exp QSA QKVG 融合、DSv4.1 compressor ring 修复；新模型主要在此接入
kernels
vllm/kernels/
约 30+ 文件		Python 侧 Triton/CuTeDSL 内核封装与自动调优
入口：（需验证具体 .py 文件）
依赖：csrc, torch
tests/kernels 是测试热点
csrc_cuda_kernels
csrc/
322 文件		C++/CUDA/HIP 内核主目录：attention、MoE、quantization、cache、collective
入口：torch_bindings.cpp, attention/, moe/, quantization/, cache.h, libtorch_stable/
依赖：torch, CUDA/HIP runtime, cutlass, qutlass
核心性能层；csrc/libtorch_stable/ 是新一代 torch::stable API 内核
distributed
vllm/distributed/
约 30+ 文件		分布式并行：TP/PP/DP/EP/CP、NCCL/HIP 通信、KV cache 跨节点传输
入口：parallel_state.py（需验证）, communication.py（需验证）, kv_transfer/（需验证）
依赖：csrc_cuda_kernels, engine
disaggregated prefill/decode 依赖此模块
config
vllm/config/
约 20+ 文件		配置系统：ModelConfig、CacheConfig、SchedulerConfig、ParallelConfig 等
入口：model_config.py, cache_config.py, scheduler_config.py, parallel_config.py（需验证）
依赖：无
所有层都依赖 config；tests/config 验证配置解析
compilation
vllm/compilation/
约 10+ 文件		torch.compile 与 CUDA/HIP graph 管理
入口：（需验证）
依赖：model_executor, kernels
piecewise/full CUDA graph 在此实现
rust_frontend
rust/
509 文件		Rust 前端：高性能 HTTP 请求路由、序列化，通过 PyO3 暴露给 Python
入口：src/（需验证）, Cargo.toml
依赖：entrypoints
setup.py 中 setuptools-rust 构建；v1 架构可能迁移更多逻辑到 Rust
lora
vllm/lora/
约 15+ 文件（提交热点）		LoRA 适配：支持 dense 和 MoE 层的 LoRA、batch-invariant split-K
入口：（需验证）
依赖：models, kernels
最近提交：deterministic split-K=8 LoRA shrink for batch invariance
platforms
vllm/platforms/
约 10+ 文件		多硬件后端抽象层
入口：（需验证）
依赖：csrc_cuda_kernels, csrc/cpu/, csrc/rocm/
README 列出 NVIDIA/AMD/Intel GPU、CPU、TPU、Gaudi、Ascend、Apple Silicon 等
tests
tests/
2341 文件		测试套件：2341 文件，覆盖 kernel、model、engine、entrypoint、distributed
入口：kernels/, models/, v1/, entrypoints/, distributed/, spec_decode/, lora/, quantization/
依赖：所有模块
tests/v1、tests/kernels、tests/models 是热点；CI 在 .buildkite/
benchmarks
benchmarks/
138 文件		性能基准测试：serving throughput/latency、kernel microbenchmark
入口：benchmark_serving.py, benchmark_throughput.py, kernels/, fused_kernels/, attention_benchmarks/
依赖：entrypoints, engine, csrc_cuda_kernels
kernels/ 下有大量 CUDA kernel benchmark（MoE、GEMM、paged attention、RoPE 等）
tools
tools/
68 文件		构建与辅助工具：Rust 构建、Triton/DeepGemm/FlashInfer 编译、kernel autotune
入口：build_rust.py, autotune_helion_kernels.py, benchmark_helion_kernels.py, ep_kernels/
依赖：csrc_cuda_kernels, rust_frontend
tools/ep_kernels/ 是 expert-parallel kernel 工具
目录树（按文件数）
  • tests/ 2341 个文件
    __init__.py, basic_correctness, benchmarks, ci_envs.py, compile, config, conftest.py, cuda, detokenizer, device_allocator, distributed, engine, entrypoints, evals
  • vllm/ 872 个文件
    __init__.py, _aiter_ops.py, _custom_ops.py, _xpu_ops.py, assets, benchmarks, collect_env.py, compilation, config, connections.py, cute_utils, device_allocator, distributed, engine
  • rust/ 509 个文件
    .config, .gitattributes, .gitignore, AGENTS.md, Cargo.lock, Cargo.toml, README.md, clippy.toml, deny.toml, proto, rustfmt.toml, rustfmt.unstable.toml, src
  • docs/ 356 个文件
    .nav.yml, README.md, api, assets, benchmarking, cli, community, configuration, contributing, deployment, design, examples, features, getting_started
  • csrc/ 322 个文件
    attention, cache.h, core, cpu, cuda_compat.h, cuda_utils.h, cumem_allocator.cpp, cumem_allocator_compat.h, custom_all_gather_reduce_scatter.cuh, custom_all_reduce.cuh, custom_collective_common.cuh, custom_quickreduce.cu, cutlass_extensions, dispatch_utils.h
  • examples/ 267 个文件
    __init__.py, applications, basic, deployment, disaggregated, features, generate, observability, pooling, ray_serving, reasoning, rl, scale_out, speech_to_text
  • .buildkite/ 225 个文件
    .pipeline_gen_v2, amd-disagg, check-torch-abi.py, check-wheel-size.py, ci_config.yaml, ci_config_intel.yaml, ci_config_rocm.yaml, hardware_tests, image_build, intel_jobs, lm-eval-harness, performance-benchmarks, release-pipeline.yaml, scripts
  • benchmarks/ 138 个文件
    README.md, __init__.py, attention_benchmarks, auto_tune, backend_request_func.py, benchmark_batch_invariance.py, benchmark_block_pool.py, benchmark_hash.py, benchmark_hidden_state_extraction.py, benchmark_latency.py, benchmark_long_document_qa_throughput.py, benchmark_ngram_proposer.py, benchmark_pin_memory.py, benchmark_prefix_block_hash.py
  • tools/ 68 个文件
    __init__.py, autotune_helion_kernels.py, benchmark_helion_kernels.py, build_deepgemm_C.py, build_rust.py, build_rust.sh, build_triton_from_source.sh, check_repo.sh, check_wheel_deepgemm.py, ci, ep_kernels, flashinfer-build.sh, generate_cmake_presets.py, generate_versions_json.py
  • .github/ 42 个文件
    CODEOWNERS, CODE_OF_CONDUCT.md, CONTRIBUTING.md, FUNDING.yml, ISSUE_TEMPLATE, PULL_REQUEST_TEMPLATE.md, actionlint.yaml, codecov.yml, dependabot.yml, mergify.yml, scale-config.yml, workflows
  • requirements/ 28 个文件
    build, common.txt, cpu.txt, cuda.txt, dev.txt, docs.in, docs.txt, kv_connectors.txt, kv_connectors_cu12.txt, kv_connectors_rocm.txt, lint.txt, rocm.txt, rubin-prerelease.txt, test
  • docker/ 19 个文件
    Dockerfile, Dockerfile.cpu, Dockerfile.ppc64le, Dockerfile.rock, Dockerfile.rock_base, Dockerfile.rocm, Dockerfile.rocm_base, Dockerfile.rocm_base_gfx1250, Dockerfile.rocm_gfx1250, Dockerfile.s390x, Dockerfile.xpu, Dockerfile.zen, build_vllm_ppc64le.sh, ci-rocm.hcl
  • .agents/ 13 个文件
    skills
  • cmake/ 13 个文件
    cpu_extension.cmake, external_projects, hipify.py, patches, utils.cmake
  • .claude/ 6 个文件
    skills
  • .clang-format/ 1 个文件

一次调用怎么流过这些模块

一次典型推理请求的数据流如下： 1) 请求进入：HTTP/gRPC 请求到达 rust/ 前端（PyO3 绑定）或 vllm/entrypoints/api_server.py，被封装为 SamplingParams + token ids，送入 LLMEngine.add_request()。 2) 调度：vllm/engine/llm_engine.py 的 EngineCore 运行 scheduler（scheduler.py），根据 PagedAttention 的 block table 状态决定本轮调度哪些 request 的 prefill/decode。调度器输出 SchedulerOutputs，包含选中的 request 列表、它们的 block allocation、是否为 chunked prefill。 3) 模型前向准备：vllm/model_executor/ 的 model runner 将调度结果组装为 ModelInput（包含 input_ids、positions、block_tables、slot_mapping 等 IR），通过 vllm/ir/（Intermediate Representation）做图捕获。 4) Worker 执行：vllm/worker/（需验证路径）的 Worker 在对应 device 上调用 model_executor.execute_model()，触发模型 forward。 5) Kernel 层计算：forward 过程中调用各 kernel—— - csrc/attention/ 或 csrc/libtorch_stable/attention/ 做 paged attention / FlashMLA / TRTLLM-GEN attention - csrc/libtorch_stable/quantization/ 做 FP8/NVFP4/MXFP4 量化 GEMM（CUTLASS、CuTeDSL、Marlin、Machete） - csrc/libtorch_stable/moe/ 做 MoE routing + grouped GEMM - csrc/libtorch_stable/cache_kernels.cu 做 reshape_and_cache（将新 KV 写入 paged cache） - csrc/libtorch_stable/activation_kernels.cu 做 SwiGLU/GeGLU 等激活 - csrc/libtorch_stable/pos_encoding_kernels.cu 做 RoPE 6) 采样：logits 回到 vllm/model_executor/layers/sampler.py（需验证），调用 csrc/cpu/sampling_kernels.cpp 或 GPU sampling kernel 做 top-k/top-p/greedy/Gumbel-max 采样。 7) 输出处理：采样结果经 engine/output_processor.py（需验证）做 detokenize、stop string 检查、streaming 输出，最终通过 entrypoints 返回给客户端。 关键数据结构：SequenceGroup（请求组）、Sequence（单个序列）、BlockTable（PagedAttention 块表）、ModelInput（IR）、SchedulerOutputs（调度结果）、SamplerOutput（采样输出）。调度点：EngineCore.step() → scheduler.schedule() → worker.execute_model() → model_executor.execute_model()。

1HTTP 请求到达APIServer · vllm/entrypoints/api_server.py2封装为 ModelInputLLMEngine.add_request · vllm/engine/llm_engine.py3调度 prefill/decodeScheduler.schedule · vllm/engine/scheduler.py（需验证）4组装 forward 输入ModelRunner.execute_model · vllm/model_executor/model_runner.py（需验证）5CUDA kernel 计算csrc CUDA kernels · csrc/libtorch_stable/（attention/cache/quant/moe）6采样 next tokenSampler · vllm/model_executor/layers/sampler.py（需验证）7流式返回输出OutputProcessor · vllm/engine/output_processor.py（需验证）

关键类型与函数

名称路径用途
LLMEnginevllm/engine/llm_engine.py
EngineCorevllm/engine/core.py（需验证）
Schedulervllm/engine/scheduler.py（需验证）
ModelRunnervllm/model_executor/model_runner.py（需验证）
Workervllm/worker/worker.py（需验证）
BlockTablevllm/core/block_manager.py 或 vllm/v1/core/（需验证）
ModelInput / SamplingParamsvllm/model_executor/（需验证）
reshape_and_cachecsrc/libtorch_stable/cache_kernels.cu
swap_blockscsrc/libtorch_stable/cache_kernels.cu
paged_attention kernelscsrc/attention/ 或 csrc/libtorch_stable/attention/
fused_qknorm_rope_kernelcsrc/libtorch_stable/fused_qknorm_rope_kernel.cu
fused_deepseek_v4_qnorm_rope_kv_insert_kernelcsrc/libtorch_stable/fused_deepseek_v4_qnorm_rope_kv_insert_kernel.cu
activation_kernels (SwiGLU/GeGLU)csrc/libtorch_stable/activation_kernels.cu
MoE routing + grouped GEMMcsrc/libtorch_stable/moe/ 和 csrc/libtorch_stable/quantization/
CUTLASS scaled GEMM (W8A8/FP8/NVFP4)csrc/libtorch_stable/quantization/w8a8/ 和 fp4/
fused_gumbel_argmax_kernelcsrc/cpu/sampling_kernels.cpp
ModelRegistryvllm/models/registry.py（需验证）

扩展点

最近在动的地方

建议阅读顺序

  1. README.md + docs/design/ —— 理解 PagedAttention 与整体设计
  2. vllm/entrypoints/api_server.py —— 看请求如何进入
  3. vllm/engine/llm_engine.py —— 理解 Engine 主循环与调度入口
  4. vllm/engine/core.py（需验证） —— 看 EngineCore.step() 调度流程
  5. vllm/model_executor/ —— 理解 ModelRunner 与 forward 组装
  6. vllm/models/llama.py（或任一熟悉模型）—— 看模型注册与 forward 实现
  7. csrc/libtorch_stable/cache_kernels.cu —— 理解 reshape_and_cache 与 PagedAttention 内存写入
  8. csrc/libtorch_stable/attention/ 或 csrc/attention/ —— 看 paged attention kernel
  9. csrc/libtorch_stable/fused_deepseek_v4_qnorm_rope_kv_insert_kernel.cu —— 看超融合 MLA kernel（当前最复杂 kernel）
  10. tests/kernels/ + benchmarks/kernels/ —— 理解 kernel 测试与性能基准

三、本地跑起来（没有 GPU 的 Mac）

安装

  1. # 1. 安装 uv（macOS 推荐用 Homebrew 或官方脚本）
  2. brew install uv # 或 curl -LsSf https://astral.sh/uv/install.sh | sh
  4. # 2. 创建 Python 3.12 虚拟环境（Apple Silicon 上 3.12 最稳）
  5. uv venv --python 3.12
  6. source .venv/bin/activate
  8. # 3. 安装 CPU 专用依赖（跳过 CUDA/ROCm）
  9. uv pip install -r requirements/common.txt
  10. uv pip install -r requirements/cpu.txt
  12. # 4. 关键：强制 VLLM_TARGET_DEVICE=cpu，避免 setup.py 尝试编译 CUDA 扩展
  13. # setup.py 中明确有逻辑：macOS 上若 VLLM_TARGET_DEVICE != 'cpu' 会自动降级为 cpu
  14. # 但显式设置可避免触发 torch.cuda 相关检查
  15. export VLLM_TARGET_DEVICE=cpu
  17. # 5. 使用预编译扩展editable安装（跳过本地编译 csrc/ 中的 CUDA 内核）
  18. # 这是 AGENTS.md 推荐的方式，Apple Silicon 上无法编译 .cu/.cuh 文件
  19. VLLM_USE_PRECOMPILED=1 uv pip install -e . --torch-backend=auto
  21. # 6. 若上一步失败（无预编译 wheel 匹配当前 torch 版本），尝试纯 Python 安装
  22. # 这会跳过 C++/Rust 扩展编译，仅安装 Python 包
  23. # uv pip install -e . --no-build-isolation
  25. # 7. 安装测试依赖（CPU 子集）
  26. uv pip install -r requirements/test/cuda.in # 或 requirements/dev.txt

哪些路径能真跑

['可执行路径（CPU/MPS）：', '- csrc/cpu/ 下所有 .cpp/.hpp：cpu_attn.cpp、cpu_fused_moe.cpp、layernorm.cpp、sampling_kernels.cpp、mamba_cpu.cpp、dnnl_kernels.cpp 等，这些是纯 C++ 实现，Apple Silicon 上通过 -mcpu=apple-m1 或 NEON 指令编译', '- vllm/kernels/ 中部分 Triton/CuTeDSL 内核：若 torch 支持 MPS backend，部分 kernel 可回退到 MPS；但多数 CUDA-specific kernel（如 paged_attention、flash_attn）无法执行', '- vllm/engine/、vllm/v1/、vllm/entrypoints/：调度逻辑纯 Python，可在 CPU 上跑通流程（但推理极慢）', '- tests/platforms/、tests/cpu/（若存在）：平台抽象层测试', '', '只能读代码或需 Colab T4 验证：', '- csrc/libtorch_stable/ 下所有 .cu 文件：activation_kernels.cu、cache_kernels.cu、fused_deepseek_v4_qnorm_rope_kv_insert_kernel.cu 等，全部依赖 CUDA API', '- csrc/attention/ 下 .cuh 文件：attention_generic.cuh、dtype_fp8.cuh 等', '- csrc/cutlass_extensions/、csrc/moe/、csrc/quantization/：CUTLASS/CuTe 内核', '- tests/kernels/、tests/cuda/、tests/rocm/：GPU 专用测试', '- rust/ 目录：Rust 前端需要 cargo 编译，且部分模块依赖 CUDA 特性']

最小可运行

  1. # 冒烟测试 1：验证 vllm 包导入（确认安装成功）
  2. .venv/bin/python -c "import vllm; print(vllm.__version__)"
  4. # 冒烟测试 2：验证 CPU 平台后端加载
  5. .venv/bin/python -c "from vllm.platforms import current_platform; print(current_platform)"
  7. # 冒烟测试 3：用 tiny model 跑 CPU 推理（极慢但验证端到端流程）
  8. # 需要下载一个小型 HF 模型，如 facebook/opt-125m
  9. .venv/bin/python -c "
  10. from vllm import LLM, SamplingParams
  11. llm = LLM(model='facebook/opt-125m', device='cpu', enforce_eager=True)
  12. outputs = llm.generate(['Hello world'], SamplingParams(max_tokens=10))
  13. print(outputs[0].outputs[0].text)"
  15. # 冒烟测试 4：运行 CPU 专用 kernel 测试（若存在）
  16. .venv/bin/python -m pytest tests/platforms/ -v -k 'cpu'
  18. # 冒烟测试 5：运行 v1 引擎调度测试（纯 Python 逻辑）
  19. .venv/bin/python -m pytest tests/v1/ -v --timeout=60
  21. # 冒烟测试 6：验证 Rust 前端是否可用（若编译成功）
  22. .venv/bin/python -c "from vllm._rust import RustFrontend; print('Rust frontend loaded')"

测试

测试框架：pytest（根目录 tests/，2341 个文件） CPU 子集运行命令： # 运行平台相关测试 .venv/bin/python -m pytest tests/platforms/ -v --timeout=120 # 运行 v1 调度测试（不依赖 GPU） .venv/bin/python -m pytest tests/v1/ tests/engine/ -v --timeout=120 # 运行配置和入口点测试 .venv/bin/python -m pytest tests/config/ tests/entrypoints/ -v --timeout=120 # 运行模型执行器测试（部分需 GPU，用 -k 过滤） .venv/bin/python -m pytest tests/model_executor/ -v -k 'not cuda' # 运行 kernel 测试中的 CPU 部分 .venv/bin/python -m pytest tests/kernels/ -v -k 'cpu' 耗时估计： - 纯 Python 测试（tests/v1/、tests/config/）：5-15 分钟 - 含 C++ 扩展的测试（tests/platforms/）：10-30 分钟（首次编译较慢） - 完整 tests/ 套件：数小时，且多数需 GPU

调试

CI

CI 系统：Buildkite（.buildkite/ 目录，225 个文件） 主要流水线： - test-pipeline.yaml：主测试流水线 - test-amd.yaml：AMD GPU 测试 - ci_config.yaml、ci_config_rocm.yaml、ci_config_intel.yaml：多硬件配置 - performance-benchmarks/：性能基准测试 - lm-eval-harness/：模型评估测试 PR 会被卡住的条件： 1. pre-commit 失败（.clang-format、.ruff、setup.py 检查） 2. 代码覆盖率下降（codecov.yml） 3. 测试失败：tests/v1/、tests/kernels/、tests/models/ 是热点区域 4. 文档构建失败（docs/ 目录） 5. Rust 编译失败（rust/ 目录） 6. 多硬件测试不通过（NVIDIA/AMD/Intel GPU） 注意：Apple Silicon 上无法运行 CI 中的 GPU 测试，需在 Colab T4 上验证

坑

四、维护者与社区

约每两周一个 minor release：v0.29.0（2026-09-09）、v0.30.0（2026-09-22）、v0.31.0（2026-10-05），节奏稳定。提交热点集中在 vllm/models、tests/v1、tests/kernels、vllm/v1、vllm/entrypoints、vllm/lora，说明 v1 架构重构、新模型接入、kernel 回归测试是当前主线。

谁角色依据
Woosuk Kwon项目创始人 / 核心架构师README 引用 PagedAttention 论文的第一作者；项目起源于 UC Berkeley Sky Computing Lab
youkaichao核心维护者 / Reviewercommit 与 PR 中频繁出现，涉及 vllm/v1、vllm/engine、csrc 等核心模块
yewentao256Kernel / 性能方向维护者Issue #57406（GLM 5.3 Performance Optimization）与 #27433（Batch Invariant）的 assignee，涉及 kernel 优化
bwastiKernel / Batch Invariant 负责人Issue #27433（Batch Invariant Feature and Performance Optimization）的 assignee，该 Issue 有 99 条评论
PaulZhang12Kernel / Batch Invariant 协作者Issue #27433 的 assignee
sfeng33Kernel / Batch Invariant 协作者Issue #27433 的 assignee
ZJY0516Mamba / Hybrid 模型性能维护者Issue #60008（Hybrid Mamba prefix caching 性能问题）的 assignee
vllmellmROCm / AMD 后端维护者Issue #56021（RDNA gfx12 AITER 问题）与 #58858（GLM-5.3-Flash kpool indexer）的 assignee
LucasWilkinson模型性能 / GLM 方向Issue #57406（GLM 5.3 Performance Optimization）的 assignee
MatthewBonanni模型性能 / GLM 方向Issue #57406 的 assignee
hmellorTransformers 升级 / 依赖维护Issue #38379（Upgrade to Transformers v5）的 assignee
zou3519torch.compile / 量化性能Issue #25094（QuantFP8 group quantization 性能问题）的 assignee
eellisontorch.compile / 量化性能Issue #25094 的 assignee

流程与 Review 风格

1. 先 Issue / RFC：AGENTS.md 明确要求『Before proposing a PR, run these checks』，用 gh issue view / gh pr list 检查重复工作；若已有 open PR 处理同一修复则不得重复提交。2. DCO：仓库根目录有 DCO 文件，提交需带 Signed-off-by。3. pre-commit：.pre-commit-config.yaml 存在，AGENTS.md 要求『Always make sure pre-commit and its hooks are installed』并运行 pre-commit install。4. AI 辅助贡献：AGENTS.md 有完整规定——纯 code-agent PR 不被允许，必须有人类提交者理解并逐行 review；PR description 必须说明为何不重复已有 PR、跑了哪些测试、模型评估结果、并明确声明使用了 AI 辅助。5. 测试：AGENTS.md 要求用 uv 管理环境，跑 .venv/bin/python -m pytest tests/path/to/test_file.py -v。6. 不得提交低价值 busywork PR（单 typo、孤立 style 改动等）。

从 Issue 与 PR 评论推断：(1) 性能相关 Issue（如 #60008、#59534、#25094）要求给出具体数字（µs、% throughput），不接受模糊描述；(2) Bug 报告（如 #60007、#59086）需要最小复现命令与硬件/模型/dtype 信息；(3) RFC 类 Issue（如 #59055、#59382、#38175）讨论较充分，维护者会引导方向；(4) 响应速度：活跃 Issue 多在 1-2 天内有回复，但 stale 标签的 Issue（如 #28467、#28498）长期无人处理；(5) 对 kernel 优化 PR 审查严格，需附带 benchmark 数据。

渠道

这里的规矩

维护者现在最想要的帮助

五、切入方案

建议长期负责：csrc/cpu/ + benchmarks/kernels/cpu/ + tests/kernels/ 的 CPU 回归测试，长期负责 vLLM CPU 后端的 kernel 优化、微基准与 Apple Silicon 支持。
CPU 后端是 vLLM 多硬件抽象层的关键一环（README 明确列出 x86/ARM/Apple Silicon），但当前投入远少于 CUDA/ROCm；该模块允许在 Apple Silicon 上无 GPU 起步，通过 NEON 向量化、DNNL 集成、batch-invariant 采样、Mamba 内核优化等逐步深入；路径清晰：先补测试与基准 → 再优化内核 → 最终成为 CPU 后端 reviewer，通向维护者身份。

它现在缺什么（你无 GPU 也能补）

缺口依据为什么是你
CPU 后端 kernel 缺少系统化微基准与回归测试benchmarks/kernels/cpu/ 下仅有 benchmark_cpu_attn.py 与 benchmark_cpu_fused_moe.py，而 CUDA 侧有 80+ 个 benchmark 文件覆盖 MoE/MLA/FP8/NVFP4/RoPE 等；tests/kernels/ 中 CPU 相关回归极少，csrc/cpu/ 下 cpu_attn.cpp、cpu_fused_moe.cpp、dnnl_kernels.cpp、mamba_cpu.cpp、sampling_kernels.cpp 均无对应微基准。你擅长算子融合与内核性能，可在 Apple Silicon 上直接用 CMake + -mcpu=apple-m1 / NEON 编译 csrc/cpu/ 并跑基准，无需 GPU。
CPU 后端缺少 batch-invariant 采样实现csrc/core/batch_invariant.hpp 定义了 batch invariant 抽象；Issue #27433（Batch Invariant Feature and Performance Optimization，99 条评论）是当前热点；csrc/cpu/sampling_kernels.cpp 已实现 fused_gumbel_argmax_kernel 与 greedy_argmax_kernel，但未见 batch-invariant 版本。你熟悉分布式训练确定性与算子融合，可在 CPU 侧先实现 batch-invariant greedy/top-k/top-p 采样，作为无 GPU 贡献的切入点。
Apple Silicon / NEON 向量化的 CPU kernel 缺少性能文档与基准对比csrc/cpu/cpu_attn_neon.hpp、cpu_attn_vec.hpp、cpu_tanhf_neon.hpp、micro_gemm/cpu_micro_gemm_neon.hpp 已实现 NEON 路径，但 docs/ 中无 CPU 性能调优指南，README 也未提 Apple Silicon 支持细节。你可在 MacBook Air 上实测 NEON 路径，补文档与基准数据，形成差异化贡献。
Mamba / Hybrid 模型的 CPU 解码路径缺少基准与测试csrc/cpu/mamba_cpu.cpp 与 mamba_kernels.hpp 实现了 causal_conv1d_update_kernel 与 selective_state_update；Issue #60008（Hybrid Mamba prefix caching 性能问题）显示 Mamba 性能是热点；benchmarks/kernels/cpu/ 无 Mamba 基准。你可为 CPU Mamba 内核写基准与回归测试，验证 Apple Silicon 上的 SSM 推理性能。
CPU 后端缺少与 CUDA 后端的功能/精度对照测试tests/kernels/ 下大量 CUDA kernel 测试，但 CPU 端缺少对应精度对齐测试；csrc/cpu/dnnl_kernels.cpp 的 static/dynamic_scaled_int8_quant_impl 等量化内核无精度回归。你可补 CPU vs CUDA 精度对照测试，确保 CPU 后端在量化场景下与 GPU 一致。
Rust 前端缺少 CPU 路径的端到端测试rust/ 509 文件承担 HTTP 路由与请求解析，通过 PyO3 暴露；但 tests/ 中 Rust 前端测试集中在 API 兼容性，缺少 CPU 后端的端到端 serving 测试。你可补 Rust 前端 + CPU 后端的集成测试，覆盖 Apple Silicon 上的 serving 路径。
CPU 后端缺少自动调优（autotune）支持tools/autotune_helion_kernels.py 与 benchmarks/auto_tune/ 显示项目有 kernel autotune 机制，但仅针对 CUDA/Helion；csrc/cpu/ 下无 autotune 入口。你可为 CPU 内核设计 autotune 框架，在 Apple Silicon 上自动选择 NEON/DNNL 最优路径。
缺少 CPU 后端的性能回归 CI.buildkite/ 下 test-pipeline.yaml、ci_config.yaml 等多为 GPU 测试；Dockerfile.cpu 存在但无对应性能回归 job；csrc/cpu/ 改动缺少自动化性能监控。你可设计轻量级 CPU 性能回归 CI，用 GitHub Actions 或 Buildkite 的 CPU runner 跑基准。

第 1–30 天：看懂并露面

第 31–60 天：稳定产出

第 61–90 天：接管一块

第一批 PR

题目范围为什么安全
[CPU] Add batch-invariant greedy/top-k/top-p sampling kernelscsrc/cpu/sampling_kernels.cpp 新增 batch-invariant 采样实现 + tests/kernels/ 对应精度测试纯新增功能，不改现有 CUDA 路径；Issue #27433 是公开讨论的热点，有明确需求；测试先行确保安全。
[CPU] Add micro-benchmarks for cpu_fused_moe and mamba_cpubenchmarks/kernels/cpu/ 新增 benchmark_cpu_fused_moe_extended.py 与 benchmark_cpu_mamba.py仅添加基准脚本，不改 kernel 代码；可本地验证，无副作用。
[Tests] Add CPU vs CUDA precision tests for int8 quant and layernormtests/kernels/ 新增 test_cpu_quant.py 与 test_cpu_layernorm.py，对比 CPU 与 CUDA 输出纯测试 PR，不修改 kernel 实现；失败时仅暴露已有问题，不引入新 bug。
[Docs] Add CPU backend performance tuning guide for Apple Silicondocs/ 新增 cpu_performance.md，记录编译选项、NEON 路径、基准数据纯文档 PR，无代码风险；基于本地实测数据。
[CPU] Add pytest unit tests for mamba_cpu causal_conv1d_update and selective_state_updatetests/kernels/ 新增 test_mamba_cpu.py，覆盖 state roll + conv 计算纯测试，验证现有 kernel 正确性；Issue #60008 显示 Mamba 性能是热点，测试先行安全。

怎么知道自己站住了

风险与对策
  • CPU 后端在 vLLM 中优先级低于 CUDA/ROCm，贡献可能被边缘化：绑定公开 Issue（如 #27433、#60008）证明需求；用基准数据展示 Apple Silicon 用户群体；主动与 youkaichao 等核心维护者对齐路线图。
  • Apple Silicon 16GB 内存限制导致无法跑大模型验证：
  • csrc/cpu/ 代码可能缺少文档与注释，理解成本高：先读 csrc/attention/ 与 csrc/libtorch_stable/ 中相似 kernel 的 CUDA 实现作为参考；在 PR 中主动补文档。
  • Rust 前端改动需要 Rust 技能，超出当前舒适区：先避开 Rust 前端，专注 csrc/cpu/ 与 Python 测试；需要时与 rust/ 维护者合作。
  • CPU 后端 CI 资源有限，性能回归测试可能无基础设施：先用 GitHub Actions 的 macOS ARM runner 做轻量级基准；推动 Buildkite 加入 CPU job。
  • batch-invariant 采样涉及跨模块改动，可能触及核心调度逻辑：
  • 项目节奏快（两周一 release），PR 可能因 CI 拥挤被延迟：
  • Apple Silicon 的 NEON 路径可能与 x86/ARM 服务器行为不一致：在测试中覆盖多架构条件编译；与 vllm/platforms/ 维护者确认 CPU 后端抽象层设计。

六、怎么介入这个项目

社区入口：discuss.vllm.ai · slack.vllm.ai

建议顺序

成为长期维护者的路径
  • 先做纯 CPU / 纯测试 / 纯文档的 PR（不碰 CUDA 路径），让维护者看到在无 GPU 环境下也能稳定交付
  • 在 Issue #27433 下持续评论、补测试、补基准，逐步承接 batch-invariant 在 CPU 侧的落地
  • 接入 vLLM 社区：https://discuss.vllm.ai、https://slack.vllm.ai、https://docs.vllm.ai/en/latest/contributing/
  • 长期目标：成为 csrc/cpu/ + benchmarks/kernels/cpu/ + tests/kernels/ 中 CPU 回归测试的 reviewer/owner

七、任务卡

任务 1优先 · medium · Mac · 5–7 个晚上

[CPU] 为 csrc/cpu/ 添加 batch-invariant greedy/top-k/top-p 采样内核

Issue #27433 · [Feature]: Batch Invariant Feature and Performance Optimization ↗

已指派 bwasti, PaulZhang12, yewentao256, sfeng33已有 PR #399 条评论good first issuefeature request更新 2026-10-04

用到的专长：使用候选人在算子融合、内核实现、分布式训练确定性方面的专长，直接在 C++ 层实现 batch-invariant 采样。

目标：在 csrc/cpu/sampling_kernels.cpp 中新增 batch-invariant 的 greedy、top-k、top-p 采样实现，使 VLLM_BATCH_INVARIANT=1 在 CPU 后端也能端到端通过 tests/v1/determinism/ 的相关测试。

为什么值得长期做：Issue #27433 是 vLLM 当前最活跃的 batch-invariance tracker（99 条评论、good first issue、4 位 assignee），但 CPU 侧采样仍是空白。csrc/cpu/sampling_kernels.cpp 已有 fused_gumbel_argmax_kernel 与 greedy_argmax_kernel，但无 batch-invariant 版本。这是无 GPU 环境下能直接发挥 kernel 专长、且维护者明确想要的贡献，通向 CPU 后端 ownership 的最短路径。

怎么介入：Issue #27433 有 4 位 assignee（bwasti、PaulZhang12、yewentao256、sfeng33）和 99 条评论，但 CPU 采样子任务未被明确认领。先在 Issue 下评论确认方向，再动手。
第一个 PR 的边界：第一个 PR 仅新增内核 + 测试，不修改现有 CUDA 路径或 scheduler 逻辑；边界在 csrc/cpu/sampling_kernels.cpp 与 tests/kernels/test_cpu_sampling_batch_invariant.py（新增）。
第一步：在 Issue #27433 下开评论确认 CPU 采样子任务是否仍开放，并询问维护者对实现路径的偏好（纯 C++ kernel vs Python wrapper）。
本机怎么复现 / 验证：在 MacBook 上通过 CMake 编译 csrc/cpu/（-mcpu=apple-m1），运行 pytest tests/kernels/test_cpu_sampling_batch_invariant.py（新增），用 VLLM_BATCH_INVARIANT=1 验证 bitwise 一致性。
认领留言（英文，可直接贴到 Issue）
Hi all, I'd like to pick up the CPU-side batch-invariant sampling kernels (greedy/top-k/top-p) under this tracker. I've read csrc/cpu/sampling_kernels.cpp and csrc/core/batch_invariant.hpp — the existing fused_gumbel_argmax_kernel gives a clear template. My plan: add batch_invariant_greedy/top_k/top_p kernels in C++, register them in the CPU backend, and add tests/kernels/test_cpu_sampling_batch_invariant.py covering bitwise consistency under VLLM_BATCH_INVARIANT=1. Could you confirm (1) if this sub-task is still unclaimed, (2) whether you prefer pure C++ kernels or a Python wrapper, and (3) if temperature scaling should be included? I'll have a draft PR ready in about 5–7 days.
大致实施方案
  • 阅读 csrc/cpu/sampling_kernels.cpp 与 csrc/core/batch_invariant.hpp，理解现有 fused_gumbel_argmax_kernel / greedy_argmax_kernel 的接口与 batch invariant 抽象
  • 阅读 tests/v1/determinism/test_batch_invariance.py，理解 batch-invariant 测试的断言逻辑与调用路径
  • 在 csrc/cpu/sampling_kernels.cpp 中新增 batch_invariant_greedy / top_k / top_p 内核，遵循 batch_invariant.hpp 的接口约定
  • 在 csrc/cpu/ 的 CMakeLists.txt 或对应构建文件中注册新内核，确保 -mcpu=apple-m1 / NEON 路径可编译
  • 在 tests/kernels/ 新增 test_cpu_sampling_batch_invariant.py（新增），覆盖 greedy/top-k/top-p 的 bitwise 一致性
  • 在 MacBook 上编译并跑通测试，记录基准数据
可能涉及的目录或文件
  • csrc/cpu/sampling_kernels.cpp → 新增内核实现
  • csrc/cpu/ 构建注册 → CMakeLists.txt 或 torch_bindings
  • tests/kernels/test_cpu_sampling_batch_invariant.py → 新增测试文件
  • 需先定位 batch invariant 抽象在 CPU 侧的现有 hook 点
验收方式
  • 在 MacBook 上编译 csrc/cpu/ 并运行新增的 test_cpu_sampling_batch_invariant.py，断言 bitwise 一致
  • 运行 tests/v1/determinism/test_batch_invariance.py 中 CPU 相关用例（若有），确认不回归
  • 在 Colab T4 上编译并跑同一测试，确认 CPU 路径与 CUDA 路径行为一致
开工前问题与风险

向维护者确认

  • CPU 侧 batch-invariant 采样是否已有设计文档或接口约定？
  • 维护者偏好纯 C++ kernel 还是 Python wrapper 调用现有算子？
  • 是否需要同时覆盖 sampling post-processing（如 temperature scaling）？

风险

  • batch invariant 抽象可能仍在快速迭代，接口可能变动
  • CPU 采样路径可能依赖 scheduler 侧改动，需确认边界
  • Apple Silicon 上编译 C++ 内核可能遇到 NEON / DNNL 兼容性问题
任务 2可选 · low · Mac · 2–3 个晚上

[CPU] 为 cpu_fused_moe 与 mamba_cpu 添加微基准

Issue #60008 · [Performance]: Hybrid Mamba prefix caching (mamba_cache_mode="align") costs 11-16% throughput on Nemotron-3.5-Lightning with no cache hits: per-group eager block-table ops, per-step align kernels outside CUDA graphs, and block-boundary prefill splits ↗

已指派 ZJY05162 条评论performance更新 2026-10-05

用到的专长：使用候选人在性能建模、微基准设计、算子融合评估方面的专长。

目标：在 benchmarks/kernels/cpu/ 新增 benchmark_cpu_fused_moe_extended.py 与 benchmark_cpu_mamba.py（均为新增），覆盖不同 hidden_size / num_experts / seq_len 配置，输出延迟与吞吐量数据。

为什么值得长期做：Issue #60008 显示 Mamba 性能是热点，但 benchmarks/kernels/cpu/ 下仅有 benchmark_cpu_attn.py 与 benchmark_cpu_fused_moe.py，无 Mamba 基准。csrc/cpu/mamba_cpu.cpp 已实现 causal_conv1d_update_kernel 与 selective_state_update，但缺少系统化微基准。这是无 GPU 环境下能直接交付、且维护者明确需要的基础设施。

怎么介入：Issue #60008 已指派 ZJY0516，但该 Issue 聚焦 CUDA 侧 Mamba prefix caching 性能问题，CPU 微基准未被认领。在 Issue #60008 或 #27433 下评论确认 CPU 基准是否欢迎。
第一个 PR 的边界：第一个 PR 仅新增两个基准脚本，不修改任何 kernel 代码；边界在 benchmarks/kernels/cpu/ 下两个新文件。
第一步：阅读现有 benchmarks/kernels/cpu/benchmark_cpu_attn.py 与 benchmark_cpu_fused_moe.py，理解基准框架与输出格式。
本机怎么复现 / 验证：在 MacBook 上运行 python benchmarks/kernels/cpu/benchmark_cpu_fused_moe_extended.py 与 benchmark_cpu_mamba.py，确认输出无报错、数据合理。
认领留言（英文，可直接贴到 Issue）
Hi, I noticed benchmarks/kernels/cpu/ only has benchmark_cpu_attn.py and benchmark_cpu_fused_moe.py, with no Mamba or extended MoE coverage. Since I'm working on CPU backend improvements, I'd like to add benchmark_cpu_fused_moe_extended.py (sweeping hidden_size/num_experts/seq_len) and benchmark_cpu_mamba.py (sweeping state_size/conv_width/seq_len). Both will follow the existing benchmark script conventions and run on Apple Silicon. Would you prefer CSV, Markdown table, or JSON output? I can have a draft PR ready in 2–3 days.
大致实施方案
  • 阅读 benchmarks/kernels/cpu/ 下现有基准脚本，理解 argparse、计时、输出格式
  • 阅读 csrc/cpu/cpu_fused_moe.cpp 与 csrc/cpu/mamba_cpu.cpp 的接口，确定可调参数
  • 新增 benchmarks/kernels/cpu/benchmark_cpu_fused_moe_extended.py（新增），覆盖 hidden_size ∈ {2048, 4096, 8192}、num_experts ∈ {8, 64, 256}、seq_len ∈ {128, 512, 2048}
  • 新增 benchmarks/kernels/cpu/benchmark_cpu_mamba.py（新增），覆盖 state_size ∈ {16, 64, 128}、conv_width ∈ {4, 16}、seq_len ∈ {128, 1024}
  • 在 MacBook 上运行两个脚本，记录基准数据并附在 PR 描述中
可能涉及的目录或文件
  • benchmarks/kernels/cpu/benchmark_cpu_fused_moe_extended.py → 新增
  • benchmarks/kernels/cpu/benchmark_cpu_mamba.py → 新增
  • 需先定位 CPU 基准框架的入口与输出约定
验收方式
  • 在
  • M
  • a
  • c
  • B
  • o
  • o
  • k
  • 上
  • 运
  • 行
  • p
  • y
  • t
  • h
  • o
  • n
  • b
  • e
  • n
  • c
  • h
  • m
  • a
  • r
  • k
  • s
  • /
  • k
  • e
  • r
  • n
  • e
  • l
  • s
  • /
  • c
  • p
  • u
  • /
  • b
  • e
  • n
  • c
  • h
  • m
  • a
  • r
  • k
  • _
  • c
  • p
  • u
  • _
  • f
  • u
  • s
  • e
  • d
  • _
  • m
  • o
  • e
  • _
  • e
  • x
  • t
  • e
  • n
  • d
  • e
  • d
  • .
  • p
  • y
  • 与
  • b
  • e
  • n
  • c
  • h
  • m
  • a
  • r
  • k
  • _
  • c
  • p
  • u
  • _
  • m
  • a
  • m
  • b
  • a
  • .
  • p
  • y
  • ，
  • 确
  • 认
  • 输
  • 出
  • C
  • S
  • V
  • /
  • 表
  • 格
  • 格
  • 式
  • 正
  • 确
  • 、
  • 无
  • 报
  • 错
  • 。
开工前问题与风险

向维护者确认

  • 基
  • 准
  • 输
  • 出
  • 格
  • 式
  • 偏
  • 好
  • （
  • C
  • S
  • V
  • v
  • s
  • M
  • a
  • r
  • k
  • d
  • o
  • w
  • n
  • t
  • a
  • b
  • l
  • e
  • v
  • s
  • J
  • S
  • O
  • N
  • ）
  • ？
  • 是
  • 否
  • 需
  • 要
  • 与
  • C
  • U
  • D
  • A
  • 侧
  • b
  • e
  • n
  • c
  • h
  • m
  • a
  • r
  • k
  • 脚
  • 本
  • 保
  • 持
  • 同
  • 名
  • 接
  • 口
  • ？

风险

  • C
  • P
  • U
  • 基
  • 准
  • 脚
  • 本
  • 可
  • 能
  • 依
  • 赖
  • t
  • o
  • r
  • c
  • h
  • 特
  • 定
  • 版
  • 本
  • 或
  • C
  • P
  • U
  • 后
  • 端
  • 编
  • 译
  • 选
  • 项
  • ，
  • 需
  • 确
  • 认
  • A
  • p
  • p
  • l
  • e
  • S
  • i
  • l
  • i
  • c
  • o
  • n
  • 兼
  • 容
  • 性
任务 3可选 · low · Mac · 3–4 个晚上

[Tests] 添加 CPU vs CUDA int8 quant / layernorm 精度对照测试

Issue #60007 · [Bug]: TRITON_MLA is not batch invariant under chunked prefill with VLLM_BATCH_INVARIANT=1 (DeepSeek-V2-Lite, DeepSeek-V3.1) ↗

无人认领2 条评论bugdeepseek更新 2026-10-05

用到的专长：使用候选人在算子数值正确性、量化内核、精度验证方面的专长。

目标：在 tests/kernels/ 新增 test_cpu_quant.py 与 test_cpu_layernorm.py（均为新增），对比 CPU 与 CUDA 在相同输入下的 int8 量化与 layernorm 输出，确保数值一致（在合理容差内）。

为什么值得长期做：Issue #60007 涉及 batch invariance 在 chunked prefill 下的数值一致性，而 CPU 后端缺少与 CUDA 后端的精度对照测试是系统性缺口。csrc/cpu/dnnl_kernels.cpp 的 static/dynamic_scaled_int8_quant_impl 等量化内核无精度回归。这是纯测试 PR，不修改 kernel 实现，失败时仅暴露已有问题，不引入新 bug。

怎么介入：Issue #60007 聚焦 TRITON_MLA 的 batch invariance，但 CPU vs CUDA 精度对照是更通用的基础设施。在 Issue #60007 或 #27433 下评论确认是否欢迎纯测试 PR。
第一个 PR 的边界：第一个 PR 仅新增两个测试文件，不修改任何 kernel 实现；边界在 tests/kernels/ 下两个新文件。
第一步：阅读 tests/kernels/ 下现有 CUDA kernel 测试，理解测试框架、张量构造、断言方式。
本机怎么复现 / 验证：在 MacBook 上运行 pytest tests/kernels/test_cpu_quant.py 与 test_cpu_layernorm.py（新增），确认 CPU 端通过；在 Colab T4 上运行同一测试确认 CUDA 端对齐。
认领留言（英文，可直接贴到 Issue）
Hi, I'd like to add CPU vs CUDA precision regression tests for int8 quantization and layernorm in tests/kernels/. This would catch silent numerical drift between the two backends. I've checked csrc/cpu/dnnl_kernels.cpp and csrc/cpu/layernorm.cpp — both have Python-callable interfaces. My plan: add test_cpu_quant.py and test_cpu_layernorm.py that construct identical tensors, run both CPU and CUDA paths, and assert closeness within a reasonable tolerance. These are pure test PRs (no kernel changes), so failures only expose existing issues. Could you confirm if this is wanted and whether the CPU quant/layernorm Python entry points are stable? Draft PR in 3–4 days.
大致实施方案
  • 阅读 tests/kernels/ 下现有测试（如 test_quant.py、test_layernorm.py），理解 pytest 结构与 device 标记
  • 阅读 csrc/cpu/dnnl_kernels.cpp 与 csrc/cpu/layernorm.cpp，确定可调用的 Python 接口
  • 新增 tests/kernels/test_cpu_quant.py（新增），覆盖 int8 量化在不同 shape 下的 CPU vs CUDA 输出对比
  • 新增 tests/kernels/test_cpu_layernorm.py（新增），覆盖 layernorm 在不同 hidden_size / dtype 下的 CPU vs CUDA 输出对比
  • 在 MacBook 上运行两个测试文件，确认 CPU 端通过；在 Colab T4 上运行确认 CUDA 端对齐
可能涉及的目录或文件
  • tests/kernels/test_cpu_quant.py → 新增
  • tests/kernels/test_cpu_layernorm.py → 新增
  • 需先定位 CPU quant / layernorm 的 Python 入口（torch 算子或 vllm 自定义 op）
验收方式
  • 在
  • M
  • a
  • c
  • B
  • o
  • o
  • k
  • 上
  • 运
  • 行
  • p
  • y
  • t
  • e
  • s
  • t
  • t
  • e
  • s
  • t
  • s
  • /
  • k
  • e
  • r
  • n
  • e
  • l
  • s
  • /
  • t
  • e
  • s
  • t
  • _
  • c
  • p
  • u
  • _
  • q
  • u
  • a
  • n
  • t
  • .
  • p
  • y
  • 与
  • t
  • e
  • s
  • t
  • _
  • c
  • p
  • u
  • _
  • l
  • a
  • y
  • e
  • r
  • n
  • o
  • r
  • m
  • .
  • p
  • y
  • ，
  • 确
  • 认
  • C
  • P
  • U
  • 端
  • 通
  • 过
  • ；
  • 在
  • C
  • o
  • l
  • a
  • b
  • T
  • 4
  • 上
  • 运
  • 行
  • 同
  • 一
  • 测
  • 试
  • ，
  • 确
  • 认
  • C
  • U
  • D
  • A
  • 端
  • 对
  • 齐
  • 。
开工前问题与风险

向维护者确认

  • C
  • P
  • U
  • 端
  • i
  • n
  • t
  • 8
  • q
  • u
  • a
  • n
  • t
  • /
  • l
  • a
  • y
  • e
  • r
  • n
  • o
  • r
  • m
  • 的
  • P
  • y
  • t
  • h
  • o
  • n
  • 入
  • 口
  • 是
  • 否
  • 已
  • 暴
  • 露
  • ？
  • 还
  • 是
  • 需
  • 要
  • 先
  • 添
  • 加
  • t
  • o
  • r
  • c
  • h
  • b
  • i
  • n
  • d
  • i
  • n
  • g
  • ？

风险

  • C
  • P
  • U
  • 端
  • 可
  • 能
  • 缺
  • 少
  • 某
  • 些
  • q
  • u
  • a
  • n
  • t
  • 路
  • 径
  • 的
  • D
  • N
  • N
  • L
  • 实
  • 现
  • ，
  • 导
  • 致
  • 测
  • 试
  • 暴
  • 露
  • 已
  • 有
  • b
  • u
  • g
任务 4可选 · low · Mac · 2–3 个晚上

[Docs] 编写 Apple Silicon CPU 后端性能调优指南

Issue #59534 · [Performance]: FlashAttention backend rebuilds KV-cache views on every call (+~21 µs CPU/layer since #44455) ↗

无人认领2 条评论performance更新 2026-10-05

用到的专长：使用候选人在性能建模、roofline 分析、NEON 向量化方面的专长。

目标：在 docs/ 新增 cpu_performance.md（新增），记录 Apple Silicon 上的编译选项、NEON 路径、DNNL 后端选择、基准数据与常见调优参数。

为什么值得长期做：Issue #59534 涉及 CPU 侧 attention 性能（KV-cache view 重建开销），而 docs/ 中无 CPU 性能调优指南，README 也未提 Apple Silicon 支持细节。csrc/cpu/ 下已有 NEON 路径（cpu_attn_neon.hpp、cpu_tanhf_neon.hpp、cpu_micro_gemm_neon.hpp），但缺少文档与基准数据。这是无 GPU 环境下能直接交付、且形成差异化贡献的入口。

怎么介入：Issue #59534 聚焦 FlashAttention KV-cache view 重建，但 CPU 性能文档是更通用的缺口。在 Issue #59534 或 vLLM Slack 中确认文档需求。
第一个 PR 的边界：第一个 PR 仅新增 docs/cpu_performance.md，不修改任何代码；边界在 docs/ 下一个新文件。
第一步：阅读 docs/ 现有结构、csrc/cpu/ 下 NEON 相关文件、CMakeLists.txt 中的 CPU 编译选项。
本机怎么复现 / 验证：在 MacBook 上编译 vllm CPU 后端，运行 benchmarks/kernels/cpu/ 下脚本获取基准数据；运行 mkdocs serve 确认 docs/cpu_performance.md 渲染正常。
认领留言（英文，可直接贴到 Issue）
Hi, I noticed docs/ has no CPU backend performance guide, and README doesn't detail Apple Silicon support. Since I'm running vLLM on Apple Silicon (M-series, 16GB), I've measured the NEON paths in csrc/cpu/ (cpu_attn_neon.hpp, cpu_tanhf_neon.hpp, cpu_micro_gemm_neon.hpp) and can provide real benchmark data. I'd like to add docs/cpu_performance.md covering: build flags (-mcpu=apple-m1, DNNL options), NEON vs DNNL path selection, benchmark tables for cpu_attn/cpu_fused_moe/mamba_cpu, and common env vars. Could you confirm the preferred docs subdirectory and whether README should be updated too? Draft PR in 2–3 days.
大致实施方案
  • 阅读 docs/ 目录结构与现有性能相关文档（如 features/、getting_started/）
  • 阅读 csrc/cpu/cpu_attn_neon.hpp、cpu_attn_vec.hpp、cpu_tanhf_neon.hpp、micro_gemm/cpu_micro_gemm_neon.hpp，理解 NEON 路径的触发条件
  • 阅读 CMakeLists.txt 中与 CPU 后端相关的编译标志（-mcpu=apple-m1、DNNL 选项）
  • 在 MacBook 上实测 cpu_attn、cpu_fused_moe、mamba_cpu 的基准数据（利用现有 benchmarks/kernels/cpu/ 脚本）
  • 新增 docs/cpu_performance.md（新增），包含编译指南、NEON vs DNNL 选择、基准数据表、常见环境变量
可能涉及的目录或文件
  • docs/cpu_performance.md → 新增
  • 需先定位 docs/ 的导航结构（mkdocs.yaml 或 docs/ 下的 index）
验收方式
  • 在
  • M
  • a
  • c
  • B
  • o
  • o
  • k
  • 上
  • 实
  • 测
  • 文
  • 档
  • 中
  • 记
  • 录
  • 的
  • 基
  • 准
  • 数
  • 据
  • ，
  • 确
  • 保
  • 可
  • 复
  • 现
  • ；
  • 运
  • 行
  • m
  • k
  • d
  • o
  • c
  • s
  • s
  • e
  • r
  • v
  • e
  • 确
  • 认
  • 文
  • 档
  • 渲
  • 染
  • 正
  • 常
  • 。
开工前问题与风险

向维护者确认

  • 文
  • 档
  • 应
  • 放
  • 在
  • d
  • o
  • c
  • s
  • /
  • 哪
  • 个
  • 子
  • 目
  • 录
  • （
  • f
  • e
  • a
  • t
  • u
  • r
  • e
  • s
  • /
  • 、
  • g
  • e
  • t
  • t
  • i
  • n
  • g
  • _
  • s
  • t
  • a
  • r
  • t
  • e
  • d
  • /
  • 、
  • b
  • a
  • c
  • k
  • e
  • n
  • d
  • /
  • ）
  • ？
  • 是
  • 否
  • 需
  • 要
  • 同
  • 步
  • 更
  • 新
  • R
  • E
  • A
  • D
  • M
  • E
  • 中
  • 的
  • A
  • p
  • p
  • l
  • e
  • S
  • i
  • l
  • i
  • c
  • o
  • n
  • 提
  • 及
  • ？

风险

  • A
  • p
  • p
  • l
  • e
  • S
  • i
  • l
  • i
  • c
  • o
  • n
  • 编
  • 译
  • 选
  • 项
  • 可
  • 能
  • 随
  • X
  • c
  • o
  • d
  • e
  • /
  • C
  • M
  • a
  • k
  • e
  • 版
  • 本
  • 变
  • 化
  • ，
  • 需
  • 注
  • 明
  • 适
  • 用
  • 版
  • 本