AlexsJones/llmfit
GitHub: AlexsJones/llmfit
一款终端硬件适配工具，自动检测系统规格并从数百个 LLM 模型中筛选出最适合你机器运行的模型及最优量化方案。
Stars: 24415 | Forks: 1461
# llmfit
: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
# 强制指定特定 runtime（绕过 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 行为：
```
# 自动 spawn 服务器并运行端点/模式/过滤器断言
python3 scripts/test_api.py --spawn
# 或者测试一个已经在运行的服务器
python3 scripts/test_api.py --base-url http://127.0.0.1:8787
```
### 硬件覆盖
硬件自动检测在某些系统上可能会失败（例如损坏的 `nvidia-smi`、虚拟机、直通设置），或者你可能希望针对不同的目标硬件评估模型适配度。使用 `--memory`、`--ram` 和 `--cpu-cores` 来覆盖检测到的值：
```
# 覆盖 GPU VRAM
llmfit --memory=32G
# 覆盖系统 RAM
llmfit --ram=128G
# 覆盖 CPU 核心数
llmfit --cpu-cores=16
# 组合覆盖项以模拟目标硬件
llmfit --memory=24G --ram=64G --cpu-cores=8 fit
llmfit --memory=24G --ram=64G system --json
# 适用于所有模式：TUI、CLI 和子命令
llmfit --memory=24G --cli
llmfit --memory=24G fit --perfect -n 5
llmfit --ram=64G recommend --json
```
`--memory` 和 `--ram` 接受的后缀：`G`/`GB`/`GiB`（吉字节），`M`/`MB`/`MiB`（兆字节），`T`/`TB`/`TiB`（太字节）。不区分大小写。如果未检测到 GPU，`--memory` 会创建一个合成 GPU 条目，以便为 GPU 推理对模型进行评分。在统一内存系统上，`--ram` 也会更新 VRAM；请使用 `--memory` 独立覆盖 VRAM。
### 用于估算的上下文长度上限
使用 `--max-context` 来限制用于内存估算的上下文长度（不改变每个模型公布的 advertised maximum 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 # Hardware specs as JSON
llmfit --json fit -n 10 # Top 10 fits as JSON
llmfit recommend --json # Top 5 recommendations (JSON is default for recommend)
llmfit plan "Qwen/Qwen2.5-Coder-0.5B-Instruct" --context 8192 --json
```
`plan` 的 JSON 包含以下稳定字段：
- 请求（`context`、`quantization`、`target_tps`）
- 预估的最低/推荐硬件
- 每条路径的可行性（`gpu`、`cpu_offload`、`cpu_only`）
- 升级增量
## 工作原理
1. **硬件检测** —— 通过 `sysinfo` 读取总/可用 RAM，计算 CPU 核心数，并探测 GPU：
- **NVIDIA** —— 通过 `nvidia-smi` 支持多 GPU。汇总所有检测到的 GPU 的 VRAM。如果报告失败，则从 GPU 型号名称回退到 VRAM 估算。
- **AMD** —— 通过 `rocm-smi` 检测。
- **Intel Arc** —— 独立显存通过 sysfs 获取，核显通过 `lspci` 获取。
- **Apple Silicon** —— 通过 `system_profiler` 获取统一内存。VRAM = 系统 RAM。
- **Ascend** —— 通过 `npu-smi` 检测。
- **后端检测** —— 自动识别加速后端（CUDA、Metal、ROCm、SYCL、CPU ARM、CPU x86、Ascend）以进行速度估算。
2. **模型数据库** —— 数百种模型均来源于 HuggingFace API，存储在 `data/hf_models.json` 中并在编译时嵌入。内存需求是根据跨量化层级（从 Q8_0 到 Q2_K）的参数数量计算得出的。VRAM 是 GPU 推理的主要限制；系统内存是纯 CPU 执行的回退方案。
**MoE 支持** —— 带有混合专家架构的模型（Mixtral、DeepSeek-V2/V3）会被自动检测。每个 token 只激活专家的一个子集，因此有效的 VRAM 需求远低于总参数数量所暗示的值。例如，Mixtral 8x7B 有 46.7B 的总参数，但每个 token 仅激活约 12.9B，在启用专家卸载的情况下，将 VRAM 从 23.9 GB 降低到了约 6.6 GB。
3. **动态量化** —— llmfit 不采用固定的量化方式，而是尝试最适合你硬件的高质量量化。它从 Q8_0（最佳质量）向下遍历到 Q2_K（最高压缩）的层级，选择能装入可用内存的最高质量量化。如果在完整上下文下没有任何一种能装入，它会以一半的上下文再次尝试。
4. **多维度评分** —— 每个模型都通过四个维度进行评分（各项 0-100 分）：
| 维度 | 衡量内容 |
|-------------|--------------------------------------------------------------------------------|
| **Quality** | 参数数量、模型家族声誉、量化惩罚、任务一致性 |
| **Speed** | 基于后端、参数和量化估算的 tokens/sec |
| **Fit** | 内存利用率效率（最佳点：可用内存的 50–80%） |
| **Context** | 上下文窗口能力与用例目标的对比 |
各维度被组合成一个加权的综合评分。权重因用例类别（General、Coding、Reasoning、Chat、Multimodal、Embedding）而异。例如，Chat 对 Speed 的权重更高（0.35），而 Reasoning 对 Quality 的权重更高（0.55）。模型按综合评分排名，不可运行的模型（Too Tight）始终排在最末。
5. **速度估算** —— LLM 推理中的 token 生成受限于内存带宽：每个 token 需要从 VRAM 中读取一次完整的模型权重。当 GPU 型号被识别时，llmfit 会使用其实际的内存带宽来估算吞吐量：
公式：`(bandwidth_GB_s / model_size_GB) × efficiency_factor`
效率因子（0.55）和每种模式的乘数可以通过高级配置弹窗（TUI 中的 `A`）进行调整。默认值考虑了内核开销、KV-cache 读取和内存控制器效应。此方法已通过 llama.cpp（[Apple Silicon](https://github.com/ggml-org/llama.cpp/discussions/4167)、[NVIDIA T4](https://github.com/ggml-org/llama.cpp/discussions/4225)）发布的基准测试和真实世界测量结果进行了验证。
带宽查找表涵盖了 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 × quant_speed_multiplier`，其中每种模式的惩罚可通过高级配置弹窗（TUI 中的 `A`）进行调整。
6. **适配分析** —— 对每个模型进行内存兼容性评估：
**运行模式：**
- **GPU** —— 模型适合装入 VRAM。快速推理。
- **MoE** —— 带有专家卸载的混合专家模型。活跃专家在 VRAM 中，非活跃专家在 RAM 中。
- **CPU+GPU** —— VRAM 不足，溢出到系统内存并进行部分 GPU 卸载。
- **CPU** —— 无 GPU。模型完全加载到系统内存中。
**适配等级：**
- **Perfect** —— 在 GPU 上满足推荐内存。需要 GPU 加速。
- **Good** —— 适配且有余量。MoE 卸载或 CPU+GPU 所能达到的最佳状态。
- **Marginal** —— 勉强适配，或仅限 CPU（纯 CPU 始终止步于此）。
- **Too Tight** —— VRAM 或系统内存均不足。
## 模型数据库
模型列表由 `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 架构。
模型类别涵盖通用目的、编程、推理 (DeepSeek-R1、Orca-2)、多模态/视觉 (Llama 3.2 Vision、Llama 4 Scout/Maverick、Qwen2.5-VL)、聊天、企业 和嵌入 (nomic-embed、bge)。
完整列表请参见 [MODELS.md](MODELS.md)。
模型数据库在编译时嵌入，因此**最终用户**只需通过升级 llmfit 本身（`brew upgrade llmfit`、`scoop update llmfit` 或下载最新版本）即可获取更新。以下命令适用于**贡献者**从源代码刷新数据库：
要刷新模型数据库：
```
# 自动更新（推荐）
make update-models
# 或者直接运行脚本
./scripts/update_models.sh
# 或者手动操作
python3 scripts/scrape_hf_models.py
cargo build --release
```
该抓取工具会写入 `data/hf_models.json`，该文件通过 `include_str!` 被烘焙进二进制文件中。自动更新脚本会备份现有数据，验证 JSON 输出，并重新构建二进制文件。
默认情况下，抓取工具会使用来自 [unsloth](https://huggingface.co/unsloth) 和 [bartowski](https://huggingface.co/bartowski) 等提供商的已知 GGUF 下载源来丰富模型信息。结果会缓存在 `data/gguf_sources_cache.json` 中（7 天 TTL），以避免重复的 API 调用。使用 `--no-gguf-sources` 可跳过此步骤，从而实现更快的抓取速度。
## 项目结构
```
src/
main.rs -- CLI argument parsing, entrypoint, TUI launch
hardware.rs -- System RAM/CPU/GPU detection (multi-GPU, backend identification)
models.rs -- Model database, quantization hierarchy, dynamic quant selection
fit.rs -- Multi-dimensional scoring (Q/S/F/C), speed estimation, MoE offloading
providers.rs -- Runtime provider integration (Ollama, llama.cpp, MLX, Docker Model Runner, LM Studio), install detection, pull/download
display.rs -- Classic CLI table rendering + JSON output
tui_app.rs -- TUI application state, filters, navigation
tui_ui.rs -- TUI rendering (ratatui)
tui_events.rs -- TUI keyboard event handling (crossterm)
data/
hf_models.json -- Model database (206 models)
skills/
llmfit-advisor/ -- OpenClaw skill for hardware-aware model recommendations
scripts/
scrape_hf_models.py -- HuggingFace API scraper
update_models.sh -- Automated database update script
install-openclaw-skill.sh -- Install the OpenClaw skill
Makefile -- Build and maintenance commands
```
## 发布到 crates.io
`Cargo.toml` 已包含所需的元数据（description、license、repository）。要发布：
```
# 首先进行 Dry run 以捕获问题
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/` 和 `demo.gif` 排除在已发布的 crate 之外，以保持较小的下载体积。
要发布更新：
```
# 提升版本
# 编辑 Cargo.toml：version = "0.2.0"
cargo publish
```
## 依赖项
| Crate | 用途 |
|------------------------|--------------------------------------------------|
| `clap` | 带有派生宏的 CLI 参数解析 |
| `sysinfo` | 跨平台的 RAM 和 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 模型缓存 + 可选服务器） —— MLX 下载映射到 HuggingFace 上的 `mlx-community/*` 仓库，而不是原始模型发布者
- **Docker Model Runner**（Docker Desktop 的内置模型服务）
- **LM Studio**（带有用于模型管理 + 下载的 REST API 的本地模型服务器）
当某个模型有多个兼容的提供商时，在 TUI 中按 `d` 会打开一个提供商选择器弹窗。
### Ollama 集成
llmfit 与 [Ollama](https://ollama.com) 集成，以检测你已安装的模型，并直接从 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 installed)`。
当你在某个模型上按 `d` 时，llmfit 会向 Ollama 发送 `POST /api/pull` 以下载它。该行将以动画进度指示器高亮显示，实时显示下载进度。一旦完成，该模型即可立即在 Ollama 中使用。
如果 Ollama 未运行，则跳过特定于 Ollama 的操作；在可用的情况下，TUI 仍支持其他提供商（如 llama.cpp）。
### llama.cpp 集成
llmfit 在 TUI 和 CLI 中都将 [llama.cpp](https://github.com/ggml-org/llama.cpp) 作为运行时/下载提供商进行集成。
前置条件：
- `PATH` 中可用 `llama-cli` 或 `llama-server`（用于运行时检测）
- 具备访问 Hugging Face 的网络权限以下载 GGUF
工作原理：
- llmfit 将 HF 模型映射到已知的 GGUF 仓库（带有启发式回退）
- 将 GGUF 文件下载到本地的 llama.cpp 模型缓存中
- 当本地存在匹配的 GGUF 文件时，将模型标记为已安装
#### 环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `LLAMA_CPP_PATH` | *(无)* | 包含 llama.cpp 二进制文件（`llama-cli`、`llama-server`）的目录。在 `PATH` 查找之前检查。 |
| `LLAMA_SERVER_PORT` | `8080` | 在探测正在运行的 `llama-server` 健康端点以进行运行时检测时使用的端口。 |
如果 llama.cpp 安装在非标准位置，请设置 `LLAMA_CPP_PATH`，以便 llmfit 能找到它，而不需要将其放入你的 `PATH` 中。
### Docker Model Runner 集成
llmfit 与 [Docker Model Runner](https://docs.docker.com/desktop/features/model-runner/) 集成，这是 Docker Desktop 的内置模型服务功能。
前置条件：
- 启用了 Model Runner 的 Docker Desktop
- 默认端点：`http://localhost:12434`
工作原理：
- llmfit 查询 `GET /engines` 以列出 Docker Model Runner 中可用的模型
- 使用 Ollama 风格的标签映射将模型匹配到 HF 数据库（Docker Model Runner 使用 `ai/` 命名方式）
- 在 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](https://lmstudio.ai) 作为具有内置模型下载功能的本地模型服务器进行集成。
前置条件：
- 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 自动检测。Adreno 等移动 GPU 通常无法通过 llmfit 使用的桌面/服务器探测接口看到。
### GPU 支持
| 厂商 | 检测方法 | VRAM 报告 |
|------------------------|-------------------------------|--------------------------------|
| NVIDIA | `nvidia-smi` | 精确的独立显存 |
| AMD | `rocm-smi` | 已检测（VRAM 可能为未知） |
| Intel Arc (独立显卡) | sysfs (`mem_info_vram_total`) | 精确的独立显存 |
| Intel Arc (核显) | `lspci` | 共享的系统内存 |
| Apple Silicon | `system_profiler` | 统一内存 (= 系统 RAM) |
| Ascend | `npu-smi` | 已检测（VRAM 可能为未知） |
如果自动检测失败或报告了错误的值，请使用 `--memory`、`--ram` 或 `--cpu-cores` 进行覆盖（参见上面的[硬件覆盖](#hardware-overrides)）。
### Android / Termux 注意事项
在诸如 **Termux + PRoot** 等 Android 环境中，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 运行时检测。
## 参与贡献
欢迎贡献，尤其是添加新模型。
### 在提交 PR 之前
请在推送更改之前运行 `cargo fmt`。大多数 CI 检查失败都是由未格式化的代码引起的：
```
cargo fmt
```
### 添加模型
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](MODELS.md)：`python3 << 'EOF' < scripts/...`（参见提交历史中的生成器脚本）
6. 提交 Pull Request。
当前列表请参见 [MODELS.md](MODELS.md)，架构细节请参见 [AGENTS.md](AGENTS.md)。
## OpenClaw 集成
llmfit 作为 [OpenClaw](https://github.com/openclaw/openclaw) 技能提供，允许 Agent 推荐适合硬件的本地模型，并自动配置 Ollama/vLLM/LM Studio 提供商。
### 安装技能
```
# 从 llmfit 仓库
./scripts/install-openclaw-skill.sh
# 或者手动操作
cp -r skills/llmfit-advisor ~/.openclaw/skills/
```
安装后，你可以向你的 OpenClaw Agent 提问，例如：
- “我可以运行哪些本地模型？”
- “为我的硬件推荐一个编程模型”
- “使用最适合我 GPU 的模型设置 Ollama”
该 Agent 会在后台调用 `llmfit recommend --json`，解释结果，并提议使用最佳的模型选择配置你的 `openclaw.json`。
### 工作原理
该技能教会 OpenClaw Agent：
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](skills/llmfit-advisor/SKILL.md)。
## 替代方案
如果你正在寻找不同的方法，请查看 [llm-checker](https://github.com/Pavelevich/llm-checker) —— 这是一个带有 Ollama 集成的 Node.js CLI 工具，可以直接拉取并对模型进行基准测试。它采取了一种更实际的方法，通过 Ollama 在你的硬件上实际运行模型，而不是根据规格进行估算。如果你已经安装了 Ollama 并想测试真实世界的性能，这会是一个很好的选择。请注意，它不支持 MoE（混合专家）架构 —— 所有模型都被视为密集模型，因此对于像 Mixal 或 DeepSeek-V3 这样的模型，其内存估算反映的是总参数量，而不是较小的活跃子集。
## 许可证
MIT
English · 中文
标签：Apex, CLI, CPU, DLL 劫持, Docker, GPU支持, llama.cpp, LLM, LLM评估, LM Studio, MLX, MoE架构, Ollama, Rust, SEO检索, TUI, Unmanaged PE, WiFi技术, 交互式终端, 人工智能, 内存评估, 可视化界面, 国家安全局, 多GPU, 大语言模型, 安全防御评估, 开源, 性能评分, 推理速度估算, 本地推理, 本地部署, 机器学习, 模型下载管理, 模型压缩, 模型推荐, 模型评估, 模型量化, 用户模式Hook绕过, 硬件检测, 系统适配, 网络流量审计, 网络测绘, 请求拦截, 运行时提供商, 逆向工具, 通知系统