diff --git a/docs/worker-dependencies.md b/docs/worker-dependencies.md new file mode 100644 index 0000000..4eb30d7 --- /dev/null +++ b/docs/worker-dependencies.md @@ -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 |