今天要讓後端第一次真正開口說英文。
流程設計
/chat 的流程很單純：接收使用者訊息與情境 → 組合 Prompt → 呼叫 LLM → 解析 JSON → 回傳給前端。每一步都先想清楚輸入與輸出，寫起來就不會亂。
遇到的問題
最大的狀況是 AI 偶爾回傳不完整的 JSON，導致解析失敗。我加上錯誤處理，失敗時回傳預設訊息，並用自動產生的 /docs 頁面反覆測試，確認各種情況都不會讓服務崩潰。
踩雷一：建立 .env 時，終端機沒有反應
照著步驟建立 .env 時，貼上指令後終端機沒有任何反應。整理出四個要先排除的原因：

1. cp、cd 這類指令成功時本來就不會輸出訊息，沒有訊息就代表成功。
2. 同一個視窗如果還在執行 uvicorn，視窗就被佔用，新指令不會執行。要按 Control + C 停止，或按 Command + T 開新分頁。
3. Mac 的 zsh 不會把 # 當成註解，連註解一起貼上會被當成參數，所以要一行一行輸入。
4. .env 以點開頭，Finder 預設會隱藏，按 Command + Shift + . 才看得到。
   用 ls -a 列出檔案，是確認 .env 有沒有建立成功最快的方法。
   踩雷二：設定檢查工具連續失敗兩次
   編輯好 .env 之後，我用 check_llm.py 檢查連線，前後失敗兩次，原因不一樣：
   • 第一次：顯示 LLM_MODEL is not set。Claude 有預設模型，但 Gemini 和 OpenAI 必須自己指定模型名稱。對照 Google 官方模型頁目前列出的名稱，我填入 gemini-3.5-flash-lite。
   • 第二次：顯示 HTTP 400「Please pass a valid API key」，也就是金鑰無效。Gemini 對無效金鑰回的是 400，而不是常見的 401，所以第一版檢查工具沒有給出對應提示。
   修正金鑰設定後，終於看到「✔ 連線成功」，後端啟動時也印出 LLM_PROVIDER=gemini。檢查工具之後補上金鑰格式檢查，會提醒空白、引號、全形字元這些肉眼看不出來的問題，而且不會顯示完整金鑰。
   小結
   與 AI 串接時，不能假設輸出永遠正確，容錯設計和功能本身一樣重要。另外也學到，整合外部服務時最先出問題的往往不是程式，而是設定。與其反覆猜測，不如做一個能一鍵檢查「設定有沒有生效」的工具，並讓錯誤訊息直接說明下一步。