llmfit

English · 中文

数百种模型与提供商。一条命令即可找到适合您硬件的模型。

一款终端工具，可根据您的系统内存、CPU 和 GPU 资源，智能选择最合适的 LLM 模型。它会检测您的硬件配置，从质量、速度、适配性和上下文处理能力等多个维度对每个模型进行评分，并告诉您哪些模型在您的机器上能够流畅运行。

默认提供交互式 TUI 界面，同时也支持经典 CLI 模式。支持多 GPU 配置、MoE 架构、动态量化选择、速度估算以及本地运行时提供商（Ollama、llama.cpp、MLX、Docker Model Runner、LM Studio）。

姊妹项目：

• sympozium — 在 Kubernetes 中管理代理。
• llmserve — 一个用于部署本地 LLM 模型的简单 TUI 工具。选择模型、选择后端，即可开始服务。

---

安装

Windows

scoop install llmfit

如果尚未安装 Scoop，请参考 Scoop 安装指南。

macOS / Linux

Homebrew

brew install llmfit

快速安装

curl -fsSL https://llmfit.axjns.dev/install.sh | sh

该命令会从 GitHub 下载最新版本的二进制文件，并将其安装到 /usr/local/bin（如果没有 sudo 权限，则安装到 ~/.local/bin）。

无需 sudo 安装到 ~/.local/bin：

curl -fsSL https://llmfit.axjns.dev/install.sh | sh -s -- --local

Docker / Podman

docker run ghcr.io/alexsjones/llmfit

此命令会输出 llmfit recommend 命令的 JSON 结果。您可以使用 jq 对 JSON 进一步查询。

podman run ghcr.io/alexsjones/llmfit recommend --use-case coding | jq '.models[].name'

从源码编译

git clone https://github.com/AlexsJones/llmfit.git
cd llmfit
cargo build --release
# 生成的二进制文件位于 target/release/llmfit

---

使用方法

TUI（默认）

llmfit

启动交互式终端界面。屏幕顶部会显示您的系统规格（CPU、内存、GPU 型号、显存大小、运行时后端）。下方是一个可滚动的表格，模型按综合评分排序。每行显示模型的评分、预估的 token/s 速度、最适合您硬件的量化方式、运行模式、内存占用以及适用场景分类。

键	功能
Up / Down 或 j / k	导航浏览模型
/	进入搜索模式（支持名称、提供商、参数、使用场景的部分匹配）
Esc 或 Enter	退出搜索模式
Ctrl-U	清除搜索内容
f	切换适配性筛选器：全部、可运行、完美、良好、勉强
a	切换可用性筛选器：全部、GGUF 可用、已安装
s	切换排序列：评分、参数量、内存占比、上下文长度、发布日期、使用场景
v	进入视觉模式（可多选模型）
V	进入列筛选模式
t	切换颜色主题（自动保存）
p	打开所选模型的规划模式（硬件资源规划）
P	打开提供商筛选弹出窗口
U	打开使用场景筛选弹出窗口
C	打开功能特性筛选弹出窗口
m	标记所选模型以供比较
c	打开比较视图（已标记模型与当前选中模型对比）
x	清除比较标记
i	切换“已安装优先”排序（基于检测到的运行时提供商）
d	下载所选模型（当有多个提供商时会弹出选择框）
r	从运行时提供商处刷新已安装模型
Enter	切换所选模型的详细信息视图
PgUp / PgDn	每次滚动 10 行
g / G	跳转到列表顶部 / 底部
q	退出程序

类 Vim 模式

TUI 使用受 Vim 启发的模式，显示在左下角的状态栏中。当前模式决定了哪些键是可用的。

正常模式

默认模式。用于导航、搜索、筛选和打开视图。上表中的所有按键在此模式下均适用。

可视模式 (v)

选择连续的模型范围以进行批量比较。按 v 键将锚点定位到当前行，然后使用 j/k 或方向键扩展选择范围。选中的行会高亮显示。

键	动作
j / k 或箭头键	上下扩展选区
c	比较所有选中的模型（打开多模型比较视图）
m	标记当前模型以进行双模型比较
Esc 或 v	退出可视模式

多模型比较视图显示一个表格，其中行代表属性（得分、tok/s、适配度、内存占比、参数量、运行模式、上下文长度、量化等），列则为不同的模型。最佳值会被高亮显示。如果选择的模型数量超过屏幕宽度，可使用 h/l 或方向键水平滚动。

选择模式 (V)

基于列的筛选模式。按 V（Shift-v）进入选择模式，然后使用 h/l 或方向键在列标题间移动。当前活动的列会以视觉方式突出显示。按下 Enter 或 空格 键即可激活该列对应的筛选功能：

列	筛选操作
实例	循环切换可用性筛选
模型	进入搜索模式
提供者	打开提供者弹出菜单
参数量	打开参数规模分桶弹出菜单（<3B、3-7B、7-14B、14-30B、30-70B、70B+）
得分、tok/s、内存占比、上下文长度、日期	按该列排序
量化	打开量化弹出菜单
运行模式	打开运行模式弹出菜单（GPU、MoE、CPU+GPU、CPU）
适配度	循环切换适配度筛选
使用场景	打开使用场景弹出菜单

在选择模式下，行导航（j/k）仍然有效，因此您可以在应用筛选器时查看其效果。按 Esc 键返回正常模式。

TUI 计划模式 (p)

计划模式颠覆了常规的适配分析：它不是问“什么适合我的硬件？”，而是估算“这个模型配置需要什么样的硬件？”。

在选中某一行后，按下 p 键，然后：

键	动作
Tab / j / k	在可编辑字段之间移动（上下文长度、量化、目标 TPS）
Left / Right	在当前字段内移动光标
输入	编辑当前字段
Backspace / Delete	删除字符
Ctrl-U	清除当前字段
Esc 或 q	退出计划模式

计划模式会显示以下估算结果：

• 最小和推荐的显存/内存/CPU 核心数
• 可行的运行路径（GPU、CPU 卸载、纯 CPU）
• 为达到更好的适配目标所需的升级幅度

主题

按 t 键可在 10 种内置颜色主题之间循环切换。您的选择会自动保存到 ~/.config/llmfit/theme 文件中，并在下次启动时恢复。

主题	描述
默认	原始 llmfit 颜色
Dracula	深紫色背景搭配柔和色调
Solarized	伊森·斯库诺弗的 Solarized Dark 调色板
Nord	北极风，冷峻的蓝灰色调
Monokai	Monokai Pro 的温暖语法高亮颜色
Gruvbox	复古风格调色板，带有温暖的大地色调
Catppuccin Latte	🌻 浅色主题 — 和谐的粉彩色反转
Catppuccin Frappé	🪴 低对比度深色 — 沉稳、低调的美学
Catppuccin Macchiato	🌺 中等对比度深色 — 温和、舒缓的色调
Catppuccin Mocha	🌿 最深的变体 — 舒适且色彩丰富的点缀

Web 控制面板

当您以非 JSON 模式运行 llmfit 时，它会自动在 0.0.0.0:8787 启动一个后台 Web 控制面板。在同一网络中的任何浏览器中打开即可：

http://<your-machine-ip>:8787

您可以通过环境变量覆盖主机或端口：

LLMFIT_DASHBOARD_HOST=0.0.0.0 LLMFIT_DASHBOARD_PORT=9000 llmfit

变量	默认值	描述
LLMFIT_DASHBOARD_HOST	0.0.0.0	控制面板服务器绑定的接口
LLMFIT_DASHBOARD_PORT	8787	控制面板服务器绑定的端口

要禁用自动启动的控制面板，可以传递 --no-dashboard 参数：

llmfit --no-dashboard

CLI 模式

使用 --cli 或任何子命令可获得经典的表格输出：

# 按适配度排名的所有模型表格
llmfit --cli

# 完美适配的模型，前 5 名
llmfit fit --perfect -n 5

# 显示检测到的系统规格
llmfit system

# 列出数据库中的所有模型
llmfit list

# 按名称、提供商或参数量搜索
llmfit search "llama 8b"

# 单个模型的详细信息
llmfit info "Mistral-7B"

# 前 5 名推荐（JSON 格式，供代理或脚本使用）
llmfit recommend --json --limit 5

# 按使用场景筛选的推荐
llmfit recommend --json --use-case coding --limit 3

# 强制指定运行时（绕过 Apple Silicon 上的自动 MLX 选择）
llmfit recommend --force-runtime llamacpp
llmfit recommend --force-runtime llamacpp --use-case coding --limit 3

# 为特定模型配置规划所需硬件
llmfit plan "Qwen/Qwen3-4B-MLX-4bit" --context 8192
llmfit plan "Qwen/Qwen3-4B-MLX-4bit" --context 8192 --quant mlx-4bit
llmfit plan "Qwen/Qwen3-4B-MLX-4bit" --context 8192 --target-tps 25 --json

# 作为节点级 REST API 运行（适用于集群调度器/聚合器）
llmfit serve --host 0.0.0.0 --port 8787

REST API (llmfit serve)

llmfit serve 启动一个 HTTP API，公开与 TUI/CLI 相同的拟合/评分数据，包括节点的筛选和顶级模型选择。

# 活性检查
curl http://localhost:8787/health

# 节点硬件信息
curl http://localhost:8787/api/v1/system

# 带筛选条件的完整拟合列表
curl "http://localhost:8787/api/v1/models?min_fit=marginal&runtime=llamacpp&sort=score&limit=20"

# 关键调度端点：该节点可运行的顶级模型
curl "http://localhost:8787/api/v1/models/top?limit=5&min_fit=good&use_case=coding"

# 按模型名称/提供商文本搜索
curl "http://localhost:8787/api/v1/models/Mistral?runtime=any"

models/models/top 支持的查询参数：

• limit（或 n）：返回的最大行数
• perfect：true|false（为 true 时强制仅显示完美匹配）
• min_fit：perfect|good|marginal|too_tight
• runtime：any|mlx|llamacpp
• use_case：general|coding|reasoning|chat|multimodal|embedding
• provider：提供商文本过滤器（子字符串）
• search：跨名称/提供商/尺寸/使用场景的自由文本过滤
• sort：score|tps|params|mem|ctx|date|use_case
• include_too_tight：是否包含不可运行的行（默认在 /top 上为 false，在 /models 上为 true）
• max_context：用于内存估算的每请求上下文上限
• force_runtime：mlx|llamacpp|vllm — 在分析过程中覆盖自动运行时选择

在本地验证 API 行为：

# 自动启动服务器并运行端点/模式/筛选断言
python3 scripts/test_api.py --spawn

# 或测试已运行的服务器
python3 scripts/test_api.py --base-url http://127.0.0.1:8787

GPU 内存覆盖

在某些系统上，GPU 显存自动检测可能会失败（例如 nvidia-smi 出现问题、虚拟机、直通设置等）。可以使用 --memory 手动指定 GPU 的显存大小：

# 覆盖为 32 GB 显存
llmfit --memory=32G

# 也可以使用 MB 单位（32000 MB ≈ 31.25 GB）
llmfit --memory=32000M

# 适用于所有模式：TUI、CLI 和子命令
llmfit --memory=24G --cli
llmfit --memory=24G fit --perfect -n 5
llmfit --memory=24G system
llmfit --memory=24G info "Llama-3.1-70B"
llmfit --memory=24G recommend --json

支持的后缀：G/GB/GiB（千兆字节）、M/MB/MiB（兆字节）、T/TB/TiB（太字节）。不区分大小写。如果未检测到 GPU，则覆盖会创建一个模拟的 GPU 条目，以便对模型进行 GPU 推理的评分。

用于估算的上下文长度上限

使用 --max-context 可以限制用于内存估算的上下文长度（而不改变每个模型所宣传的最大上下文长度）：

# 在 4K 上下文长度下估算内存占用
llmfit --max-context 4096 --cli

# 也适用于子命令
llmfit --max-context 8192 fit --perfect -n 5
llmfit --max-context 16384 recommend --json --limit 5

如果未设置 --max-context，llmfit 将在可用时使用 OLLAMA_CONTEXT_LENGTH。

JSON 输出

在任何子命令中添加 --json 可获得机器可读的输出：

llmfit --json system     # 硬件规格以 JSON 格式输出
llmfit --json fit -n 10  # 前 10 名拟合结果以 JSON 格式输出
llmfit recommend --json  # 前 5 名推荐结果（recommend 默认为 JSON 格式）
llmfit plan "Qwen/Qwen2.5-Coder-0.5B-Instruct" --context 8192 --json

plan 的 JSON 包含以下稳定字段：

• 请求信息（上下文、量化、目标 TPS）
• 估计的最低/推荐硬件配置
• 各路径的可行性（GPU、CPU 卸载、纯 CPU）
• 升级差异

---

工作原理

1. 硬件检测 -- 通过 sysinfo 读取总内存/可用内存，统计 CPU 核心数，并探测 GPU：

   • NVIDIA -- 通过 nvidia-smi 支持多 GPU。汇总所有检测到的 GPU 的显存。若报告失败，则回退到根据 GPU 型号名称估算显存。
   • AMD -- 通过 rocm-smi 检测。
   • Intel Arc -- 独立显存通过 sysfs 获取，集成显存则通过 lspci 获取。
   • Apple Silicon -- 统一内存通过 system_profiler 获取。显存等于系统内存。
   • Ascend -- 通过 npu-smi 检测。
   • 后端检测 -- 自动识别加速后端（CUDA、Metal、ROCm、SYCL、CPU ARM、CPU x86、Ascend），用于速度估算。

2. 模型数据库 -- 数百个模型来自 HuggingFace API，存储在 data/hf_models.json 中，并在编译时嵌入。内存需求根据参数量，结合量化层级（Q8_0 至 Q2_K）计算得出。显存在 GPU 推理中是主要限制；仅 CPU 运行时则以系统内存作为后备。

   MoE 支持 -- 具有专家混合架构的模型（Mixtral、DeepSeek-V2/V3）会自动检测。每个 token 只激活部分专家，因此实际显存需求远低于总参数量所暗示的数值。例如，Mixtral 8x7B 总参数量为 467 亿，但每 token 只激活约 129 亿，通过专家卸载可将显存需求从 23.9 GB 降至约 6.6 GB。

3. 动态量化 -- llmfit 不假设固定量化级别，而是尝试最适合您硬件的质量量化。它从 Q8_0（质量最高）开始，逐步降低到 Q2_K（压缩比最高），选择能在可用内存内运行的最高质量量化。如果全上下文都不满足，再尝试半上下文。

4. 多维度评分 -- 每个模型在四个维度上进行评分（每个维度满分为 100 分）：

   维度	衡量内容
   质量	参数量、模型家族声誉、量化惩罚、任务匹配程度
   速度	根据后端、参数量和量化估计的每秒生成 token 数
   契合度	内存使用效率（理想范围：50–80% 的可用内存）
   上下文	上下文窗口能力与用例目标的匹配程度

   各维度按加权综合得分排序。权重因用例类别而异（通用、编码、推理、聊天、多模态、嵌入）。例如，聊天场景更注重速度（权重 0.35），而推理场景则更注重质量（权重 0.55）。无法运行的模型（过于紧张）始终排在最后。

5. 速度估算 -- LLM 推理中的 token 生成受内存带宽限制：每个 token 需从显存中读取一次完整的模型权重。当 GPU 型号被识别后，llmfit 使用其实际内存带宽来估算吞吐量：

   公式：(带宽_GB_s / 模型大小_GB) × 效率因子

   效率因子（0.55）考虑了内核开销、KV 缓存读取及内存控制器的影响。该方法已通过 llama.cpp 的公开基准测试（Apple Silicon、NVIDIA T4）以及实际测量结果验证。

   带宽查找表覆盖了 NVIDIA（消费级 + 数据中心）、AMD（RDNA + CDNA）和 Apple Silicon 系列的约 80 款 GPU。

   对于未识别的 GPU，llmfit 会回退到各后端的速度常数：

   后端	超速常数
   CUDA	220
   Metal	160
   ROCm	180
   SYCL	100
   CPU (ARM)	90
   CPU (x86)	70
   NPU (Ascend)	390

   回退公式：K / params_b × 量化速度倍增因子，其中对 CPU 卸载（0.5×）、仅 CPU 运行（0.3×）以及 MoE 专家切换（0.8×）均设有惩罚。

6. 契合度分析 -- 每个模型都会评估其内存兼容性：

   运行模式：

   • GPU -- 模型可完全容纳在显存中。推理速度快。
   • MoE -- 专家混合架构，采用专家卸载策略。活跃专家位于显存，不活跃专家位于内存。
   • CPU+GPU -- 显存不足，部分数据溢出至系统内存，同时进行部分 GPU 卸载。
   • CPU -- 无 GPU。模型完全加载到系统内存中。

   契合度等级：

   • 完美 -- 在 GPU 上达到推荐内存要求。需要 GPU 加速。
   • 良好 -- 有余量，适合专家卸载或 CPU+GPU 模式。
   • 临界 -- 内存较为紧张，或仅限 CPU 运行（仅 CPU 模式一律归于此）。
   • 过于紧张 -- 显存或系统内存均不足。

---

模型数据库

模型列表由 scripts/scrape_hf_models.py 生成，这是一段独立的 Python 脚本（仅使用标准库，无需 pip 依赖），用于查询 HuggingFace REST API。涵盖数百个模型及提供商，包括 Meta Llama、Mistral、Qwen、Google Gemma、Microsoft Phi、DeepSeek、IBM Granite、Allen Institute OLMo、xAI Grok、Cohere、BigCode、01.ai、Upstage、TII Falcon、HuggingFace、Zhipu GLM、Moonshot Kimi、Baidu ERNIE 等。爬虫会自动通过模型配置文件（num_local_experts、num_experts_per_tok）及已知架构映射检测 MoE 架构。

模型类别涵盖通用、编码（CodeLlama、StarCoder2、WizardCoder、Qwen2.5-Coder、Qwen3-Coder）、推理（DeepSeek-R1、Orca-2）、多模态/视觉（Llama 3.2 Vision、Llama 4 Scout/Maverick、Qwen2.5-VL）、聊天、企业级（IBM Granite）以及嵌入（nomic-embed、bge）等。

完整列表请参阅 MODELS.md。

要刷新模型数据库：

# 自动更新（推荐）
make update-models

# 或直接运行脚本
./scripts/update_models.sh

# 或手动操作
python3 scripts/scrape_hf_models.py
cargo build --release

爬虫会将数据写入 data/hf_models.json，并通过 include_str! 将其嵌入二进制文件中。自动更新脚本会备份现有数据，验证 JSON 输出，并重新构建二进制文件。

默认情况下，爬虫会为模型补充来自 unsloth 和 bartowski 等提供商的已知 GGUF 下载源。结果会缓存到 data/gguf_sources_cache.json（有效期 7 天），以避免重复调用 API。如需加快抓取速度，可使用 --no-gguf-sources 参数跳过补充下载源的步骤。

---

项目结构

src/
  main.rs         -- CLI 参数解析、入口点、TUI 启动
  hardware.rs     -- 系统内存/CPU/GPU 检测（多 GPU、后端识别）
  models.rs       -- 模型数据库、量化层级、动态量化选择
  fit.rs          -- 多维度评分（Q/S/F/C）、速度估算、MoE 分载
  providers.rs    -- 运行时提供者集成（Ollama、llama.cpp、MLX、Docker Model Runner、LM Studio）、安装检测、拉取/下载
  display.rs      -- 经典 CLI 表格渲染 + JSON 输出
  tui_app.rs      -- TUI 应用程序状态、过滤器、导航
  tui_ui.rs       -- TUI 渲染（ratatui）
  tui_events.rs   -- TUI 键盘事件处理（crossterm）
data/
  hf_models.json  -- 模型数据库（206 个模型）
skills/
  llmfit-advisor/ -- OpenClaw 技能，用于硬件感知的模型推荐
scripts/
  scrape_hf_models.py        -- HuggingFace API 爬虫
  update_models.sh            -- 自动化数据库更新脚本
  install-openclaw-skill.sh   -- 安装 OpenClaw 技能
Makefile           -- 构建和维护命令

---

发布到 crates.io

Cargo.toml 已包含必要的元数据（描述、许可证、仓库）。发布步骤如下：

# 先进行干运行以捕获问题
cargo publish --dry-run

# 正式发布（需要 crates.io API token）
cargo login
cargo publish

在发布前，请确保：

• Cargo.toml 中的版本号正确（每次发布都需递增）。
• 仓库根目录下存在 LICENSE 文件。如果缺失，可使用以下命令创建：

# 对于 MIT 许可证：
curl -sL https://opensource.org/license/MIT -o LICENSE
# 或者自行编写许可证内容。`Cargo.toml` 中已声明 license = "MIT"。

• data/hf_models.json 已提交。该文件会在编译时嵌入，必须存在于发布的 crate 中。
• Cargo.toml 中的 exclude 列表应将 target/、scripts/ 和 https://oss.gittoolsai.com/images/AlexsJones_llmfit_readme_bfe3c444a49a.gif 排除在外，以减小下载包的大小。

更新发布步骤如下：

# 递增版本号
# 编辑 Cargo.toml：version = "0.2.0"
cargo publish

---

依赖项

Crate	用途
clap	使用 derive 宏进行 CLI 参数解析
sysinfo	跨平台内存和 CPU 检测
serde / serde_json	用于模型数据库的 JSON 反序列化
tabled	CLI 表格格式化
colored	CLI 彩色输出
ureq	用于运行时/提供者 API 集成的 HTTP 客户端
ratatui	终端 UI 框架
crossterm	ratatui 的终端输入输出后端

---

运行时提供者集成

llmfit 支持多种本地运行时提供者：

• Ollama（基于守护进程/API 的拉取）
• llama.cpp（直接从 Hugging Face 下载 GGUF 文件并检测本地缓存）
• MLX（Apple Silicon / mlx-community 模型缓存 + 可选服务器）
• Docker Model Runner（Docker Desktop 内置的模型服务）
• LM Studio（具有 REST API 的本地模型服务器，支持模型管理和下载）

当一个模型有多个兼容的提供者可用时，在 TUI 中按下 d 键会打开提供者选择模态框。

Ollama 集成

llmfit 与 Ollama 集成，用于检测您已安装哪些模型，并直接从 TUI 下载新模型。

要求

• Ollama 必须已安装并正在运行（ollama serve 或 Ollama 桌面应用）。
• llmfit 会连接到 http://localhost:11434（Ollama 的默认 API 端口）。
• 无需额外配置——只要 Ollama 在运行，llmfit 就会自动检测到它。

远程 Ollama 实例

要连接到运行在不同机器或端口上的 Ollama，可以设置 OLLAMA_HOST 环境变量：

# 连接到特定 IP 和端口的 Ollama
OLLAMA_HOST="http://192.168.1.100:11434" llmfit

# 通过主机名连接
OLLAMA_HOST="http://ollama-server:666" llmfit

# 适用于所有 TUI 和 CLI 命令
OLLAMA_HOST="http://192.168.1.100:11434" llmfit --cli
OLLAMA_HOST="http://192.168.1.100:11434" llmfit fit --perfect -n 5

这在以下场景中非常有用：

• 在一台机器上运行 llmfit，而 Ollama 在另一台机器上提供服务（例如，GPU 服务器 + 笔记本客户端）。
• 连接到运行在 Docker 容器中且使用自定义端口的 Ollama。
• 在反向代理或负载均衡器后使用 Ollama。

工作原理

启动时，llmfit 会查询 GET /api/tags 来列出您已安装的 Ollama 模型。每个已安装的模型在 TUI 的 Inst 列中都会显示一个绿色的 ✓。系统栏会显示 Ollama: ✓ (N 已安装)。

当您对某个模型按下 d 键时，llmfit 会向 Ollama 发送 POST /api/pull 请求来下载该模型。对应的行会高亮显示，并带有动画进度条实时显示下载进度。下载完成后，该模型即可立即通过 Ollama 使用。

如果 Ollama 未运行，与 Ollama 相关的操作会被跳过；TUI 仍会支持其他提供者，例如 llama.cpp（如果可用）。

llama.cpp 集成

llmfit 与 llama.cpp 集成，作为 TUI 和 CLI 中的运行时/下载提供者。

要求：

• llama-cli 或 llama-server 必须在 PATH 中可用（用于运行时检测）。
• 需要有网络访问权限，以便从 Hugging Face 下载 GGUF 文件。

工作原理：

• llmfit 会将 HF 模型映射到已知的 GGUF 仓库（并提供启发式回退方案）。
• 将 GGUF 文件下载到本地 llama.cpp 模型缓存中。
• 当本地存在匹配的 GGUF 文件时，会标记该模型已安装。

Docker Model Runner 集成

llmfit 与 Docker Model Runner 集成，后者是 Docker Desktop 内置的模型服务功能。

要求：

• Docker Desktop 必须启用 Model Runner 功能。
• 默认端点为 http://localhost:12434。

工作原理：

• llmfit 会查询 GET /engines 来列出 Docker Model Runner 中可用的模型。
• 模型会通过 Ollama 式的标签映射与 HF 数据库匹配（Docker Model Runner 使用 ai/<tag> 命名）。
• 在 TUI 中按下 d 键会通过 docker model pull 进行拉取。

远程 Docker Model Runner 实例

要连接到运行在不同主机或端口上的 Docker Model Runner，可以设置 DOCKER_MODEL_RUNNER_HOST 环境变量：

DOCKER_MODEL_RUNNER_HOST="http://192.168.1.100:12434" llmfit

LM Studio 集成

llmfit 与 LM Studio 集成，作为本地模型服务器，并内置模型下载功能。

要求：

• LM Studio 必须运行且已启用本地服务器
• 默认端点：http://127.0.0.1:1234

工作原理：

• llmfit 通过 GET /v1/models 查询 LM Studio 中可用的模型列表
• 在 TUI 中按下 d 键会触发通过 POST /api/v1/models/download 进行下载
• 下载进度通过轮询 GET /api/v1/models/download-status 来跟踪
• LM Studio 直接接受 HuggingFace 模型名称，因此无需进行名称映射

远程 LM Studio 实例

若要连接到不同主机或端口上的 LM Studio，请设置 LMSTUDIO_HOST 环境变量：

LMSTUDIO_HOST="http://192.168.1.100:1234" llmfit

模型名称映射

llmfit 的数据库使用 HuggingFace 模型名称（例如 Qwen/Qwen2.5-Coder-14B-Instruct），而 Ollama 使用自己的命名方案（例如 qwen2.5-coder:14b）。llmfit 维护了一个准确的映射表，确保安装检测和拉取操作能够解析为正确的模型。每个映射都是精确的——qwen2.5-coder:14b 映射的是 Coder 模型，而不是基础的 qwen2.5:14b。

---

平台支持

• Linux -- 完全支持。可通过 nvidia-smi（NVIDIA）、rocm-smi（AMD）、sysfs/lspci（Intel Arc）以及 npu-smi（Ascend）检测 GPU。
• macOS（Apple Silicon） -- 完全支持。通过 system_profiler 检测统一内存。VRAM 即系统 RAM（共享池）。模型通过 Metal GPU 加速运行。
• macOS（Intel） -- 可检测 RAM 和 CPU。如果安装了 nvidia-smi，则可检测独立 GPU。
• Windows -- 可检测 RAM 和 CPU。如果已安装 nvidia-smi，则可检测 NVIDIA GPU。
• Android / Termux / PRoot -- 通常可以检测 CPU 和 RAM，但目前不支持 GPU 自动检测。移动 GPU（如 Adreno）通常无法通过 llmfit 使用的桌面/服务器探测接口被识别。

GPU 支持

厂商	检测方法	VRAM 报告
NVIDIA	nvidia-smi	精确的专用 VRAM
AMD	rocm-smi	已检测（VRAM 可能未知）
Intel Arc（独立）	sysfs (mem_info_vram_total)	精确的专用 VRAM
Intel Arc（集成）	lspci	共享系统内存
Apple Silicon	system_profiler	独立内存（等于系统 RAM）
Ascend	npu-smi	已检测（VRAM 可能未知）

如果自动检测失败或报告值不正确，可使用 --memory=<SIZE> 参数进行覆盖（参见上文的 [GPU 内存覆盖]）。

Android / Termux 注意事项

在 Android 系统中，例如 Termux + PRoot，llmfit 通常无法通过标准的 Linux 检测路径（nvidia-smi、rocm-smi、DRM/sysfs、lspci 等）检测到移动 GPU。在这种环境下，当前实现下出现“未检测到 GPU”的情况是正常的。

如果您仍然希望在使用统一内存的手机或平板上获得 GPU 类似的推荐，可以手动覆盖内存大小：

llmfit --memory=8G fit -n 20
llmfit recommend --json --memory=8G --limit 10

这只是用于推荐和评分的临时解决方案，并不能真正检测 Android 设备上的 GPU 运行情况。

---

贡献

欢迎贡献，尤其是新增模型。

添加模型

1. 将模型的 HuggingFace 仓库 ID（例如 meta-llama/Llama-3.1-8B）添加到 scripts/scrape_hf_models.py 中的 TARGET_MODELS 列表。
2. 如果模型受限制（需要 HuggingFace 认证才能访问元数据），请在同一脚本的 FALLBACKS 列表中添加一个备用条目，包含参数量和上下文长度。
3. 运行自动化更新脚本：

   make update-models
   # 或：./scripts/update_models.sh
   

4. 验证更新后的模型列表：./target/release/llmfit list
5. 更新 MODELS.md，运行：python3 << 'EOF' < scripts/...（参见提交历史中的生成脚本）。
6. 打开拉取请求。

当前列表请参阅 MODELS.md，架构详情请参阅 AGENTS.md。

---

OpenClaw 集成

llmfit 以 OpenClaw 技能的形式提供，该技能可以让代理推荐适合硬件的本地模型，并自动配置 Ollama/vLLM/LM Studio 提供者。

安装技能

# 从 llmfit 仓库
./scripts/install-openclaw-skill.sh

# 或手动
cp -r skills/llmfit-advisor ~/.openclaw/skills/

安装完成后，您可以向 OpenClaw 代理询问以下问题：

• “我可以运行哪些本地模型？”
• “为我的硬件推荐一个编码模型”
• “用最适合我 GPU 的模型来配置 Ollama”

代理会在后台调用 llmfit recommend --json，解析结果，并提示您将最佳模型选择配置到 openclaw.json 文件中。

工作原理

该技能教会 OpenClaw 代理：

1. 通过 llmfit --json system 检测您的硬件
2. 通过 llmfit recommend --json 获取排名推荐
3. 将 HuggingFace 模型名称映射到 Ollama/vLLM/LM Studio 标签
4. 配置 openclaw.json 中的 models.providers.ollama.models

完整技能定义请参阅 skills/llmfit-advisor/SKILL.md。

---

替代方案

如果您正在寻找其他方法，可以查看 llm-checker —— 一个集成了 Ollama 的 Node.js 命令行工具，可以直接拉取和基准测试模型。它采用更直接的方式，通过 Ollama 在您的硬件上实际运行模型，而不是仅根据规格估算性能。如果您已经安装了 Ollama 并希望测试真实性能，这将是一个不错的选择。需要注意的是，它不支持 MoE（专家混合）架构——所有模型都被视为密集型模型，因此像 Mixtral 或 DeepSeek-V3 这样的模型的内存估算将反映总参数量，而非较小的活跃子集。

---

许可证

MIT

llmfit 快速上手指南

llmfit 是一款终端工具，旨在根据你的硬件配置（RAM、CPU、GPU）智能推荐最适合运行的大语言模型（LLM）。它能检测系统规格，从质量、速度、适配度和上下文长度等维度对模型进行评分，并告诉你哪些模型能在你的机器上流畅运行。

环境准备

• 操作系统：支持 Windows、macOS (Intel/Apple Silicon) 和 Linux。
• 硬件要求：无特殊限制，工具会自动检测你的 CPU、内存、显卡及显存信息。
• 前置依赖：
  • Windows: 建议安装 Scoop 包管理器。
  • macOS: 建议安装 Homebrew。
  • Linux/macOS (源码编译): 需安装 Rust 工具链 (cargo)。
  • 运行时 (可选): 若需直接运行模型，建议预先安装 Ollama、llama.cpp 或 LM Studio 等后端，llmfit 会自动识别它们。

安装步骤

请选择适合你系统的安装方式：

Windows (使用 Scoop)

scoop install llmfit

若未安装 Scoop，请先访问 https://scoop.sh/ 进行安装。

macOS / Linux

方式一：使用 Homebrew (推荐 macOS 用户)

brew install llmfit

方式二：一键脚本安装 (通用) 下载最新二进制文件并安装到 /usr/local/bin (需要 sudo 权限)：

curl -fsSL https://llmfit.axjns.dev/install.sh | sh

方式三：免 sudo 安装到用户目录 将二进制文件安装到 ~/.local/bin：

curl -fsSL https://llmfit.axjns.dev/install.sh | sh -s -- --local

注意：如果选择此方式，请确保 ~/.local/bin 已添加到你的 $PATH 环境变量中。

使用 Docker / Podman

无需安装二进制文件，直接运行容器：

docker run ghcr.io/alexsjones/llmfit

从源码编译

git clone https://github.com/AlexsJones/llmfit.git
cd llmfit
cargo build --release
# 编译后的二进制文件位于 target/release/llmfit

基本使用

1. 启动交互式界面 (TUI) - 推荐

直接运行命令即可启动带有图形界面的终端模式，自动检测硬件并列出推荐模型：

llmfit

核心操作快捷键：

• j / k 或 ↑ / ↓：上下浏览模型列表。
• /：进入搜索模式（支持按名称、提供商、参数量搜索）。
• f：切换适配度过滤（所有 / 可运行 / 完美适配 / 良好 / 勉强）。
• p：进入 Plan 模式，反向推算运行选定模型所需的硬件配置。
• d：下载选中的模型（需已安装对应的运行时后端）。
• Enter：查看模型详细信息。
• q：退出程序。

提示：启动 TUI 后，工具会自动在后台开启一个 Web 仪表盘，默认地址为 http://0.0.0.0:8787，你可以在浏览器中查看相同的分析结果。

2. 命令行模式 (CLI)

如果你需要在脚本中使用或仅需文本输出，可以使用 --cli 标志或子命令。

查看适配度排名列表：

llmfit --cli

仅显示“完美适配”的前 5 个模型：

llmfit fit --perfect -n 5

查看当前系统硬件检测结果：

llmfit system

搜索特定模型（如 llama 8b）：

llmfit search "llama 8b"

以 JSON 格式输出推荐结果（适合集成到 Agent 或脚本）：

llmfit recommend --json --limit 5

针对特定场景推荐（例如编程）：

llmfit recommend --json --use-case coding --limit 3