docs: update docs_v1.0/ documentation
- Fix markdown lint issues (MD030, MD047, MD051, MD028, MD005) - Update AI agents, architecture, implementation docs - Add new identity, face recognition, and API documentation - Remove deprecated face/person API guides
This commit is contained in:
Warren
@@ -64,7 +64,7 @@ ai_query_hints:
|
||||
|
||||
### 2.2 開發標準
|
||||
|
||||
#### Python 處理器標準：
|
||||
#### Python 處理器標準
|
||||
```python
|
||||
# 1. 必要的導入
|
||||
import json
|
||||
@@ -79,7 +79,7 @@ parser.add_argument("--output", required=True, help="Output path")
|
||||
args = parser.parse_args()
|
||||
|
||||
# 3. 主處理邏輯
|
||||
def process_video(video_uuid, output_path):
|
||||
def process_video(file_uuid, output_path):
|
||||
# 處理邏輯
|
||||
result = {
|
||||
"status": "success",
|
||||
@@ -107,31 +107,31 @@ if __name__ == "__main__":
|
||||
|
||||
### 3.1 測試類型
|
||||
|
||||
#### 單元測試：
|
||||
#### 單元測試
|
||||
- 測試處理器核心邏輯
|
||||
- 驗證輸入輸出格式
|
||||
- 測試錯誤處理
|
||||
|
||||
#### 集成測試：
|
||||
#### 集成測試
|
||||
- 測試與其他組件的集成
|
||||
- 驗證數據流完整
|
||||
- 測試性能表現
|
||||
|
||||
#### 回歸測試：
|
||||
#### 回歸測試
|
||||
- 確保新版本不破壞現有功能
|
||||
- 測試兼容性
|
||||
- 驗證性能改進
|
||||
|
||||
### 3.2 測試數據
|
||||
|
||||
#### 測試視頻：
|
||||
#### 測試視頻
|
||||
| 類型 | 用途 | 示例 |
|
||||
|------|------|------|
|
||||
| 短視頻（<1分鐘） | 快速測試 | test_video.mp4 |
|
||||
| 中等視頻（1-5分鐘） | 功能測試 | demo_video.mp4 |
|
||||
| 長視頻（>10分鐘） | 性能測試 | long_video.mp4 |
|
||||
|
||||
#### 測試環境：
|
||||
#### 測試環境
|
||||
1. **本地開發環境**：快速迭代
|
||||
2. **測試服務器**：集成測試
|
||||
3. **生產模擬環境**：性能測試
|
||||
@@ -187,25 +187,25 @@ INSERT INTO processors (
|
||||
|
||||
### 5.1 調度與執行
|
||||
|
||||
#### 任務調度流程：
|
||||
#### 任務調度流程
|
||||
```
|
||||
1. 任務創建 → 2. 處理器選擇 → 3. 資源分配
|
||||
→ 4. 執行監控 → 5. 結果收集 → 6. 狀態更新
|
||||
```
|
||||
|
||||
#### 執行監控：
|
||||
#### 執行監控
|
||||
1. **進程監控**：監控處理器進程狀態
|
||||
2. **資源監控**：監控 CPU、內存、GPU 使用
|
||||
3. **性能監控**：監控處理速度和進度
|
||||
|
||||
### 5.2 錯誤處理與恢復
|
||||
|
||||
#### 錯誤類型：
|
||||
#### 錯誤類型
|
||||
1. **可恢復錯誤**：臨時性問題，可重試
|
||||
2. **配置錯誤**：配置問題，需要修復
|
||||
3. **系統錯誤**：系統級問題，需要干預
|
||||
|
||||
#### 重試策略：
|
||||
#### 重試策略
|
||||
```rust
|
||||
// Rust 中的重試機制示例
|
||||
let result = run_with_retry(
|
||||
@@ -221,7 +221,7 @@ let result = run_with_retry(
|
||||
|
||||
### 5.3 性能優化
|
||||
|
||||
#### 優化策略：
|
||||
#### 優化策略
|
||||
1. **並行處理**：同時處理多個視頻
|
||||
2. **批處理**：批量處理相關任務
|
||||
3. **緩存優化**：重用計算結果
|
||||
@@ -233,13 +233,13 @@ let result = run_with_retry(
|
||||
|
||||
### 6.1 日常維護
|
||||
|
||||
#### 監控項目：
|
||||
#### 監控項目
|
||||
1. **處理器狀態**：運行狀態、健康狀態
|
||||
2. **性能指標**：處理速度、成功率
|
||||
3. **資源使用**：CPU、內存、存儲
|
||||
4. **錯誤率**：各種錯誤的發生頻率
|
||||
|
||||
#### 維護任務：
|
||||
#### 維護任務
|
||||
1. **日誌分析**：定期分析處理器日誌
|
||||
2. **性能調優**：根據監控數據進行調優
|
||||
3. **安全更新**：更新依賴庫修復安全漏洞
|
||||
@@ -247,13 +247,13 @@ let result = run_with_retry(
|
||||
|
||||
### 6.2 版本升級
|
||||
|
||||
#### 升級流程：
|
||||
#### 升級流程
|
||||
1. **兼容性檢查**：檢查新版本與現有系統的兼容性
|
||||
2. **回滾計劃**：制定升級失敗時的回滾計劃
|
||||
3. **分階段部署**：分階段逐步升級
|
||||
4. **驗證測試**：升級後進行全面測試
|
||||
|
||||
#### 版本兼容性矩陣：
|
||||
#### 版本兼容性矩陣
|
||||
| 處理器版本 | 系統版本 | 模型版本 | 狀態 |
|
||||
|------------|----------|----------|------|
|
||||
| v1.0.x | v0.1.0 | insightface==0.7.3 | ✅ 兼容 |
|
||||
@@ -361,4 +361,4 @@ let result = run_with_retry(
|
||||
|------|------|----------|--------|
|
||||
| V1.0 | 2026-04-22 | 創建處理器生命週期管理文檔 | OpenCode |
|
||||
|
||||
**最後更新日期**: 2026-04-22
|
||||
**最後更新日期**: 2026-04-22
|
||||
|
||||
@@ -305,10 +305,10 @@ match processor.execution_type.as_str() {
|
||||
處理器在執行時，需要查詢「服務註冊中心」來獲取依賴資源的配置。
|
||||
|
||||
**流程範例**:
|
||||
1. 排程器啟動 `asr_processor.py`。
|
||||
2. Python 腳本查詢本地配置檔 (由排程器生成，內容來自 `services` 表)。
|
||||
3. 腳本獲取 Ollama 的 `endpoint` 與 `model_name`。
|
||||
4. 腳本執行 Embedding 任務。
|
||||
1. 排程器啟動 `asr_processor.py`。
|
||||
2. Python 腳本查詢本地配置檔 (由排程器生成，內容來自 `services` 表)。
|
||||
3. 腳本獲取 Ollama 的 `endpoint` 與 `model_name`。
|
||||
4. 腳本執行 Embedding 任務。
|
||||
|
||||
這樣實現了**處理器與基礎設施配置的解耦**。
|
||||
|
||||
|
||||
@@ -22,8 +22,8 @@
|
||||
所有 Processor (YOLO, ASR...) 和 Agent (Translation, Summary...) 啟動時應主動註冊。
|
||||
|
||||
### 1.1 註冊時機
|
||||
* **Processor**: 在 Python 腳本啟動時，呼叫 HTTP Endpoint 註冊。
|
||||
* **Agent**: 在服務啟動時呼叫 HTTP Endpoint 註冊。
|
||||
* **Processor**: 在 Python 腳本啟動時，呼叫 HTTP Endpoint 註冊。
|
||||
* **Agent**: 在服務啟動時呼叫 HTTP Endpoint 註冊。
|
||||
|
||||
---
|
||||
|
||||
@@ -48,7 +48,7 @@
|
||||
}
|
||||
```
|
||||
|
||||
* **resource_id**: 建議格式 `{type}_{name}_{uuid}`，例如 `processor_yolo_a1b2c3`。
|
||||
* **resource_id**: 建議格式 `{type}_{name}_{uuid}`，例如 `processor_yolo_a1b2c3`。
|
||||
|
||||
### 2.3 Response
|
||||
|
||||
@@ -74,23 +74,23 @@
|
||||
```json
|
||||
{
|
||||
"status": "idle | busy | error",
|
||||
"job_uuid": "current_video_uuid",
|
||||
"job_uuid": "current_file_uuid",
|
||||
"progress": 0.45,
|
||||
"last_frame_index": 12500
|
||||
}
|
||||
```
|
||||
|
||||
* **progress**: 0.0 到 1.0 之間的浮點數。
|
||||
* **job_uuid**: 當前正在處理的任務 ID。
|
||||
* **progress**: 0.0 到 1.0 之間的浮點數。
|
||||
* **job_uuid**: 當前正在處理的任務 ID。
|
||||
|
||||
---
|
||||
|
||||
## 4. 監控用途
|
||||
|
||||
系統後台 (Portal Dashboard) 可透過查詢 Registry 實現：
|
||||
1. **即時儀表板**: 顯示目前有幾個 Processor 在運行 (`busy` 數量)。
|
||||
2. **進度條**: 透過 `last_frame_index` 與影片總幀數計算百分比。
|
||||
3. **健康檢查**: 若資源超過 60 秒未發送心跳，標記為 `offline`。
|
||||
1. **即時儀表板**: 顯示目前有幾個 Processor 在運行 (`busy` 數量)。
|
||||
2. **進度條**: 透過 `last_frame_index` 與影片總幀數計算百分比。
|
||||
3. **健康檢查**: 若資源超過 60 秒未發送心跳，標記為 `offline`。
|
||||
|
||||
---
|
||||
|
||||
@@ -116,5 +116,5 @@ deregister_resource(&resource_id).await;
|
||||
|
||||
## 版本資訊
|
||||
|
||||
- 版本: V1.0
|
||||
- 建立日期: 2026-04-25
|
||||
* 版本: V1.0
|
||||
* 建立日期: 2026-04-25
|
||||
|
||||
@@ -67,18 +67,18 @@
|
||||
|
||||
## 3. 資源生命週期 (Resource Lifecycle)
|
||||
|
||||
1. **註冊 (Registration)**:
|
||||
* 組件啟動時向 **Resource Registry** 報到，聲明其 ID、類型和能力。
|
||||
* *範例*: Agent 啟動，註冊 `resource_type: "agent"`, `capabilities: ["summarize_text"]`。
|
||||
2. **發現 (Discovery)**:
|
||||
* 調度器 (Scheduler) 根據任務需求查詢 Registry 尋找合適的資源。
|
||||
* *範例*: 任務需要「語音轉文字」，查詢 `capabilities: ["audio_to_text"]`。
|
||||
3. **分配與執行 (Allocation & Execution)**:
|
||||
* 狀態變為 `busy`，接收任務並執行。
|
||||
4. **健康檢查 (Health Monitoring)**:
|
||||
* Registry 定期 Ping 資源。若無回應，標記為 `offline`。
|
||||
5. **登出 (Deregistration)**:
|
||||
* 組件關閉或崩潰時從 Registry 移除。
|
||||
1. **註冊 (Registration)**:
|
||||
* 組件啟動時向 **Resource Registry** 報到，聲明其 ID、類型和能力。
|
||||
* *範例*: Agent 啟動，註冊 `resource_type: "agent"`, `capabilities: ["summarize_text"]`。
|
||||
2. **發現 (Discovery)**:
|
||||
* 調度器 (Scheduler) 根據任務需求查詢 Registry 尋找合適的資源。
|
||||
* *範例*: 任務需要「語音轉文字」，查詢 `capabilities: ["audio_to_text"]`。
|
||||
3. **分配與執行 (Allocation & Execution)**:
|
||||
* 狀態變為 `busy`，接收任務並執行。
|
||||
4. **健康檢查 (Health Monitoring)**:
|
||||
* Registry 定期 Ping 資源。若無回應，標記為 `offline`。
|
||||
5. **登出 (Deregistration)**:
|
||||
* 組件關閉或崩潰時從 Registry 移除。
|
||||
|
||||
---
|
||||
|
||||
@@ -127,36 +127,36 @@ CREATE INDEX idx_res_caps ON resources USING GIN(capabilities);
|
||||
## 5. 實作建議
|
||||
|
||||
### 5.1 Processor 實作 (確定性)
|
||||
* 通常由 Python 腳本或 Rust 二進制執行。
|
||||
* 啟動時呼叫 `POST /resources/register`，宣告如 `["video_to_frames", "detect_objects"]`。
|
||||
* 通常由 Python 腳本或 Rust 二進制執行。
|
||||
* 啟動時呼叫 `POST /resources/register`，宣告如 `["video_to_frames", "detect_objects"]`。
|
||||
|
||||
### 5.2 Agent 實作 (機率性)
|
||||
* 通常封裝為具備 LLM Context 的服務。
|
||||
* 啟動時呼叫 `POST /resources/register`，宣告如 `["summarize_text", "extract_5w1h"]`。
|
||||
* **重點**: 在 `metadata` 中記錄使用的 LLM 模型名稱 (e.g., `gpt-4o`, `llama3`)。
|
||||
* 通常封裝為具備 LLM Context 的服務。
|
||||
* 啟動時呼叫 `POST /resources/register`，宣告如 `["summarize_text", "extract_5w1h"]`。
|
||||
* **重點**: 在 `metadata` 中記錄使用的 LLM 模型名稱 (e.g., `gpt-4o`, `llama3`)。
|
||||
|
||||
### 5.3 Service 實作 (基礎設施)
|
||||
* 通常由 Docker Compose 或 Systemd 管理。
|
||||
* 可透過 Sidecar 或定期腳本進行註冊與心跳更新。
|
||||
* 通常由 Docker Compose 或 Systemd 管理。
|
||||
* 可透過 Sidecar 或定期腳本進行註冊與心跳更新。
|
||||
|
||||
---
|
||||
|
||||
## 6. 與其他架構的關係
|
||||
|
||||
* **Job/Task Scheduler**: 任務調度器依賴 Resource Registry 來尋找誰能執行任務。
|
||||
* **Configuration Management**: 資源的詳細參數 (如 API Key, Threshold) 應存在 Config 中心，Registry 僅儲存引用或摘要。
|
||||
* **Monitoring**: Prometheus/Grafana 應抓取 Registry 狀態來展示系統資源健康度儀表板。
|
||||
* **Job/Task Scheduler**: 任務調度器依賴 Resource Registry 來尋找誰能執行任務。
|
||||
* **Configuration Management**: 資源的詳細參數 (如 API Key, Threshold) 應存在 Config 中心，Registry 僅儲存引用或摘要。
|
||||
* **Monitoring**: Prometheus/Grafana 應抓取 Registry 狀態來展示系統資源健康度儀表板。
|
||||
|
||||
## 7. 關聯文檔
|
||||
|
||||
本目錄整合了原有的 Processor 與 Service 架構，並納入新的 Agent 架構：
|
||||
- `PROCESSOR_REGISTRY_ARCHITECTURE.md` - 舊版處理器註冊設計 (已整合)。
|
||||
- `SERVICE_REGISTRY_ARCHITECTURE.md` - 舊版服務註冊設計 (已整合)。
|
||||
- `PROCESSOR_LIFECYCLE.md` - 處理器生命週期 (資源生命週期的子集)。
|
||||
* `PROCESSOR_REGISTRY_ARCHITECTURE.md` - 舊版處理器註冊設計 (已整合)。
|
||||
* `SERVICE_REGISTRY_ARCHITECTURE.md` - 舊版服務註冊設計 (已整合)。
|
||||
* `PROCESSOR_LIFECYCLE.md` - 處理器生命週期 (資源生命週期的子集)。
|
||||
|
||||
---
|
||||
|
||||
## 版本資訊
|
||||
|
||||
- 版本: V1.0
|
||||
- 建立日期: 2026-04-25
|
||||
* 版本: V1.0
|
||||
* 建立日期: 2026-04-25
|
||||
|
||||
Reference in New Issue
Block a user