docs: add agents/search endpoint to 12_agent.md
This commit is contained in:
Accusys
@@ -116,6 +116,96 @@ Get status of the 5W1H agent pipeline for a file.
|
||||
| **Dimension** | 768 |
|
||||
| **Used by** | `parent_chunk_5w1h.py --embed`, story, 5W1H, search |
|
||||
|
||||
---
|
||||
|
||||
## POST /api/v1/agents/search
|
||||
|
||||
Conversational search assistant. Uses Gemma4 function calling to automatically decide which tools to call based on the user's natural language query. Supports multi-turn conversation.
|
||||
|
||||
### Request
|
||||
|
||||
```json
|
||||
{
|
||||
"query": "Audrey Hepburn 和 Cary Grant 第一次同框在哪個 frame？",
|
||||
"conversation_id": null,
|
||||
"file_uuid": null
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `query` | string | ✅ | 自然語言查詢 |
|
||||
| `conversation_id` | string | ❌ | 延續對話時傳入；新對話不傳 |
|
||||
| `file_uuid` | string | ❌ | Portal 有選中檔案時可指定 |
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"conversation_id": "conv_abc123",
|
||||
"answer": "在 Charade (1963) 中，Audrey Hepburn 與 Cary Grant 第一次同框在第 38619 幀（約 1544.76 秒）。",
|
||||
"need_input": false,
|
||||
"sources": [
|
||||
{
|
||||
"tool": "tkg_query",
|
||||
"result": "{\"first_cooccurrence\":{\"frame\":38619,\"timestamp_secs\":1544.76}}"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `conversation_id` | string | 後續對話需要傳入此 ID |
|
||||
| `answer` | string | Agent 的自然語言回答（或反問） |
|
||||
| `need_input` | boolean | `true` 表示 agent 需要更多資訊才能回答 |
|
||||
| `suggestions` | string[] | 建議用戶提供的線索（當 `need_input=true`） |
|
||||
| `sources` | array | 引用的工具執行結果 |
|
||||
|
||||
### Conversation Flow
|
||||
|
||||
```
|
||||
Round 1: POST /agents/search { query: "我想看男女主角同框" }
|
||||
→ need_input: true, suggestions: ["片名", "演員", "年代"]
|
||||
→ answer: "請問是哪部電影？請提供更多線索"
|
||||
|
||||
Round 2: POST /agents/search { query: "奧黛麗赫本", conversation_id: "..." }
|
||||
→ need_input: false
|
||||
→ answer: "找到 Charade (1963)，Audrey Hepburn 和 Cary Grant..."
|
||||
```
|
||||
|
||||
### Available Tools
|
||||
|
||||
Agent 內部使用 Gemma4 function calling 自動調用以下工具：
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `find_file` | 透過片名/演員/年份關鍵字搜尋影片，回傳 file_uuid + has_data 狀態 |
|
||||
| `list_files` | 列出近期註冊的影片 |
|
||||
| `tkg_query` | 查詢人物互動資料（7 種子類型：top_identities、first_cooccurrence、identity_details、mutual_gaze、interaction_network、identity_traces、file_info） |
|
||||
| `smart_search` | 文字內容 ILIKE 搜尋 chunk（可指定 file_uuid 限制範圍） |
|
||||
| `get_identity_detail` | 查詢單一身份的詳細資料（角色、TMDb 資訊） |
|
||||
| `get_file_info` | 查詢影片基本資訊（片長、解析度） |
|
||||
| `get_representative_frame` | 查詢影片最具代表性的 frame 資訊 |
|
||||
|
||||
### Design Principles
|
||||
|
||||
- **用戶不需要知道 file_uuid** — Agent 會自動用 `find_file` 搜尋或反問
|
||||
- **不推薦無資料的影片** — `has_data=false` 的影片不會被推薦給用戶
|
||||
- **多輪對話** — 透過 `conversation_id` 延續上下文，agent 會記得之前的交流
|
||||
- **並行工具呼叫** — Gemma4 可以一次呼叫多個工具再綜合回答
|
||||
|
||||
### Model
|
||||
|
||||
| Detail | Value |
|
||||
|--------|-------|
|
||||
| **LLM** | Gemma4 26B (Q5_K_M) |
|
||||
| **Engine** | llama.cpp at `localhost:8082` |
|
||||
| **Endpoint** | `/v1/chat/completions` (OpenAI-compatible) |
|
||||
| **Temperature** | 0.1 |
|
||||
| **Max rounds** | 5 (tool call iterations) |
|
||||
| **Conversation TTL** | 30 minutes |
|
||||
|
||||
---
|
||||
*Updated: 2026-05-19 12:49:24*
|
||||
*Updated: 2026-05-22*
|
||||
|
||||
@@ -116,6 +116,96 @@ Get status of the 5W1H agent pipeline for a file.
|
||||
| **Dimension** | 768 |
|
||||
| **Used by** | `parent_chunk_5w1h.py --embed`, story, 5W1H, search |
|
||||
|
||||
---
|
||||
|
||||
## POST /api/v1/agents/search
|
||||
|
||||
Conversational search assistant. Uses Gemma4 function calling to automatically decide which tools to call based on the user's natural language query. Supports multi-turn conversation.
|
||||
|
||||
### Request
|
||||
|
||||
```json
|
||||
{
|
||||
"query": "Audrey Hepburn 和 Cary Grant 第一次同框在哪個 frame？",
|
||||
"conversation_id": null,
|
||||
"file_uuid": null
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `query` | string | ✅ | 自然語言查詢 |
|
||||
| `conversation_id` | string | ❌ | 延續對話時傳入；新對話不傳 |
|
||||
| `file_uuid` | string | ❌ | Portal 有選中檔案時可指定 |
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"conversation_id": "conv_abc123",
|
||||
"answer": "在 Charade (1963) 中，Audrey Hepburn 與 Cary Grant 第一次同框在第 38619 幀（約 1544.76 秒）。",
|
||||
"need_input": false,
|
||||
"sources": [
|
||||
{
|
||||
"tool": "tkg_query",
|
||||
"result": "{\"first_cooccurrence\":{\"frame\":38619,\"timestamp_secs\":1544.76}}"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `conversation_id` | string | 後續對話需要傳入此 ID |
|
||||
| `answer` | string | Agent 的自然語言回答（或反問） |
|
||||
| `need_input` | boolean | `true` 表示 agent 需要更多資訊才能回答 |
|
||||
| `suggestions` | string[] | 建議用戶提供的線索（當 `need_input=true`） |
|
||||
| `sources` | array | 引用的工具執行結果 |
|
||||
|
||||
### Conversation Flow
|
||||
|
||||
```
|
||||
Round 1: POST /agents/search { query: "我想看男女主角同框" }
|
||||
→ need_input: true, suggestions: ["片名", "演員", "年代"]
|
||||
→ answer: "請問是哪部電影？請提供更多線索"
|
||||
|
||||
Round 2: POST /agents/search { query: "奧黛麗赫本", conversation_id: "..." }
|
||||
→ need_input: false
|
||||
→ answer: "找到 Charade (1963)，Audrey Hepburn 和 Cary Grant..."
|
||||
```
|
||||
|
||||
### Available Tools
|
||||
|
||||
Agent 內部使用 Gemma4 function calling 自動調用以下工具：
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `find_file` | 透過片名/演員/年份關鍵字搜尋影片，回傳 file_uuid + has_data 狀態 |
|
||||
| `list_files` | 列出近期註冊的影片 |
|
||||
| `tkg_query` | 查詢人物互動資料（7 種子類型：top_identities、first_cooccurrence、identity_details、mutual_gaze、interaction_network、identity_traces、file_info） |
|
||||
| `smart_search` | 文字內容 ILIKE 搜尋 chunk（可指定 file_uuid 限制範圍） |
|
||||
| `get_identity_detail` | 查詢單一身份的詳細資料（角色、TMDb 資訊） |
|
||||
| `get_file_info` | 查詢影片基本資訊（片長、解析度） |
|
||||
| `get_representative_frame` | 查詢影片最具代表性的 frame 資訊 |
|
||||
|
||||
### Design Principles
|
||||
|
||||
- **用戶不需要知道 file_uuid** — Agent 會自動用 `find_file` 搜尋或反問
|
||||
- **不推薦無資料的影片** — `has_data=false` 的影片不會被推薦給用戶
|
||||
- **多輪對話** — 透過 `conversation_id` 延續上下文，agent 會記得之前的交流
|
||||
- **並行工具呼叫** — Gemma4 可以一次呼叫多個工具再綜合回答
|
||||
|
||||
### Model
|
||||
|
||||
| Detail | Value |
|
||||
|--------|-------|
|
||||
| **LLM** | Gemma4 26B (Q5_K_M) |
|
||||
| **Engine** | llama.cpp at `localhost:8082` |
|
||||
| **Endpoint** | `/v1/chat/completions` (OpenAI-compatible) |
|
||||
| **Temperature** | 0.1 |
|
||||
| **Max rounds** | 5 (tool call iterations) |
|
||||
| **Conversation TTL** | 30 minutes |
|
||||
|
||||
---
|
||||
*Updated: 2026-05-19 12:49:24*
|
||||
*Updated: 2026-05-22*
|
||||
|
||||
Reference in New Issue
Block a user