triAIge 架構說明（給團隊成員）

救護車上的救護員說「男性，胸痛半小時，血壓一百六十、九十，心跳一百一」，幾秒後，救護紀錄表上的性別、主訴與生命徵象就填好了，每一格都標明是 AI 填入、等人複查；病人送到急診時，檢傷護理師打開同一個案件，看到的是預先填好、附上建議檢傷級數的評估表。triAIge 做的就是這件事。前端是救護端、急診端與醫師端的網頁；後端是一個 FastAPI 服務，在一台 DGX Spark 上用 Nemotron 3 Super 擷取欄位，臨床判斷交給確定性規則與護理師。這份文件說明系統現在的組成：程式分成哪幾層、一句話經過哪些層、每一類規則放在哪裡，以及新增提示詞、新增檢查或換模型時要改哪裡。

1. 這份文件給誰、怎麼讀

讀者有兩種：開發者會用到全部章節；臨床組員只需要讀第 2 章（系統全貌）、第 4 章（一句話的處理過程）與第 12 章（已知限制），第 5 到第 10 章講程式內部結構與操作，可以跳過。

這份文件遵守 eval/README.md 的誠實規則：評測用的逐字稿是模型寫的草稿，案例卡來自 MIMIC，還在等醫師審閱，所以這裡不說「已通過臨床驗證」。

2. 系統全貌

flowchart LR
  subgraph Browser["前端（iPad／瀏覽器）"]
    WEB["/ 正式介面（真後端）"]
    MOCK["/internal 模擬版（瀏覽器內 mock）"]
  end
  FUNNEL["Tailscale Funnel"]
  subgraph Spark["DGX Spark"]
    subgraph SRV["triaige-server（FastAPI，:8100）"]
      API["api/"]
      AI["ai/"]
      ENG["engine/"]
      TR["task_rules/"]
      LLM["llm/"]
    end
    NAT["NeMo Agent Toolkit<br/>WorkflowBuilder + guardrails middleware"]
    VLLM[("vLLM：Nemotron 3 Super<br/>:8000")]
    PG[("PostgreSQL :5433<br/>cases JSONB、kb_passages")]
  end
  EVAL["eval/（離線評測）"]
  WEB --> FUNNEL --> API
  API --> AI
  API --> ENG
  AI --> NAT --> VLLM
  SRV --> PG
  EVAL -.-> VLLM

• 前端有兩份：/ 連真後端，/internal 在瀏覽器內用 web/src/mock/ 模擬後端。兩邊的案件規則必須一致，所以由 server/tests/fixtures/mock_parity.json 與 server/tests/unit/test_engine_parity.py、test_drift.py 檢查。網頁部署在 Vercel。
• 後端是單一 FastAPI 服務（server/src/triaige_server/），NAT 內嵌在同一個行程裡，不另外起服務。
• 資料存在 PostgreSQL：案件以 JSONB 存放；kb_passages 表已經先建好，留給階段 2 的 RAG（server/src/triaige_server/migrations/001_init.sql）。
• 模型由同一台 Spark 上的 vLLM 提供，後端用 OpenAI 相容的 HTTP 介面呼叫它。
• eval/ 離線呼叫同一台 vLLM，不經過後端。

決策背景見 docs/specs/2026-10-13-backend/decision.md 與 design.md，部署參數見 infra/inventory/group_vars/servers.yml。

3. 分層與依賴方向

哪些程式碼該知道「現在用的是哪個模型」？我們的答案是只有 llm/。其餘各層分成「任務本身的規則」與「執行任務的程式」，兩者都不能出現模型名稱、取樣參數，或處理模型輸出習慣的程式碼。

flowchart TB
  subgraph Interface["介面層"]
    API["api/（FastAPI 路由、SSE）"]
  end
  subgraph Application["應用層 ai/"]
    SVC["service.py 編排<br/>scheduler、sequencer、route、gate、recorded、mapping"]
    RT["NAT 執行期黏合<br/>extractor.py、nat_*.py、workflow.yml<br/>（workflow.yml 只有 functions 與 guardrails）"]
  end
  subgraph Task["任務層（與模型無關）"]
    ENGN["engine/（案件規則，與 web mock 對齊）"]
    TRN["task_rules/（只用標準函式庫）<br/>詞彙、record／statement／route 檢查、主訴翻譯檢查"]
  end
  subgraph Model["模型適配層 llm/（只用標準函式庫）"]
    PROF["profiles/nemotron_3_super/<br/>ModelProfile"]
    PS["prompt_sets/ems_compact/<br/>record、statement、classify、translate、self_check"]
    ADP["output.py、wire.py、choice_scoring.py"]
  end
  INFRA["infra/ 部署手冊與 group_vars"]
  VLLM[("vLLM")]
  API --> SVC
  API --> ENGN
  SVC --> ENGN
  SVC --> TRN
  SVC --> RT
  SVC --> PROF
  RT --> PROF
  RT -- "OpenAI 相容 HTTP" --> VLLM
  ENGN --> TRN
  PROF --> PS
  PROF --> ADP
  PS --> TRN
  ADP --> TRN
  INFRA -. "served name、port、profile id" .-> RT

這些依賴方向由 server/tests/unit/test_architecture.py 強制，沒有例外清單：

• engine 不能 import ai 或 llm。
• task_rules 不能 import triaige_server 內的其他套件，也不能用第三方套件。
• llm 只能 import 自己與 task_rules，也只能用標準函式庫，所以不能引入 NAT、langchain、fastapi。
• llm/ 以外的 server/src 不能出現模型字面值（nemotron、<主機名稱>、enable_thinking、chat_template_kwargs、top_logprobs、max_tokens、/v1），也不能有取出 {…} 的修補程式；ai/ 裡不能有提示詞檔或提示詞文字。

每一條掃描都另外用刻意放入的違規範例測試過，確認它確實抓得到。

4. 一句話的處理過程

救護人員說了一句話，從送出到畫面更新，中間經過哪些步驟？

sequenceDiagram
  participant U as 前端
  participant A as api/（介面）
  participant S as ai/ 排程與編排（應用）
  participant N as NAT（應用）
  participant V as vLLM
  participant L as llm/（模型）
  participant T as task_rules/（任務）
  participant E as engine/（任務）
  U->>A: POST /cases/{id}/messages
  A->>E: 建立訊息（寫入來源規則）
  A-->>U: 201（先回，AI 在背景跑）
  A-->>U: SSE message.created、assistant.started
  A->>S: schedule(case, message)
  S->>S: scheduler 依 P0／P1／P2 排隊，空位數是 `settings.ai_concurrency`，預設取自 profile 的 max_streams
  S->>S: sequencer 讓同一案件的 R1 句子依序處理
  S->>N: 呼叫擷取
  N->>V: 提示詞與取樣參數來自 profile
  V-->>N: 回覆（含 logprobs）
  N-->>S: 回覆文字
  S->>L: profile.reply_text 修補輸出
  S->>T: task_rules 檢查（範圍、詞彙、過敏接地）
  S->>L: choice_scoring 評分選項欄位
  S->>E: 寫入 record（人工或已確認的值優先）
  A-->>U: SSE record.updated、assistant.completed
  S->>S: P2 背景：主訴翻譯

圖中每一步都標了所屬的層。要注意修補與檢查的順序：先用模型層的 reply_text 把回覆整理成一個 JSON 物件，再交給任務層做嚴格檢查；評分與稽核紀錄則用沒有修補過的原始回覆（raw）。整個後端只有 llm/output.py 的 json_span 會取出 {…}，其他地方再寫一份，會被架構測試擋下。

5. 各關注點在哪裡

6. 模型適配層（llm/）

ModelProfile 是這條邊界的核心：後端要服務一個模型時需要知道的事，都收在這個物件裡。它是不可變的（frozen），建立時就檢查四個取樣角色是否齊全、上限是否為正數。

classDiagram
  class ModelProfile {
    id
    display_name
    reply_text(raw) str
    evidence
  }
  class Serving {
    api
    served_name
    default_base_url
    timeout_s
    max_streams
    recipe
  }
  class Sampling {
    max_tokens
    temperature
    extra_body
  }
  class Confidence {
    top_logprobs
    thresholds
    fixtures
  }
  class PromptSet {
    id
    record
    statement
    classify
    translate
    self_check
  }
  ModelProfile --> Serving
  ModelProfile --> "4" Sampling : extraction、route、translate、rail
  ModelProfile --> Confidence
  ModelProfile --> PromptSet

應用層有三條固定規則，不由設定檔決定：max_retries 一律是 0（失敗就送出 assistant.failed）；沒有備援模型；請求逾時與 asyncio.timeout 用同一個 settings.llm_timeout_s。這三條都來自「失敗要明確，不默默降級」的原則。

現行設定檔：nemotron_3_super

這些值由 server/tests/unit/test_model_profile.py 固定，設定檔裡列出的每個路徑也要存在。

候選設定檔：nemotron_3_5_super_vl（評估中，不是預設）

Nemotron 3.5 Super VL NVFP4，只用文字輸入。為了讓評估只比較模型本身，它和 Super 只差在服務名稱 nemotron-3.5-super-vl；取樣、token 上限、提示詞集、關閉推理的開關、json_span、top_logprobs=5、逾時與 2 條串流都和 Super 相同，由同一個測試固定。它有自己的信心門檻檔，還沒校準（enabled=false，每個欄位的 tau 都是 null）。對數機率測試資料（fixture）要在評估窗口錄製。vLLM 啟動參數的出處、切換與回滾，見 infra/README.md 的「評估 Nemotron 3.5 Super VL」。在保留集上不比 Super 差，才把 triaige_model_profile 換成它。

第二個設定檔要填什麼

下面是示意，不是會上線的程式碼：

PROFILE = ModelProfile(
    id="<vendor_model_size_quant>",
    display_name="…, vLLM vX, DGX Spark",
    serving=Serving(api="openai_chat", served_name="<served-name>",
                    default_base_url="http://<主機名稱>:8000/v1",
                    timeout_s=<實測 p99 × 餘裕>, max_streams=<實測穩定串流數>,
                    recipe="infra/playbooks/deploy-<model>.yml"),
    prompts=ems_compact.PROMPT_SET,   # 先沿用；有保留集證據才分岔
    sampling={ "extraction": Sampling(max_tokens=..., extra_body={...}), ... },
    reply_text=output.strip_think_then_json_span,   # 模型會輸出推理區塊時才需要
    confidence=Confidence(top_logprobs=5 或 None, thresholds=None,
                          fixtures="server/tests/fixtures/logprobs/<id>"),
    evidence=("eval/results/<date>-<id>-…",),
)

• 關閉推理的方式因模型而異：chat_template_kwargs、reasoning_effort 欄位，或根本沒有開關，所以 extra_body 不限格式。
• 如果伺服器回不了 top_logprobs，填 None；這時設定 TRIAIGE_CHOICE_CONFIDENCE=true 會在啟動時直接失敗，不會默默產生沒有信心值的結果。
• 啟動時遇到不認得的設定檔 id 也會失敗，錯誤訊息會列出認得的 id（llm/registry.py）。

提示詞集與稽核版本

提示詞以提示詞集（prompt set）為單位，設定檔以 id 引用（ems_compact）。多個設定檔可以共用同一個提示詞集；只有保留集的證據顯示是模型讀錯時，才另外分出新的提示詞集，並提高 PROMPT_VERSION。稽核紀錄裡的 AI 身分是 name = 服務名稱、version = 提示詞版本，設定檔 id 只寫進啟動日誌與評測結果。

7. 檢查放哪一層

新增一條檢查時，怎麼決定它放在哪裡？先問一個問題：如果模型是完美的，這條檢查還需要嗎？

flowchart TD
  Q1{"換成完美的模型，<br/>這條檢查還需要嗎？"}
  Q1 -- 需要 --> TASK["任務層：task_rules/ 或 engine/<br/>影響畫面時要同步 web mock"]
  Q1 -- 不需要 --> Q2{"它在修補或量測<br/>這個模型或伺服器的輸出習慣嗎？"}
  Q2 -- 是 --> MODEL["模型層：profile.reply_text 或信心評分"]
  Q2 -- 否 --> RUNTIME["執行期：傳輸、排程、可用性<br/>留在 ai/"]

目前主要的檢查分類如下：

系統裡沒有「JSON 壞掉就重試」或「改用備援模型」的程式，也不打算加。

8. 新增提示詞或檢查

• 提示詞： 放進提示詞集模組，不放在 ai/；只能用標準函式庫；提高 PROMPT_VERSION。提示詞與使用者訊息的位元組由 server/tests/unit/test_model_layer_pins.py 固定（基準檔在 server/tests/fixtures/model_layer/，用 server/scripts/record_model_layer_goldens.py 產生），重新產生基準檔時必須附上保留集證據。另外要維持 StubLlm 的前綴約定（server/tests/stub_llm.py），不然就要連 StubLlm 一起改。
• 檢查： 用第 7 章的判斷。任務檢查放 task_rules/ 或 engine/，影響畫面的規則，要有對照案例，網頁端也要有相同的實作；模型檢查放 llm/output.py 或設定檔。
• 每條新規則都要有一個「拿掉它就會失敗」的測試，並附上變異測試的證據。

9. 換模型操作手冊

換模型時要改的是 llm/ 裡新增的設定檔，加上 infra/ 裡那個模型自己的部署手冊；其他層不必改。

flowchart TD
  S1["1 可行性<br/>端點、對數機率、推理開關、記憶體、授權"] --> S2["2 部署手冊<br/>部署腳本、模板、group_vars；<br/>bench_serving 與 3 串流壓測決定 max_streams"]
  S2 --> S3["3 寫 profile 並登錄 registry"]
  S3 --> S4["4 不需模型的本機檢查"]
  S4 --> S5["5 錄對數機率測試資料"]
  S5 --> G{"6 宣告門檻後，<br/>保留集全部跑完<br/>達標？"}
  G -- 否 --> S7["7 在根因那一層修；<br/>不加個案字眼"] --> G
  G -- 是 --> S8["8 信心校準"]
  S8 --> S9["9 部署（--check --diff）"]
  S9 --> S10["10 記錄證據"]

1. 可行性。 確認端點是 OpenAI 相容、logprobs 與 top_logprobs（含 bytes）能不能回、推理怎麼關、context 長度、記憶體（Super 現在約 95–103 GiB；後端與資料庫上限合計 2 GiB，見 triaige_server_mem_limit 與 triaige_db_mem_limit）、授權。資料來源見 docs/specs/2026-10-13-backend/research-<帳號>-stack.md 與 group_vars/servers.yml 的註解。
2. 部署手冊。 新增 infra/playbooks/deploy-<model>.yml、模板與 group_vars 區塊，先 --check --diff，部署到 Spark，再跑 eval/scripts/bench_serving.py 與 3 條串流壓測，之後才決定 max_streams。
3. 寫設定檔。 新增 llm/profiles/<id>/__init__.py，內容：身分與服務名稱、各角色的 Sampling（max_tokens 取該角色在校準集上輸出 token 的 p99 × 1.5）、reply_text、信心能力、逾時與串流數、prompts（先引用 ems_compact）、證據；然後在 llm/registry.py 登錄。
4. 不用模型的本機檢查。 用 TRIAIGE_MODEL_PROFILE=<id> 跑後端的 pytest（StubLlm 與設定檔無關）、架構測試、設定檔契約測試（server/tests/unit/test_model_profile.py：每個角色都有取樣、路徑存在）、eval pytest、cd web && bun run check。
5. 對數機率測試資料。 執行 server/scripts/record_logprobs_fixtures.py --profile <id>（--profile 預設是 nemotron_3_super），寫到 server/tests/fixtures/logprobs/<id>/。測試資料專屬的預期值要重新推導，性質測試不用改。
6. 開跑前先宣告門檻（誠實規則）。以評測標準（yardstick） cb8bb62 為準，全部在保留集：基準是現行設定檔跑 3 次取平均；容忍度是 3 次的最大值減最小值，不設下限；候選模型跑 1 次。要跑的有：eval/scripts/run_extraction.py（整段口述）、eval/scripts/replay_backend.py（逐句，含正常與連發）、run_corrections.py 與 score_corrections.py、路由 T1／T3、過敏 T2、eval/complaint_zh、延遲 A/B（ab_latency.py、ab_logprobs.py）。一律在 lockf ~/.local/state/triaige-qa/super.lock 內執行，串流數不超過 max_streams，結果寫到 eval/results/<date>-<id>/。
7. 失敗怎麼修。 在根本原因所在的那一層修正（2026-10-13 的使用者規則）：模型讀錯了才改提示詞，而且只寫通則、只在校準集上調整、保留集只跑一次；切句或上下文的問題改擷取架構；合併的問題改 engine；標準答案有疑問就交給臨床組員。不能加只針對個案的字眼。
8. 信心校準。 執行 calibrate_choice_confidence.py --profile <id>（尚未實作，屬於 C2 工作），寫入該設定檔的門檻檔。達到 inline-review 計畫 的 D7 目標之前維持 enabled=false。重新產生模擬後端用的副本，並跑漂移測試。
9. 部署。 把 triaige_model_profile 指向新模型（infra/inventory/group_vars/servers.yml；服務名稱從 vllm_served_names 查，vLLM 的 vllm_stack 跟著它），--check --diff 後部署，再照 infra/README.md 跑部署後的煙霧測試，並重播兩個案例。回滾就是回到前一個設定檔 id 與前一個映像標籤。
10. 記錄。 在 eval/README.md 加一節、更新設定檔的 evidence、更新本文第 6 章的表。

10. 部署與設定開關

flowchart LR
  subgraph Host["DGX Spark 主機"]
    TS["Tailscale Funnel"]
    subgraph Docker
      SRV["triaige-server :8100<br/>記憶體上限 1536m"]
      DB[("PostgreSQL :5433<br/>記憶體上限 512m")]
      VLLM[("vLLM Nemotron 3 Super :8000")]
    end
  end
  TS --> SRV
  SRV --> DB
  SRV -- "TRIAIGE_LLM_BASE_URL" --> VLLM

部署由 infra/playbooks/deploy-triaige-server.yml、deploy-nemotron-super.yml 與 infra/playbooks/templates/triaige/docker-compose.yml.j2 負責，參數在 infra/inventory/group_vars/servers.yml。後端映像在 Spark 上原生建置，標籤是 git revision。正式環境目前執行映像 triaige-server:03c2ed7c0f49，設定檔是 nemotron_3_super。

環境旗標（server/src/triaige_server/config.py）：

11. 證據索引

• eval/README.md：〈服務參數實測（2026-10-12）〉、〈R1 採用標準與重新判定〉、〈R1 上下文（X1）採用標準〉、〈X1 審查修正後的重新驗收〉。
• 結果目錄：eval/results/serving-2026-10-12/、yardstick-2026-10-13/、r1-context-fix-2026-10-14/、routing-2026-10-13/、choice-confidence-latency-2026-10-14/。
• 評測標準的 commit：cb8bb62。
• 分層與模型邊界的測試：server/tests/unit/test_architecture.py（依賴方向、模型字面值、JSON 修補位置）、test_model_profile.py（設定檔的值與路徑）、test_model_layer_pins.py（提示詞與解析結果的位元組）、test_reply_adapters.py（輸出修補）、test_choice_confidence_properties.py（信心評分的性質）。
• 設計：docs/specs/2026-10-14-inline-review/plan.md §4（信心設計）、docs/specs/2026-10-13-backend/design.md。

12. 已知限制

• 信心規則的適用範圍見 inline-review 計畫 §4.3；對數機率測試資料只在 Super 上錄過，換模型要重錄。
• 主訴翻譯檢查只能盡量擋下錯誤（ZH9）；主訴含數字或明確次數時，只顯示英文。
• 提示詞是針對 Super 調整的；換成其他模型會怎樣，沒有證據。
• 評測用的逐字稿是模型寫的草稿，案例卡還在等醫師審閱。
• 同時請求的上限是 2，因為第 3 條串流曾觸發 CUDA 錯誤（原因不明，間歇發生）。
• 網頁測試的字面值與註解裡出現的 nemotron 字串沒有作用，不需要改。