八月初給kevinclaw增加了一樣架構,可以觀測平台到AI供應商間所有端點間的API效能. 今早特別為我一個排程工作做了檢查,我之前做了一個自動排程, 每天早上由KevinClaw自動去抓聯合報當天的頭條要聞並整理成列表加上超連結,這樣子我一早起來就等著看今日頭條. 下圖便是今早跑的結果, 但我覺得它跑的不夠快,我就讓google antigravity查我的LOG做說明.
下圖是排程任務的管理界面: (PS:時間紀錄還需調整,GMT+0問題,但不影响排程輸出結果)
順手修復時間顯示問題: 後台用GMT+0 前台未即時顯示, 更新時間換成上次執行時間.(本來是設定檔變更的時間紀錄,取消)
以下是GEMINI的說明, 如果我平台沒有做這個api latency observatility的案子, GEMINI也查不出來,因為沒有LOG參考,它得自己重建現場跑半天.. 以下是GEMINI的檢查結果, 其實就是OPENROUTER這免費的特別慢, 尤其在多輪工具調用下, 它會刻意被放慢, 沒辦法, 用免費的, 你需要的是耐心, 若我把AI PROVIDER換成GEMINI, 就快好幾倍..以下兩個截圖是報告結果.
最後放上此案 API Latency Observability結案報告.
date: 2026-08-03
-
延遲可觀測性架構總覽報告
VER14 Provider-Neutral API Latency Observability 全域結案與架構總覽報告
[[2026-08-02-provider-neutral-latency-observability-phase0-baseline]]
[[2026-08-03-latency-observability-phase7a-operability-closeout]]
[[2026-08-03-latency-observability-phase7b-five-sample-evidence]]
[[2026-08-03-latency-observability-operability-runbook]]
1. 專案總覽 (Executive Summary)
本專案旨在為 VER14 平台建立 無 Provider 偏見、無破壞性（Provider-Neutral & Non-Breaking）的端到端 API 延遲可觀測性（Latency Observability）框架。
核心目標與成就：
- 零功能破壞 (Non-Interfering)：在不修改任何既有 API 協議 (Contract)、不更動 SSE 傳輸數據格式、不改動前端 UI 渲染邏輯的前提下，精確擷取毫秒級 Timing 數據。
- 全域零盲區 (Total End-to-End Coverage)：覆蓋所有前端進入點 (Web Conversation, Web Search, Channel, Scheduler, External API, Hybrid Desktop Client)、所有 10 大 LLM Providers (OpenAI-compatible, Anthropic, Gemini, Ollama, OpenRouter)、所有 MCP 工具與後台服務 (PaddleOCR, Browser, KB Embeddings, Email, Calendar, EasyEDA, WordPress)。
- 實證驅動效能優化 (Evidence-Driven Optimization)：透過導入輕量級多樣態統計分析器與 Phase 7B 5-Sample 生產數據驗證，定位出串流首字 Flush 瓶頸，成功推出「首刷可見區塊 (First Fragment Immediate Flush)」優化，大幅提升使用者體驗。
2. 系統總體架構概要 (Overall Architecture Overview)
Latency Observability 採用 樹狀階層 Span（Hierarchical Span Lineage Tree） 與 輕量 ContextVar 傳播機制，架構設計如下：
flowchart TD
A[Entrypoint / User Intent] -->|X-Latency-Trace-ID| B[LatencyTrace Root]
B --> C[Span: Route & Preparation]
B --> D[Span: Search / Preparation]
B --> E[Span: Provider Request]
B --> F[Span: Durable Execution Run]
E --> E1[stage: provider_request_start]
E --> E2[stage: provider_headers_received]
E --> E3[stage: provider_first_event / content]
E --> E4[stage: provider_first_visible_flush]
E --> E5[stage: span_end / outcome]
F --> G[Span: MCP Manager / Tool Call]
G --> H[Span: Subsystem - PaddleOCR / Browser / KB]關鍵架構特點：
- 核心類別 (
LatencyTrace&LatencySpan)- 精確計時：基於
time.monotonic()進行高精度時鐘追蹤，不受系統時間 NTP 校正影響。 - Context 傳播：利用 Python
contextvars.ContextVar(_current_latency_trace,_current_latency_span)，自動跨 Async 協程與 Thread 傳遞當前追蹤上下文。 - 父子關聯 (Lineage)：每個
LatencySpan具備span_id與parent_span_id，形成完整的父子調用樹狀結構。 - 無負擔日誌 (Zero-Blocking Overhead)：數據僅於記憶體內記錄時間戳，於關鍵階段結束時發射單條
[LatencyTrace]log，單次開銷小於 0.1 毫秒。
- 精確計時：基於
- 全 Trace 一致性抽樣 (Deterministic Sampling Mechanism)
- 控制變數：
VER14_LATENCY_OBSERVABILITY_ENABLED(預設true)VER14_LATENCY_OBSERVABILITY_SAMPLE_RATE(預設1.0，可於0.0~1.0調整)
- 抽樣演算：基於
SHA-256(trace_id)計算 Hash Bucket，確保「同一次請求的所有子 Span 與 MCP 調用」一致被採樣或丟棄，絕不產生孤立日誌。
- 控制變數：
- Durable Execution Run 整合
- 將 Trace 自動與平台的 Execution Policy (
policy_version,shadow/enforced) 以及execution_run_id綁定，支援平台非同步排程與 Channel 任務的完整履歷追溯。
- 將 Trace 自動與平台的 Execution Policy (
3. 分階段實施歷程 (Phased Implementation Summary)
本專案自 Phase 0 至 Phase 7 劃分為 25 個細粒度工作切片，全數通過單元與整合測試：
| 階段 | 涵蓋模組 / 範圍 | 核心產出與切片成果 |
|---|---|---|
| Phase 0 | Baseline & Ownership 盤點 | 完成 Entrypoint、Provider、Execution Policy 與 MCP 超時盤點；建立 94 項離線基線測試。 |
| Phase 1-2 | 基礎建設與 Core Lineage | 擴充 LatencyTrace.child_span() 階層結構；完成 Shared Agent、Durable Execution Run 與 Conversation SSE Response 的外層 Trace 綁定。 |
| Phase 3 | LLM Providers 深度剖析 | 完成 5 大 Provider 家族（OpenAI-Compatible, Anthropic, Gemini, Ollama, OpenRouter）內部階段剖析（request_start, headers_received, first_content, first_visible_flush）。 |
| Phase 4 | MCP & 複雜工具鏈 | 於 mcp_server_manager 建立 Parent Tool Span，並深鑽 PaddleOCR 完成圖片/PDF 讀取、編碼、雲端請求、頁面合併與 Office 轉換子階段監控。 |
| Phase 5 | 搜尋與 Hybrid Bridge | 完成 Brave / Puppeteer 搜尋階段拆解；綁定 Web 與 Universal Desktop Client 的 Hybrid Continuation 追蹤。 |
| Phase 6 | 後台服務與 Channel / Scheduler | 涵蓋 Channel、Scheduler、External API 進入點，以及 Email、Calendar、Browser、Gemini Video、EasyEDA、KB Embeddings、WordPress 輔助模組。 |
| Phase 7A | 可維護性與分析工具 (Operability) | 釋出獨立唯讀分析器 analyze_latency_traces.py（支援 Log 旋轉解析、中位數與近秩 p95 計算）；編寫 Operability Runbook。 |
| Phase 7B | 生產五樣本數據驗證與實證優化 | 收集 5 組嚴格控制條件的 Production 請求，成功診斷 OpenRouter 串流 Flush 瓶頸並完成首刷優化。 |
4. 五樣本生產實證與重大效能突破 (Five-Sample Evidence & Insight)
在 Phase 7B 中，我們針對標準網路搜尋對話進行了 5 筆控制組生產採樣（Prompt: 郭董的新歡..., Model: OpenRouter / nemotron-3-super-120b-a12b:free）：
階段耗時數據表 (單位: 毫秒 ms)
| 階段 Stage | 中位數 (Median) | 95 百分位 (p95) | 最小值 (Minimum) | 說明與瓶頸判定 |
|---|---|---|---|---|
| Search | 4,337 ms | 5,643 ms | 3,406 ms | 網路搜尋穩定受控於 3.4~5.6 秒 |
| Route | 135 ms | 236 ms | 113 ms | 平台路由耗時極低 (< 0.24 秒) |
| Prepare | 289 ms | 591 ms | 253 ms | Prompt 與上下文準備極快 (< 0.59 秒) |
| Headers | 2,253 ms | 2,789 ms | 1,719 ms | 等待 OpenRouter 首批 Header |
| First content | 4,636 ms | 8,934 ms | 3,466 ms | OpenRouter 生成首個 Token |
| First visible | 6,275 ms | 21,636 ms | 4,064 ms | 前端 UI 首次刷出文字 |
| Provider Total | 15,602 ms | 41,499 ms | 10,233 ms | 模型串流總生成耗時 |
| End-to-End | 21,447 ms | 46,542 ms | 14,514 ms | 使用者發送到接收完畢總時間 |
💡 重大效能發現與優化 (First Flush Optimization)
- 問題發現：採樣 4 顯示，模型在 4.02 秒 已生成首個 Token，但 UI 卻直到 21.64 秒 才顯示文字，出現長達 17.6 秒的空白等待期。原因在於舊適配器需等待緩衝區滿 800 字元或遇到句號才 Flush。
- 解決方案：推出「首刷立即 Flushing (First Fragment Immediate Flush)」改進——對於第一個生成的有效內文區塊無條件立即發射，後續區塊才維持 Batch 緩衝。
- 優化成果：經重啟後驗證，首字可見時間由 21.6 秒大幅縮短至毫秒級，在不增加伺服器負擔的前提下顯著提升了 UI 體感流暢度。
5. 運維與日誌管理指南 (Operability Summary)
- 環境變數控制：
- 啟用觀測：
$env:VER14_LATENCY_OBSERVABILITY_ENABLED="true" - 調整採樣率：
$env:VER14_LATENCY_OBSERVABILITY_SAMPLE_RATE="0.5"(採樣 50%)
- 啟用觀測：
- 分析器使用：
- 執行
python scripts/analyze_latency_traces.py --log-dir logs即可自動掃描app.log與輪轉日誌，計算所有進入點與 Provider 的 Median 與 p95 延遲。
- 執行
- 資訊安全防護：
- 系統已內建敏感資訊去標籤化 (Log Sanitization)，
[LatencyTrace]僅輸出元數據 (Metadata)，絕不記錄使用者 Prompt、模型回覆內文或資料庫 Key。
- 系統已內建敏感資訊去標籤化 (Log Sanitization)，
6. 關聯單元與細節稽核文件 (Audit Traceability)
所有細碎切片之稽核紀錄均完整保留於 docs/audits/ 目錄下：
- 基線與核心：
[[2026-08-02-provider-neutral-latency-observability-phase0-baseline]] - Provider 家族切片：
phase3a(OpenAI),phase3b(Anthropic),phase3c(Gemini),phase3d(Ollama),phase3e(OpenRouter) - MCP 與服務切片：
phase4a(MCP Manager),phase4b(PaddleOCR),phase6c1(Browser),phase6c3b(EasyEDA),phase6c3c(WordPress) - 結案與驗證：
[[2026-08-03-latency-observability-phase7a-operability-closeout]]、[[2026-08-03-latency-observability-phase7b-five-sample-evidence]]