README.md

metadata

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+，並在終端機執行：

pip install -r requirements.txt

2. 設定環境變數

請編輯同目錄下的 .env 檔案，填入您的 LINE Bot 金鑰（您可以前往 LINE Developers Console 取得）：

LINE_CHANNEL_ACCESS_TOKEN=你的Channel_Access_Token
LINE_CHANNEL_SECRET=你的Channel_Secret
DEFAULT_TARGET_ID=你的UserID或GroupID_供測試推播用(選填)

3. 啟動 Local 服務

python app.py

此時服務會運行在 http://localhost:7860。

4. 使用 ngrok 進行外部通道測試 (選填)

LINE Webhook 必須使用 HTTPS 網址。您可以使用 ngrok 將本地服務對外公開：

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 並登入。
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：

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