🧠【Day 22】AI 助理的本地部署實戰與陷阱分析

🚀 前言：那個「要不要部署在本地」的靈魂拷問

到了這一天，我們的 AI 助理已經能對話、能呼叫外部 API、能幫你整理文件。
但問題來了：

「如果這些對話都送到雲端，真的安全嗎？」
「公司能允許我們把內部資料丟到外部模型嗎？」
「我能不能讓整個助理在自己的機器上跑？」

這篇文章，我要把自己這幾天在「本地部署」這條路上的踩坑、實驗與思考，一次整理出來。

🎯 本日目標

• 理解「完全本地」與「混合部署」兩種策略的差異
• 學會如何用 LangGraph 串接本地模型服務（例如 Hugging Face TGI）
• 實際啟動一個能離線運行的 AI 助理
• 了解部署後的維運與安全考量

🤔 一開始的懷疑：雲端真的不能用嗎？

我原本也是那種「一定要全本地」的信徒。
但實際比較過才發現：

後來我發現，混合部署 才是現實世界的解法。
我們可以讓 應用邏輯 在本地，模型推理 則依情境選擇雲端或本地模型。

🧩 部署架構概念圖

+---------------------------------------+

本地應用 (LangGraph)

- Agent Workflow
- 工具 / 記憶 / Prompt 管理
- 接 Gemini 或本地模型 API
+---------------------------------------+


│
            │ REST / WebSocket
            ▼

+---------------------------------------+

本地模型伺服器 (TGI/vLLM)

- Hugging Face TGI (Docker)
- Llama.cpp / GGUF / 量化模型
+---------------------------------------+

🧪 實作 Part 1：Hybrid（本地邏輯 + 雲端 Gemini）

這是最輕量的方式，也是我最推薦初學者的起點。

步驟 1：安裝 Gemini CLI

npm install -g @google/gemini-cli
gemini login

提醒：Gemini CLI 本身只是「操作介面」，模型仍在 Google 雲端上。
你可以用 GEMINI_API_KEY 或 OAuth 登入。

步驟 2：建立 LangGraph 專案

pip install langgraph
langgraph new my_ai_assistant

編輯 .env 加入：

GEMINI_API_KEY=你的_API_KEY

步驟 3：串接 Gemini 模型

在 LangGraph 中加入以下 Python 代碼：

from langchain_google_genai import ChatGoogleGenerativeAI

model = ChatGoogleGenerativeAI(model="gemini-2.5-flash")
response = model.invoke("你好，今天的部署任務是什麼？")
print(response.content)

就能快速呼叫 Gemini。
優點： 開發快、延遲低。
缺點： 資料還是上雲。

🏗️ 實作 Part 2：完全本地部署（TGI + LangGraph）

如果你想完全離線運行，這才是你要走的路。

步驟 1：安裝 Docker 與 GPU 驅動

確認 Docker + NVIDIA Container Toolkit 已安裝。

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

步驟 2：建立 docker-compose.yml

version: "3.8"
services:
  tgi:
    image: ghcr.io/huggingface/text-generation-inference:latest
    command: >
      --model-id meta-llama/Llama-2-7b-chat-hf
      --hostname 0.0.0.0 --port 80
    ports:
      - "8080:80"
    environment:
      - HF_API_TOKEN=${HF_API_TOKEN}

  langgraph:
    build: ./backend
    depends_on:
      - tgi
    environment:
      - TGI_URL=http://tgi:80
    ports:
      - "8000:8000"
    command: ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

執行：

export HF_API_TOKEN=你的_HuggingFace_Token
docker-compose up --build

步驟 3：在 LangGraph 呼叫本地模型

from langchain_huggingface import HuggingFaceTextGenInference

llm = HuggingFaceTextGenInference(
    inference_server_url="http://localhost:8080",
    max_new_tokens=128,
    temperature=0.7,
)
response = llm.invoke("部署成功了嗎？")
print(response)

如果成功，你就完成一個 完全本地的 AI 助理環境 🎉

🧮 延伸主題：量化與模型選擇

模型類型 檔案大小 適合環境

Llama 2 7B (FP16) 約 13 GB 單 GPU
Llama 2 7B (GGUF Q4) 約 4 GB CPU 可用
Mistral 7B 約 12 GB 單 GPU
Phi-3-mini 約 3.8 GB 輕量應用

想用 CPU 跑？那你一定要學會 量化 (Quantization)。
可用工具：llama.cpp
轉換指令：

./convert.py models/llama-2-7b/ --to-gguf
./quantize ./llama-2-7b.gguf ./llama-2-7b.Q4.gguf Q4_K_M

🧩 實際踩雷紀錄（血淚篇）

1. OOM（Out of Memory）：第一次跑 13B 模型在 16GB RAM 筆電上，直接崩潰。
   → 解法：改跑 7B GGUF 量化版本。

2. 容器死循環重啟：model not found。
   → 原因：HF token 沒設環境變數。

3. Port 被佔用：LangGraph 跟 TGI 搶 port。
   → 改 compose 設定。

🔍 部署不是終點，而是開始

部署後你還得考慮：

✅ 監控（Prometheus / Grafana）

🔐 安全性（不要讓 :8080 暴露到外網）

🧾 成本（本地 GPU 電費、風扇聲、碳排…）

「本地部署」聽起來自由，其實是換來責任的自由。

💬 結語：技術浪漫的盡頭是維運

我曾以為「只要模型跑在我自己的機器上，我就贏了」。
但經過幾天測試，我學到一件更重要的事：

部署不是炫技，而是一種持續責任。

本地部署讓你擁有完整控制權，也讓你成為唯一的救火隊。
不過，只要懂得取捨，這條路依然值得探索。

🔧 下一篇預告：Day 23 — 雲端部署實戰（Vercel × Gemini × LangGraph）

我們將把今天的本地助理，打包成可公開使用的雲端應用。
要讓你的 AI 助理從「開發機」走向「世界」，別錯過明天。