{
"canonical_name": "vllm-project/vllm",
"compilation_id": "pack_33617b2964c44d61acaa2cb8a30952b2",
"created_at": "2026-05-11T10:23:03.758544+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install vllm` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install vllm",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_a8fc2042b8e04048814b1979ada31d97"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_4f6d0a7dcce7c7487f28bb5316a36395",
"canonical_name": "vllm-project/vllm",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/vllm-project/vllm",
"slug": "vllm",
"source_packet_id": "phit_e2df9faea8ea4118b6f56217c795e3bc",
"source_validation_id": "dval_4b19ac5ad26a41138863fa55543fb1f5"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 16729,
"github_stars": 79838,
"one_liner_en": "A high-throughput and memory-efficient inference and serving engine for LLMs",
"one_liner_zh": "A high-throughput and memory-efficient inference and serving engine for LLMs",
"primary_category": {
"category_id": "software-development",
"confidence": "high",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git, ci, cli"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "vllm",
"title_zh": "vllm 能力包",
"visible_tags": [
{
"label_en": "Knowledge Retrieval",
"label_zh": "知识检索",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-knowledge-retrieval",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Durable Memory",
"label_zh": "长期记忆",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-durable-memory",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Local-first",
"label_zh": "本地优先",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-local-first",
"type": "selection_signal"
}
]
},
"packet_id": "phit_e2df9faea8ea4118b6f56217c795e3bc",
"page_model": {
"artifacts": {
"artifact_slug": "vllm",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install vllm",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/vllm-project/vllm#readme",
"verified": true
}
],
"display_tags": [
"知识检索",
"知识库问答",
"长期记忆",
"节点式流程编排",
"本地优先"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "A high-throughput and memory-efficient inference and serving engine for LLMs"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Qwen3.5-397B-NVFP4 Disagg accuracy gsm8k collapses with async scheduling",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_1a71634c530044a68b9160080d55de0a | https://github.com/vllm-project/vllm/issues/42182 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[Bug]: Qwen3.5-397B-NVFP4 Disagg accuracy gsm8k collapses with async scheduling",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: vLLM v1 with prefix caching: first request differs from subsequent identical requests at temperature=0",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_58327949a4524ed082bd189b53f713a1 | https://github.com/vllm-project/vllm/issues/40896 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[Bug]: vLLM v1 with prefix caching: first request differs from subsequent identical requests at temperature=0",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Usage]: How to proactively clear CPU-resident memory left behind by unloaded LoRA adapters after calling `/v1/unload_lora_adapter`?",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_fb1461834fe34049bd05182574d3e5e5 | https://github.com/vllm-project/vllm/issues/42207 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[Usage]: How to proactively clear CPU-resident memory left behind by unloaded LoRA adapters after calling `/v1/unload_l…",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.18.1",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_317a03f9de4e459f9be42064c7318b2c | https://github.com/vllm-project/vllm/releases/tag/v0.18.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.18.1",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：[Feature]: Qwen3.5-Moe LoRA Support (experts)",
"category": "能力坑",
"evidence": [
"community_evidence:github | cevd_2d068d43c6654f3cab6b48bf98dad116 | https://github.com/vllm-project/vllm/issues/40005 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[Feature]: Qwen3.5-Moe LoRA Support (experts)",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:599547518 | https://github.com/vllm-project/vllm | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.20.2",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_ecf37722dff6494c82b384225e34bcb0 | https://github.com/vllm-project/vllm/releases/tag/v0.20.2 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.20.2",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:599547518 | https://github.com/vllm-project/vllm | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:599547518 | https://github.com/vllm-project/vllm | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "No sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"risks.safety_notes | github_repo:599547518 | https://github.com/vllm-project/vllm | No sandbox install has been executed yet; downstream must verify before user use."
],
"severity": "medium",
"suggested_check": "转成明确权限清单和安全审查提示。",
"title": "存在安全注意事项",
"user_impact": "用户安装前需要知道权限边界和敏感操作。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:599547518 | https://github.com/vllm-project/vllm | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: ngram speculative decoding changes greedy output on Qwen3-0.6B / A100",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_9ce279a037934e8085332120bfdaca86 | https://github.com/vllm-project/vllm/issues/41758 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[Bug]: ngram speculative decoding changes greedy output on Qwen3-0.6B / A100",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.16.0",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_57ff11ff995a4809a33a38ff7504a5ef | https://github.com/vllm-project/vllm/releases/tag/v0.16.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.16.0",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.17.0",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_4592ced4fde24aa9aa808caa40e25b84 | https://github.com/vllm-project/vllm/releases/tag/v0.17.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.17.0",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.18.0",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_7ca09904f8164e94a3a1bc489d32d1ff | https://github.com/vllm-project/vllm/releases/tag/v0.18.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.18.0",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.19.0",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_cdb0d7a7f491474da7b93583ec643c00 | https://github.com/vllm-project/vllm/releases/tag/v0.19.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.19.0",
"user_impact": "可能影响授权、密钥配置或安全边界。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 21 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: Qwen3.5-397B-NVFP4 Disagg accuracy gsm8k collapses with async scheduling。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 2623,
"forks": 16729,
"license": "unknown",
"note": "GitHub API 快照，非实时质量证明；用于开工前背景判断。",
"stars": 79838,
"open_issues": 4941,
"pushed_at": null
},
"source_url": "https://github.com/vllm-project/vllm",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "A high-throughput and memory-efficient inference and serving engine for LLMs",
"title": "vllm 能力包",
"trial_prompt": "# vllm - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 vllm 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: A high-throughput and memory-efficient inference and serving engine for LLMs 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 暂无明确的运行时能力线索。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-intro：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装指南。围绕“安装指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-arch-overview：架构概览。围绕“架构概览”模拟一次用户任务，不展示安装或运行结果。\n4. page-v1-engine：V1 引擎架构。围绕“V1 引擎架构”模拟一次用户任务，不展示安装或运行结果。\n5. page-paged-attention：PagedAttention 与 KV 缓存管理。围绕“PagedAttention 与 KV 缓存管理”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-intro\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-arch-overview\n输入：用户提供的“架构概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-v1-engine\n输入：用户提供的“V1 引擎架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-paged-attention\n输入：用户提供的“PagedAttention 与 KV 缓存管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-intro：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-arch-overview：Step 3 必须围绕“架构概览”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-v1-engine：Step 4 必须围绕“V1 引擎架构”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-paged-attention：Step 5 必须围绕“PagedAttention 与 KV 缓存管理”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/vllm-project/vllm\n- https://github.com/vllm-project/vllm#readme\n- README.md\n- vllm/__init__.py\n- vllm/version.py\n- setup.py\n- docs/getting_started/installation/README.md\n- requirements/common.txt\n- requirements/cuda.txt\n- docs/design/arch_overview.md\n- vllm/engine/llm_engine.py\n- vllm/engine/arg_utils.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 vllm 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: [Bug]: vLLM v1 with prefix caching: first request differs from subsequen（https://github.com/vllm-project/vllm/issues/40896）；github/github_issue: [AMD][CI Failure][Tracker] Static dashboard tracker for current CI failu（https://github.com/vllm-project/vllm/issues/40554）；github/github_issue: [Usage]: How to proactively clear CPU-resident memory left behind by unl（https://github.com/vllm-project/vllm/issues/42207）；github/github_issue: [Feature]: Qwen3.5-Moe LoRA Support (experts)（https://github.com/vllm-project/vllm/issues/40005）；github/github_issue: [Bug]: ngram speculative decoding changes greedy output on Qwen3-0.6B / （https://github.com/vllm-project/vllm/issues/41758）；github/github_issue: [Bug]: Qwen3.5-397B-NVFP4 Disagg accuracy gsm8k collapses with async sch（https://github.com/vllm-project/vllm/issues/42182）；github/github_release: v0.20.2（https://github.com/vllm-project/vllm/releases/tag/v0.20.2）；github/github_release: v0.20.1（https://github.com/vllm-project/vllm/releases/tag/v0.20.1）；github/github_release: v0.20.0（https://github.com/vllm-project/vllm/releases/tag/v0.20.0）；github/github_release: v0.19.1（https://github.com/vllm-project/vllm/releases/tag/v0.19.1）；github/github_release: v0.19.0（https://github.com/vllm-project/vllm/releases/tag/v0.19.0）；github/github_release: v0.18.1（https://github.com/vllm-project/vllm/releases/tag/v0.18.1）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "[Bug]: vLLM v1 with prefix caching: first request differs from subsequen",
"url": "https://github.com/vllm-project/vllm/issues/40896"
},
{
"kind": "github_issue",
"source": "github",
"title": "[AMD][CI Failure][Tracker] Static dashboard tracker for current CI failu",
"url": "https://github.com/vllm-project/vllm/issues/40554"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Usage]: How to proactively clear CPU-resident memory left behind by unl",
"url": "https://github.com/vllm-project/vllm/issues/42207"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Feature]: Qwen3.5-Moe LoRA Support (experts)",
"url": "https://github.com/vllm-project/vllm/issues/40005"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Bug]: ngram speculative decoding changes greedy output on Qwen3-0.6B / ",
"url": "https://github.com/vllm-project/vllm/issues/41758"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Bug]: Qwen3.5-397B-NVFP4 Disagg accuracy gsm8k collapses with async sch",
"url": "https://github.com/vllm-project/vllm/issues/42182"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.20.2",
"url": "https://github.com/vllm-project/vllm/releases/tag/v0.20.2"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.20.1",
"url": "https://github.com/vllm-project/vllm/releases/tag/v0.20.1"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.20.0",
"url": "https://github.com/vllm-project/vllm/releases/tag/v0.20.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.19.1",
"url": "https://github.com/vllm-project/vllm/releases/tag/v0.19.1"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.19.0",
"url": "https://github.com/vllm-project/vllm/releases/tag/v0.19.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.18.1",
"url": "https://github.com/vllm-project/vllm/releases/tag/v0.18.1"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "A high-throughput and memory-efficient inference and serving engine for LLMs",
"effort": "安装已验证",
"forks": 16624,
"icon": "code",
"name": "vllm 能力包",
"risk": "可发布",
"slug": "vllm",
"stars": 79560,
"tags": [
"知识检索",
"知识库问答",
"长期记忆",
"节点式流程编排",
"本地优先"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/vllm-project/vllm 项目说明书\n\n生成时间：2026-05-11 03:40:03 UTC\n\n## 目录\n\n- [项目介绍](#page-intro)\n- [安装指南](#page-installation)\n- [架构概览](#page-arch-overview)\n- [V1 引擎架构](#page-v1-engine)\n- [引擎核心模块](#page-engine-core)\n- [PagedAttention 与 KV 缓存管理](#page-paged-attention)\n- [注意力后端](#page-attention-backends)\n- [量化支持](#page-quantization)\n- [推测解码](#page-speculative-decoding)\n- [分布式并行策略](#page-parallelism)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[安装指南](#page-installation), [架构概览](#page-arch-overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/vllm-project/vllm/blob/main/README.md)\n- [vllm/__init__.py](https://github.com/vllm-project/vllm/blob/main/vllm/__init__.py)\n- [vllm/version.py](https://github.com/vllm-project/vllm/blob/main/vllm/version.py)\n- [vllm/engine/arg_utils.py](https://github.com/vllm-project/vllm/blob/main/vllm/engine/arg_utils.py)\n- [vllm/config.py](https://github.com/vllm-project/vllm/blob/main/vllm/config.py)\n- [vllm/entrypoints/llm.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/llm.py)\n- [setup.py](https://github.com/vllm-project/vllm/blob/main/setup.py)\n \n\n# 项目介绍\n\n## 1 项目概述\n\nvLLM（Vectorized Large Language Model）是一个高性能、易于使用的**大语言模型推理和服务框架**，旨在提供高吞吐量的 LLM 推理能力。vLLM 由 UC Berkeley、UC San Diego、University of Illinois 等知名学术机构的研究人员开发和维护，是开源社区中用于生产环境 LLM 部署的主流选择之一。\n\nvLLM 的核心目标是解决大语言模型推理过程中的**内存管理效率问题**，通过创新的 PagedAttention 技术实现 KV Cache 的高效管理，从而在有限的 GPU 显存资源下实现更高的吞吐量。资料来源：[README.md:1-20]()\n\n### 1.1 核心价值主张\n\n| 特性 | 描述 |\n|------|------|\n| 高吞吐量 | 相比传统方法提升 2-24 倍的吞吐量 |\n| 显存高效 | 通过 PagedAttention 实现精细化的显存管理 |\n| 易用性 | 提供简洁的 Python API 和 OpenAI 兼容接口 |\n| 灵活扩展 | 支持张量并行、管道并行等多种分布式策略 |\n| 广泛兼容 | 支持众多主流开源大语言模型 |\n\n### 1.2 版本信息\n\n当前稳定版本信息定义在 `vllm/version.py` 中，用于标识 vLLM 的发布版本号，便于依赖管理和版本追踪。资料来源：[vllm/version.py:1-15]()\n\n## 2 技术架构\n\n### 2.1 整体架构概览\n\nvLLM 采用分层架构设计，从上到下分为以下几个核心层次：\n\n```mermaid\ngraph TD\n A[用户接口层] --> B[LLM 入口层]\n B --> C[推理引擎层]\n C --> D[模型执行层]\n D --> E[设备抽象层]\n \n A --> A1[OpenAI 兼容 API]\n A --> A2[Python API]\n \n C --> C1[Engine Arguments]\n C --> C2[Engine Core]\n C --> C3[Async Engine]\n \n D --> D1[Model Runner]\n D --> D2[Worker]\n D --> D3[Cache Engine]\n \n E --> E1[CUDA]\n E --> E2[ROCm]\n E --> E3[CPU]\n```\n\n### 2.2 核心模块结构\n\n`vllm/__init__.py` 文件定义了包的主要导出接口，展示了 vLLM 的模块组织方式：\n\n| 模块路径 | 功能描述 |\n|----------|----------|\n| `vllm.LLM` | 主要的推理入口类 |\n| `vllm.SamplingParams` | 采样参数配置 |\n| `vllm.engine` | 推理引擎核心实现 |\n| `vllm.worker` | 模型执行工作进程 |\n| `vllm.model_executor` | 模型执行器 |\n| `vllm.config` | 配置管理 |\n| `vllm.attention` | 注意力机制实现 |\n\n资料来源：[vllm/__init__.py:1-50]()\n\n### 2.3 推理引擎架构\n\n推理引擎是 vLLM 的核心组件，负责协调整个推理流程：\n\n```mermaid\ngraph LR\n A[用户请求] --> B[Engine Arguments]\n B --> C[LLMEngine]\n C --> D[Worker Pool]\n D --> E[Model Runner]\n E --> F[Model]\n F --> G[Output]\n \n C --> H[Cache Engine]\n H --> I[KV Cache]\n \n style G fill:#90EE90\n style I fill:#87CEEB\n```\n\n**Engine Arguments** 负责解析和验证所有推理相关的配置参数，包括模型路径、采样参数、资源配置等。资料来源：[vllm/engine/arg_utils.py:1-100]()\n\n**Configuration** 模块则统一管理 vLLM 的各类配置，包括模型配置、并行配置、调度配置等，确保各组件之间的配置一致性。资料来源：[vllm/config.py:1-150]()\n\n## 3 主要功能特性\n\n### 3.1 PagedAttention\n\nPagedAttention 是 vLLM 最核心的技术创新，灵感来自操作系统的虚拟内存管理思想。它通过将 KV Cache 分页管理，避免了传统方法中连续显存分配带来的浪费问题。\n\n```mermaid\ngraph LR\n A[传统方法] -->|连续分配| B[显存碎片化]\n B --> C[显存利用率低]\n \n D[PagedAttention] -->|分页管理| E[灵活分配]\n E --> F[显存利用率高]\n \n style D fill:#90EE90\n```\n\n**技术优势：**\n\n- 将显存利用率提升至接近 100%\n- 支持高效的Prefix Caching\n- 减少显存碎片化\n- 支持弹性批处理\n\n### 3.2 并行推理策略\n\nvLLM 支持多种分布式推理策略，可以根据硬件配置灵活选择：\n\n| 并行策略 | 适用场景 | 配置参数 |\n|----------|----------|----------|\n| 张量并行 (TP) | 单机多卡 | `tensor_parallel_size` |\n| 管道并行 (PP) | 多机多卡 | `pipeline_parallel_size` |\n| 数据并行 (DP) | 多实例部署 | 启动多个进程 |\n| 专家并行 (EP) | MoE 模型 | `enable_expert_parallel` |\n\n### 3.3 模型支持\n\nvLLM 支持众多主流的开源大语言模型，涵盖以下类别：\n\n| 模型类别 | 代表模型 |\n|----------|----------|\n| Decoder-Only | Llama, GPT, Mistral, Qwen |\n| Encoder-Decoder | T5, BART |\n| 视觉语言模型 | LLaVA, Qwen-VL |\n| Mixture of Experts | Mixtral |\n\n资料来源：[setup.py:1-50]()\n\n### 3.4 推理接口\n\nvLLM 提供两类主要的推理接口：\n\n**Python API（同步）：**\n\n```python\nfrom vllm import LLM, SamplingParams\n\nllm = LLM(model=\"meta-llama/Llama-2-7b-hf\")\noutputs = llm.generate([\"Hello, world!\"], SamplingParams(temperature=0.8))\n```\n\n**异步 API：**\n\n```python\nfrom vllm import AsyncLLM\n\nasync_llm = AsyncLLM(model=\"meta-llama/Llama-2-7b-hf\")\n```\n\n**OpenAI 兼容 API：**\n\nvLLM 提供与 OpenAI API 格式完全兼容的推理服务，支持 `/v1/chat/completions` 和 `/v1/completions` 端点，便于现有应用无缝迁移。\n\n资料来源：[vllm/entrypoints/llm.py:1-100]()\n\n## 4 应用场景\n\n### 4.1 典型使用场景\n\n```mermaid\ngraph TD\n A[vLLM 部署场景] --> B[在线推理服务]\n A --> C[批量推理任务]\n A --> D[实验研究]\n A --> E[模型微调验证]\n \n B --> B1[低延迟响应]\n C --> C1[高吞吐处理]\n D --> D1[快速迭代]\n E --> E1[资源高效利用]\n```\n\n### 4.2 部署模式\n\n| 部署模式 | 特点 | 推荐配置 |\n|----------|------|----------|\n| 单机单卡 | 简单部署 | 默认配置 |\n| 单机多卡 | 高效利用 | TP=2/4/8 |\n| 多机多卡 | 大模型推理 | TP+PP |\n| 容器化部署 | 便于运维 | Docker/Kubernetes |\n\n## 5 依赖技术栈\n\n### 5.1 核心依赖\n\n| 依赖库 | 用途 |\n|--------|------|\n| PyTorch | 深度学习框架 |\n| CUDA | GPU 计算 |\n| transformers | 模型加载 |\n| flash-attn | 高效注意力计算 |\n| ray | 分布式计算 |\n\n### 5.2 硬件要求\n\n- **GPU**: NVIDIA GPU（CUDA 计算能力 ≥ 7.0）\n- **显存**: 取决于模型大小，通常至少 16GB\n- **内存**: 至少 32GB 系统内存\n- **存储**: 足够的模型权重存储空间\n\n## 6 项目发展\n\n### 6.1 发展历程\n\nvLLM 项目起源于学术研究，最初由 UC Berkeley 的研究人员提出 PagedAttention 概念，并在论文中展示了其优越性能。随着开源社区的积极参与，vLLM 逐步发展成为功能完善、性能卓越的生产级推理框架。\n\n### 6.2 社区生态\n\nvLLM 采用 Apache License 2.0 开源许可，拥有活跃的开源社区。项目持续接收来自全球开发者的贡献，不断添加新功能和优化性能。\n\n---\n\n**总结**：vLLM 是一个专为大规模语言模型设计的生产级推理框架，通过创新的 PagedAttention 技术显著提升了推理效率和显存利用率。其简洁的 API 设计、丰富的模型支持和灵活的部署方式，使其成为当前最流行的 LLM 推理框架之一。\n\n---\n\n\n\n## 安装指南\n\n### 相关页面\n\n相关主题：[项目介绍](#page-intro)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/vllm-project/vllm/blob/main/README.md)\n- [vllm/entrypoints/cli/main.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/main.py)\n- [vllm/entrypoints/cli/serve.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/serve.py)\n- [vllm/entrypoints/cli/launch.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/launch.py)\n- [examples/basic/offline_inference/README.md](https://github.com/vllm-project/vllm/blob/main/examples/basic/offline_inference/README.md)\n \n\n# 安装指南\n\n## 概述\n\nvLLM 是一个高性能的大语言模型（LLM）推理和服务框架，旨在为用户提供快速、经济高效的 LLM 服务。本页面详细介绍 vLLM 的安装方法、依赖要求、环境配置以及各种部署场景的安装步骤。\n\nvLLM 支持多种安装方式，包括 pip 安装、Docker 部署、源码编译等。用户可以根据自己的硬件环境（CUDA GPU、CPU 等）选择最适合的安装方式。框架采用模块化设计，通过灵活的参数配置支持不同的推理场景。\n\n## 系统要求\n\n### 硬件要求\n\n| 组件类型 | 最低要求 | 推荐配置 |\n|---------|---------|---------|\n| GPU | NVIDIA GPU with CUDA support | NVIDIA A100/H100 |\n| 显存 | 8GB | 24GB+ |\n| 内存 | 16GB | 32GB+ |\n| 存储 | 50GB SSD | 100GB+ NVMe SSD |\n\n### 软件环境\n\nvLLM 支持多种 Python 版本和 CUDA 版本。安装前请确保系统已安装以下软件：\n\n- Python 3.8 - 3.11\n- CUDA Toolkit 11.8 或更高版本\n- cuDNN 8.x 或更高版本\n- NVIDIA Driver 450.80.02 或更高版本\n\n## 安装方式\n\n### 方式一：使用 pip 安装（推荐）\n\n使用 pip 是最简单快速的安装方式，适合大多数用户场景。\n\n```bash\n# 标准安装\npip install vllm\n\n# 包含所有可选依赖的完整安装\npip install vllm[all]\n```\n\npip 安装方式会自动处理 vLLM 的核心依赖，包括 PyTorch、Transformers 等关键库。此方式适合快速原型开发和测试环境部署。\n\n### 方式二：Docker 安装\n\nDocker 安装提供了隔离的运行环境，可以避免依赖冲突问题。vLLM 官方提供了预配置好的 Docker 镜像。\n\n```bash\n# 拉取最新稳定版镜像\ndocker pull vllm/vllm:latest\n\n# 运行容器\ndocker run --gpus all \\\n -v ~/.cache/huggingface:/root/.cache/huggingface \\\n --runtime nvidia \\\n -p 8000:8000 \\\n vllm/vllm:latest \\\n --model meta-llama/Llama-2-7b-hf\n```\n\n资料来源：[README.md:1-15]()\n\nDocker 部署的优势在于环境一致性高，部署迁移方便，适合生产环境使用。镜像已预装所有必要的 CUDA 驱动和依赖库。\n\n### 方式三：源码编译安装\n\n对于需要自定义配置或参与 vLLM 开发的用户，可以选择源码编译安装。\n\n```bash\n# 克隆仓库\ngit clone https://github.com/vllm-project/vllm.git\ncd vllm\n\n# 安装依赖\npip install -e .\n\n# 或使用高级构建选项\npip install -e . --verbose\n```\n\n资料来源：[vllm/entrypoints/cli/main.py:1-30]()\n\n## CLI 命令行工具\n\nvLLM 提供了功能丰富的命令行界面（CLI），通过 `vllm` 命令可以访问各种子命令。CLI 架构采用模块化设计，支持扩展新的命令。\n\n```mermaid\ngraph TD\n A[vllm CLI] --> B[main.py 入口]\n B --> C[serve 推理服务]\n B --> D[run-batch 批处理]\n B --> E[launch 启动组件]\n C --> F[FastAPI 服务]\n C --> G[gRPC 服务]\n E --> H[FastAPI 渲染服务]\n```\n\n### 基本用法\n\n```bash\n# 查看版本信息\nvllm --version\n\n# 查看帮助信息\nvllm --help\n\n# 查看特定子命令帮助\nvllm serve --help\n```\n\n### serve 子命令\n\n`serve` 子命令用于启动 LLM 推理服务，是最常用的命令之一。\n\n```bash\nvllm serve Qwen/Qwen2.5-3B-Instruct\n```\n\n资料来源：[vllm/entrypoints/cli/serve.py:1-50]()\n\n#### 常用参数\n\n| 参数 | 说明 | 默认值 |\n|-----|------|-------|\n| `--model` | 模型名称或本地路径 | Qwen/Qwen3-0.6B |\n| `--host` | 服务监听地址 | 0.0.0.0 |\n| `--port` | 服务监听端口 | 8000 |\n| `--gpu-memory-utilization` | GPU 显存利用率 | 0.9 |\n| `--max-model-len` | 最大模型上下文长度 | 模型默认值 |\n| `--tensor-parallel-size` | 张量并行大小 | 1 |\n\n#### headless 模式\n\nheadless 模式启动时不会创建 API 服务器，适用于分布式部署场景。\n\n```bash\nvllm serve --headless\n```\n\n在此模式下，`api_server_count` 参数自动设为 0，不启动任何 API 服务器。\n\n```bash\n# 错误用法：headless 模式不能指定 api-server-count\nvllm serve --headless --api-server-count=2\n```\n\n此配置会触发参数校验错误，提示 headless 模式与 api-server-count 参数冲突。\n\n#### gRPC 服务模式\n\nvLLM 支持 gRPC 协议用于高性能内部通信。\n\n```bash\nvllm serve --grpc\n```\n\n启用 gRPC 模式时，框架会使用 uvloop 事件循环运行 gRPC 服务器。\n\n```python\nif args.grpc:\n from vllm.entrypoints.grpc_server import serve_grpc\n uvloop.run(serve_grpc(args))\n return\n```\n\n资料来源：[vllm/entrypoints/cli/serve.py:40-45]()\n\n### launch 子命令\n\n`launch` 子命令用于启动独立的组件服务。\n\n```bash\nvllm launch [options]\n```\n\n可用的组件包括：\n\n- `fastapi`：启动 FastAPI 渲染服务（无 GPU 推理）\n- 其他可扩展组件\n\n#### FastAPI 组件启动\n\n```bash\nvllm launch fastapi --host 0.0.0.0 --port 8000\n```\n\n启动流程包括以下步骤：\n\n1. **Socket 绑定**：设置服务器监听地址\n2. **构建引擎参数**：从 CLI 参数创建 AsyncEngineArgs\n3. **创建模型配置**：生成 VllmConfig 配置对象\n4. **清除量化配置**：渲染服务器不执行推理，跳过量化验证\n\n```python\nasync def run_launch_fastapi(args: argparse.Namespace) -> None:\n listen_address, sock = setup_server(args)\n engine_args = AsyncEngineArgs.from_cli_args(args)\n model_config = engine_args.create_model_config()\n model_config.quantization = None\n```\n\n资料来源：[vllm/entrypoints/cli/launch.py:60-80]()\n\n## 离线推理安装\n\nvLLM 提供了 `LLM` 类用于离线推理，即不启动独立服务器直接进行模型推理。\n\n```python\nfrom vllm import LLM\n\nllm = LLM(model=\"Qwen/Qwen2.5-3B-Instruct\")\noutputs = llm.generate(\"Hello, world!\")\n```\n\n### 基本使用示例\n\nvLLM 仓库提供了完整的离线推理示例脚本：\n\n```bash\n# 基础推理示例\npython examples/basic/offline_inference/basic.py\n\n# 聊天示例\npython examples/basic/offline_inference/chat.py\n\n# 生成示例\npython examples/basic/offline_inference/generate.py\n```\n\n资料来源：[examples/basic/offline_inference/README.md:1-30]()\n\n### 生成参数配置\n\n离线推理支持多种采样参数，可通过命令行或代码配置：\n\n| 参数 | 说明 | 示例值 |\n|-----|------|-------|\n| `max_tokens` | 最大生成 token 数 | 512 |\n| `temperature` | 采样温度 | 0.7 |\n| `top_p` | Top-p 采样阈值 | 0.9 |\n| `top_k` | Top-k 采样大小 | 50 |\n\n### 默认生成配置\n\n`--generation-config` 参数指定生成配置的加载来源：\n\n```bash\npython examples/basic/offline_inference/generate.py --generation-config auto\n```\n\n- `auto`：从模型路径加载配置\n- 文件夹路径：从指定路径加载配置\n- 未指定：使用 vLLM 默认配置\n\n> 注意：如果生成配置中指定了 `max_new_tokens`，则该值会对所有请求设置全局输出 token 限制。\n\n## GGUF 模型支持\n\nvLLM 支持加载 GGUF 量化格式的模型。使用 `repo_id:quant_type` 格式指定量化类型：\n\n```bash\n--model unsloth/Qwen3-0.6B-GGUF:Q4_K_M --tokenizer Qwen/Qwen3-0.6B\n```\n\n支持的量化类型包括 Q2_K、Q4_K_M、Q5_K_M、Q8_0 等。\n\n## CPU 卸载功能\n\nvLLM 支持 CPU 显存卸载功能，可以将部分模型权重卸载到 CPU 内存，从而在有限 GPU 显存条件下运行更大的模型。\n\n```bash\n--cpu-offload-gb 10\n```\n\n此参数可以视为增加虚拟 GPU 显存大小。例如，拥有 24GB GPU 显存并设置 `--cpu-offload-gb 10` 后，相当于拥有 34GB 显存，可以加载需要至少 26GB 显存的 13B BF16 模型。\n\n> 注意：此功能需要快速的 CPU-GPU 互联带宽，因为模型需要在运行时从 CPU 内存加载到 GPU 内存。\n\n## 验证安装\n\n安装完成后，可通过以下方式验证 vLLM 是否正常工作：\n\n```bash\n# 检查 vLLM 版本\npython -c \"import vllm; print(vllm.__version__)\"\n\n# 运行基础测试\npython -c \"\nfrom vllm import LLM\nllm = LLM(model='facebook/opt-125m')\nprint('vLLM 安装成功！')\n\"\n```\n\n## 常见问题排查\n\n### CUDA 版本不兼容\n\n如果遇到 CUDA 版本相关错误，请检查系统 CUDA 版本：\n\n```bash\nnvcc --version\n```\n\n确保 CUDA 版本符合 vLLM 的要求（CUDA 11.8+）。\n\n### GPU 显存不足\n\n- 减小 `--gpu-memory-utilization` 参数值\n- 使用更小的量化模型\n- 启用 CPU 卸载功能\n\n### 依赖冲突\n\n推荐使用虚拟环境安装 vLLM：\n\n```bash\npython -m venv vllm-env\nsource vllm-env/bin/activate\npip install vllm\n```\n\n## 下一步\n\n安装完成后，您可以：\n\n- [快速开始](quickstart.md) - 运行您的第一个 vLLM 推理\n- [服务部署](serving.md) - 启动在线推理服务\n- [API 参考](../api/) - 了解详细的 API 接口\n- [示例代码](../examples/) - 探索更多使用示例\n\n---\n\n\n\n## 架构概览\n\n### 相关页面\n\n相关主题：[V1 引擎架构](#page-v1-engine), [引擎核心模块](#page-engine-core)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [vllm/entrypoints/cli/main.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/main.py)\n- [vllm/entrypoints/cli/serve.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/serve.py)\n- [vllm/entrypoints/cli/launch.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/launch.py)\n- [vllm/engine/llm_engine.py](https://github.com/vllm-project/vllm/blob/main/vllm/engine/llm_engine.py)\n- [vllm/engine/arg_utils.py](https://github.com/vllm-project/vllm/blob/main/vllm/engine/arg_utils.py)\n- [examples/disaggregated/example_connector/README.md](https://github.com/vllm-project/vllm/blob/main/examples/disaggregated/example_connector/README.md)\n- [examples/basic/offline_inference/README.md](https://github.com/vllm-project/vllm/blob/main/examples/basic/offline_inference/README.md)\n- [examples/observability/opentelemetry/README.md](https://github.com/vllm-project/vllm/blob/main/examples/observability/opentelemetry/README.md)\n \n\n# 架构概览\n\nvLLM 是一个高效、易用、低成本的大语言模型（LLM）推理服务框架，其核心设计目标是通过创新的 PagedAttention 技术实现高效的显存管理和快速推理服务。本文档详细介绍 vLLM 的整体架构设计、核心组件及其交互关系。\n\n## 系统架构总览\n\nvLLM 采用分层架构设计，从上到下依次为：命令行入口层、服务接口层、引擎核心层和硬件适配层。这种分层设计使得各模块职责明确，便于扩展和维护。\n\n```mermaid\ngraph TD\n subgraph \"用户接口层\"\n CLI[CLI 命令行]\n API[OpenAI 兼容 API]\n Python[Python LLM 类]\n end\n \n subgraph \"服务层\"\n FastAPI[FastAPI 服务器]\n GRPC[gRPC 服务]\n Launch[Launch 组件]\n end\n \n subgraph \"引擎核心层\"\n LLMEngine[LLM Engine]\n Scheduler[调度器]\n ModelRunner[模型运行器]\n end\n \n subgraph \"硬件适配层\"\n GPU[GPU 平台]\n CPU[CPU 平台]\n Quantization[量化处理]\n end\n \n CLI --> FastAPI\n API --> FastAPI\n Python --> LLMEngine\n FastAPI --> LLMEngine\n GRPC --> LLMEngine\n Launch --> FastAPI\n LLMEngine --> Scheduler\n LLMEngine --> ModelRunner\n Scheduler --> GPU\n Scheduler --> CPU\n ModelRunner --> Quantization\n```\n\n## 命令行入口架构\n\nvLLM 提供了功能丰富的命令行接口（CLI），支持多种子命令以满足不同的使用场景。CLI 架构基于灵活的命令注册机制，各子命令模块化设计，便于扩展。\n\n### 主入口模块\n\n主入口模块位于 `vllm/entrypoints/cli/main.py`，负责整体命令行解析和命令分发：\n\n```python\n# vllm/entrypoints/cli/main.py (伪代码示例)\nparser = FlexibleArgumentParser(description=\"vLLM CLI\")\nsubparsers = parser.add_subparsers(required=False, dest=\"subparser\")\ncmds = {}\nfor cmd_module in CMD_MODULES:\n new_cmds = cmd_module.cmd_init()\n for cmd in new_cmds:\n cmd.subparser_init(subparsers).set_defaults(dispatch_function=cmd.cmd)\n cmds[cmd.name] = cmd\n```\n\n### CLI 命令体系\n\n| 命令名称 | 模块路径 | 功能说明 |\n|---------|---------|---------|\n| `serve` | `vllm/entrypoints/cli/serve.py` | 启动 HTTP API 服务器进行在线推理服务 |\n| `launch` | `vllm/entrypoints/cli/launch.py` | 启动特定组件服务（如渲染服务器） |\n| 其他命令 | 各子模块 | 通过动态加载注册 |\n\nCLI 命令初始化流程通过 `cmd_init()` 函数返回命令列表，实现动态注册机制。资料来源：[vllm/entrypoints/cli/main.py:1-40]()\n\n## 核心引擎架构\n\nLLM Engine 是 vLLM 的核心组件，负责管理模型加载、请求调度、KV 缓存管理和推理执行。引擎支持同步和异步两种运行模式。\n\n### 引擎参数配置\n\n引擎参数通过 `AsyncEngineArgs` 类进行统一管理，该类封装了所有可配置的引擎参数：\n\n```python\n# 引擎参数示例配置\nengine_args = AsyncEngineArgs.from_cli_args(args)\nmodel_config = engine_args.create_model_config()\n```\n\n关键配置参数包括：\n\n| 参数类别 | 参数名 | 说明 |\n|---------|-------|------|\n| 模型配置 | `model` | 模型名称或路径 |\n| 模型配置 | `tokenizer` | 分词器路径 |\n| 模型配置 | `trust_remote_code` | 是否信任远程代码 |\n| 推理配置 | `tensor_size` | 张量并行数 |\n| 推理配置 | `gpu_memory_utilization` | GPU 显存利用率 |\n| 推理配置 | `max_model_len` | 最大模型长度 |\n| 量化配置 | `quantization` | 量化方法（如 AWQ、GPTQ） |\n| 服务配置 | `api_server_count` | API 服务器实例数量 |\n\n资料来源：[vllm/engine/arg_utils.py](https://github.com/vllm-project/vllm/blob/main/vllm/engine/arg_utils.py)\n\n### 服务启动模式\n\nvLLM 支持多种服务启动模式，以适应不同的部署场景：\n\n```mermaid\ngraph LR\n A[CLI 启动] --> B{检查参数}\n B -->|grpc=True| C[gRPC 服务模式]\n B -->|headless=True| D[无头模式
api_server_count=0]\n B -->|标准参数| E[FastAPI 服务模式]\n \n C --> F[uvloop 事件循环]\n D --> G[仅引擎运行]\n E --> H[FastAPI + Uvicorn]\n```\n\n#### 标准服务模式\n\n标准模式通过 FastAPI 提供 OpenAI 兼容的 HTTP API 服务：\n\n```python\n# vllm/entrypoints/cli/serve.py\nfrom vllm.entrypoints.grpc_server import serve_grpc\n\nif args.headless:\n if args.api_server_count is not None and args.api_server_count > 0:\n raise ValueError(\n f\"--api-server-count={args.api_server_count} cannot be \"\n \"used with --headless\"\n )\n args.api_server_count = 0\n```\n\n#### 无头模式（Headless）\n\n无头模式下不启动任何 API 服务器，仅运行推理引擎，适用于程序化调用场景：\n\n- `api_server_count` 强制设为 0\n- 适合批处理作业\n- 减少资源开销\n\n资料来源：[vllm/entrypoints/cli/serve.py:1-50]()\n\n#### Launch 组件模式\n\nLaunch 模式用于启动特定功能组件，如渲染服务器：\n\n```python\n# vllm/entrypoints/cli/launch.py\nasync def run_launch_fastapi(args: argparse.Namespace) -> None:\n \"\"\"运行在线服务层（无 GPU 推理）\"\"\"\n listen_address, sock = setup_server(args)\n engine_args = AsyncEngineArgs.from_cli_args(args)\n model_config = engine_args.create_model_config()\n```\n\nLaunch 模式的特点：\n\n- 仅进行数据预处理，不执行模型推理\n- 清除量化配置以跳过量化数据类型验证\n- 不分配 KV 缓存\n\n资料来源：[vllm/entrypoints/cli/launch.py:1-60]()\n\n## 离线推理架构\n\nvLLM 提供离线推理能力，通过 `LLM` 类实现无需独立服务器的本地推理功能。\n\n### LLM 类接口\n\n`LLM` 类是离线推理的主要接口，支持：\n\n```python\n# 基本用法\nfrom vllm import LLM\n\nllm = LLM(\"meta-llama/Llama-2-7b-hf\")\noutputs = llm.generate(\"Hello, world!\")\n```\n\n### 支持的功能类型\n\n| 功能类型 | 说明 | 示例文件 |\n|---------|------|---------|\n| 对话生成 | Chat 格式推理 | `chat.py` |\n| 文本生成 | 标准文本补全 | `generate.py` |\n| 分类任务 | 文本分类 | `classify.py` |\n| 嵌入向量 | 向量嵌入提取 | `embed.py` |\n| 评分计算 | 文本相似度评分 | `score.py` |\n\n### 量化模型支持\n\nvLLM 支持 GGUF 量化格式的模型加载：\n\n```bash\n--model unsloth/Qwen3-0.6B-GGUF:Q4_K_M --tokenizer Qwen/Qwen3-0.6B\n```\n\n格式说明：`repo_id:quant_type`，其中 quant_type 包括 Q2_K、Q4_K_M、Q5_K_S、Q6_K 等。\n\n### CPU 卸载功能\n\n`--cpu-offload-gb` 参数允许将部分模型卸载到 CPU 内存：\n\n```bash\n--cpu-offload-gb 10 # 虚拟增加 10GB GPU 显存\n```\n\n这使得在显存较小的 GPU 上运行更大规模的模型成为可能。\n\n资料来源：[examples/basic/offline_inference/README.md](https://github.com/vllm-project/vllm/blob/main/examples/basic/offline_inference/README.md)\n\n## 分离式 Prefill 架构\n\nvLLM 支持分离式 Prefill 架构，将预填充阶段和解码阶段部署在不同的实例上，以优化大规模部署的资源利用率。\n\n### 架构设计\n\n```mermaid\ngraph TD\n subgraph \"Encoder 实例\"\n Encoder[编码器模型]\n ECC[EC Connector]\n end\n \n subgraph \"Prefill 实例\"\n Prefill[Prefill 模型]\n ECC2[EC Connector]\n end\n \n subgraph \"Decode 实例\"\n Decode[Decode 模型]\n KVStore[KV 状态存储]\n end\n \n Encoder -->|编码缓存| ECC\n ECC -->|EC Transfer| ECC2\n ECC2 --> Prefill\n Prefill -->|KV 状态| Decode\n Decode --> KVStore\n```\n\n### EC Connector 配置\n\nEncoder Cache (EC) Connector 用于在实例间传输编码器缓存：\n\n```bash\n# Encoder 实例配置\n--ec-transfer-config '{\n \"ec_connector\": \"ECExampleConnector\",\n \"ec_role\": \"ec_producer\",\n \"ec_connector_extra_config\": {\n \"shared_storage_path\": \"/path/to/storage\"\n }\n}'\n\n# Prefill/Decode 实例配置\n--ec-transfer-config '{\n \"ec_connector\": \"ECExampleConnector\",\n \"ec_role\": \"ec_consumer\",\n \"ec_connector_extra_config\": {\n \"shared_storage_path\": \"/path/to/storage\"\n }\n}'\n```\n\n### 离线示例工作流\n\n离线分离式推理示例包含两个脚本协同工作：\n\n1. **prefill_example.py** - 仅执行预填充，保存 KV 状态和提示词\n2. **decode_example.py** - 加载 KV 状态，执行解码生成\n\n```bash\n./run.sh # 顺序执行 prefill 和 decode\n```\n\n资料来源：[examples/disaggregated/example_connector/README.md](https://github.com/vllm-project/vllm/blob/main/examples/disaggregated/example_connector/README.md)\n\n## 可观测性架构\n\nvLLM 提供完整的可观测性支持，包括指标采集、分布式追踪和日志记录。\n\n### OpenTelemetry 集成\n\nvLLM 原生支持 OpenTelemetry 标准，可与 Jaeger、Prometheus 等监控系统集成：\n\n```bash\n# 启动带追踪的 vLLM 服务\nopentelemetry-instrument vllm serve facebook/opt-125m\n```\n\n### 追踪架构\n\n```mermaid\ngraph LR\n A[vLLM 实例] -->|OTLP| B[Jaeger Collector]\n B --> C[Jaeger UI]\n D[Prometheus] --> E[Grafana]\n A -->|Metrics| D\n```\n\n### 集成组件\n\n| 组件 | 类型 | 用途 |\n|-----|------|------|\n| opentelemetry-sdk | 追踪 SDK | 核心追踪功能 |\n| opentelemetry-api | API 接口 | 标准化接口 |\n| opentelemetry-exporter-otlp | 导出器 | OTLP 协议导出 |\n| opentelemetry-semantic-conventions-ai | 语义约定 | AI 领域约定 |\n\n### Jaeger 部署示例\n\n```bash\n# 启动 Jaeger\ndocker run --rm --name jaeger \\\n -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \\\n -p 6831:6831/udp -p 16686:16686 \\\n -p 4317:4317 -p 4318:4318 \\\n jaegertracing/all-in-one:1.57\n\n# 配置端点\nexport JAEGER_IP=$(docker inspect --format '{{ .NetworkSettings.IPAddress }}' jaeger)\nexport OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=grpc://$JAEGER_IP:4317\nexport OTEL_SERVICE_NAME=\"vllm-service\"\n```\n\n资料来源：[examples/observability/opentelemetry/README.md](https://github.com/vllm-project/vllm/blob/main/examples/observability/opentelemetry/README.md)\n\n## 平台检测机制\n\nvLLM 在启动时自动检测运行平台，并相应调整资源配置：\n\n```python\n# 平台检测逻辑（伪代码）\nif platform_unspecified():\n logger.info(\"Unspecified platform detected, switching to CPU Platform instead.\")\n switch_to_cpu_platform()\n```\n\n支持的平台：\n\n| 平台 | 说明 | 适用场景 |\n|-----|------|---------|\n| CUDA | NVIDIA GPU 平台 | 生产环境高性能推理 |\n| ROCm | AMD GPU 平台 | AMD 硬件部署 |\n| CPU | CPU 计算平台 | 开发测试、轻量推理 |\n| TPU | Google TPU 平台 | TPU 硬件部署 |\n\n## 结构化输出支持\n\nvLLM 支持结构化输出功能，可生成符合约束条件的 JSON、Regex 等格式的输出。\n\n### 支持的约束类型\n\n| 约束类型 | 说明 | 使用场景 |\n|---------|------|---------|\n| `json` | JSON Schema 约束 | API 响应格式化 |\n| `regex` | 正则表达式约束 | 特定格式匹配 |\n| `structural_tag` | 结构化标签约束 | XML/HTML 类输出 |\n\n### 使用示例\n\n```bash\n# 启动结构化输出服务\nvllm serve deepseek-ai/DeepSeek-R1-Distill-Qwen-7B \\\n --reasoning-parser deepseek_r1\n\n# 运行结构化输出测试\npython structured_outputs_offline.py --constraint structural_tag regex --stream\n```\n\n## 数据并行与负载均衡\n\nvLLM 支持多种数据并行和负载均衡模式：\n\n### 模式类型\n\n| 模式 | 启动参数 | 说明 |\n|-----|---------|------|\n| 外部负载均衡 | `--data-parallel-external-lb` | 外部 LB 分配请求 |\n| 混合负载均衡 | `--data-parallel-hybrid-lb` | 内部+外部混合 |\n| 数据并行 | `--data-parallel-rank` | 指定实例排名 |\n| 起始排名 | `--data-parallel-start-rank` | 混合模式起始rank |\n\n### API Server 计数配置\n\n```python\n# 默认值根据模式自动确定\nif args.headless:\n args.api_server_count = 0 # 无头模式下禁用 API 服务器\n```\n\n## 总结\n\nvLLM 的架构设计体现了以下核心设计原则：\n\n1. **模块化设计** - 各层职责清晰，便于独立开发和测试\n2. **灵活部署** - 支持在线服务、离线推理、分离式部署等多种模式\n3. **资源高效** - 通过 PagedAttention 实现显存的高效利用\n4. **标准兼容** - 提供 OpenAI 兼容 API，便于现有系统集成\n5. **可观测性** - 内置 OpenTelemetry 支持，便于监控和调试\n\n这些设计使得 vLLM 能够满足从研究实验到生产部署的各种需求，成为大语言模型推理服务的重要选择。\n\n---\n\n\n\n## V1 引擎架构\n\n### 相关页面\n\n相关主题：[架构概览](#page-arch-overview), [PagedAttention 与 KV 缓存管理](#page-paged-attention), [注意力后端](#page-attention-backends)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [vllm/v1/engine/core.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/engine/core.py)\n- [vllm/v1/engine/async_llm.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/engine/async_llm.py)\n- [vllm/v1/core/sched/scheduler.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/core/sched/scheduler.py)\n- [vllm/v1/sample/sampler.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/sample/sampler.py)\n- [vllm/v1/core/kv_cache_manager.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/core/kv_cache_manager.py)\n- [vllm/v1/core/block_manager.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/core/block_manager.py)\n- [vllm/v1/worker/worker_base.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/worker/worker_base.py)\n \n\n# V1 引擎架构\n\n## 概述\n\nV1引擎是vLLM的全新一代推理引擎架构，采用完全异步的设计理念，实现了高性能的批量请求调度和KV缓存管理。与传统同步引擎不同，V1引擎通过异步流水线架构，能够更高效地处理并发推理请求，显著提升GPU利用率和吞吐量。\n\nV1引擎的核心设计目标包括：\n\n- **异步优先**：全链路异步处理，避免阻塞等待\n- **高效调度**：智能批量调度，优化GPU计算资源\n- **内存优化**：精细化的KV缓存管理，提高显存利用率\n- **可扩展性**：模块化设计，支持多种推理策略\n\n资料来源：[vllm/v1/engine/core.py:1-100]()\n\n## 整体架构\n\n### 架构组件图\n\n```mermaid\ngraph TD\n Client[客户端请求] --> AsyncLLM[AsyncLLM 异步接口]\n AsyncLLM --> Core[LLMCore 核心引擎]\n Core --> Scheduler[Scheduler 调度器]\n Scheduler --> Sampler[Sampler 采样器]\n Scheduler --> KVCacheMgr[KVCacheManager KV缓存管理]\n KVCacheMgr --> BlockMgr[BlockManager 块管理器]\n Sampler --> Worker[Worker 计算单元]\n Worker --> GPU[GPU 推理执行]\n \n style AsyncLLM fill:#e1f5fe\n style Core fill:#fff3e0\n style Scheduler fill:#e8f5e9\n style KVCacheMgr fill:#fce4ec\n```\n\n### 核心组件职责\n\n| 组件 | 文件路径 | 主要职责 |\n|------|----------|----------|\n| AsyncLLM | `vllm/v1/engine/async_llm.py` | 异步请求接口，事件循环管理 |\n| LLMCore | `vllm/v1/engine/core.py` | 引擎核心逻辑，请求生命周期管理 |\n| Scheduler | `vllm/v1/core/sched/scheduler.py` | 请求调度，批次优化 |\n| Sampler | `vllm/v1/sample/sampler.py` | 词元采样，生成控制 |\n| KVCacheManager | `vllm/v1/core/kv_cache_manager.py` | KV缓存分配与回收 |\n| BlockManager | `vllm/v1/core/block_manager.py` | 物理块管理，显存映射 |\n\n资料来源：[vllm/v1/engine/async_llm.py:1-50]()\n\n## AsyncLLM 异步接口层\n\n### 设计概述\n\nAsyncLLM是V1引擎对外暴露的异步编程接口，采用Python asyncio事件循环驱动。它将同步的用户请求转换为异步操作，实现非阻塞的推理调用。\n\n```mermaid\ngraph LR\n A[add_request] --> B[请求队列]\n C[get_output] --> D[输出队列]\n B --> E[事件循环]\n E --> D\n E --> F[后台处理任务]\n```\n\n### 核心方法\n\n```python\nclass AsyncLLM:\n async def add_request(\n request_id: str,\n prompt: str,\n sampling_params: SamplingParams,\n lora_request: Optional[LoRARequest] = None\n ) -> None\n \n async def generate() -> AsyncGenerator[RequestOutput, None]\n \n async def abort_request(request_id: str) -> None\n```\n\n资料来源：[vllm/v1/engine/async_llm.py:80-150]()\n\n## LLMCore 核心引擎\n\n### 引擎初始化流程\n\nLLMCore是V1引擎的核心类，负责初始化和管理整个推理引擎的生命周期。\n\n```mermaid\nflowchart TD\n A[初始化配置] --> B[创建Worker]\n B --> C[初始化KVCacheManager]\n C --> D[初始化Scheduler]\n D --> E[初始化Sampler]\n E --> F[启动事件循环]\n F --> G[引擎就绪]\n```\n\n### 核心类结构\n\n```python\nclass LLMCore:\n def __init__(\n self,\n model_config: ModelConfig,\n cache_config: CacheConfig,\n parallel_config: ParallelConfig,\n scheduler_config: SchedulerConfig,\n ...\n ):\n self.worker = self._init_worker()\n self.kv_cache_manager = KVCacheManager(...)\n self.scheduler = Scheduler(...)\n self.sampler = Sampler(...)\n```\n\n资料来源：[vllm/v1/engine/core.py:100-200]()\n\n## Scheduler 调度器\n\n### 调度策略\n\nScheduler负责管理待处理请求的调度，决定何时以及如何将请求打包成批次进行推理。V1引擎的调度器采用多级队列和多策略调度算法。\n\n```mermaid\ngraph TD\n A[新请求] --> B[等待队列 WaitQueue]\n B --> C{调度决策}\n C -->|可以调度| D[运行队列 RunningQueue]\n C -->|等待资源| E[阻塞队列 BlockedQueue]\n D --> F[生成完成]\n F --> G[输出队列]\n E -->|资源释放| C\n```\n\n### 调度配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| max_num_seqs | int | 256 | 单批次最大序列数 |\n| max_num_batched_tokens | int | 8192 | 单批次最大词元数 |\n| gpu_memory_utilization | float | 0.9 | GPU显存利用率 |\n| num_scheduler_steps | int | 1 | 调度器步数 |\n\n资料来源：[vllm/v1/core/sched/scheduler.py:50-150]()\n\n### 调度循环\n\nScheduler的核心调度循环实现如下：\n\n1. **请求入队**：新请求加入等待队列\n2. **资源检查**：检查KV缓存和计算资源\n3. **批次构建**：选择可调度的请求构建批次\n4. **执行分发**：将批次分发给Worker执行\n5. **结果收集**：收集推理结果并更新请求状态\n\n```python\ndef schedule(self) -> SchedulerOutput:\n # 1. 更新已完成的请求\n self._update_completed_requests()\n \n # 2. 分配新的 KV cache 块\n self._allocate_kv_cache()\n \n # 3. 选择要调度的请求批次\n scheduled = self._select_new_batch()\n \n # 4. 生成调度输出\n return SchedulerOutput(scheduled=scheduled, ...)\n```\n\n资料来源：[vllm/v1/core/sched/scheduler.py:200-350]()\n\n## Sampler 采样器\n\n### 采样流程\n\nSampler负责从模型输出的logits中进行词元采样，是生成式推理的关键环节。\n\n```mermaid\ngraph LR\n A[Logits] --> B[Temperature处理]\n B --> C[Top-K过滤]\n C --> D[Top-P过滤]\n D --> E[采样]\n E --> F[新Token]\n```\n\n### 采样配置\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| temperature | float | 温度参数，控制随机性 |\n| top_p | float | Nucleus采样概率阈值 |\n| top_k | int | Top-K过滤的K值 |\n| max_tokens | int | 最大生成长度 |\n| seed | List[int] | 随机种子 |\n\n```python\nclass Sampler:\n def __init__(self, gpu_device: int, ...):\n self._setup_sampling_algorithms()\n \n def sample(\n self,\n logits: torch.Tensor,\n sampling_params: SamplingParams\n ) -> torch.Tensor:\n # 应用温度\n logits = self._apply_temperature(logits, sampling_params.temperature)\n \n # Top-K 采样\n if sampling_params.top_k != -1:\n logits = self._apply_top_k(logits, sampling_params.top_k)\n \n # Top-P 采样\n if sampling_params.top_p < 1.0:\n logits = self._apply_top_p(logits, sampling_params.top_p)\n \n # 最终采样\n return self._sample(logits, sampling_params.seed)\n```\n\n资料来源：[vllm/v1/sample/sampler.py:50-200]()\n\n## KVCacheManager 缓存管理\n\n### 设计原理\n\nKVCacheManager是V1引擎的KV缓存管理器，负责高效管理和复用GPU显存中的Key-Value缓存。\n\n```mermaid\ngraph TD\n A[请求到达] --> B{检查现有缓存}\n B -->|命中| C[复用已有缓存]\n B -->|未命中| D[分配新缓存块]\n C --> E[追加新Token]\n D --> E\n E --> F[更新块状态]\n F --> G[等待下次调度]\n \n style C fill:#c8e6c9\n style D fill:#ffcdd2\n```\n\n### 缓存块管理\n\n| 块类型 | 说明 | 管理方式 |\n|--------|------|----------|\n| 空闲块 | 未分配的缓存块 | 空闲链表 |\n| 已占用块 | 当前被请求使用的块 | 引用计数 |\n| 已回收块 | 请求完成后待回收的块 | 回收队列 |\n\n```python\nclass KVCacheManager:\n def __init__(self, num_blocks: int, block_size: int, ...):\n self.num_blocks = num_blocks\n self.block_size = block_size\n self._free_blocks: Deque[int] = deque(range(num_blocks))\n self._block_mapping: Dict[str, List[int]] = {}\n \n def allocate(self, request_id: str, num_tokens: int) -> List[int]:\n \"\"\"为请求分配缓存块\"\"\"\n num_blocks_needed = (num_tokens + self.block_size - 1) // self.block_size\n blocks = []\n for _ in range(num_blocks_needed):\n if not self._free_blocks:\n raise OutOfMemoryError(\"KV cache exhausted\")\n blocks.append(self._free_blocks.popleft())\n self._block_mapping[request_id] = blocks\n return blocks\n \n def free(self, request_id: str) -> None:\n \"\"\"释放请求的缓存块\"\"\"\n if request_id in self._block_mapping:\n self._free_blocks.extend(self._block_mapping.pop(request_id))\n```\n\n资料来源：[vllm/v1/core/kv_cache_manager.py:80-200]()\n\n### 缓存分配策略\n\nV1引擎采用以下缓存分配策略优化显存利用：\n\n1. **预分配策略**：根据请求预估长度预分配缓存\n2. **动态扩展**：运行时根据实际需求动态扩展缓存\n3. **块复用**：同一模型层的不同请求共享块结构\n4. **分层管理**：支持不同层的KV缓存独立管理\n\n资料来源：[vllm/v1/core/kv_cache_manager.py:200-300]()\n\n## BlockManager 块管理器\n\n### 物理块管理\n\nBlockManager负责底层物理块的管理，将逻辑缓存块映射到实际的GPU显存地址。\n\n```python\nclass BlockManager:\n def __init__(\n self,\n num_gpu_blocks: int,\n num_cpu_blocks: int,\n block_size: int,\n ):\n self._gpu_block_table: Dict[int, torch.Tensor] = {}\n self._cpu_block_table: Dict[int, torch.Tensor] = {}\n self._block_allocator = BlockAllocator(...)\n```\n\n### 块状态转换\n\n```mermaid\nstateDiagram-v2\n [*] --> Free: 初始化\n Free --> Allocated: 分配\n Allocated --> Free: 释放\n Allocated --> Swapping: 换出到CPU\n Swapping --> Allocated: 换入到GPU\n```\n\n资料来源：[vllm/v1/core/block_manager.py:50-150]()\n\n## Worker 计算单元\n\n### Worker架构\n\nWorker是V1引擎的执行单元，负责在GPU上执行实际的推理计算。\n\n```mermaid\ngraph TD\n A[输入词元] --> B[Embedding层]\n B --> C[Transformer层]\n C --> D[计算Attention]\n D --> E[读取KV缓存]\n E --> C\n C --> F[Logits输出]\n F --> G[返回给Sampler]\n```\n\n### Worker基类\n\n```python\nclass WorkerBase:\n def __init__(self, vllm_config: VllmConfig, ...):\n self.vllm_config = vllm_config\n self.model_runner = ModelRunner(...)\n \n def execute_model(\n self,\n seq_group_metadata_list: List[SequenceGroupMetadata],\n kv_caches: List[torch.Tensor],\n ) -> Optional[List[torch.Tensor]]:\n # 准备输入\n input_tokens = self._prepare_input(seq_group_metadata_list)\n \n # 执行模型推理\n output = self.model_runner.execute(input_tokens, kv_caches)\n \n return output\n```\n\n资料来源：[vllm/v1/worker/worker_base.py:50-150]()\n\n## 请求处理流程\n\n### 完整推理流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant AsyncLLM as AsyncLLM\n participant Core as LLMCore\n participant Scheduler as Scheduler\n participant Worker as Worker\n participant Sampler as Sampler\n participant KVCache as KVCacheManager\n \n Client->>AsyncLLM: add_request()\n AsyncLLM->>Core: 提交请求\n Core->>Scheduler: 入队\n Scheduler->>KVCache: 分配缓存\n Scheduler->>Worker: 分发批次\n Worker->>Worker: GPU推理\n Worker-->>Sampler: Logits输出\n Sampler->>Sampler: 词元采样\n Sampler-->>KVCache: 更新缓存\n KVCache-->>Scheduler: 分配完成\n Scheduler-->>AsyncLLM: 调度结果\n AsyncLLM-->>Client: 输出流\n```\n\n### 多步推理循环\n\nV1引擎支持多步推理（Multi-Step Decoding），在单次调度中执行多个推理步骤：\n\n1. **步骤1**：执行Attention计算\n2. **步骤2**：更新KV缓存\n3. **步骤3**：执行采样\n4. **步骤4**：判断是否继续\n\n```python\nfor step in range(num_scheduler_steps):\n # 执行模型前向\n hidden_states = model(input_ids, kv_caches)\n \n # 计算logits\n logits = hidden_states @ lm_head.weight\n \n # 采样新token\n next_tokens = sampler.sample(logits)\n \n # 检查终止条件\n if self._should_stop(next_tokens):\n break\n```\n\n资料来源：[vllm/v1/engine/core.py:300-400]()\n\n## 配置与优化\n\n### 引擎配置选项\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| model | str | 必填 | 模型路径或HuggingFace ID |\n| tensor_parallel_size | int | 1 | 张量并行度 |\n| gpu_memory_utilization | float | 0.9 | GPU显存利用率 |\n| max_model_len | int | 8192 | 最大模型长度 |\n| block_size | int | 16 | KV缓存块大小 |\n| enable_prefix_caching | bool | True | 启用前缀缓存 |\n| num_scheduler_steps | int | 1 | 调度器步数 |\n\n### 性能优化建议\n\n1. **调整GPU显存利用率**：根据模型大小调整，避免OOM\n2. **优化块大小**：较大块减少碎片，较小块提高利用率\n3. **启用前缀缓存**：对重复前缀的请求效果显著\n4. **批量大小优化**：根据延迟和吞吐量需求调整\n\n资料来源：[vllm/v1/engine/core.py:400-500]()\n\n## 与V0引擎的对比\n\n| 特性 | V0引擎 | V1引擎 |\n|------|--------|--------|\n| 架构模式 | 同步批量处理 | 异步流水线 |\n| 缓存管理 | 静态分配 | 动态管理 |\n| 调度策略 | 固定批次 | 自适应调度 |\n| 扩展性 | 一般 | 模块化设计 |\n| 多步推理 | 不支持 | 原生支持 |\n\nV1引擎通过异步架构和精细化的资源管理，实现了更高的GPU利用率和更低的请求延迟。\n\n## 总结\n\nV1引擎架构代表了vLLM在推理优化领域的最新技术演进。通过异步设计、智能调度和高效缓存管理的协同优化，V1引擎能够充分利用现代GPU的并行计算能力，为大语言模型推理提供高性能、高吞吐量的解决方案。模块化的组件设计使得V1引擎具有良好的可扩展性和可维护性，便于后续功能扩展和性能优化。\n\n---\n\n\n\n## 引擎核心模块\n\n### 相关页面\n\n相关主题：[架构概览](#page-arch-overview), [V1 引擎架构](#page-v1-engine)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [vllm/engine/llm_engine.py](https://github.com/vllm-project/vllm/blob/main/vllm/engine/llm_engine.py)\n- [vllm/engine/async_llm_engine.py](https://github.com/vllm-project/vllm/blob/main/vllm/engine/async_llm_engine.py)\n- [vllm/engine/protocol.py](https://github.com/vllm-project/vllm/blob/main/vllm/engine/protocol.py)\n- [vllm/v1/engine/llm_engine.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/engine/llm_engine.py)\n- [vllm/entrypoints/cli/serve.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/serve.py)\n- [vllm/entrypoints/cli/launch.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/launch.py)\n- [vllm/entrypoints/cli/main.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/main.py)\n \n\n# 引擎核心模块\n\n## 概述\n\nvLLM 的引擎核心模块是整个推理服务系统的核心组件，负责管理模型加载、请求调度、推理执行和结果返回等关键流程。引擎模块支持同步和异步两种运行模式，提供了面向不同应用场景的编程接口。\n\nvLLM 引擎采用了分层架构设计，底层封装了高性能的推理内核，上层提供了灵活的调度策略和请求管理机制。引擎通过抽象接口与上层服务层解耦，同时通过适配器与底层硬件平台紧密集成。\n\n引擎模块位于 `vllm/engine/` 目录下，主要包含以下核心组件：\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| LLMEngine | `vllm/engine/llm_engine.py` | 同步推理引擎主类 |\n| AsyncLLMEngine | `vllm/engine/async_llm_engine.py` | 异步推理引擎主类 |\n| EngineProtocol | `vllm/engine/protocol.py` | 引擎通信协议定义 |\n| V1 LLMEngine | `vllm/v1/engine/llm_engine.py` | V1版本引擎实现 |\n\n资料来源：[vllm/engine/llm_engine.py](https://github.com/vllm-project/vllm/blob/main/vllm/engine/llm_engine.py)\n\n## 架构设计\n\n### 整体架构\n\nvLLM 引擎采用事件驱动的异步架构，核心模块之间通过协议接口进行通信。引擎接收来自 API 服务层的请求，经过调度器分配后交由推理内核执行，最终将结果返回给调用方。\n\n```mermaid\ngraph TD\n subgraph \"服务层\"\n A[API Server] --> B[CLI/SDK]\n end\n \n subgraph \"引擎层\"\n C[AsyncLLMEngine] --> D[LLMEngine]\n D --> E[Scheduler]\n E --> F[Model Runner]\n end\n \n subgraph \"内核层\"\n G[CUDA Kernels] --> H[PagedAttention]\n F --> G\n end\n \n A --> C\n B --> C\n```\n\n资料来源：[vllm/entrypoints/cli/main.py:46-58](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/main.py)\n\n### 双引擎模式\n\nvLLM 支持 V0 和 V1 两套引擎实现，两者在架构和性能特性上有所不同：\n\n| 特性 | V0 Engine | V1 Engine |\n|------|----------|-----------|\n| 调度策略 | 多种调度器可选 | 统一调度框架 |\n| 内存管理 | 传统 KV Cache | PagedAttention |\n| 异步支持 | 有限 | 原生异步支持 |\n| 性能优化 | 成熟稳定 | 新一代优化 |\n\nV1 引擎位于 `vllm/v1/engine/` 目录下，代表了 vLLM 的新一代架构设计。\n\n资料来源：[vllm/v1/engine/llm_engine.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/engine/llm_engine.py)\n\n## 同步引擎 (LLMEngine)\n\n### 类定义\n\n`LLMEngine` 是 vLLM 的同步推理引擎主类，提供阻塞式的推理接口。该类负责初始化推理环境、管理模型权重、处理推理请求并返回结果。\n\n```python\nclass LLMEngine:\n def __init__(\n self,\n model_config: ModelConfig,\n cache_config: CacheConfig,\n parallel_config: ParallelConfig,\n scheduler_config: SchedulerConfig,\n device_config: DeviceConfig,\n executor_class: Type[ExecutorBase],\n log_stats: bool = True,\n usage_context: UsageContext = UsageContext.LLM_CLASS,\n ) -> None:\n```\n\n### 核心方法\n\n| 方法 | 参数 | 返回值 | 功能描述 |\n|------|------|--------|----------|\n| add_request | request_id, prompt, params | None | 添加推理请求 |\n| step | - | List[Output] | 执行一步推理 |\n| abort_request | request_id | None | 取消指定请求 |\n| get_num_unfinished_requests | - | int | 获取未完成请求数 |\n\n`step()` 方法是引擎的核心执行方法，每次调用会推进推理状态机，处理调度、内存分配、内核执行等操作。\n\n资料来源：[vllm/engine/llm_engine.py](https://github.com/vllm-project/vllm/blob/main/vllm/engine/llm_engine.py)\n\n### 请求处理流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Engine as LLMEngine\n participant Scheduler as 调度器\n participant Runner as ModelRunner\n participant Kernel as CUDA Kernels\n\n Client->>Engine: add_request()\n Engine->>Scheduler: 排队请求\n loop 推理循环\n Engine->>Scheduler: step()\n Scheduler->>Runner: 分发批次\n Runner->>Kernel: 执行推理\n Kernel-->>Runner: 输出结果\n Runner-->>Scheduler: 收集输出\n end\n Engine-->>Client: 返回结果\n```\n\n## 异步引擎 (AsyncLLMEngine)\n\n### 设计理念\n\n`AsyncLLMEngine` 是 vLLM 的异步推理引擎，专为高性能 Web 服务设计。它基于事件循环实现非阻塞推理，能够同时处理大量并发请求。\n\n异步引擎封装了底层同步引擎，通过 `asyncio` 协程提供非阻塞接口。这使得 vLLM 能够与 FastAPI、aiohttp 等异步 Web 框架无缝集成。\n\n资料来源：[vllm/engine/async_llm_engine.py](https://github.com/vllm-project/vllm/blob/main/vllm/engine/async_llm_engine.py)\n\n### 核心接口\n\n```python\nclass AsyncLLMEngine:\n async def add_request(\n self,\n request_id: str,\n prompt: PromptType,\n params: Optional[RequestParams] = None,\n arrival_time: Optional[float] = None,\n ) -> AsyncStream:\n \"\"\"添加异步推理请求\"\"\"\n```\n\n异步引擎通过 `AsyncStream` 对象返回结果，支持流式输出。调用方可以通过 `async for` 语法逐token获取生成结果。\n\n### 请求取消机制\n\n异步引擎支持请求级别的取消操作。当客户端需要中止某个长时间运行的推理时，可以通过 `abort()` 方法通知引擎。\n\n```python\nasync def abort(self, request_id: str) -> None:\n \"\"\"取消指定请求\"\"\"\n```\n\n资料来源：[vllm/engine/async_llm_engine.py](https://github.com/vllm-project/vllm/blob/main/vllm/engine/async_llm_engine.py)\n\n## 引擎协议 (EngineProtocol)\n\n`EngineProtocol` 定义了引擎与外部组件通信的标准接口规范。该协议抽象了引擎的核心行为，确保不同实现之间的一致性。\n\n```mermaid\ngraph LR\n subgraph \"协议层\"\n A[EngineProtocol] --> B[generate]\n A --> C[abort]\n A --> D[get_output]\n end\n```\n\n协议定义包括以下核心接口：\n\n| 接口 | 方法签名 | 说明 |\n|------|----------|------|\n| generate | async generate(request) | 生成推理请求 |\n| abort | abort(request_id) | 中止请求 |\n| get_output | await output_event | 获取输出事件 |\n\n资料来源：[vllm/engine/protocol.py](https://github.com/vllm-project/vllm/blob/main/vllm/engine/protocol.py)\n\n## 配置管理\n\n### 引擎参数\n\n引擎初始化时需要传入多个配置对象，这些配置控制了推理行为的各个方面：\n\n| 配置类 | 参数数量 | 主要功能 |\n|--------|----------|----------|\n| ModelConfig | 50+ | 模型架构、词汇表、量化配置 |\n| CacheConfig | 10+ | KV Cache 内存管理策略 |\n| ParallelConfig | 5+ | 多GPU并行配置 |\n| SchedulerConfig | 10+ | 调度器行为参数 |\n| DeviceConfig | 5+ | 硬件平台选择 |\n\n### 命令行参数\n\n引擎支持通过命令行参数进行配置，常用参数包括：\n\n```bash\nvllm serve Qwen/Qwen2.5-3B-Instruct \\\n --tensor-parallel-size 2 \\\n --max-model-len 8192 \\\n --gpu-memory-utilization 0.9\n```\n\n资料来源：[vllm/entrypoints/cli/serve.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/serve.py)\n\n## 服务启动流程\n\n### CLI 入口\n\nvLLM 的服务通过命令行启动，主要入口流程如下：\n\n```mermaid\nflowchart LR\n A[vllm serve] --> B[main.py]\n B --> C[导入模块]\n C --> D[ServeSubcommand]\n D --> E[创建引擎]\n E --> F[启动服务]\n```\n\nCLI 入口位于 `vllm/entrypoints/cli/main.py`，负责解析命令行参数并分发到相应的子命令处理器。\n\n资料来源：[vllm/entrypoints/cli/main.py:48-68](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/main.py)\n\n### 引擎初始化\n\n```python\ndef cmd(args: argparse.Namespace) -> None:\n # CLI 参数优先级高于默认值\n if hasattr(args, \"model_tag\") and args.model_tag is not None:\n args.model = args.model_tag\n\n # gRPC 模式\n if getattr(args, \"grpc\", False):\n from vllm.entrypoints.grpc_server import serve_grpc\n uvloop.run(serve_grpc(args))\n return\n\n # Headless 模式（无API服务器）\n if args.headless:\n args.api_server_count = 0\n```\n\n引擎支持多种运行模式，包括标准 HTTP 服务、gRPC 服务和 headless 模式。Headless 模式不启动 API 服务器，适用于分布式推理场景。\n\n资料来源：[vllm/entrypoints/cli/serve.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/serve.py)\n\n### Launch 组件\n\n`vllm launch` 命令提供了组件级别的启动能力，支持快速启动特定的推理组件：\n\n```bash\nvllm launch [options]\n```\n\nLaunch 子系统采用插件化架构，新的组件可以通过继承 `LaunchSubcommandBase` 类注册到系统中。\n\n资料来源：[vllm/entrypoints/cli/launch.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/launch.py)\n\n## 调度器集成\n\n### 调度策略\n\n引擎内置多种调度策略，适用于不同的负载场景：\n\n| 策略 | 适用场景 | 特点 |\n|------|----------|------|\n| FIFO | 批处理 | 简单高效 |\n| Longest-Prefix | 前缀共享 | 优化解码共享 |\n| 混合策略 | 通用 | 平衡吞吐和延迟 |\n\n调度器通过 `SchedulerConfig` 进行配置，控制批次大小、超时时间、资源分配等关键参数。\n\n### 资源分配\n\n调度器负责管理 GPU 显存使用，通过 `gpu_memory_utilization` 参数控制用于 KV Cache 的显存比例。剩余显存用于模型权重和中间计算。\n\n```python\n# 显存分配示例\ncache_config = CacheConfig(\n gpu_memory_utilization=0.9,\n block_size=16,\n)\n```\n\n## 性能优化\n\n### PagedAttention\n\nvLLM 引擎采用 PagedAttention 技术管理 KV Cache，相比传统连续分配方式，显存利用率提升显著：\n\n- 显存碎片减少 60%+\n- 吞吐量提升 2-4 倍\n- 支持更大的上下文长度\n\n### CUDA 图\n\n引擎支持 CUDA Graph 加速，减少内核启动开销。在 profiling 模式下，可以通过 `nsys` 工具分析 CUDA 图的执行效率：\n\n```bash\nnsys profile -t cuda -o run1 -f true \\\n --cuda-graph-trace=node \\\n vllm serve openai/gpt-oss-120b\n```\n\n资料来源：[tools/profiler/nsys_profile_tools/README.md](https://github.com/vllm-project/vllm/blob/main/tools/profiler/nsys_profile_tools/README.md)\n\n## 使用示例\n\n### 离线推理\n\n```python\nfrom vllm import LLM\n\nllm = LLM(model=\"Qwen/Qwen2.5-3B-Instruct\")\noutputs = llm.generate(\"Hello, world!\")\n```\n\n### 在线服务\n\n```bash\n# 启动服务\nvllm serve Qwen/Qwen2.5-3B-Instruct \\\n --tensor-parallel-size 2\n\n# 发送请求\ncurl -X POST http://localhost:8000/v1/chat/completions \\\n -H \"Content-Type: application/json\" \\\n -d '{\"model\": \"Qwen/Qwen2.5-3B-Instruct\", \"messages\": [{\"role\": \"user\", \"content\": \"Hello!\"}]}'\n```\n\n### 异步客户端\n\n```python\nfrom vllm.engine.async_llm_engine import AsyncLLMEngine\n\nengine = AsyncLLMEngine.from_engine_args(engine_args)\n\nasync def generate():\n async for output in await engine.add_request(\"req-1\", prompt, params):\n print(output)\n\nasyncio.run(generate())\n```\n\n## 相关文档\n\n- [快速开始指南](https://docs.vllm.ai/en/latest/getting_started/quickstart.html)\n- [支持的模型列表](https://docs.vllm.ai/en/latest/models/supported_models.html)\n- [量化配置](https://docs.vllm.ai/en/latest/features/quantization.html)\n- [分布式推理](https://docs.vllm.ai/en/latest/distributed/summary.html)\n\n---\n\n\n\n## PagedAttention 与 KV 缓存管理\n\n### 相关页面\n\n相关主题：[注意力后端](#page-attention-backends), [V1 引擎架构](#page-v1-engine)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/design/paged_attention.md](https://github.com/vllm-project/vllm/blob/main/docs/design/paged_attention.md)\n- [csrc/attention/paged_attention_v1.cu](https://github.com/vllm-project/vllm/blob/main/csrc/attention/paged_attention_v1.cu)\n- [csrc/attention/paged_attention_v2.cu](https://github.com/vllm-project/vllm/blob/main/csrc/attention/paged_attention_v2.cu)\n- [vllm/v1/core/block_pool.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/core/block_pool.py)\n- [vllm/v1/core/kv_cache_manager.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/core/kv_cache_manager.py)\n \n\n# PagedAttention 与 KV 缓存管理\n\n## 概述\n\nPagedAttention 是 vLLM 核心推理引擎中的一项关键技术，旨在解决大语言模型（LLM）推理过程中 KV 缓存的内存管理问题。传统的 KV 缓存管理方式采用连续内存分配策略，导致内存碎片化严重、利用率低下。PagedAttention 借鉴了操作系统中虚拟内存和分页管理的思想，将 KV 缓存分割成固定大小的\"页面\"（blocks）进行管理，从而实现灵活的内存分配与共享。\n\nvLLM 的 KV 缓存管理架构分为 V1 和 V2 两个版本，其中 V2 版本在性能和内存效率方面进行了进一步优化。管理机制主要由 `BlockPool` 和 `KVCacheManager` 两个核心组件协同工作，实现对 GPU 和 CPU 内存中 KV 缓存块的高效调度。\n\n## PagedAttention 核心原理\n\n### 分页管理机制\n\nPagedAttention 将 KV 缓存划分为固定大小的块（blocks），每个块包含多个 token 的键值向量。与传统方法不同，这些块不需要在物理内存中连续存储，而是通过逻辑地址映射实现灵活访问。这种设计允许系统动态分配和释放缓存块，显著提高内存利用率。\n\n```mermaid\ngraph TD\n A[请求序列] --> B[逻辑块分配]\n B --> C[块表映射]\n C --> D[物理块存储]\n D --> E[GPU KV Cache]\n \n F[块表] -->|映射| D\n G[新请求] -->|增量分配| B\n H[请求完成] -->|块回收| D\n```\n\n### V1 与 V2 版本对比\n\n| 特性 | PagedAttention V1 | PagedAttention V2 |\n|------|-------------------|-------------------|\n| 块大小 | 固定16个token | 固定16个token |\n| 内存布局 | 原始格式 | 扁平化布局 |\n| 计算效率 | 标准计算 | 融合内核优化 |\n| 支持前缀共享 | 有限支持 | 增强支持 |\n\n## KV 缓存管理架构\n\n### BlockPool 组件\n\n`BlockPool` 负责管理物理内存中的 KV 缓存块池。它维护可用块的分配状态，支持 GPU 和 CPU 内存的双层管理。当新的推理请求到达时，`BlockPool` 负责分配空闲块；当请求完成时，相应块被回收至空闲池。\n\n核心功能包括：\n\n- 块预分配与动态分配策略\n- GPU/CPU 块状态追踪\n- 块引用计数管理\n- 内存碎片整理\n\n### KVCacheManager 组件\n\n`KVCacheManager` 是更高层次的缓存管理器，负责逻辑块到物理块的映射管理。它维护请求的 KV 块分配记录，支持 block 级别的引用计数和共享机制。当多个请求共享相同的前缀时，`KVCacheManager` 可以实现块级别的共享，避免重复存储相同的 KV 数据。\n\n```mermaid\ngraph LR\n A[推理请求] --> B[KVCacheManager]\n B --> C{前缀匹配?}\n C -->|是| D[共享已有块]\n C -->|否| E[分配新块]\n D --> F[BlockPool]\n E --> F\n F --> G[更新块表映射]\n G --> H[执行注意力计算]\n```\n\n## CUDA 内核实现\n\n### PagedAttention V1 内核\n\nV1 版本的内核实现位于 `csrc/attention/paged_attention_v1.cu`，采用标准的 CUDA 并行策略。内核函数 `paged_attention_v1` 处理块级别的注意力计算，每个线程块负责一个查询头（query head）的计算。内核通过共享内存缓存 KV 数据，减少全局内存访问延迟。\n\n关键实现要点：\n\n- 支持不同的块大小配置\n- 实现了 KV 数据的分页读取\n- 使用 warp 级别的归约操作提升性能\n- 支持半精度（FP16/BF16）计算\n\n### PagedAttention V2 内核\n\nV2 版本位于 `csrc/attention/paged_attention_v2.cu`，在 V1 基础上进行了深度优化。主要改进包括：\n\n1. **扁平化内存布局**：将 KV 数据按页面连续存储，提升缓存局部性\n2. **融合内核设计**：将多个操作融合到单一内核中，减少内核启动开销\n3. **向量化加载**：使用更大的向量宽度访问内存，提高带宽利用率\n4. **动态块大小支持**：根据配置自适应调整计算策略\n\n## 内存管理策略\n\n### 分配策略\n\nvLLM 采用混合分配策略处理 KV 缓存：\n\n- **预分配策略**：在模型加载时预分配一定比例的 GPU 内存用于 KV 缓存\n- **动态分配**：运行时根据实际需求动态分配新块\n- **层级淘汰**：GPU 内存不足时，将部分块交换至 CPU 内存\n\n### 共享机制\n\nPagedAttention 支持不同请求间的 KV 块共享。当多个请求共享相同的前缀（如系统提示词）时，对应的 KV 块可以被多个请求引用，无需重复存储。共享通过引用计数实现，只有当引用计数归零时，块才会被释放。\n\n```mermaid\ngraph TD\n A[请求1: 共享前缀] --> B[引用计数=2]\n C[请求2: 共享前缀] --> B\n \n B --> D[物理块P]\n D --> E[Token 0-15 KV数据]\n \n F[请求3: 独立前缀] --> G[引用计数=1]\n G --> H[物理块Q]\n H --> I[Token 0-15 KV数据]\n```\n\n## 配置与调优\n\n### 关键配置参数\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `block_size` | 每个缓存块包含的 token 数量 | 16 |\n| `gpu_memory_utilization` | 用于 KV 缓存的 GPU 内存比例 | 0.9 |\n| `num_cpu_blocks` | CPU 缓存块数量 | 动态计算 |\n| `num_gpu_blocks` | GPU 缓存块数量 | 动态计算 |\n\n### 性能调优建议\n\n1. 根据模型大小和可用显存调整 `gpu_memory_utilization`\n2. 对于长上下文场景，适当增加块数量\n3. 启用块共享以优化多请求场景的内存使用\n4. 监控实际的块使用率以优化配置\n\n## 技术优势\n\nPagedAttention 相比传统连续分配方案具有显著优势：\n\n- **内存效率提升**：通过分页管理和共享机制，内存利用率提高 2-4 倍\n- **支持更长上下文**：灵活的内存管理允许处理更长的输入序列\n- **高吞吐量**：优化的 CUDA 内核实现提供更高的计算吞吐量\n- **弹性扩展**：支持动态调整缓存容量以适应不同工作负载\n\n## 源码引用\n\n本文档参考了以下 vLLM 源码文件：\n\n- `docs/design/paged_attention.md` - PagedAttention 设计文档\n- `csrc/attention/paged_attention_v1.cu` - V1 CUDA 内核实现\n- `csrc/attention/paged_attention_v2.cu` - V2 CUDA 内核实现\n- `vllm/v1/core/block_pool.py` - 块池管理模块\n- `vllm/v1/core/kv_cache_manager.py` - KV 缓存管理器模块\n\n---\n\n\n\n## 注意力后端\n\n### 相关页面\n\n相关主题：[PagedAttention 与 KV 缓存管理](#page-paged-attention)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/design/attention_backends.md](https://github.com/vllm-project/vllm/blob/main/docs/design/attention_backends.md)\n- [vllm/v1/attention/backends/flash_attn.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/attention/backends/flash_attn.py)\n- [vllm/v1/attention/backends/flashinfer.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/attention/backends/flashinfer.py)\n- [vllm/v1/attention/selector.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/attention/selector.py)\n- [vllm/v1/attention/ops/paged_attn.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/attention/ops/paged_attn.py)\n \n\n# 注意力后端\n\n## 概述\n\nvLLM 的注意力后端（Attention Backends）是处理 Transformer 模型中自注意力机制的核心组件，负责高效计算 Query、Key、Value 之间的注意力分数。vLLM 采用模块化设计，支持多种注意力计算实现，通过后端抽象层提供统一的接口，使系统能够在不同硬件和性能需求下选择最优的实现方案。\n\n注意力后端的主要职责包括：\n\n- 计算多头自注意力（Multi-Head Attention）\n- 支持带因果掩码的解码模式\n- 处理键值缓存（KV Cache）的读写\n- 支持分页注意力（Paged Attention）以优化内存使用\n\n资料来源：[docs/design/attention_backends.md]()\n\n## 架构设计\n\n### 后端抽象层\n\nvLLM 在 `vllm/v1/attention/backends/` 目录下实现了后端抽象层，每个后端都继承自统一的基类接口。这种设计允许在运行时根据硬件能力和配置选择合适的实现。\n\n```mermaid\ngraph TD\n A[Attention Layer] --> B[Attention Backend Selector]\n B --> C[FlashAttention Backend]\n B --> D[FlashInfer Backend]\n B --> E[其他后端...]\n C --> F[CUDA FlashAttention]\n D --> G[FlashInfer Kernel]\n```\n\n### 核心接口定义\n\n每个注意力后端需要实现以下核心方法：\n\n| 方法名 | 功能描述 |\n|--------|----------|\n| `forward()` | 执行注意力前向计算 |\n| `init_backend()` | 初始化后端资源 |\n| `get_name()` | 返回后端名称标识 |\n| `get_supported_dtypes()` | 获取支持的数据类型列表 |\n\n资料来源：[vllm/v1/attention/backends/flash_attn.py:1-100]()\n\n## 后端实现\n\n### FlashAttention 后端\n\nFlashAttention 是一种高效的注意力实现，通过分块计算和融合核（fused kernel）显著减少内存访问，提升计算吞吐量。\n\nFlashAttention 后端的主要特性：\n\n- 支持 FP16、BF16 数据类型\n- 通过 CUDA 核心实现分块矩阵乘法\n- 自动处理序列长度大于 GPU 限制的情况（通过 Flash Attention 2/3 的支持）\n- 与 vLLM 的 Paged Attention 机制无缝集成\n\n```python\n# FlashAttention 后端核心逻辑示意\nclass FlashAttentionBackend:\n def __init__(self, num_heads: int, head_dim: int, scale: float):\n self.num_heads = num_heads\n self.head_dim = head_dim\n self.scale = scale\n \n def forward(self, query, key, value, cu_seqlen_q, cu_seqlen_k):\n # 使用 CUDA Flash Attention 内核计算\n return flash_attn_varlen_func(\n query, key, value,\n cu_seqlen_q, cu_seqlen_k,\n self.scale\n )\n```\n\n资料来源：[vllm/v1/attention/backends/flash_attn.py:1-150]()\n\n### FlashInfer 后端\n\nFlashInfer 是另一种高性能注意力库，特别针对推理场景优化，提供更低的延迟和更好的吞吐。\n\nFlashInfer 后端的特点：\n\n- 针对推理工作负载优化\n- 支持增量解码（Incremental Decoding）\n- 与 PagedAttention 深度集成\n- 支持连续批处理（Continuous Batching）\n\n```python\n# FlashInfer 后端核心逻辑示意\nclass FlashInferBackend:\n def forward(self, query, key, value, paged_kv_cache, ...):\n # 使用 FlashInfer 核函数\n return flashinfer.attention(\n query, paged_kv_cache,\n ...\n )\n```\n\n资料来源：[vllm/v1/attention/backends/flashinfer.py:1-100]()\n\n## 后端选择机制\n\n### 动态选择器\n\nvLLM 提供了智能的后端选择器（Attention Selector），根据系统环境和配置自动选择最优的注意力后端。选择逻辑位于 `vllm/v1/attention/selector.py` 文件中。\n\n```mermaid\ngraph TD\n A[启动时检测] --> B{检查用户配置}\n B -->|明确指定| C[使用指定后端]\n B -->|未指定| D[检测 GPU 能力]\n D --> E{FlashInfer 可用?}\n E -->|是| F[优先选择 FlashInfer]\n E -->|否| G{FlashAttention 可用?}\n G -->|是| H[选择 FlashAttention]\n G -->|否| I[降级到基础实现]\n```\n\n### 选择优先级\n\n| 优先级 | 后端 | 条件 |\n|--------|------|------|\n| 1 | FlashInfer | GPU 支持且已安装 |\n| 2 | FlashAttention | CUDA 版本兼容 |\n| 3 | 基础实现 | 无其他选项时的兜底方案 |\n\n资料来源：[vllm/v1/attention/selector.py:1-80]()\n\n## 分页注意力机制\n\n### Paged Attention 概述\n\nPagedAttention 是 vLLM 的核心创新之一，通过将 KV 缓存分页存储在 GPU 内存中，显著提高内存利用率，支持更大的并发批处理。\n\n### 核心数据结构\n\n```mermaid\ngraph LR\n A[逻辑 KV Cache] -->|映射| B[物理块]\n A[Query] --> C[注意力计算]\n B --> C\n```\n\nPagedAttention 使用块表（Block Table）来管理逻辑块到物理块的映射关系。每个请求的 KV 缓存被分割成固定大小的块（通常为 16 或 32 个 token），存储在非连续的物理内存位置。\n\n### 块表结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `physical_blocks` | List[int] | 物理块编号列表 |\n| `num_blocks` | int | 块数量 |\n| `block_size` | int | 每个块的 token 数量 |\n\n资料来源：[vllm/v1/attention/ops/paged_attn.py:1-120]()\n\n## 配置与使用\n\n### 命令行配置\n\n用户可以通过命令行参数指定注意力后端：\n\n```bash\nvllm serve --attention-backend flashinfer\n```\n\n支持的参数值：\n- `auto` - 自动选择最优后端（默认）\n- `flash_attn` - 强制使用 FlashAttention\n- `flashinfer` - 强制使用 FlashInfer\n\n### 编程接口配置\n\n在 Python 代码中配置注意力后端：\n\n```python\nfrom vllm import LLM, SamplingParams\n\nllm = LLM(\n model=\"Qwen/Qwen2.5-3B-Instruct\",\n attention_backend=\"flashinfer\" # 指定后端\n)\n```\n\n### 环境变量\n\n| 环境变量 | 作用 |\n|----------|------|\n| `VLLM_ATTENTION_BACKEND` | 覆盖默认后端选择 |\n\n## 性能特性对比\n\n| 特性 | FlashAttention | FlashInfer |\n|------|-----------------|------------|\n| 首次 token 延迟 | 中等 | 低 |\n| 解码吞吐 | 高 | 更高 |\n| 内存效率 | 高 | 极高 |\n| 连续批处理 | 支持 | 深度优化 |\n| 适用场景 | 通用推理 | 生产级推理 |\n\n## 扩展新的注意力后端\n\n如需为 vLLM 添加新的注意力后端，需要：\n\n1. 在 `vllm/v1/attention/backends/` 下创建新的 Python 模块\n2. 实现 `AttentionBackend` 基类定义的所有接口\n3. 在 `selector.py` 中注册新的后端和选择逻辑\n4. 在配置选项中添加新后端的支持\n\n```python\n# 新后端模板\nclass NewAttentionBackend(AttentionBackend):\n def __init__(self, num_heads: int, head_dim: int, scale: float):\n self.num_heads = num_heads\n self.head_dim = head_dim\n self.scale = scale\n \n @staticmethod\n def get_name() -> str:\n return \"new_backend\"\n \n @staticmethod\n def get_supported_dtypes() -> List[torch.dtype]:\n return [torch.float16, torch.bfloat16]\n \n def forward(self, ...):\n # 实现注意力计算\n pass\n```\n\n## 注意事项\n\n- 确保 GPU 驱动和 CUDA 版本与所选后端兼容\n- FlashInfer 后端需要单独安装：`pip install flashinfer`\n- 在多 GPU 场景下，后端选择需要考虑 NCCL 通信开销\n- 某些特殊模型架构可能需要特定后端才能正常工作\n\n---\n\n\n\n## 量化支持\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [vllm/model_executor/layers/quantization/fp8.py](https://github.com/vllm-project/vllm/blob/main/vllm/model_executor/layers/quantization/fp8.py)\n- [vllm/model_executor/layers/quantization/gptq.py](https://github.com/vllm-project/vllm/blob/main/vllm/model_executor/layers/quantization/gptq.py)\n- [vllm/model_executor/layers/quantization/awq.py](https://github.com/vllm-project/vllm/blob/main/vllm/model_executor/layers/quantization/awq.py)\n- [vllm/model_executor/layers/quantization/gguf.py](https://github.com/vllm-project/vllm/blob/main/vllm/model_executor/layers/quantization/gguf.py)\n- [vllm/model_executor/layers/quantization/compressed_tensors/compressed_tensors.py](https://github.com/vllm-project/vllm/blob/main/vllm/model_executor/layers/quantization/compressed_tensors/compressed_tensors.py)\n- [examples/basic/offline_inference/README.md](https://github.com/vllm-project/vllm/blob/main/examples/basic/offline_inference/README.md)\n- [csrc/quantization](https://github.com/vllm-project/vllm/blob/main/csrc/quantization)\n \n\n# 量化支持\n\n## 概述\n\nvLLM 的量化支持模块位于 `vllm/model_executor/layers/quantization/` 目录下，提供多种权重量化方案以降低模型内存占用和提升推理效率。该模块实现了统一的量化接口规范，支持 FP8、GPTQ、AWQ、GGUF 和 Compressed Tensors 等主流量化格式。\n\n量化层的核心设计采用策略模式（Strategy Pattern），通过抽象基类定义标准接口，不同量化算法作为独立实现类存在。这种架构允许用户通过 `--quantization` 参数灵活选择量化方案，同时保持核心推理逻辑的一致性。\n\n---\n\n## 支持的量化格式\n\n### 量化格式对比表\n\n| 量化格式 | 类型 | 精度损失 | 加速效果 | 使用场景 |\n|---------|------|---------|---------|---------|\n| FP8 | 动态量化 | 低 | 中等 | 通用推理，适合 Hopper/Ada 架构 |\n| GPTQ | 静态量化 | 中等 | 高 | 4-bit 量化，GPU 部署 |\n| AWQ | 静态量化 | 低 | 高 | 4-bit 量化，自动权重排序 |\n| GGUF | 静态量化 | 可调 | 高 | CPU/GPU 混合推理 |\n| Compressed Tensors | 通用格式 | 可调 | 依赖实现 | 高度自定义的压缩方案 |\n\n---\n\n## 架构设计\n\n### 模块结构\n\n```\nvllm/model_executor/layers/quantization/\n├── __init__.py\n├── fp8.py # FP8 量化实现\n├── gptq.py # GPTQ 量化实现\n├── awq.py # AWQ 量化实现\n├── gguf.py # GGUF 量化实现\n├── compressed_tensors/ # Compressed Tensors 量化实现\n│ └── compressed_tensors.py\n└── utils.py # 量化工具函数\n```\n\n### 类层次结构\n\n```mermaid\ngraph TD\n A[QuantizationConfig] --> B[FP8Config]\n A --> C[GPTQConfig]\n A --> D[AWQConfig]\n A --> E[GGUFConfig]\n A --> F[CompressedTensorsConfig]\n \n G[QuantizationMethods] --> H[FP8Methods]\n G --> I[GPTQMethods]\n G --> J[AWQMethods]\n G --> K[GGUFMethods]\n G --> L[CompressedTensorsMethods]\n```\n\n---\n\n## FP8 量化\n\n### 概述\n\nFP8（8-bit Floating Point）量化是一种混合精度方案，在 H100/H200 等新架构 GPU 上可获得显著加速。vLLM 支持 FP8_E4M3 和 FP8_E5M2 两种格式。\n\n### 核心实现\n\nFP8 量化模块（`vllm/model_executor/layers/quantization/fp8.py`）实现了以下关键功能：\n\n- **动态范围计算**：根据权重分布自动确定缩放因子\n- **E4M3/E5M2 支持**：可配置 FP8 格式\n- **Kernel 优化**：利用 TensorCore 进行高效计算\n\n### 配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| fp8_format | str | \"hybrid\" | 量化格式：\"fp8_e4m3fn\" 或 \"fp8_e5m2\" |\n| activation_scheme | str | \"dynamic\" | 激活值量化策略 |\n\n---\n\n## GPTQ 量化\n\n### 概述\n\nGPTQ（Generative Pretrained Transformer Quantization）是一种 Post-Training Quantization（PTQ）方法，支持 4-bit 权重量化，显著降低显存占用。\n\n### 核心实现\n\nGPTQ 量化模块（`vllm/model_executor/layers/quantization/gptq.py`）包含：\n\n- **分组量化**：将权重分组处理，每组独立的缩放因子和零点\n- **GPTQ 校准**：使用校准数据集确定最优量化参数\n- **高度优化的 CUDA Kernel**：针对批量推理优化\n\n### 模型加载\n\n使用 GPTQ 量化模型时，需要指定量化位宽：\n\n```bash\nvllm serve --quantization gptq --quantization_param_path \n```\n\n---\n\n## AWQ 量化\n\n### 概述\n\nAWQ（Activation-Aware Weight Quantization）是一种改进的权重量化方案，通过分析激活值分布来选择重要权重进行保护，降低精度损失。\n\n### 核心实现\n\nAWQ 量化模块（`vllm/model_executor/layers/quantization/awq.py`）实现：\n\n- **重要性权重排序**：根据激活值分布识别关键权重\n- **混合精度策略**：对重要权重使用更高精度\n- **自动平滑因子计算**：减少量化误差\n\n---\n\n## GGUF 量化\n\n### 概述\n\nGGUF 是 llama.cpp 项目开发的量化格式，vLLM 通过 GGUF 量化模块（`vllm/model_executor/layers/quantization/gguf.py`）提供原生支持。GGUF 支持多种量化位宽（Q2_K、Q4_0、Q4_K、Q5_K、Q6_K、Q8_0 等），用户可以通过 `repo_id:quant_type` 格式直接从 HuggingFace 加载量化模型。\n\n### 使用方式\n\n```bash\npython examples/basic/offline_inference/generate.py \\\n --model unsloth/Qwen3-0.6B-GGUF:Q4_K_M \\\n --tokenizer Qwen/Qwen3-0.6B\n```\n\n### GGUF 量化类型\n\n| 类型 | 位宽 | 内存节省 | 精度 |\n|------|------|---------|------|\n| Q2_K | 2-bit | ~75% | 较低 |\n| Q4_0 | 4-bit | ~60% | 中等 |\n| Q4_K | 4-bit | ~60% | 较好 |\n| Q5_K | 5-bit | ~50% | 良好 |\n| Q6_K | 6-bit | ~40% | 优秀 |\n| Q8_0 | 8-bit | ~20% | 几乎无损 |\n\n---\n\n## Compressed Tensors 量化\n\n### 概述\n\nCompressed Tensors 是一个通用的压缩格式框架，允许高度自定义的量化方案，支持非均匀量化和结构化稀疏。\n\n### 核心实现\n\n`vllm/model_executor/layers/quantization/compressed_tensors/compressed_tensors.py` 模块提供：\n\n- **动态压缩方案**：支持任意量化策略\n- **元数据管理**：存储压缩所需的元信息\n- **混合精度组合**：支持不同层使用不同精度\n\n---\n\n## CUDA Kernel 实现\n\n### 量化计算位置\n\n量化相关的 CUDA Kernel 实现位于 `csrc/quantization/` 目录下，包含：\n\n- FP8 矩阵乘法 kernel\n- GPTQ 反量化 kernel\n- AWQ 量化/反量化 kernel\n- GGUF 解压缩 kernel\n\n### 优化策略\n\n```mermaid\ngraph LR\n A[模型权重] --> B[量化压缩]\n B --> C[存储/传输]\n C --> D[推理时反量化]\n D --> E[FP32/FP16 计算]\n E --> F[输出]\n```\n\n---\n\n## 使用示例\n\n### 命令行使用\n\n```bash\n# 启动量化模型服务\nvllm serve meta-llama/Llama-2-7b-hf --quantization fp8\n\n# 启动 GGUF 量化模型\nvllm serve mradermacher/llama-2-7b-chat-GGUF:Q4_K_M\n```\n\n### Python API 使用\n\n```python\nfrom vllm import LLM\n\n# 加载量化模型\nllm = LLM(\n model=\"meta-llama/Llama-2-7b-hf\",\n quantization=\"gptq\"\n)\n\n# 生成\noutputs = llm.generate([\"Hello, world!\"])\n```\n\n---\n\n## 注意事项\n\n1. **硬件兼容性**：FP8 需要 Hopper/Ada 架构 GPU\n2. **精度验证**：建议在生产环境前进行精度基准测试\n3. **混合量化**：同一模型可对不同层使用不同量化方案\n4. **量化校准**：静态量化需要代表性数据集进行校准\n\n---\n\n## 参考资料\n\n- vLLM 官方文档：https://docs.vllm.ai/en/latest/\n- 量化配置源码：`vllm/model_executor/layers/quantization/`\n- CUDA 实现：`csrc/quantization/`\n\n---\n\n\n\n## 推测解码\n\n### 相关页面\n\n相关主题：[V1 引擎架构](#page-v1-engine)\n\n# 推测解码\n\n> **注意**: 当前检索到的上下文内容中未包含推测解码相关的源码文件。以下文档是基于 vLLM 项目中推测解码功能的通用技术知识构建，具体的 API 参数、配置选项和行为细节需要参考实际源码文件进行验证。\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/features/speculative_decoding/README.md](https://github.com/vllm-project/vllm/blob/main/docs/features/speculative_decoding/README.md)\n- [vllm/v1/spec_decode/draft_model.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/spec_decode/draft_model.py)\n- [vllm/v1/spec_decode/eagle.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/spec_decode/eagle.py)\n- [vllm/v1/spec_decode/ngram_proposer.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/spec_decode/ngram_proposer.py)\n- [vllm/v1/spec_decode/metrics.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/spec_decode/metrics.py)\n- [vllm/config/speculative.py](https://github.com/vllm-project/vllm/blob/main/vllm/config/speculative.py)\n\n \n\n## 概述\n\n推测解码（Speculative Decoding）是 vLLM 中用于加速大语言模型推理的一种技术。该技术通过使用一个轻量级的\"草稿模型\"（Draft Model）提前生成多个候选 token，然后由原始的目标模型（Target Model）并行验证这些候选 token，从而减少自回归生成的顺序等待时间。\n\n### 核心价值\n\n- **降低延迟**: 通过并行验证减少生成 token 的平均等待时间\n- **保持输出质量**: 验证机制确保最终输出与标准自回归解码完全一致\n- **灵活的加速策略**: 支持多种草稿模型和提议策略\n\n## 工作原理\n\n推测解码的核心思想是将自回归解码过程中的顺序计算转换为\"生成-验证\"两阶段模式：\n\n1. **提议阶段（Proposal）**: 草稿模型快速生成多个候选 token\n2. **验证阶段（Verification）**: 目标模型批量验证这些候选 token 的正确性\n\n```mermaid\ngraph TD\n A[输入 Prompt] --> B[草稿模型提议]\n B --> C[生成候选 Token 序列]\n C --> D[目标模型并行验证]\n D --> E{验证结果}\n E -->|全部正确| F[接受候选序列]\n E -->|部分错误| G[回退到首个错误位置]\n F --> H[继续下一轮]\n G --> I[修正后继续生成]\n H --> B\n I --> B\n```\n\n### 验证机制\n\n目标模型对草稿模型生成的每个 token 进行验证。只有通过验证的 token 才会被接受为最终输出。如果某个 token 验证失败，系统会回退到该位置，使用目标模型生成的结果替换草稿模型的错误预测。\n\n## 架构设计\n\n### 核心组件\n\n| 组件 | 职责 | 源码位置 |\n|------|------|----------|\n| 推测解码配置 | 管理推测解码相关参数 | `vllm/config/speculative.py` |\n| 草稿模型接口 | 定义草稿模型的标准接口 | `vllm/v1/spec_decode/draft_model.py` |\n| 提议器实现 | 具体实现不同类型的提议策略 | `vllm/v1/spec_decode/` |\n| 指标收集 | 跟踪推测解码性能指标 | `vllm/v1/spec_decode/metrics.py` |\n\n### 提议策略类型\n\nvLLM 支持多种推测解码提议策略：\n\n1. **Ngram 提议器（Ngram Proposer）**\n - 基于 n-gram 统计的简单提议策略\n - 无需额外训练模型\n - 适用于快速原型验证\n\n2. **EAGLE 提议器**\n - 使用自回归方式生成候选 token\n - 可配合小型语言模型使用\n - 支持更复杂的语义预测\n\n3. **自定义提议器**\n - 通过插件机制扩展\n - 支持用户自定义草稿模型\n\n## 配置参数\n\n推测解码的主要配置参数定义在 `vllm/config/speculative.py` 中：\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `speculative_model` | str | 草稿模型的名称或路径 | - |\n| `num_speculative_tokens` | int | 每轮提议的 token 数量 | 1 |\n| `speculative_draft_tensor_parallel_size` | int | 草稿模型的张量并行大小 | 1 |\n| `speculative_disable_by_num_cached_sequences` | int | 缓存序列数超过此值时禁用推测 | - |\n\n## 使用方法\n\n### 命令行启动\n\n使用 `vllm serve` 命令启动带推测解码的服务：\n\n```bash\nvllm serve \\\n --speculative-model \\\n --num-speculative-tokens 5\n```\n\n### Python API\n\n```python\nfrom vllm import LLM\n\nllm = LLM(\n model=\"meta-llama/Llama-2-70b-chat-hf\",\n speculative_model=\"meta-llama/Llama-2-7b-chat-hf\",\n num_speculative_tokens=5,\n tensor_parallel_size=2\n)\n```\n\n## 性能指标\n\n推测解码的效率通过以下指标衡量：\n\n| 指标 | 说明 |\n|------|------|\n| 接受率 | 草稿模型生成的 token 被目标模型接受的比例 |\n| 加速比 | 推测解码相对于标准自回归解码的速度提升 |\n| Token 吞吐量 | 每秒处理的 token 数量 |\n\n这些指标由 `vllm/v1/spec_decode/metrics.py` 模块收集和计算。\n\n## 限制与注意事项\n\n1. **GPU 内存**: 草稿模型会占用额外的 GPU 显存\n2. **接受率依赖**: 加速效果高度依赖于草稿模型与目标模型输出的一致性\n3. **不支持的场景**: 某些特殊的采样参数（如某些类型的 logits warper）可能与推测解码不兼容\n4. **分布式部署**: 草稿模型和目标模型的并行策略需要协调配置\n\n## 相关文档\n\n- [推测解码功能文档](https://docs.vllm.ai/en/latest/features/speculative_decoding.html)\n- [vLLM 官方文档](https://docs.vllm.ai)\n\n---\n\n\n\n## 分布式并行策略\n\n### 相关页面\n\n相关主题：[架构概览](#page-arch-overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/serving/parallelism_scaling.md](https://github.com/vllm-project/vllm/blob/main/docs/serving/parallelism_scaling.md)\n- [vllm/distributed/parallel_state.py](https://github.com/vllm-project/vllm/blob/main/vllm/distributed/parallel_state.py)\n- [vllm/distributed/device_communicators/cuda_communicator.py](https://github.com/vllm-project/vllm/blob/main/vllm/distributed/device_communicators/cuda_communicator.py)\n- [vllm/config/parallel.py](https://github.com/vllm-project/vllm/blob/main/vllm/config/parallel.py)\n- [vllm/distributed/elastic_ep](https://github.com/vllm-project/vllm/blob/main/vllm/distributed/elastic_ep)\n \n\n# 分布式并行策略\n\n## 概述\n\nvLLM 是一个高性能的大语言模型推理服务框架，支持多种分布式并行策略以满足不同规模和场景的部署需求。这些并行策略包括数据并行（Data Parallelism）、张量并行（Tensor Parallelism）、流水线并行（Pipeline Parallelism）以及它们的组合形式。通过灵活配置这些并行策略，vLLM 能够有效利用多 GPU 和多节点集群的计算资源，实现大规模模型的高效推理。\n\nvLLM 的分布式并行策略建立在 PyTorch 分布式通信原语之上，并针对 LLM 推理的工作负载特征进行了深度优化。其核心设计理念是在保证推理正确性的前提下，最大化 GPU 利用率和吞吐量，同时最小化通信开销。\n\n## 核心并行模式\n\n### 张量并行（Tensor Parallelism, TP）\n\n张量并行是一种将模型的单个层的权重矩阵沿行或列方向切分到多个 GPU 上的技术。在 LLM 中，这通常应用于注意力机制和前馈网络层。每个 GPU 持有完整输入的一部分和部分权重，通过集合通信操作（如 AllReduce）聚合结果。\n\n张量并行的主要优势在于能够将单个层的计算分布到多个设备上，从而支持超出单个 GPU 显存限制的模型。vLLM 采用了 Megatron-LM 风格的张量并行实现，支持 2、4、8 等多种并行度配置。\n\n### 流水线并行（Pipeline Parallelism, PP）\n\n流水线并行将模型的不同层组分配到不同的 GPU 上。每个 GPU 负责模型的一个连续子集，形成计算流水线。这种策略特别适合多节点场景，能够有效减少节点间的通信开销。\n\nvLLM 支持微批处理（micro-batching）来提高流水线并行下的 GPU 利用率，减少流水线气泡（pipeline bubble）。流水线并行通常与张量并行结合使用，形成 3D 并行（TP + PP + DP）。\n\n### 数据并行（Data Parallelism, DP）\n\n数据并行是最简单的并行策略，每个 GPU 持有模型权重的完整副本，独立处理不同的输入批次。vLLM 的数据并行实现支持多种负载均衡模式，包括外部负载均衡（External LB）和混合负载均衡（Hybrid LB）。\n\n在数据并行模式下，vLLM 通过分片 KV 缓存管理来支持多副本推理，提高系统吞吐量。数据并行可以与张量并行和流水线并行叠加使用，形成混合并行配置。\n\n## 分布式并行配置\n\n### 并行配置参数\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `tensor-parallel-size` | int | 张量并行度 | 1 |\n| `pipeline-parallel-size` | int | 流水线并行度 | 1 |\n| `data-parallel-size` | int | 数据并行度 | 1 |\n| `data-parallel-external-lb` | bool | 启用外部负载均衡 | False |\n| `data-parallel-hybrid-lb` | bool | 启用混合负载均衡 | False |\n| `data-parallel-start-rank` | int | 混合负载均衡起始节点 | 0 |\n\n### 启动命令示例\n\n```bash\nvllm serve Qwen/Qwen2.5-3B-Instruct \\\n --tensor-parallel-size 4 \\\n --pipeline-parallel-size 2 \\\n --data-parallel-size 2\n```\n\n上述命令配置了 4x2x2 = 16 GPU 的混合并行拓扑，适用于大规模模型部署场景。\n\n## 架构设计\n\n### 分布式并行状态管理\n\nvLLM 通过 `parallel_state.py` 模块管理分布式并行状态。该模块负责初始化和协调各并行维度的通信组，建立 GPU 之间的拓扑关系，并提供进程组查询接口。\n\n```mermaid\ngraph TD\n A[全局初始化] --> B[创建通信组]\n B --> C[张量并行组 TP]\n B --> D[流水线并行组 PP]\n B --> E[数据并行组 DP]\n C --> F[AllReduce 通信]\n D --> G[流水线调度]\n E --> H[数据分片]\n F --> I[聚合结果]\n G --> I\n H --> I\n```\n\n### 设备通信层\n\n`cuda_communicator.py` 实现了针对 NVIDIA GPU 优化的集合通信操作。该模块封装了 PyTorch 分布式通信原语，提供了高效的 AllReduce、Broadcast、AllGather 等操作实现。通信层针对 LLM 推理的通信模式进行了优化，最小化了流水线气泡和通信延迟。\n\n### 弹性并行（Elastic EP）\n\nvLLM 支持弹性并行（Elastic EP），允许在运行时动态调整数据并行组的规模。这一特性通过 `vllm/distributed/elastic_ep` 模块实现，提供了容错能力和弹性扩展能力。当集群中的部分节点发生故障或新增时，系统能够自动重新配置数据并行组，无需中断服务。\n\n## 分片 KV 缓存管理\n\n分片 KV 缓存是 vLLM 实现高效数据并行的关键技术之一。在传统的数据并行中，所有副本需要共享或复制 KV 缓存，导致显存浪费或同步开销。vLLM 通过将 KV 缓存按注意力头维度分片，让每个数据并行副本持有 KV 缓存的不同部分。\n\n这种方法的优势在于：\n\n- 减少每个副本的 KV 缓存显存占用\n- 支持更大的批量处理\n- 通过 PagedAttention 技术实现细粒度的显存管理\n- 支持 Prefix Caching 以加速重复前缀的推理\n\n## 通信优化\n\n### CUDA 通信优化\n\nvLLM 的设备通信层利用 CUDA 的高效内存复制和集合操作，减少 GPU 间通信延迟。通信操作与计算重叠执行，通过异步执行和流水线技术隐藏通信开销。\n\n### 流水线气泡优化\n\n在流水线并行中，vLLM 采用微批处理策略来减少流水线气泡。通过将每个批次划分为多个微批次，系统能够更充分地利用流水线各阶段的 GPU 资源，提高整体吞吐量。\n\n## 监控与调优\n\n### 性能指标\n\nvLLM 提供了丰富的分布式并行性能指标，包括：\n\n| 指标 | 说明 |\n|------|------|\n| GPU 利用率 | 各 GPU 的计算利用率 |\n| 通信带宽 | GPU 间通信的实际带宽 |\n| 流水线气泡率 | 流水线空闲时间占比 |\n| 吞吐量 | 每秒处理的请求数 |\n\n### 分布式追踪\n\nvLLM 支持 OpenTelemetry 分布式追踪，能够追踪请求在多个 GPU 和节点间的处理路径。这对于诊断分布式并行下的性能瓶颈和通信问题非常重要。\n\n配置示例：\n\n```bash\nopentelemetry-instrument vllm serve facebook/opt-125m\n```\n\n## 最佳实践\n\n### 并行度选择\n\n- **单节点多卡**：推荐使用张量并行（TP=2/4/8），根据显存和模型大小调整\n- **多节点部署**：推荐 TP × PP × DP 混合并行，充分利用节点内高带宽和节点间网络\n- **大批量推理**：增加数据并行度，提高系统吞吐量\n\n### 配置建议\n\n- 确保 NVLink 连接用于张量并行通信\n- 流水线并行的节点间网络带宽应足够高\n- 数据并行适用于无状态或状态可分片的模型\n\n## 参考资料\n\n- 张量并行实现：[vllm/distributed/parallel_state.py]()\n- 设备通信层：[vllm/distributed/device_communicators/cuda_communicator.py]()\n- 并行配置：[vllm/config/parallel.py]()\n- 弹性并行：[vllm/distributed/elastic_ep]()\n- 官方文档：[docs/serving/parallelism_scaling.md]()\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：vllm-project/vllm\n\n摘要：发现 21 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: Qwen3.5-397B-NVFP4 Disagg accuracy gsm8k collapses with async scheduling。\n\n## 1. 安装坑 · 来源证据：[Bug]: Qwen3.5-397B-NVFP4 Disagg accuracy gsm8k collapses with async scheduling\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Qwen3.5-397B-NVFP4 Disagg accuracy gsm8k collapses with async scheduling\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1a71634c530044a68b9160080d55de0a | https://github.com/vllm-project/vllm/issues/42182 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：[Bug]: vLLM v1 with prefix caching: first request differs from subsequent identical requests at temperature=0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: vLLM v1 with prefix caching: first request differs from subsequent identical requests at temperature=0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_58327949a4524ed082bd189b53f713a1 | https://github.com/vllm-project/vllm/issues/40896 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：[Usage]: How to proactively clear CPU-resident memory left behind by unloaded LoRA adapters after calling `/v1/unload_l…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Usage]: How to proactively clear CPU-resident memory left behind by unloaded LoRA adapters after calling `/v1/unload_lora_adapter`?\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fb1461834fe34049bd05182574d3e5e5 | https://github.com/vllm-project/vllm/issues/42207 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：v0.18.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.18.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_317a03f9de4e459f9be42064c7318b2c | https://github.com/vllm-project/vllm/releases/tag/v0.18.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 能力坑 · 来源证据：[Feature]: Qwen3.5-Moe LoRA Support (experts)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：[Feature]: Qwen3.5-Moe LoRA Support (experts)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2d068d43c6654f3cab6b48bf98dad116 | https://github.com/vllm-project/vllm/issues/40005 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:599547518 | https://github.com/vllm-project/vllm | README/documentation is current enough for a first validation pass.\n\n## 7. 运行坑 · 来源证据：v0.20.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.20.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ecf37722dff6494c82b384225e34bcb0 | https://github.com/vllm-project/vllm/releases/tag/v0.20.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:599547518 | https://github.com/vllm-project/vllm | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:599547518 | https://github.com/vllm-project/vllm | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:599547518 | https://github.com/vllm-project/vllm | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 11. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:599547518 | https://github.com/vllm-project/vllm | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 来源证据：[Bug]: ngram speculative decoding changes greedy output on Qwen3-0.6B / A100\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: ngram speculative decoding changes greedy output on Qwen3-0.6B / A100\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9ce279a037934e8085332120bfdaca86 | https://github.com/vllm-project/vllm/issues/41758 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 13. 安全/权限坑 · 来源证据：v0.16.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.16.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_57ff11ff995a4809a33a38ff7504a5ef | https://github.com/vllm-project/vllm/releases/tag/v0.16.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：v0.17.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.17.0\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4592ced4fde24aa9aa808caa40e25b84 | https://github.com/vllm-project/vllm/releases/tag/v0.17.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：v0.18.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.18.0\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7ca09904f8164e94a3a1bc489d32d1ff | https://github.com/vllm-project/vllm/releases/tag/v0.18.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：v0.19.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.19.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cdb0d7a7f491474da7b93583ec643c00 | https://github.com/vllm-project/vllm/releases/tag/v0.19.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：v0.19.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.19.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8c2ec43cf6f147d49f80f22bcd199e8f | https://github.com/vllm-project/vllm/releases/tag/v0.19.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 18. 安全/权限坑 · 来源证据：v0.20.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.20.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c867dafed19f4b97978d637aea4c7308 | https://github.com/vllm-project/vllm/releases/tag/v0.20.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v0.20.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.20.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dc6a717c695b47838899da8c9791f907 | https://github.com/vllm-project/vllm/releases/tag/v0.20.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:599547518 | https://github.com/vllm-project/vllm | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:599547518 | https://github.com/vllm-project/vllm | release_recency=unknown\n\n\n",
"markdown_key": "vllm",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:599547518",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/vllm-project/vllm"
},
{
"evidence_id": "art_bebf82825fe1411683aeb7967778e694",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/vllm-project/vllm#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "vllm 说明书",
"toc": [
"https://github.com/vllm-project/vllm 项目说明书",
"目录",
"项目介绍",
"1 项目概述",
"2 技术架构",
"3 主要功能特性",
"4 应用场景",
"5 依赖技术栈",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": false,
"repo_commit": null,
"repo_inspection_error": null,
"repo_inspection_files": [],
"repo_inspection_verified": false,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# vllm - Doramagic AI Context Pack\n\n> 定位：给用户宿主 AI 装载的开工前上下文。它不代表已经安装、运行或验证目标项目。\n\n## 项目\n\n- canonical_name: `vllm-project/vllm`\n- capability: A high-throughput and memory-efficient inference and serving engine for LLMs\n- expected_user_outcome: A high-throughput and memory-efficient inference and serving engine for LLMs\n\n## 基础边界\n\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 项目事实必须来自 repo evidence、Claim Graph 或明确来源。\n- 遇到未验证能力时，必须标记为待验证，而不是补全为事实。\n- publish_status: `publishable`\n- blocking_gaps: none\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目介绍**：importance `high`\n - source_paths: README.md, vllm/__init__.py, vllm/version.py\n- **安装指南**：importance `high`\n - source_paths: setup.py, docs/getting_started/installation/README.md, requirements/common.txt, requirements/cuda.txt\n- **架构概览**：importance `high`\n - source_paths: docs/design/arch_overview.md, vllm/engine/llm_engine.py, vllm/engine/arg_utils.py\n- **V1 引擎架构**：importance `high`\n - source_paths: vllm/v1/engine/core.py, vllm/v1/engine/async_llm.py, vllm/v1/core/sched/scheduler.py, vllm/v1/sample/sampler.py, vllm/v1/core/kv_cache_manager.py\n- **引擎核心模块**：importance `medium`\n - source_paths: vllm/engine/llm_engine.py, vllm/engine/async_llm_engine.py, vllm/engine/protocol.py, vllm/v1/engine/llm_engine.py\n- **PagedAttention 与 KV 缓存管理**：importance `high`\n - source_paths: docs/design/paged_attention.md, csrc/attention/paged_attention_v1.cu, csrc/attention/paged_attention_v2.cu, vllm/v1/core/block_pool.py, vllm/v1/core/kv_cache_manager.py\n- **注意力后端**：importance `medium`\n - source_paths: docs/design/attention_backends.md, vllm/v1/attention/backends/flash_attn.py, vllm/v1/attention/backends/flashinfer.py, vllm/v1/attention/selector.py, vllm/v1/attention/ops/paged_attn.py\n- **量化支持**：importance `high`\n - source_paths: docs/features/quantization/README.md, vllm/model_executor/layers/quantization/fp8.py, vllm/model_executor/layers/quantization/gptq.py, vllm/model_executor/layers/quantization/awq.py, vllm/model_executor/layers/quantization/gguf.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: false\n- repo_inspection_verified: false\n- repo_commit: `unknown`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：[Bug]: Qwen3.5-397B-NVFP4 Disagg accuracy gsm8k collapses with async scheduling\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Qwen3.5-397B-NVFP4 Disagg accuracy gsm8k collapses with async scheduling\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_1a71634c530044a68b9160080d55de0a | https://github.com/vllm-project/vllm/issues/42182 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：[Bug]: vLLM v1 with prefix caching: first request differs from subsequent identical requests at temperature=0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: vLLM v1 with prefix caching: first request differs from subsequent identical requests at temperature=0\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_58327949a4524ed082bd189b53f713a1 | https://github.com/vllm-project/vllm/issues/40896 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：[Usage]: How to proactively clear CPU-resident memory left behind by unloaded LoRA adapters after calling `/v1/unload_l…\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Usage]: How to proactively clear CPU-resident memory left behind by unloaded LoRA adapters after calling `/v1/unload_lora_adapter`?\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_fb1461834fe34049bd05182574d3e5e5 | https://github.com/vllm-project/vllm/issues/42207 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：v0.18.1\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.18.1\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_317a03f9de4e459f9be42064c7318b2c | https://github.com/vllm-project/vllm/releases/tag/v0.18.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：[Feature]: Qwen3.5-Moe LoRA Support (experts)\n\n- Trigger: GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：[Feature]: Qwen3.5-Moe LoRA Support (experts)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_2d068d43c6654f3cab6b48bf98dad116 | https://github.com/vllm-project/vllm/issues/40005 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:599547518 | https://github.com/vllm-project/vllm | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：v0.20.2\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.20.2\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_ecf37722dff6494c82b384225e34bcb0 | https://github.com/vllm-project/vllm/releases/tag/v0.20.2 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:599547518 | https://github.com/vllm-project/vllm | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:599547518 | https://github.com/vllm-project/vllm | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 存在安全注意事项\n\n- Trigger: No sandbox install has been executed yet; downstream must verify before user use.\n- Host AI rule: 转成明确权限清单和安全审查提示。\n- Why it matters: 用户安装前需要知道权限边界和敏感操作。\n- Evidence: risks.safety_notes | github_repo:599547518 | https://github.com/vllm-project/vllm | No sandbox install has been executed yet; downstream must verify before user use.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：vllm-project/vllm\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：[Bug]: Qwen3.5-397B-NVFP4 Disagg accuracy gsm8k collapses with async scheduling（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Bug]: vLLM v1 with prefix caching: first request differs from subsequent identical requests at temperature=0（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Usage]: How to proactively clear CPU-resident memory left behind by unloaded LoRA adapters after calling `/v1/unload_l…（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：v0.18.1（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：[Feature]: Qwen3.5-Moe LoRA Support (experts)（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/vllm-project/vllm 项目说明书\n\n生成时间：2026-05-11 03:40:03 UTC\n\n## 目录\n\n- [项目介绍](#page-intro)\n- [安装指南](#page-installation)\n- [架构概览](#page-arch-overview)\n- [V1 引擎架构](#page-v1-engine)\n- [引擎核心模块](#page-engine-core)\n- [PagedAttention 与 KV 缓存管理](#page-paged-attention)\n- [注意力后端](#page-attention-backends)\n- [量化支持](#page-quantization)\n- [推测解码](#page-speculative-decoding)\n- [分布式并行策略](#page-parallelism)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[安装指南](#page-installation), [架构概览](#page-arch-overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/vllm-project/vllm/blob/main/README.md)\n- [vllm/__init__.py](https://github.com/vllm-project/vllm/blob/main/vllm/__init__.py)\n- [vllm/version.py](https://github.com/vllm-project/vllm/blob/main/vllm/version.py)\n- [vllm/engine/arg_utils.py](https://github.com/vllm-project/vllm/blob/main/vllm/engine/arg_utils.py)\n- [vllm/config.py](https://github.com/vllm-project/vllm/blob/main/vllm/config.py)\n- [vllm/entrypoints/llm.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/llm.py)\n- [setup.py](https://github.com/vllm-project/vllm/blob/main/setup.py)\n \n\n# 项目介绍\n\n## 1 项目概述\n\nvLLM（Vectorized Large Language Model）是一个高性能、易于使用的**大语言模型推理和服务框架**，旨在提供高吞吐量的 LLM 推理能力。vLLM 由 UC Berkeley、UC San Diego、University of Illinois 等知名学术机构的研究人员开发和维护，是开源社区中用于生产环境 LLM 部署的主流选择之一。\n\nvLLM 的核心目标是解决大语言模型推理过程中的**内存管理效率问题**，通过创新的 PagedAttention 技术实现 KV Cache 的高效管理，从而在有限的 GPU 显存资源下实现更高的吞吐量。资料来源：[README.md:1-20]()\n\n### 1.1 核心价值主张\n\n| 特性 | 描述 |\n|------|------|\n| 高吞吐量 | 相比传统方法提升 2-24 倍的吞吐量 |\n| 显存高效 | 通过 PagedAttention 实现精细化的显存管理 |\n| 易用性 | 提供简洁的 Python API 和 OpenAI 兼容接口 |\n| 灵活扩展 | 支持张量并行、管道并行等多种分布式策略 |\n| 广泛兼容 | 支持众多主流开源大语言模型 |\n\n### 1.2 版本信息\n\n当前稳定版本信息定义在 `vllm/version.py` 中，用于标识 vLLM 的发布版本号，便于依赖管理和版本追踪。资料来源：[vllm/version.py:1-15]()\n\n## 2 技术架构\n\n### 2.1 整体架构概览\n\nvLLM 采用分层架构设计，从上到下分为以下几个核心层次：\n\n```mermaid\ngraph TD\n A[用户接口层] --> B[LLM 入口层]\n B --> C[推理引擎层]\n C --> D[模型执行层]\n D --> E[设备抽象层]\n \n A --> A1[OpenAI 兼容 API]\n A --> A2[Python API]\n \n C --> C1[Engine Arguments]\n C --> C2[Engine Core]\n C --> C3[Async Engine]\n \n D --> D1[Model Runner]\n D --> D2[Worker]\n D --> D3[Cache Engine]\n \n E --> E1[CUDA]\n E --> E2[ROCm]\n E --> E3[CPU]\n```\n\n### 2.2 核心模块结构\n\n`vllm/__init__.py` 文件定义了包的主要导出接口，展示了 vLLM 的模块组织方式：\n\n| 模块路径 | 功能描述 |\n|----------|----------|\n| `vllm.LLM` | 主要的推理入口类 |\n| `vllm.SamplingParams` | 采样参数配置 |\n| `vllm.engine` | 推理引擎核心实现 |\n| `vllm.worker` | 模型执行工作进程 |\n| `vllm.model_executor` | 模型执行器 |\n| `vllm.config` | 配置管理 |\n| `vllm.attention` | 注意力机制实现 |\n\n资料来源：[vllm/__init__.py:1-50]()\n\n### 2.3 推理引擎架构\n\n推理引擎是 vLLM 的核心组件，负责协调整个推理流程：\n\n```mermaid\ngraph LR\n A[用户请求] --> B[Engine Arguments]\n B --> C[LLMEngine]\n C --> D[Worker Pool]\n D --> E[Model Runner]\n E --> F[Model]\n F --> G[Output]\n \n C --> H[Cache Engine]\n H --> I[KV Cache]\n \n style G fill:#90EE90\n style I fill:#87CEEB\n```\n\n**Engine Arguments** 负责解析和验证所有推理相关的配置参数，包括模型路径、采样参数、资源配置等。资料来源：[vllm/engine/arg_utils.py:1-100]()\n\n**Configuration** 模块则统一管理 vLLM 的各类配置，包括模型配置、并行配置、调度配置等，确保各组件之间的配置一致性。资料来源：[vllm/config.py:1-150]()\n\n## 3 主要功能特性\n\n### 3.1 PagedAttention\n\nPagedAttention 是 vLLM 最核心的技术创新，灵感来自操作系统的虚拟内存管理思想。它通过将 KV Cache 分页管理，避免了传统方法中连续显存分配带来的浪费问题。\n\n```mermaid\ngraph LR\n A[传统方法] -->|连续分配| B[显存碎片化]\n B --> C[显存利用率低]\n \n D[PagedAttention] -->|分页管理| E[灵活分配]\n E --> F[显存利用率高]\n \n style D fill:#90EE90\n```\n\n**技术优势：**\n\n- 将显存利用率提升至接近 100%\n- 支持高效的Prefix Caching\n- 减少显存碎片化\n- 支持弹性批处理\n\n### 3.2 并行推理策略\n\nvLLM 支持多种分布式推理策略，可以根据硬件配置灵活选择：\n\n| 并行策略 | 适用场景 | 配置参数 |\n|----------|----------|----------|\n| 张量并行 (TP) | 单机多卡 | `tensor_parallel_size` |\n| 管道并行 (PP) | 多机多卡 | `pipeline_parallel_size` |\n| 数据并行 (DP) | 多实例部署 | 启动多个进程 |\n| 专家并行 (EP) | MoE 模型 | `enable_expert_parallel` |\n\n### 3.3 模型支持\n\nvLLM 支持众多主流的开源大语言模型，涵盖以下类别：\n\n| 模型类别 | 代表模型 |\n|----------|----------|\n| Decoder-Only | Llama, GPT, Mistral, Qwen |\n| Encoder-Decoder | T5, BART |\n| 视觉语言模型 | LLaVA, Qwen-VL |\n| Mixture of Experts | Mixtral |\n\n资料来源：[setup.py:1-50]()\n\n### 3.4 推理接口\n\nvLLM 提供两类主要的推理接口：\n\n**Python API（同步）：**\n\n```python\nfrom vllm import LLM, SamplingParams\n\nllm = LLM(model=\"meta-llama/Llama-2-7b-hf\")\noutputs = llm.generate([\"Hello, world!\"], SamplingParams(temperature=0.8))\n```\n\n**异步 API：**\n\n```python\nfrom vllm import AsyncLLM\n\nasync_llm = AsyncLLM(model=\"meta-llama/Llama-2-7b-hf\")\n```\n\n**OpenAI 兼容 API：**\n\nvLLM 提供与 OpenAI API 格式完全兼容的推理服务，支持 `/v1/chat/completions` 和 `/v1/completions` 端点，便于现有应用无缝迁移。\n\n资料来源：[vllm/entrypoints/llm.py:1-100]()\n\n## 4 应用场景\n\n### 4.1 典型使用场景\n\n```mermaid\ngraph TD\n A[vLLM 部署场景] --> B[在线推理服务]\n A --> C[批量推理任务]\n A --> D[实验研究]\n A --> E[模型微调验证]\n \n B --> B1[低延迟响应]\n C --> C1[高吞吐处理]\n D --> D1[快速迭代]\n E --> E1[资源高效利用]\n```\n\n### 4.2 部署模式\n\n| 部署模式 | 特点 | 推荐配置 |\n|----------|------|----------|\n| 单机单卡 | 简单部署 | 默认配置 |\n| 单机多卡 | 高效利用 | TP=2/4/8 |\n| 多机多卡 | 大模型推理 | TP+PP |\n| 容器化部署 | 便于运维 | Docker/Kubernetes |\n\n## 5 依赖技术栈\n\n### 5.1 核心依赖\n\n| 依赖库 | 用途 |\n|--------|------|\n| PyTorch | 深度学习框架 |\n| CUDA | GPU 计算 |\n| transformers | 模型加载 |\n| flash-attn | 高效注意力计算 |\n| ray | 分布式计算 |\n\n### 5.2 硬件要求\n\n- **GPU**: NVIDIA GPU（CUDA 计算能力 ≥ 7.0）\n- **显存**: 取决于模型大小，通常至少 16GB\n- **内存**: 至少 32GB 系统内存\n- **存储**: 足够的模型权重存储空间\n\n## 6 项目发展\n\n### 6.1 发展历程\n\nvLLM 项目起源于学术研究，最初由 UC Berkeley 的研究人员提出 PagedAttention 概念，并在论文中展示了其优越性能。随着开源社区的积极参与，vLLM 逐步发展成为功能完善、性能卓越的生产级推理框架。\n\n### 6.2 社区生态\n\nvLLM 采用 Apache License 2.0 开源许可，拥有活跃的开源社区。项目持续接收来自全球开发者的贡献，不断添加新功能和优化性能。\n\n---\n\n**总结**：vLLM 是一个专为大规模语言模型设计的生产级推理框架，通过创新的 PagedAttention 技术显著提升了推理效率和显存利用率。其简洁的 API 设计、丰富的模型支持和灵活的部署方式，使其成为当前最流行的 LLM 推理框架之一。\n\n---\n\n\n\n## 安装指南\n\n### 相关页面\n\n相关主题：[项目介绍](#page-intro)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/vllm-project/vllm/blob/main/README.md)\n- [vllm/entrypoints/cli/main.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/main.py)\n- [vllm/entrypoints/cli/serve.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/serve.py)\n- [vllm/entrypoints/cli/launch.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/launch.py)\n- [examples/basic/offline_inference/README.md](https://github.com/vllm-project/vllm/blob/main/examples/basic/offline_inference/README.md)\n \n\n# 安装指南\n\n## 概述\n\nvLLM 是一个高性能的大语言模型（LLM）推理和服务框架，旨在为用户提供快速、经济高效的 LLM 服务。本页面详细介绍 vLLM 的安装方法、依赖要求、环境配置以及各种部署场景的安装步骤。\n\nvLLM 支持多种安装方式，包括 pip 安装、Docker 部署、源码编译等。用户可以根据自己的硬件环境（CUDA GPU、CPU 等）选择最适合的安装方式。框架采用模块化设计，通过灵活的参数配置支持不同的推理场景。\n\n## 系统要求\n\n### 硬件要求\n\n| 组件类型 | 最低要求 | 推荐配置 |\n|---------|---------|---------|\n| GPU | NVIDIA GPU with CUDA support | NVIDIA A100/H100 |\n| 显存 | 8GB | 24GB+ |\n| 内存 | 16GB | 32GB+ |\n| 存储 | 50GB SSD | 100GB+ NVMe SSD |\n\n### 软件环境\n\nvLLM 支持多种 Python 版本和 CUDA 版本。安装前请确保系统已安装以下软件：\n\n- Python 3.8 - 3.11\n- CUDA Toolkit 11.8 或更高版本\n- cuDNN 8.x 或更高版本\n- NVIDIA Driver 450.80.02 或更高版本\n\n## 安装方式\n\n### 方式一：使用 pip 安装（推荐）\n\n使用 pip 是最简单快速的安装方式，适合大多数用户场景。\n\n```bash\n# 标准安装\npip install vllm\n\n# 包含所有可选依赖的完整安装\npip install vllm[all]\n```\n\npip 安装方式会自动处理 vLLM 的核心依赖，包括 PyTorch、Transformers 等关键库。此方式适合快速原型开发和测试环境部署。\n\n### 方式二：Docker 安装\n\nDocker 安装提供了隔离的运行环境，可以避免依赖冲突问题。vLLM 官方提供了预配置好的 Docker 镜像。\n\n```bash\n# 拉取最新稳定版镜像\ndocker pull vllm/vllm:latest\n\n# 运行容器\ndocker run --gpus all \\\n -v ~/.cache/huggingface:/root/.cache/huggingface \\\n --runtime nvidia \\\n -p 8000:8000 \\\n vllm/vllm:latest \\\n --model meta-llama/Llama-2-7b-hf\n```\n\n资料来源：[README.md:1-15]()\n\nDocker 部署的优势在于环境一致性高，部署迁移方便，适合生产环境使用。镜像已预装所有必要的 CUDA 驱动和依赖库。\n\n### 方式三：源码编译安装\n\n对于需要自定义配置或参与 vLLM 开发的用户，可以选择源码编译安装。\n\n```bash\n# 克隆仓库\ngit clone https://github.com/vllm-project/vllm.git\ncd vllm\n\n# 安装依赖\npip install -e .\n\n# 或使用高级构建选项\npip install -e . --verbose\n```\n\n资料来源：[vllm/entrypoints/cli/main.py:1-30]()\n\n## CLI 命令行工具\n\nvLLM 提供了功能丰富的命令行界面（CLI），通过 `vllm` 命令可以访问各种子命令。CLI 架构采用模块化设计，支持扩展新的命令。\n\n```mermaid\ngraph TD\n A[vllm CLI] --> B[main.py 入口]\n B --> C[serve 推理服务]\n B --> D[run-batch 批处理]\n B --> E[launch 启动组件]\n C --> F[FastAPI 服务]\n C --> G[gRPC 服务]\n E --> H[FastAPI 渲染服务]\n```\n\n### 基本用法\n\n```bash\n# 查看版本信息\nvllm --version\n\n# 查看帮助信息\nvllm --help\n\n# 查看特定子命令帮助\nvllm serve --help\n```\n\n### serve 子命令\n\n`serve` 子命令用于启动 LLM 推理服务，是最常用的命令之一。\n\n```bash\nvllm serve Qwen/Qwen2.5-3B-Instruct\n```\n\n资料来源：[vllm/entrypoints/cli/serve.py:1-50]()\n\n#### 常用参数\n\n| 参数 | 说明 | 默认值 |\n|-----|------|-------|\n| `--model` | 模型名称或本地路径 | Qwen/Qwen3-0.6B |\n| `--host` | 服务监听地址 | 0.0.0.0 |\n| `--port` | 服务监听端口 | 8000 |\n| `--gpu-memory-utilization` | GPU 显存利用率 | 0.9 |\n| `--max-model-len` | 最大模型上下文长度 | 模型默认值 |\n| `--tensor-parallel-size` | 张量并行大小 | 1 |\n\n#### headless 模式\n\nheadless 模式启动时不会创建 API 服务器，适用于分布式部署场景。\n\n```bash\nvllm serve --headless\n```\n\n在此模式下，`api_server_count` 参数自动设为 0，不启动任何 API 服务器。\n\n```bash\n# 错误用法：headless 模式不能指定 api-server-count\nvllm serve --headless --api-server-count=2\n```\n\n此配置会触发参数校验错误，提示 headless 模式与 api-server-count 参数冲突。\n\n#### gRPC 服务模式\n\nvLLM 支持 gRPC 协议用于高性能内部通信。\n\n```bash\nvllm serve --grpc\n```\n\n启用 gRPC 模式时，框架会使用 uvloop 事件循环运行 gRPC 服务器。\n\n```python\nif args.grpc:\n from vllm.entrypoints.grpc_server import serve_grpc\n uvloop.run(serve_grpc(args))\n return\n```\n\n资料来源：[vllm/entrypoints/cli/serve.py:40-45]()\n\n### launch 子命令\n\n`launch` 子命令用于启动独立的组件服务。\n\n```bash\nvllm launch [options]\n```\n\n可用的组件包括：\n\n- `fastapi`：启动 FastAPI 渲染服务（无 GPU 推理）\n- 其他可扩展组件\n\n#### FastAPI 组件启动\n\n```bash\nvllm launch fastapi --host 0.0.0.0 --port 8000\n```\n\n启动流程包括以下步骤：\n\n1. **Socket 绑定**：设置服务器监听地址\n2. **构建引擎参数**：从 CLI 参数创建 AsyncEngineArgs\n3. **创建模型配置**：生成 VllmConfig 配置对象\n4. **清除量化配置**：渲染服务器不执行推理，跳过量化验证\n\n```python\nasync def run_launch_fastapi(args: argparse.Namespace) -> None:\n listen_address, sock = setup_server(args)\n engine_args = AsyncEngineArgs.from_cli_args(args)\n model_config = engine_args.create_model_config()\n model_config.quantization = None\n```\n\n资料来源：[vllm/entrypoints/cli/launch.py:60-80]()\n\n## 离线推理安装\n\nvLLM 提供了 `LLM` 类用于离线推理，即不启动独立服务器直接进行模型推理。\n\n```python\nfrom vllm import LLM\n\nllm = LLM(model=\"Qwen/Qwen2.5-3B-Instruct\")\noutputs = llm.generate(\"Hello, world!\")\n```\n\n### 基本使用示例\n\nvLLM 仓库提供了完整的离线推理示例脚本：\n\n```bash\n# 基础推理示例\npython examples/basic/offline_inference/basic.py\n\n# 聊天示例\npython examples/basic/offline_inference/chat.py\n\n# 生成示例\npython examples/basic/offline_inference/generate.py\n```\n\n资料来源：[examples/basic/offline_inference/README.md:1-30]()\n\n### 生成参数配置\n\n离线推理支持多种采样参数，可通过命令行或代码配置：\n\n| 参数 | 说明 | 示例值 |\n|-----|------|-------|\n| `max_tokens` | 最大生成 token 数 | 512 |\n| `temperature` | 采样温度 | 0.7 |\n| `top_p` | Top-p 采样阈值 | 0.9 |\n| `top_k` | Top-k 采样大小 | 50 |\n\n### 默认生成配置\n\n`--generation-config` 参数指定生成配置的加载来源：\n\n```bash\npython examples/basic/offline_inference/generate.py --generation-config auto\n```\n\n- `auto`：从模型路径加载配置\n- 文件夹路径：从指定路径加载配置\n- 未指定：使用 vLLM 默认配置\n\n> 注意：如果生成配置中指定了 `max_new_tokens`，则该值会对所有请求设置全局输出 token 限制。\n\n## GGUF 模型支持\n\nvLLM 支持加载 GGUF 量化格式的模型。使用 `repo_id:quant_type` 格式指定量化类型：\n\n```bash\n--model unsloth/Qwen3-0.6B-GGUF:Q4_K_M --tokenizer Qwen/Qwen3-0.6B\n```\n\n支持的量化类型包括 Q2_K、Q4_K_M、Q5_K_M、Q8_0 等。\n\n## CPU 卸载功能\n\nvLLM 支持 CPU 显存卸载功能，可以将部分模型权重卸载到 CPU 内存，从而在有限 GPU 显存条件下运行更大的模型。\n\n```bash\n--cpu-offload-gb 10\n```\n\n此参数可以视为增加虚拟 GPU 显存大小。例如，拥有 24GB GPU 显存并设置 `--cpu-offload-gb 10` 后，相当于拥有 34GB 显存，可以加载需要至少 26GB 显存的 13B BF16 模型。\n\n> 注意：此功能需要快速的 CPU-GPU 互联带宽，因为模型需要在运行时从 CPU 内存加载到 GPU 内存。\n\n## 验证安装\n\n安装完成后，可通过以下方式验证 vLLM 是否正常工作：\n\n```bash\n# 检查 vLLM 版本\npython -c \"import vllm; print(vllm.__version__)\"\n\n# 运行基础测试\npython -c \"\nfrom vllm import LLM\nllm = LLM(model='facebook/opt-125m')\nprint('vLLM 安装成功！')\n\"\n```\n\n## 常见问题排查\n\n### CUDA 版本不兼容\n\n如果遇到 CUDA 版本相关错误，请检查系统 CUDA 版本：\n\n```bash\nnvcc --version\n```\n\n确保 CUDA 版本符合 vLLM 的要求（CUDA 11.8+）。\n\n### GPU 显存不足\n\n- 减小 `--gpu-memory-utilization` 参数值\n- 使用更小的量化模型\n- 启用 CPU 卸载功能\n\n### 依赖冲突\n\n推荐使用虚拟环境安装 vLLM：\n\n```bash\npython -m venv vllm-env\nsource vllm-env/bin/activate\npip install vllm\n```\n\n## 下一步\n\n安装完成后，您可以：\n\n- [快速开始](quickstart.md) - 运行您的第一个 vLLM 推理\n- [服务部署](serving.md) - 启动在线推理服务\n- [API 参考](../api/) - 了解详细的 API 接口\n- [示例代码](../examples/) - 探索更多使用示例\n\n---\n\n\n\n## 架构概览\n\n### 相关页面\n\n相关主题：[V1 引擎架构](#page-v1-engine), [引擎核心模块](#page-engine-core)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [vllm/entrypoints/cli/main.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/main.py)\n- [vllm/entrypoints/cli/serve.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/serve.py)\n- [vllm/entrypoints/cli/launch.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/launch.py)\n- [vllm/engine/llm_engine.py](https://github.com/vllm-project/vllm/blob/main/vllm/engine/llm_engine.py)\n- [vllm/engine/arg_utils.py](https://github.com/vllm-project/vllm/blob/main/vllm/engine/arg_utils.py)\n- [examples/disaggregated/example_connector/README.md](https://github.com/vllm-project/vllm/blob/main/examples/disaggregated/example_connector/README.md)\n- [examples/basic/offline_inference/README.md](https://github.com/vllm-project/vllm/blob/main/examples/basic/offline_inference/README.md)\n- [examples/observability/opentelemetry/README.md](https://github.com/vllm-project/vllm/blob/main/examples/observability/opentelemetry/README.md)\n \n\n# 架构概览\n\nvLLM 是一个高效、易用、低成本的大语言模型（LLM）推理服务框架，其核心设计目标是通过创新的 PagedAttention 技术实现高效的显存管理和快速推理服务。本文档详细介绍 vLLM 的整体架构设计、核心组件及其交互关系。\n\n## 系统架构总览\n\nvLLM 采用分层架构设计，从上到下依次为：命令行入口层、服务接口层、引擎核心层和硬件适配层。这种分层设计使得各模块职责明确，便于扩展和维护。\n\n```mermaid\ngraph TD\n subgraph \"用户接口层\"\n CLI[CLI 命令行]\n API[OpenAI 兼容 API]\n Python[Python LLM 类]\n end\n \n subgraph \"服务层\"\n FastAPI[FastAPI 服务器]\n GRPC[gRPC 服务]\n Launch[Launch 组件]\n end\n \n subgraph \"引擎核心层\"\n LLMEngine[LLM Engine]\n Scheduler[调度器]\n ModelRunner[模型运行器]\n end\n \n subgraph \"硬件适配层\"\n GPU[GPU 平台]\n CPU[CPU 平台]\n Quantization[量化处理]\n end\n \n CLI --> FastAPI\n API --> FastAPI\n Python --> LLMEngine\n FastAPI --> LLMEngine\n GRPC --> LLMEngine\n Launch --> FastAPI\n LLMEngine --> Scheduler\n LLMEngine --> ModelRunner\n Scheduler --> GPU\n Scheduler --> CPU\n ModelRunner --> Quantization\n```\n\n## 命令行入口架构\n\nvLLM 提供了功能丰富的命令行接口（CLI），支持多种子命令以满足不同的使用场景。CLI 架构基于灵活的命令注册机制，各子命令模块化设计，便于扩展。\n\n### 主入口模块\n\n主入口模块位于 `vllm/entrypoints/cli/main.py`，负责整体命令行解析和命令分发：\n\n```python\n# vllm/entrypoints/cli/main.py (伪代码示例)\nparser = FlexibleArgumentParser(description=\"vLLM CLI\")\nsubparsers = parser.add_subparsers(required=False, dest=\"subparser\")\ncmds = {}\nfor cmd_module in CMD_MODULES:\n new_cmds = cmd_module.cmd_init()\n for cmd in new_cmds:\n cmd.subparser_init(subparsers).set_defaults(dispatch_function=cmd.cmd)\n cmds[cmd.name] = cmd\n```\n\n### CLI 命令体系\n\n| 命令名称 | 模块路径 | 功能说明 |\n|---------|---------|---------|\n| `serve` | `vllm/entrypoints/cli/serve.py` | 启动 HTTP API 服务器进行在线推理服务 |\n| `launch` | `vllm/entrypoints/cli/launch.py` | 启动特定组件服务（如渲染服务器） |\n| 其他命令 | 各子模块 | 通过动态加载注册 |\n\nCLI 命令初始化流程通过 `cmd_init()` 函数返回命令列表，实现动态注册机制。资料来源：[vllm/entrypoints/cli/main.py:1-40]()\n\n## 核心引擎架构\n\nLLM Engine 是 vLLM 的核心组件，负责管理模型加载、请求调度、KV 缓存管理和推理执行。引擎支持同步和异步两种运行模式。\n\n### 引擎参数配置\n\n引擎参数通过 `AsyncEngineArgs` 类进行统一管理，该类封装了所有可配置的引擎参数：\n\n```python\n# 引擎参数示例配置\nengine_args = AsyncEngineArgs.from_cli_args(args)\nmodel_config = engine_args.create_model_config()\n```\n\n关键配置参数包括：\n\n| 参数类别 | 参数名 | 说明 |\n|---------|-------|------|\n| 模型配置 | `model` | 模型名称或路径 |\n| 模型配置 | `tokenizer` | 分词器路径 |\n| 模型配置 | `trust_remote_code` | 是否信任远程代码 |\n| 推理配置 | `tensor_size` | 张量并行数 |\n| 推理配置 | `gpu_memory_utilization` | GPU 显存利用率 |\n| 推理配置 | `max_model_len` | 最大模型长度 |\n| 量化配置 | `quantization` | 量化方法（如 AWQ、GPTQ） |\n| 服务配置 | `api_server_count` | API 服务器实例数量 |\n\n资料来源：[vllm/engine/arg_utils.py](https://github.com/vllm-project/vllm/blob/main/vllm/engine/arg_utils.py)\n\n### 服务启动模式\n\nvLLM 支持多种服务启动模式，以适应不同的部署场景：\n\n```mermaid\ngraph LR\n A[CLI 启动] --> B{检查参数}\n B -->|grpc=True| C[gRPC 服务模式]\n B -->|headless=True| D[无头模式
api_server_count=0]\n B -->|标准参数| E[FastAPI 服务模式]\n \n C --> F[uvloop 事件循环]\n D --> G[仅引擎运行]\n E --> H[FastAPI + Uvicorn]\n```\n\n#### 标准服务模式\n\n标准模式通过 FastAPI 提供 OpenAI 兼容的 HTTP API 服务：\n\n```python\n# vllm/entrypoints/cli/serve.py\nfrom vllm.entrypoints.grpc_server import serve_grpc\n\nif args.headless:\n if args.api_server_count is not None and args.api_server_count > 0:\n raise ValueError(\n f\"--api-server-count={args.api_server_count} cannot be \"\n \"used with --headless\"\n )\n args.api_server_count = 0\n```\n\n#### 无头模式（Headless）\n\n无头模式下不启动任何 API 服务器，仅运行推理引擎，适用于程序化调用场景：\n\n- `api_server_count` 强制设为 0\n- 适合批处理作业\n- 减少资源开销\n\n资料来源：[vllm/entrypoints/cli/serve.py:1-50]()\n\n#### Launch 组件模式\n\nLaunch 模式用于启动特定功能组件，如渲染服务器：\n\n```python\n# vllm/entrypoints/cli/launch.py\nasync def run_launch_fastapi(args: argparse.Namespace) -> None:\n \"\"\"运行在线服务层（无 GPU 推理）\"\"\"\n listen_address, sock = setup_server(args)\n engine_args = AsyncEngineArgs.from_cli_args(args)\n model_config = engine_args.create_model_config()\n```\n\nLaunch 模式的特点：\n\n- 仅进行数据预处理，不执行模型推理\n- 清除量化配置以跳过量化数据类型验证\n- 不分配 KV 缓存\n\n资料来源：[vllm/entrypoints/cli/launch.py:1-60]()\n\n## 离线推理架构\n\nvLLM 提供离线推理能力，通过 `LLM` 类实现无需独立服务器的本地推理功能。\n\n### LLM 类接口\n\n`LLM` 类是离线推理的主要接口，支持：\n\n```python\n# 基本用法\nfrom vllm import LLM\n\nllm = LLM(\"meta-llama/Llama-2-7b-hf\")\noutputs = llm.generate(\"Hello, world!\")\n```\n\n### 支持的功能类型\n\n| 功能类型 | 说明 | 示例文件 |\n|---------|------|---------|\n| 对话生成 | Chat 格式推理 | `chat.py` |\n| 文本生成 | 标准文本补全 | `generate.py` |\n| 分类任务 | 文本分类 | `classify.py` |\n| 嵌入向量 | 向量嵌入提取 | `embed.py` |\n| 评分计算 | 文本相似度评分 | `score.py` |\n\n### 量化模型支持\n\nvLLM 支持 GGUF 量化格式的模型加载：\n\n```bash\n--model unsloth/Qwen3-0.6B-GGUF:Q4_K_M --tokenizer Qwen/Qwen3-0.6B\n```\n\n格式说明：`repo_id:quant_type`，其中 quant_type 包括 Q2_K、Q4_K_M、Q5_K_S、Q6_K 等。\n\n### CPU 卸载功能\n\n`--cpu-offload-gb` 参数允许将部分模型卸载到 CPU 内存：\n\n```bash\n--cpu-offload-gb 10 # 虚拟增加 10GB GPU 显存\n```\n\n这使得在显存较小的 GPU 上运行更大规模的模型成为可能。\n\n资料来源：[examples/basic/offline_inference/README.md](https://github.com/vllm-project/vllm/blob/main/examples/basic/offline_inference/README.md)\n\n## 分离式 Prefill 架构\n\nvLLM 支持分离式 Prefill 架构，将预填充阶段和解码阶段部署在不同的实例上，以优化大规模部署的资源利用率。\n\n### 架构设计\n\n```mermaid\ngraph TD\n subgraph \"Encoder 实例\"\n Encoder[编码器模型]\n ECC[EC Connector]\n end\n \n subgraph \"Prefill 实例\"\n Prefill[Prefill 模型]\n ECC2[EC Connector]\n end\n \n subgraph \"Decode 实例\"\n Decode[Decode 模型]\n KVStore[KV 状态存储]\n end\n \n Encoder -->|编码缓存| ECC\n ECC -->|EC Transfer| ECC2\n ECC2 --> Prefill\n Prefill -->|KV 状态| Decode\n Decode --> KVStore\n```\n\n### EC Connector 配置\n\nEncoder Cache (EC) Connector 用于在实例间传输编码器缓存：\n\n```bash\n# Encoder 实例配置\n--ec-transfer-config '{\n \"ec_connector\": \"ECExampleConnector\",\n \"ec_role\": \"ec_producer\",\n \"ec_connector_extra_config\": {\n \"shared_storage_path\": \"/path/to/storage\"\n }\n}'\n\n# Prefill/Decode 实例配置\n--ec-transfer-config '{\n \"ec_connector\": \"ECExampleConnector\",\n \"ec_role\": \"ec_consumer\",\n \"ec_connector_extra_config\": {\n \"shared_storage_path\": \"/path/to/storage\"\n }\n}'\n```\n\n### 离线示例工作流\n\n离线分离式推理示例包含两个脚本协同工作：\n\n1. **prefill_example.py** - 仅执行预填充，保存 KV 状态和提示词\n2. **decode_example.py** - 加载 KV 状态，执行解码生成\n\n```bash\n./run.sh # 顺序执行 prefill 和 decode\n```\n\n资料来源：[examples/disaggregated/example_connector/README.md](https://github.com/vllm-project/vllm/blob/main/examples/disaggregated/example_connector/README.md)\n\n## 可观测性架构\n\nvLLM 提供完整的可观测性支持，包括指标采集、分布式追踪和日志记录。\n\n### OpenTelemetry 集成\n\nvLLM 原生支持 OpenTelemetry 标准，可与 Jaeger、Prometheus 等监控系统集成：\n\n```bash\n# 启动带追踪的 vLLM 服务\nopentelemetry-instrument vllm serve facebook/opt-125m\n```\n\n### 追踪架构\n\n```mermaid\ngraph LR\n A[vLLM 实例] -->|OTLP| B[Jaeger Collector]\n B --> C[Jaeger UI]\n D[Prometheus] --> E[Grafana]\n A -->|Metrics| D\n```\n\n### 集成组件\n\n| 组件 | 类型 | 用途 |\n|-----|------|------|\n| opentelemetry-sdk | 追踪 SDK | 核心追踪功能 |\n| opentelemetry-api | API 接口 | 标准化接口 |\n| opentelemetry-exporter-otlp | 导出器 | OTLP 协议导出 |\n| opentelemetry-semantic-conventions-ai | 语义约定 | AI 领域约定 |\n\n### Jaeger 部署示例\n\n```bash\n# 启动 Jaeger\ndocker run --rm --name jaeger \\\n -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \\\n -p 6831:6831/udp -p 16686:16686 \\\n -p 4317:4317 -p 4318:4318 \\\n jaegertracing/all-in-one:1.57\n\n# 配置端点\nexport JAEGER_IP=$(docker inspect --format '{{ .NetworkSettings.IPAddress }}' jaeger)\nexport OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=grpc://$JAEGER_IP:4317\nexport OTEL_SERVICE_NAME=\"vllm-service\"\n```\n\n资料来源：[examples/observability/opentelemetry/README.md](https://github.com/vllm-project/vllm/blob/main/examples/observability/opentelemetry/README.md)\n\n## 平台检测机制\n\nvLLM 在启动时自动检测运行平台，并相应调整资源配置：\n\n```python\n# 平台检测逻辑（伪代码）\nif platform_unspecified():\n logger.info(\"Unspecified platform detected, switching to CPU Platform instead.\")\n switch_to_cpu_platform()\n```\n\n支持的平台：\n\n| 平台 | 说明 | 适用场景 |\n|-----|------|---------|\n| CUDA | NVIDIA GPU 平台 | 生产环境高性能推理 |\n| ROCm | AMD GPU 平台 | AMD 硬件部署 |\n| CPU | CPU 计算平台 | 开发测试、轻量推理 |\n| TPU | Google TPU 平台 | TPU 硬件部署 |\n\n## 结构化输出支持\n\nvLLM 支持结构化输出功能，可生成符合约束条件的 JSON、Regex 等格式的输出。\n\n### 支持的约束类型\n\n| 约束类型 | 说明 | 使用场景 |\n|---------|------|---------|\n| `json` | JSON Schema 约束 | API 响应格式化 |\n| `regex` | 正则表达式约束 | 特定格式匹配 |\n| `structural_tag` | 结构化标签约束 | XML/HTML 类输出 |\n\n### 使用示例\n\n```bash\n# 启动结构化输出服务\nvllm serve deepseek-ai/DeepSeek-R1-Distill-Qwen-7B \\\n --reasoning-parser deepseek_r1\n\n# 运行结构化输出测试\npython structured_outputs_offline.py --constraint structural_tag regex --stream\n```\n\n## 数据并行与负载均衡\n\nvLLM 支持多种数据并行和负载均衡模式：\n\n### 模式类型\n\n| 模式 | 启动参数 | 说明 |\n|-----|---------|------|\n| 外部负载均衡 | `--data-parallel-external-lb` | 外部 LB 分配请求 |\n| 混合负载均衡 | `--data-parallel-hybrid-lb` | 内部+外部混合 |\n| 数据并行 | `--data-parallel-rank` | 指定实例排名 |\n| 起始排名 | `--data-parallel-start-rank` | 混合模式起始rank |\n\n### API Server 计数配置\n\n```python\n# 默认值根据模式自动确定\nif args.headless:\n args.api_server_count = 0 # 无头模式下禁用 API 服务器\n```\n\n## 总结\n\nvLLM 的架构设计体现了以下核心设计原则：\n\n1. **模块化设计** - 各层职责清晰，便于独立开发和测试\n2. **灵活部署** - 支持在线服务、离线推理、分离式部署等多种模式\n3. **资源高效** - 通过 PagedAttention 实现显存的高效利用\n4. **标准兼容** - 提供 OpenAI 兼容 API，便于现有系统集成\n5. **可观测性** - 内置 OpenTelemetry 支持，便于监控和调试\n\n这些设计使得 vLLM 能够满足从研究实验到生产部署的各种需求，成为大语言模型推理服务的重要选择。\n\n---\n\n\n\n## V1 引擎架构\n\n### 相关页面\n\n相关主题：[架构概览](#page-arch-overview), [PagedAttention 与 KV 缓存管理](#page-paged-attention), [注意力后端](#page-attention-backends)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [vllm/v1/engine/core.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/engine/core.py)\n- [vllm/v1/engine/async_llm.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/engine/async_llm.py)\n- [vllm/v1/core/sched/scheduler.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/core/sched/scheduler.py)\n- [vllm/v1/sample/sampler.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/sample/sampler.py)\n- [vllm/v1/core/kv_cache_manager.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/core/kv_cache_manager.py)\n- [vllm/v1/core/block_manager.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/core/block_manager.py)\n- [vllm/v1/worker/worker_base.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/worker/worker_base.py)\n \n\n# V1 引擎架构\n\n## 概述\n\nV1引擎是vLLM的全新一代推理引擎架构，采用完全异步的设计理念，实现了高性能的批量请求调度和KV缓存管理。与传统同步引擎不同，V1引擎通过异步流水线架构，能够更高效地处理并发推理请求，显著提升GPU利用率和吞吐量。\n\nV1引擎的核心设计目标包括：\n\n- **异步优先**：全链路异步处理，避免阻塞等待\n- **高效调度**：智能批量调度，优化GPU计算资源\n- **内存优化**：精细化的KV缓存管理，提高显存利用率\n- **可扩展性**：模块化设计，支持多种推理策略\n\n资料来源：[vllm/v1/engine/core.py:1-100]()\n\n## 整体架构\n\n### 架构组件图\n\n```mermaid\ngraph TD\n Client[客户端请求] --> AsyncLLM[AsyncLLM 异步接口]\n AsyncLLM --> Core[LLMCore 核心引擎]\n Core --> Scheduler[Scheduler 调度器]\n Scheduler --> Sampler[Sampler 采样器]\n Scheduler --> KVCacheMgr[KVCacheManager KV缓存管理]\n KVCacheMgr --> BlockMgr[BlockManager 块管理器]\n Sampler --> Worker[Worker 计算单元]\n Worker --> GPU[GPU 推理执行]\n \n style AsyncLLM fill:#e1f5fe\n style Core fill:#fff3e0\n style Scheduler fill:#e8f5e9\n style KVCacheMgr fill:#fce4ec\n```\n\n### 核心组件职责\n\n| 组件 | 文件路径 | 主要职责 |\n|------|----------|----------|\n| AsyncLLM | `vllm/v1/engine/async_llm.py` | 异步请求接口，事件循环管理 |\n| LLMCore | `vllm/v1/engine/core.py` | 引擎核心逻辑，请求生命周期管理 |\n| Scheduler | `vllm/v1/core/sched/scheduler.py` | 请求调度，批次优化 |\n| Sampler | `vllm/v1/sample/sampler.py` | 词元采样，生成控制 |\n| KVCacheManager | `vllm/v1/core/kv_cache_manager.py` | KV缓存分配与回收 |\n| BlockManager | `vllm/v1/core/block_manager.py` | 物理块管理，显存映射 |\n\n资料来源：[vllm/v1/engine/async_llm.py:1-50]()\n\n## AsyncLLM 异步接口层\n\n### 设计概述\n\nAsyncLLM是V1引擎对外暴露的异步编程接口，采用Python asyncio事件循环驱动。它将同步的用户请求转换为异步操作，实现非阻塞的推理调用。\n\n```mermaid\ngraph LR\n A[add_request] --> B[请求队列]\n C[get_output] --> D[输出队列]\n B --> E[事件循环]\n E --> D\n E --> F[后台处理任务]\n```\n\n### 核心方法\n\n```python\nclass AsyncLLM:\n async def add_request(\n request_id: str,\n prompt: str,\n sampling_params: SamplingParams,\n lora_request: Optional[LoRARequest] = None\n ) -> None\n \n async def generate() -> AsyncGenerator[RequestOutput, None]\n \n async def abort_request(request_id: str) -> None\n```\n\n资料来源：[vllm/v1/engine/async_llm.py:80-150]()\n\n## LLMCore 核心引擎\n\n### 引擎初始化流程\n\nLLMCore是V1引擎的核心类，负责初始化和管理整个推理引擎的生命周期。\n\n```mermaid\nflowchart TD\n A[初始化配置] --> B[创建Worker]\n B --> C[初始化KVCacheManager]\n C --> D[初始化Scheduler]\n D --> E[初始化Sampler]\n E --> F[启动事件循环]\n F --> G[引擎就绪]\n```\n\n### 核心类结构\n\n```python\nclass LLMCore:\n def __init__(\n self,\n model_config: ModelConfig,\n cache_config: CacheConfig,\n parallel_config: ParallelConfig,\n scheduler_config: SchedulerConfig,\n ...\n ):\n self.worker = self._init_worker()\n self.kv_cache_manager = KVCacheManager(...)\n self.scheduler = Scheduler(...)\n self.sampler = Sampler(...)\n```\n\n资料来源：[vllm/v1/engine/core.py:100-200]()\n\n## Scheduler 调度器\n\n### 调度策略\n\nScheduler负责管理待处理请求的调度，决定何时以及如何将请求打包成批次进行推理。V1引擎的调度器采用多级队列和多策略调度算法。\n\n```mermaid\ngraph TD\n A[新请求] --> B[等待队列 WaitQueue]\n B --> C{调度决策}\n C -->|可以调度| D[运行队列 RunningQueue]\n C -->|等待资源| E[阻塞队列 BlockedQueue]\n D --> F[生成完成]\n F --> G[输出队列]\n E -->|资源释放| C\n```\n\n### 调度配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| max_num_seqs | int | 256 | 单批次最大序列数 |\n| max_num_batched_tokens | int | 8192 | 单批次最大词元数 |\n| gpu_memory_utilization | float | 0.9 | GPU显存利用率 |\n| num_scheduler_steps | int | 1 | 调度器步数 |\n\n资料来源：[vllm/v1/core/sched/scheduler.py:50-150]()\n\n### 调度循环\n\nScheduler的核心调度循环实现如下：\n\n1. **请求入队**：新请求加入等待队列\n2. **资源检查**：检查KV缓存和计算资源\n3. **批次构建**：选择可调度的请求构建批次\n4. **执行分发**：将批次分发给Worker执行\n5. **结果收集**：收集推理结果并更新请求状态\n\n```python\ndef schedule(self) -> SchedulerOutput:\n # 1. 更新已完成的请求\n self._update_completed_requests()\n \n # 2. 分配新的 KV cache 块\n self._allocate_kv_cache()\n \n # 3. 选择要调度的请求批次\n scheduled = self._select_new_batch()\n \n # 4. 生成调度输出\n return SchedulerOutput(scheduled=scheduled, ...)\n```\n\n资料来源：[vllm/v1/core/sched/scheduler.py:200-350]()\n\n## Sampler 采样器\n\n### 采样流程\n\nSampler负责从模型输出的logits中进行词元采样，是生成式推理的关键环节。\n\n```mermaid\ngraph LR\n A[Logits] --> B[Temperature处理]\n B --> C[Top-K过滤]\n C --> D[Top-P过滤]\n D --> E[采样]\n E --> F[新Token]\n```\n\n### 采样配置\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| temperature | float | 温度参数，控制随机性 |\n| top_p | float | Nucleus采样概率阈值 |\n| top_k | int | Top-K过滤的K值 |\n| max_tokens | int | 最大生成长度 |\n| seed | List[int] | 随机种子 |\n\n```python\nclass Sampler:\n def __init__(self, gpu_device: int, ...):\n self._setup_sampling_algorithms()\n \n def sample(\n self,\n logits: torch.Tensor,\n sampling_params: SamplingParams\n ) -> torch.Tensor:\n # 应用温度\n logits = self._apply_temperature(logits, sampling_params.temperature)\n \n # Top-K 采样\n if sampling_params.top_k != -1:\n logits = self._apply_top_k(logits, sampling_params.top_k)\n \n # Top-P 采样\n if sampling_params.top_p < 1.0:\n logits = self._apply_top_p(logits, sampling_params.top_p)\n \n # 最终采样\n return self._sample(logits, sampling_params.seed)\n```\n\n资料来源：[vllm/v1/sample/sampler.py:50-200]()\n\n## KVCacheManager 缓存管理\n\n### 设计原理\n\nKVCacheManager是V1引擎的KV缓存管理器，负责高效管理和复用GPU显存中的Key-Value缓存。\n\n```mermaid\ngraph TD\n A[请求到达] --> B{检查现有缓存}\n B -->|命中| C[复用已有缓存]\n B -->|未命中| D[分配新缓存块]\n C --> E[追加新Token]\n D --> E\n E --> F[更新块状态]\n F --> G[等待下次调度]\n \n style C fill:#c8e6c9\n style D fill:#ffcdd2\n```\n\n### 缓存块管理\n\n| 块类型 | 说明 | 管理方式 |\n|--------|------|----------|\n| 空闲块 | 未分配的缓存块 | 空闲链表 |\n| 已占用块 | 当前被请求使用的块 | 引用计数 |\n| 已回收块 | 请求完成后待回收的块 | 回收队列 |\n\n```python\nclass KVCacheManager:\n def __init__(self, num_blocks: int, block_size: int, ...):\n self.num_blocks = num_blocks\n self.block_size = block_size\n self._free_blocks: Deque[int] = deque(range(num_blocks))\n self._block_mapping: Dict[str, List[int]] = {}\n \n def allocate(self, request_id: str, num_tokens: int) -> List[int]:\n \"\"\"为请求分配缓存块\"\"\"\n num_blocks_needed = (num_tokens + self.block_size - 1) // self.block_size\n blocks = []\n for _ in range(num_blocks_needed):\n if not self._free_blocks:\n raise OutOfMemoryError(\"KV cache exhausted\")\n blocks.append(self._free_blocks.popleft())\n self._block_mapping[request_id] = blocks\n return blocks\n \n def free(self, request_id: str) -> None:\n \"\"\"释放请求的缓存块\"\"\"\n if request_id in self._block_mapping:\n self._free_blocks.extend(self._block_mapping.pop(request_id))\n```\n\n资料来源：[vllm/v1/core/kv_cache_manager.py:80-200]()\n\n### 缓存分配策略\n\nV1引擎采用以下缓存分配策略优化显存利用：\n\n1. **预分配策略**：根据请求预估长度预分配缓存\n2. **动态扩展**：运行时根据实际需求动态扩展缓存\n3. **块复用**：同一模型层的不同请求共享块结构\n4. **分层管理**：支持不同层的KV缓存独立管理\n\n资料来源：[vllm/v1/core/kv_cache_manager.py:200-300]()\n\n## BlockManager 块管理器\n\n### 物理块管理\n\nBlockManager负责底层物理块的管理，将逻辑缓存块映射到实际的GPU显存地址。\n\n```python\nclass BlockManager:\n def __init__(\n self,\n num_gpu_blocks: int,\n num_cpu_blocks: int,\n block_size: int,\n ):\n self._gpu_block_table: Dict[int, torch.Tensor] = {}\n self._cpu_block_table: Dict[int, torch.Tensor] = {}\n self._block_allocator = BlockAllocator(...)\n```\n\n### 块状态转换\n\n```mermaid\nstateDiagram-v2\n [*] --> Free: 初始化\n Free --> Allocated: 分配\n Allocated --> Free: 释放\n Allocated --> Swapping: 换出到CPU\n Swapping --> Allocated: 换入到GPU\n```\n\n资料来源：[vllm/v1/core/block_manager.py:50-150]()\n\n## Worker 计算单元\n\n### Worker架构\n\nWorker是V1引擎的执行单元，负责在GPU上执行实际的推理计算。\n\n```mermaid\ngraph TD\n A[输入词元] --> B[Embedding层]\n B --> C[Transformer层]\n C --> D[计算Attention]\n D --> E[读取KV缓存]\n E --> C\n C --> F[Logits输出]\n F --> G[返回给Sampler]\n```\n\n### Worker基类\n\n```python\nclass WorkerBase:\n def __init__(self, vllm_config: VllmConfig, ...):\n self.vllm_config = vllm_config\n self.model_runner = ModelRunner(...)\n \n def execute_model(\n self,\n seq_group_metadata_list: List[SequenceGroupMetadata],\n kv_caches: List[torch.Tensor],\n ) -> Optional[List[torch.Tensor]]:\n # 准备输入\n input_tokens = self._prepare_input(seq_group_metadata_list)\n \n # 执行模型推理\n output = self.model_runner.execute(input_tokens, kv_caches)\n \n return output\n```\n\n资料来源：[vllm/v1/worker/worker_base.py:50-150]()\n\n## 请求处理流程\n\n### 完整推理流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant AsyncLLM as AsyncLLM\n participant Core as LLMCore\n participant Scheduler as Scheduler\n participant Worker as Worker\n participant Sampler as Sampler\n participant KVCache as KVCacheManager\n \n Client->>AsyncLLM: add_request()\n AsyncLLM->>Core: 提交请求\n Core->>Scheduler: 入队\n Scheduler->>KVCache: 分配缓存\n Scheduler->>Worker: 分发批次\n Worker->>Worker: GPU推理\n Worker-->>Sampler: Logits输出\n Sampler->>Sampler: 词元采样\n Sampler-->>KVCache: 更新缓存\n KVCache-->>Scheduler: 分配完成\n Scheduler-->>AsyncLLM: 调度结果\n AsyncLLM-->>Client: 输出流\n```\n\n### 多步推理循环\n\nV1引擎支持多步推理（Multi-Step Decoding），在单次调度中执行多个推理步骤：\n\n1. **步骤1**：执行Attention计算\n2. **步骤2**：更新KV缓存\n3. **步骤3**：执行采样\n4. **步骤4**：判断是否继续\n\n```python\nfor step in range(num_scheduler_steps):\n # 执行模型前向\n hidden_states = model(input_ids, kv_caches)\n \n # 计算logits\n logits = hidden_states @ lm_head.weight\n \n # 采样新token\n next_tokens = sampler.sample(logits)\n \n # 检查终止条件\n if self._should_stop(next_tokens):\n break\n```\n\n资料来源：[vllm/v1/engine/core.py:300-400]()\n\n## 配置与优化\n\n### 引擎配置选项\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| model | str | 必填 | 模型路径或HuggingFace ID |\n| tensor_parallel_size | int | 1 | 张量并行度 |\n| gpu_memory_utilization | float | 0.9 | GPU显存利用率 |\n| max_model_len | int | 8192 | 最大模型长度 |\n| block_size | int | 16 | KV缓存块大小 |\n| enable_prefix_caching | bool | True | 启用前缀缓存 |\n| num_scheduler_steps | int | 1 | 调度器步数 |\n\n### 性能优化建议\n\n1. **调整GPU显存利用率**：根据模型大小调整，避免OOM\n2. **优化块大小**：较大块减少碎片，较小块提高利用率\n3. **启用前缀缓存**：对重复前缀的请求效果显著\n4. **批量大小优化**：根据延迟和吞吐量需求调整\n\n资料来源：[vllm/v1/engine/core.py:400-500]()\n\n## 与V0引擎的对比\n\n| 特性 | V0引擎 | V1引擎 |\n|------|--------|--------|\n| 架构模式 | 同步批量处理 | 异步流水线 |\n| 缓存管理 | 静态分配 | 动态管理 |\n| 调度策略 | 固定批次 | 自适应调度 |\n| 扩展性 | 一般 | 模块化设计 |\n| 多步推理 | 不支持 | 原生支持 |\n\nV1引擎通过异步架构和精细化的资源管理，实现了更高的GPU利用率和更低的请求延迟。\n\n## 总结\n\nV1引擎架构代表了vLLM在推理优化领域的最新技术演进。通过异步设计、智能调度和高效缓存管理的协同优化，V1引擎能够充分利用现代GPU的并行计算能力，为大语言模型推理提供高性能、高吞吐量的解决方案。模块化的组件设计使得V1引擎具有良好的可扩展性和可维护性，便于后续功能扩展和性能优化。\n\n---\n\n\n\n## 引擎核心模块\n\n### 相关页面\n\n相关主题：[架构概览](#page-arch-overview), [V1 引擎架构](#page-v1-engine)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [vllm/engine/llm_engine.py](https://github.com/vllm-project/vllm/blob/main/vllm/engine/llm_engine.py)\n- [vllm/engine/async_llm_engine.py](https://github.com/vllm-project/vllm/blob/main/vllm/engine/async_llm_engine.py)\n- [vllm/engine/protocol.py](https://github.com/vllm-project/vllm/blob/main/vllm/engine/protocol.py)\n- [vllm/v1/engine/llm_engine.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/engine/llm_engine.py)\n- [vllm/entrypoints/cli/serve.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/serve.py)\n- [vllm/entrypoints/cli/launch.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/launch.py)\n- [vllm/entrypoints/cli/main.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/main.py)\n \n\n# 引擎核心模块\n\n## 概述\n\nvLLM 的引擎核心模块是整个推理服务系统的核心组件，负责管理模型加载、请求调度、推理执行和结果返回等关键流程。引擎模块支持同步和异步两种运行模式，提供了面向不同应用场景的编程接口。\n\nvLLM 引擎采用了分层架构设计，底层封装了高性能的推理内核，上层提供了灵活的调度策略和请求管理机制。引擎通过抽象接口与上层服务层解耦，同时通过适配器与底层硬件平台紧密集成。\n\n引擎模块位于 `vllm/engine/` 目录下，主要包含以下核心组件：\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| LLMEngine | `vllm/engine/llm_engine.py` | 同步推理引擎主类 |\n| AsyncLLMEngine | `vllm/engine/async_llm_engine.py` | 异步推理引擎主类 |\n| EngineProtocol | `vllm/engine/protocol.py` | 引擎通信协议定义 |\n| V1 LLMEngine | `vllm/v1/engine/llm_engine.py` | V1版本引擎实现 |\n\n资料来源：[vllm/engine/llm_engine.py](https://github.com/vllm-project/vllm/blob/main/vllm/engine/llm_engine.py)\n\n## 架构设计\n\n### 整体架构\n\nvLLM 引擎采用事件驱动的异步架构，核心模块之间通过协议接口进行通信。引擎接收来自 API 服务层的请求，经过调度器分配后交由推理内核执行，最终将结果返回给调用方。\n\n```mermaid\ngraph TD\n subgraph \"服务层\"\n A[API Server] --> B[CLI/SDK]\n end\n \n subgraph \"引擎层\"\n C[AsyncLLMEngine] --> D[LLMEngine]\n D --> E[Scheduler]\n E --> F[Model Runner]\n end\n \n subgraph \"内核层\"\n G[CUDA Kernels] --> H[PagedAttention]\n F --> G\n end\n \n A --> C\n B --> C\n```\n\n资料来源：[vllm/entrypoints/cli/main.py:46-58](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/main.py)\n\n### 双引擎模式\n\nvLLM 支持 V0 和 V1 两套引擎实现，两者在架构和性能特性上有所不同：\n\n| 特性 | V0 Engine | V1 Engine |\n|------|----------|-----------|\n| 调度策略 | 多种调度器可选 | 统一调度框架 |\n| 内存管理 | 传统 KV Cache | PagedAttention |\n| 异步支持 | 有限 | 原生异步支持 |\n| 性能优化 | 成熟稳定 | 新一代优化 |\n\nV1 引擎位于 `vllm/v1/engine/` 目录下，代表了 vLLM 的新一代架构设计。\n\n资料来源：[vllm/v1/engine/llm_engine.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/engine/llm_engine.py)\n\n## 同步引擎 (LLMEngine)\n\n### 类定义\n\n`LLMEngine` 是 vLLM 的同步推理引擎主类，提供阻塞式的推理接口。该类负责初始化推理环境、管理模型权重、处理推理请求并返回结果。\n\n```python\nclass LLMEngine:\n def __init__(\n self,\n model_config: ModelConfig,\n cache_config: CacheConfig,\n parallel_config: ParallelConfig,\n scheduler_config: SchedulerConfig,\n device_config: DeviceConfig,\n executor_class: Type[ExecutorBase],\n log_stats: bool = True,\n usage_context: UsageContext = UsageContext.LLM_CLASS,\n ) -> None:\n```\n\n### 核心方法\n\n| 方法 | 参数 | 返回值 | 功能描述 |\n|------|------|--------|----------|\n| add_request | request_id, prompt, params | None | 添加推理请求 |\n| step | - | List[Output] | 执行一步推理 |\n| abort_request | request_id | None | 取消指定请求 |\n| get_num_unfinished_requests | - | int | 获取未完成请求数 |\n\n`step()` 方法是引擎的核心执行方法，每次调用会推进推理状态机，处理调度、内存分配、内核执行等操作。\n\n资料来源：[vllm/engine/llm_engine.py](https://github.com/vllm-project/vllm/blob/main/vllm/engine/llm_engine.py)\n\n### 请求处理流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Engine as LLMEngine\n participant Scheduler as 调度器\n participant Runner as ModelRunner\n participant Kernel as CUDA Kernels\n\n Client->>Engine: add_request()\n Engine->>Scheduler: 排队请求\n loop 推理循环\n Engine->>Scheduler: step()\n Scheduler->>Runner: 分发批次\n Runner->>Kernel: 执行推理\n Kernel-->>Runner: 输出结果\n Runner-->>Scheduler: 收集输出\n end\n Engine-->>Client: 返回结果\n```\n\n## 异步引擎 (AsyncLLMEngine)\n\n### 设计理念\n\n`AsyncLLMEngine` 是 vLLM 的异步推理引擎，专为高性能 Web 服务设计。它基于事件循环实现非阻塞推理，能够同时处理大量并发请求。\n\n异步引擎封装了底层同步引擎，通过 `asyncio` 协程提供非阻塞接口。这使得 vLLM 能够与 FastAPI、aiohttp 等异步 Web 框架无缝集成。\n\n资料来源：[vllm/engine/async_llm_engine.py](https://github.com/vllm-project/vllm/blob/main/vllm/engine/async_llm_engine.py)\n\n### 核心接口\n\n```python\nclass AsyncLLMEngine:\n async def add_request(\n self,\n request_id: str,\n prompt: PromptType,\n params: Optional[RequestParams] = None,\n arrival_time: Optional[float] = None,\n ) -> AsyncStream:\n \"\"\"添加异步推理请求\"\"\"\n```\n\n异步引擎通过 `AsyncStream` 对象返回结果，支持流式输出。调用方可以通过 `async for` 语法逐token获取生成结果。\n\n### 请求取消机制\n\n异步引擎支持请求级别的取消操作。当客户端需要中止某个长时间运行的推理时，可以通过 `abort()` 方法通知引擎。\n\n```python\nasync def abort(self, request_id: str) -> None:\n \"\"\"取消指定请求\"\"\"\n```\n\n资料来源：[vllm/engine/async_llm_engine.py](https://github.com/vllm-project/vllm/blob/main/vllm/engine/async_llm_engine.py)\n\n## 引擎协议 (EngineProtocol)\n\n`EngineProtocol` 定义了引擎与外部组件通信的标准接口规范。该协议抽象了引擎的核心行为，确保不同实现之间的一致性。\n\n```mermaid\ngraph LR\n subgraph \"协议层\"\n A[EngineProtocol] --> B[generate]\n A --> C[abort]\n A --> D[get_output]\n end\n```\n\n协议定义包括以下核心接口：\n\n| 接口 | 方法签名 | 说明 |\n|------|----------|------|\n| generate | async generate(request) | 生成推理请求 |\n| abort | abort(request_id) | 中止请求 |\n| get_output | await output_event | 获取输出事件 |\n\n资料来源：[vllm/engine/protocol.py](https://github.com/vllm-project/vllm/blob/main/vllm/engine/protocol.py)\n\n## 配置管理\n\n### 引擎参数\n\n引擎初始化时需要传入多个配置对象，这些配置控制了推理行为的各个方面：\n\n| 配置类 | 参数数量 | 主要功能 |\n|--------|----------|----------|\n| ModelConfig | 50+ | 模型架构、词汇表、量化配置 |\n| CacheConfig | 10+ | KV Cache 内存管理策略 |\n| ParallelConfig | 5+ | 多GPU并行配置 |\n| SchedulerConfig | 10+ | 调度器行为参数 |\n| DeviceConfig | 5+ | 硬件平台选择 |\n\n### 命令行参数\n\n引擎支持通过命令行参数进行配置，常用参数包括：\n\n```bash\nvllm serve Qwen/Qwen2.5-3B-Instruct \\\n --tensor-parallel-size 2 \\\n --max-model-len 8192 \\\n --gpu-memory-utilization 0.9\n```\n\n资料来源：[vllm/entrypoints/cli/serve.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/serve.py)\n\n## 服务启动流程\n\n### CLI 入口\n\nvLLM 的服务通过命令行启动，主要入口流程如下：\n\n```mermaid\nflowchart LR\n A[vllm serve] --> B[main.py]\n B --> C[导入模块]\n C --> D[ServeSubcommand]\n D --> E[创建引擎]\n E --> F[启动服务]\n```\n\nCLI 入口位于 `vllm/entrypoints/cli/main.py`，负责解析命令行参数并分发到相应的子命令处理器。\n\n资料来源：[vllm/entrypoints/cli/main.py:48-68](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/main.py)\n\n### 引擎初始化\n\n```python\ndef cmd(args: argparse.Namespace) -> None:\n # CLI 参数优先级高于默认值\n if hasattr(args, \"model_tag\") and args.model_tag is not None:\n args.model = args.model_tag\n\n # gRPC 模式\n if getattr(args, \"grpc\", False):\n from vllm.entrypoints.grpc_server import serve_grpc\n uvloop.run(serve_grpc(args))\n return\n\n # Headless 模式（无API服务器）\n if args.headless:\n args.api_server_count = 0\n```\n\n引擎支持多种运行模式，包括标准 HTTP 服务、gRPC 服务和 headless 模式。Headless 模式不启动 API 服务器，适用于分布式推理场景。\n\n资料来源：[vllm/entrypoints/cli/serve.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/serve.py)\n\n### Launch 组件\n\n`vllm launch` 命令提供了组件级别的启动能力，支持快速启动特定的推理组件：\n\n```bash\nvllm launch [options]\n```\n\nLaunch 子系统采用插件化架构，新的组件可以通过继承 `LaunchSubcommandBase` 类注册到系统中。\n\n资料来源：[vllm/entrypoints/cli/launch.py](https://github.com/vllm-project/vllm/blob/main/vllm/entrypoints/cli/launch.py)\n\n## 调度器集成\n\n### 调度策略\n\n引擎内置多种调度策略，适用于不同的负载场景：\n\n| 策略 | 适用场景 | 特点 |\n|------|----------|------|\n| FIFO | 批处理 | 简单高效 |\n| Longest-Prefix | 前缀共享 | 优化解码共享 |\n| 混合策略 | 通用 | 平衡吞吐和延迟 |\n\n调度器通过 `SchedulerConfig` 进行配置，控制批次大小、超时时间、资源分配等关键参数。\n\n### 资源分配\n\n调度器负责管理 GPU 显存使用，通过 `gpu_memory_utilization` 参数控制用于 KV Cache 的显存比例。剩余显存用于模型权重和中间计算。\n\n```python\n# 显存分配示例\ncache_config = CacheConfig(\n gpu_memory_utilization=0.9,\n block_size=16,\n)\n```\n\n## 性能优化\n\n### PagedAttention\n\nvLLM 引擎采用 PagedAttention 技术管理 KV Cache，相比传统连续分配方式，显存利用率提升显著：\n\n- 显存碎片减少 60%+\n- 吞吐量提升 2-4 倍\n- 支持更大的上下文长度\n\n### CUDA 图\n\n引擎支持 CUDA Graph 加速，减少内核启动开销。在 profiling 模式下，可以通过 `nsys` 工具分析 CUDA 图的执行效率：\n\n```bash\nnsys profile -t cuda -o run1 -f true \\\n --cuda-graph-trace=node \\\n vllm serve openai/gpt-oss-120b\n```\n\n资料来源：[tools/profiler/nsys_profile_tools/README.md](https://github.com/vllm-project/vllm/blob/main/tools/profiler/nsys_profile_tools/README.md)\n\n## 使用示例\n\n### 离线推理\n\n```python\nfrom vllm import LLM\n\nllm = LLM(model=\"Qwen/Qwen2.5-3B-Instruct\")\noutputs = llm.generate(\"Hello, world!\")\n```\n\n### 在线服务\n\n```bash\n# 启动服务\nvllm serve Qwen/Qwen2.5-3B-Instruct \\\n --tensor-parallel-size 2\n\n# 发送请求\ncurl -X POST http://localhost:8000/v1/chat/completions \\\n -H \"Content-Type: application/json\" \\\n -d '{\"model\": \"Qwen/Qwen2.5-3B-Instruct\", \"messages\": [{\"role\": \"user\", \"content\": \"Hello!\"}]}'\n```\n\n### 异步客户端\n\n```python\nfrom vllm.engine.async_llm_engine import AsyncLLMEngine\n\nengine = AsyncLLMEngine.from_engine_args(engine_args)\n\nasync def generate():\n async for output in await engine.add_request(\"req-1\", prompt, params):\n print(output)\n\nasyncio.run(generate())\n```\n\n## 相关文档\n\n- [快速开始指南](https://docs.vllm.ai/en/latest/getting_started/quickstart.html)\n- [支持的模型列表](https://docs.vllm.ai/en/latest/models/supported_models.html)\n- [量化配置](https://docs.vllm.ai/en/latest/features/quantization.html)\n- [分布式推理](https://docs.vllm.ai/en/latest/distributed/summary.html)\n\n---\n\n\n\n## PagedAttention 与 KV 缓存管理\n\n### 相关页面\n\n相关主题：[注意力后端](#page-attention-backends), [V1 引擎架构](#page-v1-engine)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/design/paged_attention.md](https://github.com/vllm-project/vllm/blob/main/docs/design/paged_attention.md)\n- [csrc/attention/paged_attention_v1.cu](https://github.com/vllm-project/vllm/blob/main/csrc/attention/paged_attention_v1.cu)\n- [csrc/attention/paged_attention_v2.cu](https://github.com/vllm-project/vllm/blob/main/csrc/attention/paged_attention_v2.cu)\n- [vllm/v1/core/block_pool.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/core/block_pool.py)\n- [vllm/v1/core/kv_cache_manager.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/core/kv_cache_manager.py)\n \n\n# PagedAttention 与 KV 缓存管理\n\n## 概述\n\nPagedAttention 是 vLLM 核心推理引擎中的一项关键技术，旨在解决大语言模型（LLM）推理过程中 KV 缓存的内存管理问题。传统的 KV 缓存管理方式采用连续内存分配策略，导致内存碎片化严重、利用率低下。PagedAttention 借鉴了操作系统中虚拟内存和分页管理的思想，将 KV 缓存分割成固定大小的\"页面\"（blocks）进行管理，从而实现灵活的内存分配与共享。\n\nvLLM 的 KV 缓存管理架构分为 V1 和 V2 两个版本，其中 V2 版本在性能和内存效率方面进行了进一步优化。管理机制主要由 `BlockPool` 和 `KVCacheManager` 两个核心组件协同工作，实现对 GPU 和 CPU 内存中 KV 缓存块的高效调度。\n\n## PagedAttention 核心原理\n\n### 分页管理机制\n\nPagedAttention 将 KV 缓存划分为固定大小的块（blocks），每个块包含多个 token 的键值向量。与传统方法不同，这些块不需要在物理内存中连续存储，而是通过逻辑地址映射实现灵活访问。这种设计允许系统动态分配和释放缓存块，显著提高内存利用率。\n\n```mermaid\ngraph TD\n A[请求序列] --> B[逻辑块分配]\n B --> C[块表映射]\n C --> D[物理块存储]\n D --> E[GPU KV Cache]\n \n F[块表] -->|映射| D\n G[新请求] -->|增量分配| B\n H[请求完成] -->|块回收| D\n```\n\n### V1 与 V2 版本对比\n\n| 特性 | PagedAttention V1 | PagedAttention V2 |\n|------|-------------------|-------------------|\n| 块大小 | 固定16个token | 固定16个token |\n| 内存布局 | 原始格式 | 扁平化布局 |\n| 计算效率 | 标准计算 | 融合内核优化 |\n| 支持前缀共享 | 有限支持 | 增强支持 |\n\n## KV 缓存管理架构\n\n### BlockPool 组件\n\n`BlockPool` 负责管理物理内存中的 KV 缓存块池。它维护可用块的分配状态，支持 GPU 和 CPU 内存的双层管理。当新的推理请求到达时，`BlockPool` 负责分配空闲块；当请求完成时，相应块被回收至空闲池。\n\n核心功能包括：\n\n- 块预分配与动态分配策略\n- GPU/CPU 块状态追踪\n- 块引用计数管理\n- 内存碎片整理\n\n### KVCacheManager 组件\n\n`KVCacheManager` 是更高层次的缓存管理器，负责逻辑块到物理块的映射管理。它维护请求的 KV 块分配记录，支持 block 级别的引用计数和共享机制。当多个请求共享相同的前缀时，`KVCacheManager` 可以实现块级别的共享，避免重复存储相同的 KV 数据。\n\n```mermaid\ngraph LR\n A[推理请求] --> B[KVCacheManager]\n B --> C{前缀匹配?}\n C -->|是| D[共享已有块]\n C -->|否| E[分配新块]\n D --> F[BlockPool]\n E --> F\n F --> G[更新块表映射]\n G --> H[执行注意力计算]\n```\n\n## CUDA 内核实现\n\n### PagedAttention V1 内核\n\nV1 版本的内核实现位于 `csrc/attention/paged_attention_v1.cu`，采用标准的 CUDA 并行策略。内核函数 `paged_attention_v1` 处理块级别的注意力计算，每个线程块负责一个查询头（query head）的计算。内核通过共享内存缓存 KV 数据，减少全局内存访问延迟。\n\n关键实现要点：\n\n- 支持不同的块大小配置\n- 实现了 KV 数据的分页读取\n- 使用 warp 级别的归约操作提升性能\n- 支持半精度（FP16/BF16）计算\n\n### PagedAttention V2 内核\n\nV2 版本位于 `csrc/attention/paged_attention_v2.cu`，在 V1 基础上进行了深度优化。主要改进包括：\n\n1. **扁平化内存布局**：将 KV 数据按页面连续存储，提升缓存局部性\n2. **融合内核设计**：将多个操作融合到单一内核中，减少内核启动开销\n3. **向量化加载**：使用更大的向量宽度访问内存，提高带宽利用率\n4. **动态块大小支持**：根据配置自适应调整计算策略\n\n## 内存管理策略\n\n### 分配策略\n\nvLLM 采用混合分配策略处理 KV 缓存：\n\n- **预分配策略**：在模型加载时预分配一定比例的 GPU 内存用于 KV 缓存\n- **动态分配**：运行时根据实际需求动态分配新块\n- **层级淘汰**：GPU 内存不足时，将部分块交换至 CPU 内存\n\n### 共享机制\n\nPagedAttention 支持不同请求间的 KV 块共享。当多个请求共享相同的前缀（如系统提示词）时，对应的 KV 块可以被多个请求引用，无需重复存储。共享通过引用计数实现，只有当引用计数归零时，块才会被释放。\n\n```mermaid\ngraph TD\n A[请求1: 共享前缀] --> B[引用计数=2]\n C[请求2: 共享前缀] --> B\n \n B --> D[物理块P]\n D --> E[Token 0-15 KV数据]\n \n F[请求3: 独立前缀] --> G[引用计数=1]\n G --> H[物理块Q]\n H --> I[Token 0-15 KV数据]\n```\n\n## 配置与调优\n\n### 关键配置参数\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `block_size` | 每个缓存块包含的 token 数量 | 16 |\n| `gpu_memory_utilization` | 用于 KV 缓存的 GPU 内存比例 | 0.9 |\n| `num_cpu_blocks` | CPU 缓存块数量 | 动态计算 |\n| `num_gpu_blocks` | GPU 缓存块数量 | 动态计算 |\n\n### 性能调优建议\n\n1. 根据模型大小和可用显存调整 `gpu_memory_utilization`\n2. 对于长上下文场景，适当增加块数量\n3. 启用块共享以优化多请求场景的内存使用\n4. 监控实际的块使用率以优化配置\n\n## 技术优势\n\nPagedAttention 相比传统连续分配方案具有显著优势：\n\n- **内存效率提升**：通过分页管理和共享机制，内存利用率提高 2-4 倍\n- **支持更长上下文**：灵活的内存管理允许处理更长的输入序列\n- **高吞吐量**：优化的 CUDA 内核实现提供更高的计算吞吐量\n- **弹性扩展**：支持动态调整缓存容量以适应不同工作负载\n\n## 源码引用\n\n本文档参考了以下 vLLM 源码文件：\n\n- `docs/design/paged_attention.md` - PagedAttention 设计文档\n- `csrc/attention/paged_attention_v1.cu` - V1 CUDA 内核实现\n- `csrc/attention/paged_attention_v2.cu` - V2 CUDA 内核实现\n- `vllm/v1/core/block_pool.py` - 块池管理模块\n- `vllm/v1/core/kv_cache_manager.py` - KV 缓存管理器模块\n\n---\n\n\n\n## 注意力后端\n\n### 相关页面\n\n相关主题：[PagedAttention 与 KV 缓存管理](#page-paged-attention)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/design/attention_backends.md](https://github.com/vllm-project/vllm/blob/main/docs/design/attention_backends.md)\n- [vllm/v1/attention/backends/flash_attn.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/attention/backends/flash_attn.py)\n- [vllm/v1/attention/backends/flashinfer.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/attention/backends/flashinfer.py)\n- [vllm/v1/attention/selector.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/attention/selector.py)\n- [vllm/v1/attention/ops/paged_attn.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/attention/ops/paged_attn.py)\n \n\n# 注意力后端\n\n## 概述\n\nvLLM 的注意力后端（Attention Backends）是处理 Transformer 模型中自注意力机制的核心组件，负责高效计算 Query、Key、Value 之间的注意力分数。vLLM 采用模块化设计，支持多种注意力计算实现，通过后端抽象层提供统一的接口，使系统能够在不同硬件和性能需求下选择最优的实现方案。\n\n注意力后端的主要职责包括：\n\n- 计算多头自注意力（Multi-Head Attention）\n- 支持带因果掩码的解码模式\n- 处理键值缓存（KV Cache）的读写\n- 支持分页注意力（Paged Attention）以优化内存使用\n\n资料来源：[docs/design/attention_backends.md]()\n\n## 架构设计\n\n### 后端抽象层\n\nvLLM 在 `vllm/v1/attention/backends/` 目录下实现了后端抽象层，每个后端都继承自统一的基类接口。这种设计允许在运行时根据硬件能力和配置选择合适的实现。\n\n```mermaid\ngraph TD\n A[Attention Layer] --> B[Attention Backend Selector]\n B --> C[FlashAttention Backend]\n B --> D[FlashInfer Backend]\n B --> E[其他后端...]\n C --> F[CUDA FlashAttention]\n D --> G[FlashInfer Kernel]\n```\n\n### 核心接口定义\n\n每个注意力后端需要实现以下核心方法：\n\n| 方法名 | 功能描述 |\n|--------|----------|\n| `forward()` | 执行注意力前向计算 |\n| `init_backend()` | 初始化后端资源 |\n| `get_name()` | 返回后端名称标识 |\n| `get_supported_dtypes()` | 获取支持的数据类型列表 |\n\n资料来源：[vllm/v1/attention/backends/flash_attn.py:1-100]()\n\n## 后端实现\n\n### FlashAttention 后端\n\nFlashAttention 是一种高效的注意力实现，通过分块计算和融合核（fused kernel）显著减少内存访问，提升计算吞吐量。\n\nFlashAttention 后端的主要特性：\n\n- 支持 FP16、BF16 数据类型\n- 通过 CUDA 核心实现分块矩阵乘法\n- 自动处理序列长度大于 GPU 限制的情况（通过 Flash Attention 2/3 的支持）\n- 与 vLLM 的 Paged Attention 机制无缝集成\n\n```python\n# FlashAttention 后端核心逻辑示意\nclass FlashAttentionBackend:\n def __init__(self, num_heads: int, head_dim: int, scale: float):\n self.num_heads = num_heads\n self.head_dim = head_dim\n self.scale = scale\n \n def forward(self, query, key, value, cu_seqlen_q, cu_seqlen_k):\n # 使用 CUDA Flash Attention 内核计算\n return flash_attn_varlen_func(\n query, key, value,\n cu_seqlen_q, cu_seqlen_k,\n self.scale\n )\n```\n\n资料来源：[vllm/v1/attention/backends/flash_attn.py:1-150]()\n\n### FlashInfer 后端\n\nFlashInfer 是另一种高性能注意力库，特别针对推理场景优化，提供更低的延迟和更好的吞吐。\n\nFlashInfer 后端的特点：\n\n- 针对推理工作负载优化\n- 支持增量解码（Incremental Decoding）\n- 与 PagedAttention 深度集成\n- 支持连续批处理（Continuous Batching）\n\n```python\n# FlashInfer 后端核心逻辑示意\nclass FlashInferBackend:\n def forward(self, query, key, value, paged_kv_cache, ...):\n # 使用 FlashInfer 核函数\n return flashinfer.attention(\n query, paged_kv_cache,\n ...\n )\n```\n\n资料来源：[vllm/v1/attention/backends/flashinfer.py:1-100]()\n\n## 后端选择机制\n\n### 动态选择器\n\nvLLM 提供了智能的后端选择器（Attention Selector），根据系统环境和配置自动选择最优的注意力后端。选择逻辑位于 `vllm/v1/attention/selector.py` 文件中。\n\n```mermaid\ngraph TD\n A[启动时检测] --> B{检查用户配置}\n B -->|明确指定| C[使用指定后端]\n B -->|未指定| D[检测 GPU 能力]\n D --> E{FlashInfer 可用?}\n E -->|是| F[优先选择 FlashInfer]\n E -->|否| G{FlashAttention 可用?}\n G -->|是| H[选择 FlashAttention]\n G -->|否| I[降级到基础实现]\n```\n\n### 选择优先级\n\n| 优先级 | 后端 | 条件 |\n|--------|------|------|\n| 1 | FlashInfer | GPU 支持且已安装 |\n| 2 | FlashAttention | CUDA 版本兼容 |\n| 3 | 基础实现 | 无其他选项时的兜底方案 |\n\n资料来源：[vllm/v1/attention/selector.py:1-80]()\n\n## 分页注意力机制\n\n### Paged Attention 概述\n\nPagedAttention 是 vLLM 的核心创新之一，通过将 KV 缓存分页存储在 GPU 内存中，显著提高内存利用率，支持更大的并发批处理。\n\n### 核心数据结构\n\n```mermaid\ngraph LR\n A[逻辑 KV Cache] -->|映射| B[物理块]\n A[Query] --> C[注意力计算]\n B --> C\n```\n\nPagedAttention 使用块表（Block Table）来管理逻辑块到物理块的映射关系。每个请求的 KV 缓存被分割成固定大小的块（通常为 16 或 32 个 token），存储在非连续的物理内存位置。\n\n### 块表结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `physical_blocks` | List[int] | 物理块编号列表 |\n| `num_blocks` | int | 块数量 |\n| `block_size` | int | 每个块的 token 数量 |\n\n资料来源：[vllm/v1/attention/ops/paged_attn.py:1-120]()\n\n## 配置与使用\n\n### 命令行配置\n\n用户可以通过命令行参数指定注意力后端：\n\n```bash\nvllm serve --attention-backend flashinfer\n```\n\n支持的参数值：\n- `auto` - 自动选择最优后端（默认）\n- `flash_attn` - 强制使用 FlashAttention\n- `flashinfer` - 强制使用 FlashInfer\n\n### 编程接口配置\n\n在 Python 代码中配置注意力后端：\n\n```python\nfrom vllm import LLM, SamplingParams\n\nllm = LLM(\n model=\"Qwen/Qwen2.5-3B-Instruct\",\n attention_backend=\"flashinfer\" # 指定后端\n)\n```\n\n### 环境变量\n\n| 环境变量 | 作用 |\n|----------|------|\n| `VLLM_ATTENTION_BACKEND` | 覆盖默认后端选择 |\n\n## 性能特性对比\n\n| 特性 | FlashAttention | FlashInfer |\n|------|-----------------|------------|\n| 首次 token 延迟 | 中等 | 低 |\n| 解码吞吐 | 高 | 更高 |\n| 内存效率 | 高 | 极高 |\n| 连续批处理 | 支持 | 深度优化 |\n| 适用场景 | 通用推理 | 生产级推理 |\n\n## 扩展新的注意力后端\n\n如需为 vLLM 添加新的注意力后端，需要：\n\n1. 在 `vllm/v1/attention/backends/` 下创建新的 Python 模块\n2. 实现 `AttentionBackend` 基类定义的所有接口\n3. 在 `selector.py` 中注册新的后端和选择逻辑\n4. 在配置选项中添加新后端的支持\n\n```python\n# 新后端模板\nclass NewAttentionBackend(AttentionBackend):\n def __init__(self, num_heads: int, head_dim: int, scale: float):\n self.num_heads = num_heads\n self.head_dim = head_dim\n self.scale = scale\n \n @staticmethod\n def get_name() -> str:\n return \"new_backend\"\n \n @staticmethod\n def get_supported_dtypes() -> List[torch.dtype]:\n return [torch.float16, torch.bfloat16]\n \n def forward(self, ...):\n # 实现注意力计算\n pass\n```\n\n## 注意事项\n\n- 确保 GPU 驱动和 CUDA 版本与所选后端兼容\n- FlashInfer 后端需要单独安装：`pip install flashinfer`\n- 在多 GPU 场景下，后端选择需要考虑 NCCL 通信开销\n- 某些特殊模型架构可能需要特定后端才能正常工作\n\n---\n\n\n\n## 量化支持\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [vllm/model_executor/layers/quantization/fp8.py](https://github.com/vllm-project/vllm/blob/main/vllm/model_executor/layers/quantization/fp8.py)\n- [vllm/model_executor/layers/quantization/gptq.py](https://github.com/vllm-project/vllm/blob/main/vllm/model_executor/layers/quantization/gptq.py)\n- [vllm/model_executor/layers/quantization/awq.py](https://github.com/vllm-project/vllm/blob/main/vllm/model_executor/layers/quantization/awq.py)\n- [vllm/model_executor/layers/quantization/gguf.py](https://github.com/vllm-project/vllm/blob/main/vllm/model_executor/layers/quantization/gguf.py)\n- [vllm/model_executor/layers/quantization/compressed_tensors/compressed_tensors.py](https://github.com/vllm-project/vllm/blob/main/vllm/model_executor/layers/quantization/compressed_tensors/compressed_tensors.py)\n- [examples/basic/offline_inference/README.md](https://github.com/vllm-project/vllm/blob/main/examples/basic/offline_inference/README.md)\n- [csrc/quantization](https://github.com/vllm-project/vllm/blob/main/csrc/quantization)\n \n\n# 量化支持\n\n## 概述\n\nvLLM 的量化支持模块位于 `vllm/model_executor/layers/quantization/` 目录下，提供多种权重量化方案以降低模型内存占用和提升推理效率。该模块实现了统一的量化接口规范，支持 FP8、GPTQ、AWQ、GGUF 和 Compressed Tensors 等主流量化格式。\n\n量化层的核心设计采用策略模式（Strategy Pattern），通过抽象基类定义标准接口，不同量化算法作为独立实现类存在。这种架构允许用户通过 `--quantization` 参数灵活选择量化方案，同时保持核心推理逻辑的一致性。\n\n---\n\n## 支持的量化格式\n\n### 量化格式对比表\n\n| 量化格式 | 类型 | 精度损失 | 加速效果 | 使用场景 |\n|---------|------|---------|---------|---------|\n| FP8 | 动态量化 | 低 | 中等 | 通用推理，适合 Hopper/Ada 架构 |\n| GPTQ | 静态量化 | 中等 | 高 | 4-bit 量化，GPU 部署 |\n| AWQ | 静态量化 | 低 | 高 | 4-bit 量化，自动权重排序 |\n| GGUF | 静态量化 | 可调 | 高 | CPU/GPU 混合推理 |\n| Compressed Tensors | 通用格式 | 可调 | 依赖实现 | 高度自定义的压缩方案 |\n\n---\n\n## 架构设计\n\n### 模块结构\n\n```\nvllm/model_executor/layers/quantization/\n├── __init__.py\n├── fp8.py # FP8 量化实现\n├── gptq.py # GPTQ 量化实现\n├── awq.py # AWQ 量化实现\n├── gguf.py # GGUF 量化实现\n├── compressed_tensors/ # Compressed Tensors 量化实现\n│ └── compressed_tensors.py\n└── utils.py # 量化工具函数\n```\n\n### 类层次结构\n\n```mermaid\ngraph TD\n A[QuantizationConfig] --> B[FP8Config]\n A --> C[GPTQConfig]\n A --> D[AWQConfig]\n A --> E[GGUFConfig]\n A --> F[CompressedTensorsConfig]\n \n G[QuantizationMethods] --> H[FP8Methods]\n G --> I[GPTQMethods]\n G --> J[AWQMethods]\n G --> K[GGUFMethods]\n G --> L[CompressedTensorsMethods]\n```\n\n---\n\n## FP8 量化\n\n### 概述\n\nFP8（8-bit Floating Point）量化是一种混合精度方案，在 H100/H200 等新架构 GPU 上可获得显著加速。vLLM 支持 FP8_E4M3 和 FP8_E5M2 两种格式。\n\n### 核心实现\n\nFP8 量化模块（`vllm/model_executor/layers/quantization/fp8.py`）实现了以下关键功能：\n\n- **动态范围计算**：根据权重分布自动确定缩放因子\n- **E4M3/E5M2 支持**：可配置 FP8 格式\n- **Kernel 优化**：利用 TensorCore 进行高效计算\n\n### 配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| fp8_format | str | \"hybrid\" | 量化格式：\"fp8_e4m3fn\" 或 \"fp8_e5m2\" |\n| activation_scheme | str | \"dynamic\" | 激活值量化策略 |\n\n---\n\n## GPTQ 量化\n\n### 概述\n\nGPTQ（Generative Pretrained Transformer Quantization）是一种 Post-Training Quantization（PTQ）方法，支持 4-bit 权重量化，显著降低显存占用。\n\n### 核心实现\n\nGPTQ 量化模块（`vllm/model_executor/layers/quantization/gptq.py`）包含：\n\n- **分组量化**：将权重分组处理，每组独立的缩放因子和零点\n- **GPTQ 校准**：使用校准数据集确定最优量化参数\n- **高度优化的 CUDA Kernel**：针对批量推理优化\n\n### 模型加载\n\n使用 GPTQ 量化模型时，需要指定量化位宽：\n\n```bash\nvllm serve --quantization gptq --quantization_param_path \n```\n\n---\n\n## AWQ 量化\n\n### 概述\n\nAWQ（Activation-Aware Weight Quantization）是一种改进的权重量化方案，通过分析激活值分布来选择重要权重进行保护，降低精度损失。\n\n### 核心实现\n\nAWQ 量化模块（`vllm/model_executor/layers/quantization/awq.py`）实现：\n\n- **重要性权重排序**：根据激活值分布识别关键权重\n- **混合精度策略**：对重要权重使用更高精度\n- **自动平滑因子计算**：减少量化误差\n\n---\n\n## GGUF 量化\n\n### 概述\n\nGGUF 是 llama.cpp 项目开发的量化格式，vLLM 通过 GGUF 量化模块（`vllm/model_executor/layers/quantization/gguf.py`）提供原生支持。GGUF 支持多种量化位宽（Q2_K、Q4_0、Q4_K、Q5_K、Q6_K、Q8_0 等），用户可以通过 `repo_id:quant_type` 格式直接从 HuggingFace 加载量化模型。\n\n### 使用方式\n\n```bash\npython examples/basic/offline_inference/generate.py \\\n --model unsloth/Qwen3-0.6B-GGUF:Q4_K_M \\\n --tokenizer Qwen/Qwen3-0.6B\n```\n\n### GGUF 量化类型\n\n| 类型 | 位宽 | 内存节省 | 精度 |\n|------|------|---------|------|\n| Q2_K | 2-bit | ~75% | 较低 |\n| Q4_0 | 4-bit | ~60% | 中等 |\n| Q4_K | 4-bit | ~60% | 较好 |\n| Q5_K | 5-bit | ~50% | 良好 |\n| Q6_K | 6-bit | ~40% | 优秀 |\n| Q8_0 | 8-bit | ~20% | 几乎无损 |\n\n---\n\n## Compressed Tensors 量化\n\n### 概述\n\nCompressed Tensors 是一个通用的压缩格式框架，允许高度自定义的量化方案，支持非均匀量化和结构化稀疏。\n\n### 核心实现\n\n`vllm/model_executor/layers/quantization/compressed_tensors/compressed_tensors.py` 模块提供：\n\n- **动态压缩方案**：支持任意量化策略\n- **元数据管理**：存储压缩所需的元信息\n- **混合精度组合**：支持不同层使用不同精度\n\n---\n\n## CUDA Kernel 实现\n\n### 量化计算位置\n\n量化相关的 CUDA Kernel 实现位于 `csrc/quantization/` 目录下，包含：\n\n- FP8 矩阵乘法 kernel\n- GPTQ 反量化 kernel\n- AWQ 量化/反量化 kernel\n- GGUF 解压缩 kernel\n\n### 优化策略\n\n```mermaid\ngraph LR\n A[模型权重] --> B[量化压缩]\n B --> C[存储/传输]\n C --> D[推理时反量化]\n D --> E[FP32/FP16 计算]\n E --> F[输出]\n```\n\n---\n\n## 使用示例\n\n### 命令行使用\n\n```bash\n# 启动量化模型服务\nvllm serve meta-llama/Llama-2-7b-hf --quantization fp8\n\n# 启动 GGUF 量化模型\nvllm serve mradermacher/llama-2-7b-chat-GGUF:Q4_K_M\n```\n\n### Python API 使用\n\n```python\nfrom vllm import LLM\n\n# 加载量化模型\nllm = LLM(\n model=\"meta-llama/Llama-2-7b-hf\",\n quantization=\"gptq\"\n)\n\n# 生成\noutputs = llm.generate([\"Hello, world!\"])\n```\n\n---\n\n## 注意事项\n\n1. **硬件兼容性**：FP8 需要 Hopper/Ada 架构 GPU\n2. **精度验证**：建议在生产环境前进行精度基准测试\n3. **混合量化**：同一模型可对不同层使用不同量化方案\n4. **量化校准**：静态量化需要代表性数据集进行校准\n\n---\n\n## 参考资料\n\n- vLLM 官方文档：https://docs.vllm.ai/en/latest/\n- 量化配置源码：`vllm/model_executor/layers/quantization/`\n- CUDA 实现：`csrc/quantization/`\n\n---\n\n\n\n## 推测解码\n\n### 相关页面\n\n相关主题：[V1 引擎架构](#page-v1-engine)\n\n# 推测解码\n\n> **注意**: 当前检索到的上下文内容中未包含推测解码相关的源码文件。以下文档是基于 vLLM 项目中推测解码功能的通用技术知识构建，具体的 API 参数、配置选项和行为细节需要参考实际源码文件进行验证。\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/features/speculative_decoding/README.md](https://github.com/vllm-project/vllm/blob/main/docs/features/speculative_decoding/README.md)\n- [vllm/v1/spec_decode/draft_model.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/spec_decode/draft_model.py)\n- [vllm/v1/spec_decode/eagle.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/spec_decode/eagle.py)\n- [vllm/v1/spec_decode/ngram_proposer.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/spec_decode/ngram_proposer.py)\n- [vllm/v1/spec_decode/metrics.py](https://github.com/vllm-project/vllm/blob/main/vllm/v1/spec_decode/metrics.py)\n- [vllm/config/speculative.py](https://github.com/vllm-project/vllm/blob/main/vllm/config/speculative.py)\n\n \n\n## 概述\n\n推测解码（Speculative Decoding）是 vLLM 中用于加速大语言模型推理的一种技术。该技术通过使用一个轻量级的\"草稿模型\"（Draft Model）提前生成多个候选 token，然后由原始的目标模型（Target Model）并行验证这些候选 token，从而减少自回归生成的顺序等待时间。\n\n### 核心价值\n\n- **降低延迟**: 通过并行验证减少生成 token 的平均等待时间\n- **保持输出质量**: 验证机制确保最终输出与标准自回归解码完全一致\n- **灵活的加速策略**: 支持多种草稿模型和提议策略\n\n## 工作原理\n\n推测解码的核心思想是将自回归解码过程中的顺序计算转换为\"生成-验证\"两阶段模式：\n\n1. **提议阶段（Proposal）**: 草稿模型快速生成多个候选 token\n2. **验证阶段（Verification）**: 目标模型批量验证这些候选 token 的正确性\n\n```mermaid\ngraph TD\n A[输入 Prompt] --> B[草稿模型提议]\n B --> C[生成候选 Token 序列]\n C --> D[目标模型并行验证]\n D --> E{验证结果}\n E -->|全部正确| F[接受候选序列]\n E -->|部分错误| G[回退到首个错误位置]\n F --> H[继续下一轮]\n G --> I[修正后继续生成]\n H --> B\n I --> B\n```\n\n### 验证机制\n\n目标模型对草稿模型生成的每个 token 进行验证。只有通过验证的 token 才会被接受为最终输出。如果某个 token 验证失败，系统会回退到该位置，使用目标模型生成的结果替换草稿模型的错误预测。\n\n## 架构设计\n\n### 核心组件\n\n| 组件 | 职责 | 源码位置 |\n|------|------|----------|\n| 推测解码配置 | 管理推测解码相关参数 | `vllm/config/speculative.py` |\n| 草稿模型接口 | 定义草稿模型的标准接口 | `vllm/v1/spec_decode/draft_model.py` |\n| 提议器实现 | 具体实现不同类型的提议策略 | `vllm/v1/spec_decode/` |\n| 指标收集 | 跟踪推测解码性能指标 | `vllm/v1/spec_decode/metrics.py` |\n\n### 提议策略类型\n\nvLLM 支持多种推测解码提议策略：\n\n1. **Ngram 提议器（Ngram Proposer）**\n - 基于 n-gram 统计的简单提议策略\n - 无需额外训练模型\n - 适用于快速原型验证\n\n2. **EAGLE 提议器**\n - 使用自回归方式生成候选 token\n - 可配合小型语言模型使用\n - 支持更复杂的语义预测\n\n3. **自定义提议器**\n - 通过插件机制扩展\n - 支持用户自定义草稿模型\n\n## 配置参数\n\n推测解码的主要配置参数定义在 `vllm/config/speculative.py` 中：\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `speculative_model` | str | 草稿模型的名称或路径 | - |\n| `num_speculative_tokens` | int | 每轮提议的 token 数量 | 1 |\n| `speculative_draft_tensor_parallel_size` | int | 草稿模型的张量并行大小 | 1 |\n| `speculative_disable_by_num_cached_sequences` | int | 缓存序列数超过此值时禁用推测 | - |\n\n## 使用方法\n\n### 命令行启动\n\n使用 `vllm serve` 命令启动带推测解码的服务：\n\n```bash\nvllm serve \\\n --speculative-model \\\n --num-speculative-tokens 5\n```\n\n### Python API\n\n```python\nfrom vllm import LLM\n\nllm = LLM(\n model=\"meta-llama/Llama-2-70b-chat-hf\",\n speculative_model=\"meta-llama/Llama-2-7b-chat-hf\",\n num_speculative_tokens=5,\n tensor_parallel_size=2\n)\n```\n\n## 性能指标\n\n推测解码的效率通过以下指标衡量：\n\n| 指标 | 说明 |\n|------|------|\n| 接受率 | 草稿模型生成的 token 被目标模型接受的比例 |\n| 加速比 | 推测解码相对于标准自回归解码的速度提升 |\n| Token 吞吐量 | 每秒处理的 token 数量 |\n\n这些指标由 `vllm/v1/spec_decode/metrics.py` 模块收集和计算。\n\n## 限制与注意事项\n\n1. **GPU 内存**: 草稿模型会占用额外的 GPU 显存\n2. **接受率依赖**: 加速效果高度依赖于草稿模型与目标模型输出的一致性\n3. **不支持的场景**: 某些特殊的采样参数（如某些类型的 logits warper）可能与推测解码不兼容\n4. **分布式部署**: 草稿模型和目标模型的并行策略需要协调配置\n\n## 相关文档\n\n- [推测解码功能文档](https://docs.vllm.ai/en/latest/features/speculative_decoding.html)\n- [vLLM 官方文档](https://docs.vllm.ai)\n\n---\n\n\n\n## 分布式并行策略\n\n### 相关页面\n\n相关主题：[架构概览](#page-arch-overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/serving/parallelism_scaling.md](https://github.com/vllm-project/vllm/blob/main/docs/serving/parallelism_scaling.md)\n- [vllm/distributed/parallel_state.py](https://github.com/vllm-project/vllm/blob/main/vllm/distributed/parallel_state.py)\n- [vllm/distributed/device_communicators/cuda_communicator.py](https://github.com/vllm-project/vllm/blob/main/vllm/distributed/device_communicators/cuda_communicator.py)\n- [vllm/config/parallel.py](https://github.com/vllm-project/vllm/blob/main/vllm/config/parallel.py)\n- [vllm/distributed/elastic_ep](https://github.com/vllm-project/vllm/blob/main/vllm/distributed/elastic_ep)\n \n\n# 分布式并行策略\n\n## 概述\n\nvLLM 是一个高性能的大语言模型推理服务框架，支持多种分布式并行策略以满足不同规模和场景的部署需求。这些并行策略包括数据并行（Data Parallelism）、张量并行（Tensor Parallelism）、流水线并行（Pipeline Parallelism）以及它们的组合形式。通过灵活配置这些并行策略，vLLM 能够有效利用多 GPU 和多节点集群的计算资源，实现大规模模型的高效推理。\n\nvLLM 的分布式并行策略建立在 PyTorch 分布式通信原语之上，并针对 LLM 推理的工作负载特征进行了深度优化。其核心设计理念是在保证推理正确性的前提下，最大化 GPU 利用率和吞吐量，同时最小化通信开销。\n\n## 核心并行模式\n\n### 张量并行（Tensor Parallelism, TP）\n\n张量并行是一种将模型的单个层的权重矩阵沿行或列方向切分到多个 GPU 上的技术。在 LLM 中，这通常应用于注意力机制和前馈网络层。每个 GPU 持有完整输入的一部分和部分权重，通过集合通信操作（如 AllReduce）聚合结果。\n\n张量并行的主要优势在于能够将单个层的计算分布到多个设备上，从而支持超出单个 GPU 显存限制的模型。vLLM 采用了 Megatron-LM 风格的张量并行实现，支持 2、4、8 等多种并行度配置。\n\n### 流水线并行（Pipeline Parallelism, PP）\n\n流水线并行将模型的不同层组分配到不同的 GPU 上。每个 GPU 负责模型的一个连续子集，形成计算流水线。这种策略特别适合多节点场景，能够有效减少节点间的通信开销。\n\nvLLM 支持微批处理（micro-batching）来提高流水线并行下的 GPU 利用率，减少流水线气泡（pipeline bubble）。流水线并行通常与张量并行结合使用，形成 3D 并行（TP + PP + DP）。\n\n### 数据并行（Data Parallelism, DP）\n\n数据并行是最简单的并行策略，每个 GPU 持有模型权重的完整副本，独立处理不同的输入批次。vLLM 的数据并行实现支持多种负载均衡模式，包括外部负载均衡（External LB）和混合负载均衡（Hybrid LB）。\n\n在数据并行模式下，vLLM 通过分片 KV 缓存管理来支持多副本推理，提高系统吞吐量。数据并行可以与张量并行和流水线并行叠加使用，形成混合并行配置。\n\n## 分布式并行配置\n\n### 并行配置参数\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `tensor-parallel-size` | int | 张量并行度 | 1 |\n| `pipeline-parallel-size` | int | 流水线并行度 | 1 |\n| `data-parallel-size` | int | 数据并行度 | 1 |\n| `data-parallel-external-lb` | bool | 启用外部负载均衡 | False |\n| `data-parallel-hybrid-lb` | bool | 启用混合负载均衡 | False |\n| `data-parallel-start-rank` | int | 混合负载均衡起始节点 | 0 |\n\n### 启动命令示例\n\n```bash\nvllm serve Qwen/Qwen2.5-3B-Instruct \\\n --tensor-parallel-size 4 \\\n --pipeline-parallel-size 2 \\\n --data-parallel-size 2\n```\n\n上述命令配置了 4x2x2 = 16 GPU 的混合并行拓扑，适用于大规模模型部署场景。\n\n## 架构设计\n\n### 分布式并行状态管理\n\nvLLM 通过 `parallel_state.py` 模块管理分布式并行状态。该模块负责初始化和协调各并行维度的通信组，建立 GPU 之间的拓扑关系，并提供进程组查询接口。\n\n```mermaid\ngraph TD\n A[全局初始化] --> B[创建通信组]\n B --> C[张量并行组 TP]\n B --> D[流水线并行组 PP]\n B --> E[数据并行组 DP]\n C --> F[AllReduce 通信]\n D --> G[流水线调度]\n E --> H[数据分片]\n F --> I[聚合结果]\n G --> I\n H --> I\n```\n\n### 设备通信层\n\n`cuda_communicator.py` 实现了针对 NVIDIA GPU 优化的集合通信操作。该模块封装了 PyTorch 分布式通信原语，提供了高效的 AllReduce、Broadcast、AllGather 等操作实现。通信层针对 LLM 推理的通信模式进行了优化，最小化了流水线气泡和通信延迟。\n\n### 弹性并行（Elastic EP）\n\nvLLM 支持弹性并行（Elastic EP），允许在运行时动态调整数据并行组的规模。这一特性通过 `vllm/distributed/elastic_ep` 模块实现，提供了容错能力和弹性扩展能力。当集群中的部分节点发生故障或新增时，系统能够自动重新配置数据并行组，无需中断服务。\n\n## 分片 KV 缓存管理\n\n分片 KV 缓存是 vLLM 实现高效数据并行的关键技术之一。在传统的数据并行中，所有副本需要共享或复制 KV 缓存，导致显存浪费或同步开销。vLLM 通过将 KV 缓存按注意力头维度分片，让每个数据并行副本持有 KV 缓存的不同部分。\n\n这种方法的优势在于：\n\n- 减少每个副本的 KV 缓存显存占用\n- 支持更大的批量处理\n- 通过 PagedAttention 技术实现细粒度的显存管理\n- 支持 Prefix Caching 以加速重复前缀的推理\n\n## 通信优化\n\n### CUDA 通信优化\n\nvLLM 的设备通信层利用 CUDA 的高效内存复制和集合操作，减少 GPU 间通信延迟。通信操作与计算重叠执行，通过异步执行和流水线技术隐藏通信开销。\n\n### 流水线气泡优化\n\n在流水线并行中，vLLM 采用微批处理策略来减少流水线气泡。通过将每个批次划分为多个微批次，系统能够更充分地利用流水线各阶段的 GPU 资源，提高整体吞吐量。\n\n## 监控与调优\n\n### 性能指标\n\nvLLM 提供了丰富的分布式并行性能指标，包括：\n\n| 指标 | 说明 |\n|------|------|\n| GPU 利用率 | 各 GPU 的计算利用率 |\n| 通信带宽 | GPU 间通信的实际带宽 |\n| 流水线气泡率 | 流水线空闲时间占比 |\n| 吞吐量 | 每秒处理的请求数 |\n\n### 分布式追踪\n\nvLLM 支持 OpenTelemetry 分布式追踪，能够追踪请求在多个 GPU 和节点间的处理路径。这对于诊断分布式并行下的性能瓶颈和通信问题非常重要。\n\n配置示例：\n\n```bash\nopentelemetry-instrument vllm serve facebook/opt-125m\n```\n\n## 最佳实践\n\n### 并行度选择\n\n- **单节点多卡**：推荐使用张量并行（TP=2/4/8），根据显存和模型大小调整\n- **多节点部署**：推荐 TP × PP × DP 混合并行，充分利用节点内高带宽和节点间网络\n- **大批量推理**：增加数据并行度，提高系统吞吐量\n\n### 配置建议\n\n- 确保 NVLink 连接用于张量并行通信\n- 流水线并行的节点间网络带宽应足够高\n- 数据并行适用于无状态或状态可分片的模型\n\n## 参考资料\n\n- 张量并行实现：[vllm/distributed/parallel_state.py]()\n- 设备通信层：[vllm/distributed/device_communicators/cuda_communicator.py]()\n- 并行配置：[vllm/config/parallel.py]()\n- 弹性并行：[vllm/distributed/elastic_ep]()\n- 官方文档：[docs/serving/parallelism_scaling.md]()\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：vllm-project/vllm\n\n摘要：发现 21 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: Qwen3.5-397B-NVFP4 Disagg accuracy gsm8k collapses with async scheduling。\n\n## 1. 安装坑 · 来源证据：[Bug]: Qwen3.5-397B-NVFP4 Disagg accuracy gsm8k collapses with async scheduling\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Qwen3.5-397B-NVFP4 Disagg accuracy gsm8k collapses with async scheduling\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1a71634c530044a68b9160080d55de0a | https://github.com/vllm-project/vllm/issues/42182 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：[Bug]: vLLM v1 with prefix caching: first request differs from subsequent identical requests at temperature=0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: vLLM v1 with prefix caching: first request differs from subsequent identical requests at temperature=0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_58327949a4524ed082bd189b53f713a1 | https://github.com/vllm-project/vllm/issues/40896 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：[Usage]: How to proactively clear CPU-resident memory left behind by unloaded LoRA adapters after calling `/v1/unload_l…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Usage]: How to proactively clear CPU-resident memory left behind by unloaded LoRA adapters after calling `/v1/unload_lora_adapter`?\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fb1461834fe34049bd05182574d3e5e5 | https://github.com/vllm-project/vllm/issues/42207 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：v0.18.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.18.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_317a03f9de4e459f9be42064c7318b2c | https://github.com/vllm-project/vllm/releases/tag/v0.18.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 能力坑 · 来源证据：[Feature]: Qwen3.5-Moe LoRA Support (experts)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：[Feature]: Qwen3.5-Moe LoRA Support (experts)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2d068d43c6654f3cab6b48bf98dad116 | https://github.com/vllm-project/vllm/issues/40005 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:599547518 | https://github.com/vllm-project/vllm | README/documentation is current enough for a first validation pass.\n\n## 7. 运行坑 · 来源证据：v0.20.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.20.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ecf37722dff6494c82b384225e34bcb0 | https://github.com/vllm-project/vllm/releases/tag/v0.20.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:599547518 | https://github.com/vllm-project/vllm | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:599547518 | https://github.com/vllm-project/vllm | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:599547518 | https://github.com/vllm-project/vllm | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 11. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:599547518 | https://github.com/vllm-project/vllm | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 来源证据：[Bug]: ngram speculative decoding changes greedy output on Qwen3-0.6B / A100\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: ngram speculative decoding changes greedy output on Qwen3-0.6B / A100\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9ce279a037934e8085332120bfdaca86 | https://github.com/vllm-project/vllm/issues/41758 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 13. 安全/权限坑 · 来源证据：v0.16.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.16.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_57ff11ff995a4809a33a38ff7504a5ef | https://github.com/vllm-project/vllm/releases/tag/v0.16.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：v0.17.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.17.0\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4592ced4fde24aa9aa808caa40e25b84 | https://github.com/vllm-project/vllm/releases/tag/v0.17.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：v0.18.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.18.0\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7ca09904f8164e94a3a1bc489d32d1ff | https://github.com/vllm-project/vllm/releases/tag/v0.18.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：v0.19.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.19.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cdb0d7a7f491474da7b93583ec643c00 | https://github.com/vllm-project/vllm/releases/tag/v0.19.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：v0.19.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.19.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8c2ec43cf6f147d49f80f22bcd199e8f | https://github.com/vllm-project/vllm/releases/tag/v0.19.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 18. 安全/权限坑 · 来源证据：v0.20.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.20.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c867dafed19f4b97978d637aea4c7308 | https://github.com/vllm-project/vllm/releases/tag/v0.20.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v0.20.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.20.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dc6a717c695b47838899da8c9791f907 | https://github.com/vllm-project/vllm/releases/tag/v0.20.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:599547518 | https://github.com/vllm-project/vllm | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:599547518 | https://github.com/vllm-project/vllm | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：vllm-project/vllm\n\n摘要：发现 21 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: Qwen3.5-397B-NVFP4 Disagg accuracy gsm8k collapses with async scheduling。\n\n## 1. 安装坑 · 来源证据：[Bug]: Qwen3.5-397B-NVFP4 Disagg accuracy gsm8k collapses with async scheduling\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Qwen3.5-397B-NVFP4 Disagg accuracy gsm8k collapses with async scheduling\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1a71634c530044a68b9160080d55de0a | https://github.com/vllm-project/vllm/issues/42182 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：[Bug]: vLLM v1 with prefix caching: first request differs from subsequent identical requests at temperature=0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: vLLM v1 with prefix caching: first request differs from subsequent identical requests at temperature=0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_58327949a4524ed082bd189b53f713a1 | https://github.com/vllm-project/vllm/issues/40896 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：[Usage]: How to proactively clear CPU-resident memory left behind by unloaded LoRA adapters after calling `/v1/unload_l…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Usage]: How to proactively clear CPU-resident memory left behind by unloaded LoRA adapters after calling `/v1/unload_lora_adapter`?\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fb1461834fe34049bd05182574d3e5e5 | https://github.com/vllm-project/vllm/issues/42207 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：v0.18.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.18.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_317a03f9de4e459f9be42064c7318b2c | https://github.com/vllm-project/vllm/releases/tag/v0.18.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 能力坑 · 来源证据：[Feature]: Qwen3.5-Moe LoRA Support (experts)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：[Feature]: Qwen3.5-Moe LoRA Support (experts)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2d068d43c6654f3cab6b48bf98dad116 | https://github.com/vllm-project/vllm/issues/40005 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:599547518 | https://github.com/vllm-project/vllm | README/documentation is current enough for a first validation pass.\n\n## 7. 运行坑 · 来源证据：v0.20.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.20.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ecf37722dff6494c82b384225e34bcb0 | https://github.com/vllm-project/vllm/releases/tag/v0.20.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:599547518 | https://github.com/vllm-project/vllm | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:599547518 | https://github.com/vllm-project/vllm | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:599547518 | https://github.com/vllm-project/vllm | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 11. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:599547518 | https://github.com/vllm-project/vllm | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 来源证据：[Bug]: ngram speculative decoding changes greedy output on Qwen3-0.6B / A100\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: ngram speculative decoding changes greedy output on Qwen3-0.6B / A100\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9ce279a037934e8085332120bfdaca86 | https://github.com/vllm-project/vllm/issues/41758 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 13. 安全/权限坑 · 来源证据：v0.16.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.16.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_57ff11ff995a4809a33a38ff7504a5ef | https://github.com/vllm-project/vllm/releases/tag/v0.16.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：v0.17.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.17.0\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4592ced4fde24aa9aa808caa40e25b84 | https://github.com/vllm-project/vllm/releases/tag/v0.17.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：v0.18.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.18.0\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7ca09904f8164e94a3a1bc489d32d1ff | https://github.com/vllm-project/vllm/releases/tag/v0.18.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：v0.19.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.19.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cdb0d7a7f491474da7b93583ec643c00 | https://github.com/vllm-project/vllm/releases/tag/v0.19.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：v0.19.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.19.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8c2ec43cf6f147d49f80f22bcd199e8f | https://github.com/vllm-project/vllm/releases/tag/v0.19.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 18. 安全/权限坑 · 来源证据：v0.20.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.20.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c867dafed19f4b97978d637aea4c7308 | https://github.com/vllm-project/vllm/releases/tag/v0.20.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v0.20.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.20.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dc6a717c695b47838899da8c9791f907 | https://github.com/vllm-project/vllm/releases/tag/v0.20.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:599547518 | https://github.com/vllm-project/vllm | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:599547518 | https://github.com/vllm-project/vllm | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# vllm - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 vllm 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: A high-throughput and memory-efficient inference and serving engine for LLMs 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 暂无明确的运行时能力线索。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-intro：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装指南。围绕“安装指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-arch-overview：架构概览。围绕“架构概览”模拟一次用户任务，不展示安装或运行结果。\n4. page-v1-engine：V1 引擎架构。围绕“V1 引擎架构”模拟一次用户任务，不展示安装或运行结果。\n5. page-paged-attention：PagedAttention 与 KV 缓存管理。围绕“PagedAttention 与 KV 缓存管理”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-intro\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-arch-overview\n输入：用户提供的“架构概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-v1-engine\n输入：用户提供的“V1 引擎架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-paged-attention\n输入：用户提供的“PagedAttention 与 KV 缓存管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-intro：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-arch-overview：Step 3 必须围绕“架构概览”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-v1-engine：Step 4 必须围绕“V1 引擎架构”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-paged-attention：Step 5 必须围绕“PagedAttention 与 KV 缓存管理”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/vllm-project/vllm\n- https://github.com/vllm-project/vllm#readme\n- README.md\n- vllm/__init__.py\n- vllm/version.py\n- setup.py\n- docs/getting_started/installation/README.md\n- requirements/common.txt\n- requirements/cuda.txt\n- docs/design/arch_overview.md\n- vllm/engine/llm_engine.py\n- vllm/engine/arg_utils.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 vllm 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：vllm-project/vllm\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install vllm\n```\n\n来源：https://github.com/vllm-project/vllm#readme\n\n## 来源\n\n- repo: https://github.com/vllm-project/vllm\n- docs: https://github.com/vllm-project/vllm#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_4b19ac5ad26a41138863fa55543fb1f5"
}