在 2× RTX 3090 上，针对 Qwen3.8-27B 在 vLLM 上（无 NVLink）进行 32 并发流处理时，总吞吐量可达 308 tok/s。这足以在消费级 24GB 显卡上驱动成群的本地编码智能体。

我们从压力测试中学到的要点：

• 推测解码 (MTP) 在 ≤8 并发流时表现优异；超过此数量则建议关闭，可带来 19–27% 的吞吐量提升。
• DFlash2 的外部草稿模型在 24GB 显卡上处理 8 并发流时会出现显存不足 (OOM) → 因此 MTP 的内置头机制是应对高并发的可行方案。
• KV 缓存并非瓶颈，首 token 延迟 (TTFT) 才是（从 0.6 秒激增至 12 秒），而曾导致 MTP 在并发时崩溃的问题已修复 —— 特别感谢 @A1RM4X_TV（PR #1051）。
• 完整文章及在您自己设备上复现的指南：
  https://github.com/noonghunna/club-3090/discussions/1092…

需要更多显卡还是更大显存？请分享您的数据。

noonghunna/club-3090

来源：https://github.com/noonghunna/club-3090

club-3090

本地部署 LLM 的 RTX 3090 实战配置集。
多引擎（vLLM, llama.cpp, ik_llama）、多模型、模型无关设计。
如果您拥有一两张 RTX 3090，并希望在家庭、家庭实验室或作为开发后端运行现代 LLM，本仓库汇集了经过验证的配置、补丁和基准测试。

🎯 4090 或 5090 用户？
Docker Compose 配置支持跨设备运行——贡献者已对两者进行过基准测试并提供了实测数据：
能否使用 4090？→ · 能否使用 5090？→。
工具链针对 3090 进行了校准，但配置具备设备类别感知能力；具体类别注意事项（如 4090 更严格的空闲显存、5090 的 32 GB 配额）及跨设备基准测试行已收录在 FAQ 中。

🎨 还想生成图像？
Image Studio 套件 可在两块 GPU 上同时运行 Ideogram-4 图像生成、一个聊天模型和 Open WebUI——仅需一条命令：bash scripts/setup-image-studio.sh。

快速开始

🪟 在 Windows 上？
以下步骤假设您使用 Linux/macOS。请先设置 WSL2 → 文档/WSL 安装指南（从头到尾的完整流程）。原生 Windows 只能运行 上游 llama.cpp 二进制文件——本仓库的工具链均不适用。

# 1. 克隆仓库
git clone https://github.com/noonghunna/club-3090.git
cd club-3090

# 配置分析工具需要 PyYAML。Ubuntu LTS 通常通过 python3-yaml 提供；否则运行：
python3 -m pip install pyyaml

# 2. 选择/下载 + SHA 校验模型（交互式硬件感知选择器）
# （询问您选择哪个模型，然后选择存放模型权重的位置——可选仓库内默认路径、~/models 或其他驱动器的自定义路径。
#   若要跳过提示：`export MODEL_DIR=/path/to/models` 并传递模型名称。详见 FAQ。）
bash scripts/setup.sh

# 或脚本化调用：
# bash scripts/setup.sh qwen3.6-27b

# 3. 选择配置并启动（交互式向导：询问模型 → GPU → 预估显存预算）
bash scripts/launch.sh

# 或让解析器根据您的模型+硬件自动选择（.env 固定配置 ‖ 精选默认值）：
# bash scripts/launch.sh --variant qwen3.6-27b/default   # 您为该模型设定的默认值

# 或通过显式配置跳过向导：
# bash scripts/launch.sh --variant vllm/minimal           # 单卡 qwen（32K 上下文，无视觉功能，~32/33 TPS）
# bash scripts/launch.sh --variant vllm/dual              # 双卡 262K + 视觉功能

# 已退役的单卡变体仍可通过 --force 启动；详见文档/单卡.md 中的“逃逸通道”。
# 或使用部分标志（向导将填充其余部分）：
# bash scripts/launch.sh --model qwen3.6-27b --gpus 0,1
# bash scripts/launch.sh --tp 2 --pp 1  # 覆盖 vLLM 并行配置

# 查看本机可运行的变体及每个模型的默认视图
# （按 GPU 数量硬件过滤；添加 --all 可查看所有变体）：
# bash scripts/switch.sh --list          # 可在此运行
# bash scripts/switch.sh --list --all    # 全部

# 固定您自己的默认配置，以便裸 `launch.sh` 直接进入该配置：
# bash scripts/switch.sh --set-default vllm/dual  # 例如：固定双卡默认值；清除：--clear-default qwen3.6-27b

# 4. 完整性测试（启动器已打印此 curl 命令）
curl -sf http://localhost:8020/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3.6-27b","messages":[{"role":"user","content":"法国首都？"}],"max_tokens":200}'

# 5. 运行标准基准测试
bash scripts/bench.sh

# 6. 之后无需重新点击向导即可切换：
bash scripts/switch.sh vllm/dual
bash scripts/switch.sh --list  # 所有可启动的变体（--all 包括已退役的）

# 7. 随着技术栈更新（引擎版本升级、新的 Compose 变体、内部补丁更新）保持安装最新：
bash scripts/update.sh

launch.sh 会调用 switch.sh（关闭旧版，启动新版）然后调用 verify-full.sh，因此您在将客户端指向它之前即可确认服务运行正常。所有辅助脚本详见 scripts/。

偏好图形界面而非命令行？—— 服务控制台（c3）

c3 是一个类似 lazydocker 的终端 UI，封装了相同的流程——发现 → 服务 → 操作 → 验证——整合在一个键盘驱动的控制台中：浏览目录并用 ⏎ 启动一个变体，实时查看 GPU / 场景 / 容器，运行 Doctor 健康检查，以及（生产者通道）执行添加模型的流程。

# 从检出安装（控制台 + 仓库内置核心包）：
uv pip install -e tools/serve-cockpit  # 使用 uv（推荐——一条命令）
# ...或普通 pip：
pip install -e tools/tui-core && pip install -e tools/serve-cockpit

c3  # 启动（亦可使用：python -m club3090_cockpit）

首次运行： 按 S → 设置您的模型目录（权重下载位置）和 HuggingFace 令牌 → Ctrl+S 保存；然后按 r 浏览目录并启动一个模型。

c3 --lean（或应用内 [C]）隐藏生产者通道，仅提供消费者视图。

执行 git pull 后，请重新运行安装以获取新的依赖项和 UI 变更。完整快捷键说明及详情 → tools/serve-cockpit/。

⚠️ 单卡长上下文注意： 在 24GB 单卡 vLLM 上，断崖 2（GDN 预填充在 >~50K 单提示时 OOM）问题依然存在。
变通方案： vllm/dual（TP=2 可规避此问题）。
⚠️ 之前的单卡逃逸路径 llamacpp/default 已于 2026-08-12 退役（仅 --force 可用）——在单卡上已不再有能规避断崖的 qwen 路径。完整诊断详见 docs/CLIFFS.md。

总结——本仓库是什么

• 两条互补路径 —— 根据您的工作负载瓶颈进行选择：
  • 🏎 vLLM 双卡 = 最高吞吐量。最高可达 127 TPS 代码（DFlash）或 262K 下 4 并发流（turbo）。功能齐全（视觉 · 工具 · MTP · 流式处理）。
  • 🛡 llama.cpp 单卡 = 最高稳健性。单卡 3090 上可实现完整 200K 上下文（安全最大化——余量充足；参见 CLIFFS）。经压力测试验证：无预填充断崖，25K token 工具返回正常，91K 针刺梯级通过。约 51/60 TPS（Q4_K_M + MTP）——比 vLLM 双卡慢，但不会在实际使用工具的智能体中崩溃。
• 经过验证的 Docker Compose 配置，适用于上述两条路径——在 localhost:8020 上提供即插即用的 OpenAI 兼容 API。
• 多引擎：vLLM（功能完整）、llama.cpp（最大上下文 + 稳健性）、ik_llama（最佳 GGUF 量化）。 (SGLang 已评估——目前因 Ampere 架构受阻；参见 docs/engines/SGLANG.md。)
• 模型无关：目前为 Qwen3.6-27B 及其伙伴模型提供精选配置；结构可随我们添加模型而扩展。
• 通用 pull（v0.8.0；v0.8.2 扩展）——评估任何 safetensors HF 仓库，获得诚实的一行适配结论（--recommend），当 pull 被硬性阻止时，可在一个同意步骤中将脱敏诊断信息发回（--submit-last）。每个版本覆盖更广泛的架构。详见 docs/PULL.md。

本地 AI 新手？ → docs/LOCAL_AI_PRIMER.md——通俗易懂：硬件 / 引擎 / 模型大小 / 量化如何协同工作。

初次接触本仓库？ → docs/GETTING_STARTED.md——5 分钟克隆到 curl 的路径。

已在运行，想比较引擎？ → docs/engines/

选择引擎（vLLM / llama.cpp / ik_llama）？ → docs/INFERENCE_ENGINES.md

对量化名称感到困惑（Q4_K_M vs IQ4_KS vs AWQ）？ → docs/QUANTIZATION.md

硬件问题（4090, NVLink, 功率限制）？ → docs/HARDWARE.md

不知道 TPS / KV / MTP 是什么？ → docs/GLOSSARY.md

选择您的路径

每个硬件页面都列出了所有支持的模型及相应设备数量的可用 Compose 配置，以及实测 TPS 和每个工作负载的注意事项。特定模型深入分析（量化、引擎内部）位于 models// 下。

支持的模型

¹ Ampere 24GB 上的单卡 Gemma 4：vLLM 和主线 llama.cpp 均受阻（head_dim=512 FA 墙，尚无 Ampere FA 内核）。社区 beellama.cpp 分支使用 FA_ALL_QUANTS=ON 构建，可在单卡 3090 上流畅运行——47/88 TPS，100–150K 上下文，109/114 8 包（2026-05-27 验证）。32GB+ GPU 可运行标准 vLLM 路径（由 @apnar 在 RTX 5090 32GB 上验证 (https://github.com/noonghunna/club-3090/discussions/67#discussioncomment-16832042)）。 ² Gemma 4 26B-A4B 单卡尚未在 Ampere 上测试；在适中上下文下应可适配 24GB 3090，但目前配置仅支持双卡。

更多模型即将推出——它们将遵循相同的内部模式位于 models// 下。

实测 TPS 一览

Qwen3.6-27B 按配置的 TPS
基准测试协议：3 次预热 + 5 次测量运行。测试方法详见 scripts/bench.sh。每个配置的详细信息 + 逐次运行数据 + 显存 + AL/接受率：models/qwen3.6-27b/CHANGELOG.md。

基准测试

在您自己的设备上复现上述数据。所有基准测试针对当前运行的 Compose 进行（先通过 launch.sh 启动一个）。

吞吐量 (TPS) —— 标准叙述 + 代码基准测试（每个提示 3 次预热 + 5 次测量）：

bash scripts/bench.sh

行为质量 —— 工具调用正确性、指令遵循、结构化输出等，通过 benchlocal-cli：

bash scripts/quality-test.sh         # --medium：5 包（默认，~15-25 分钟，无 Docker）
bash scripts/quality-test.sh --quick # 2 包（~5-10 分钟，无 Docker）
bash scripts/quality-test.sh --full  # 8 包 / 150 场景（~25-40 分钟，需要 Docker）
bash scripts/quality-test.sh --pack aider-polyglot-30 # 一个命名包
bash scripts/quality-test.sh --reasoning # HE+/LCB/GPQA(需授权)/GSM 推理套件——与 --full 分开；代码包需要 Docker

完整重测（一个模型，所有内容） —— 标准的 5 步流程（bench → verify-stress → quality-test --full → soak → aider-polyglot-30），每个环节约 1.75-2 小时。所有产物位于 results/rebench// 下：

bash scripts/rebench-full.sh            # 从 MODEL 自动标记
bash scripts/rebench-full.sh --tag qwen-int8 # 显式标记
bash scripts/rebench-full.sh --skip soak,aider # 跳过阶段（CSV）
bash scripts/rebench-full.sh --resume   # 恢复中断的运行（跳过已完成步骤）

# 端点优先模式（非 Docker 引擎：llama-swap, ramalama, 原生 llama-server, ...）：
bash scripts/rebench-full.sh \
  --url http://HOST:PORT --model 'MODEL-NAME' --engine llama-cpp # vllm|llama-cpp|sglang|other

对两个不同模型运行 rebench-full.sh 可组装匹配配置的头对头比较。完整的测试流程参考：docs/QUALITY_TEST.md。

诊断

当提交错误报告、共享跨设备数据或回复分类讨论时，生成一个可粘贴的分类报告——它以 markdown 格式捕获硬件、操作系统、GPU、容器运行时、技术栈版本和活动容器状态。家庭路径、主机名、用户名和 HF 令牌默认会被脱敏，因此可安全粘贴到公开问题或讨论中。

# 快速报告（约 2 秒）——硬件 + 技术栈 + 启动日志亮点
bash scripts/report.sh

# 将完整的跨设备检测捕获到文件，准备粘贴到问题/讨论中
#（约 35 分钟——去掉 --full 则仅硬件捕获约 2 秒）
bash scripts/report.sh --full > my-rig.md

# 添加实时测试输出（根据讨论需要选择）：
bash scripts/report.sh --verify        # + verify-full.sh（约 1-2 分钟）
bash scripts/report.sh --stress        # + verify-stress.sh 7/7（约 5-10 分钟）
bash scripts/report.sh --soak          # + 持续压力测试（约 25 分钟）——捕获断崖 2b
bash scripts/report.sh --bench         # + bench.sh TPS（约 3 分钟）
bash scripts/report.sh --full          # 全部四项——标准的“全量”跨设备检测（约 35 分钟）

# 仅内部共享（禁用脱敏）：
bash scripts/report.sh --no-redact

--soak 是一个独立标志，因为一个配置可能通过 verify + stress + bench，但在多轮持续压力测试（约 25K 累积 token 时的断崖 2b）中失败——压力测试是目前唯一能捕获这种智能体工作负载故障模式的测试。详见 docs/CLIFFS.md。

如果 launch.sh / switch.sh 无法启动——直接加载 Compose

启动脚本在引导过程中封装了预检（硬件 / 可用显存检查）、.env 解析和 Python 驱动的变体→Compose 注册表。如果其中任一环节出问题——例如错误的预检失败、Windows 上的 CRLF/.env 兼容问题或缺少 PyYAML——可以绕过它们，直接使用 Docker 启动 Compose 文件。

两种升级方法（假设您已下载权重——快速开始第 2 步）：

# 1. 仅跳过硬件 / 可用显存预检（保留 .env + 注册表）：
bash scripts/switch.sh --force llamacpp/default

# 2. 完全绕过脚本——直接用 Docker 启动 Compose 文件：