local-llmup 详细部署教程

local-llmup 是一个硬件感知的命令行工具和交互式终端界面 (TUI)，它能帮助你在本地机器上发现、评估、安装、运行和迁移大型语言模型 (LLM)。它的核心价值在于，在您下载任何模型之前，就能根据您的具体硬件配置，给出“能运行 / 较慢 / 不能运行”的明确结论，并估算每秒可处理的令牌数 (tok/s)。

本教程将指导您从安装到日常使用的完整过程。

1. 准备工作

1.1 核心要求

Node.js: 版本 18 或更高。
网络: 安装和下载模型时需要网络连接。但硬件评估和建议功能完全离线工作。
后端 (Backend): local-llmup 本身不运行模型，它需要调用以下至少一个后端。推荐安装 Ollama。
- Ollama (推荐，全平台支持): 从 ollama.com 下载安装。
- llama.cpp (全平台支持): 可通过 brew install llama.cpp (macOS) 等方式安装。
- MLX (仅限 Apple Silicon Mac): 通过 pip install "mlx-lm==0.31.3" 安装。
- LM Studio (全平台): 用户需自行管理其服务器，local-llmup 仅负责连接。

1.2 了解工作流程

工具的核心工作流如下：

评估 (recommend 或 can-run)：分析您的硬件 (CPU/GPU/内存)，判断哪些模型能运行。
安装并启动 (up)：下载选定的模型，验证文件完整性，并启动一个本地服务器。
对话 (chat)：通过命令行或浏览器界面与模型进行交互。
迁移 (migrate)：将当前对话的记忆迁移到另一个模型上，方便无缝切换。

2. 安装

2.1 使用 npm 全局安装 (推荐)

1	npm install -g local-llmup

安装后，您可以在任何目录下使用 local-llmup 命令。

2.2 无需安装直接运行

如果您不想全局安装，可以使用 npx 直接运行：

1	npx local-llmup

2.3 使用 Docker (体验/测试)

项目也提供了 Docker 镜像，但请注意容器内的硬件检测可能无法准确反映宿主机状态。

1 2	docker pull ghcr.io/shashankswe2020-ux/local-llmup:latest docker run --rm ghcr.io/shashankswe2020-ux/local-llmup:latest

建议: 对于准确的硬件推荐，直接使用 npm 安装而非 Docker。

3. 快速开始

3.1 第一步：评估您的硬件和可运行的模型

运行以下命令，工具会分析您的机器并列出所有推荐模型及其运行状态：

1	local-llmup

您会看到类似如下的输出，每个模型都有明确的 yes / slow / no 判定和预估速度：

Rank  Model               Verdict  Est. tok/s  Score  Backends
1     qwen3:14b           yes      45-85       0.92   ollama, llamacpp
2     llama3.1:8b         yes      30-50       0.85   ollama, llamacpp
3     qwen3:30b-a3b       slow     8-15        0.78   ollama, llamacpp
4     llama3.1:70b        no       -            -      -

3.2 第二步：检查特定模型

您也可以直接询问某个具体模型能否运行：

1	local-llmup can-run llama3.1:8b

3.3 第三步：启动您的第一个模型

选择一个判定为 yes 的模型，使用 up 命令拉取、验证并启动它：

1	local-llmup up qwen3:14b

验证: 工具会自动验证下载文件的 SHA-256 完整性，确保文件未被篡改。
安全: 启动的服务器默认只绑定在本地回环地址 127.0.0.1，不会暴露到网络。

3.4 第四步：开始对话

模型启动后，您可以直接在终端中与其对话：

1	local-llmup chat

您输入的所有内容都会作为对话历史被记录下来，方便后续迁移。

3.5 第五步：停止模型

当您使用完毕后，可以停止当前正在运行的模型服务器：

1	local-llmup down

4. 核心功能与高级用法

4.1 交互式终端界面 (TUI)

直接输入 local-llmup 并回车，在支持的终端（≥60列，≥16行）中会自动启动一个可视化的交互界面。

键盘导航: 使用 ↑/↓ 或 j/k 在模型列表中移动，按 / 键搜索，按 m 键标记模型进行比较，按 c 键查看对比详情。
核心信息: 您可以看到模型的详细评估、预估吞吐量和硬件瓶颈。
辅助模式: 为屏幕阅读器用户提供了 --accessible 标志。

4.2 浏览器图形界面 (GUI)

如果您更喜欢可视化操作，可以启动一个本地 Web 界面：

1	local-llmup gui

它会在您的默认浏览器中打开一个地址为 127.0.0.1 的本地 AI 工作区。您可以在这里浏览模型、一键启动、调整上下文窗口大小，并与模型进行对话。所有操作均通过本地回环进行，数据不会离开您的机器。

4.3 迁移对话记忆

local-llmup 最强大的功能之一是可以将对话记忆从一个模型迁移到另一个模型。这对于尝试不同模型但不想丢失当前对话上下文非常有用：

# 先迁移记忆
local-llmup migrate --from llama3.1:8b --to qwen3:14b
# 然后切换到新模型
local-llmup switch qwen3:14b

4.4 脚本化与 CI/CD 集成

工具支持 --json 输出格式和明确的退出码，方便集成到脚本中：

# 在 CI 脚本中用作门控
if local-llmup can-run llama3.1:8b --json | grep -q '"verdict":"yes"'; then
  echo "Model can run, proceeding..."
else
  echo "Model cannot run on this hardware."
fi

can-run 命令在判定为 yes 或 slow 时退出码为 0，no 时为 1。

5. 配置与运维参考

5.1 环境变量与全局选项

您可以通过全局选项来控制工具行为，例如：

--task <任务>: 根据任务（如 chat, code, vision）优化模型推荐排序。
--context <令牌数>: 指定上下文窗口大小并重新评估模型。在 GUI 中可直接选择 Low/Mid/High/Max 预设。
--backend <名称>: 限定只使用特定后端（如 --backend ollama）。
--json: 以纯 JSON 格式输出结果，便于解析。

5.2 查看硬件诊断

运行 doctor 命令可以获取详细的硬件诊断和 AI 硬件评分 (0-100)：

1	local-llmup doctor

它会给出 VRAM、RAM、计算能力和存储的细分瓶颈分析。

5.3 更新与目录管理

更新工具：npm update -g local-llmup
查看已下载模型：local-llmup ls

6. 故障排查

问题	解决方案
`up` 命令因大小不匹配失败	重新运行命令，通常是下载中断导致的。
提示 `ollama is not installed`	安装 Ollama (或选择其他后端)。评估和建议功能无需后端。
吞吐量显示 `unknown`	您的硬件带宽信息不在项目内置数据集中。您仍可依据 `yes/slow/no` 判断运行可行性。
TUI 界面不渲染	检查终端窗口是否大于 60 列、16 行。在非 TTY 环境（如管道）或使用 `--no-tui` 标志会回退到纯文本模式。
KV 缓存显示 `unknown`	该模型的注意力机制架构信息不在内置数据集中，因此无法精确计算上下文内存占用。