Unsloth でローカル LLM を Claude Code と連携させる方法

AI

Unsloth でローカル LLM を Claude Code と連携させる方法

概要

このガイドは、オープンソースの LLM と API を完全にローカル環境で Claude Code に接続する方法をステップバイステップで説明しています。Qwen3.5、DeepSeek、Gemma などのオープンモデルを使用して実行できます。

使用される主なモデル

Qwen3.5-35B-A3B

  • 特徴: 2026 年 3 月時点で最も強力な 35B MoE アージェント＆コーディングモデル
  • 要件: 24GB RAM/ユニファイドメモリデバイスで動作
  • 用途: Unsloth を使用した LLM の自動ファインチューニング
  • 代替モデル:
  • Qwen3.5-27B: よりスマートなモデルが必要場合、または VRAM が不足している場合（ただし 35B より約 2 倍遅い）
  • Qwen3.5-9B/4B/2B: 他のバリアント
  • Qwen3-Coder-Next: VRAM が十分な場合の素晴らしい選択肢

GLM-4.7-Flash

  • 同様に強力なモデルで、Qwen3.5 と同じワークフローで使用可能

Unsloth Dynamic GGUFs について

モデルの量子化には Unsloth Dynamic GGUFs を使用します。これにより、精度を可能な限り維持しながら、任意の LLM を量子化して実行できます。

第一部分：LLM セットアップチュートリアル

前提条件：llama.cpp のインストール

llama.cpp は、Mac、Linux、Windows などのデバイスで LLM を実行するためのオープンソースフレームワークです。llama-server を使用して LLM を効的に提供・展開できます。モデルはポート 8001 で提供され、すべてのエージェントツールが単一の OpenAI 互換エンドポイントを通過します。

llama.cpp インストール手順

apt-get update
apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev git-all -y
git clone https://github.com/ggml-org/llama.cpp
cmake llama.cpp -B llama.cpp/build \
    -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-cli llama-mtmd-cli llama-server llama-gguf-split
cp llama.cpp/build/bin/llama-* llama.cpp

重要設定:
– GPU がない場合: -DGGML_CUDA=ON を -DGGML_CUDA=OFF に変更
– Apple Mac / Metal デバイス: -DGGML_CUDA=OFF を設定（Metal サポートはデフォルトで有効）

Qwen3.5 詳細セットアップ

ステップ 1: モデルのダウンロード

Python の huggingface_hub を使用してモデルをダウンロードします（pip install huggingface_hub hf_transfer でインストール）。

最適な量子化: UD-Q4_K_XL（サイズと精度の最適なバランス）

hf download unsloth/Qwen3.5-35B-A3B-GGUF \
    --local-dir unsloth/Qwen3.5-35B-A3B-GGUF \
    --include "*UD-Q4_K_XL*"  # 2 ビット量子化の場合："*UD-Q2_K_XL*"

Unsloth GGUF モデルカタログ: https://unsloth.ai/docs/get-started/unsloth-model-catalog

ステップ 2: llama-server の起動

Qwen3.5 をエージェントワークロード用に展開する場合、llama-server を使用します。

Qwen3.5 のサンプリングパラメータ（Thinking モード）:
– --temp 0.6
– --top-p 0.95
– --top-k 20
– --min-p 0.00

./llama.cpp/llama-server \
    --model unsloth/Qwen3.5-35B-A3B-GGUF/Qwen3.5-35B-A3B-UD-Q4_K_XL.gguf \
    --alias "unsloth/Qwen3.5-35B-A3B" \
    --temp 0.6 \
    --top-p 0.95 \
    --top-k 20 \
    --min-p 0.00 \
    --port 8001 \
    --kv-unified \
    --cache-type-k q8_0 --cache-type-v q8_0 \
    --flash-attn on --fit on \
    --ctx-size 131072  # 必要に応じて変更

重要な設定解説:

  1. KV キャッシュ量子化: --cache-type-k q8_0 --cache-type-v q8_0
  2. VRAM 使用量を削減するために使用
  3. 完全精度が必要な場合：--cache-type-k bf16 --cache-type-v bf16

  4. 警告: f16 KV キャッシュは Qwen3.5 で精度が低下するため使用しないこと

  5. –fit on: 自動オフロードを有効化（パフォーマンスが悪い場合は --ctx-size を減らす）

  6. Thinking モードの無効化:
    bash
    --chat-template-kwargs "{\"enable_thinking\": false}"

  7. アージェントコーディングタスクではパフォーマンス向上

GLM-4.7-Flash 詳細セットアップ

ステップ 1: モデルのダウンロード

import os
os.environ["HF_HUB_ENABLE_HF_TRANSFER"] = "1"
from huggingface_hub import snapshot_download

snapshot_download(
    repo_id = "unsloth/GLM-4.7-Flash-GGUF",
    local_dir = "unsloth/GLM-4.7-Flash-GGUF",
    allow_patterns = ["*UD-Q4_K_XL*"],
)

ステップ 2: llama-server の起動

GLM-4.7-Flash のサンプリングパラメータ:
– --temp 1.0
– --top-p 0.95
– --min-p 0.01

./llama.cpp/llama-server \
    --model unsloth/GLM-4.7-Flash-GGUF/GLM-4.7-Flash-UD-Q4_K_XL.gguf \
    --alias "unsloth/GLM-4.7-Flash" \
    --temp 1.0 \
    --top-p 0.95 \
    --min-p 0.01 \
    --port 8001 \
    --kv-unified \
    --cache-type-k q8_0 --cache-type-v q8_0 \
    --flash-attn on --fit on \
    --batch-size 4096 --ubatch-size 1024 \
    --ctx-size 131072  # 必要に応じて変更

Thinking モードの無効化:

--chat-template-kwargs "{\"enable_thinking\": false}"

第二部分：Claude Code チュートリアル

Claude Code のインストールとローカル実行

Mac / Linux セットアップ

インストール:

curl -fsSL https://claude.ai/install.sh | bash
# または Homebrew: brew install --cask claude-code

設定:
ローカルの llama.cpp サーバーに Claude Code をリダイレクトするために、環境変数を設定します。

export ANTHROPIC_BASE_URL="http://localhost:8001"
export ANTHROPIC_API_KEY='sk-no-key-required'  # または 'sk-1234'

セッション永続化:
– 現在のターミナルのみ有効
– 永続化するには ~/.bashrc（bash）または ~/.zshrc（zsh）に追加

サインインプロンプトを回避:
~/.claude.json に以下を追加:

{
  "hasCompletedOnboarding": true,
  "primaryApiKey": "sk-dummy-key"
}

VS Code 拡張機能の場合、設定でDisable Login Promptを有効化（または settings.json に "claudeCode.disableLoginPrompt": true を追加）

Windows セットアップ

インストール（PowerShell）:

irm https://claude.ai/install.ps1 | iex

設定:

$env:ANTHROPIC_BASE_URL="http://localhost:8001"
$env:CLAUDE_CODE_ATTRIBUTION_HEADER=0

永続化:

setx ANTHROPIC_BASE_URL "http://localhost:8001"

重要な問題：90% の推論速度低下の修正

問題の説明

Claude Code は最近、Claude Code Attribution ヘッダーを追加し、これによりKV キャッシュが無効化され、ローカルモデルでの推論が 90% 遅くなる問題が発生しています。

解決方法

環境変数での設定では動作しないため、設定ファイルを直接編集する必要があります。

Linux / Mac:

cat > ~/.claude/settings.json

以下の設定を追加・編集:

{
  "promptSuggestionEnabled": false,
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "0",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
  },
  "attribution": {
    "commit": "",
    "pr": ""
  },
  "plansDirectory": "./plans",
  "prefersReducedMotion": true,
  "terminalProgressBarEnabled": false,
  "effortLevel": "high"
}

Windows:

~/.claude/settings.json を編集して同様の設定を追加。

重要: export CLAUDE_CODE_ATTRIBUTION_HEADER=0 環境変数の設定では動作しないため、必ず設定ファイルの "env" セクションに追加してください。

ローカルでの Claude Code 実行

プロジェクトディレクトリでの実行

# プロジェクトフォルダに移動
mkdir project
cd project

# GLM-4.7-Flash を使用
claude --model unsloth/GLM-4.7-Flash

# Qwen3.5-35B-A3B を使用
claude --model unsloth/Qwen3.5-35B-A3B

権限の省略（注意：コードを実行する際に承認を求めません）

claude --model unsloth/GLM-4.7-Flash --dangerously-skip-permissions

動作確認プロンプト例

Unsloth のファインチューニングを実行するテストプロンプト:

You can only work in the cwd project/. Do not search for CLAUDE.md - this is it. 
Install Unsloth via a virtual environment via uv. Use `python -m venv unsloth_env` 
then `source unsloth_env/bin/activate` if possible. See https://unsloth.ai/docs/get-started/install/pip-install 
on how (get it and read). Then do a simple Unsloth finetuning run described in 


Build software better, together
GitHub is where people build software. More than 150 million people use GitHub to discover, fork, and contribute to over...
github.com
 You have access to 1 GPU.

IDE 拡張機能

VS Code / Cursor での使用

公式拡張機能を使用してエディター内で直接 Claude Code を使用可能:

  • VS Code: https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code
  • Cursor: cursor:extension/anthropic.claude-code
  • ドキュメント: https://code.claude.com/docs/en/vs-code

インストール方法:
1. Ctrl+Shift+X（Windows/Linux）または Cmd+Shift+X（Mac）
2. Claude Codeを検索
3. Installをクリック

トラブルシューティング

API 接続エラー

Unable to connect to API (ConnectionRefused) エラーが表示された場合:

unset ANTHROPIC_BASE_URL

ダウンロードがフリーズする場合

Hugging Face Hub XET のデバッグ情報を参照:
https://unsloth.ai/docs/basics/troubleshooting-and-faqs/hugging-face-hub-xet-debugging

まとめ

このガイドにより、以下のことが可能になります:

  1. 完全ローカル環境での LLM 実行
  2. Claude Code とのシームレスな連携
  3. 最適なパフォーマンス設定（KV キャッシュ量子化、サンプリングパラメータ）
  4. 速度低下問題の回避（Attribution ヘッダー設定）
  5. 複数のモデルバリアントのサポート（Qwen3.5、GLM-4.7-Flash など）

24GB VRAM の GPU（RTX 4090 など）があれば、これらのモデルを効率的に実行できます。

参考リンク

  • Unsloth ドキュメント：https://unsloth.ai/docs
  • llama.cpp: https://github.com/ggml-org/llama.cpp
  • Unsloth モデルカタログ：https://unsloth.ai/docs/get-started/unsloth-model-catalog
  • Unsloth インストール：https://unsloth.ai/docs/get-started/install/pip-install
  • Unsloth GitHub: https://github.com/unslothai/unsloth

コメント

タイトルとURLをコピーしました