Deepseek大模型をローカルにデプロイする方法（詳細チュートリアル）

# はじめに

この記事では、macOS、Windows、Linuxの3つの主要オペレーティングシステムを対象とした、Deepseek大規模モデルのローカルデプロイチュートリアルを詳細に提供します。3つの主要なデプロイ方法を紹介します：**Ollama**（最も簡単で使いやすい）、**llama.cpp**（優れたパフォーマンス、GGUF形式）、および**Hugging Face Transformers**（ネイティブPython、高い柔軟性）。これにより、ニーズに最適なソリューションを選択できます。

# 1. ローカルデプロイ前の準備

デプロイを開始する前に、システムが以下の基本要件を満たしていることを確認してください。

## 1.1 ハードウェア要件

大規模モデルのローカルデプロイには、特にメモリとVRAMに関して、ある程度のハードウェア要件があります。

*   **CPU：** 8コア以上、高クロック速度を推奨します。
*   **メモリ（RAM）：** 少なくとも16GB、32GB以上を推奨します。モデルが大きいほど、より多くのメモリが必要です。
*   **GPU（グラフィックカード）：** **NVIDIAグラフィックカードの使用を強く推奨**し、少なくとも8GBのVRAM、12GB、16GB以上を推奨します。GPUは推論プロセスを大幅に高速化できます。
    *   **NVIDIAユーザー：** 最新のグラフィックカードドライバーとCUDA Toolkitがインストールされていることを確認してください。
    *   **AMDユーザー：** 一部の方法（llama.cppなど）はROCmをサポートしていますが、NVIDIAほどの互換性はありません。
    *   **macOSユーザー：** Apple Siliconチップ（Mシリーズ）は、Metalフレームワークを通じて優れたGPUアクセラレーションを提供します。
*   **ストレージ容量：** 選択したモデルのサイズに応じて、十分なディスク容量（通常数十GBから数百GB）を確保してください。ロード速度を向上させるためにSSDの使用を推奨します。

## 1.2 ソフトウェア要件（共通）

以下のソフトウェアは、ほとんどのデプロイ方法に共通する基本的なツールです。

*   **オペレーティングシステム：**
    *   macOS (Monterey 12.0 以降)
    *   Windows 10/11 (64ビット)
    *   Linux (Ubuntu 20.04+, Debian 11+, CentOS 7+ など)
*   **Git：** コードリポジトリをクローンするために使用します。
    *   **macOS：** Xcode Command Line Tools (`xcode-select --install`) または Homebrew (`brew install git`) をインストールします。
    *   **Windows：** [Git公式サイト](https://git-scm.com/download/win) からダウンロードしてインストールします。
    *   **Linux：** `sudo apt update && sudo apt install git` (Debian/Ubuntu) または `sudo yum install git` (CentOS)。
*   **Python (3.8+) および pip：** Pythonベースのデプロイ方法に使用します。
    *   **macOS/Linux：** 通常プリインストールされていますが、`pyenv` または `conda` を使用して環境を管理することを推奨します。
    *   **Windows：** [Python公式サイト](https://www.python.org/downloads/windows/) からダウンロードしてインストールし、「Add Python to PATH」にチェックを入れることを確認してください。
*   **C++ コンパイラ：** 主にllama.cppのコンパイルに使用します。
    *   **macOS：** Xcode Command Line Tools (`xcode-select --install`)。
    *   **Windows：** Visual Studio Build Tools または MinGW-w64。
    *   **Linux：** `build-essential` (`sudo apt install build-essential`)。
*   **CUDA Toolkit (NVIDIA GPUユーザー)：** [NVIDIA公式サイト](https://developer.nvidia.com/cuda-downloads) から、お使いのグラフィックカードドライバーと互換性のあるバージョンをダウンロードしてインストールします。

# 2. Deepseekモデルの選択

Deepseekは、以下を含む複数のオープンソースモデルを提供しています。

*   **Deepseek-Coder：** コード生成と理解に特化しています。
*   **Deepseek-V2：** 包括的な大規模モデルで、強力なパフォーマンスを発揮します。

Deepseekが公式にリリースしたモデルは、[Hugging Face Hub](https://huggingface.co/deepseek-ai) で見つけることができます。

**モデル形式の選択：**

*   **GGUF形式：** `ollama` および `llama.cpp` に適しています。通常、量子化されており、ファイルサイズが小さく、ハードウェア要件が比較的低いですが、精度がわずかに低下する可能性があります。
*   **PyTorch形式：** Hugging Face `transformers` ライブラリに適しています。モデルのネイティブ形式であり、ファイルサイズが大きく、ハードウェア要件が高いですが、最高のパフォーマンスと柔軟性を提供します。

# 3. デプロイ方法1：Ollamaを使用（推奨、最も簡単）

Ollamaは、大規模モデルのローカル実行プロセスを簡素化することを目的とした軽量フレームワークです。統一されたAPIとコマンドラインインターフェースを提供し、複数のGGUF形式のモデルをサポートしています。

## 3.1 Ollamaの概要

*   **利点：** インストールが簡単、使いやすい、クロスプラットフォーム対応、組み込みAPIサービス。
*   **欠点：** モデルの選択肢がOllamaライブラリに限定され、カスタマイズの自由度が低い。

## 3.2 Ollamaのインストール

#### macOS

1.  **Homebrewを使用（推奨）：**
    ```bash
    brew install ollama
    ```
2.  **または公式サイトからダウンロード：**
    [Ollama公式サイト](https://ollama.com/download) にアクセスし、macOSインストーラーをダウンロードしてアプリケーションフォルダにドラッグ＆ドロップします。

#### Windows

1.  [Ollama公式サイト](https://ollama.com/download) にアクセスし、Windowsインストーラーをダウンロードします。
2.  インストーラーをダブルクリックし、指示に従ってインストールを完了します。

#### Linux

1.  ターミナルを開き、以下のコマンドを実行します。
    ```bash
    curl -fsSL https://ollama.com/install.sh | sh
    ```
    このスクリプトは、システムを自動的に検出し、Ollamaをインストールします。

## 3.3 Deepseekモデルのダウンロードと実行

Ollamaコミュニティは、DeepseekモデルのGGUFバージョンを提供しています。[Ollama公式サイトのモデルライブラリ](https://ollama.com/library) でDeepseekを検索できます。

`deepseek-coder:latest` を例にとります。

1.  ターミナルを開きます（WindowsユーザーはPowerShellまたはCMDを使用）。
2.  以下のコマンドを実行して、モデルをダウンロードし、起動します。
    ```bash
    ollama run deepseek-coder:latest
    ```
    モデルがダウンロードされていない場合、Ollamaは自動的にダウンロードを開始します。ダウンロードが完了すると、対話型チャットインターフェースに入ります。

    ```
    >>> Send a message (/? for help)
    ```
3.  質問を入力すると、モデルが回答を生成します。
    ```
    >>> こんにちは、自己紹介をお願いします。
    私はDeepseek-Coderです。Deepseek AIによってトレーニングされた大規模言語モデルで、コード生成、理解、および質問応答に特化しています。
    ```
4.  `/bye` と入力して対話モードを終了します。

## 3.4 API経由でのアクセス

OllamaはバックグラウンドでローカルAPIサービス（デフォルトポート `11434`）を起動します。これにより、HTTPリクエストを通じて簡単にモデルと対話できます。

**例（curlを使用）：**

```bash
curl http://localhost:11434/api/generate -d '{
  "model": "deepseek-coder:latest",
  "prompt": "Pythonでn項までのフィボナッチ数列を計算する関数を書いてください。",
  "stream": false
}'
```

Pythonなどのプログラミング言語のHTTPライブラリを使用して、このAPIを呼び出すこともできます。

# 4. デプロイ方法2：llama.cppを使用（優れたパフォーマンス、GGUF形式）

`llama.cpp` は、C/C++で書かれた推論エンジンであり、CPUおよびGPU（NVIDIA CUDA、AMD ROCm、Apple Metalを含む）での効率的な推論能力で知られており、GGUF形式のモデルをサポートしています。

## 4.1 llama.cppの概要

*   **利点：** 卓越したパフォーマンス、低いリソース使用率、複数のハードウェアアクセラレーションをサポート、活発なコミュニティ。
*   **欠点：** 手動でのコンパイルが必要で、環境設定にある程度の要件があります。

## 4.2 環境準備

#### 一般的な手順

1.  **Gitのインストール：** 「1. ローカルデプロイ前の準備」の説明を参照してください。
2.  **C++コンパイラのインストール：**
    *   **macOS：** `xcode-select --install`
    *   **Windows：** [Visual Studio Build Tools](https://visualstudio.microsoft.com/zh-hans/downloads/)（「C++によるデスクトップ開発」ワークロードを選択）または [MinGW-w64](https://www.mingw-w64.org/doku.php/download) をインストールします。
    *   **Linux：** `sudo apt install build-essential` (Debian/Ubuntu) または `sudo yum groupinstall "Development Tools"` (CentOS)。

#### GPUアクセラレーション（オプション）

*   **macOS (Apple Silicon)：** 追加の設定は不要です。`llama.cpp` はデフォルトでMetalをサポートしています。
*   **NVIDIA GPU：** 最新のNVIDIAドライバーと **CUDA Toolkit** がインストールされていることを確認してください。
*   **AMD GPU：** **ROCm** がインストールされていることを確認してください。

## 4.3 llama.cppのクローンとコンパイル

1.  **リポジトリのクローン：**
    ```bash
    git clone https://github.com/ggerganov/llama.cpp.git
    cd llama.cpp
    ```
2.  **コンパイル：**
    *   **一般的なCPUコンパイル：**
        ```bash
        make
        ```
    *   **macOS (Apple Silicon Metalアクセラレーション)：**
        ```bash
        make LLAMA_METAL=1
        ```
    *   **NVIDIA GPU (CUDAアクセラレーション)：**
        ```bash
        make LLAMA_CUDA=1
        ```
        *CUDAパスの問題が発生した場合は、`CUDA_PATH`環境変数を設定するか、`make`コマンドで指定する必要がある場合があります。*
    *   **AMD GPU (ROCmアクセラレーション)：**
        ```bash
        make LLAMA_ROCM=1
        ```
    コンパイルが成功すると、`llama.cpp` ディレクトリ内に `main` (Linux/macOS) または `main.exe` (Windows) などの実行可能ファイルが表示されます。

## 4.4 Deepseek GGUFモデルのダウンロード

1.  [Hugging Face Hub](https://huggingface.co/models) にアクセスします。
2.  `deepseek` と `GGUF` を検索します。通常、コミュニティメンバーがDeepseekモデルをGGUF形式に変換しています。
    *   例：`deepseek-coder-6.7b-instruct GGUF` を検索します。
    *   信頼できるモデルアップローダー（例：`TheBloke`）を見つけ、そのモデルページにアクセスします。
3.  必要な量子化バージョンを選択します（例：`Q4_K_M` はパフォーマンスと精度のバランスが取れた一般的な選択肢です）。
4.  `.gguf` ファイルをダウンロードします。
    *   **`wget` または `curl` を使用して `llama.cpp/models` ディレクトリにダウンロードすることを推奨します：**
        ```bash
        # 例：deepseek-coder-6.7b-instruct.Q4_K_M.gguf をダウンロード
        mkdir -p models
        wget -P models https://huggingface.co/TheBloke/deepseek-coder-6.7B-Instruct-GGUF/resolve/main/deepseek-coder-6.7b-instruct.Q4_K_M.gguf
        ```
    *   **または、手動でダウンロードしてから `llama.cpp/models` ディレクトリに移動します。**

## 4.5 Deepseekモデルの実行

1.  `llama.cpp` ディレクトリ内にいることを確認します。
2.  モデルを実行します。
    ```bash
    ./main -m models/deepseek-coder-6.7b-instruct.Q4_K_M.gguf -p "こんにちは、自己紹介をお願いします。" -n 512 --temp 0.7
    ```
    *   `-m <path_to_model>`：GGUFモデルファイルのパスを指定します。
    *   `-p "<prompt>"`：入力プロンプト。
    *   `-n <tokens>`：生成されるテキストの最大トークン数。
    *   `--temp <value>`：サンプリング温度。値が高いほど結果はランダムになります（0.0～2.0）。
    *   `-t <threads>`：使用するCPUスレッド数。
    *   `-ngl <layers>`：モデルの何層をGPU（NVIDIA/Metal）にロードするか。例：`-ngl 30` は30層をGPUにロードし、残りはCPUで処理することを意味します。**これはGPUアクセラレーションを利用するための重要なパラメータです。**

    **例（GPUアクセラレーション付き）：**
    ```bash
    # macOS (Metal)
    ./main -m models/deepseek-coder-6.7b-instruct.Q4_K_M.gguf -p "Pythonでn項までのフィボナッチ数列を計算する関数を書いてください。" -n 512 --temp 0.7 -ngl 999 # 999は可能な限り多くの層をGPUにロードすることを意味します

    # NVIDIA (CUDA)
    ./main -m models/deepseek-coder-6.7b-instruct.Q4_K_M.gguf -p "Pythonでn項までのフィボナッチ数列を計算する関数を書いてください。" -n 512 --temp 0.7 -ngl 999
    ```

# 5. デプロイ方法3：Hugging Face Transformersを使用（ネイティブPython、高い柔軟性）

Hugging Face `transformers` ライブラリは、さまざまな事前学習済み大規模モデルをデプロイおよび使用するための標準ツールです。モデルのファインチューニング、複雑なアプリケーションへの統合、または最新のモデル機能の使用が必要なシナリオに最適な、最大の柔軟性を提供します。

## 5.1 Transformersの概要

*   **利点：** 公式サポート、最も幅広いモデル選択肢、Pythonプロジェクトへの統合が容易、PyTorch/TensorFlow/JAXをサポート、ファインチューニングが容易。
*   **欠点：** ハードウェア要件が最も高い（特にVRAM）、モデルファイルは通常大きい、依存関係のインストールが多くなる可能性がある。

## 5.2 環境準備

#### 一般的な手順

1.  **Python (3.8+) および pip のインストール：** 「1. ローカルデプロイ前の準備」の説明を参照してください。
2.  **仮想環境の作成とアクティベーション（強く推奨）：**
    ```bash
    python -m venv deepseek_env
    # macOS/Linux
    source deepseek_env/bin/activate
    # Windows
    .\deepseek_env\Scripts\activate
    ```
3.  **コア依存関係のインストール：**
    ```bash
    pip install torch transformers accelerate
    ```
    *   `torch`：PyTorch深層学習フレームワーク。
    *   `transformers`：Hugging Faceモデルライブラリ。
    *   `accelerate`：マルチGPUまたはCPUでのモデル実行を最適化するために使用されます。

#### GPUアクセラレーション（オプション）

*   **NVIDIA GPUユーザー：**
    *   CUDA Toolkitのバージョンに応じて、[PyTorch公式サイト](https://pytorch.org/get-started/locally/) から正しいインストールコマンドを取得します。
    *   **例（CUDA 12.1）：**
        ```bash
        pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
        ```
    *   インストール後、`python -c "import torch; print(torch.cuda.is_available())"` でCUDAが利用可能か確認します。
*   **macOS (Apple Silicon) ユーザー：**
    *   Metal Performance Shaders (MPS) をサポートするPyTorchバージョンをインストールします。
        ```bash
        pip install --pre torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/nightly/cpu
        ```
        *注意：最新のMPSサポートを得るために、nightlyバージョンをインストールする必要がある場合があります。*
    *   インストール後、`python -c "import torch; print(torch.backends.mps.is_available())"` でMPSが利用可能か確認します。

## 5.3 Deepseekモデルウェイトのダウンロード

Hugging Face `transformers` ライブラリは、モデルを初めてロードする際に、モデルウェイトをローカルキャッシュディレクトリに自動的にダウンロードします。

`deepseek-ai/deepseek-coder-6.7b-instruct` を例にとります。

## 5.4 Python推論コードの作成

Pythonファイル（例：`deepseek_inference.py`）を作成し、以下のコードを追加します。

```python
import torch
from transformers import AutoTokenizer, AutoModelForCausalLM

# 1. モデルパスの選択
# Deepseek-Coder-V1.5 6.7B Instruct
model_name = "deepseek-ai/deepseek-coder-6.7b-instruct"
# Deepseek-V2 (注意：V2モデルは通常より大きく、VRAM要件が高いです)
# model_name = "deepseek-ai/DeepSeek-V2"

# 2. デバイスの設定
# CUDA (NVIDIA GPU) を優先し、次にMPS (Apple Silicon)、最後にCPUを使用します
if torch.cuda.is_available():
    device = "cuda"
elif torch.backends.mps.is_available():
    device = "mps"
else:
    device = "cpu"

print(f"Using device: {device}")

# 3. トークナイザーとモデルのロード
print(f"Loading tokenizer for {model_name}...")
tokenizer = AutoTokenizer.from_pretrained(model_name)

print(f"Loading model {model_name} to {device}...")
# 大きなモデルの場合、メモリを節約するために load_in_8bit または load_in_4bit を使用して量子化ロードできます
# ただし、精度と速度がわずかに低下します。
# model = AutoModelForCausalLM.from_pretrained(model_name, torch_dtype=torch.bfloat16, device_map="auto", load_in_8bit=True)
# または、指定したデバイスに直接ロードします
model = AutoModelForCausalLM.from_pretrained(model_name, torch_dtype=torch.bfloat16).to(device)
model.eval() # 評価モードに設定

print("Model loaded successfully!")

# 4. 対話テンプレートの定義 (Deepseek-Coder-Instruct の例)
# Deepseekモデルには通常、特定の対話形式があります。そのHugging Faceページを参照してください。
# ここでは Deepseek-Coder-Instruct を例にとります
def generate_response(prompt_text):
    messages = [
        {"role": "user", "content": prompt_text}
    ]
    # tokenizerのapply_chat_templateメソッドを使用して対話をフォーマットします
    # add_generation_prompt=True は、ユーザーメッセージの後にモデルの応答プロンプトを追加します
    input_ids = tokenizer.apply_chat_template(messages, tokenize=True, add_generation_prompt=True, return_tensors="pt").to(device)

    print(f"\nUser: {prompt_text}")
    print("Generating response...")

    # 5. テキスト生成
    with torch.no_grad():
        outputs = model.generate(
            input_ids,
            max_new_tokens=512, # 最大生成トークン数
            do_sample=True,
            temperature=0.7,    # サンプリング温度
            top_p=0.9,          # Top-pサンプリング
            eos_token_id=tokenizer.eos_token_id,
            pad_token_id=tokenizer.pad_token_id # pad_token_idが設定されていることを確認してください
        )

    # 6. デコードして結果を表示
    # 入力部分をスキップしてデコードします
    response = tokenizer.decode(outputs[0][input_ids.shape[-1]:], skip_special_tokens=True)
    print(f"Deepseek: {response.strip()}")
    print("-" * 50)

# 7. 対話型チャット
while True:
    user_input = input("Enter your prompt (or 'quit' to exit): ")
    if user_input.lower() == 'quit':
        break
    generate_response(user_input)

print("Exiting Deepseek inference.")

```

**Pythonコードの実行：**

1.  上記のコードを `deepseek_inference.py` として保存します。
2.  アクティブな仮想環境で実行します。
    ```bash
    python deepseek_inference.py
    ```
    初回実行時に、モデルウェイトが自動的にダウンロードされます。ダウンロードが完了すると、プログラムはモデルのロードを開始し、対話モードに入ります。

# 6. よくある質問とトラブルシューティング

*   **メモリ/VRAM不足 (OOM - Out Of Memory)：**
    *   **症状：** プログラムがクラッシュし、エラーメッセージに「CUDA out of memory」、「MPS out of memory」、または「killed」が含まれる。
    *   **解決策：**
        *   より小さいモデルバージョン（例：7Bではなく67B）を選択します。
        *   より量子化されたGGUFモデル（例：Q8_0ではなくQ4_K_M）を使用します。
        *   Transformersの場合、`load_in_8bit=True` または `load_in_4bit=True` パラメータを使用して量子化ロードを試みます。
        *   `max_new_tokens` パラメータを減らします。
        *   大量のメモリ/VRAMを消費する他のプログラムを閉じます。
*   **モデルのダウンロード失敗または低速：**
    *   ネットワーク接続を確認します。
    *   Hugging Faceモデルの場合、環境変数 `HF_ENDPOINT=https://hf-mirror.com` を設定してミラーサイトを使用することを試みます（中国本土ユーザーのみ）。
    *   GGUFファイルを指定ディレクトリに手動でダウンロードします。
*   **llama.cppのコンパイルエラー：**
    *   すべての依存関係（Git、C++コンパイラ、CUDA Toolkitなど）が正しくインストールされ、環境変数が設定されていることを確認します。
    *   エラーメッセージを確認します。通常、不足しているライブラリまたはヘッダーファイルを示しています。
    *   クリーンしてから再コンパイルを試みます：`make clean && make`。
*   **Python環境の問題：**
    *   正しい仮想環境がアクティブになっていることを確認します。
    *   Pythonのバージョンが要件を満たしているか確認します。
    *   `pip list` を使用して、すべての依存関係が正しくインストールされているか確認します。
    *   PyTorchのCUDAバージョンが一致しない場合は、アンインストールして正しいバージョンのPyTorchを再インストールします。
*   **Ollamaモデルが起動しない：**
    *   Ollamaサービスが実行中か確認します (`ollama list` または `ollama ps`)。
    *   Ollamaサービスを再起動します。
    *   モデル名が正しく入力されているか確認します。

# 7. まとめと展望

この記事では、macOS、Windows、LinuxシステムでDeepseek大規模モデルをローカルデプロイするための3つの主要な方法（Ollama、llama.cpp、Hugging Face Transformers）について詳細に説明しました。

*   **Ollama** は最も簡単なデプロイ体験を提供し、迅速な試用や日常的な使用に適しています。
*   **llama.cpp** はパフォーマンスとリソース効率に優れており、GGUFモデル推論の理想的な選択肢です。
*   **Hugging Face Transformers** は最大の柔軟性と制御を提供し、深い開発やカスタマイズに適しています。

開発者、研究者、AI愛好家のいずれであっても、Deepseek大規模モデルのローカルデプロイは、大規模モデルの可能性を探求するための新しい扉を開くでしょう。オープンソースコミュニティの継続的な発展とともに、将来的にはより効率的で使いやすいツールやモデルが登場するでしょう。このチュートリアルが、最初のステップをスムーズに進め、ローカル大規模モデルがもたらす利便性と楽しさを存分に体験する一助となれば幸いです！