local-models

local-models

通过 llama.cpp 快速使用本地大模型，复用 Ollama 已拉取的 GGUF 模型（文本和嵌入无需重新下载）。所有操作都在本机运行——无需 API 密钥、无需网络，也没有按 token 计费。

何时使用此技能

遇到以下任务时，请优先使用本地模型，而不是云端 API：

• 对隐私敏感——清除个人身份信息、处理个人笔记、健康数据或涉及机密的文本。数据不会离开本机。
• 离线——没有网络，或用户明确要求仅在本地运行。
• 高频量 / 低风险——对数百个项目进行分类或添加标签，小模型已经够用，而云端成本和延迟会不断累积。
• 快速临时处理——快速摘要、翻译或“这是什么”，为此调用顶尖模型未免小题大做。

如果任务需要强大的推理能力、长上下文、严谨的代码或高准确度，请优先使用顶尖模型（Claude）——这些本地模型都很小（0.6–4B）。

核心技巧：复用 Ollama 的模型

Ollama 会将模型权重存储为没有扩展名的 GGUF 文件，位于 ~/.ollama/models/blobs/ 下。这些都是普通的 GGUF 文件，可以直接由 llama.cpp 加载。scripts/ollama_blob.py 会读取 Ollama 的清单，并将易读的名称（例如 qwen2.5:3b）解析为对应的权重文件路径。无需转换，也无需重复下载。

用法

入口是 scripts/lm。运行 scripts/lm help 查看完整列表。使用绝对路径调用，例如 ~/ai_projects/claude-skills/local-models/scripts/lm。

lm models                       # list local models (text / vision / embed)
lm ask [MODEL] "PROMPT"         # one-shot prompt (default qwen2.5:3b)
lm chat [MODEL]                 # interactive REPL

# Text presets — accept a file path, inline text, OR stdin:
lm summarize  report.md
cat notes.txt | lm tldr
lm keywords   article.txt
lm anonymize  transcript.txt         # → [NAME] [EMAIL] [PHONE] [ADDRESS] ...
lm proofread  draft.md
lm translate  German "Good morning"
lm classify   "praise,complaint,question"  feedback.txt   # → one label
lm extract    "invoice_number, total, due_date"  invoice.txt   # → JSON

# Vision (downloads model+projector once via HuggingFace — see note below):
lm describe-image photo.jpg
lm tag-image      screenshot.png
lm vision photo.jpg "What brand is the shoe?"

# Embeddings & serving:
lm embed "text to embed"             # → OpenAI-style JSON vector
lm serve qwen2.5:3b 8080             # OpenAI-compatible server on :8080

输出简洁（仅包含答案）——封装脚本会以单轮模式运行 llama-completion，并移除聊天模板框架内容和 llama.cpp 日志。

选择模型

默认设置经过调优，可提供简洁快速的输出，也可按次调用覆盖：

• 通用文本预设 → qwen2.5:3b（LM_TEXT_MODEL）
• 分类 / 提取 → qwen2.5:3b（LM_REASON_MODEL），温度设为 0
• 嵌入 → jeffh/intfloat-multilingual-e5-large:f16（LM_EMBED_MODEL）
• 其他环境变量：LM_NTOK（最大 token 数）、LM_VISION_HF（视觉仓库）、LM_DEBUG=1（显示 llama.cpp 日志）

在 ask/chat/embed/serve 的第一个参数中传入指定模型 （例如 lm ask qwen3:4b "..."）。

重要注意事项

• Ollama 的 gemma3 GGUF 无法在原版 llama.cpp 中加载。 加载会失败，并提示 key not found in model: gemma3.attention.layer_norm_rms_epsilon，因为 Ollama 写入了主线 llama.cpp 不会读取的自定义元数据键。请改用 qwen* 模型，或通过 -hf 拉取社区制作的 gemma3 GGUF。因此默认模型是 qwen，而不是 gemma3。
• qwen3:4b 会在答案前输出 `` 推理块。 用于 ask/chat 没问题，但会污染预设输出（JSON、标签）——为避免这种情况，预设默认使用 qwen2.5:3b。
• 视觉模型没有可复用的 Ollama 文件。 Ollama 没有为 qwen2.5vl 存储 mmproj （视觉投影器），而 llama.cpp 需要该文件。因此视觉命令会使用 llama-mtmd-cli -hf ggml-org/Qwen2.5-VL-3B-Instruct-GGUF，首次使用时会将模型和投影器（约 2–3 GB）下载到 ~/.cache/llama.cpp，之后可离线运行。首次进行视觉调用前，请告知用户。
• 每次单次调用都会重新加载模型（这些小模型需要几秒钟）。如果要连续调用多次，请通过 lm serve 启动一次服务，然后访问 http://localhost:8080/v1/chat/completions——详见 references/serving-and-embeddings.md。

参考资料

• references/serving-and-embeddings.md — 将 llama-server 作为兼容 OpenAI 的端点运行（并让 llm 命令行工具或任何 OpenAI 客户端连接到该端点），以及使用 llama-embedding 实现本地嵌入 / RAG 的模式。

要求

• 已安装 llama.cpp（brew install llama.cpp）——提供 llama-completion、 llama-mtmd-cli、llama-embedding、llama-server。
• 已安装 Ollama，且至少拉取了一个模型（用于复用文件的路径）。解析器需要 python3。无需 API 密钥。