AI Search API (LLM)
對齊 docs/SaaS-API.md 第 6.C.7 節（LLM 自然語言搜尋）。v0.11.0+ 新增。
端點範圍
| 方法 | 路徑 | 說明 |
|---|
| POST | /api/v1/analysis/insights/search | LLM 自然語言搜尋 |
前置條件
- 已完成設備、場景建立與分析啟動
- 認證：
Authorization: Bearer {API_KEY}
- 權限：
analytics:read
- Rate Limit：MODERATE（10 req/min）
工作原理
- 用戶提交自然語言查詢（支援中／英文）
- 後端使用 LLM
generateObject() 解析查詢意圖，提取：時間範圍、設備/場景關鍵字、風險等級、人數、活動類型
- 組成 PostgreSQL 複合查詢條件（JSONB + Full-text Search）
- 返回匹配結果 +
interpretation（供用戶驗證解析是否正確）+ tokensUsed
請求範例
curl -X POST "https://api.luminys.ai/api/v1/analysis/insights/search" \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"query": "昨天入口有人徘徊的高風險事件",
"limit": 10
}'
Request Body
| 欄位 | 型別 | 必填 | 說明 |
|---|
query | String | ✅ | 自然語言查詢（2-500 字元，支援中/英文） |
deviceId | UUID | ❌ | 預篩選特定設備 |
sceneId | UUID | ❌ | 預篩選特定場景 |
limit | Number | ❌ | 回傳筆數上限（1-50，預設 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"
}
}
Response 欄位
| 欄位 | 說明 |
|---|
data.data | 匹配的洞察列表（同 Insights API 列表格式） |
data.total | 匹配總數 |
data.interpretation | LLM 解析後的結構化條件（供驗證） |
data.tokensUsed | 本次搜尋消耗的 Token 數 |
interpretation 欄位
| 欄位 | 型別 | 說明 |
|---|
startDate | ISO 8601 | 解析的開始時間 |
endDate | ISO 8601 | 解析的結束時間 |
deviceKeyword | String | 設備名稱關鍵字 |
sceneKeyword | String | 場景名稱關鍵字 |
riskLevel | Enum | low / medium / high / critical |
severity | Enum | warning / critical |
minPersonCount | Number | 最少人數門檻 |
keywords | String[] | 全文搜索關鍵字 |
activityKeywords | String[] | 活動行為關鍵字 |
查詢範例
| 查詢 | LLM 解析 |
|---|
| "昨天入口有人徘徊的高風險事件" | startDate: yesterday, riskLevel: high, activityKeywords: ["徘徊"], deviceKeyword: "入口" |
| "超過10個人的嚴重告警" | severity: critical, minPersonCount: 10 |
| "high risk events with loitering at entrance" | riskLevel: high, activityKeywords: ["loitering"], deviceKeyword: "entrance" |
錯誤處理重點
400：查詢字串過短或格式不合法403：權限不足429：速率超限（LLM 搜尋有獨立限流，10 req/min）500：LLM 解析超時或服務不可用
實務建議
- 搜尋建議做防抖與快取，避免不必要 Token 消耗。
- 使用
interpretation 欄位向用戶展示 LLM 的解析結果，提高透明度。
- 可搭配
deviceId / sceneId 預篩選，減少 LLM 處理範圍。
相關文件