local-models

local-models

llama.cpp を通じてローカルの LLM にすばやくアクセスできます。Ollama がすでにダウンロード済みの GGUF モデルを再利用するため、テキストと埋め込みでは再ダウンロードは不要です。すべてマシン上で実行されるため、API キーもネットワークもトークンごとの料金も必要ありません。

このスキルを使う場面

次のようなタスクでは、クラウド API の代わりにローカルモデルを使います。

• プライバシーが重要な場合 — PII のマスキング、個人的なメモや健康データ、機密情報に近いテキストの処理などです。データがマシンの外に出ることはありません。
• オフラインの場合 — ネットワークを利用できない場合や、ユーザーがローカルのみでの処理を明示的に希望している場合です。
• 大量処理で、精度がそれほど重要でない場合 — 小規模モデルで十分な数百件の分類やタグ付けなどです。クラウドのコストや遅延が積み重なる場合に適しています。
• 手早く済ませる使い捨ての処理 — ちょっとした要約、翻訳、「これは何か」といった確認など、最先端モデルとのやり取りが過剰な場合です。

高度な推論、長いコンテキスト、丁寧なコーディング、高い精度が必要なタスクでは、最先端の 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（最大トークン数）、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 を取得してください。デフォルトが gemma3 ではなく qwen なのはこのためです。
• 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 CLI や任意の OpenAI クライアントから接続する方法）、さらに llama-embedding を使ったローカル埋め込み／RAG のパターンを説明します。

要件

• llama.cpp をインストール済みであること（brew install llama.cpp）。llama-completion、 llama-mtmd-cli、llama-embedding、llama-server がインストールされます。
• Ollama と、ダウンロード済みのモデルが少なくとも 1 つ必要です（ブロブ再利用方式を使う場合）。リゾルバーには python3 が必要です。API キーは不要です。