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

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

功能特色

🖥️ 現代化介面: 簡潔專業的深色/明亮模式切換
🌐 智能節點發現: 自動偵測 + 手動添加，支援定時廣播
⚡ 高效分佈式推理: 本機API伺服器 + 遠程RPC節點協同計算
📁 智能模型管理: 自動掃描 GGUF 格式模型，支援 GPU 層數調整
📊 實時監控: 多標籤日誌系統，自動滾動，狀態即時更新
🔧 專業工具: 節點連接檢查、本機IP顯示、手動節點管理
🚀 跨平台: 支援 Windows、macOS 和 Linux，統一體驗

系統需求

Node.js 18+
支援的作業系統：Windows 10+、macOS 10.15+、Ubuntu 18.04+
至少 8GB RAM（取決於模型大小）
可選：NVIDIA GPU（用於 GPU 加速）

🚀 快速開始

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

下載應用程式
- 前往本專案的 Releases 頁面
- 下載對應您作業系統的預編譯版本
- Windows: llamacpp-distributed-inference-win.zip
- macOS: llamacpp-distributed-inference-mac.zip (尚無)
- Linux: llamacpp-distributed-inference-linux.zip (尚無)

解壓縮並啟動

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

添加模型檔案
- 將 .gguf 格式的模型檔案放入 models/ 資料夾
- 可從 Hugging Face 下載

方法二：手動編譯版本

下載專案源碼

git clone <repository-url>
cd llamacpp-distributed-inference

安裝依賴
```
npm install
```
準備 llama.cpp 二進位檔案
- 前往 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/
準備模型檔案
- 將 .gguf 格式的模型檔案放入 models/ 資料夾

啟動應用程式

# Windows
start.bat

# macOS/Linux
./start.sh

安裝步驟（開發環境）

開發環境

克隆專案

git clone <repository-url>
cd llamacpp-distributed-inference

安裝依賴
```
npm install
```
準備模型檔案
- 將 .gguf 格式的模型檔案放入 models/ 資料夾
- 可從 Hugging Face 下載
確認二進位檔案
- 確保 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 檔案

使用方法

開發模式

npm run dev

生產模式

npm start

打包應用程式

npm run build

使用說明

🚀 快速開始

啟動應用程式
- 自動啟動 RPC 伺服器（端口 50052）
- 顯示本機所有網路介面 IP
- 開始 mDNS 節點發現（每30秒自動搜尋）
節點管理
- 自動發現: 等待其他節點自動出現
- 手動添加: 點擊 "+" 按鈕手動添加節點 IP
- 連接檢查: 點擊 WiFi 圖示驗證節點連接
- 節點選擇: 使用開關選擇參與計算的遠程節點
模型配置
- 從下拉選單選擇 GGUF 模型
- 調整 GPU 層數滑動條（-ngl 參數）
- 設定並行請求數（-np 參數，預設1）
- 設定 API Key（可選，用於保護服務）
- 自定義模型路徑（點擊資料夾圖示）
啟動分散式推理
- 點擊「啟動 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

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
  }'

健康檢查

curl http://localhost:8080/health

模型資訊

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顯示: 確認網路配置正確

命令行工具

# 檢查端口佔用
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 伺服器運行、請求處理、推理日誌
自動滾動: 新訊息自動滾動到底部
顏色區分: 成功(綠)、錯誤(紅)、資訊(藍)

🎯 最佳實踐

部署建議

網路規劃: 使用千兆乙太網路連接所有節點
硬體配置: 確保每個節點有足夠的 RAM 和 GPU
模型選擇: 根據總記憶體選擇合適的模型大小
負載測試: 使用少量節點測試後再擴展

安全建議

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

網路隔離:
- 必須: 在完全隔離的內網中運行
- 禁止: 連接到公共網路或不可信網路
API Key: 設定強密碼的 API Key 保護 HTTP 介面
防火牆: 嚴格限制 50052 和 8080 端口的存取來源
監控: 持續監控網路流量和節點狀態
定期檢查: 確認所有參與節點都是可信設備

維護建議

定期更新: 保持應用程式和模型的最新版本
備份配置: 備份重要的設定和 API Key
效能監控: 關注記憶體使用和網路流量
故障恢復: 準備節點故障的應對方案

技術架構

前端: 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: 高效能的 LLM 推理引擎
Text Generation Inference: Hugging Face 的推理服務
TensorRT-LLM: NVIDIA 的優化推理引擎
OpenLLM: 企業級 LLM 部署平台

貢獻指南

Fork 專案
創建功能分支
提交變更
發送 Pull Request

支援

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

⚖️ 授權與免責聲明

授權

Apache 2.0 License

免責聲明

本軟體僅供學習、研究和個人使用
開發者不對因使用本軟體而導致的任何損失或安全問題承擔責任
使用者需自行承擔網路安全風險
在使用前請詳細閱讀並理解所有安全警告

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.github/workflows		.github/workflows
images		images
models		models
scripts		scripts
src		src
.gitignore		.gitignore
BUILD.md		BUILD.md
DEVELOPMENT.md		DEVELOPMENT.md
LICENSE		LICENSE
README.md		README.md
RELEASE.md		RELEASE.md
banner.png		banner.png
image.png		image.png
package-lock.json		package-lock.json
package.json		package.json
start.bat		start.bat
start.sh		start.sh

License

ADT109119/llamacpp-distributed-inference

Folders and files

Latest commit

History

Repository files navigation

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

功能特色

系統需求

🚀 快速開始

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

方法二：手動編譯版本

安裝步驟（開發環境）

開發環境

生產環境（打包後）

使用方法

開發模式

生產模式

打包應用程式

使用說明

🚀 快速開始

📊 節點架構說明

🔧 進階功能

主題切換

模型路徑管理

並行請求控制

節點連接檢查

實時日誌監控

🌐 API 使用

OpenAI 相容 API

健康檢查

模型資訊

網路設定

🔥 防火牆設定

🌐 網路需求

💡 效能建議

⚠️ 效能限制

故障排除

🔧 故障排除

❓ 常見問題

1. 節點發現問題

2. 模型相關問題

3. 服務啟動問題

4. 效能優化

🔍 除錯工具

內建除錯功能

命令行工具

📋 日誌系統

🎯 最佳實踐

部署建議

安全建議

維護建議

技術架構

開發

專案結構

⚠️ 重要警語與使用限制

🚨 安全警告

🎯 適用場景

❌ 不適用場景

🏭 生產環境建議

貢獻指南

支援

⚖️ 授權與免責聲明

授權

免責聲明

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Languages

Packages