LLM / VLM API 使用指南
本章對齊
docs/SaaS-API.md第 6.C 節（Analysis Insights）與第 6.C.7 節（LLM 自然語言搜尋）。
端點範圍
| 方法 | 路徑 | 說明 |
|---|---|---|
| GET | /api/v1/analysis/insights | 洞察列表 |
| GET | /api/v1/analysis/insights/{id} | 洞察詳情 |
| GET | /api/v1/analysis/insights/{id}/snapshots | 洞察截圖 |
| GET | /api/v1/analysis/insights/{id}/attributes | 洞察關聯屬性（LEVEL_02） |
| GET | /api/v1/analysis/insights/attributes/stats | 屬性聚合統計（LEVEL_02） |
| GET | /api/v1/analysis/insights/vlm-summaries | VLM 摘要列表 |
| POST | /api/v1/analysis/insights/search | LLM 自然語言搜尋（v0.11.0+） |
| GET | /api/v1/analysis/attributes | 獨立屬性列表（v0.10.0+, LEVEL_02） |
| GET | /api/v1/analysis/attributes/{id} | 單筆屬性詳情（v0.10.0+, LEVEL_02） |
前置條件
- 已完成設備、場景建立與分析啟動
- 認證：
Authorization: Bearer {API_KEY} - 權限：
analytics:read - LEVEL_02 才能使用屬性相關端點
快速流程
- 先用
GET /analysis/insights做列表 - 點擊單筆用
GET /analysis/insights/{id}取完整資訊 - 需要摘要流時用
GET /analysis/insights/vlm-summaries - 需要語意查詢時用
POST /analysis/insights/search - 需要屬性資料時再打 attributes 端點（LEVEL_02）
1) 洞察列表
curl -X GET "https://api.example.com/api/v1/analysis/insights?page=1&limit=20" \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json"
{
"success": true,
"statusCode": 200,
"data": [
{
"id": "insight-uuid",
"sceneId": "scene-uuid",
"deviceId": "device-uuid",
"severity": "critical",
"vlmStatus": "completed",
"vlmSummary": "Queue is building up near counter A.",
"createdAt": "2026-02-26T10:30:00.000Z"
}
],
"meta": {
"timestamp": "2026-02-26T10:30:00.000Z",
"requestId": "7c9e6679-7425-4f2a-944b-e07fc1f90ae7"
}
}
2) 洞察詳情（含結構化結果）
curl -X GET "https://api.example.com/api/v1/analysis/insights/insight-uuid" \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json"
{
"success": true,
"statusCode": 200,
"data": {
"id": "insight-uuid",
"sceneId": "scene-uuid",
"deviceId": "device-uuid",
"vlmSummary": "Queue is building up near counter A.",
"vlmStructuredResult": {
"summary": "Queue wait time is increasing.",
"personCount": 15,
"riskLevel": "high",
"activities": ["queueing"],
"suggestions": ["Open one more service counter"],
"environment": "Indoor lobby"
},
"snapshotUrls": [
"https://cdn.example.com/snapshots/1.jpg",
"https://cdn.example.com/snapshots/2.jpg"
],
"createdAt": "2026-02-26T10:30:00.000Z"
},
"meta": {
"timestamp": "2026-02-26T10:30:00.000Z",
"requestId": "7c9e6679-7425-4f2a-944b-e07fc1f90ae7"
}
}
3) VLM 摘要列表
curl -X GET "https://api.example.com/api/v1/analysis/insights/vlm-summaries?sceneId=scene-uuid&limit=10" \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json"
4) LLM 自然語言搜尋（重點）
curl -X POST "https://api.example.com/api/v1/analysis/insights/search" \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"query": "昨天入口有人徘徊的高風險事件",
"limit": 10
}'
{
"success": true,
"statusCode": 200,
"data": {
"data": [
{
"id": "insight-uuid",
"severity": "critical",
"vlmSummary": "入口有人徘徊，風險等級高..."
}
],
"total": 1,
"interpretation": {
"riskLevel": "high",
"activityKeywords": ["徘徊"]
},
"tokensUsed": {
"inputTokens": 200,
"outputTokens": 50,
"totalTokens": 250
}
},
"meta": {
"timestamp": "2026-02-26T10:30:00.000Z",
"requestId": "7c9e6679-7425-4f2a-944b-e07fc1f90ae7"
}
}
5) 屬性 API（LEVEL_02）
curl -X GET "https://api.example.com/api/v1/analysis/insights/insight-uuid/attributes" \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json"
若設備非 level_02，常見回應：
{
"success": false,
"statusCode": 403,
"message": "Attributes feature requires LEVEL_02 plan",
"error": {
"code": "FORBIDDEN"
},
"meta": {
"timestamp": "2026-02-26T10:30:00.000Z",
"requestId": "7c9e6679-7425-4f2a-944b-e07fc1f90ae7"
}
}
錯誤處理重點
400：UUID 或日期格式不合法403：Plan 不足（LEVEL_01 呼叫屬性相關端點）404：Insight / Attribute 記錄不存在429：自然語言搜尋速率超限（LLM 搜尋）
實務建議
- 以
requestId串接 API、Queue、Compute Node 日誌。 - 列表頁優先打
insights/vlm-summaries，詳情頁才打insights/{id}。 - 自然語言搜尋建議做防抖與快取，避免不必要 token 消耗。