287 lines
6.1 KiB
Markdown
287 lines
6.1 KiB
Markdown
# Kneron Toolchain Convert Orchestrator — 設計文件（Crash 即 Reset 版）
|
||
|
||
## 0. 目的與範圍
|
||
|
||
### 目的
|
||
將 Kneron Toolchain 的模型轉換流程（ONNX → BIE → NEF）拆分為可水平擴充的 Worker Pool，
|
||
由 Scheduler 統一派工與狀態管理，並使用 MinIO 作為跨主機的 artifact 交換區，
|
||
以解決單一 VM / 單一 Toolchain instance 在高併發下造成 CPU 爆滿與 Crash 的問題。
|
||
|
||
### 範圍
|
||
- Web UI：上傳 / 查詢狀態 / 下載結果
|
||
- Task Scheduler：建立任務、寫入狀態、推送 queue、接收完成事件
|
||
- Worker Pools：
|
||
- ONNX Flow Worker Pool
|
||
- BIE Flow Worker Pool
|
||
- NEF Flow Worker Pool
|
||
- Redis：暫存 job 狀態（**重啟即清空**）
|
||
- Queue：暫存待處理任務與完成事件（**重啟即清空**）
|
||
- MinIO：存放 input/output/logs（可保留或定期清理）
|
||
|
||
### 非目標（Non-goals）
|
||
- 不做任務持久化（durability）
|
||
- 不做 crash 後 resume
|
||
- 不做 exactly-once / at-least-once 保證
|
||
- 不做 Scheduler HA
|
||
- 不做自動 retry（失敗即請使用者重送）
|
||
|
||
---
|
||
|
||
## 1. 核心設計哲學：Crash 即 Reset
|
||
|
||
- Redis 重啟 → 所有 job 狀態消失
|
||
- Queue 重啟 → 所有排隊任務消失
|
||
- Scheduler / Worker 重啟 → 不嘗試恢復任何舊任務
|
||
- UI 查不到 job → 顯示「系統已重啟，請重新送出」
|
||
- 任務資料不具不可遺失性（loss-tolerant）
|
||
|
||
---
|
||
|
||
## 2. 系統元件與責任
|
||
|
||
### 2.1 Web UI
|
||
- 提供使用者：
|
||
- 上傳 model.onnx、quant.zip
|
||
- 建立轉換任務
|
||
- 查詢任務狀態
|
||
- 下載 BIE / NEF
|
||
- Web UI 不直接讀寫 Redis 或 Queue
|
||
- Web UI 可直接與 MinIO 上傳 / 下載（或透過 Scheduler 取得路徑）
|
||
- 狀態更新：以 SSE 為主，Polling 為備援（3-5 秒）
|
||
|
||
### 2.2 Task Scheduler（控制面）
|
||
- 唯一的控制面元件
|
||
- 職責：
|
||
- 建立 job_id
|
||
- 建立 Redis job record
|
||
- 將 job 推入對應 task queue
|
||
- 接收 worker 完成事件（done queue）
|
||
- 推進 job 狀態（ONNX → BIE → NEF → COMPLETED）
|
||
- 流程固定：ONNX → BIE → NEF，不支援跳過或只跑部分
|
||
- Scheduler 不等待 worker、不執行 heavy CPU 任務
|
||
|
||
### 2.3 Task Queue
|
||
- 至少包含以下 queue：
|
||
- queue:onnx
|
||
- queue:bie
|
||
- queue:nef
|
||
- queue:done
|
||
- Queue 僅用於「暫存」任務（重啟可清空）
|
||
|
||
### 2.4 Worker Pools
|
||
- ONNX / BIE / NEF Worker 各自獨立 pool
|
||
- Worker 特性：
|
||
- 無狀態
|
||
- pull-based（自行從 queue 取任務）
|
||
- 一次只處理一個 job
|
||
- Worker 失敗：
|
||
- 回報 fail
|
||
- Scheduler 將 job 標記為 FAILED
|
||
|
||
### 2.5 MinIO（Artifact Store）
|
||
- 所有 job 的 input / output / log 都放在 MinIO
|
||
- 作為跨 worker / 跨主機的唯一資料交換區
|
||
|
||
---
|
||
|
||
## 3. 命名與資料結構
|
||
|
||
### 3.1 Job ID
|
||
- 使用 UUID v4
|
||
- 全系統唯一
|
||
|
||
### 3.2 MinIO 路徑規則（建議）
|
||
|
||
Bucket：toolchain-jobs
|
||
|
||
```
|
||
jobs/{job_id}/
|
||
input/
|
||
model.onnx
|
||
quant.zip
|
||
output/
|
||
result.bie
|
||
result.nef
|
||
logs/
|
||
onnx.log
|
||
bie.log
|
||
nef.log
|
||
```
|
||
|
||
### 3.3 Redis Job Record（Hash / JSON）
|
||
|
||
Key：job:{job_id}
|
||
|
||
```
|
||
job_id
|
||
created_at
|
||
status: ONNX | BIE | NEF | COMPLETED | FAILED
|
||
stage: ONNX | BIE | NEF
|
||
progress: 0-100
|
||
updated_at
|
||
output:
|
||
bie_key
|
||
nef_key
|
||
error:
|
||
step
|
||
reason
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 成功流程（Happy Path）
|
||
|
||
1. 使用者透過 Web UI 建立轉換任務
|
||
2. Web UI 上傳 input 到 MinIO
|
||
3. Scheduler 建立 job record，push 到 queue:onnx
|
||
4. ONNX worker pull 任務、執行、push done
|
||
5. Scheduler 推進狀態，push 到 queue:bie
|
||
6. BIE worker 執行、輸出 result.bie、push done
|
||
7. Scheduler 推進狀態，push 到 queue:nef
|
||
8. NEF worker 執行、輸出 result.nef、push done
|
||
9. Scheduler 標記 COMPLETED
|
||
10. Web UI 取得下載路徑
|
||
|
||
---
|
||
|
||
## 4.1 工作目錄與 Worker I/O 規格（落地版）
|
||
|
||
以下為實作落地時的檔案布局與 worker 互動規格（與 MinIO 路徑可一對一對應）：
|
||
|
||
### 4.1.1 工作目錄
|
||
- API 取號後建立 `task_id`
|
||
- API 將使用者上傳檔案放入工作目錄：
|
||
- `{base_path}/{task_id}/`
|
||
- 參考圖片固定放在 `ref_images/`
|
||
|
||
```
|
||
{base_path}/{task_id}/
|
||
<single_input_file> # 唯一輸入檔（副檔名不固定）
|
||
ref_images/
|
||
<image files...>
|
||
```
|
||
|
||
### 4.1.2 ONNX Worker
|
||
- 輸入：工作目錄下的唯一檔案（不假設檔名 / 副檔名）
|
||
- 輸出：`out.onnx`
|
||
- 輸出位置：同一工作目錄
|
||
|
||
### 4.1.3 BIE Worker
|
||
- 輸入：`out.onnx` + `ref_images/*`
|
||
- 輸出：`out.bie`
|
||
- 輸出位置：同一工作目錄
|
||
|
||
### 4.1.4 NEF Worker
|
||
- 輸入：`out.bie`
|
||
- 輸出：`out.nef`
|
||
- 輸出位置：同一工作目錄
|
||
|
||
### 4.1.5 Core / Toolchain 路徑一致性
|
||
- Worker 需將工作目錄 path 傳給 core
|
||
- Core 需設定 toolchain 相關 path（輸出與中間檔）都指向該工作目錄
|
||
|
||
---
|
||
|
||
## 5. 失敗行為（簡化）
|
||
|
||
- Worker 例外 → 回報 fail
|
||
- Scheduler 標記 job 為 FAILED
|
||
- UI 顯示失敗並要求使用者重新送出
|
||
- Redis / Queue Crash → 所有 job 消失，視同 reset
|
||
|
||
---
|
||
|
||
## 6. API（Scheduler）
|
||
|
||
### POST /jobs
|
||
建立新 job
|
||
|
||
Request：
|
||
```
|
||
{
|
||
"model_key": "...",
|
||
"quant_key": "..."
|
||
}
|
||
```
|
||
|
||
Response：
|
||
```
|
||
{
|
||
"job_id": "...",
|
||
"status": "ONNX"
|
||
}
|
||
```
|
||
|
||
### GET /jobs/{job_id}
|
||
查詢狀態
|
||
|
||
Response：
|
||
```
|
||
{
|
||
"job_id": "...",
|
||
"status": "BIE",
|
||
"output": {
|
||
"bie_key": null,
|
||
"nef_key": null
|
||
}
|
||
}
|
||
```
|
||
|
||
Job 不存在：
|
||
```
|
||
404 JOB_NOT_FOUND
|
||
```
|
||
|
||
### GET /jobs/{job_id}/events
|
||
SSE 事件串流（主動推送狀態更新）
|
||
|
||
建議：
|
||
- 若 SSE 斷線，改用 GET /jobs/{job_id} 每 3-5 秒輪詢
|
||
|
||
---
|
||
|
||
## 7. Worker 行為規範
|
||
|
||
- 從對應 queue pull job_id
|
||
- 從 MinIO 下載 input
|
||
- 執行 Toolchain flow
|
||
- 上傳 output
|
||
- push done event：
|
||
```
|
||
{
|
||
"job_id": "...",
|
||
"step": "onnx|bie|nef",
|
||
"result": "ok|fail",
|
||
"reason": "optional"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 併發與限流
|
||
|
||
- BIE Worker 數量 = 最大同時 BIE 任務數
|
||
- 每個 BIE Worker 一次只跑一個 job
|
||
- 不在 Scheduler 做複雜限流邏輯
|
||
|
||
---
|
||
|
||
## 9. 最小部署建議
|
||
|
||
- web-ui x1
|
||
- scheduler x1
|
||
- redis x1（不開 persistence）
|
||
- minio x1
|
||
- onnx-worker xN
|
||
- bie-worker xM
|
||
- nef-worker xK
|
||
|
||
---
|
||
|
||
## 10. MVP 驗證項目
|
||
|
||
- 單一 job 成功完成
|
||
- 多 job 排隊，BIE 不超量
|
||
- Worker 失敗 → job FAILED
|
||
- Redis 重啟 → job 消失，UI 提示重送
|