AI 守門調整手冊

適用對象：客戶端的系統維運人員（能登入主機、執行 docker compose 的人）。 本文用途：說明 AI 功能（AI 助理、AI 儀表板、證據自動分類）送給 AI 之前與之後的「守門」怎麼運作，以及現場要放寬或收緊時改哪個檔、哪一段、改完怎麼生效、怎麼確認。改這些都不必重裝、不必換版。 不在本文範圍：AI 金鑰與額度設定（在系統畫面「系統設定分組 › AI 用量」與 AI 設定頁操作）、證據分類的判斷標準（在後台「AI 分類設定」調整，見第三節最後）。

變更紀錄

① 所有 AI 呼叫都經過同一道閘門。 使用者在 AI 助理打的字、儀表板的需求、分類時讀到的證據內容，都先過閘門檢查才送給 AI；AI 的回答回來時也再檢查一次。

② 閘門的行為全部寫在主機上的一個目錄裡：

/srv/guidant-ai/ai-gateway-rules/
├── gateway_rules.yaml          守門規則：什麼要遮、什麼要標記、什麼要擋
├── presidio_recognizers.yaml   自訂的機敏資料格式（身分證字號、AWS 金鑰…）
└── prompts.yaml                各功能給 AI 的固定指示（角色、判斷方式）

資料目錄若安裝時改過（不是 /srv/guidant-ai），以 sudo guidantai status 顯示的資料目錄為準，下文一律以 /srv/guidant-ai 舉例。

③ 改完一定要重啟兩個服務才生效（用 restart 就夠，這個目錄不是 start 才會讀的設定檔）：

sudo guidantai restart guidant-api
sudo guidantai restart guidant-worker

每一行會等該服務健康檢查通過才結束。兩個都要重啟：guidant-api 管 AI 助理與儀表板，guidant-worker 管證據自動分類。只重啟一個，另一邊還是舊規則。

改檔前先備份一份：sudo cp -a /srv/guidant-ai/ai-gateway-rules /srv/guidant-ai/ai-gateway-rules.bak-$(date +%F)。

檔案裡的 rules: 底下一條一條規則，每條長這樣：

  - id: offtopic-bot          # 規則名稱，會出現在 AI 呼叫紀錄裡，全檔不可重複
    feature: ai-bot           # 套用在哪個功能
    detector: offtopic        # 用哪一種偵測方式
    action: block             # 命中後怎麼處置
    params: {...}             # 這種偵測方式的細部設定

feature（功能）

action（處置）——對應 AI 呼叫紀錄頁「處置」欄的顯示：

detector（偵測方式），共四種：

本檔最上方另有 scan_segments 與 counts_rate 兩段，分別決定「每個功能檢查哪些內容」與「哪些呼叫計入每分鐘次數」，屬於系統對接設定，不要改。

每一條的格式都是：改哪裡 → 重啟（第一節③）→ 怎麼確認。確認一律到系統畫面 「系統設定分組 › AI 用量」→「呼叫明細」，找你剛才那一筆，看「處置」欄；點該列可看「守門命中」是哪條規則。

食譜 1：AI 助理要多放行一類主題

情境：使用者問「個資法第幾條規定…」被回「我只能回答 Guidant AI 的操作與合規稽核相關問題」。

AI 助理的擋有兩層，要先分清楚是哪一層擋的：

• 回覆正好是「我只能回答 Guidant AI 的操作與合規稽核相關問題。」→ 是閘門擋的（離題規則），AI 根本沒收到。改 gateway_rules.yaml。
• 回覆是 AI 自己寫的一段婉拒（每次措辭不同）→ 是 AI 依角色設定婉拒。改 prompts.yaml（見食譜 5）。

閘門擋的改法：打開 gateway_rules.yaml，找 id: offtopic-bot，在 allow_topics 加上主題關鍵字：

      allow_topics: [合規, 稽核, 控制, 證據, 風險, SSP, 問卷, 專案, 框架, 報表, 任務, 權限,
                     Guidant, ISO, NIST, CMMC, 資安, 政策, 程序, 帳號, 登入, 上傳, 匯入, 匯出, 儀表板,
                     個資, GDPR]

規則是：句子裡只要出現任何一個 allow_topics 的字，就不算離題。加字只會放行，不會多擋。

確認：重啟後再問一次，不再是上面那句固定的回覆，改由 AI 回答；呼叫明細「狀態」為「成功」、「處置」為「放行」。

放行只代表問題送得到 AI。AI 還是會依 prompts.yaml 的角色設定決定要不要答——主題不在角色範圍內的話，它會自己婉拒（每次措辭不同）。兩層都要放寬，才會真的得到答案，另一層見食譜 5。

食譜 2：AI 助理要多擋一類問題

情境：不希望 AI 助理回答「推薦投資標的」這類問題。

在 offtopic-bot 的 offtopic_patterns 加一行樣式：

      offtopic_patterns:
        - ...（原有的保留）
        - "(投資|理財).{0,10}(標的|建議|推薦)"

樣式寫法：(A|B) 表示 A 或 B；.{0,10} 表示中間可夾 0～10 個任意字（避免換個說法就繞過）。

⚠️ 只有「命中樣式」且「沒提到 allow_topics 任何字」才會擋。所以「資安投資建議」不會被擋（提到「資安」）。這是刻意的：寧可漏擋閒聊，也不要誤擋正事。

確認：問「推薦投資標的」→ 回罐頭訊息；呼叫明細「處置」為「阻擋」，守門命中 offtopic-bot。

食譜 3：某功能不要遮 email

情境：AI 儀表板要依寄件者 email 做統計，但 email 被遮成「[已遮蔽]」。

找 id: pii-redact-dashboard，從 entities 拿掉 EMAIL_ADDRESS：

  - id: pii-redact-dashboard
    feature: ai-dashboard.*
    detector: presidio
    action: redact
    params:
      entities: [CREDIT_CARD, PHONE_NUMBER, IP_ADDRESS, AWS_ACCESS_KEY, TW_NATIONAL_ID]

AI 助理那邊是 pii-redact-bot，要調就改那一條；兩條互不影響。

⚠️ 不遮就代表這類資料會原樣送到 AI 供應商。改之前請確認貴單位的資料外送政策允許。

確認：呼叫明細點該筆 →「守門命中」不再出現 EMAIL_ADDRESS。

食譜 4：「標記」那一級要改成直接擋／直接放行

以「企圖操控 AI」為例，檔案最上方：

thresholds:
  prompt_guard: {flag: 0.8, block: 0.95}

每句輸入會得到一個 0～1 的分數，越高越像操控。分數 ≥ flag 記為「標記」、≥ block 直接「阻擋」。

證據自動分類那條（injection-classification）有 never_block: true，分數再高也只標記——證據檔本來就常含「忽略」「指示」這類字，擋了會讓整批分類失敗。不建議拿掉。

確認：呼叫明細「處置」欄從「標記」變「阻擋」（或反之）。

食譜 5：AI 回答太保守或太寬

改 prompts.yaml。每段上方都有註解說明它管什麼、改了會怎樣，動手前先讀那段註解。

例：AI 助理對「個資法」一律婉拒（不是閘門擋的）——在 role: 那段範圍清單加上去：

  role: |-
    你是 Guidant AI 的合規稽核助理。你的服務範圍包括：①本系統的操作說明；②資安合規領域知識——ISO 27001、NIST、CMMC、SSP、個資法、控制項、證據、風險評估等框架與名詞解釋、稽核實務問答。…（其餘不動）

寫法規則：

• role: |- 下一行起、比 role: 多縮排兩格的內容，就是整段文字（可以換行）。縮排少了會被當成下一個設定，整個檔就壞了。
• 不要用 Tab，一律空白。
• 某段整段刪掉或留空 → 該功能自動改用系統內建的同一段文字，不會壞。
• 儀表板那段最後一行「只返回 JSON…」的欄位名與三個 intent 值是系統對接格式，不可改。

關於證據分類：分類給 AI 的角色與判斷標準，以後台「AI 分類設定」為準（出廠附一筆「出廠通用設定」）。prompts.yaml 的 classification 只在後台設定讀取失敗時頂上。要調分類，請改後台的分類設定。

確認：重啟後在 AI 助理問同一句，看回答是否符合預期。AI 回答本身有隨機性，請多問兩三次再判斷。

食譜 6：加一種自家機敏格式（例如員工編號）

情境：員工編號格式是 EMP 加 6 位數字（EMP123456），不希望送給 AI。

在 gateway_rules.yaml 的 rules: 底下新增一條（放在「小幫手」那一區即可）：

  - id: employee-id-bot
    feature: ai-bot
    detector: format
    action: redact
    params:
      entity: EMPLOYEE_ID
      pattern: "(?<![A-Za-z0-9])EMP\\d{6}(?![A-Za-z0-9])"

• id 取一個全檔沒用過的名字。
• 要儀表板也遮，就再抄一條，id 改成 employee-id-dashboard、feature 改成 ai-dashboard.*。
• pattern 裡的反斜線要寫兩個（\\d）。(?<![A-Za-z0-9]) 與 (?![A-Za-z0-9]) 是「前後不能緊接英數字」，避免誤抓長字串中間的一段。
• 要直接擋而不是遮，把 action 改成 block，並在 params 加一行 reply: "請勿輸入員工編號。"。

確認：在 AI 助理輸入「EMP123456 的權限怎麼設」→ 呼叫明細「處置」為「遮蔽後送出」，守門命中 employee-id-bot／EMPLOYEE_ID。

升級不會蓋掉你改過的檔。 升級程式（install.sh --upgrade）對這個目錄只做兩件事：

1. 把新版出廠原檔整份放到 /srv/guidant-ai/ai-gateway-rules.default/（每次升級都換新）
2. ai-gateway-rules/ 裡缺哪個檔才補哪個，已存在的一律不動

升級過程若印出：

以下規則檔與本版出廠版不同，已保留現場版本不覆蓋：prompts.yaml

代表你手上那份與新版出廠版不一樣——可能是你改過、也可能是新版出廠有調整、或兩者都有。系統照樣用你那份，但新版的調整不會自動進來。建議升級後比對一次：

cd /srv/guidant-ai
sudo diff ai-gateway-rules.default/prompts.yaml ai-gateway-rules/prompts.yaml

• 差異全是你自己改的 → 不必動。
• 有你沒改過、新版出廠多出來或改掉的段落 → 把那幾段抄進 ai-gateway-rules/ 那份，然後重啟（第一節③）。

想整份回到新版出廠、放棄自己的修改：sudo cp ai-gateway-rules.default/<檔名> ai-gateway-rules/<檔名> 再重啟。

症狀一：重啟後 guidant-api 或 guidant-worker 起不來。 看 log：

sudo guidantai logs guidant-api       # 分類那邊換成 guidant-worker；Ctrl-C 離開

YAML 寫壞時會看到類似：

[FATAL] 啟動失敗：AI 相關必要設定缺 1 項
  - AI_GATEWAY_RULES_DIR 內的 prompts.yaml 格式錯誤：… 無法解析：while scanning a quoted scalar
  in "<unicode string>", line 2, column 9:

訊息會指出哪個檔、第幾行。最常見的原因：縮排少了兩格、引號沒關、用了 Tab、規則 id 重複。

最快的救法——整份換回出廠版：

cd /srv/guidant-ai
sudo cp ai-gateway-rules/<壞掉的檔名> ai-gateway-rules/<壞掉的檔名>.broken   # 留一份，方便事後找錯
sudo cp ai-gateway-rules.default/<壞掉的檔名> ai-gateway-rules/<壞掉的檔名>
sudo guidantai restart guidant-api
sudo guidantai restart guidant-worker

改動前有照第一節備份的話，也可以直接換回備份那份。

症狀二：ai-gateway-rules.default/ 也不見了——可以從執行中的映像直接取出出廠版：

cd /srv/guidant-ai
VER=$(sed -n 's/^GUIDANT_VERSION=//p' .env)
CID=$(sudo docker create guidant-ai-be:$VER)
sudo docker cp $CID:/opt/guidant/ai-gateway-rules/. ai-gateway-rules.default/
sudo docker rm $CID

症狀三：prompts.yaml 不小心刪掉了——服務照常啟動、行為跟出廠一樣（自動改用系統內建文字），log 會多一行「找不到 prompts.yaml」的警告。要補回來照上面換回出廠版即可。

⚠️ 不要把 ai-gateway-rules/ 整個目錄刪掉或清空：服務會因為找不到 gateway_rules.yaml 起不來（它不會自動退回映像內建那份）。