技術人員說明文檔

本文件說明阿斯頓 AI 客服機器人的主要功能、後台操作、API 使用方式、安全機制與部署注意事項。

系統定位

這個網站是一套單租戶 AI 客服系統。對外提供聊天問答與人工接手能力；對內提供設定、知識匯入、資料治理、模型切換、安全管理與日誌追蹤。

主要資料分成三類：站點設定保存在 data/config.json；聊天、記憶與待處理單保存在記憶資料庫；RAG 文件與知識圖譜保存在知識資料庫。

公開 API

`POST /ask`

前端聊天入口。傳入 query、session_id，可選 provider。系統會先嘗試快速意圖、RAG、知識圖譜，再呼叫選定模型產生回答。

curl -X POST http://chatbot.aston.tw/ask \
  -H "Content-Type: application/json" \
  -d '{"query":"請問營業時間？","session_id":"demo"}'

`GET /handoff/replies`

前端可輪詢人工補答結果，用於把 Telegram 管理員回覆推回原使用者畫面。

`POST /location/update`

手機捷徑或外部工具可用 token 更新目前位置，系統會寫入知識圖譜，回答位置相關問題。

`GET /health`

健康檢查只返回基本狀態與是否已配置，避免暴露內部細節。

管理後台

未登入時只會看到品牌首頁、登入頁與本技術文檔。登入後可進入 /menu 與後台功能。

/admin/setup：站點、模型、Telegram、資料保留與價格設定。
/menu：功能入口總覽，包含測試、資料、日誌與模型管理。
/playground/chat：模擬使用者提問，檢查回答、來源與模型輸出。
/admin/data：匯出、匯入或清理聊天歷史、記憶、RAG 與知識圖譜。
/admin/security：管理密碼、OTP 與登入狀態。
/admin/audit-logs：查看管理員登入與後台修改紀錄。

RAG 與知識圖譜

RAG 文件

可透過後台或 API 新增文字、單一 URL、sitemap。URL 匯入會檢查協議、DNS 與私有網段，避免 SSRF 類風險。

curl -X POST http://chatbot.aston.tw/add \
  -H "Content-Type: application/json" \
  -d '{"text":"客服時間為週一到週五 09:00-18:00。","source":"manual","category":"faq"}'

知識圖譜

用於保存價格、電話、地址、營業時間、社群帳號、付款方式等結構化資料。這類資料對短問句和精準問答特別有用。

/playground/kg 可手動新增三元組；/setup/confirm 有基本資料快速建檔工具；/admin/kg 可修改、刪除與匯出。

Telegram 整合

系統可用 polling 或 webhook 與 Telegram bot 通信。當使用者問題超出知識庫、命中敏感資料或需要人工確認時，會通知管理員。

管理員可以直接回覆 Telegram 待處理訊息；系統會把補答送回使用者，也可把答案寫入 RAG。若回覆包含 知識圖譜: 區塊，會嘗試拆成結構化三元組。

Webhook 模式會驗證 Telegram secret token，降低假 webhook 請求風險。

安全設定

後台路由預設需要管理員 session；公開路由僅包含品牌頁、文檔、登入與必要 API。
管理員密碼使用 PBKDF2 SHA256 雜湊，可綁定 Google Authenticator OTP。
後台表單與非 GET fetch 使用 CSRF token 保護。
/ask、/handoff/replies、/location/update 有公開速率限制。
請求 body 有大小限制，避免大 payload 壓垮服務。
RAG URL 匯入阻擋 localhost、私有網段與非 HTTP/HTTPS URL。
受保護頁面會加上安全 header 與 no-store cache header。

觀測與效能

/admin/observability 提供本地模型佇列、OpenAI 佇列、fallback、token 成本、向量索引與搜尋統計。/admin/model-switch 可切換本地 Ollama 或 OpenAI 模型。

為降低瓶頸，系統有單 session 訊息合併、模型佇列上限、OpenAI 並發控制、資料保留清理與資料庫索引。若流量增加，優先檢查模型佇列深度、RAG 搜尋耗時與資料庫大小。

部署與維運

此站點應透過 reverse-proxy 暴露，不直接把服務容器 port 開到 host。Docker 服務需加入 proxy network，並由反向代理處理網域 chatbot.aston.tw。

變更 compose 後需執行 docker compose config 驗證。一般程式碼變更不需要修改 compose。

維運建議：定期匯出 RAG 與知識圖譜、檢查 /admin/audit-logs、清理過期聊天資料、檢查 Telegram webhook 或 polling 狀態，並在更新模型或 API key 後用 /playground/chat 做端到端測試。