AI API 延遲指標：TTFT、第一個有效回應與輸出速度

AI API 延遲不是單一數字。對串流請求，應分別記錄上游 Header、第一個非空 SSE Event、第一個有效內容或動作、第一段可見文字與完整回應的時間。這些里程碑回答不同問題，不應全部稱為 TTFT。

純文字聊天通常以 First Visible Text 代表使用者感受；Reasoning 或 Tool Workflow 可能先產生 Function Arguments 等有效輸出。輸出開始後的 Generation Speed 又是另一個測量維度。

先建立一條 Request Timeline

所有 Gateway 層 Timestamp 應使用同一 Monotonic Clock 與同一起點：

t0  Gateway 收到請求
t1  Gateway 開始 Upstream Request
t2  Upstream Response Headers 到達
t3  第一個非空 SSE Event 到達
t4  第一個有效內容或動作到達
t5  第一個可見 Text Delta 到達
t6  Upstream Body 完成或關閉
t7  Gateway Handler 完成

並非每筆請求都有所有事件。Non-streaming 沒有 SSE Timeline；只產生 Function Call 的回應可能沒有可見文字；取消的 Stream 可能沒有正常完成。缺少值應保存為 Absent，而不是 0。

欄位	測量內容	重要邊界
auth_ms	Token 與 User 驗證時間	本地階段，不是上游時間
distribution_ms	Channel Selection 與 Routing Policy	本地階段
body_read_ms	讀取 Downstream Request Body	可發現路由前的慢速 Upload
upstream_headers_ms	Upstream Start 到 Response Headers	起點是 Upstream Start
first_sse_event_ms	Gateway Receipt 到第一個非空 SSE Event	Event 可能只有 Metadata
first_response_ms	到第一個有效內容或 Action Delta	包含文字、Reasoning Summary、Function Arguments
first_text_delta_ms	到第一段可見文字	沒有文字時不存在
upstream_done_ms	到 Upstream Body 關閉	關閉不一定代表成功
total_handler_ms	到最後已知 Relay 完成點	最接近 Gateway E2E
visible_output_tps	Output Tokens / 可見生成時間	使用者輸出診斷，不是系統總 TPS

不要相減起點不同的 Duration。例如 upstream_headers_ms 從 Upstream Start 計算，而 first_response_ms 從 Gateway Receipt 計算。

TTFT 有多種實際含義

NVIDIA NIM Benchmarking 指南把 Time to First Token 定義為送出查詢到第一個有效 Output Token，通常包含網路、Queue 與 Prompt Prefill，空白初始回應不應計算。

現代 API 在可見文字前可能先送出 Response-created Event、Reasoning Summary、Function Arguments、Custom Tool Input 或 Heartbeat。因此 Dashboard 應使用明確名稱：

名稱	建議定義	用途
Time to Headers	Request Start 到 Upstream Headers	網路與 Admission 診斷
Time to First Event	到第一個非空 SSE Event	僅表示傳輸活性
Time to First Effective Response	到可用內容或動作	Agent 與 Reasoning 響應性
Time to First Visible Text	到使用者可顯示文字	Chat 體感延遲

若圖表只寫 TTFT，必須在旁邊說明實際採用哪一列。

分開 Responsiveness 與 Generation Speed

end_to_end_latency = final_response_time - request_start_time
visible_generation_window = final_response_time - first_visible_text_time
visible_output_tps = output_tokens / visible_generation_window_seconds

Inter-token Latency 通常排除 TTFT，再以剩餘時間除以 output_tokens - 1。不要用 SSE Event 或 Text Delta 數量冒充 Token 數量；單一 Event 可含零個或多個 Token，而且 Token Boundary 依 Tokenizer 而異。

低 First-text Latency 配合慢 Output TPS，體感是快速開始後變慢；高 First-text Latency 配合快 TPS，則像長時間停頓後快速完成。Per-user TPS 與全系統 Aggregate Throughput 也不是同一概念。

Reasoning 與 Tools 可能早於可見文字

純文字流程中，first_response_ms 與 first_text_delta_ms 可能接近；Function Calling 流程則可能在 1.8 秒收到 Arguments，到 6.4 秒才出現文字。前者代表系統已有可執行動作，後者才代表 UI 可顯示答案。

• Terminal Agent 可使用 First Effective Action；
• 只顯示文字的 Chat UI 應使用 First Visible Text；
• Tool-call API 可能完全不需要文字；
• Early SSE Envelope 只證明連線進展，不證明有用進展。

AI API Streaming 指南說明 SSE Parsing、Cancellation 與 Idle Timeout；Parser 必須先辨識 Envelope 與 Effective Output，才能計算正確延遲。

依固定順序診斷慢速階段

現象	主要指標	優先檢查
Header 前很慢	upstream_headers_ms	Network、Provider Admission、Queue、Route、Region
Header 快但有效輸出慢	first_response_ms 與早期階段差值	Model Queue、Prefill、Reasoning、Inflight
First Event 快、Effective Output 慢	first_sse_event_ms 到 first_response_ms	Metadata Event、Heartbeat、Reasoning Startup
Action 快、Visible Text 慢	first_response_ms 到 first_text_delta_ms	Tool/Reasoning Phase 或 Response Composition
文字快出現但生成慢	visible_output_tps、upstream_done_ms	Decode Throughput、Contention、Long Context
上游正常	auth_ms、distribution_ms、body_read_ms	本地驗證、Policy Selection、Client Upload

單一指標不能證明 Root Cause。高 upstream_headers_ms 仍需 Route、Region、Provider 與 Concurrent Load 證據才能拆解。

閱讀三條合成 Trace

以下只用於診斷，不代表 Modelflare 或供應商平均值。

Trace A：等待 Upstream Headers

Metric	Value
upstream_headers_ms	6,100 ms
first_response_ms	6,350 ms
first_text_delta_ms	6,400 ms
total_handler_ms	9,200 ms
visible_output_tps	42

大部分時間在 Header 前，生成速度正常。應先檢查 Route、Admission、Network、Region 與負載，而不是 Client Renderer。

Trace B：有效動作早於可見文字

Metric	Value
upstream_headers_ms	240 ms
first_response_ms	2,900 ms
first_text_delta_ms	8,700 ms
total_handler_ms	10,200 ms
visible_output_tps	55

傳輸很快，2.9 秒已有 Action，但文字再等 5.8 秒。應檢查 Reasoning 或 Tool Phase，增加 Header Timeout 沒有幫助。

Trace C：開始快、生成慢

Metric	Value
upstream_headers_ms	260 ms
first_response_ms	420 ms
first_text_delta_ms	430 ms
total_handler_ms	20,430 ms
visible_output_tps	9.8

第一段文字很快，但生成近 20 秒。比較 Output Length、Context、Channel、Inflight 與 Provider；First-output Timeout 無法偵測這類問題。

只在受控條件下比較延遲

至少固定並記錄：模型與路由、Input/Output Token Distribution、Streaming Mode、Reasoning Effort、Tools、Region、Network Path、Concurrency、Sampling、Max Output、Warmup、Retry Policy、Sample Size 與 Percentile Method。

比較 p50、p95 與 p99，不要只放 Average。Timeout 與 Error 不應被移除，否則不可靠的路由反而可能看起來更快。Prompt、Output Length、Concurrency 或 Endpoint Behavior 不同時，不能把差異簡化成 Model Speed Ranking。

保留診斷 Metadata，而不是內容

延遲診斷通常只需 Request ID、Timestamp、Model、Group、Channel Reference、Status、Token Count、Timing Fields、Event Count、Inflight、Coarse Region 與安全的 Error Classifier，例如 upstream_headers_slow 或 generation_slow_tps。

不必保存 Prompt、Response、API Key 或明文 Client Identity。Metadata 仍可能透露操作行為，因此也要設定 Retention 與 Access Control。

調查應從完整 Timeline 開始，再用可靠 AI API 路由比較每次 Attempt 的路由，並以 AI API 錯誤排查連結 Terminal Status。這樣才能區分 Admission、Model Startup、Reasoning/Tool、Visible Generation 與本地 Gateway Overhead。