Andyyyy64/whichllm

# whichllm [](https://pypi.org/project/whichllm/) [](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT) [](https://github.com/Andyyyy64/whichllm/actions/workflows/test.yml) [](https://github.com/sponsors/Andyyyy64) **为您找出能在本地硬件上实际运行的最佳本地LLM。** 自动检测您的 GPU/CPU/RAM，并从 HuggingFace 中为您的系统匹配排名靠前的模型。 [日本語版はこちら](docs/README.ja.md)  ## 查看演示 ``` $ whichllm --gpu "RTX 4090" #1 Qwen/Qwen3.6-27B 27.8B Q5_K_M score 92.8 27 t/s #2 Qwen/Qwen3-32B 32.0B Q4_K_M score 83.0 31 t/s #3 Qwen/Qwen3-30B-A3B 30.0B Q5_K_M score 82.7 102 t/s ``` 这个 32B 模型**完全适合您的显卡** — whichllm 仍将 27B 模型排在第 1 位， 因为它在真实基准测试中得分更高，且是更新一代的模型。 仅凭尺寸判断“什么能运行？”的工具可能会给您推荐更大的那个。这个差距 正是 whichllm 的核心价值所在。（注意 #3：一个 102 t/s 的 MoE 模型 — 速度排名基于*活跃*参数，质量基于*总*参数。） ### 我能运行什么？ 真正的顶级推荐（2026 年 5 月快照 — 您的结果将跟踪**实时** HuggingFace 数据，这不是一个静态列表）： | 硬件 | 显存 | 首选推荐 | 速度 | |---|---|---|---| | RTX 5090 | 32 GB | `Qwen3.6-27B` · Q6_K · 得分 94.7 | ~40 t/s | | RTX 4090 / 3090 | 24 GB | `Qwen3.6-27B` · Q5_K_M · 得分 92.8 | ~27 t/s | | RTX 4060 | 8 GB | `Qwen3-14B` · Q3_K_M · 得分 71.0 | ~22 t/s | | Apple M3 Max | 36 GB | `Qwen3.6-27B` · Q5_K_M · 得分 89.4 | ~9 t/s | | 仅CPU | — | `gpt-oss-20b` (MoE) · Q4_K_M · 得分 45.2 | ~6 t/s | 在购买前，使用 `whichllm --gpu "<您的显卡型号>"` 模拟任意配置。 ## 星标历史 [](https://www.star-history.com/#Andyyyy64/whichllm&Date) ## 为什么选择 whichllm？ 将模型装入您的显存是容易的部分。难的部分是知道 **哪些能运行的模型才是最好的** — 而这正是 whichllm 设计要解决的核心问题。 - **基于证据的排名，而非尺寸启发式** — 首选推荐是 从合并的真实基准测试中选出的（LiveBench、Artificial Analysis、 Aider、多模态/视觉、Chatbot Arena ELO、Open LLM Leaderboard）— 决不是“恰好能运行的最大模型”。 - **时间感知** — 过时的排行榜会沿模型谱系被降权，这样 一个 2024 年的模型就不会因为过时的得分而超越当代模型。基准快照日期 在每个排名下方打印，因此过时的推荐是显而易见的，而不是被默默信任。 - **证据分级与保护** — 每个分数都标记有 `direct` / `variant` / `base` / `interpolated` / `self-reported`，并根据置信度进行折扣。捏造的上传者声明和跨家族继承（一个小分支借用其大得多的基础模型的分数）会被主动拒绝。 - **架构感知的估算** — VRAM = 权重 + GQA KV 缓存 + 激活 + 开销；速度受带宽限制，并考虑了量化效率、后端因素、MoE 活跃/总参数划分，以及统一内存与独立PCIe部分卸载建模。 - **单条命令，可脚本化** — `whichllm` 打印答案；添加 `--json | jq` 用于管道操作。无需 TUI，无需记忆键绑定。 - **实时数据** — 模型直接从 HuggingFace API 获取，为离线或速率受限的情况提供了精心策划的冻结回退数据。 ## 功能特性 - **自动检测硬件** — NVIDIA、AMD、Apple Silicon、仅CPU - **智能排名** — 根据显存适配性、速度和基准质量为模型评分 - **单命令聊天** — `whichllm run` 立即下载并启动聊天会话 - **代码片段** — `whichllm snippet` 打印任意模型的可立即运行的 Python 代码 - **实时数据** — 直接从 HuggingFace 获取模型（已缓存以提高性能） - **基准感知** — 整合真实评估分数，并应用基于置信度的衰减 - **任务配置文件** — 按通用、编码、视觉或数学用例筛选 - **GPU模拟** — 使用任意GPU测试：`whichllm --gpu "RTX 4090"` - **硬件规划** — 反向查找：`whichllm plan "llama 3 70b"` - **升级规划** — 比较您当前的机器与候选GPU - **JSON输出** — 对管道友好：`whichllm --json` ## 运行与代码片段 **单条命令即可试用任何模型。** 无需手动安装 — whichllm 通过 `uv` 创建隔离环境，安装依赖，下载模型，并启动交互式聊天。  ``` # 与模型聊天（自动选择最佳GGUF变体） whichllm run "qwen 2.5 1.5b gguf" # 为你的硬件自动选择最佳模型并聊天 whichllm run # 仅CPU模式 whichllm run "phi 3 mini gguf" --cpu-only ``` 支持**所有模型格式**： - **GGUF** — 通过 `llama-cpp-python`（轻量、快速） - **AWQ / GPTQ** — 通过 `transformers` + `autoawq` / `auto-gptq` - **FP16 / BF16** — 通过 `transformers` 获取**可直接复制粘贴的 Python 代码片段**： ``` whichllm snippet "qwen 7b" ``` ``` from llama_cpp import Llama llm = Llama.from_pretrained( repo_id="Qwen/Qwen2.5-7B-Instruct-GGUF", filename="qwen2.5-7b-instruct-q4_k_m.gguf", n_ctx=4096, n_gpu_layers=-1, verbose=False, ) output = llm.create_chat_completion( messages=[{"role": "user", "content": "Hello!"}], ) print(output["choices"][0]["message"]["content"]) ``` ## 安装 ### uv (推荐) ``` uvx whichllm ``` 要永久安装： ``` uv tool install whichllm ``` ### Homebrew ``` brew install andyyyy64/whichllm/whichllm ``` ### pip ``` pip install whichllm ``` ### 开发 ``` git clone https://github.com/Andyyyy64/whichllm.git cd whichllm uv sync --dev uv run whichllm uv run pytest ``` ## 使用方法 ``` # 自动检测硬件并展示最佳模型 whichllm # 模拟GPU（例如计划购买） whichllm --gpu "RTX 4090" whichllm --gpu "RTX 5090" # 指定变体 whichllm --gpu "RTX 5060 16" # 仅CPU模式 whichllm --cpu-only # 更多结果/筛选 whichllm --top 20 whichllm --quant Q4_K_M whichllm --min-speed 30 whichllm --evidence base # allow id/base-model matches whichllm --evidence strict # id-exact only (same as --direct) whichllm --direct # JSON输出 whichllm --json # 强制刷新（忽略缓存） whichllm --refresh # 仅显示硬件信息 whichllm hardware # 计划：特定模型需要什么GPU？ whichllm plan "llama 3 70b" whichllm plan "Qwen2.5-72B" --quant Q8_0 whichllm plan "mistral 7b" --context-length 32768 # 升级：对比你的当前机器与候选GPU whichllm upgrade "RTX 4090" "RTX 5090" "H100" whichllm upgrade "Apple M4 Max" --top 5 # 运行：即时下载模型并聊天 whichllm run "qwen 2.5 1.5b gguf" whichllm run # auto-pick best for your hardware # 代码片段：打印可运行的Python代码 whichllm snippet "qwen 7b" whichllm snippet "llama 3 8b gguf" --quant Q5_K_M ``` JSON 模型行包含 `estimated_tok_per_sec`、`speed_confidence`、 `speed_range_tok_per_sec` 和 `speed_notes`。速度范围是规划范围，而非实时基准。 ## 集成 ### Ollama 使用 JSON 输出为脚本提供数据，将 HuggingFace ID 映射到您本地的 Ollama 模型名称： ``` # 选择顶级HuggingFace模型ID whichllm --top 1 --json | jq -r '.models[0].model_id' # 查找最佳编码模型ID whichllm --profile coding --top 1 --json | jq -r '.models[0].model_id' ``` Ollama 模型名称并不总是与 HuggingFace 仓库 ID 匹配，因此在 `ollama run` 之前通常需要一个小型映射步骤。 ### Shell 别名 添加到您的 `.bashrc` / `.zshrc`： ``` alias bestllm='whichllm --top 1 --json | jq -r ".models[0].model_id"' # 用法：ollama run $(bestllm) ``` ## 评分系统 每个模型获得一个 0-100 的分数。基准测试质量和尺寸构成核心； 证据置信度和运行时适配性随后缩放，速度、来源可信度和流行度作为调整因素。 | 因素 | 影响 | 描述 | |--------|--------|-------------| | 基准质量 | 核心 | 合并的 LiveBench / Artificial Analysis / Aider / Vision / Arena ELO / Open LLM Leaderboard，并根据来源置信度加权 | | 模型尺寸 | 最高 35 | `log2` 缩放的全球知识代理（MoE 使用总参数量） | | 量化 | × 惩罚 | 位宽较低的量化会以乘法方式被折扣 | | 证据置信度 | ×0.55–1.0 | 无 / 仅自报告 ×0.55，继承 ×0.78，直接完全置信 | | 运行时适配性 | ×0.50–1.0 | 部分卸载 ×0.72，仅CPU ×0.50 | | 速度 | -8 到 +8 | 可用性门槛对比依赖适配性的 tok/s 最低值；报告时附带置信度和范围元数据 | | 来源可信度 | -5 到 +5 | 官方组织加分，已知重新打包者扣分 | | 流行度 | 平局决胜者 | 下载量/点赞数；随着证据增强，权重减小 | 分数标记： - **`~`** (黄色) — 没有直接基准；分数继承/插值自模型家族 - **`!sr`** (亮黄色) — 仅上传者报告的基准，未经独立验证 - **`?`** (红色) — 无基准数据可用 `--status` 中的速度标记： - **`~`** (黄色) — 可用的 tok/s 估算范围 - **`?`** (红色) — 低置信度的速度估算；后端/运行时敏感性高 ## 文档 - [CLI 参考](docs/cli.md) - [工作原理](docs/how-it-works.md) - [评分](docs/scoring.md) - [硬件检测与模拟](docs/hardware.md) - [运行与代码片段](docs/run-snippet.md) - [故障排除](docs/troubleshooting.md) ## 工作原理 ### 数据管道 1. **模型获取** — 从 HuggingFace API 获取流行模型： - 文本生成（下载量和最近更新） - GGUF 过滤（单独查询以提高覆盖率） - 视觉模型 (`image-text-to-text`)，当使用 `--profile vision` 或 `any` 时 2. **基准来源** — *当前层*（LiveBench、Artificial Analysis Index、Aider）在可访问时实时合并，外加一个策划的多模态/视觉索引；*冻结层*（Open LLM Leaderboard v2、Chatbot Arena ELO）。各层有独立的容量限制和基于谱系的时效性降权，这样过时的排行榜就不会过度奖励旧世代。 3. **基准证据** — 五个解析级别，折扣逐渐增加： - `direct` — 精确模型 ID 匹配 - `variant` — 去除后缀的或 -Instruct 变体 - `base_model` — 来自 cardData 的基础模型 - `line_interp` — 模型家族内的基于尺寸的插值 - `self_reported` — 上传者声称的评估（大幅折扣） 当模型的参数与其家族主导成员的差异超过 2 倍时，继承将被拒绝，从而捕获与更大型基础模型共享 `family_id` 的草稿/MTP/消融分支。 4. **缓存** — `~/.cache/whichllm/`： - `models.json` — 6 小时 TTL - `benchmark.json` — 24 小时 TTL ### 排名引擎 1. **硬件检测** — NVIDIA (nvidia-ml-py)、AMD (dbgpu/ROCm)、Apple Silicon (Metal)、CPU 核心数、内存、磁盘 2. **VRAM 估算** — 权重 + KV 缓存 + 激活 + 框架开销（约 500MB） 3. **兼容性** — 完全 GPU / 部分卸载 / 仅CPU；计算能力和操作系统检查 4. **速度** — 来自 GPU 内存带宽、量化、后端、适配类型和 MoE 活跃参数的 tok/s 5. **评分** — 基准测试（带置信度衰减）、尺寸、量化惩罚、适配类型、速度、流行度、来源可信度（官方 vs 重新打包者） 6. **后端过滤** — Apple Silicon 和仅CPU 限制为 GGUF 以保证稳定性；Linux+NVIDIA 允许 AWQ/GPTQ ### 项目结构 ``` src/whichllm/ ├── cli.py # Typer CLI: main, plan, run, snippet, hardware ├── constants.py # GPU bandwidth, quantization bytes, compute capability ├── hardware/ │ ├── detector.py # Orchestrates GPU/CPU/RAM detection │ ├── nvidia.py # NVIDIA GPU via nvidia-ml-py │ ├── amd.py # AMD GPU (Linux) │ ├── apple.py # Apple Silicon (Metal) │ ├── cpu.py # CPU name, cores, AVX support │ ├── memory.py # RAM and disk free │ ├── gpu_simulator.py # --gpu flag: synthetic GPU from name │ └── types.py # GPUInfo, HardwareInfo ├── models/ │ ├── fetcher.py # HuggingFace API, model parsing, evalResults │ ├── benchmark.py # Arena ELO, Leaderboard (parquet/rows API) │ ├── grouper.py # Family grouping by base_model and name │ ├── cache.py # JSON cache with TTL │ └── types.py # ModelInfo, GGUFVariant, ModelFamily ├── engine/ │ ├── vram.py # VRAM = weights + KV cache + activation + overhead │ ├── compatibility.py# Fit type, disk check, compute/OS warnings │ ├── performance.py # tok/s from bandwidth │ ├── quantization.py # Bytes per weight, quality penalty, non-GGUF inference │ ├── ranker.py # Scoring, evidence filter, profile/match │ └── types.py # CompatibilityResult └── output/ └── display.py # Rich table, JSON output, hardware/plan displays ``` ## 贡献 欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。 ## 支持 如果 whichllm 帮助您找到了模型或避免了糟糕的硬件猜测， 赞助将不胜感激。它有助于保持项目维护：硬件报告、打包、测试夹具、基准更新以及对更多机器的支持。 无论如何，whichllm 都将保持开源。欢迎提交 Issue 和 PR。 ## 系统要求 - Python 3.11+ - 通过 `nvidia-ml-py` 检测 NVIDIA GPU（默认包含） - AMD / Apple Silicon 自动检测 ## 许可证 MIT

标签：AI辅助, Apex, CPU优化, DLL 劫持, HuggingFace, Python, SOC Prime, Vectored Exception Handling, 人工智能, 优化工具, 大语言模型, 实时数据, 开发工具, 性能基准, 排名系统, 无后门, 本地部署, 机器学习, 模型选择, 用户模式Hook绕过, 硬件兼容性, 自动检测, 逆向工具