---
title: AI Advance Final Project
emoji: 🏢
colorFrom: red
colorTo: green
sdk: docker
pinned: false
license: mit
short_description: Final Project's Line bot Server
---

# Hugging Face Space LINE Bot (FastAPI)

這是一個精美且架構完整的 LINE Bot 範例，專為部署於 **Hugging Face Spaces**（或任何支援 Python 容器的平台）設計。本專案使用 Python **FastAPI** 與最新的 **`line-bot-sdk` v3**。

---

## ✨ 核心功能特色
1. **精準群組 @ 提及過濾**：在群組中，Bot 會自動比對 LINE 內建的 `@提及` 元資料（透過 Bot 本身 `userId` 進行安全比對）與名稱文字，只有在被 `@` 時才進行回覆，避免干擾群組對話。
2. **模擬 Diffusion 圖片生成**：當在對話中收到包含 `@create image` 的訊息時，Bot 會自動回覆美麗的模擬生成圖片與預覽圖。
3. **雙重排程主動推播（Push Message）架構**：
   - **背景執行緒排程**：內建一個背景 thread，每隔隨機時間區間（預設為 30 分鐘至 2 小時隨機）自動向活躍群組或使用者推播關懷訊息。
   - **外部 Cron 端點**：預留 `/cron/push` 的 HTTP GET/POST 路由，可配合外部 cron 服務（例如 Hugging Face Space 自身的 Cron 功能、GitHub Actions、UptimeRobot 等）進行定時戳記。
4. **超酷 Web Dashboard**：首頁設有採用 Glassmorphism（玻璃擬物化）風格的精美儀表板，當您直接瀏覽 Space 的網頁時，可即時確認 Bot 的連線狀態、環境變數設定狀態以及目前活躍的推播目標數。
5. **防止 LINE 逾時機制**：使用 FastAPI 的 `BackgroundTasks`，在驗證簽章後立即回覆 LINE 平台 HTTP 200，並在背景處理對話與回覆邏輯，徹底解決 LINE 平台要求的 1-2 秒內必須回覆造成的 Timeout 問題。

---

## 📂 檔案目錄說明
- `app.py`：FastAPI 主程式，包含路由設計、Webhook 簽章驗證、@ 提及比對邏輯、圖片回覆與背景推播排程器。
- `requirements.txt`：列出專案所依賴的套件。
- `.env`：環境變數範本檔（填寫金鑰用）。

---

## 🛠️ 本地開發與測試步驟

### 1. 安裝套件
請確保安裝了 Python 3.9+，並在終端機執行：
```bash
pip install -r requirements.txt
```

### 2. 設定環境變數
請編輯同目錄下的 `.env` 檔案，填入您的 LINE Bot 金鑰（您可以前往 [LINE Developers Console](https://developers.line.biz/) 取得）：
```env
LINE_CHANNEL_ACCESS_TOKEN=你的Channel_Access_Token
LINE_CHANNEL_SECRET=你的Channel_Secret
DEFAULT_TARGET_ID=你的UserID或GroupID_供測試推播用(選填)
```

### 3. 啟動 Local 服務
```bash
python app.py
```
此時服務會運行在 `http://localhost:7860`。

### 4. 使用 ngrok 進行外部通道測試 (選填)
LINE Webhook 必須使用 HTTPS 網址。您可以使用 ngrok 將本地服務對外公開：
```bash
ngrok http 7860
```
取得 ngrok 產生的 `https://xxxx.ngrok-free.app` 網址後，在 LINE Developer Console 的 Webhook URL 欄位填入：
`https://xxxx.ngrok-free.app/callback` 並點擊 **Verify**。

---

## 🚀 部署至 Hugging Face Space

Hugging Face Spaces 提供極為便利的 FastAPI (Docker/Python) 部署方式：

### 1. 建立 Space
1. 前往 [Hugging Face](https://huggingface.co/) 並登入。
2. 點擊右上角個人頭像，選擇 **New Space**。
3. 輸入 Space 名稱。
4. **SDK 選擇**: 選擇 **Docker** 或是 **Blank** (如果您想用預設的 Python SDK)。
   - *推薦做法*：SDK 選擇 **Docker** ➡️ 範本選擇 **FastAPI**，這最適合運行自訂 FastAPI 專案。
   - 或者選擇 **Blank**，然後在上傳檔案時加入 `Dockerfile`（如下方說明）。

### 2. 設定 Secrets (關鍵步驟 🔒)
為了安全起見，請**不要**將金鑰寫死在 `.env` 中並推送到 Hugging Face（因為 Space 預設可能是公開的）。
1. 在您剛建立好的 Space 頁面中，點擊 **Settings** 頁籤。
2. 往下滾動找到 **Variables and Secrets** 區塊。
3. 點擊 **New secret** 按鈕，新增以下兩個 Secrets：
   - Name: `LINE_CHANNEL_ACCESS_TOKEN` / Value: `(您的 LINE Channel Access Token)`
   - Name: `LINE_CHANNEL_SECRET` / Value: `(您的 LINE Channel Secret)`
   - (選填) Name: `DEFAULT_TARGET_ID` / Value: `(您的 LINE User ID 或測試群組 ID)`

### 3. 上傳檔案
將 `app.py`、`requirements.txt` 上傳至您的 Space 儲存庫即可。
如果您使用的是 Docker 模式，請上傳以下內容的 `Dockerfile`：

```dockerfile
# Read the doc: https://huggingface.co/docs/hub/spaces-sdks-docker
# you will also find guides on how best to write your Dockerfile

FROM python:3.9

# Create a non-root user with UID 1000 to comply with Hugging Face Space security guidelines
RUN useradd -m -u 1000 user

# Set up environment variables for the new user
ENV HOME=/home/user \
    PATH=/home/user/.local/bin:$PATH

# Set the working directory to user's home app directory
WORKDIR $HOME/app

# Switch to the non-root user
USER user

# Copy requirements and install dependencies
COPY --chown=user requirements.txt requirements.txt
RUN pip install --no-cache-dir --upgrade -r requirements.txt

# Copy all project files into the container
COPY --chown=user . .

# Expose port 7860 (Hugging Face Spaces default port)
EXPOSE 7860

# Run the FastAPI application using uvicorn
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]
```

上傳完成後，Hugging Face 會自動編譯並啟動您的 Space！

### 4. 設定 LINE Webhook
當 Space 狀態顯示為 **Running** 後：
1. 複製您 Space 的 App 網址（通常格式為 `https://[使用者名稱]-[Space名稱].hf.space`）。
2. 在 LINE Developer Console 的 Webhook URL 填入：
   `https://[使用者名稱]-[Space名稱].hf.space/callback`
3. 儲存並啟用 **Use Webhook**。

---

## 💬 測試 Bot
1. 將 Bot 邀請入群組或直接與其私訊。
2. 在群組中打：`@Bot名稱 測試看看`，Bot 會回覆。
3. 在群組中打：`@create image`，Bot 會回覆一張生成好的模擬圖片！
4. 訪問 `https://[您的HF_SPACE_URL]/cron/push` 可立即手動觸發一次推播測試。