跳到主要內容

CV Day 44 部署：ONNX、FastAPI 與 Streamlit

CV Day 44 部署：ONNX、FastAPI 與 Streamlit

執行需求：CPU 可跑。本篇是專案五篇的倒數第二篇，要把你從 Day 41–43 練出來的兩個 PyTorch 模型（EfficientNet-B0 分類器與 DeepLabV3+ 分割器）部署成一個完整可用的瑕疵檢測服務。我們會做四件事：把兩個 .pt 權重匯出成 ONNX（opset 17）、用 onnxruntime 1.19 驗證 ONNX 推論、用 FastAPI 0.115 寫 HTTP 端點（POST 上傳圖片、回傳 good/defect + 信心分數 + 瑕疵 mask 的 base64 PNG）、用 Streamlit 1.39 寫展示頁（拖拉上傳 → 看分類結果 + 視覺化 mask）。整個流程在本地 CPU（無 GPU）上跑得動：ONNX 匯出約 60 秒、ONNX 推論單張約 80 ms、Streamlit 啟動約 5 秒；服務啟動後 throughput 約 4–8 FPS，符合 Day 41 的部署目標。

引言

Day 14 我們做過 YOLO11 的 ONNX 匯出，Day 22 用過 SAM 做標註助手，但「兩條管線 + FastAPI + Streamlit」這套完整部署流程是專案篇才走到。我們今天要解決的不是「怎麼匯出 ONNX」（Day 14 已示範），而是「怎麼把兩個獨立模型組合起來、回傳結構化 JSON、回應前端的需求」。實務上工業界的瑕疵檢測 API 通常回傳「是/否、有多少瑕疵、瑕疵在哪裡、長什麼樣」四個資訊，本篇都會提供。

本篇的程式分四段：第 1 段把 PyTorch .pt 匯出成 ONNX（opset 17）、第 2 段用 onnxruntime 寫推論類別、第 3 段用 FastAPI 0.115 寫 HTTP 端點、第 4 段用 Streamlit 1.39 寫展示頁。與前系列 Day 14（YOLO 部署）相比，本篇的差異有三：第一，兩個模型同時匯出與部署，要設計一個「共用 preprocess、共用 postprocess」的服務層；第二，回傳 JSON 同時包含分類與分割；第三，Streamlit 端能即時畫出 mask overlay。讀完這篇你會了解：ONNX opset 17 的特性、EfficientNet-B0 與 DeepLabV3+ 在 ONNX 的算子對應、Pydantic 與 FastAPI 的請求/回應設計、Streamlit 的檔案上傳與影像顯示元件。

貫穿專案的共用設定：MVTec AD bottle 類別、影像 256×256、timm EfficientNet-B0、smp DeepLabV3Plus + ResNet34、ONNX opset 17、threshold 0.30（沿用 Day 43 的信心門檻掃描最佳值）、SEED=42。FastAPI 0.115 用 lifespan 而不是 deprecated 的 on_event，與 2024 年的官方寫法一致。

ONNX 匯出的設計考量

為什麼選擇 ONNX 而不是繼續用 PyTorch？三個理由。第一，跨平台相容性：ONNX 模型可以被 ONNX Runtime（CPU/GPU）、TensorRT（NVIDIA GPU）、OpenVINO（Intel CPU）、CoreML（iOS）、TFLite（Android）讀取，工業界部署選 ONNX 代表「換硬體不用重新寫模型」。第二，無 Python 依賴：PyTorch 模型在推論時需要完整的 torch 環境（數百 MB），ONNX 模型只需要 onnxruntime（CPU 版約 30 MB），對邊緣裝置或 Docker 容器友善。第三，opset 17 是 2024 年的穩定版本，支援 EfficientNet 的 Swish、SE 模組、與 smp 的 ASPP 所有算子。

opset 17 與 opset 12（Day 14 示範的）的差別：opset 17 多了 EfficientNet 的 HardSwish 與 smp 的某些 3D Resize 算子的優化路徑；對 smp DeepLabV3+ 影響不大，但對 timm 的部分模型有實質加速。我們選 opset 17 主要考量是「未來換模型時不必再重新選 opset」。

另一個設計選擇是 dynamic_axes。Day 14 用的是 dynamic=False（固定 batch=1），本篇改成 dynamic_axes={"input": {0: "batch"}, "output": {0: "batch"}}，讓模型支援動態 batch。這對 FastAPI 服務特別有用：多個 request 同時進來時，可以用批次推論（batch=4 或 8）提升 throughput；但本篇為了簡化每次 request 仍走 batch=1，dynamic_axes 是給未來批次優化預留。

底下這段小程式用 onnx 套件對匯出的模型做基本驗證：檢查 opset 版本與是否有 IR 警告。

# ONNX 模型品質檢查：opset 17、IR 版本、無未支援算子
import onnx

for path in ["cls_efficientnet_b0.onnx", "seg_deeplabv3plus.onnx"]:
    model = onnx.load(path)
    opset = model.opset_import[0].version
    ir_version = model.ir_version
    n_nodes = len(model.graph.node)
    print(f"{path}: opset={opset}, ir_version={ir_version}, nodes={n_nodes}")

# 用 onnx.checker 做嚴格驗證（會檢查 IR 規範）
for path in ["cls_efficientnet_b0.onnx", "seg_deeplabv3plus.onnx"]:
    try:
        onnx.checker.check_model(onnx.load(path))
        print(f"  {path}: PASS")
    except onnx.checker.ValidationError as e:
        print(f"  {path}: FAIL — {e}")
# 輸出範例（固定條件下每次都一致）：
# cls_efficientnet_b0.onnx: opset=17, ir_version=10, nodes=205
# seg_deeplabv3plus.onnx: opset=17, ir_version=10, nodes=412
#   cls_efficientnet_b0.onnx: PASS
#   seg_deeplabv3plus.onnx: PASS

onnx.checker.check_model() 會檢查 IR 規範（節點屬性、算子版本、輸入輸出 shape 等是否符合 ONNX 標準）。如果兩個模型都 PASS，代表 opset 對應無誤，可以放心部署。如果 FAIL，通常要降 opset 或升級 onnx 套件。

匯出 ONNX 時還有一個非顯而易見的陷阱：smp 的模型在 forward 內會呼叫 encoder 的 MultiScaleFusion，這個 fusion 在 PyTorch 是 Python 控制流，ONNX 不支援 Python 條件分支。我們用的是 smp.DeepLabV3Plus，這個結構已經是純 tensor 運算，可以直接匯出；如果未來換成 smp.Linknet 等較複雜的 decoder，可能需要先把 forward 改成單一 tensor graph 才能匯出。

完整實作：ONNX、FastAPI、Streamlit

執行前需要：pip install torch==2.5.0 onnx==1.17.0 onnxruntime==1.19.2 fastapi==0.115.0 uvicorn==0.32.0 streamlit==1.39.0 python-multipart==0.0.12 albumentations==1.4.10（版本對齊 2024 年底基準）。

# 1. 把 Day 42 訓練的兩個 .pt 權重匯出成 ONNX（opset 17，動態 batch）
import torch, timm, segmentation_models_pytorch as smp

# ---- 分類模型 ----
cls_model = timm.create_model("efficientnet_b0", pretrained=False, num_classes=2)
cls_model.load_state_dict(torch.load("cls_efficientnet_b0_best.pt", map_location="cpu"))
cls_model.eval()

dummy_cls = torch.randn(1, 3, 256, 256)
torch.onnx.export(
    cls_model, dummy_cls, "cls_efficientnet_b0.onnx",
    input_names=["input"], output_names=["logits"],
    opset_version=17,
    dynamic_axes={"input": {0: "batch"}, "logits": {0: "batch"}},
    do_constant_folding=True,
)
print("分類 ONNX 已匯出")
# 輸出：分類 ONNX 已匯出

# ---- 分割模型 ----
seg_model = smp.DeepLabV3Plus(encoder_name="resnet34", encoder_weights=None,
                                in_channels=3, classes=1, activation=None)
seg_model.load_state_dict(torch.load("seg_deeplabv3plus_best.pt", map_location="cpu"))
seg_model.eval()

dummy_seg = torch.randn(1, 3, 256, 256)
torch.onnx.export(
    seg_model, dummy_seg, "seg_deeplabv3plus.onnx",
    input_names=["input"], output_names=["mask_logits"],
    opset_version=17,
    dynamic_axes={"input": {0: "batch"}, "mask_logits": {0: "batch"}},
    do_constant_folding=True,
)
print("分割 ONNX 已匯出")
# 輸出：分割 ONNX 已匯出

import os
print("\n檔案大小：")
print(f"  cls_efficientnet_b0.onnx: {os.path.getsize('cls_efficientnet_b0.onnx') / 1e6:.2f} MB")
print(f"  seg_deeplabv3plus.onnx:   {os.path.getsize('seg_deeplabv3plus.onnx') / 1e6:.2f} MB")
# 輸出範例（實際數字會略有不同）：
# 檔案大小：
#   cls_efficientnet_b0.onnx: 8.32 MB
#   seg_deeplabv3plus.onnx:   24.78 MB

這段把兩個 .pt 模型匯出成 ONNX，跑在 CPU 上約 50–60 秒（兩個模型合計）。opset_version=17 是 2024 年的標準選擇，do_constant_folding=True 會讓 ONNX 把模型中的常數摺進權重（例如 EfficientNet 的 BN 參數會被融進 conv 權重），通常能讓模型小 5–10% 且推論快 5%。我們也把 input/output name 設成有意義的字串（input、logits、mask_logits），方便後續 onnxruntime 推論時的命名查找。

# 2. 用 onnxruntime 寫一個 InferenceService 類別，封裝 preprocess/forward/postprocess
import onnxruntime as ort
import numpy as np
from PIL import Image
import io, base64, cv2
import albumentations as A
from albumentations.pytorch import ToTensorV2

# 影像前處理（與 Day 42 一致）
def preprocess(image_pil, size=256):
    img = np.array(image_pil.convert("RGB"))
    img = cv2.resize(img, (size, size))
    x = img.astype(np.float32) / 255.0
    x = (x - np.array([0.485, 0.456, 0.406])) / np.array([0.229, 0.224, 0.225])
    x = x.transpose(2, 0, 1)[None].astype(np.float32)   # (1, 3, 256, 256)
    return x

CLASS_NAMES = ["good", "defect"]
THRESHOLD = 0.30          # 沿用 Day 43 信心門檻掃描的最佳值

class DefectService:
    def __init__(self, cls_onnx_path, seg_onnx_path):
        providers = ["CPUExecutionProvider"]
        self.cls_sess = ort.InferenceSession(cls_onnx_path, providers=providers)
        self.seg_sess = ort.InferenceSession(seg_onnx_path, providers=providers)
        self.cls_in = self.cls_sess.get_inputs()[0].name
        self.seg_in = self.seg_sess.get_inputs()[0].name

    def predict(self, image_pil):
        x = preprocess(image_pil)
        cls_out = self.cls_sess.run(None, {self.cls_in: x})[0]   # (1, 2)
        seg_out = self.seg_sess.run(None, {self.seg_in: x})[0]   # (1, 1, 256, 256)

        # 分類 postprocess
        probs = _softmax(cls_out[0])
        prob_defect = float(probs[1])
        label = "defect" if prob_defect >= THRESHOLD else "good"

        # 分割 postprocess：sigmoid → binarize → mask overlay
        mask_prob = 1.0 / (1.0 + np.exp(-seg_out[0, 0]))   # sigmoid
        mask_bin = (mask_prob > 0.5).astype(np.uint8) * 255
        mask_pil = Image.fromarray(mask_bin, mode="L")

        # 把 mask 疊到原圖上（紅色半透明），方便視覺化
        overlay = np.array(image_pil.convert("RGB").resize((256, 256)))
        overlay[mask_bin > 0] = [255, 0, 0]
        overlay_pil = Image.fromarray(overlay)

        # 編碼為 base64 PNG，方便回傳 JSON
        buf = io.BytesIO()
        overlay_pil.save(buf, format="PNG")
        overlay_b64 = base64.b64encode(buf.getvalue()).decode("ascii")

        return {
            "label": label,
            "prob_defect": prob_defect,
            "prob_good": 1.0 - prob_defect,
            "mask_area_pixels": int((mask_bin > 0).sum()),
            "overlay_png_base64": overlay_b64,
        }

def _softmax(logits):
    e = np.exp(logits - logits.max())
    return e / e.sum()

# 簡單的本地測試
service = DefectService("cls_efficientnet_b0.onnx", "seg_deeplabv3plus.onnx")
test_img = Image.open("manifest_bottle_seed42.csv").read  # 避免讀到不存在的檔
print("服務已建立（執行單元測試請準備一張本地影像）")

這段把兩個 ONNX 模型包成 DefectService 類別，並寫好 preprocess（resize + ImageNet normalize）與 postprocess（softmax + sigmoid + binarize + 紅色 mask overlay）。prob_defect 是分類器給的瑕疵機率，mask_area_pixels 是分割器偵測到的瑕疵面積，overlay_png_base64 是疊好 mask 的影像給前端 Streamlit 直接顯示。注意：Day 43 掃描出的 threshold 0.30 在這裡直接套用，作為部署決策的具體成果。

# 3. FastAPI HTTP 端點：POST 上傳影像，回傳 JSON
import shutil
from pathlib import Path
from fastapi import FastAPI, UploadFile, File
from fastapi.responses import JSONResponse

app = FastAPI(title="MVTec AD Bottle Defect Service", version="1.0.0")

# 啟動時載入服務（沿用 FastAPI 0.115 的 lifespan API）
service = None
@app.on_event("startup")
def load_service():
    global service
    service = DefectService("cls_efficientnet_b0.onnx", "seg_deeplabv3plus.onnx")
    print("DefectService 已載入")

@app.get("/health")
def health():
    """健康檢查端點"""
    return {"status": "ok", "model": "efficientnet_b0 + deeplabv3plus", "threshold": THRESHOLD}

@app.post("/predict")
async def predict(file: UploadFile = File(...)):
    """POST 端點：上傳影像，回傳 defect 標籤 + 信心 + mask"""
    if service is None:
        return JSONResponse(status_code=503, content={"error": "service not ready"})
    # 讀取上傳檔，轉成 PIL Image
    contents = await file.read()
    try:
        image = Image.open(io.BytesIO(contents))
    except Exception as e:
        return JSONResponse(status_code=400, content={"error": f"無法讀取影像：{e}"})
    # 推論
    result = service.predict(image)
    result["filename"] = file.filename
    return result

# 啟動指令：uvicorn deploy_api:app --host 0.0.0.0 --port 8000 --reload
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

服務啟動後可以用 curl 驗證兩個端點，先確定 /health 回 200，再丟一張測試影像到 /predict：

# 1. 健康檢查
curl -s http://localhost:8000/health | python -m json.tool
# 輸出：
# {
#     "status": "ok",
#     "model": "efficientnet_b0 + deeplabv3plus",
#     "threshold": 0.3
# }

# 2. 推論一張 MVTec bottle 影像
curl -s -F "file=@/path/to/test/bottle/001.png" \
    http://localhost:8000/predict | python -m json.tool | head -20
# 輸出：
# {
#     "filename": "001.png",
#     "label": "defect",
#     "prob_defect": 0.8123,
#     "prob_good": 0.1877,
#     "mask_area_pixels": 612,
#     "overlay_png_base64": "iVBORw0KGgoAAAANSUhEUgAAA..."
# }

# 3. 批次壓力測試：用 ab 或 hey 看 throughput
hey -n 50 -c 4 -m POST -T "image/png" \
    -D /tmp/test.png http://localhost:8000/predict
# 預期：平均 latency 約 250 ms、QPS 約 16 req/s

第一個 curl 確認服務已啟動；第二個 curl 給一張 MVTec AD test 影像，推論結果會回 label、prob、mask 與 base64 overlay；第三個用 hey 做簡單壓力測試（單機 50 request、並行 4），預期服務能撐住 16 req/s，本機 CPU 極限約 20 req/s。實務上 16 req/s 代表 1 秒可以處理 16 張影像，比 Day 41 設定的 4 FPS 高，符合「無 GPU 部署」的常見 KPI。

如果想寫一份 Python 版壓力測試腳本，可以用 concurrent.futures + requests 自己模擬多執行緒併發，並統計延遲分佈：

# 5. Python 版壓力測試：用 ThreadPoolExecutor 模擬併發，統計 P50/P95 延遲
import time
from concurrent.futures import ThreadPoolExecutor
import requests
from pathlib import Path

def predict_once(image_path):
    start = time.time()
    with open(image_path, "rb") as f:
        r = requests.post("http://localhost:8000/predict", files={"file": f}, timeout=30)
    elapsed = time.time() - start
    return elapsed, r.status_code

# 取 10 張 test 影像做 20 次隨機併發（每張可能重複測）
test_imgs = list(Path("~/datasets/mvtec_ad/bottle/test/good").glob("*.png"))[:10]
tasks = []
for _ in range(20):
    img = str(test_imgs[len(tasks) % len(test_imgs)])
    tasks.append(img)

with ThreadPoolExecutor(max_workers=4) as ex:
    results = list(ex.map(predict_once, tasks))

latencies = sorted([r[0] for r in results])
p50 = latencies[len(latencies) // 2]
p95 = latencies[int(len(latencies) * 0.95)]
print(f"併發 4、20 個 request：")
print(f"  P50 延遲: {p50 * 1000:.1f} ms")
print(f"  P95 延遲: {p95 * 1000:.1f} ms")
print(f"  全部成功: {all(r[1] == 200 for r in results)}")
# 輸出範例（實際數字會略有不同）：
# 併發 4、20 個 request：
#   P50 延遲: 280.4 ms
#   P95 延遲: 412.6 ms
#   全部成功: True

這個腳本透過 P50 與 P95 延遲告訴你服務在併發下的「SLA 邊界」。工業界常見的 KPI 是「P95 < 500 ms」，本服務在併發 4 下 P95 約 410 ms，仍能過關。如果要再壓低 P95，可以考慮 (1) 把 base64 overlay 改用 JPEG 編碼省網路傳輸時間、(2) 增加 worker 數量（但 CPU 推論已滿載）、(3) 把 mask 推論與分類推論分開兩個 worker pool 避免頭部排隊。

這段是 FastAPI 0.115 的標準寫法。@app.on_event("startup") 在服務啟動時載入 ONNX 模型；之後的 request 都用這個已載入的 service 物件（不會每次都重新載入）。/health 是給 Kubernetes 或 Load Balancer 用的健康檢查端點，回傳當前模型名稱與 threshold；/predict 是真正的推論端點，接受 multipart/form-data 上傳的檔案。FastAPI 0.115 的 async 推論雖然 onnxruntime 是 sync、但因為 IO 是 async，整體 throughput 可以滿足 4–8 FPS 的目標（瓶頸在 CPU 推論，不在 FastAPI）。

啟動指令是 uvicorn deploy_api:app --host 0.0.0.0 --port 8000 --reload。若要在背景跑，把 --reload 拿掉。第一次啟動時 ONNX 載入約 3–5 秒，之後的 request 都是毫秒級。這個 deploy_api.py 與 DefectService 類別可以放在專案根目錄的 serve/ 子目錄內。

# 4. Streamlit 展示頁：拖拉上傳、看分類結果與 mask overlay
# 檔名：streamlit_app.py（用 streamlit run streamlit_app.py 啟動）
import streamlit as st
import requests
from PIL import Image
import io, base64

st.set_page_config(page_title="MVTec AD Bottle 瑕疵檢測", layout="wide")
st.title("MVTec AD bottle 瑕疵檢測 Demo")
st.write("上傳一張 bottle 影像，系統會用 EfficientNet-B0 分類 + DeepLabV3+ 分割給出瑕疵位置。")

uploaded = st.file_uploader("選擇一張影像", type=["png", "jpg", "jpeg"])
if uploaded is not None:
    image = Image.open(uploaded).convert("RGB")
    st.image(image, caption="原始影像", width=320)

    # 送到 FastAPI
    files = {"file": (uploaded.name, uploaded.getvalue(), uploaded.type)}
    with st.spinner("推論中..."):
        resp = requests.post("http://localhost:8000/predict", files=files, timeout=30)
    if resp.status_code != 200:
        st.error(f"推論失敗：HTTP {resp.status_code} {resp.text}")
    else:
        data = resp.json()
        col1, col2 = st.columns(2)
        with col1:
            st.markdown("### 分類結果")
            color = "red" if data["label"] == "defect" else "green"
            st.markdown(f"<h2 style='color:{color};'>{data['label'].upper()}</h2>",
                        unsafe_allow_html=True)
            st.metric("瑕疵機率", f"{data['prob_defect']:.3f}")
            st.metric("瑕疵面積 (px)", data["mask_area_pixels"])
        with col2:
            st.markdown("### 瑕疵遮罩")
            overlay_pil = Image.open(io.BytesIO(base64.b64decode(data["overlay_png_base64"])))
            st.image(overlay_pil, caption="紅色區域為瑕疵", width=320)

# 側邊欄：threshold 資訊
with st.sidebar:
    st.markdown("### 部署資訊")
    st.write("- 模型：EfficientNet-B0 + DeepLabV3+ ResNet34")
    st.write("- 部署框架：FastAPI 0.115")
    st.write("- 推論引擎：onnxruntime 1.19（CPU）")
    st.write("- Threshold：0.30（沿用 Day 43 信心門檻掃描）")
    st.write("- 預期 throughput：4–8 FPS（單執行緒 CPU）")

部署驗證與容量規劃

把這套服務跑起來需要四個指令：pip install ...（前面已給）、uvicorn deploy_api:app --host 0.0.0.0 --port 8000（背景跑 API）、streamlit run streamlit_app.py（背景跑前端）、curl -F 'file=@test.jpg' http://localhost:8000/predict（用 curl 測 API）。整個 stack 都是 CPU 跑得動，總記憶體占用約 350 MB（onnxruntime 50 MB、FastAPI 30 MB、Streamlit 80 MB、兩個 ONNX 模型合計 33 MB、Albumentations 與 torchvision 100 MB、其他 60 MB）。

這個「兩個 process 一台機」的部署樣貌適合 demo、單機展示、小型工廠試點；若要走正式 production，建議改用 Docker Compose 把它們包成兩個容器：一個 defect-api（FastAPI）服務 + 一個 defect-ui（Streamlit）服務，並透過 Nginx 或 Caddy 反向代理做 TLS 與負載平衡。容器化的額外好處是「換機部署只需 docker compose pull + up」，版本會鎖在 2024 年的 12 月基準，重現性高。Day 45 系列總結會再回頭看這套部署的可擴展性與延伸學習方向。

容量規劃：單執行緒 throughput 約 4 FPS（每張 250 ms：120 ms 推論 + 130 ms preprocess/postprocess）。如果要拉到 8 FPS，可以用兩條策略：用 asyncio.gather 同時處理多個 request、或者把 ONNX 改用 OpenVINO 推論（Intel CPU 上加速約 2 倍）。我們這份服務採用前者，後者留給延伸學習。

另一個部署細節是 mask overlay 的 base64 PNG。mask_area_pixels 是純量數字方便統計；overlay_png_base64 是影像方便前端顯示；prob_defect 是分類器給的瑕疵機率，方便日誌記錄。三個欄位合在一起構成完整的「瑕疵檢測 API response」，工業界常見的模式是把這個 response 存到 MongoDB 或 PostgreSQL 做為品質紀錄。日後要回頭查某個時間點的瑕疵分布、或重新訓練模型時，這份日誌就是珍貴的標註來源。

常見錯誤與踩雷

錯誤一：FastAPI 啟動時 onnxruntime 找不到 providers。如果你只裝了 onnxruntime==1.19.2（CPU 版本），它不支援 CUDA provider；如果你裝了 onnxruntime-gpu 但機器沒有 GPU，會在初始化時報錯。對應排查方向：用 providers=["CPUExecutionProvider"] 明確指定，避免在沒有 GPU 的環境選錯。對應 debug：在本機用 ort.get_available_providers() 看有哪些。

錯誤二：ONNX 匯出後推論結果與 PyTorch 不一致。opset 對應錯誤會讓某些算子在 ONNX 用不同的 kernel 實作，造成 ±0.01 的 logits 差異。對應排查方向：匯出後先用 ort.run(...) 跑同一張影像、對比 PyTorch 模型的輸出；若差異 < 1e-3 通常是浮點精度造成的、可接受；若差異 > 1e-2 要檢查 opset 是否太低。

錯誤三：FastAPI 的 @app.on_event 在新版被 deprecated。FastAPI 0.115 推薦用 lifespan handler 而非 on_event；本篇為了簡化仍寫 on_event，但若部署到新版 FastAPI 0.116+ 會出現 warning。對應排查方向：改寫 async def lifespan(app): ... 並在 FastAPI 建構時傳入。

錯誤四：Streamlit 上傳的 file.filename 是原始路徑。Windows 環境下 file.filename 可能包含路徑分隔符（例如 C:\\Users\\...\\test.jpg），這會讓 FastAPI 寫檔或日誌出錯。對應排查方向：取 PurePosixPath(file.filename).name 只取檔名。

錯誤五：mask overlay 的 base64 PNG 比原圖大太多。我們用 PNG 編碼（無損），一張 256×256 的 mask overlay 約 5–10 KB。若要縮小可以改成 JPEG（quality=85）約 2 KB；本篇用 PNG 是因為瑕疵邊界要清楚，後者壓縮會喪失精度。

效能與實務提醒

在 Colab T4 與本地 CPU 兩種環境下，這套服務的表現差異：Colab T4 的 ONNX 推論速度是 CPU 的 4–6 倍（單張從 250 ms 降到 50 ms）；但 Colab 不適合做長期部署，session 12 小時就斷，且無法被外部服務串接。本地 CPU 雖然慢但穩定性高、Latency 一致，且部署成本接近零（不需 GPU 機房租用）。工業界常見的模式是「訓練在 Colab、部署到本地 CPU server」。

另一個部署時的提醒：不要把 Day 42 訓練用的全 232 張 train 影像都放進 ONNX 推理服務。ONNX 模型是純前向運算，不會「學到」新東西；如果你在生產線上看到新瑕疵類型（例如 contamination 出現新色澤），應該把新影像累積到一個「再訓練」資料集，每週批次 retrain 一次（或用 Day 39 的合成方式）。這個「推論服務 + 批次再訓練」的閉環，是工業界最常用、也是最有效的持續改善模式。

最後，整個部署要從三個面向看：(1) 正確性，threshold 0.30 + 分類與分割一致決定「這個產品是不是 defect」；(2) 速度，CPU 4 FPS 決定「產線節拍能不能支援」；(3) 可觀察性，每個 request 的 latency、mask 面積、瑕疵機率都要寫到日誌，方便日後回頭查特定產品是否被誤判。三個面向都做到，這個服務才能算「可上線」。實務上工業界還會再加第四個面向：可回滾性，亦即新模型上線後若發現指標掉得比前一版還差，要能在 5 分鐘內 rollback 回舊模型；這個機制通常透過模型版本管理（MVTec AD baseline、custom v0、custom v1）與 blue-green 部署來實現。

小結

今天把 Day 41–43 的所有成果濃縮成一個可部署的瑕疵檢測服務：兩個 PyTorch 模型匯出成 ONNX（opset 17）、onnxruntime 1.19 包成 DefectService、FastAPI 0.115 提供 /health 與 /predict 兩個端點、Streamlit 1.39 寫出能即時上傳與視覺化的展示頁。我們用 Day 43 的信心門檻掃描結果 threshold 0.30 作為部署決策，讓分類器在 recall 與 precision 之間取得平衡。整個 stack 都是 CPU 可跑，總記憶體約 350 MB、throughput 4 FPS（單執行緒）。明天 Day 45 是系列最後一篇，會回顧 Day 1–44 的學習路徑，整理「貫穿五個任務的工業瑕疵檢測專案」成果與延伸學習方向。

結語

今天的重點是「把四篇的成果，變成一個能跑的服務」。我們從 PyTorch 模型的權重出發，做了 ONNX 匯出、推論封裝、API 與前端三個層次的部署，並把 Day 43 評估得到的 threshold 0.30 嵌入服務內。這是工業界最常見的部署樣貌：兩個 ONNX 模型 + 一個 FastAPI + 一個前端，總程式碼約 200 行，卻能支撐一條產線的初篩。整個 stack 的選擇都偏向「簡單、可讀、可重現」：ONNX 取代 PyTorch 是為了移除 Python 依賴、FastAPI 取代 Flask 是因為它原生支援 async 與 OpenAPI 文件、Streamlit 取代 React/Vue 是因為它能用最少程式碼展示成果。

部署不是結束，是「上線後的觀察」的開始。一個服務上線後第一週通常會發現幾個盲點：train 沒看過的新瑕疵類型、硬碟 IO 變慢、某些產線的影像解析度不同等等；這些都需要更精細的 log、retrain 機制、與 Day 45 即將介紹的延伸學習。明天 Day 45 是整個系列的最後一篇，會把 Day 1 到 Day 44 的學習路徑畫成一張地圖，回顧五個任務的整合方法、給出延伸學習的方向，並替這個系列收一個安靜的尾。

延伸資源

  • ONNX 官方網站（2024）：https://onnx.ai/，opset 規格、轉換工具、與社群模型的標準來源。
  • ONNX Runtime 官方文件（1.19，2024）：https://onnxruntime.ai/docs/，CPU 與 GPU provider 的安裝、API 與效能調校指引。
  • FastAPI 官方教學（0.115，2024）：https://fastapi.tiangolo.com/zh-tw/tutorial/，async 路由、Pydantic 模型、依賴注入與 lifespan handler 的標準範例。
  • Streamlit 官方文件（1.39，2024）：https://docs.streamlit.io/，st.file_uploader、st.image、st.metric 等元件的 API。
  • MVTec AD 部署案例：MVTec Software 提供兩套官方 baseline（PatchCore、PaDiM），均可匯出 ONNX 部署在 CPU；本系列用的是輕量版自訓模型，但部署概念一致。
  • Pydantic 官方文件（2024）：https://docs.pydantic.dev/，FastAPI 0.115 內建整合 Pydantic v2，本篇的 JSON 回應可以進一步包成 Pydantic BaseModel 加強型別檢查。
標籤：

留言

張貼留言

這個網誌中的熱門文章

Day 2 變數與資料型別

Day 2 變數與資料型別 引言 寫程式的過程中，變數與資料型別是處理資料的基礎。變數是存放資料的容器，資料型別則決定這筆資料有哪些特性、可以進行哪些操作。學會定義變數、認識各種資料型別，是學好 Python 的關鍵一步。 這篇文章會帶你了解 Python 中變數的觀念、如何定義變數，以及常見的資料型別，包括整數、浮點數、字串、布林值，還有串列、元組、字典與集合等容器型別。我們也會介紹變數的命名規則與撰寫風格建議，以及如何用 type() 檢查資料型別。 什麼是變數？如何在 Python 中定義變數 變數是在程式執行時用來存放資料的名稱。透過定義變數，我們可以給一筆資料一個名字，並在程式的其他地方用這個名字取用該筆資料。在 Python 中，變數不需要事先宣告型別，因為 Python 是動態型別語言，變數的型別由指定給它的值決定。 定義變數的基本語法 在 Python 中定義變數非常簡單，只要用賦值符號 = 把值指定給變數即可。例如： x = 5 # 定義變數 x，並把整數 5 賦值給它 name = "Alice" # 定義變數 name，並把字串 "Alice" 賦值給它 在這裡，x 是一個變數，被賦予整數 5；name 是另一個變數，被賦予字串 "Alice"。 變數的更新與覆寫 變數的值可以修改，也就是說，我們可以在程式的不同地方給同一個變數新的值。例如： x = 10 # x 最初被賦予 10 x = 15 # x 的值現在被更新為 15 這樣就能依照需求，在程式執行過程中靈活調整變數的值。 Python 的動態型別系統 Python 和某些靜態型別語言不同，定義變數時不需要宣告型別。賦值時，Python 會根據值自動判斷變數的型別。例如： x = 5 # x 是整數 x = 3.14 # x 變成浮點數 x = "Hi" # x 變成字串 同一個變數在程式執行過程中可以存放不同型別的值，這是 Python 的彈性之一。 常見資料型別 在 Python 中，資料型別決定我們可以對變數進行哪些操作...
張貼留言
閱讀完整內容

Day 1 Python 簡介與環境設定

Day 1 Python 簡介與環境設定 引言 在現在的科技環境裡，程式設計已經是一項重要技能。無論你是對資料科學有興趣、想成為開發者，或是想踏入人工智慧（AI）領域，學會寫程式都能明顯提升你的競爭力。在眾多程式語言中，Python 因為語法簡單、功能強大、應用範圍廣泛，成為許多人進入程式世界的第一選擇。這篇文章會帶你認識 Python 的背景與優勢，並一步步教你在不同系統上安裝與設定 Python 開發環境，最後寫出第一支 Python 程式。 為什麼選擇 Python？ Python 是一種高階程式語言，由 Guido van Rossum 在 1991 年發布。Python 的設計哲學強調程式碼的可讀性，並用縮排來定義程式區塊，這點和許多使用大括號的語言不同。簡潔的語法讓它成為初學者的理想選擇；就算是經驗豐富的開發者，也能用它完成複雜的專案。 Python 的優勢如下： 簡單易學 ：Python 的語法清楚、結構簡潔，初學者很快就能上手。和其他語言相比，學習曲線相對平緩，不需要先弄懂一堆複雜觀念，就能開始寫程式。 應用範圍廣泛 ：從資料科學、網頁開發、人工智慧、機器學習、自動化測試到網路爬蟲，Python 都有大量開源函式庫與工具支援，而且在這些領域都扮演關鍵角色。 豐富的函式庫與框架 ：Python 的函式庫生態系非常龐大。做資料分析有 NumPy、Pandas；開發網站有 Django、Flask；做深度學習有 TensorFlow、PyTorch。各種需求幾乎都能找到對應的套件，讓開發更有效率。 跨平台支援 ：Python 支援 Windows、macOS、Linux 等作業系統，程式通常不需要太多修改就能跨平台執行，讓開發與部署更有彈性。 活躍的社群 ：Python 擁有龐大的開發者社群。學習或開發上遇到問題，幾乎都能在社群與論壇（例如 Stack Overflow）找到答案，對初學者來說是很強的後盾，也能減少卡關時的挫折感。 Python 的應用領域 Python 的流行與強大功能，讓許多領域都開始大量使用它。以下是幾個常見的應用方向： 資料科學 ：隨著大數據與人工智慧興起，資料科學大量使用 Python。NumPy、Pandas 與 Matplotlib 等工具能處理和分析龐...
張貼留言
閱讀完整內容

Python 從入門到 PyTorch 深度學習：開啟 AI 世界的大門

Python 從入門到 PyTorch 深度學習：開啟 AI 世界的大門 隨著人工智慧（AI）與深度學習（Deep Learning）快速發展，越來越多人對這些技術產生興趣。不論你是想踏入 AI 領域的初學者，還是已經有程式基礎的開發者，學好 Python 與深度學習框架（例如 PyTorch），都能為你打開更多可能。 為什麼選擇 Python？ Python 已經是資料科學與人工智慧領域的首選語言。它的語法簡潔、容易上手，而且擁有龐大的生態系與大量開源函式庫。無論是資料處理、資料視覺化，還是建立機器學習與深度學習模型，Python 都能勝任。對想進入 AI 或資料科學領域的人來說，它幾乎是必備工具。 PyTorch 是什麼？ PyTorch 是由 Meta（原 Facebook）AI 研究團隊開發的開源深度學習框架，以易用、靈活和動態計算圖著稱，是許多 AI 研究人員與開發者的首選。相較於其他框架，PyTorch 的寫法更貼近原生 Python，對初學者相對友善。無論是簡單的實驗，還是複雜的深度學習模型，PyTorch 都能提供強大的支援。 這個系列能帶給你什麼？ 這個系列會從 Python 的基礎開始，帶你一步一步學習，最後能自己用 PyTorch 建立深度學習模型。即使你完全沒有寫過程式，也能跟著文章的節奏累積技能，理解 AI 與深度學習的核心觀念。 本系列涵蓋的主題 Python 基礎：從變數、條件判斷到函式與模組。 資料處理工具：用 NumPy 與 Pandas 有效率地操作資料。 資料視覺化：用 Matplotlib 與 Seaborn 把資料畫成圖表。 深度學習的數學基礎：線性代數、微積分與機率。 PyTorch 入門：理解張量、模型建構與 GPU 加速。 基礎深度學習模型：CNN 與 RNN 的實作應用。 深度學習專案實戰：從資料前處理到模型部署的端到端流程。 誰適合這個系列？ 程式初學者 ：如果你對 AI 充滿好奇，卻還沒寫過程式，系列的第一部分會帶你快速上手 Python，並幫助你理解深度學習的基本觀念。 資料科學愛好者 ：如果你已經熟悉一些資料處理方法，進階部分會教你如何用 PyTorch 建構深度學習模型。 開發者與研究人員 ：想更深入了...
張貼留言
閱讀完整內容