{
  "schema": "aiinfra_local_ai_concurrency_record_template",
  "schema_version": "1.0",
  "dataset_version": "2026-09-02",
  "last_verified": "2026-09-02",
  "title": "本地 AI 多人併發壓力測試紀錄範本",
  "scope": "記錄單一模型、引擎、硬體、工作負載與 concurrency 或 request rate 測試點；用於重跑、比較與人工驗收，不是本站跑分或通用使用者容量答案。",
  "usage_note": "每個測試點建立一筆 record。未量測、未知或 unavailable 使用 null 或明確狀態，不以 0 補值；原始 benchmark output、metrics snapshot、命令與版本證據另行保存。",
  "evidence_stage_values": {
    "CONFIG_ONLY": "只有設定與計畫，尚未產生量測結果。",
    "SINGLE_STREAM_BASELINE": "固定版本與 workload 的單流基線，只支持該測試點。",
    "CONCURRENCY_SWEEP": "以多個 concurrency 或 request rate 測試點建立曲線。",
    "SOAK_TEST": "在固定負載下持續觀察熱穩態、錯誤與資源行為。",
    "SANITIZED_TRACE_REPLAY": "使用已去識別的真實到達形狀重播，仍受 trace 範圍限制。"
  },
  "result_values": [
    "NOT_TESTED",
    "PASS",
    "FAIL",
    "INCONCLUSIVE"
  ],
  "fields": [
    { "name": "test_id", "type": "string|null", "required": true, "description": "單一測試點的穩定識別碼。" },
    { "name": "recorded_at", "type": "ISO-8601 datetime|null", "required": true, "description": "測試時間與時區。" },
    { "name": "evidence_stage", "type": "enum", "required": true, "description": "CONFIG_ONLY、SINGLE_STREAM_BASELINE、CONCURRENCY_SWEEP、SOAK_TEST 或 SANITIZED_TRACE_REPLAY。" },
    { "name": "environment", "type": "string|null", "required": true, "description": "lab、office、staging 或其他環境邊界。" },
    { "name": "serving_engine", "type": "string|null", "required": true, "description": "推論引擎，例如 vLLM、llama.cpp 或 Ollama。" },
    { "name": "engine_version", "type": "string|null", "required": true, "description": "引擎版本或 commit。" },
    { "name": "model_id", "type": "string|null", "required": true, "description": "完整模型名稱或路徑。" },
    { "name": "model_revision", "type": "string|null", "required": false, "description": "模型 tag、commit 或 hash。" },
    { "name": "quantization", "type": "string|null", "required": true, "description": "dtype 或量化格式。" },
    { "name": "tokenizer_revision", "type": "string|null", "required": false, "description": "Tokenizer 版本；若與模型相同仍可明列。" },
    { "name": "accelerator", "type": "string|null", "required": true, "description": "GPU、NPU 或其他加速器型號與數量。" },
    { "name": "memory_capacity_gb", "type": "number|null", "required": false, "description": "可用 VRAM 或 unified memory 容量；類型在限制中說明。" },
    { "name": "driver_runtime_host", "type": "string|null", "required": true, "description": "Driver、CUDA 或 ROCm、CPU、RAM 與作業系統。" },
    { "name": "workload_name", "type": "string|null", "required": true, "description": "代表性工作負載名稱。" },
    { "name": "dataset_or_prompt_source", "type": "string|null", "required": true, "description": "資料集、prompt 分布、檔案 hash 或去識別 trace 來源。" },
    { "name": "request_arrival_mode", "type": "enum|string|null", "required": true, "description": "closed-loop、open-loop、sanitized-trace-replay、other 或 UNKNOWN。" },
    { "name": "streaming", "type": "boolean|string|null", "required": false, "description": "是否使用串流輸出；未知時使用 UNKNOWN 或 null。" },
    { "name": "request_rate_rps", "type": "number|null", "required": false, "description": "每秒新到達請求；未控制時保留 null。" },
    { "name": "concurrency", "type": "integer|null", "required": true, "description": "同時 in-flight 請求數，不等於註冊或實際使用者總數。" },
    { "name": "max_active_sequences", "type": "integer|null", "required": false, "description": "引擎設定的最大 active sequences。" },
    { "name": "context_limit", "type": "integer|null", "required": false, "description": "測試時的 context limit，單位 tokens。" },
    { "name": "input_tokens_p50", "type": "number|null", "required": true, "description": "輸入 token 長度中位數。" },
    { "name": "output_tokens_p50", "type": "number|null", "required": false, "description": "輸出 token 長度中位數。" },
    { "name": "warmup_requests", "type": "integer|null", "required": false, "description": "正式量測前 warm-up 請求數。" },
    { "name": "measured_requests", "type": "integer|null", "required": true, "description": "正式量測請求數。" },
    { "name": "test_duration_minutes", "type": "number|null", "required": false, "description": "正式量測持續時間，單位分鐘。" },
    { "name": "successful_requests", "type": "integer|null", "required": true, "description": "成功請求數；未量測時為 null。" },
    { "name": "failed_requests", "type": "integer|null", "required": true, "description": "失敗請求數；未量測時為 null。" },
    { "name": "request_throughput_rps", "type": "number|null", "required": true, "description": "完成請求吞吐，單位 requests/s。" },
    { "name": "output_throughput_tps", "type": "number|null", "required": true, "description": "整體輸出吞吐，單位 output tokens/s。" },
    { "name": "ttft_p50_ms", "type": "number|null", "required": false, "description": "Time to First Token p50，單位毫秒。" },
    { "name": "ttft_p95_ms", "type": "number|null", "required": true, "description": "Time to First Token p95，單位毫秒。" },
    { "name": "tpot_p50_ms", "type": "number|null", "required": false, "description": "Time Per Output Token p50，單位毫秒／token。" },
    { "name": "tpot_p95_ms", "type": "number|null", "required": true, "description": "Time Per Output Token p95，單位毫秒／token。" },
    { "name": "e2e_p95_ms", "type": "number|null", "required": true, "description": "端到端請求延遲 p95，單位毫秒。" },
    { "name": "queue_p95_ms", "type": "number|null", "required": true, "description": "排隊時間 p95，單位毫秒；引擎未提供時為 null。" },
    { "name": "kv_cache_usage_peak_percent", "type": "number|null", "required": false, "description": "KV cache 使用率峰值百分比；引擎未提供時為 null。" },
    { "name": "memory_usage_peak_gb", "type": "number|null", "required": false, "description": "記憶體使用峰值，單位 GB；量測工具在限制中說明。" },
    { "name": "preemptions_or_evictions", "type": "integer|null", "required": false, "description": "測試期間 preemption 或 eviction 次數。" },
    { "name": "acceptance_thresholds", "type": "string|null", "required": true, "description": "測試前定義的延遲、錯誤、吞吐與持續時間門檻。" },
    { "name": "result", "type": "enum", "required": true, "description": "NOT_TESTED、PASS、FAIL 或 INCONCLUSIVE。" },
    { "name": "evidence_location", "type": "string|null", "required": true, "description": "原始 JSON、metrics snapshot、命令、log、commit 或工單位置。" },
    { "name": "limitations", "type": "string|null", "required": true, "description": "未涵蓋條件、量測限制與不可外推事項。" }
  ],
  "metric_definitions": {
    "concurrency": "同時位於系統內的 in-flight 請求數。",
    "request_rate_rps": "每秒新到達請求數；與 concurrency 是不同控制變數。",
    "ttft": "請求抵達到第一個輸出 token 的時間。",
    "tpot": "第一個 token 後，每個輸出 token 的平均或分位時間。",
    "request_throughput": "單位時間內成功完成的請求數。",
    "output_throughput": "所有請求合計的輸出 token 速率。",
    "error_rate": "failed_requests / (successful_requests + failed_requests)；分母未量測或為 0 時應保留 unavailable。"
  },
  "interpretation_rules": [
    "單流 tokens/s 不能單獨回答多人容量。",
    "PASS 必須引用測試前門檻與原始證據，不由空白範本自動產生。",
    "變更模型、revision、量化、context、引擎、硬體或 workload 後應重跑。",
    "最高吞吐點若已超過延遲或錯誤門檻，不是可接受容量點。",
    "合成 prompt、指定 trace 或單一硬體結果不得外推成所有使用者與環境。"
  ],
  "sources": [
    {
      "label": "vLLM Metrics",
      "url": "https://docs.vllm.ai/en/stable/design/metrics/"
    },
    {
      "label": "vLLM Online serving benchmark",
      "url": "https://docs.vllm.ai/en/stable/api/vllm/benchmarks/serve/"
    },
    {
      "label": "vLLM Parallelism and scaling",
      "url": "https://github.com/vllm-project/vllm/blob/main/docs/serving/parallelism_scaling.md"
    }
  ],
  "record": {
    "test_id": "replace-me",
    "recorded_at": null,
    "evidence_stage": "CONFIG_ONLY",
    "environment": null,
    "serving_engine": null,
    "engine_version": null,
    "model_id": null,
    "model_revision": null,
    "quantization": null,
    "tokenizer_revision": null,
    "accelerator": null,
    "memory_capacity_gb": null,
    "driver_runtime_host": null,
    "workload_name": null,
    "dataset_or_prompt_source": null,
    "request_arrival_mode": "UNKNOWN",
    "streaming": "UNKNOWN",
    "request_rate_rps": null,
    "concurrency": null,
    "max_active_sequences": null,
    "context_limit": null,
    "input_tokens_p50": null,
    "output_tokens_p50": null,
    "warmup_requests": null,
    "measured_requests": null,
    "test_duration_minutes": null,
    "successful_requests": null,
    "failed_requests": null,
    "request_throughput_rps": null,
    "output_throughput_tps": null,
    "ttft_p50_ms": null,
    "ttft_p95_ms": null,
    "tpot_p50_ms": null,
    "tpot_p95_ms": null,
    "e2e_p95_ms": null,
    "queue_p95_ms": null,
    "kv_cache_usage_peak_percent": null,
    "memory_usage_peak_gb": null,
    "preemptions_or_evictions": null,
    "acceptance_thresholds": null,
    "result": "NOT_TESTED",
    "evidence_location": null,
    "limitations": "空白範本；尚未量測，不能外推成實際使用者人數。"
  }
}