前情提要：前面幾篇我們把腦袋練起來（Prompt、記憶、RAG）。接下來要把它變成 能佈署、能監控、能管成本 的雲端系統。這篇先不急著寫程式，先用 GCP 的觀念把整體藍圖定下來。

flowchart LR
  subgraph Client ["前端 / 第三方服務"]
    F1[Web / App (BFF)] -- WebSocket/HTTP --> GW
  end

  subgraph CloudRun ["Cloud Run (多服務)"]
    GW[api-gateway\n(認證/流量控管/路由)] -->|同步| CHAT[chat-service\n(會話控制/個人化)]
    CHAT -->|查詢| MEM[mem-service\n(短/長期記憶)]
    CHAT -->|檢索| RAG[rag-service\n(檔案/RAG/向量查詢)]
    CHAT -->|工具| TOOL[tool-service\n(外部API/任務調度)]
    CHAT -->|非同步事件| BUS[(Pub/Sub)]
    BUS --> WORK[worker-service\n(重計算/回呼/回補)]
  end

  subgraph Data ["資料與AI"]
    VDB[(向量DB/BigQuery/Datastore)]
    SQL[(Cloud SQL/PostgreSQL)]
    SECRETS[(Secret Manager/KMS)]
    GEM[Vertex AI Gemini API]
    APP[AI Applications\n(原 Agent Builder)]
  end

  RAG <--> VDB
  MEM <--> SQL
  TOOL -->|受控| 外部API[(內外部系統)]
  CHAT -->|同步/非同步| GEM
  CHAT --> APP
  GW --> SECRETS
  CHAT --> SECRETS

核心重點

• 同步路徑：Client → Gateway → chat-service 最多兩跳內回應（ACK/快速答案/查快取）。
• 非同步路徑：複雜檢索、慢工具、長上下文整合 → 丟 Pub/Sub，由 worker-service 回補（WS 推播或回呼）。
• 各服務單一職責：chat（會話/協調）、mem（記憶）、rag（檢索）、tool（外部動作）、worker（重計算/回補）。

2) 先畫「邊界」再談實作

邊界一：同步 vs 非同步

• 同步：使用者可感知的即時回饋（< 1~2 秒）。

  例：回「我收到你的問題、正在處理」、簡短答案、快取命中。

• 非同步：資料檢索、工具呼叫、向量查詢、模型長回應。

  例：RAG 完整答案、跨系統工作流程、LLM 產製多步結果。

邊界二：使用者記憶 vs 知識庫

• 記憶（mem-service）：個人資料、偏好、最近對話摘要。

• 知識庫（rag-service）：文件、FAQ、規範、手冊。

  兩者都會影響回答，但存放與生命週期不同，不可混用一個 DB。

邊界三：模型直連 vs AI Applications

• 直連 Gemini API：快速原型、客製化高。
• AI Applications：多工具、多步驟、可視化管理、（未來）團隊協作；進階篇用它做複雜流程。

3) 服務職責表

原則：每個服務都有「你只做這件事」的一句話。模糊就會耦合。

4) 兩條資料流：同步 ACK 與非同步完成

同步（ACK + 快速回應）

sequenceDiagram
  participant C as Client
  participant GW as Gateway
  participant CH as chat-service
  participant MEM as mem-service
  participant R as rag-service

  C->>GW: POST /chat
  GW->>CH: 轉發(已驗證)
  CH->>MEM: 拉短期記憶摘要
  CH-->>C: 200 OK (ack/busy/短答)
  CH->>R: 非同步查詢 (透過 Pub/Sub 交給 worker)

非同步

sequenceDiagram
  participant BUS as Pub/Sub
  participant WK as worker-service
  participant GEM as Vertex AI
  participant APP as AI Applications
  participant C as Client

  BUS->>WK: chat.task
  WK->>APP: 流程/工具/檢索
  WK->>GEM: 產生最終回答
  WK->>C: WebSocket 推播 / callback webhook

5) 雲端落地：GCP 元件怎麼配

運算與網路

• Cloud Run：所有服務容器化；設定最小實例（避免冷啟）、併發度（預設 80，不要盲目拉滿）。
• VPC 連線器：若要內網打 DB/內部 API。
• 雜湊路由：WebSocket/BFF 走固定路由，避免連線漂移。

身分與祕密

• Service Account：每個服務一個，權限最小化（least privilege）。
• Secret Manager + KMS：金鑰/密碼，不落環境變數原文（至少在部署層用 secret 引用）。
• IAM：把「讀向量庫」「寫記憶」權限拆清楚。

資料層

• Cloud SQL (PostgreSQL)：記憶/使用者設定/任務狀態。
• 向量庫：你可先選簡單（PG + pgvector / AlloyDB），企業後期再評估專用向量解決方案。
• 物件儲存：原始文件放 GCS，RAG 前處理產出索引與中繼資料。

AI 層

• Vertex AI Gemini API：模型主力。
• AI Applications（原 Agent Builder）：多工具、多步流程的協調中樞（下一系列重點）。

觀測與成本

• Cloud Logging / Monitoring：金四指標（延遲、錯誤率、流量、飽和度）。
• Error Reporting / Trace：查爆點。
• Budget + Alert：先設門檻，不然帳單會嚇人。

6) 設定與佈署骨架

cloudbuild.yaml（精簡骨架）

steps:
  - name: gcr.io/cloud-builders/docker
    args: ["build","-t","$_REGION-docker.pkg.dev/$PROJECT_ID/$_REPO/chat-service:$SHORT_SHA","-f","Dockerfile","."]
  - name: gcr.io/cloud-builders/docker
    args: ["push","$_REGION-docker.pkg.dev/$PROJECT_ID/$_REPO/chat-service:$SHORT_SHA"]
  - name: gcr.io/google.com/cloudsdktool/cloud-sdk
    entrypoint: gcloud
    args:
      - run
      - deploy
      - chat-service
      - --image=$_REGION-docker.pkg.dev/$PROJECT_ID/$_REPO/chat-service:$SHORT_SHA
      - --region=$_REGION
      - --platform=managed
      - --service-account=chat-sa@${PROJECT_ID}.iam.gserviceaccount.com
      - --set-secrets=JWT_KEY=projects/${PROJECT_ID}/secrets/jwt-key:latest
      - --set-env-vars=RAG_ENDPOINT=http://rag-service
      - --min-instances=1
      - --max-instances=10
      - --cpu=1
      - --memory=512Mi
substitutions:
  _REGION: asia-east1
  _REPO: ai-assistant

環境變數規格（範例）

原則：任何會換環境就會換值的東西，都放環境變數或 Secret。程式碼零硬編。

7) 認證與授權

• 對外：Gateway 驗發 JWT（RS256，kid 對應 JWKS），BFF/前端送 Bearer。
• 服務間：推薦 「JWT + SA 認證」 兩段式：
  1. Gateway 將使用者 JWT 轉成「下游可理解的 Authz Claim」（如 userId、scopes）。
  2. 服務間彼此用 Service Account 身分通行（避免把使用者 JWT 亂傳）。
• AI Applications/外部工具：用服務級憑證（SA / OAuth 客戶端），集中管理配額與審計。

8) 失敗策略與重試

• Idempotency Key：chatId/requestId 進入 Pub/Sub 前先上鎖，避免重送重算。
• 重試政策：worker-service 對可重試錯誤（429/5xx）做指數退避；對不可重試錯誤直接 DLQ（死信佇列）。
• 回補超時：同步超過 2 秒直接回 ACK + 進度事件；完整答案用 WS 推播或 callback。
• 灰度與回滾：Cloud Run 以版本百分比釋出；出事立即回滾上一版。

9) 成本護欄

• 併發度與最小實例：min-instances 不是越多越好，先 0~1；高耗服務分出來。
• 向量查詢節制：先快取、再縮小 Top-K、最後才加速算力。
• 模型選型：能用小模型就別上大模型；學會用系統 Prompt 降 hallucination，少洗 token。
• 配額告警：一開始就開（Vertex、Run、Pub/Sub、Logging）。