| --- |
| 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` 可立即手動觸發一次推播測試。 |
|
|
