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:
jim800121chen 2026-04-03 00:09:14 +08:00
parent efa67d59a4
commit 75e3a9b2cc

347
docs/worker-dependencies.md Normal file
View 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 | 量化流程 V1520/720/530/630 |
| `sys_flow_v2` | `/workspace/` (Python path) | BIE | 量化流程 V2730 |
| `extract_bie_info` | `/workspace/` (Python path) | BIE (間接) | BIE 檔案 I/O 資訊提取 |
| `kneron_inference` | `/workspace/E2E_Simulator/python_flow/` | E2E 模擬 | 推理模擬入口 |
### 外部 BinaryELF 執行檔 / .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 |