diff --git a/README.md b/README.md index ace1d68..17049ad 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,9 @@ + +> [!NOTE] +> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 +> [English](./README.en.md) · [原始项目](https://github.com/AlexsJones/llmfit) · [上游 README](https://github.com/AlexsJones/llmfit/blob/HEAD/README.md) +> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 + # llmfit

@@ -5,8 +11,8 @@

- English · - 中文 · + English · + 中文 · 日本語

@@ -17,53 +23,48 @@ Signed with SignPath

-> **📊 New: benchmark & share — real numbers from your machine, better estimates for everyone.** `llmfit bench --share` measures real tok/s on your hardware and contributes it back to the project as a PR — no `gh` CLI, no third-party account. Every run is saved locally first (skip sharing, upload the backlog any time), your own measurements replace estimates in the fit table, and each merged submission ships in the next release: anyone on identical hardware gets measured `✓` numbers and calibrated estimates before they ever run a benchmark. [Get started with sharing →](docs/cli.md#contributing-benchmarks-bench---share) +> **📊 新功能：基准测试与共享 — 来自你机器的真实数据，让所有人的估算更准确。** `llmfit bench --share` 在你的硬件上实测 tok/s，并以 PR 的形式贡献回项目 — 无需 `gh` CLI，也无需第三方账号。每次测试结果都会先保存在本地（可以暂不共享，之后随时批量上传），你自己的实测值会替换拟合表中的估算值；每条合并的提交都会随下一个版本发布：相同硬件的用户无需自己跑基准测试，就能获得实测 `✓` 数值和校准后的估算。[开始共享 →](docs/cli.md#contributing-benchmarks-bench---share) > -> *Previously: [llmfit 1.0 — the release where the numbers became verifiable →](https://github.com/AlexsJones/llmfit/discussions/708)* +> *此前：[llmfit 1.0 — 让每个数字都可验证的里程碑版本 →](https://github.com/AlexsJones/llmfit/discussions/708)* -**Hundreds of models & providers. One command to find what runs on your hardware.** +**数百种模型与提供商，一条命令即可找出你的硬件能运行哪些模型。** -A terminal tool that right-sizes LLM models to your system's RAM, CPU, and GPU. Detects your hardware, scores each model across quality, speed, fit, and context dimensions, and tells you which ones will actually run well on your machine. +一款终端工具，根据你系统的 RAM、CPU 和 GPU 为 LLM 模型匹配合适的规格。自动检测硬件，从质量、速度、适配度和上下文四个维度为每个模型打分，告诉你哪些模型能在你的机器上流畅运行。 -Ships with an interactive TUI (default) and a classic CLI mode. Supports multi-GPU setups, MoE architectures, dynamic quantization selection, speed estimation, and local runtime providers (Ollama, llama.cpp, MLX, Docker Model Runner, LM Studio). +内置交互式 TUI（默认）和经典 CLI 模式。支持多 GPU 配置、MoE（混合专家）架构、动态量化选择、速度估算，以及本地运行时提供商（Ollama、llama.cpp、MLX、Docker Model Runner、LM Studio）。 -> **Sister projects:** -> - [sympozium](https://github.com/sympozium-ai/sympozium/) — managing agents in Kubernetes. -> - [llmserve](https://github.com/AlexsJones/llmserve) — a simple TUI for serving local LLM models. Pick a model, pick a backend, serve it. -> - [llama-panel](https://github.com/AlexsJones/llama-panel) — a native macOS app for managing local llama-server instances. +**新功能：[社区排行榜](#社区排行榜-b) (`b`)** — 查看与你使用相同硬件的其他用户的真实 tok/s、TTFT 和 VRAM 占用情况。由 [localmaxxing.com](https://localmaxxing.com) 提供支持，这弥合了预估性能与实际性能之间的差距。 -![demo](assets/demo.gif) +同时：[下载管理器](#下载管理器-d) (`D`)、[高级配置](#高级配置-a) (`A`) 和 [硬件模拟](#硬件模拟-s) — 按 `D` 管理下载、查看历史记录、删除模型以及配置下载目录。按 `A` 调整 TPS 效率、运行模式系数和评分权重。按 `S` 模拟不同的硬件。 -## Documentation +> **姐妹项目：** +> - [sympozium](https://github.com/sympozium-ai/sympozium/) — 在 Kubernetes 中管理 Agent。 +> - [llmserve](https://github.com/AlexsJones/llmserve) — 一个简单的 TUI，用于服务本地 LLM 模型。选择模型、选择后端、开始服务。 +> - [llama-panel](https://github.com/AlexsJones/llama-panel) — 用于管理本地 llama-server 实例的原生 macOS 应用。 -| | | -|---|---| -| **Get started** | [Install](#install) · [Usage](#usage) · [How it works](#how-it-works) | -| **Guides** | [TUI guide](docs/tui.md) · [CLI & automation](docs/cli.md) · [Runtime providers](docs/providers.md) · [OpenClaw integration](docs/openclaw.md) | -| **Reference** | [How it works (full)](docs/how-it-works.md) · [Platform & GPU support](docs/platform-support.md) · [Custom models](docs/custom-models.md) · [Development](docs/development.md) | -| **Project** | [Contributing](#contributing) · [Alternatives](#alternatives) · [Code signing](#code-signing) · [License](#license) | +![演示](assets/demo.gif) --- -## Install +## 安装 ### Windows ```sh scoop install llmfit ``` -If Scoop is not installed, follow the [Scoop installation guide](https://scoop.sh/). +如果尚未安装 Scoop，请参阅 [Scoop 安装指南](https://scoop.sh/)。 ### macOS / Linux #### Homebrew -Prebuilt binary (recommended, works on all macOS/Linux versions): +预编译的二进制文件（推荐，适用于所有 macOS/Linux 版本）： ```sh brew install AlexsJones/llmfit/llmfit ``` -Or from the homebrew-core formula, which builds from source on macOS versions without a bottle: +或者从 homebrew-core 公式安装，对于没有预编译包的 macOS 版本将从源码编译： ```sh brew install llmfit ``` @@ -73,118 +74,938 @@ brew install llmfit port install llmfit ``` -#### Quick install +#### 快速安装 ```sh curl -fsSL https://llmfit.axjns.dev/install.sh | sh ``` -Downloads the latest release binary from GitHub and installs it to `/usr/local/bin` (or `~/.local/bin` if no sudo). +从 GitHub 下载最新发布的二进制文件并安装到 `/usr/local/bin`（如果没有 sudo 则安装到 `~/.local/bin`）。 -**Install to `~/.local/bin` without sudo:** +**安装到 `~/.local/bin`（无需 sudo）：** ```sh curl -fsSL https://llmfit.axjns.dev/install.sh | sh -s -- --local ``` ### uv / pip -To install or update llmfit: +安装或更新 llmfit： ```sh uv tool install -U llmfit ``` -To run without installing: +不安装直接运行： ```sh uvx llmfit ``` -You can also install llmfit as a Python package in the normal way with tools such as pip or uv. +你也可以像普通 Python 包一样，使用 pip 或 uv 等工具安装 llmfit。 ### Docker / Podman ```sh docker run ghcr.io/alexsjones/llmfit ``` -This prints JSON from `llmfit recommend` command. The JSON could be further queried with `jq`. +此命令会输出 `llmfit recommend` 命令的 JSON 结果，可以用 `jq` 进一步查询。 ``` podman run ghcr.io/alexsjones/llmfit recommend --use-case coding | jq '.models[].name' ``` -To launch the interactive TUI instead, pass the global `--tui` flag: -```sh -docker run --rm -it ghcr.io/alexsjones/llmfit --tui -``` -### From source +### 从源码构建 ```sh git clone https://github.com/AlexsJones/llmfit.git cd llmfit cargo build --release -# binary is at target/release/llmfit +# 二进制文件位于 target/release/llmfit ``` --- -## Usage +## 使用方法 + +### TUI（默认） ```sh -llmfit # interactive TUI: your hardware, every model, ranked +llmfit ``` -The TUI shows your detected specs at the top and every model scored for fit, speed, quality, and context. See the [TUI guide](docs/tui.md) for navigation, planning, simulation, downloads, the community leaderboard, and benchmarking. +启动交互式终端 UI。系统配置（CPU、RAM、GPU 名称、VRAM、后端）显示在顶部。模型按综合评分排序，以可滚动的表格列出。每行显示模型的评分、预估 tok/s、适合你硬件的最佳量化方案、运行模式、内存占用和用途分类。 -For scripts, agents, and classic terminal output: +| 按键 | 操作 | +|----------------------------|-------------------------------------------------| +| `Up` / `Down` 或 `j` / `k` | 浏览模型 | +| `/` | 进入搜索模式（按名称、提供商、参数量、用途模糊匹配） | +| `Esc` 或 `Enter` | 退出搜索模式 | +| `Ctrl-U` | 清除搜索 | +| `f` | 切换适配度过滤：全部、可运行、完美、良好、勉强 | +| `a` | 切换可用性过滤：全部、GGUF 可用、已安装 | +| `s` | 切换排序列：评分、参数量、内存%、上下文、日期、用途 | +| `v` | 进入 Visual 模式（多选模型） | +| `V` | 进入 Select 模式（按列过滤） | +| `t` | 切换颜色主题（自动保存） | +| `p` | 打开 Plan 模式用于选中的模型（硬件规划） | +| `P` | 打开提供商过滤弹窗（输入以模糊过滤提供商） | +| `U` | 打开用途过滤弹窗 | +| `C` | 打开能力过滤弹窗 | +| `L` | 打开许可证过滤弹窗 | +| `R` | 打开运行时/后端过滤弹窗（llama.cpp、MLX、vLLM） | +| `S` | 打开硬件模拟弹窗（覆盖 RAM/VRAM/CPU） | +| `A` | 打开高级配置弹窗（调整效率、运行模式系数） | +| `b` | 打开社区排行榜视图（localmaxxing.com） | +| `I` | 打开推理基准测试视图（对你的模型进行本地质量评分） | +| `h` | 打开帮助弹窗（所有快捷键） | +| `m` | 标记选中模型用于对比 | +| `c` | 打开对比视图（已标记 vs 选中） | +| `x` | 清除对比标记 | +| `i` | 切换已安装优先排序（任何已检测的运行时提供商） | +| `d` | 下载选中模型（多个提供商可用时弹出选择器） | +| `D` | 打开下载管理器（历史记录、删除、配置） | +| `r` | 从运行时提供商刷新已安装模型 | +| `Enter` | 切换选中模型的详情视图 | +| `PgUp` / `PgDn` | 滚动 10 行 | +| `g` / `G` | 跳转到顶部 / 底部 | +| `q` | 退出 | + +### 类 Vim 模式 + +TUI 使用类 Vim 模式，当前模式显示在左下角状态栏。当前模式决定哪些按键生效。 + +#### Normal 模式 + +默认模式。可浏览、搜索、过滤和打开各种视图。上表中的所有按键均在此模式下有效。 + +#### Visual 模式 (`v`) + +选择连续的多个模型进行批量对比。按 `v` 在当前行设置锚点，然后用 `j`/`k` 或方向键扩展选区。选中的行会高亮显示。 + +| 按键 | 操作 | +|--------------------|--------------------------------------| +| `j` / `k` 或方向键 | 向上/下扩展选区 | +| `c` | 对比所有选中模型（打开多模型对比视图） | +| `m` | 标记当前模型用于双模型对比 | +| `Esc` 或 `v` | 退出 Visual 模式 | + +多模型对比视图以表格形式显示，行为属性（评分、tok/s、适配度、内存%、参数量、模式、上下文、量化等），列为模型。最优值会高亮显示。如果选中的模型超出屏幕宽度，可用 `h`/`l` 或方向键水平滚动。 + +#### Select 模式 (`V`) + +按列过滤。按 `V`（shift-v）进入 Select 模式，然后用 `h`/`l` 或方向键在列标题间移动。当前列会高亮显示。按 `Enter` 或 `Space` 触发该列当前的过滤操作。 + +| 列 | 过滤操作 | +|-------------------------------|-------------------------------------------------------| +| Inst | 切换可用性过滤 | +| Model | 进入搜索模式 | +| Provider | 打开提供商弹窗 | +| Params | 打开参数量分组弹窗（<3B、3-7B、7-14B、14-30B、30-70B、70B+） | +| Score, tok/s, Mem%, Ctx, Date | 按该列排序 | +| Quant | 打开量化弹窗 | +| Mode | 打开运行模式弹窗（GPU、MoE、CPU+GPU、CPU） | +| Fit | 切换适配度过滤 | +| Use Case | 打开用途弹窗 | + +在 Select 模式下仍可用 `j`/`k`、方向键、`Ctrl-U`、`Ctrl-D`、`PageUp`、`PageDown`、`Home` 和 `End` 浏览行，以便在应用过滤器时查看效果。按 `Esc` 返回 Normal 模式。 + +### TUI Plan 模式 (`p`) + +Plan 模式与常规适配分析相反：不是问“我的硬件能跑什么？”，而是估算“这个模型配置需要什么硬件？”。 + +在选中的行上按 `p`，然后： + +| 按键 | 操作 | +|------------------------|------------------------------------------| +| `Tab` / `j` / `k` | 在可编辑字段间移动（上下文、量化、目标 TPS） | +| `Left` / `Right` | 在当前字段内移动光标 | +| 输入 | 编辑当前字段 | +| `Backspace` / `Delete` | 删除字符 | +| `Ctrl-U` | 清空当前字段 | +| `Esc` 或 `q` | 退出 Plan 模式 | + +Plan 模式显示以下估算： +- 最低和推荐的 VRAM/RAM/CPU 核心数 +- 可行的运行路径（GPU、CPU 卸载、纯 CPU） +- 达到更好适配目标所需的升级差距 + +### 硬件模拟 (`S`) + +按 `S` 打开硬件模拟弹窗。覆盖 RAM、VRAM 和 CPU 核心数，查看哪些模型适合不同的目标硬件。所有模型评分、适配等级和速度估算会根据模拟配置即时重新计算。 + +![硬件模拟](assets/simulation.png) + +| 按键 | 操作 | +|------------------------|-----------------------------------------| +| `Tab` / `j` / `k` | 在 RAM、VRAM、CPU 字段间切换 | +| 输入数字 | 编辑选中字段 | +| `Enter` | 应用模拟 | +| `Ctrl-R` | 重置为真实检测到的硬件 | +| `Esc` | 取消并关闭 | + +模拟激活时，系统栏和状态栏会显示 `SIM` 标识。整个模型表格会反映模拟硬件，直到你重置。 + +### 高级配置 (`A`) + +按 `A` 打开高级配置弹窗。该面板允许你调整 TPS 估算、运行模式惩罚和综合评分背后的参数 — 解决部分模型（如 Qwen3 30B）tok/s 被高估的 [问题 #449](https://github.com/AlexsJones/llmfit/issues/449)。 + +所有更改会立即应用并重新计算模型表格。按 `Esc` 接受，或按 `Ctrl-R` 重置为默认值。 + +| 字段 | 描述 | 默认值 | +|-------------------|-------------------------------------------------------------------------|---------| +| **Efficiency** | 基于带宽的 TPS 的全局效率系数。计算开销 | `0.55` | +| **GPU factor** | 纯 GPU 推理的速度乘数 | `1.0` | +| **CPU Offload** | 当权重溢出到系统 RAM 时的速度乘数 | `0.5` | +| **MoE Offload** | 混合专家模型进行专家切换时的速度乘数 | `0.8` | +| **Tensor Par** | 张量并行推理的速度乘数 | `0.9` | +| **CPU Only** | 纯 CPU 执行的速度乘数 | `0.3` | +| **Context cap** | 内存估算使用的最大上下文长度（留空为默认值） | `auto` | + +| 按键 | 操作 | +|------------------------|-----------------------------------------| +| `Tab` / `j` / `k` | 在字段间切换 | +| 输入数字 / `.` | 编辑选中的字段 | +| `Left` / `Right` | 在字段内移动光标 | +| `Backspace` / `Delete` | 删除字符 | +| `Ctrl-U` | 清空当前字段 | +| `Enter` | 应用更改并重新计算所有评分 | +| `Esc` / `q` | 关闭且不应用更改 | + +### 下载管理器 (`D`) + +按 `D` 打开下载管理器视图。该全屏视图会替换主模型表格并提供三个部分： + +- **当前下载 (Active Download)** — 显示当前正在进行的下载及进度条、模型名称和状态信息。 +- **配置 (Config)** — 显示（并允许编辑）GGUF 模型目录。配置的路径会在会话间持久保留。 +- **历史记录 (History)** — 以最新优先排列的历史下载列表，包含模型名称、提供商、状态和日期。可以从历史记录中移除失败的下载，也可以从提供商中删除已成功的下载模型。 + +使用 `Tab` / `Shift-Tab` 在各个部分间循环切换焦点。 + +| 按键 | 操作 | +|------------------------|------------------------------------------------| +| `Tab` / `Shift-Tab` | 循环切换焦点：当前下载 → 配置 → 历史记录 | +| `j` / `k` 或方向键 | 浏览历史记录列表（历史记录为焦点时） | +| `x` | 删除选中的模型（会弹出确认提示） | +| `y` / `n` | 确认或取消删除 | +| `e` | 编辑下载目录（配置为焦点时） | +| `Enter` | 确认目录编辑 | +| `Esc` / `D` / `q` | 关闭并返回模型表格 | + +对于失败的下载（如 404 错误），`x` 会将其从历史记录中移除。对于成功的下载，`x` 将从提供商中删除模型（支持 Ollama 和 llama.cpp）。 + +### 社区排行榜 (`b`) + +按 `b` 打开社区排行榜视图。此视图不仅仅依赖于 llmfit 的理论速度估算，而是展示使用相同硬件的其他用户的**真实性能数据** — 实际测量的 tok/s、首次 token 响应时间和峰值 VRAM 使用率。 + +![社区排行榜](assets/benchmark.jpeg) + +数据来源于 [localmaxxing.com](https://localmaxxing.com)（一个社区基准测试数据库）。当你打开该视图时，llmfit 会自动检测你的硬件（GPU 型号、VRAM 层级、Apple Silicon 芯片系列、操作系统）并查询匹配结果。 + +| 列 | 描述 | +|---------------|------------------------------------------------------------| +| **Model** | HuggingFace 模型 ID | +| **Engine** | 使用的推理运行时（llama.cpp、vLLM、Ollama、MLX 等） | +| **Quant** | 量化格式（Q4_K_M、Q8_0 等） | +| **tok/s** | 测量的输出 token 生成速度 | +| **Total t/s** | 总吞吐量（提示词 + 生成） | +| **TTFT** | 首次 token 响应时间（延迟） | +| **VRAM** | 推理期间的峰值内存使用量 | +| **Ctx** | 基准测试中使用的上下文长度 | +| **User** | 提交者（已验证用户标有 `*`） | + +| 按键 | 操作 | +|------------------------|-----------------------------------------| +| `j` / `k` 或方向键 | 浏览结果 | +| `H` | 打开硬件选择器（浏览任何 GPU） | +| `r` | 从 API 刷新 / 重新获取 | +| `b` / `q` / `Esc` | 关闭并返回模型表格 | + +按 `H` 打开硬件选择器 — 一个包含 27 种流行 GPU 和芯片的滚动列表（涵盖 RTX 5090 到纯 CPU、Apple Silicon M1-M4 变体、AMD RX/MI 系列以及 NVIDIA 数据中心显卡）。选择任何一种即可立即加载该硬件的基准测试，即使它不是你当前正在使用的硬件。选择 "My Hardware (auto-detect)" 将切回至你自己的系统。 + +#### API 密钥配置 + +公开的基准测试无需认证即可工作。要获得完全访问权限，请提供你的 [localmaxxing.com](https://localmaxxing.com) API 密钥： ```sh -llmfit fit # table of all models ranked by fit -llmfit recommend --json # top picks as JSON (agent/script consumption) -llmfit info "" # one model: fit analysis, estimate basis, verify commands -llmfit bench # measure real tok/s/TTFT against your running provider -llmfit doctor # hardware detection report for bug reports +# 通过环境变量（推荐） +export LOCALMAXXING_API_KEY="bhk_你的密钥" +llmfit + +# 或通过 CLI 标志 +llmfit --api-key "bhk_你的密钥" ``` -Full reference: [CLI & automation](docs/cli.md). +| 变量 | 描述 | +|---|---| +| `LOCALMAXXING_API_KEY` | localmaxxing.com API 的 Bearer token | + +### 推理基准测试 (`I`) + +按 `I`（大写）打开推理基准测试 (Inference Bench) 视图。这会对你**本地运行的提供商**（Ollama、vLLM 和 MLX）运行**实时推理基准测试**，并通过真实的推理请求测量首次 token 响应时间 (TTFT)、每秒 token 数 (TPS) 和总延迟。 + +与社区排行榜（展示其他用户的众包数据）不同，推理基准测试在你的实际硬件上测试你的实际模型。 + +#### TUI 使用 + +| 按键 | 操作 | +|-----|--------| +| `I` | 打开推理基准测试（自动检测提供商并运行基准测试） | +| `I` (再次) | 在测试视图内重新运行基准测试 | +| `j` / `k` 或方向键 | 浏览模型结果 | +| `Enter` | 打开选中模型的详细视图 | +| `r` | 切换到路由矩阵视图 | +| `q` / `Esc` | 关闭基准测试视图 | + +结果会缓存到 `~/.config/llmfit/bench-cache.json`，在后续打开时可立即加载。 + +#### CLI 使用 + +```sh +# 自动检测提供商并进行基准测试 +llmfit bench + +# 测试所有运行中提供商的所有已发现模型 +llmfit bench --all + +# 通过 Ollama 测试特定模型 +llmfit bench --provider ollama llama3.2 + +# 覆盖端点 URL +llmfit bench --provider ollama --url http://my-server:11434 llama3.2 + +# 覆盖 vLLM 端点 +llmfit bench --provider vllm --url http://localhost:8000 + +# 以 JSON 格式输出（供脚本使用） +llmfit bench --json + +# 运行质量基准测试（用于路由的基于角色的评分） +llmfit bench --quality + +# 输出路由矩阵 +llmfit bench --quality --routing +``` + +#### 环境变量 + +| 变量 | 默认值 | 描述 | +|---|---|---| +| `OLLAMA_HOST` | `http://localhost:11434` | Ollama API 基础 URL | +| `VLLM_PORT` | `8000` | vLLM 服务器端口（被用作 `http://localhost:$VLLM_PORT`） | + +### 主题 + +按 `t` 可在 10 种内置颜色主题间切换。选择会自动保存到 `~/.config/llmfit/theme`，下次启动时恢复。 + +| 主题 | 描述 | +|--------------------------|---------------------------------------------| +| **Default** | llmfit 原始配色 | +| **Dracula** | 深紫色背景搭配柔和色调 | +| **Solarized** | Ethan Schoonover 的 Solarized Dark 配色方案 | +| **Nord** | 极地风格，冷蓝灰色调 | +| **Monokai** | Monokai Pro 暖色语法配色 | +| **Gruvbox** | 复古风格，暖色大地色调 | +| **Catppuccin Latte** | 🌻 浅色主题——和谐的柔和反转配色 | +| **Catppuccin Frappé** | 🪴 低对比度深色——柔和、内敛的美学 | +| **Catppuccin Macchiato** | 🌺 中对比度深色——温柔舒缓的色调 | +| **Catppuccin Mocha** | 🌿 最深的暗色变体——温馨且色彩丰富 | + +### Web 仪表盘 + +当你以非 JSON 模式运行 `llmfit` 时，会自动在后台启动 Web 仪表盘，默认监听 `0.0.0.0:8787`。可在同一网络中的任意浏览器打开： + +``` +http://<你的机器IP>:8787 +``` + +你也可以通过环境变量覆盖主机或端口： + +```sh +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`： + +```sh +llmfit --no-dashboard +``` + +### CLI 模式 + +使用 `--cli` 或任何子命令获取经典表格输出： + +```sh +# 按适配度排序的所有模型表格 +llmfit --cli + +# 仅显示完美适配的模型，前 5 个 +llmfit fit --perfect -n 5 + +# 显示检测到的系统配置 +llmfit system + +# 列出数据库中所有模型 +llmfit list + +# 按名称、提供商或参数量搜索 +llmfit search "llama 8b" + +# 单个模型的详细信息 +llmfit info "Mistral-7B" + +# 前 5 个推荐（JSON 格式，供 agent/脚本使用） +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 相同的适配/评分数据，包括过滤和节点级最优模型选择。 + +```sh +# 健康检查 +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 行为： + +```sh +# 自动启动服务器并运行端点/模式/过滤断言 +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` 覆盖检测到的值： + +```sh +# 覆盖 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 推理对模型评分。在统一内存系统（Apple Silicon）上，`--ram` 同时更新 VRAM；使用 `--memory` 可独立覆盖 VRAM。 + +### 上下文长度上限 + +使用 `--max-context` 限制用于内存估算的上下文长度（不改变每个模型标称的最大上下文）： + +```sh +# 按 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` 获取机器可读输出： + +```sh +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 输出包含以下稳定字段： +- 请求参数（`context`、`quantization`、`target_tps`） +- 估算的最低/推荐硬件 +- 每条路径的可行性（`gpu`、`cpu_offload`、`cpu_only`） +- 升级差距 --- -## How it works +## 工作原理 -llmfit detects your hardware (RAM, CPU, GPU/VRAM, backend), then scores every model in its catalog across four dimensions: memory fit, estimated speed, quality, and context. Speed estimates come from a memory-bandwidth model grounded in runtime sampling and real community measurements — and every estimate ships its inputs, so `llmfit info` shows exactly what a number assumes and how to verify it on your machine. +1. **硬件检测** -- 通过 `sysinfo` 读取总计/可用 RAM，统计 CPU 核心数，并探测 GPU： + - **NVIDIA** -- 通过 `nvidia-smi` 支持多 GPU。聚合所有检测到的 GPU 的 VRAM。如果报告失败，则根据 GPU 型号名称估算 VRAM。 + - **AMD** -- 通过 `rocm-smi` 检测。 + - **Intel Arc** -- 独立显卡通过 sysfs 检测 VRAM，集成显卡通过 `lspci` 检测。 + - **Apple Silicon** -- 通过 `system_profiler` 检测统一内存。VRAM = 系统 RAM。 + - **Ascend** -- 通过 `npu-smi` 检测。 + - **后端检测** -- 自动识别加速后端（CUDA、Metal、ROCm、SYCL、CPU ARM、CPU x86、Ascend）用于速度估算。 -Full detail, including the estimation formulas and the model database: [How llmfit works](docs/how-it-works.md). +2. **模型数据库** -- 数百个模型来源于 HuggingFace API，存储在 `data/hf_models.json` 中并在编译时嵌入。内存需求根据量化层级（Q8_0 到 Q2_K）的参数量计算。VRAM 是 GPU 推理的主要约束；系统 RAM 是纯 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）： + + | 维度 | 衡量内容 | + |------------|------------------------------------------| + | **质量** | 参数量、模型系列声誉、量化惩罚、任务对齐度 | + | **速度** | 基于后端、参数量和量化的预估 tokens/sec | + | **适配度** | 内存利用效率（最佳区间：可用内存的 50-80%） | + | **上下文** | 上下文窗口能力与用途目标的对比 | + + 各维度通过加权合成为综合评分。权重因用途类别而异（通用、编程、推理、对话、多模态、嵌入）。例如，对话类更侧重速度（0.35），推理类更侧重质量（0.55）。模型按综合评分排序，不可运行的模型（Too Tight）始终排在最后。 + +5. **速度估算** -- LLM 推理中的 token 生成受内存带宽限制：每个 token 需要从 VRAM 完整读取一次模型权重。当识别出 GPU 型号时，llmfit 使用其实际内存带宽来估算吞吐量： + + 公式：`(bandwidth_GB_s / model_size_GB) × efficiency_factor` + + 效率因子（0.55）和各模式速度乘数可通过高级配置弹窗（TUI 中的 `A`）进行调整。默认值考虑了内核开销、KV 缓存读取和内存控制器效应。该方法已通过 llama.cpp 的公开基准测试验证（[Apple Silicon](https://github.com/ggml-org/llama.cpp/discussions/4167)、[NVIDIA T4](https://github.com/ggml-org/llama.cpp/discussions/4225)）及实际测量数据。 + + 带宽查找表涵盖约 80 种 GPU，覆盖 NVIDIA（消费级 + 数据中心级）、AMD（RDNA + CDNA）和 Apple Silicon 系列。 + + 对于未识别的 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 不足，溢出到系统 RAM 并使用部分 GPU 卸载。 + - **CPU** -- 无 GPU。模型完全加载到系统 RAM 中。 + + **适配等级：** + - **Perfect（完美）** -- GPU 上满足推荐内存。需要 GPU 加速。 + - **Good（良好）** -- 有余量地装入。MoE 卸载或 CPU+GPU 模式的最佳等级。 + - **Marginal（勉强）** -- 装入紧张，或纯 CPU 运行（纯 CPU 始终封顶在此等级）。 + - **Too Tight（过紧）** -- VRAM 和系统 RAM 均不足。 --- -## Contributing +## 模型数据库 -Contributions are welcome, especially new models. +模型列表由 `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 架构。 -### Before submitting a PR +模型类别涵盖通用、编程（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）。 -Please run `cargo fmt` before pushing your changes. Most CI check failures are caused by unformatted code: +完整列表请参阅 [MODELS.md](MODELS.md)。 + +模型数据库在编译时嵌入，因此**最终用户**通过升级 llmfit 本身来获取更新（`brew upgrade llmfit`、`scoop update llmfit` 或下载更新的发布版本）。以下命令适用于从源码刷新数据库的**贡献者**： + +刷新模型数据库： + +```sh +# 自动更新（推荐） +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 参数解析、入口、TUI 启动 + hardware.rs -- 系统 RAM/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` 已包含所需的元数据（描述、许可证、仓库地址）。发布步骤： + +```sh +# 先进行试运行以发现问题 +cargo publish --dry-run + +# 正式发布（需要 crates.io API token） +cargo login +cargo publish +``` + +发布前请确认： + +- `Cargo.toml` 中的版本号正确（每次发布时递增）。 +- 仓库根目录存在 `LICENSE` 文件。如果缺失请创建： + +```sh +# MIT 许可证： +curl -sL https://opensource.org/license/MIT -o LICENSE +# 或自行编写。Cargo.toml 声明 license = "MIT"。 +``` + +- `data/hf_models.json` 已提交。它在编译时嵌入，必须存在于发布的 crate 中。 + +发布更新： + +```sh +# 递增版本号 +# 编辑 Cargo.toml: version = "0.2.0" +cargo publish +``` + +--- + +## 依赖 + +| Crate | 用途 | +|------------------------|------------------------------------------| +| `clap` | 基于 derive 宏的 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` 环境变量： + +```sh +# 连接到指定 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 与 [llama.cpp](https://github.com/ggml-org/llama.cpp) 集成，在 TUI 和 CLI 中均可作为运行时/下载提供商使用。 + +要求： + +- `llama-cli` 或 `llama-server` 在 `PATH` 中可用（用于运行时检测） +- 需要网络访问 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 内置的模型服务功能。 + +要求： + +- Docker Desktop 已启用 Model Runner +- 默认端点：`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` 环境变量： + +```sh +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` 环境变量： + +```sh +LMSTUDIO_HOST="http://192.168.1.100:1234" llmfit +``` + +### API 认证 + +如果你的 LM Studio 实例启用了**Require API Key**（访问 MCP 服务器需要），请设置 `LMSTUDIO_API_KEY` 环境变量以在所有请求中提供 Bearer token： + +```sh +export LMSTUDIO_API_KEY="你的-api-key" +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` | 精确的独立 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`、`--ram` 或 `--cpu-cores` 覆盖（参见上方[硬件覆盖](#硬件覆盖)）。 + +### Android / Termux 说明 + +在 **Termux + PRoot** 等 Android 环境中，llmfit 通常无法通过标准 Linux 检测路径（`nvidia-smi`、`rocm-smi`、DRM/sysfs、`lspci` 等）检测到移动 GPU。在这些环境中，"未检测到 GPU"是当前实现的预期行为。 + +如果你仍希望在统一内存的手机或平板上获得 GPU 风格的推荐，可使用手动内存覆盖： + +```sh +llmfit --memory=8G fit -n 20 +llmfit recommend --json --memory=8G --limit 10 +``` + +这仅是推荐/评分的变通方案；不提供真正的 Android GPU 运行时检测。 + +--- + +## 贡献 + +欢迎贡献，特别是添加新模型。 + +### 提交 PR 前 + +在推送更改前，请运行 `cargo fmt`。大多数 CI 检查失败都是由于未格式化的代码引起的： ```sh cargo fmt ``` -Guides for adding models — locally (no rebuild) or to the built-in catalog: [Custom models](docs/custom-models.md). +### 添加模型 + +1. 在 `scripts/scrape_hf_models.py` 的 `TARGET_MODELS` 列表中添加模型的 HuggingFace 仓库 ID（例如 `meta-llama/Llama-3.1-8B`）。 +2. 如果模型有访问限制（需要 HuggingFace 身份验证才能访问元数据），在同一脚本的 `FALLBACKS` 列表中添加包含参数量和上下文长度的回退条目。 +3. 运行自动更新脚本： + ```sh + 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) 查看架构详情。 --- -## Alternatives +## OpenClaw 集成 -If you're looking for a different approach, check out [llm-checker](https://github.com/Pavelevich/llm-checker) -- a Node.js CLI tool with Ollama integration that can pull and benchmark models directly. It takes a more hands-on approach by actually running models on your hardware via Ollama, rather than estimating from specs. Good if you already have Ollama installed and want to test real-world performance. Note that it doesn't support MoE (Mixture-of-Experts) architectures -- all models are treated as dense, so memory estimates for models like Mixtral or DeepSeek-V3 will reflect total parameter count rather than the smaller active subset. +llmfit 作为 [OpenClaw](https://github.com/openclaw/openclaw) 技能提供，让 agent 能够推荐适合硬件的本地模型，并自动配置 Ollama/vLLM/LM Studio 提供商。 + +### 安装技能 + +```sh +# 从 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) 查看完整技能定义。 --- -## Code signing +## 替代方案 -llmfit's Windows release binaries are digitally signed (Authenticode) via [SignPath.io](https://about.signpath.io/), with a free code signing certificate provided by the [SignPath Foundation](https://signpath.org/). - -Signing happens automatically in the [release pipeline](.github/workflows/release.yml): only artifacts built by GitHub Actions from this repository are submitted for signing, and signing requests are approved by the project maintainer ([@AlexsJones](https://github.com/AlexsJones)). - -**Code signing policy:** see the [SignPath Foundation code signing policy and terms](https://signpath.org/terms). - -**Privacy:** this program will not transfer any information to other networked systems unless specifically requested by the user or the person installing or operating it. llmfit only contacts external services when you explicitly use the corresponding feature (e.g. model downloads, runtime provider queries, or the community leaderboard). +如果你在寻找不同的方案，可以看看 [llm-checker](https://github.com/Pavelevich/llm-checker) -- 一个带有 Ollama 集成的 Node.js CLI 工具，可以直接拉取和基准测试模型。它采用更直接的方式，通过 Ollama 在你的硬件上实际运行模型，而不是从配置参数估算。如果你已安装 Ollama 并想测试真实性能，这是个不错的选择。注意它不支持 MoE（混合专家）架构 -- 所有模型都被视为密集模型，因此 Mixtral 或 DeepSeek-V3 等模型的内存估算将反映总参数量而非较小的活跃子集。 --- -## License +## 代码签名 + +llmfit 的 Windows 发布二进制文件通过 [SignPath.io](https://about.signpath.io/) 进行数字签名（Authenticode），代码签名证书由 [SignPath Foundation](https://signpath.org/) 免费提供。 + +签名在[发布流水线](.github/workflows/release.yml)中自动完成：只有由 GitHub Actions 从本仓库构建的产物才会提交签名，签名请求由项目维护者（[@AlexsJones](https://github.com/AlexsJones)）审批。 + +**代码签名政策：**参见 [SignPath Foundation 代码签名政策与条款](https://signpath.org/terms)。 + +**隐私：**除非用户或安装/运行本程序的人员明确请求，本程序不会向其他联网系统传输任何信息。llmfit 仅在你明确使用相应功能时才会访问外部服务（例如模型下载、运行时提供商查询或社区排行榜）。 + +--- + +## 许可证 MIT + +--- + +*本文档由 [@JasonYeYuhe](https://github.com/JasonYeYuhe) 翻译并维护。如果您发现任何翻译问题或需要增加新特性说明，欢迎提交 Issue 或与我联系。* \ No newline at end of file