feat: add batch inference testing script and update documentation

README.md

@@ -10,5 +10,33 @@ license: mit
 
 # TrafficFlow API Backend
 
-This is the FastAPI backend and ZIP inference model for the TrafficFlow application.
-It exposes endpoints for getting HCMC camera data, predicting vehicle counts, and proxying camera images.
+Đây là dịch vụ Backend FastAPI và mô hình AI Zero-shot Image Prior (ZIP) cho dự án TrafficFlow.
+Hệ thống cung cấp các API để truy xuất camera giao thông TP.HCM, dự đoán lưu lượng xe cộ và proxy hình ảnh camera.
+
+---
+
+## 🚀 Hướng dẫn Đánh giá Mô hình (Model Evaluation)
+
+Dự án cung cấp sẵn kịch bản kiểm thử tự động `test_batch_inference.py` để sinh viên/nhóm nghiên cứu có thể chạy hàng loạt ảnh và lấy kết quả thống kê.
+
+### 1. Cách chạy kịch bản kiểm thử (Script)
+
+1. Cài đặt thư viện: `pip install httpx`
+2. Tạo thư mục `test_images/` nằm cùng cấp với file script và chép các ảnh camera giao thông cần kiểm thử vào (hỗ trợ `.jpg`, `.png`).
+3. Chạy lệnh: `python test_batch_inference.py`
+4. Code sẽ tự động gửi ảnh lên Hugging Face Endpoint và xuất ra file báo cáo `evaluation_results.csv`.
+
+_(Lưu ý: Mặc định script sẽ tạm dừng 1 giây giữa các ảnh để tránh làm quá tải (spam) Endpoint)._
+
+### 2. Giải thích các Thông số Đầu ra (Output Parameters)
+
+Kết quả trong file `.csv` chứa các tham số quan trọng sau:
+
+- **`total_count`**: Tổng số phương tiện đếm được trong ảnh.
+- **`car_count` / `motorbike_count`**: Số lượng dự đoán bóc tách riêng từng loại xe (Dựa trên tỷ lệ ước tính của hệ thống).
+- **`density_level`**: Phân loại mức độ kẹt xe AI đánh giá:
+  - `low` (Thông thoáng): Mật độ xe thưa thớt, đường trống.
+  - `moderate` (Đông vừa): Xe bắt đầu đông nhưng vẫn di chuyển ổn định.
+  - `heavy` (Kẹt xe): Lượng xe rất đông, có dấu hiệu ùn ứ.
+  - `severe` (Kẹt cứng): Lòng đường đặc kín xe, không thể di chuyển.
+- **`latency_seconds`**: Thời gian phản hồi (tính bằng giây). Bao gồm thời gian mạng truyền tải (Network latency) + Thời gian mô hình AI phân tích (Inference time).

test_batch_inference.py

@@ -0,0 +1,138 @@
+import os
+import sys
+import glob
+import time
+import csv
+from pathlib import Path
+import httpx
+import asyncio
+
+# Cấu hình
+API_URL = "https://htrnguyen-trafficflow-api.hf.space/api/predict"
+INPUT_FOLDER = "./test_images"
+OUTPUT_CSV = "evaluation_results.csv"
+SLEEP_SECONDS = 1.5
+
+
+async def predict_image(client: httpx.AsyncClient, image_path: str):
+    filename = os.path.basename(image_path)
+    try:
+        with open(image_path, "rb") as f:
+            files = {"file": (filename, f, "image/jpeg")}
+
+            start_time = time.time()
+            response = await client.post(API_URL, files=files, timeout=60.0)
+            latency = time.time() - start_time
+
+            if response.status_code == 200:
+                data = response.json()
+                pred = data.get("prediction", {})
+                return {
+                    "filename": filename,
+                    "status": "success",
+                    "total_count": pred.get("total_count", 0),
+                    "car_count": pred.get("car_count", 0),
+                    "motorbike_count": pred.get("motorbike_count", 0),
+                    "person_count": pred.get("person_count", 0),
+                    "density_level": pred.get("density_level", "unknown"),
+                    "latency_seconds": round(latency, 2),
+                    "error": "",
+                }
+            else:
+                return {
+                    "filename": filename,
+                    "status": "failed",
+                    "total_count": 0,
+                    "car_count": 0,
+                    "motorbike_count": 0,
+                    "person_count": 0,
+                    "density_level": "error",
+                    "latency_seconds": round(latency, 2),
+                    "error": f"HTTP {response.status_code}: {response.text}",
+                }
+    except Exception as e:
+        return {
+            "filename": filename,
+            "status": "error",
+            "total_count": 0,
+            "car_count": 0,
+            "motorbike_count": 0,
+            "person_count": 0,
+            "density_level": "error",
+            "latency_seconds": 0,
+            "error": str(e),
+        }
+
+
+async def main():
+    if not os.path.exists(INPUT_FOLDER):
+        print(f"[ERROR] Không tìm thấy thư mục: {INPUT_FOLDER}")
+        print("[INFO] Vui lòng tạo thư mục này và chép ảnh (jpg, png) vào để bắt đầu.")
+        os.makedirs(INPUT_FOLDER, exist_ok=True)
+        return
+
+    image_extensions = ["*.jpg", "*.jpeg", "*.png"]
+    image_paths = []
+    for ext in image_extensions:
+        image_paths.extend(glob.glob(os.path.join(INPUT_FOLDER, ext)))
+        image_paths.extend(glob.glob(os.path.join(INPUT_FOLDER, ext.upper())))
+
+    if not image_paths:
+        print(f"[WARNING] Không có ảnh nào trong thư mục {INPUT_FOLDER}.")
+        return
+
+    print(f"[INFO] Bắt đầu đánh giá {len(image_paths)} ảnh qua API: {API_URL}")
+    results = []
+
+    async with httpx.AsyncClient() as client:
+        for i, path in enumerate(image_paths, 1):
+            print(
+                f"[{i}/{len(image_paths)}] Đang xử lý: {os.path.basename(path)} ... ",
+                end="",
+                flush=True,
+            )
+            res = await predict_image(client, path)
+            results.append(res)
+
+            if res["status"] == "success":
+                print(
+                    f"[SUCCESS] {res['total_count']} phương tiện ({res['latency_seconds']}s)"
+                )
+            else:
+                print(f"[ERROR] {res['error']}")
+
+            if i < len(image_paths):
+                print(f"[INFO] Tạm dừng {SLEEP_SECONDS}s trước khi gửi tiếp...")
+                await asyncio.sleep(SLEEP_SECONDS)
+
+    fieldnames = [
+        "filename",
+        "status",
+        "total_count",
+        "car_count",
+        "motorbike_count",
+        "person_count",
+        "density_level",
+        "latency_seconds",
+        "error",
+    ]
+
+    with open(OUTPUT_CSV, mode="w", newline="", encoding="utf-8-sig") as f:
+        writer = csv.DictWriter(f, fieldnames=fieldnames)
+        writer.writeheader()
+        writer.writerows(results)
+
+    print(f"\n[INFO] Hoàn tất quá trình đánh giá. Báo cáo lưu tại: {OUTPUT_CSV}")
+
+    successful_runs = [r for r in results if r["status"] == "success"]
+    if successful_runs:
+        avg_latency = sum(r["latency_seconds"] for r in successful_runs) / len(
+            successful_runs
+        )
+        print(f"[REPORT] Thống kê hiệu năng:")
+        print(f"   - Số lượng thành công: {len(successful_runs)}/{len(results)}")
+        print(f"   - Thời gian phản hồi trung bình: {avg_latency:.2f} giây/ảnh")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())