在本地运行 LLM 前检测硬件并匹配可运行模型

当你需要知道当前机器能运行哪些本地 LLM、该选什么量化与用例模型，或反推某模型所需硬件时，用 llmfit 做检测、评分、推荐与规划。

适用场景

解决思路

1. macOS/Linux 使用 Homebrew 安装：brew install llmfit
2. 快速安装脚本：curl -fsSL https://llmfit.axjns.dev/install.sh | sh
3. 无 sudo 安装到 ~/.local/bin：curl -fsSL https://llmfit.axjns.dev/install.sh | sh -s -- --local
4. Windows 使用 Scoop 安装：scoop install llmfit
5. Docker/Podman 运行：docker run ghcr.io/alexsjones/llmfit
6. 用 Podman 配合 jq 脚本化推荐：podman run ghcr.io/alexsjones/llmfit recommend --use-case coding | jq '.models[].name'
7. 从源码构建：git clone https://github.com/AlexsJones/llmfit.git，cd llmfit，cargo build --release，二进制在 target/release/llmfit
8. 使用 fit tiers 解释/筛选兼容性：perfect（运行很好）、good（运行良好）、marginal（能运行但紧张）、too_tight（无法运行）
9. 用评分维度评估模型：quality、speed（预计 tok/s）、fit（内存余量）、context capacity
10. 根据运行模式选择：GPU、CPU+GPU offload、CPU-only、MoE
11. 让 llmfit 自动为硬件选择最佳量化，如 Q4_K_M、Q5_K_S、mlx-4bit
12. 使用支持的 provider：Ollama、llama.cpp、MLX、Docker Model Runner
13. 启动交互式 TUI：llmfit
14. CLI 表格输出：llmfit --cli
15. 显示系统硬件检测：llmfit system
16. JSON 输出系统硬件：llmfit --json system
17. 列出所有模型：llmfit list
18. 搜索模型：llmfit search 'llama 8b'
19. 搜索模型：llmfit search 'mistral'
20. 搜索模型：llmfit search 'qwen coding'
21. 按 fit 分析所有可运行模型并排序：llmfit fit
22. 只显示 perfect fits，前 5 个：llmfit fit --perfect -n 5
23. JSON 输出 fit 分析前 10：llmfit --json fit -n 10
24. 查看模型详情：llmfit info Mistral-7B
25. 查看模型详情：llmfit info Llama-3.1-70B
26. 推荐 Top 5（默认 JSON）：llmfit recommend --json --limit 5
27. 按用例 coding 推荐前 3：llmfit recommend --json --use-case coding --limit 3
28. 按用例 reasoning 推荐前 5：llmfit recommend --json --use-case reasoning --limit 5
29. 硬件规划（反推需要什么硬件）：llmfit plan Qwen/Qwen3-4B-MLX-4bit --context 8192
30. 指定量化规划：llmfit plan Qwen/Qwen3-4B-MLX-4bit --context 8192 --quant mlx-4bit
31. 指定目标 tok/s 并 JSON 输出：llmfit plan Qwen/Qwen3-4B-MLX-4bit --context 8192 --target-tps 25 --json
32. 规划特定模型：llmfit plan Qwen/Qwen2.5-Coder-0.5B-Instruct --context 8192 --json
33. 启动 REST API 服务器（用于集群调度）：llmfit serve
34. 指定 host/port 启动：llmfit serve --host 0.0.0.0 --port 8787
35. 自动检测失败时（VM、损坏 nvidia-smi、passthrough）覆盖 GPU VRAM：llmfit --memory=32G
36. 覆盖并 CLI 表格输出：llmfit --memory=24G --cli
37. 覆盖并只显示 perfect fit 前 5：llmfit --memory=24G fit --perfect -n 5
38. 覆盖并 JSON 推荐：llmfit --memory=24G recommend --json
39. 以 MB 覆盖：llmfit --memory=32000M
40. 覆盖参数适用于任何子命令：llmfit --memory=16G info Llama-3.1-70B
41. 使用后缀 G/GB/GiB、M/MB/MiB、T/TB/TiB（大小写不敏感）
42. 限制上下文长度估计：llmfit --max-context 4096 --cli
43. 带子命令限制上下文：llmfit --max-context 8192 fit --perfect -n 5
44. 带子命令限制上下文：llmfit --max-context 16384 recommend --json --limit 5
45. 通过环境变量设置上下文：export OLLAMA_CONTEXT_LENGTH=8192，然后 llmfit recommend --json
46. 启动服务器：llmfit serve --host 0.0.0.0 --port 8787
47. 健康检查：curl http://localhost:8787/health
48. 获取节点硬件信息：curl http://localhost:8787/api/v1/system
49. 获取带过滤的完整模型列表：curl 'http://localhost:8787/api/v1/models?min_fit=marginal&runtime=llamacpp&sort=score&limit=20'
50. 获取该节点 Top 可运行模型（调度关键端点）：curl 'http://localhost:8787/api/v1/models/top?limit=5&min_fit=good&use_case=coding'
51. 按模型名/provider 搜索：curl 'http://localhost:8787/api/v1/models/Mistral?runtime=any'
52. /models 和 /models/top 查询参数 limit/n：整数，最大返回行数
53. 查询参数 min_fit：perfect|good|marginal|too_tight，最小 fit tier
54. 查询参数 perfect：true|false，强制仅 perfect
55. 查询参数 runtime：any|mlx|llamacpp，按 runtime 过滤
56. 查询参数 use_case：general|coding|reasoning|chat|multimodal|embedding，按用例过滤
57. 查询参数 provider：字符串，按 provider 子串匹配
58. 查询参数 search：字符串，跨 name/provider/size/use-case 自由文本搜索
59. 查询参数 sort：score|tps|params|mem|ctx|date|use_case，排序列
60. 查询参数 include_too_tight：true|false，包含不可运行模型
61. 查询参数 max_context：整数，每请求上下文上限
62. Bash：获取 top coding models JSON 并用 jq 提取：llmfit recommend --json --use-case coding --limit 3 | jq -r '.models[] | [.name, .score, .quantization] | @csv'
63. Bash：检查指定模型是否适合：MODEL='Mistral-7B'; RESULT=$(llmfit info $MODEL --json 2>/dev/null); FIT=$(echo $RESULT | jq -r '.fit'); if [[ $FIT == 'perfect' || $FIT == 'good' ]]; then echo '$MODEL will run well (fit:' $FIT ')'; else echo '$MODEL may not run well (fit:' $FIT ')'; fi
64. Bash：自动拉取 top Ollama 模型：TOP_MODEL=$(llmfit recommend --json --limit 1 | jq -r '.models[0].name'); echo 'Pulling:' $TOP_MODEL; ollama pull $TOP_MODEL
65. Python：查询 REST API：定义 BASE_URL 为 http://localhost:8787，get_system_info() 请求 /api/v1/system，get_top_models() 请求 /api/v1/models/top 并传 use_case、limit、min_fit、sort，search_models() 请求 /api/v1/models/{query} 并传 runtime
66. Python：硬件感知模型选择器：get_best_model_for_task(use_case, min_fit='good') 调用 llmfit recommend --json --use-case use_case --limit 1 并解析 JSON；plan_hardware_requirements(model_name, context=4096) 调用 llmfit plan model_name --context context --json 并解析 JSON
67. Docker Compose：节点调度模式：定义服务 llmfit-api，镜像 ghcr.io/alexsjones/llmfit，command 为 serve --host 0.0.0.0 --port 8787，ports 为 8787:8787，environment 为 OLLAMA_CONTEXT_LENGTH=8192，devices 为 /dev/nvidia0:/dev/nvidia0
68. TUI 按键 ↑/↓ 或 j/k：导航模型
69. TUI 按键 /：搜索（name、provider、params、use case）
70. TUI 按键 Esc/Enter：退出搜索
71. TUI 按键 Ctrl-U：清除搜索
72. TUI 按键 f：循环 fit filter：All → Runnable → Perfect → Good → Marginal
73. TUI 按键 a：循环 availability：All → GGUF Avail → Installed
74. TUI 按键 s：循环 sort：Score → Params → Mem% → Ctx → Date → Use Case
75. TUI 按键 t：循环颜色主题（自动保存）
76. TUI 按键 v：Visual mode（多选比较）
77. TUI 按键 V：Select mode（基于列过滤）
78. TUI 按键 p：Plan mode（该模型需要什么硬件？）
79. TUI 按键 P：Provider filter 弹窗
80. TUI 按键 U：Use-case filter 弹窗
81. TUI 按键 C：Capability filter 弹窗
82. TUI 按键 m：标记模型用于比较
83. TUI 按键 c：比较视图（标记 vs 选中）
84. TUI 按键 d：下载模型（通过检测到的 runtime）
85. TUI 按键 r：从 runtime 刷新已安装模型
86. TUI 按键 Enter：切换详情视图
87. TUI 按键 g/G：跳到顶部/底部
88. TUI 按键 q：退出
89. 主题：按 t 循环 Default → Dracula → Solarized → Nord → Monokai → Gruvbox；主题保存到 ~/.config/llmfit/theme
90. GPU 检测 NVIDIA：通过 nvidia-smi 检测（多 GPU，聚合 VRAM）
91. GPU 检测 AMD：通过 rocm-smi 检测
92. GPU 检测 Intel Arc：独立显卡通过 sysfs，集成显卡通过 lspci 检测
93. GPU 检测 Apple Silicon：通过 system_profiler 检测（统一内存 = VRAM）
94. GPU 检测 Ascend：通过 npu-smi 检测
95. 16GB M2 Mac 可运行什么：llmfit fit --perfect -n 10；或运行 llmfit 后按 f 过滤到 Perfect fit
96. 3090（24GB VRAM）适合什么 coding 模型：llmfit recommend --json --use-case coding | jq '.models[]'；检测失败时用 llmfit --memory=24G recommend --json --use-case coding
97. Llama 70B 能否在机器上运行：llmfit info Llama-3.1-70B；规划所需硬件：llmfit plan Llama-3.1-70B --context 4096 --json
98. 只显示 Ollama 已安装模型：运行 llmfit，按 a 循环到 Installed filter；或 llmfit fit -n 20 后在 TUI 按 i 以 installed-first
99. 脚本：找到最佳模型并启动 Ollama：MODEL=$(llmfit recommend --json --limit 1 | jq -r '.models[0].name')，ollama serve &，ollama run $MODEL
100. API：为集群调度轮询节点能力：curl -s 'http://node1:8787/api/v1/models/top?limit=3&min_fit=good&use_case=reasoning' | jq '.models[].name'
101. GPU 未检测到/VRAM 错误：llmfit system 验证；llmfit --memory=24G --cli 手动覆盖
102. 有 NVIDIA GPU 但 nvidia-smi 未找到：安装 CUDA toolkit 或 nvidia-utils，然后重试；或手动覆盖 llmfit --memory=8G fit --perfect
103. 模型显示 too_tight 但内存足够：llmfit 可能使用上下文膨胀估计；限制上下文 llmfit --max-context 2048 fit --perfect -n 10
104. REST API 测试端点：python3 scripts/test_api.py --spawn 启动服务器并运行验证套件；python3 scripts/test_api.py --base-url http://127.0.0.1:8787 测试已运行服务器
105. Apple Silicon：VRAM 显示为系统 RAM 是预期：统一内存；llmfit 自动处理；llmfit system 应显示 backend: Metal
106. 上下文长度环境变量：export OLLAMA_CONTEXT_LENGTH=4096，然后 llmfit recommend --json 使用 4096 作为上下文上限

适用边界 · 注意事项

• 未安装且无法安装 llmfit 工具时。
• 只需要调用云端 LLM API、不打算在本地运行模型时。
• 需要生产级精确性能基准而非 llmfit 的估算结果时。