Add worker dependencies documentation with binary mapping per stage
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
efa67d59a4
commit
75e3a9b2cc
347
docs/worker-dependencies.md
Normal file
347
docs/worker-dependencies.md
Normal file
@ -0,0 +1,347 @@
|
||||
# Worker 套件依賴關係圖
|
||||
|
||||
> 最後更新：2026-04-02
|
||||
|
||||
## 轉換流程總覽（含外部 Binary 標註）
|
||||
|
||||
```
|
||||
上傳模型 (.onnx / .tflite)
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ Stage 1: ONNX 優化 (onnx-worker) │
|
||||
│ │
|
||||
│ 輸入: .onnx 或 .tflite │
|
||||
│ 輸出: out.onnx │
|
||||
│ │
|
||||
│ ┌─ Python 套件 ───────────────────────────────────────────────┐ │
|
||||
│ │ onnx — 模型載入/儲存 │ │
|
||||
│ │ tensorflow — TFLite 解析（僅 .tflite 輸入時） │ │
|
||||
│ │ tf2onnx — TFLite→ONNX 轉換（僅 .tflite 輸入時） │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ ┌─ [BINARY] 系統庫 ──────────────────────────────────────────┐ │
|
||||
│ │ kneronnxopt — ONNX 圖形最佳化引擎 │ │
|
||||
│ │ 位置: /workspace/libs/kneronnxopt/ │ │
|
||||
│ │ 呼叫: ktc.onnx_optimizer → Python import │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ ┌─ [BINARY] 可選：IP 評估 ───────────────────────────────────┐ │
|
||||
│ │ (使用 ktc.ModelConfig.evaluate()， │ │
|
||||
│ │ 底層透過 sys_flow 呼叫量化分析庫) │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└──────────┬───────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ Stage 2: BIE 量化 (bie-worker) │
|
||||
│ │
|
||||
│ 輸入: out.onnx + 參考圖片 │
|
||||
│ 輸出: out.bie │
|
||||
│ │
|
||||
│ ┌─ Python 套件 ───────────────────────────────────────────────┐ │
|
||||
│ │ onnx — 載入 ONNX、讀取 input shape │ │
|
||||
│ │ Pillow — 參考圖片讀取 │ │
|
||||
│ │ numpy — 圖片數值運算 │ │
|
||||
│ │ opencv-python — 圖片預處理（resize 等） │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ ┌─ [BINARY] 系統庫 ──────────────────────────────────────────┐ │
|
||||
│ │ kneronnxopt — ONNX 再次最佳化 │ │
|
||||
│ │ 位置: /workspace/libs/kneronnxopt/ │ │
|
||||
│ │ 呼叫: ktc.onnx_optimizer → Python import │ │
|
||||
│ │ │ │
|
||||
│ │ sys_flow — 量化流程 V1（平台 520/720/530/630） │ │
|
||||
│ │ 位置: /workspace/ (Python path) │ │
|
||||
│ │ 呼叫: ktc/toolchain.py → gen_fx_model_v1()│ │
|
||||
│ │ │ │
|
||||
│ │ sys_flow_v2 — 量化流程 V2（平台 730） │ │
|
||||
│ │ 位置: /workspace/ (Python path) │ │
|
||||
│ │ 呼叫: ktc/toolchain.py → gen_fx_model_v2()│ │
|
||||
│ │ + gen_opt_model_v2() │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└──────────┬───────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ Stage 3: NEF 編譯 (nef-worker) │
|
||||
│ │
|
||||
│ 輸入: out.bie │
|
||||
│ 輸出: out.nef │
|
||||
│ │
|
||||
│ ┌─ [BINARY] ELF 執行檔（subprocess.run 呼叫）────────────────┐ │
|
||||
│ │ │ │
|
||||
│ │ gen_config.py — 產生編譯設定檔 │ │
|
||||
│ │ 位置: libs/compiler/gen_config.py │ │
|
||||
│ │ libs_V2/compiler/gen_config.py (730) │ │
|
||||
│ │ 呼叫: subprocess.run(["python", gen_config.py, ...]) │ │
|
||||
│ │ 時機: 編譯前的設定準備 │ │
|
||||
│ │ │ │
|
||||
│ │ batch_compile — 模型批次編譯器（主編譯器） │ │
|
||||
│ │ 位置: libs/compiler/batch_compile │ │
|
||||
│ │ libs_V2/compiler/batch_compile (730) │ │
|
||||
│ │ 呼叫: subprocess.run([batch_compile, ...]) │ │
|
||||
│ │ 時機: BIE → 中間編譯產物 │ │
|
||||
│ │ 連結: libpiano.so, libmozart.so, libschubert.so, │ │
|
||||
│ │ libbeethoven.so, libbach.so, libwagner.so │ │
|
||||
│ │ │ │
|
||||
│ │ kneron_nef_utils — NEF 封裝工具 │ │
|
||||
│ │ 位置: libs/compiler/kneron_nef_utils │ │
|
||||
│ │ libs_V2/compiler/kneron_nef_utils (730) │ │
|
||||
│ │ 呼叫: subprocess.run([kneron_nef_utils, ...]) │ │
|
||||
│ │ 時機: 中間產物 → 最終 NEF 封裝 │ │
|
||||
│ │ 連結: libencoder.so, libkne.so │ │
|
||||
│ │ │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ Binary 路徑選擇邏輯： │
|
||||
│ if USE_PREBUILD 環境變數存在 → 使用預構建路徑 │
|
||||
│ elif platform == "730" → libs_V2/compiler/ │
|
||||
│ else → libs/compiler/ │
|
||||
└──────────────────────────────────────────────────────────────────┘
|
||||
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ (未完成) E2E 模擬 │
|
||||
│ │
|
||||
│ ┌─ [BINARY] 動態庫（ctypes.CDLL 載入）────────────────────────┐ │
|
||||
│ │ │ │
|
||||
│ │ libdynasty.so — Dynasty 推理引擎 │ │
|
||||
│ │ 位置: libs/dynasty/E2ESimulator/libdynasty.so │ │
|
||||
│ │ 呼叫: ctypes.CDLL() → 浮點/定點推理 │ │
|
||||
│ │ │ │
|
||||
│ │ libload*.so — 各平台預處理庫 │ │
|
||||
│ │ 位置: E2E_Simulator/c_interface/libs/ │ │
|
||||
│ │ 呼叫: ctypes.CDLL() │ │
|
||||
│ │ │ │
|
||||
│ │ libprocessing*.so — 各平台後處理庫 │ │
|
||||
│ │ 位置: E2E_Simulator/c_interface/libs/ │ │
|
||||
│ │ 呼叫: ctypes.CDLL() │ │
|
||||
│ │ │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ ┌─ [BINARY] CSIM 仿真器（subprocess.run 呼叫）───────────────┐ │
|
||||
│ │ │ │
|
||||
│ │ npu_csim_520 — KDP520 硬體仿真 │ │
|
||||
│ │ npu_csim_730 — KDP730 硬體仿真 │ │
|
||||
│ │ 位置: E2E_Simulator/bin/current/ │ │
|
||||
│ │ 呼叫: subprocess.run([npu_csim_*, ...]) │ │
|
||||
│ │ │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└──────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 依賴分層架構
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ Worker 入口層 │
|
||||
│ services/workers/{onnx,bie,nef}/worker.py │
|
||||
│ 用途：啟動 consumer、選擇 stub/real 模式 │
|
||||
│ 依賴：consumer.py, stubs.py 或 core.py │
|
||||
├─────────────────────────────────────────────────────────────────────┤
|
||||
│ Worker 消費者層 │
|
||||
│ services/workers/consumer.py │
|
||||
│ 用途：Redis Stream 佇列消費、檔案上下載、流程控制 │
|
||||
│ 依賴：redis, boto3 (MinIO), 標準庫 │
|
||||
├─────────────────────────────────────────────────────────────────────┤
|
||||
│ Worker 核心處理層 │
|
||||
│ services/workers/{onnx,bie,nef}/core.py │
|
||||
│ 用途：呼叫 Backend Interface 執行模型轉換 │
|
||||
│ 依賴：onnx, ktc, backends │
|
||||
├─────────────────────────────────────────────────────────────────────┤
|
||||
│ Backend 介面層 (Protocol) │
|
||||
│ services/backends/{compiler,quantization,evaluator,simulator}.py │
|
||||
│ 用途：定義抽象介面，封裝 KTC 呼叫 │
|
||||
│ 依賴：ktc (lazy import) │
|
||||
├─────────────────────────────────────────────────────────────────────┤
|
||||
│ KTC 封裝層 │
|
||||
│ ktc/toolchain.py, ktc/onnx_optimizer.py, ktc/inferencer.py │
|
||||
│ 用途：封裝 Kneron Toolchain 的 Python API 和 binary 呼叫 │
|
||||
│ 依賴：onnx, numpy, kneronnxopt, sys_flow, subprocess (binary) │
|
||||
├─────────────────────────────────────────────────────────────────────┤
|
||||
│ 外部 Binary / 系統庫層 │
|
||||
│ libs/, libs_V2/, E2E_Simulator/ │
|
||||
│ 用途：Kneron 編譯器、模擬器、最佳化器的實際二進制執行檔 │
|
||||
│ 呼叫方式：subprocess.run(), ctypes.CDLL() │
|
||||
└─────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 各 Stage 套件依賴明細
|
||||
|
||||
### Stage 1: ONNX 優化（onnx-worker）
|
||||
|
||||
| 套件 | 類型 | 用途 | 呼叫位置 |
|
||||
|------|------|------|---------|
|
||||
| `redis` | 第三方 (pip) | Redis Stream 佇列消費、訊息 ACK | `consumer.py` |
|
||||
| `boto3` | 第三方 (pip) | MinIO 檔案上傳/下載 | `consumer.py` → `s3_storage.py` |
|
||||
| `onnx` | 第三方 (pip) | 載入/儲存 ONNX 模型 | `onnx/core.py` — `onnx.load()`, `onnx.save()` |
|
||||
| `ktc.onnx_optimizer` | 本地模組 | TFLite→ONNX 轉換、ONNX 模型最佳化 | `onnx/core.py` — `tflite2onnx_flow()`, `onnx2onnx_flow()` |
|
||||
| `kneronnxopt` | 系統庫 | ONNX 圖形最佳化（被 ktc.onnx_optimizer 呼叫） | `ktc/onnx_optimizer_1_13.py` |
|
||||
| `ktc.ModelConfig` | 本地模組 | IP 評估（可選） | `backends/evaluator.py` → `km.evaluate()` |
|
||||
|
||||
**ONNX 版本分歧：**
|
||||
```
|
||||
ktc/onnx_optimizer.py
|
||||
├─ onnx 1.7.0 → onnx_optimizer_1_7.py (舊版相容)
|
||||
└─ onnx 1.13+ → onnx_optimizer_1_13.py (目前使用)
|
||||
└─ import kneronnxopt
|
||||
```
|
||||
|
||||
### Stage 2: BIE 量化（bie-worker）
|
||||
|
||||
| 套件 | 類型 | 用途 | 呼叫位置 |
|
||||
|------|------|------|---------|
|
||||
| `redis` | 第三方 (pip) | Redis Stream 佇列消費 | `consumer.py` |
|
||||
| `boto3` | 第三方 (pip) | MinIO 檔案上傳/下載 | `consumer.py` → `s3_storage.py` |
|
||||
| `onnx` | 第三方 (pip) | 載入 ONNX 模型、讀取輸入節點資訊 | `bie/core.py` — `onnx.load()`, 讀取 graph input shape |
|
||||
| `ktc.onnx_optimizer` | 本地模組 | ONNX 模型再次最佳化 | `bie/core.py` — `onnx2onnx_flow()` |
|
||||
| `kneron_preprocess` | 本地模組 | 參考圖片預處理（resize, normalize） | `bie/core.py` — `preprocess_func()` |
|
||||
| `Pillow` | 第三方 (pip) | 圖片讀取（被 kneron_preprocess 呼叫） | `kneron_preprocess.py` |
|
||||
| `numpy` | 第三方 (pip) | 圖片數值運算 | `kneron_preprocess.py` |
|
||||
| `ktc.ModelConfig` | 本地模組 | 建立模型設定 | `backends/quantization.py` |
|
||||
| `km.analysis()` | 本地模組 | 執行量化分析，產出 BIE | `backends/quantization.py` |
|
||||
| `sys_flow` | 系統庫 | 量化流程 V1（平台 520/720/530/630） | `ktc/toolchain.py` — `gen_fx_model_v1()` |
|
||||
| `sys_flow_v2` | 系統庫 | 量化流程 V2（平台 730） | `ktc/toolchain.py` — `gen_fx_model_v2()`, `gen_opt_model_v2()` |
|
||||
|
||||
### Stage 3: NEF 編譯（nef-worker）
|
||||
|
||||
| 套件 | 類型 | 用途 | 呼叫位置 |
|
||||
|------|------|------|---------|
|
||||
| `redis` | 第三方 (pip) | Redis Stream 佇列消費 | `consumer.py` |
|
||||
| `boto3` | 第三方 (pip) | MinIO 檔案上傳/下載 | `consumer.py` → `s3_storage.py` |
|
||||
| `ktc.ModelConfig` | 本地模組 | 建立模型設定 | `backends/compiler.py` |
|
||||
| `ktc.compile()` | 本地模組 | 執行 NEF 編譯 | `backends/compiler.py` |
|
||||
| `batch_compile` | 外部 Binary | 模型批次編譯（ELF 執行檔） | `ktc/toolchain.py` → `subprocess.run()` |
|
||||
| `kneron_nef_utils` | 外部 Binary | NEF 封裝工具（ELF 執行檔） | `ktc/toolchain.py` → `subprocess.run()` |
|
||||
| `gen_config.py` | 外部 Script | 編譯設定檔產生器 | `ktc/toolchain.py` → `subprocess.run(["python", ...])` |
|
||||
|
||||
**Binary 路徑解析：**
|
||||
```
|
||||
_resolve_compiler_paths(platform)
|
||||
├─ 若 USE_PREBUILD 環境變數存在 → 使用預構建路徑
|
||||
├─ 平台 730 → libs_V2/compiler/
|
||||
└─ 其他平台 → libs/compiler/
|
||||
```
|
||||
|
||||
### E2E 模擬（未完成，旗標已定義）
|
||||
|
||||
| 套件 | 類型 | 用途 | 呼叫位置 |
|
||||
|------|------|------|---------|
|
||||
| `ktc.kneron_inference` | 本地模組 | E2E 推理入口 | `backends/simulator.py` |
|
||||
| `kneron_inference` (E2E_Simulator) | 系統庫 | 推理執行 | `ktc/inferencer.py` — 硬編碼 `/workspace/E2E_Simulator/python_flow` |
|
||||
| `numpy` | 第三方 (pip) | radix 計算 | `ktc/inferencer.py` |
|
||||
| `libdynasty.so` | 外部 Binary | Dynasty 推理引擎 | E2E_Simulator → `ctypes.CDLL()` |
|
||||
| `npu_csim_*` | 外部 Binary | 各平台 CSIM 仿真器 | E2E_Simulator → `subprocess.run()` |
|
||||
|
||||
---
|
||||
|
||||
## 完整套件依賴總表
|
||||
|
||||
### 第三方套件（pip install）
|
||||
|
||||
| 套件 | 版本 | 使用階段 | 用途 |
|
||||
|------|------|---------|------|
|
||||
| `redis` | >=5.0 | 全部 | Redis Stream 佇列通訊 |
|
||||
| `boto3` | >=1.28 | 全部 | MinIO 物件儲存（S3 相容 API） |
|
||||
| `onnx` | 1.14.1 | ONNX + BIE | 模型載入/儲存/圖形解析 |
|
||||
| `numpy` | - | BIE + E2E | 數值運算、圖片處理 |
|
||||
| `Pillow` | - | BIE | 參考圖片讀取 |
|
||||
| `onnxruntime` | - | ONNX (間接) | ONNX 推理（被 kneronnxopt 使用） |
|
||||
| `tensorflow` | 2.16.2 | ONNX (間接) | TFLite 轉換 |
|
||||
| `tf2onnx` | - | ONNX (間接) | TFLite→ONNX 轉換 |
|
||||
| `opencv-python` | - | BIE (間接) | 圖片預處理 |
|
||||
| `scipy` | - | BIE (間接) | 量化分析數學運算 |
|
||||
|
||||
### 系統庫（需部署在 /workspace）
|
||||
|
||||
| 模組 | 位置 | 使用階段 | 用途 |
|
||||
|------|------|---------|------|
|
||||
| `kneronnxopt` | `/workspace/libs/kneronnxopt/` | ONNX | ONNX 圖形最佳化引擎 |
|
||||
| `sys_flow` | `/workspace/` (Python path) | BIE | 量化流程 V1（520/720/530/630） |
|
||||
| `sys_flow_v2` | `/workspace/` (Python path) | BIE | 量化流程 V2（730） |
|
||||
| `extract_bie_info` | `/workspace/` (Python path) | BIE (間接) | BIE 檔案 I/O 資訊提取 |
|
||||
| `kneron_inference` | `/workspace/E2E_Simulator/python_flow/` | E2E 模擬 | 推理模擬入口 |
|
||||
|
||||
### 外部 Binary（ELF 執行檔 / .so 動態庫）
|
||||
|
||||
| Binary | 位置 | 使用階段 | 呼叫方式 |
|
||||
|--------|------|---------|---------|
|
||||
| `batch_compile` | `libs/compiler/` 或 `libs_V2/compiler/` | NEF | `subprocess.run()` |
|
||||
| `kneron_nef_utils` | `libs/compiler/` 或 `libs_V2/compiler/` | NEF | `subprocess.run()` |
|
||||
| `gen_config.py` | `libs/compiler/` 或 `libs_V2/compiler/` | NEF | `subprocess.run(["python", ...])` |
|
||||
| `libdynasty.so` | `libs/dynasty/E2ESimulator/` | E2E 模擬 | `ctypes.CDLL()` |
|
||||
| `npu_csim_520` | `E2E_Simulator/bin/current/` | E2E 模擬 | `subprocess.run()` |
|
||||
| `npu_csim_730` | `E2E_Simulator/bin/current/` | E2E 模擬 | `subprocess.run()` |
|
||||
| `libload*.so` | `E2E_Simulator/c_interface/libs/` | E2E 模擬 | `ctypes.CDLL()` |
|
||||
| `libprocessing*.so` | `E2E_Simulator/c_interface/libs/` | E2E 模擬 | `ctypes.CDLL()` |
|
||||
| `libpiano.so` | `libs/compiler/lib/` | NEF (間接) | batch_compile 動態連結 |
|
||||
| `libmozart.so` | `libs/compiler/lib/` | NEF (間接) | batch_compile 動態連結 |
|
||||
| `libencoder.so` | `libs/compiler/lib/` | NEF (間接) | kneron_nef_utils 動態連結 |
|
||||
| `libkne.so` | `libs/compiler/lib/` | NEF (間接) | kneron_nef_utils 動態連結 |
|
||||
|
||||
---
|
||||
|
||||
## 依賴關係圖（按呼叫鏈）
|
||||
|
||||
```
|
||||
onnx-worker
|
||||
└─ consumer.py ─────────── redis, boto3
|
||||
└─ onnx/core.py
|
||||
├─ onnx ─────────────── onnx.load(), onnx.save()
|
||||
├─ ktc.onnx_optimizer
|
||||
│ ├─ onnx
|
||||
│ ├─ kneronnxopt ──── [系統庫] ONNX 圖形最佳化
|
||||
│ └─ (tflite 時) tf2onnx, tensorflow
|
||||
└─ (可選) backends/evaluator.py
|
||||
└─ ktc.ModelConfig → km.evaluate()
|
||||
|
||||
bie-worker
|
||||
└─ consumer.py ─────────── redis, boto3
|
||||
└─ bie/core.py
|
||||
├─ onnx ─────────────── onnx.load(), 讀取 input shape
|
||||
├─ ktc.onnx_optimizer ── (同上)
|
||||
├─ kneron_preprocess ─── Pillow, numpy, opencv-python
|
||||
└─ backends/quantization.py
|
||||
└─ ktc.ModelConfig → km.analysis()
|
||||
├─ sys_flow ──── [系統庫] 量化 V1
|
||||
└─ sys_flow_v2 ── [系統庫] 量化 V2
|
||||
|
||||
nef-worker
|
||||
└─ consumer.py ─────────── redis, boto3
|
||||
└─ nef/core.py
|
||||
└─ backends/compiler.py
|
||||
└─ ktc.compile()
|
||||
├─ gen_config.py ──── [subprocess] 產生編譯設定
|
||||
├─ batch_compile ──── [subprocess] 執行編譯
|
||||
│ └─ libpiano.so, libmozart.so... [動態連結]
|
||||
└─ kneron_nef_utils ── [subprocess] 封裝 NEF
|
||||
└─ libencoder.so, libkne.so [動態連結]
|
||||
|
||||
(未完成) e2e-simulation
|
||||
└─ backends/simulator.py
|
||||
└─ ktc.kneron_inference
|
||||
└─ E2E_Simulator/kneron_inference
|
||||
├─ libdynasty.so ──── [ctypes] Dynasty 推理
|
||||
├─ npu_csim_* ─────── [subprocess] CSIM 仿真
|
||||
└─ libload*.so ─────── [ctypes] 預/後處理
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 環境變數一覽
|
||||
|
||||
| 變數 | 預設值 | 用途 | 影響範圍 |
|
||||
|------|--------|------|---------|
|
||||
| `REDIS_URL` | `redis://localhost:6379` | Redis 連線 | consumer.py |
|
||||
| `WORKER_MODE` | `real` | `stub` = 開發模式, `real` = 真實處理 | worker.py |
|
||||
| `STORAGE_BACKEND` | `local` | `local` = 共享卷, `minio` = MinIO | consumer.py |
|
||||
| `MINIO_ENDPOINT_URL` | `http://192.168.0.130:9000` | MinIO 端點 | s3_storage.py |
|
||||
| `MINIO_BUCKET` | `convertet-working-space` | MinIO Bucket | s3_storage.py |
|
||||
| `MINIO_ACCESS_KEY` | `convuser` | MinIO 帳號 | s3_storage.py |
|
||||
| `MINIO_SECRET_KEY` | - | MinIO 密碼 | s3_storage.py |
|
||||
| `MINIO_LIFECYCLE_DAYS` | `7` | 檔案自動清理天數 | s3_storage.py |
|
||||
| `JOB_DATA_DIR` | `/data/jobs` | 本地工作目錄 | consumer.py |
|
||||
| `KTC_OUTPUT_DIR` | `/data1/kneron_flow` | KTC 輸出目錄 | core.py → ktc |
|
||||
| `KTC_WORKDIR` | `/workspace/.tmp` | KTC 暫存目錄 | core.py → ktc |
|
||||
| `KTC_SCRIPT_RES` | - | KTC 資源目錄 | core.py → ktc |
|
||||
| `USE_PREBUILD` | - | 預構建 binary 路徑（優先於 libs/） | ktc/toolchain.py |
|
||||
Loading…
x
Reference in New Issue
Block a user