llmfit 硬件模型匹配器

技能来自 ara.so — 每日 2026 技能合集。

llmfit 检测你的系统内存、CPU 和 GPU，然后对数百个 LLM 模型进行质量、速度、适配度和上下文维度评分——准确地告诉你哪些模型可以在你的硬件上良好运行。它附带一个交互式 TUI 和一个 CLI，支持多 GPU、MoE 架构、动态量化以及本地运行时提供商（Ollama、llama.cpp、MLX、Docker Model Runner）。

安装

macOS / Linux (Homebrew)

brew install llmfit

快速安装脚本

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

# 不使用 sudo，安装到 ~/.local/bin
curl -fsSL https://llmfit.axjns.dev/install.sh | sh -s -- --local

Windows (Scoop)

scoop install llmfit

Docker / Podman

docker run ghcr.io/alexsjones/llmfit

# 使用 jq 进行脚本处理
podman run ghcr.io/alexsjones/llmfit recommend --use-case coding | jq '.models[].name'

从源码安装 (Rust)

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

核心概念

• 适配等级：perfect（运行极佳）、good（运行良好）、marginal（可运行但紧张）、too_tight（无法运行）
• 评分维度：质量、速度（tok/s 估算）、适配度（内存余量）、上下文容量
• 运行模式：GPU、CPU+GPU 卸载、仅 CPU、MoE
• 量化：自动为你的硬件选择最佳量化方案（例如 Q4_K_M、Q5_K_S、mlx-4bit）
• 提供商：Ollama、llama.cpp、MLX、Docker Model Runner

主要命令

启动交互式 TUI

llmfit

CLI 表格输出

llmfit --cli

显示系统硬件检测

llmfit system
llmfit --json system   # JSON 输出

列出所有模型

llmfit list

搜索模型

llmfit search "llama 8b"
llmfit search "mistral"
llmfit search "qwen coding"

适配度分析

# 所有可运行模型按适配度排序
llmfit fit

# 仅完美适配模型，前 5 个
llmfit fit --perfect -n 5

# JSON 输出
llmfit --json fit -n 10

模型详情

llmfit info "Mistral-7B"
llmfit info "Llama-3.1-70B"

推荐

# 前 5 个推荐（默认 JSON）
llmfit recommend --json --limit 5

# 按用例过滤：general, coding, reasoning, chat, multimodal, embedding
llmfit recommend --json --use-case coding --limit 3
llmfit recommend --json --use-case reasoning --limit 5

硬件规划（反向：我需要什么硬件？）

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
llmfit plan "Qwen/Qwen2.5-Coder-0.5B-Instruct" --context 8192 --json

REST API 服务器（用于集群调度）

llmfit serve
llmfit serve --host 0.0.0.0 --port 8787

硬件覆盖

当自动检测失败时（虚拟机、损坏的 nvidia-smi、直通设置）：

# 覆盖 GPU VRAM
llmfit --memory=32G
llmfit --memory=24G --cli
llmfit --memory=24G fit --perfect -n 5
llmfit --memory=24G recommend --json

# 兆字节
llmfit --memory=32000M

# 适用于任何子命令
llmfit --memory=16G info "Llama-3.1-70B"

可接受的后缀：G/GB/GiB、M/MB/MiB、T/TB/TiB（不区分大小写）。

上下文长度限制

# 估算 4K 上下文下的内存适配度
llmfit --max-context 4096 --cli

# 与子命令一起使用
llmfit --max-context 8192 fit --perfect -n 5
llmfit --max-context 16384 recommend --json --limit 5

# 环境变量替代方案
export OLLAMA_CONTEXT_LENGTH=8192
llmfit recommend --json

REST API 参考

启动服务器：

llmfit serve --host 0.0.0.0 --port 8787

端点

# 健康检查
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 的查询参数

脚本与自动化示例

Bash：以 JSON 格式获取最佳编程模型

#!/bin/bash
# 获取完美适配的前 3 个编程模型
llmfit recommend --json --use-case coding --limit 3 | \
  jq -r '.models[] | "\(.name) (\(.score)) - \(.quantization)"'

Bash：检查特定模型是否适配

#!/bin/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 将运行良好 (适配度: $FIT)"
else
  echo "$MODEL 可能无法良好运行 (适配度: $FIT)"
fi

Bash：自动拉取最佳 Ollama 模型

#!/bin/bash
# 获取最佳适配模型名称并使用 Ollama 拉取
TOP_MODEL=$(llmfit recommend --json --limit 1 | jq -r '.models[0].name')
echo "正在拉取: $TOP_MODEL"
ollama pull "$TOP_MODEL"

Python：查询 REST API

import requests

BASE_URL = "http://localhost:8787"

def get_system_info():
    resp = requests.get(f"{BASE_URL}/api/v1/system")
    return resp.json()

def get_top_models(use_case="coding", limit=5, min_fit="good"):
    params = {
        "use_case": use_case,
        "limit": limit,
        "min_fit": min_fit,
        "sort": "score"
    }
    resp = requests.get(f"{BASE_URL}/api/v1/models/top", params=params)
    return resp.json()

def search_models(query, runtime="any"):
    resp = requests.get(
        f"{BASE_URL}/api/v1/models/{query}",
        params={"runtime": runtime}
    )
    return resp.json()

# 使用示例
system = get_system_info()
print(f"GPU: {system.get('gpu_name')} | VRAM: {system.get('vram_gb')}GB")

models = get_top_models(use_case="reasoning", limit=3)
for m in models.get("models", []):
    print(f"{m['name']}: score={m['score']}, fit={m['fit']}, quant={m['quantization']}")

Python：面向代理的硬件感知模型选择器

import subprocess
import json

def get_best_model_for_task(use_case: str, min_fit: str = "good") -> dict:
    """使用 llmfit 为给定任务选择最佳模型。"""
    result = subprocess.run(
        ["llmfit", "recommend", "--json", "--use-case", use_case, "--limit", "1"],
        capture_output=True,
        text=True
    )
    data = json.loads(result.stdout)
    models = data.get("models", [])
    return models[0] if models else None

def plan_hardware_requirements(model_name: str, context: int = 4096) -> dict:
    """获取运行特定模型的硬件要求。"""
    result = subprocess.run(
        ["llmfit", "plan", model_name, "--context", str(context), "--json"],
        capture_output=True,
        text=True
    )
    return json.loads(result.stdout)

# 选择最佳编程模型
best = get_best_model_for_task("coding")
if best:
    print(f"最佳编程模型: {best['name']}")
    print(f"  量化方案: {best['quantization']}")
    print(f"  估算 tok/s: {best['tps']}")
    print(f"  内存使用率: {best['mem_pct']}%")

# 规划特定模型的硬件需求
plan = plan_hardware_requirements("Qwen/Qwen3-4B-MLX-4bit", context=8192)
print(f"所需最小 VRAM: {plan['hardware']['min_vram_gb']}GB")
print(f"推荐 VRAM: {plan['hardware']['recommended_vram_gb']}GB")

Docker Compose：节点调度器模式

version: "3.8"
services:
  llmfit-api:
    image: 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  # 透传 GPU

TUI 按键参考

主题

t 循环：默认 → Dracula → Solarized → Nord → Monokai → Gruvbox
主题保存到 ~/.config/llmfit/theme

GPU 检测详情

常见模式

“我的 16GB M2 Mac 能运行什么？”

llmfit fit --perfect -n 10
# 或交互式
llmfit
# 按 'f' 筛选到完美适配

“我有一块 3090（24GB VRAM），哪些编程模型适配？”

llmfit recommend --json --use-case coding | jq '.models[]'
# 如果检测失败，手动覆盖
llmfit --memory=24G recommend --json --use-case coding

“Llama 70B 能在我的机器上运行吗？”

llmfit info "Llama-3.1-70B"
# 规划你需要的硬件
llmfit plan "Llama-3.1-70B" --context 4096 --json

“只显示 Ollama 中已安装的模型”

llmfit
# 按 'a' 循环到已安装筛选器
# 或
llmfit fit -n 20  # 运行后，在 TUI 中按 'i' 进行已安装优先排序

“脚本：找到最佳模型并启动 Ollama”

MODEL=$(llmfit recommend --json --limit 1 | jq -r '.models[0].name')
ollama serve &
ollama run "$MODEL"

“API：为集群调度器轮询节点能力”

# 检查节点，获取前 3 个良好+推理模型
curl -s "http://node1:8787/api/v1/models/top?limit=3&min_fit=good&use_case=reasoning" | \
  jq '.models[].name'

故障排除

GPU 未检测到 / 报告的 VRAM 错误

# 验证检测
llmfit system

# 手动覆盖
llmfit --memory=24G --cli

未找到 nvidia-smi 但你有 NVIDIA GPU

# 安装 CUDA 工具包或 nvidia-utils，然后重试
# 或手动覆盖：
llmfit --memory=8G fit --perfect

模型显示为 too_tight 但你有足够的内存

# llmfit 可能使用了上下文放大的估算；限制上下文
llmfit --max-context 2048 fit --perfect -n 10

REST API：测试端点

# 启动服务器并运行验证套件
python3 scripts/test_api.py --spawn

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

Apple Silicon：VRAM 显示为系统内存（符合预期）

# 这是正确的——Apple Silicon 使用统一内存
# llmfit 会自动处理此情况
llmfit system  # 应显示后端：Metal

上下文长度环境变量

export OLLAMA_CONTEXT_LENGTH=4096
llmfit recommend --json  # 使用 4096 作为上下文上限