llmfit 详细部署与使用教程

llmfit 是一个强大的命令行工具，它能自动检测你的硬件配置（CPU、内存、GPU 及显存），然后从数百个开源大语言模型中，精准推荐最适合你设备运行的模型及量化版本。本教程将指导你完成安装、配置和基本使用。

一、 安装前准备

llmfit 是一个单一二进制文件，无运行时依赖，安装非常轻量。

1. 系统要求

  • 操作系统: Linux (x86_64, aarch64), macOS (Intel, Apple Silicon), 或 Windows (x86_64)。
  • 可选依赖: 为了获得更精确的 GPU 检测，建议安装对应驱动工具。
    • NVIDIA: nvidia-smi
    • AMD: rocm-smi
    • Intel Arc: sysfs, lspci
    • Apple Silicon: system_profiler (系统内置)

注意：llmfit 本身占用资源极少 (~10 MB 磁盘，<50 MB 内存)。如果自动检测硬件失败，可以手动指定参数，例如 llmfit --memory=24G。

二、 安装方式

根据你的操作系统，选择一种最适合的安装方法。

操作系统 推荐方式 安装命令
macOS / Linux 快速安装脚本 `curl -fsSL https://llmfit.axjns.dev/install.sh
Homebrew brew install llmfit
Windows Scoop scoop install llmfit
通用 uv / pip uv tool install -U llmfit
从源码编译 需要 Rust，见下文

从源码编译 (所有平台)

如果你需要最新的开发版或没有包管理器：

1
2
3
4
5
git clone https://github.com/AlexsJones/llmfit.git
cd llmfit
cargo build --release
# 将编译好的二进制文件移动到系统 PATH 路径下
sudo mv target/release/llmfit /usr/local/bin/

安装完成后，运行 llmfit --version 验证是否成功。

三、 基本使用方法

1. 启动交互式终端界面 (TUI)

这是 llmfit 最核心、最直观的用法。在终端直接输入命令即可启动：

1
llmfit

TUI 界面会清晰展示你的硬件规格，以及所有模型针对你硬件的适配度、预估速度 (tok/s)、内存占用等评分。

TUI 关键快捷键：

  • Tab / Shift+Tab: 切换标签页 (模型、系统信息、基准测试)
  • ↑ / ↓ 或 j / k: 上下浏览模型列表
  • /: 过滤/搜索模型
  • d: 下载选中的模型 (支持 Ollama, llama.cpp 等)
  • r: 刷新已安装的模型列表
  • p: 进入“计划模式”，估算运行特定模型所需的硬件
  • S: 进入“硬件模拟”模式，自由调整硬件参数进行规划
  • q: 退出

2. 命令行 (CLI) 模式

适用于脚本、自动化或快速查询。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 显示硬件信息和所有推荐模型 (表格输出)
llmfit fit

# 只显示完美适配的模型，并限制输出前 5 个
llmlit fit --perfect -n 5

# 输出 JSON 格式，便于程序解析
llmfit recommend --json

# 查看详细的硬件检测报告
llmfit system

# 搜索特定模型 (如 Llama)
llmfit search "llama"

四、 部署为服务：Web UI 与 API 服务器

llmfit 可以以服务器模式运行，提供 Web 仪表盘和 REST API，方便远程访问或集成到其他系统。

1. 启动服务

1
2
3
4
5
# 默认监听 0.0.0.0:8787
llmfit serve

# 指定端口和主机
llmfit serve --host 127.0.0.1 --port 8080

2. 使用 Docker 部署

项目提供了多架构 Docker 镜像，可以快速部署为服务。

启动 Web UI / API 服务器:

1
docker run -d -p 8787:8787 ghcr.io/alexsjones/llmfit serve

启动交互式 TUI (需要 -it 参数):

1
docker run -it --rm ghcr.io/alexsjones/llmfit --tui

使用 Docker Compose (生产环境推荐):

1
2
3
4
5
6
7
8
services:
  llmfit:
    image: ghcr.io/alexsjones/llmfit:latest
    container_name: llmfit
    restart: unless-stopped
    command: ["serve", "--host", "0.0.0.0", "--port", "8787"]
    ports:
      - "8787:8787"

启动后，在浏览器访问 http://<你的机器IP>:8787 即可使用 Web 仪表盘。

五、 进阶配置与扩展

1. 自定义模型数据库

你可以添加项目官方尚未收录的模型，无需重新编译。

在 llmfit 的数据目录下创建 custom_models.json 文件：

  • Linux: ~/.local/share/llmfit/custom_models.json
  • macOS: ~/Library/Application Support/llmfit/custom_models.json
  • Windows: %APPDATA%\llmfit\custom_models.json

文件格式为 JSON 数组，示例如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
[
  {
    "name": "my-org/My-Model-7B",
    "provider": "my-org",
    "parameter_count": "7B",
    "min_ram_gb": 5.0,
    "recommended_ram_gb": 8.0,
    "min_vram_gb": 5.0,
    "quantization": "Q4_K_M",
    "context_length": 32768,
    "use_case": "General chat"
  }
]

2. 与 Ollama 等运行时联动

llmfit 能检测已安装的 Ollama、llama.cpp 等后端。

  • 下载模型: 在 TUI 中选中模型后按 d 键，可自动调用 Ollama 等工具下载。
  • 刷新状态: 在 TUI 中按 r 键，可刷新从运行时检测到的已安装模型列表。

六、 常见问题

1. GPU 或显存检测不到/不准确

现象：在 TUI 或 llmfit system 中看不到 GPU 信息。
解决方法：

  • 确保已安装对应 GPU 的驱动和检测工具 (nvidia-smi 等)。
  • 使用命令行参数手动覆盖：llmfit --memory=24G。

2. 在 Android/Termux 上无法检测 GPU

说明：在 Termux 等环境中，llmfit 通常无法看到移动 GPU，这属于预期行为。
解决方法：使用手动内存覆盖模式获得推荐，如 llmfit --memory=8G fit -n 20。

3. TUI 界面操作困惑

说明：TUI 使用 Vim-style 模式。
解决方法：在 TUI 中按 h 键，可以随时打开帮助弹窗查看所有快捷键绑定。