https://github.com/adt109119/llamacpp-distributed-inference

一個基於 llama.cpp 的分佈式 LLM 推理程式，讓您能夠利用區域網路內的多台電腦協同進行大型語言模型的分佈式推理，使用 Electron 的製作跨平台桌面應用程式操作 UI。
https://github.com/adt109119/llamacpp-distributed-inference

distributed-inference distributed-llm gguf llamacpp llm llm-inference rpc

Last synced: 26 days ago
JSON representation

一個基於 llama.cpp 的分佈式 LLM 推理程式，讓您能夠利用區域網路內的多台電腦協同進行大型語言模型的分佈式推理，使用 Electron 的製作跨平台桌面應用程式操作 UI。

• Host: GitHub
• URL: https://github.com/adt109119/llamacpp-distributed-inference
• Owner: ADT109119
• License: apache-2.0
• Created: 2025-07-20T03:15:26.000Z (11 months ago)
• Default Branch: main
• Last Pushed: 2025-07-22T14:47:40.000Z (11 months ago)
• Last Synced: 2025-07-22T16:30:10.328Z (11 months ago)
• Topics: distributed-inference, distributed-llm, gguf, llamacpp, llm, llm-inference, rpc
• Language: JavaScript
• Homepage:
• Size: 297 KB
• Stars: 1
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# 分佈式 LLM 推理桌面應用程式

一個基於 [llama.cpp](https://github.com/ggml-org/llama.cpp) 的分佈式 LLM 推理程式，讓您能夠利用區域網路內的多台電腦協同進行大型語言模型的分佈式推理，使用 Electron 的製作跨平台桌面應用程式操作 UI。

![](banner.png)

## 功能特色

- 🖥️ **現代化介面**: 簡潔專業的深色/明亮模式切換

- 🌐 **智能節點發現**: 自動偵測 + 手動添加，支援定時廣播

- ⚡ **高效分佈式推理**: 本機API伺服器 + 遠程RPC節點協同計算

- 📁 **智能模型管理**: 自動掃描 GGUF 格式模型，支援 GPU 層數調整

- 📊 **實時監控**: 多標籤日誌系統，自動滾動，狀態即時更新

- 🔧 **專業工具**: 節點連接檢查、本機IP顯示、手動節點管理

- 🚀 **跨平台**: 支援 Windows、macOS 和 Linux，統一體驗

![](image.png)

## 系統需求

- Node.js 18+ 

- 支援的作業系統：Windows 10+、macOS 10.15+、Ubuntu 18.04+

- 至少 8GB RAM（取決於模型大小）

- 可選：NVIDIA GPU（用於 GPU 加速）

## 🚀 快速開始

### 方法一：下載預編譯版本（推薦）

1. **下載應用程式**

   - 前往本專案的 [Releases 頁面](../../releases)

   - 下載對應您作業系統的預編譯版本

   - Windows: `llamacpp-distributed-inference-win.zip`

   - macOS: `llamacpp-distributed-inference-mac.zip` (尚無)

   - Linux: `llamacpp-distributed-inference-linux.zip` (尚無)

2. **解壓縮並啟動**

   ```bash

   # Windows

   解壓縮後雙擊 ./分佈式 LLM 推理器.exe

   ```

3. **添加模型檔案**

   - 將 `.gguf` 格式的模型檔案放入 `models/` 資料夾

   - 可從 [Hugging Face](https://huggingface.co/models?library=gguf) 下載

### 方法二：手動編譯版本

1. **下載專案源碼**

   ```bash

   git clone 

   cd llamacpp-distributed-inference

   ```

2. **安裝依賴**

   ```bash

   npm install

   ```

3. **準備 llama.cpp 二進位檔案**

   - 前往 [llama.cpp Releases](https://github.com/ggerganov/llama.cpp/releases)

   - 下載對應平台的編譯版本

   - 解壓縮並將以下檔案放入對應的 `bin/` 資料夾：

     - Windows: `rpc-server.exe`, `llama-server.exe` → `bin/windows/`

     - macOS: `rpc-server`, `llama-server` → `bin/macos/`

     - Linux: `rpc-server`, `llama-server` → `bin/linux/`

4. **準備模型檔案**

   - 將 `.gguf` 格式的模型檔案放入 `models/` 資料夾

5. **啟動應用程式**

   ```bash

   # Windows

   start.bat

   

   # macOS/Linux

   ./start.sh

   ```

## 安裝步驟（開發環境）

### 開發環境

1. **克隆專案**

   ```bash

   git clone 

   cd llamacpp-distributed-inference

   ```

2. **安裝依賴**

   ```bash

   npm install

   ```

3. **準備模型檔案**

   - 將 `.gguf` 格式的模型檔案放入 `models/` 資料夾

   - 可從 [Hugging Face](https://huggingface.co/models?library=gguf) 下載

4. **確認二進位檔案**

   - 確保 `bin/` 資料夾包含對應平台的執行檔

   - 檔案需自行至 https://github.com/ggml-org/llama.cpp/releases 下載

   - Windows: `rpc-server.exe`, `llama-server.exe`

   - Linux/macOS: `rpc-server`, `llama-server`

### 生產環境（打包後）

打包後的應用程式結構：

```

app/

├── resources/

│   ├── bin/               # llama.cpp 執行檔

│   │   ├── windows/

│   │   ├── linux/

│   │   └── macos/

│   └── app/

│       ├── src/

│       ├── models/        # 模型資料夾

│       └── node_modules/

```

**重要說明**：

- 打包時會自動排除 `.gguf` 檔案以減少安裝包大小

- 用戶需要手動將模型檔案放入安裝後的 `models/` 資料夾

- 應用程式會自動檢測並載入 `models/` 資料夾中的 `.gguf` 檔案

## 使用方法

### 開發模式

```bash

npm run dev

```

### 生產模式

```bash

npm start

```

### 打包應用程式

```bash

npm run build

```

## 使用說明

### 🚀 **快速開始**

1. **啟動應用程式**

   - 自動啟動 RPC 伺服器（端口 50052）

   - 顯示本機所有網路介面 IP

   - 開始 mDNS 節點發現（每30秒自動搜尋）

2. **節點管理**

   - **自動發現**: 等待其他節點自動出現

   - **手動添加**: 點擊 "+" 按鈕手動添加節點 IP

   - **連接檢查**: 點擊 WiFi 圖示驗證節點連接

   - **節點選擇**: 使用開關選擇參與計算的遠程節點

3. **模型配置**

   - 從下拉選單選擇 GGUF 模型

   - 調整 GPU 層數滑動條（-ngl 參數）

   - 設定並行請求數（-np 參數，預設1）

   - 設定 API Key（可選，用於保護服務）

   - 自定義模型路徑（點擊資料夾圖示）

4. **啟動分散式推理**

   - 點擊「啟動 API 伺服器」

   - 本機自動作為 API 伺服器參與計算

   - 選中的遠程節點作為 RPC 計算節點

   - 服務在 `http://localhost:8080` 啟動

### 📊 **節點架構說明**

```

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐

│   本機 (API)    │    │  遠程節點 (RPC) │    │  遠程節點 (RPC) │

│  127.0.0.1      │◄──►│  192.168.1.101  │    │  192.168.1.102  │

│  端口: 8080     │    │  端口: 50052    │    │  端口: 50052    │

│  [自動參與]     │    │  [可選擇]       │    │  [可選擇]       │

└─────────────────┘    └─────────────────┘    └─────────────────┘

```

### 🔧 **進階功能**

#### **主題切換**

- 點擊右上角月亮/太陽圖示

- 支援明亮模式（預設）和深色模式

- 設定自動保存

#### **模型路徑管理**

- 點擊資料夾圖示設定自定義模型路徑

- 支援瀏覽器選擇資料夾

- 一鍵開啟模型資料夾

- 自動創建預設 models 資料夾

#### **並行請求控制**

- 滑動條調整並行請求數（1-16）

- 提高 API 伺服器吞吐量

- 根據硬體配置優化性能

#### **節點連接檢查**

- 每個節點都有 WiFi 圖示檢查按鈕

- 自動檢查 RPC 服務（端口 50052）

- 顯示連接狀態氣泡提示

- 定時廣播發現新節點（每30秒）

#### **實時日誌監控**

- **系統日誌**: 應用程式操作和狀態

- **RPC 日誌**: RPC 伺服器運行日誌  

- **API 日誌**: API 伺服器運行日誌

- 自動滾動到最新訊息

- 多標籤切換，顏色區分訊息類型

### 🌐 **API 使用**

#### **OpenAI 相容 API**

```bash

curl -X POST http://localhost:8080/v1/chat/completions \

  -H "Content-Type: application/json" \

  -H "Authorization: Bearer YOUR_API_KEY" \

  -d '{

    "model": "gpt-3.5-turbo",

    "messages": [{"role": "user", "content": "Hello!"}],

    "max_tokens": 100,

    "temperature": 0.7

  }'

```

#### **健康檢查**

```bash

curl http://localhost:8080/health

```

#### **模型資訊**

```bash

curl http://localhost:8080/v1/models

```

## 網路設定

### 🔥 **防火牆設定**

確保以下端口開放：

- **50052**: RPC 伺服器通訊端口（必須）

- **8080**: API 伺服器端口（必須）

- **5353**: mDNS 服務發現端口（建議）

### 🌐 **網路需求**

- **可信內網**: **必須在完全可信的內部網路中運行**

- **網路隔離**: **嚴禁連接到公共網路或不安全網路**

- **同一網段**: 所有節點必須在相同的區域網路內

- **mDNS 支援**: 大部分家用路由器預設支援

- **穩定連接**: 建議使用有線網路以獲得最佳性能

### 💡 **效能建議**

- **GPU 加速**: 設定適當的 GPU 層數（-ngl）

- **記憶體管理**: 確保每個節點有足夠 RAM

- **網路頻寬**: 節點間通訊需要穩定頻寬

- **負載平衡**: 合理分配計算任務到各節點

### ⚠️ **效能限制**

- **木桶效應**: 整體推論速度取決於節點中最慢的裝置

- **瓶頸風險**: 如果有一個裝置特別慢，例如加入了一個僅有CPU沒有GPU的裝置，任務很可能會都卡在那個裝置上

- **建議**: 使用性能相近的設備組成分散式網路，避免性能差異過大

## 故障排除

## 🔧 故障排除

### ❓ **常見問題**

#### **1. 節點發現問題**

- **自動發現失敗**: 

  - 檢查防火牆是否開放端口 5353

  - 確認路由器支援 mDNS 廣播

  - 使用手動添加功能作為替代方案

- **節點連接失敗**:

  - 使用連接檢查功能驗證節點狀態

  - 確認目標設備已啟動此程式

  - 檢查網路連通性

#### **2. 模型相關問題**

- **模型載入失敗**:

  - 確認檔案格式為 `.gguf`

  - 檢查檔案完整性和權限

  - 確保有足夠磁碟空間

- **記憶體不足**:

  - 選擇較小的量化模型（如 Q4_K_M）

  - 調整 GPU 層數設定

  - 增加更多節點分散負載

#### **3. 服務啟動問題**

- **API 伺服器啟動失敗**:

  - 檢查端口 8080 是否被佔用

  - 查看 API 日誌獲取詳細錯誤

  - 確認模型檔案路徑正確

- **RPC 伺服器問題**:

  - 檢查端口 50052 是否可用

  - 查看 RPC 日誌排查問題

  - 重新啟動應用程式

#### **4. 效能優化**

- **推理速度慢**:

  - 增加 GPU 層數（如果有 GPU）

  - 添加更多計算節點

  - 使用更快的網路連接

- **網路延遲高**:

  - 使用有線網路連接

  - 確保節點在同一網段

  - 檢查網路頻寬使用情況

### 🔍 **除錯工具**

#### **內建除錯功能**

- **連接檢查**: 點擊 WiFi 圖示測試節點連接

- **實時日誌**: 查看詳細的系統運行日誌

- **狀態監控**: 即時顯示服務器和節點狀態

- **本機IP顯示**: 確認網路配置正確

#### **命令行工具**

```bash

# 檢查端口佔用

netstat -an | grep :8080

netstat -an | grep :50052

# 測試網路連通性

ping 192.168.1.101

telnet 192.168.1.101 50052

# 檢查 mDNS 服務

# Windows: 使用 Bonjour Browser

# macOS: dns-sd -B _llm-cluster._tcp

# Linux: avahi-browse -rt _llm-cluster._tcp

```

### 📋 **日誌系統**

應用程式提供完整的日誌監控：

- **系統日誌**: 節點發現、連接狀態、操作記錄

- **RPC 日誌**: RPC 伺服器啟動、連接、錯誤訊息

- **API 日誌**: API 伺服器運行、請求處理、推理日誌

- **自動滾動**: 新訊息自動滾動到底部

- **顏色區分**: 成功(綠)、錯誤(紅)、資訊(藍)

### 🎯 **最佳實踐**

#### **部署建議**

1. **網路規劃**: 使用千兆乙太網路連接所有節點

2. **硬體配置**: 確保每個節點有足夠的 RAM 和 GPU

3. **模型選擇**: 根據總記憶體選擇合適的模型大小

4. **負載測試**: 使用少量節點測試後再擴展

#### **安全建議**

> ⚠️ **重要提醒**: 以下建議僅能降低風險，但無法完全消除 RPC 通訊的安全隱患

1. **網路隔離**: 

   - **必須**: 在完全隔離的內網中運行

   - **禁止**: 連接到公共網路或不可信網路

2. **API Key**: 設定強密碼的 API Key 保護 HTTP 介面

3. **防火牆**: 嚴格限制 50052 和 8080 端口的存取來源

4. **監控**: 持續監控網路流量和節點狀態

5. **定期檢查**: 確認所有參與節點都是可信設備

#### **維護建議**

1. **定期更新**: 保持應用程式和模型的最新版本

2. **備份配置**: 備份重要的設定和 API Key

3. **效能監控**: 關注記憶體使用和網路流量

4. **故障恢復**: 準備節點故障的應對方案

## 技術架構

- **前端**: HTML + CSS + JavaScript

- **後端**: Electron (Node.js)

- **推理引擎**: llama.cpp

- **服務發現**: mDNS (bonjour-service)

- **設定儲存**: electron-store

## 開發

### 專案結構

```

├── src/

│   ├── main/           # Electron 主進程

│   ├── preload/        # 預載腳本

│   └── renderer/       # 前端介面

├── bin/                # llama.cpp 二進位檔

├── models/             # 模型檔案

└── package.json

```

## ⚠️ **重要警語與使用限制**

### 🚨 **安全警告**

- **RPC 通訊安全隱患**: 本專案的 RPC 通訊**未加密且缺乏身份驗證**，存在安全風險

- **僅限可信網路**: **請僅在完全可信的網路環境中使用**（如家庭內網、隔離的實驗室網路）

- **禁止公網使用**: **嚴禁在公共網路或不安全的網路環境中運行**，你的電腦很可能會被爆破

### 🎯 **適用場景**

- ✅ **個人使用**: 個人單機 VRAM 不足，但想跑大一點的模型，且確定只有個人使用，不會部署成服務

- ✅ **個人學習和研究**: 在家庭網路中進行 LLM 實驗

- ✅ **概念驗證 (PoC)**: 演示分佈式推理的基本概念

- ✅ **教育用途**: 學習分佈式計算和 LLM 部署

- ✅ **原型開發**: 快速驗證分佈式推理想法

### ❌ **不適用場景**

- ❌ **生產環境部署**: 缺乏企業級安全和穩定性保證

- ❌ **商業用途**: 未經充分的安全審計和壓力測試

- ❌ **公共服務**: 不適合對外提供服務

### 🏭 **生產環境建議**

如需在生產環境中部署 LLM 推理伺服器，建議使用更成熟的解決方案，以獲得更高的安全性與更好的推理效能：

- **[vLLM](https://github.com/vllm-project/vllm)**: 高效能的 LLM 推理引擎

- **[Text Generation Inference](https://github.com/huggingface/text-generation-inference)**: Hugging Face 的推理服務

- **[TensorRT-LLM](https://github.com/NVIDIA/TensorRT-LLM)**: NVIDIA 的優化推理引擎

- **[OpenLLM](https://github.com/bentoml/OpenLLM)**: 企業級 LLM 部署平台

---

### 貢獻指南

1. Fork 專案

2. 創建功能分支

3. 提交變更

4. 發送 Pull Request

## 支援

如有問題或建議，請提交 Issue 或聯繫本人 2.jerry32262686@gmail.com。

## ⚖️ 授權與免責聲明

### 授權

Apache 2.0 License

### 免責聲明

- 本軟體僅供學習、研究和個人使用

- 開發者不對因使用本軟體而導致的任何損失或安全問題承擔責任

- 使用者需自行承擔網路安全風險

- 在使用前請詳細閱讀並理解所有安全警告