樹莓派5建立自己的AI(LLM)主機獨立運算主機

10月 09, 2025

直接上成品：https://youtu.be/do7OHwPtWAo?si=Z4H75k6f7lYmzIpC

這段時間用樹莓派5裝了一個Ai(LLM)主機，算是實做的邊緣運算(edge computing)，在使用上如果是網頁版的使用方式，回覆速度是真的不慢!但回覆的內容存在嚴重的幻覺，所以只是裝好了載台，後續的FineTune才會是重點!!

現在先分享怎麼建立的，希望之後可以直接套用GPIO，並建立自己的機器人：

硬體規格：樹莓派 Raspberry Pi 5 Model B / 8G 超值組 (含 Pi 5/8GB 主機、原廠認證 64G A2記憶卡、官方原廠電源、外殼、官方原廠 HDMI 線) - 搭配 EDA被動式散熱外殼

模型：Gemma 2B(來源：hugginface)

特性：可以斷外部網路，並由自己或是同個封閉網路內使用

待解問題：電池續航

相關步驟：

文件目的： 本手冊旨在指導開發人員在 Raspberry Pi 5 (16GB RAM) 上，從零開始部署一個由 llama.cpp 驅動、以 Gemma-2B-IT 為模型的本地大型語言模型，並最終以網頁介面形式提供服務。

最後更新時間： 2025年10月9日

文件目的：本手冊旨在指導開發人員在 Raspberry Pi 5 (16GB RAM) 上，從零開始部署一個由 `llama.cpp` 驅動、以 `Gemma-2B-IT` 為模型的本地大型語言模型，並最終以網頁介面形式提供服務。
最後更新時間： 2025年10月9日

第 1 章：環境準備與設定

在開始之前，請確保硬體與系統環境已準備就緒。

1.1 硬體需求

主機: Raspberry Pi 5 (建議 8GB RAM 或以上版本，本手冊使用 16GB 版本)。
電源供應器: [極度重要] 必須使用官方或同等規格的 5V/5A (27W) USB-C PD 電源供應器，以避免在高負載下因電壓不足而自動重啟。
散熱: [極度重要] 必須安裝主動式散熱裝置（如官方 Active Cooler 風扇），以防止 CPU 在高強度運算下過熱降頻或重啟。
儲存: 高速 MicroSD 卡 (建議 Class 10, A2 等級, 32GB 或以上)。

1.2 系統與套件更新

首次開機後，請先更新系統套件列表與已安裝套件。

sudo apt update
sudo apt full-upgrade -y

第 2 章：核心框架 `llama.cpp` 的安裝與編譯

`llama.cpp` 是我們用來在 CPU 上高效運行模型的 C++ 框架。

2.1 安裝編譯所需依賴套件

# 安裝基礎編譯工具、Git、CMake 以及 llama.cpp 需要的 CURL 函式庫
sudo apt install -y git build-essential cmake libcurl4-openssl-dev

2.2 下載 `llama.cpp` 原始碼

從 GitHub 複製最新的專案原始碼。

cd ~
git clone [https://github.com/ggerganov/llama.cpp.git](https://github.com/ggerganov/llama.cpp.git)

2.3 使用 CMake 進行編譯

新版的 llama.cpp 使用 CMake 系統進行編譯。

# 進入 llama.cpp 目錄
cd ~/llama.cpp

# 建立一個獨立的 build 資料夾並進入，這是 CMake 的標準做法
mkdir build
cd build

# 執行 CMake 來設定專案
cmake ..

# 執行編譯指令，這會花費數分鐘時間
cmake --build .

編譯完成後，所有可執行檔（包括我們需要的 llama-cli 和 llama-server）會被放置在 ~/llama.cpp/build/bin/ 目錄下。

第 3 章：下載 Gemma AI 模型

我們將使用 Hugging Face 平台來下載模型檔案。

3.1 安裝 Hugging Face Hub 工具

# 此指令會將工具安裝至使用者目錄
pip install -U huggingface_hub --break-system-packages

3.2 設定環境變數 (重要)

為了讓系統能直接找到剛剛安裝的指令，需要將使用者安裝路徑加入 PATH。

# 將 PATH 設定指令加入 .bashrc，使其永久生效
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

# 立即重新載入 .bashrc 使其在當前視窗生效
source ~/.bashrc

3.3 登入 Hugging Face

取得 Token: 前往 Hugging Face Access Tokens 頁面，產生一個新的 read 權限 token 並複製。
在樹莓派登入:
```
huggingface-cli login
```
接著，貼上您剛剛複製的 hf_... token 並按下 Enter。

3.4 同意模型使用條款

授權存取: 前往 Gemma 模型頁面 (lmstudio-ai/gemma-2b-it-GGUF)。
勾選同意框並點擊 "Access repository" 按鈕。

3.5 下載模型檔案

# 建立一個專門存放模型的資料夾
mkdir -p ~/llm-models

# 使用 hf download 指令下載 GGUF 格式的模型檔案
hf download \
  lmstudio-ai/gemma-2b-it-GGUF \
  gemma-2b-it-q4_k_m.gguf \
  --local-dir ~/llm-models

下載完成後，模型檔案會存放在 ~/llm-models/ 目錄下。

第 4 章：啟動與使用

4.1 啟動網頁伺服器模式

這是最推薦的使用方式，可以讓區域網路內任何裝置透過瀏覽器連線。

# 執行 llama-server 程式
~/llama.cpp/build/bin/llama-server -m ~/llm-models/gemma-2b-it-q4_k_m.gguf --chat-template gemma --host 0.0.0.0 --port 8080

--host 0.0.0.0: 允許來自任何 IP 的連線。
--port 8080: 指定服務運行的通訊埠。

4.2 連線使用

取得樹莓派 IP: 在新的終端機視窗輸入 `hostname -I`，記下顯示的 IP 位址 (例如 `192.168.1.15`)。
連線: 在同一區域網路下的任何電腦或手機，打開瀏覽器，輸入 `http://<你的樹莓派IP>:8080`。

4.3 如何停止伺服器

在運行 `llama-server` 的終端機視窗中，按下 `Ctrl` + `C` 即可停止服務。

第 5 章：建立啟動腳本 (可選，但建議)

為了方便日後啟動，可以建立一個腳本。

5.1 建立腳本檔案

nano ~/start_gemma_server.sh

5.2 寫入腳本內容

將以下內容完整複製並貼上到 nano 編輯器中：

#!/bin/bash
/home/windsongiove/llama.cpp/build/bin/llama-server -m /home/windsongiove/llm-models/gemma-2b-it-q4_k_m.gguf --chat-template gemma --host 0.0.0.0 --port 8080

注意： 腳本中的 /home/windsongiove/ 是您的家目錄路徑，請根據實際情況確認。

5.3 儲存並賦予權限

在 nano 中，按下 Ctrl + X，接著按 Y，再按 Enter 儲存退出。
賦予腳本執行權限：
```
chmod +x ~/start_gemma_server.sh
```

5.4 日後啟動

未來只需要執行以下指令即可啟動伺服器：

~/start_gemma_server.sh