Andyyyy64/whichllm

来源：https://github.com/Andyyyy64/whichllm

whichllm

PyPI 版本（https://pypi.org/project/whichllm/）
Python 3.11+（https://www.python.org/downloads/）
许可证：MIT（https://opensource.org/licenses/MIT）
测试（https://github.com/Andyyyy64/whichllm/actions/workflows/test.yml）

找到真正能在你硬件上运行的最佳本地 LLM。
自动检测你的 GPU/CPU/内存，从 HuggingFace 上排名出最适合你系统的高分模型。

日本語版はこちら

演示效果

$ whichllm --gpu "RTX 4090"
#1 Qwen/Qwen3.6-27B  27.8B  Q5_K_M  得分 92.8  27 t/s
#2 Qwen/Qwen3-32B   32.0B  Q4_K_M  得分 83.0  31 t/s
#3 Qwen/Qwen3-30B-A3B  30.0B  Q5_K_M  得分 82.7  102 t/s

32B 模型在你的显卡上完全能跑——但 whichllm 仍将 27B 排在第一，因为它在真实基准测试中得分更高，且是新一代模型。一个只看大小的“能跑什么？“工具会直接给你更大的模型。这个差距正是 whichllm 存在的意义。

（注意 #3：一个 MoE 模型，102 t/s——速度按活跃参数排名，质量按总参数排名。）

我能跑什么？

真实最佳推荐（快照 2026-05——你的结果会跟随 实时 HuggingFace 数据，这不是静态列表）：

使用 whichllm --gpu "" 在购买前模拟上述任何配置。

觉得有用？给个 GitHub Star 能帮助其他人找到它——而且我很想知道它为你的设备推荐了什么：请在 Issues（https://github.com/Andyyyy64/whichllm/issues） 里告诉我。

为什么选 whichllm？

把模型装进显存是容易的部分。难点在于知道哪些能装进去的模型实际上是最好的——这正是 whichllm 要解决的问题。

• 基于证据的排名，不是大小启发式——最佳选择来自合并的真实基准测试（LiveBench、Artificial Analysis、Aider、多模态/视觉、Chatbot Arena ELO、Open LLM Leaderboard）——绝不是“刚好能装进去的最大模型“。
• 考虑时效性——过时的排行榜会根据各模型的血统被降权，所以 2024 年的模型不会因为一个旧分数而超过当前代模型。每个排名下都印有基准快照日期，这样过时的推荐可以自证，而不是被默默信任。
• 证据分级且有防护——每个分数都带有 direct / variant / base / interpolated / self-reported 标签，并根据置信度打折。虚假的上传者声明和跨家族继承（一个小分支借用了其大得多的基座模型的分数）会被主动拒绝。
• 架构感知的估算——显存 = 权重 + 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"
• 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"])

安装

pipx（推荐）

pipx install whichllm

Homebrew

brew tap Andyyyy64/whichllm
brew install 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"

# 仅 CPU 模式
whichllm --cpu-only

# 更多结果 / 筛选
whichllm --top 20
whichllm --quant Q4_K_M
whichllm --min-speed 30
whichllm --evidence base   # 允许 id/基座模型匹配
whichllm --evidence strict # 仅 id 精确匹配（同 --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

# 运行：下载并立即与模型聊天
whichllm run "qwen 2.5 1.5b gguf"
whichllm run  # 自动选择最适合你硬件的模型

# 片段：输出即用的 Python 代码
whichllm snippet "qwen 7b"
whichllm snippet "llama 3 8b gguf" --quant Q5_K_M

集成

Ollama

找到最佳模型并直接运行：

# 选择最佳模型并用 Ollama 运行
whichllm --top 1 --json | jq -r '.models[0].model_id' | xargs ollama run

# 找到最佳编码模型
whichllm --profile coding --top 1 --json | jq -r '.models[0].model_id' | xargs ollama run

Shell 别名

添加到 .bashrc / .zshrc：

alias bestllm='whichllm --top 1 --json | jq -r ".models[0].model_id"'
# 用法：ollama run $(bestllm)

评分

每个模型获得 0-100 分。基准质量和大小构成核心；证据置信度和运行时适配再对其缩放，速度、来源可信度和流行度作为调整项。

分数标记：

• ~（黄色）— 没有直接基准；分数从模型家族继承/插值
• ?（黄色）— 没有基准数据可用

工作原理

数据管道

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. 显存估算——权重 + KV 缓存 + 激活 + 框架开销（约 500MB）
3. 兼容性——完全 GPU / 部分卸载 / 仅 CPU；计算能力和操作系统检查
4. 速度——根据 GPU 内存带宽查找得出 tok/s（constants.py）
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 带宽、量化字节数、计算能力
├── hardware/
│   ├── detector.py       # 协调 GPU/CPU/内存检测
│   ├── nvidia.py         # 通过 nvidia-ml-py 检测 NVIDIA GPU
│   ├── amd.py            # AMD GPU（Linux）
│   ├── apple.py          # Apple Silicon（Metal）
│   ├── cpu.py            # CPU 名称、核心数、AVX 支持
│   ├── memory.py         # 内存和磁盘可用空间
│   ├── gpu_simulator.py  # --gpu 标志：通过名称模拟 GPU
│   └── types.py          # GPUInfo、HardwareInfo
├── models/
│   ├── fetcher.py        # HuggingFace API、模型解析、evalResults
│   ├── benchmark.py      # Arena ELO、Leaderboard（parquet/rows API）
│   ├── grouper.py        # 按 base_model 和名称分组
│   ├── cache.py          # 带 TTL 的 JSON 缓存
│   └── types.py          # ModelInfo、GGUFVariant、ModelFamily
├── engine/
│   ├── vram.py           # 显存 = 权重 + KV 缓存 + 激活 + 开销
│   ├── compatibility.py  # 适配类型、磁盘检查、计算/操作系统警告
│   ├── performance.py    # 根据带宽计算 tok/s
│   ├── quantization.py   # 每权重的字节数、质量惩罚、非 GGUF 推理
│   ├── ranker.py         # 评分、证据筛选、配置/匹配
│   └── types.py          # CompatibilityResult
└── output/
    └── display.py        # Rich 表格、JSON 输出、硬件/规划显示

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 获取指南。

要求

• Python 3.11+
• 通过 nvidia-ml-py 检测 NVIDIA GPU（默认包含）
• AMD / Apple Silicon 自动检测

许可证

MIT