# 部署 Dify + Ollama：本地運行大型語言模型的詳細教程 (Docker & GPU 加速)

## 🚀 前言

如果想在自己的電腦上運行像 Llama 3、Qwen 這樣強大的大型語言模型 (LLM)，並透過一個精美的 UI 來進行互動和開發應用嗎？本教學將帶你一步步使用 Docker 部署 [Dify](https://dify.ai/) 和 [Ollama](https://ollama.com/)，實現一個完全在本地端、可選擇 GPU 加速的 LLM 工作流程。

- **Ollama**: 一個能讓你在本地輕鬆運行 Llama 3, Mistral, Gemma 等開源大型語言模型的工具。
- **Dify**: 一個開源的 LLM 應用程式開發平台，提供視覺化的 Prompt 工程、RAG（檢索增強生成）以及應用編排能力。
- **Docker**: 一個容器化平台，能讓我們用標準化、隔離的環境快速部署應用，告別繁瑣的環境配置。

透過這套組合，你不僅能確保數據的私密性，還能免費、無限制地使用 LLM 進行實驗和開發。

---

## 📋 先備條件

在開始之前，請確保你的系統滿足以下要求：

1. **💻 硬體資源**:
- **RAM**: 建議至少 16GB。運行 8B（80億參數）模型通常需要 8GB+ 的 RAM，更大的模型需要更多。
- **儲存空間**: 建議至少 50GB 的可用 SSD 空間，因為模型檔案通常很大。
- **GPU (可選但強烈推薦)**: 擁有 NVIDIA 顯卡可大幅提升模型推理速度。如果計畫使用 GPU，請確保已安裝對應的驅動程式。

2. **🔧 軟體環境**:
- **Docker**: [安裝 Docker Desktop](https://www.docker.com/products/docker-desktop/) (適用於 Windows/Mac) 或 Docker Engine (適用於 Linux)。
- **Docker Compose**: Docker Desktop 已內建，Linux 用戶需單獨安裝。
- **Git**: 用於下載 Dify 的部署文件。
- **基本的終端機/命令提示字元操作能力**。
- **(GPU 用戶)**: [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)，讓 Docker 可以使用 GPU。

---

## ⭐ GPU 用戶特別步驟：安裝 NVIDIA Container Toolkit

如果你擁有 NVIDIA 顯示卡並希望 Ollama 在 Docker 中利用 GPU 進行加速，**必須**先安裝 NVIDIA Container Toolkit。這個工具可以讓 Docker 容器安全地存取主機的 GPU 資源。

> **注意**：以下教學基於 Debian/Ubuntu 系統。其他 Linux 發行版請參考 [NVIDIA 官方文件](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)。

### 步驟 1：設定官方軟體庫

首先，我們需要將 NVIDIA 的軟體庫加入到系統的 `apt` 源中。

1. **加入 GPG 金鑰**：

    curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

2. **加入軟體庫源**：

    curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
      sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
      sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

### 步驟 2：安裝 Toolkit

1. **更新軟體包列表**：

    sudo apt-get update

2. **安裝 NVIDIA Container Toolkit**：

    sudo apt-get install -y nvidia-container-toolkit

### 步驟 3：設定 Docker 使用 NVIDIA Runtime

安裝完畢後，需要執行一個命令來設定 Docker，讓它知道有 NVIDIA Runtime 可用。

sudo nvidia-ctk runtime configure --runtime=docker

### 步驟 4：重啟 Docker 服務

為了讓設定生效，必須重啟 Docker。

sudo systemctl restart docker

### 步驟 5：驗證安裝 (強烈建議)

執行一個簡單的 CUDA 容器來驗證 Docker 是否能成功調用 GPU。

docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi

如果安裝成功，你應該會看到與在主機上直接執行 `nvidia-smi` 類似的輸出，顯示你的 GPU 型號、驅動版本和 CUDA 版本。看到這個畫面，代表你的 Docker 已經準備好進行 GPU 加速了！

---

## 步驟一：部署 Ollama (二選一)

你可以選擇將 Ollama 作為 Docker 容器運行，或直接安裝在你的主機上。**對於大多數用戶，推薦使用 Docker 方法。**

### 方案 A：🐳 在 Docker 中部署 Ollama (推薦)

這是最簡單、最乾淨的方法，因為所有東西都在容器中。

1. **啟動 Ollama 容器**

打開你的終端機，根據您是否有 GPU 選擇以下一個命令執行：

- **GPU 用戶 (推薦)**:
> 前提是您已安裝 NVIDIA 驅動和 NVIDIA Container Toolkit。

        docker run -d --gpus=all -v ollama:/root/.ollama -p 11434:11434 --name ollama --rm ollama/ollama

- **僅 CPU 用戶**:

        docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama --rm ollama/ollama

**命令解釋**:
- `--gpus=all`: (GPU用戶) 讓容器可以使用主機上所有的 GPU 資源。
- `-v ollama:/root/.ollama`: 創建一個 Docker volume 來持久化儲存您下載的模型，即使容器被刪除，模型檔案也會保留。
- `--rm`: 容器停止時自動刪除，方便管理（volume 中的模型不受影響）。
- 其他參數見上一版教學。

2. **下載一個模型**

使用 `docker exec` 進入運行的容器並下載模型。以 `qwen:4b` (通義千問 40億參數模型) 為例：

    docker exec -it ollama ollama pull qwen:4b

你可以替換成其他模型，如 `llama3` 或 `mistral`。下載完成後，Ollama 就緒！

### 方案 B：🖥️ 在主機上直接安裝 Ollama (替代方案)

如果你不想在 Docker 中運行 Ollama，可以將其直接安裝在 Linux 主機上。

1. **安裝 Ollama**

    curl -fsSL https://ollama.com/install.sh | sh

2. **配置網絡訪問**

為了讓 Docker 中的 Dify 能夠連接到主機上的 Ollama，你需要修改 Ollama 的服務配置，使其監聽所有網絡接口。

- 編輯服務文件：

        sudo systemctl edit ollama.service

- 在打開的編輯器中，添加以下內容並儲存：

        [Service]
        Environment="OLLAMA_HOST=0.0.0.0"

- 重載配置並重啟 Ollama 服務：

        sudo systemctl daemon-reload
        sudo systemctl restart ollama

3. **下載一個模型**

    ollama pull qwen:4b

---

## 步驟二：🚀 使用 Docker Compose 部署 Dify

此步驟與 Ollama 的部署方式無關。

1. **下載 Dify 的部署文件**

    git clone https://github.com/langgenius/dify.git
    cd dify/docker

2. **創建環境變數文件**

複製範例環境檔，這是官方推薦的做法。

    cp .env.example .env

3. **啟動 Dify 服務**

在 `dify/docker` 目錄下，執行以下命令：

    docker-compose up -d

第一次啟動會需要一些時間來下載映像。

4. **初始化 Dify**

- 在您的瀏覽器中開啟 `http://localhost/install`。
- 根據頁面提示，設定你的管理員帳號和密碼。
- 完成後，登入 Dify。

---

## 步驟三：🔗 將 Ollama 整合至 Dify

告訴 Dify 如何找到我們部署好的 Ollama 服務。

1. **找到你電腦的內網 IP 位址**

由於 Dify (在 Docker 中) 和 Ollama (可能在 Docker 中或在主機上) 是隔離的，Dify **不能** 使用 `localhost` 來找到 Ollama。我們需要使用您電腦在區域網路中的 IP 位址。

- **Windows**: `ipconfig`
- **macOS/Linux**: `ifconfig` 或 `ip addr`

> **⚠️ 注意**: 請勿使用 `127.0.0.1` 或 `localhost`。假設您的 IP 是 `192.168.1.100`。

2. **在 Dify 中配置模型提供商**

- 登入 Dify 後，點擊右上角的頭像 -> **設定** -> **模型供應商**。
- 點擊 **Ollama**。
- **伺服器 URL**: 填寫 `http://<您的內網IP>:11434`。例如：`http://192.168.1.100:11434`。
- **模型**: 點擊「從伺服器 URL 載入」來自動抓取可用的模型列表，然後選擇您要使用的模型（如 `qwen:4b`）。
- 點擊 **儲存**。

---

## 步驟四：🎉 建立你的第一個本地 LLM 應用

整合完成後，讓我們來建立一個簡單的聊天應用來測試成果！

1. **建構應用** -> 選擇 **對話型應用** -> 命名。
2. 在 **模型與參數** 中，選擇你剛剛配置的 **Ollama** 模型。
3. 點擊 **預覽** 並開始對話！

恭喜！你已成功搭建了一個完全在本地運行的 LLM 應用開發環境！

---

## 💡 配置與效能建議

當你成功部署完畢後，可以透過以下建議來優化你的使用體驗和系統效能。

### 一、通用配置建議

1. **增加 Docker 資源配置 (Mac/Windows)**
如果你使用 Docker Desktop，預設分配給 Docker 的 CPU、記憶體和磁碟空間可能不足以流暢運行大型模型。
- **路徑**: Docker Desktop -> Settings (設定) -> Resources (資源)。
- **建議**: 至少分配 8GB RAM，並根據你要運行的模型大小酌情增加。CPU 核心數也建議調高。

2. **堅持使用 Docker Volume**
本教學中的 `docker run` 命令已包含 `-v ollama:/root/.ollama`。這一步至關重要，因為：
- **模型持久化**: 你下載的模型會被儲存在名為 `ollama` 的 Docker Volume 中，即使你刪除並重建 Ollama 容器，模型依然存在，無需重新下載。
- **方便管理**: 你可以輕鬆地備份、遷移或清理這些模型資料。

3. **(進階) 建立專用 Docker 網路**
雖然使用主機 IP 位址很方便，但在某些複雜的網路環境下可能會不穩定。一個更穩健的方法是讓 Dify 和 Ollama 加入同一個自訂的 Docker 網路中，這樣它們就可以透過容器名稱直接通訊。

- **1. 建立網路**:

        docker network create dify-net

- **2. 啟動 Ollama 時加入網路**:

        # 在原有的 docker run 命令中加入 --network=dify-net
        docker run -d --gpus=all --network=dify-net -v ollama:/root/.ollama -p 11434:11434 --name ollama --rm ollama/ollama

- **3. 修改 Dify 的 docker-compose.yml**:
在 `dify/docker/docker-compose.yml` 的末尾添加網路設定，並讓所有服務加入此網路。

        # ... (檔案原有內容) ...
        
        # 在檔案最底部添加
        networks:
          default:
            name: dify-net
            external: true

- **4. 在 Dify 中設定 Ollama**:
完成上述步驟並重啟所有容器後，你在 Dify 的模型供應商 URL 中就可以直接使用 `http://ollama:11434`！

### 二、模型相關建議

1. **如何選擇模型？**
- **大小 vs. 效能**:
- **小型模型 (< 7B)**: 如 `gemma:2b`, `qwen:4b`。速度快、記憶體佔用少，適合快速測試、簡單任務或資源有限的設備。
- **中型模型 (7B ~ 13B)**: 如 `llama3:8b`, `mistral:7b`。在效能和資源消耗之間取得了很好的平衡，是目前的主流選擇。
- **大型模型 (> 30B)**: 如 `llama3:70b`。能力極強，但對硬體要求非常高（通常需要多張高階 GPU），推理速度較慢。
- **量化 (Quantization)**: 你看到的模型標籤（如 `llama3`）通常是經過量化的版本（例如 4-bit）。量化是一種壓縮技術，它能大幅減少模型大小和記憶體佔用，同時對精度的影響很小。對於大多數本地部署場景，使用預設的量化版本即可。

2. **管理多個模型**
Ollama 會在模型第一次被調用時將其載入到 RAM/VRAM 中。同時運行多個模型會消耗大量記憶體。
- **查看已載入模型**: 在終端機執行 `ollama list`，可以看到哪些模型正在運行。
- **釋放資源**: 如果你想切換模型並釋放記憶體，可以先停止 Ollama 服務/容器，然後再重新啟動。

3. **設定 Dify 中的上下文 (Context)**
在 Dify 的應用程式 -> "提示詞編排" -> "模型與參數" 中，你可以設定模型的上下文長度。
- **意義**: 上下文長度決定了模型能「記住」多少對話歷史。
- **建議**: 較長的上下文能讓對話更連貫，但也會在每次請求時消耗更多運算資源。建議從預設值開始，根據應用需求調整。

4. **(進階) 自訂 Ollama Modelfile**
對於進階用戶，你可以建立一個名為 `Modelfile` 的文件來創建模型的自訂版本。這允許您永久修改模型的系統提示 (System Prompt)、溫度 (Temperature) 等參數。

- **範例 `MyLlama3`**:

        FROM llama3

        # 設定預設的系統提示
        SYSTEM """
        You are a helpful and friendly assistant. Always answer in Traditional Chinese.
        """

        # 設定預設的溫度 (0-1, 越高越有創意)
        PARAMETER temperature 0.7

- **創建自訂模型**:

        ollama create MyLlama3 -f ./Modelfile

之後，你就可以在 Dify 中像使用官方模型一樣使用 `MyLlama3` 了。

---

## 🔧 管理與問題排查

- **Ollama 服務管理 (僅限本地安裝)**

    # 停止服務
    sudo systemctl stop ollama

    # 啟動服務
    sudo systemctl start ollama
    
    # 強制結束所有 Ollama 進程
    pkill ollama

- **連線失敗？**
- 再三確認你在 Dify 中填寫的 IP 位址正確。
- 檢查你的電腦防火牆或安全軟體是否阻擋了 11434 連接埠。
- 在終端機使用 `ss -tuln | grep 11434` (Linux/Mac) 或 `netstat -an | findstr 11434` (Windows) 檢查 Ollama 是否正在監聽。

- **如何查看日誌？**

    # 查看 Dify API 服務日誌
    docker logs dify-api-1 
    
    # 查看 Ollama 容器日誌
    docker logs ollama

- **如何停止所有服務？**

    # 停止並刪除 Dify 容器
    cd dify/docker # 確保在正確的目錄
    docker-compose down

    # 停止並刪除 Ollama 容器 (如果使用 Docker 部署)
    docker stop ollama 

現在，你可以開始探索 Dify 強大的功能，例如上傳知識庫進行 RAG、設計複雜的 Prompt 工作流等，而所有的運算都在您的掌控之中。享受您的本地 LLM 之旅吧！