Vietnamese Food Detection

Reproducible, auditable tooling for a legacy 156-class YOLOv5s food detector.

Bắt đầu nhanh · Artifact · Đánh giá · Bảo mật · Tài liệu

Important

Đây là baseline phục dựng kỹ thuật, không phải hệ thống production. Taxonomy legacy, annotation, quyền dữ liệu và giấy phép của code/weights vẫn cần human review trước khi triển khai hoặc tái phân phối.

✨ Repository này cung cấp gì?

🔐 Tin cậy artifact	🧪 Tái lập được	🛡️ Vận hành có kiểm soát
Khóa SHA-256 cho checkpoint, ONNX và evidence	Pin đúng YOLOv5 commit, dependency và protocol	Process isolation, hard timeout và giới hạn tài nguyên
Loader từ chối model ngoài allowlist	Audit dataset, benchmark và kiểm tra parity	Run bất biến, JSON canonical và HTML offline
Provenance tập trung trong manifest	CPU/GPU baseline có evidence máy đọc được	Telemetry redacted và retention có quarantine

Các workflow chính gồm inference cục bộ, kiểm tra dữ liệu YOLO, benchmark baseline, export ONNX và so sánh PyTorch ↔ ONNX Runtime.

🧭 Kiến trúc

flowchart LR
    A[Ảnh cục bộ] --> B[CLI / Python API]
    B --> C{Process isolation}
    C -->|mặc định| D[Worker riêng]
    C -->|debug| E[In-process]
    D --> F[Hash-locked YOLOv5]
    E --> F
    F --> G[Prediction schema v2]
    G --> H[predictions.json]
    G --> I[report.html]
    G --> J[annotated images]
    B -. redacted .-> K[Telemetry JSONL]
    H --> L[Retention / quarantine]
    I --> L
    J --> L

Loading

Mặc định mỗi ảnh được xử lý trong worker riêng. Run chỉ được publish bằng atomic rename sau khi các artifact bắt buộc đã ghi thành công; lỗi một ảnh có thể được cô lập mà không làm mất kết quả của các ảnh còn lại.

🚀 Bắt đầu nhanh

1. Cài môi trường

git clone https://github.com/alexmerex/ObjectDetection.git
Set-Location ObjectDetection

py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[inference]"

Trên Linux/macOS, kích hoạt môi trường bằng source .venv/bin/activate. Với GPU, cài đúng wheel PyTorch 2.5.1 cho CUDA của máy theo hướng dẫn phiên bản chính thức trước khi cài project.

2. Bootstrap backend và kiểm tra sức khỏe

food-detect bootstrap
food-detect doctor
food-detect inspect best.pt

bootstrap chỉ tải source YOLOv5 tại commit 100a423b66fee81e0a2915d5da934d7872f12c8c, xác minh checksum rồi lưu trong .cache/. Không có source upstream nào được vendored vào package.

3. Chạy prediction

food-detect predict .\your-image.jpg --name demo-local --device cpu

Tên run là bất biến; dùng tên mới khi chạy lại. Đầu vào chỉ được đọc từ file hoặc thư mục cục bộ — CLI không fetch URL từ xa.

runs/predict/demo-local/
├── predictions.json       # contract canonical, schema v2
├── report.html            # report tĩnh, xem offline
└── annotated/
    └── *.annotated.jpg    # visualization, không phải ground truth

Exit	Ý nghĩa	Run được publish?
0	Hoàn tất, có thể kèm warning	Có
1	Hoàn tất một phần; đọc failures[] trong JSON	Có
2	Preflight/fatal/fail-fast	Không

Xem hợp đồng đầy đủ tại Prediction run schema v2.

📦 Artifact đã xác minh

Artifact	Vai trò	Identity	Evidence	Trạng thái
best.pt	Baseline inference	4a1f5027…a6657b0 · 15.16 MB	benchmark JSON	Có trong checkout
model.onnx	Runtime dẫn xuất	a1b6c981…286e697 · opset 17	export manifest · parity JSON	Có trong checkout
model.h5 legacy	COCO 80-class state dict bị đặt sai đuôi	3cc5313e…85920	forensic audit	Đã loại khỏi cây phát hành; không dùng

Full hash, kích thước và liên kết provenance nằm trong artifacts.manifest.json. ONNX dùng input FP32 NCHW RGB cố định 1×3×416×416; letterbox và NMS nằm ngoài graph.

📊 Kết quả baseline

Protocol: best.pt, 416 px, FP32, confidence 0.001, NMS IoU 0.6, annotation corrected-boxes.

Snapshot	Precision	Recall	mAP50	mAP50–95	Phạm vi
NhauHoai v2 · CPU	0.5879	0.1400	0.2110	0.1425	9 ảnh · 128 instance · 42/156 lớp có support
NhauHoai v2 · GTX 1650	0.5879	0.1400	0.2110	0.1425	Cùng protocol; metric khớp CPU

Warning

Test set rất nhỏ và thiếu support cho 114/156 lớp. Các số trên chỉ xác nhận baseline phục dựng; không đại diện cho độ chính xác ngoài thực tế hoặc chất lượng production.

Parity đã duyệt so sánh 9 ảnh trên CPU: mỗi backend tạo 2,700 detection ở max_det=300, không có detection không ghép được, IoU ghép nhỏ nhất 0.999993 và confidence delta lớn nhất 3.43e-6. Đây là kiểm tra tương đương kỹ thuật, không phải quality claim.

Audit dataset và chạy lại benchmark

Raw snapshot nằm cục bộ tại data/roboflow/nhauhoai-v2/ và bị loại khỏi Git. Registry không chứa credential nằm tại data/registry/nhauhoai-v2.json.

food-detect validate-dataset data/roboflow/nhauhoai-v2 `
  --output runs/data-audit/nhauhoai-v2.json

food-detect benchmark data/roboflow/nhauhoai-v2 `
  --name corrected-cpu-rebuild `
  --annotation-mode corrected-boxes `
  --device cpu

Export có 79 label file trộn bbox/polygon. Lane corrected-boxes chuẩn hóa từng dòng; lane legacy-loader chỉ tái hiện lỗi parser lịch sử.

Export ONNX và kiểm tra parity

python -m pip install -e ".[inference,export]"

food-detect export-onnx `
  --output-dir runs/export `
  --name rebuild-opset17

food-detect parity data/roboflow/nhauhoai-v2 `
  --export-manifest runs/export/rebuild-opset17/export.json `
  --output-dir runs/parity `
  --name rebuild-opset17-cpu

Isolation, telemetry và retention

food-detect predict .\your-images `
  --name observed-run `
  --image-timeout-seconds 120 `
  --worker-startup-timeout-seconds 180 `
  --telemetry-file runs/telemetry/prediction.jsonl

food-detect retain runs/predict --dry-run --max-age-days 30 --keep-latest 10
food-detect retain runs/predict --max-age-days 30 --keep-latest 10
food-detect purge-quarantine runs/predict --dry-run --max-age-days 7

Retention chuyển run hết hạn sang <runs-root>/.retention-quarantine/; purge là bước riêng có audit. Xem Operations trước khi bật automation.

🗂️ Cấu trúc repository

.
├── src/food_detection/      package và CLI
├── tests/                   unit, contract và integration tests
├── docs/                    audit, model card, runbook và schema docs
├── data/                    registry + manifest; raw snapshot bị ignore
├── models/exports/          ONNX canonical + export evidence
├── runs/                    chỉ track benchmark/parity evidence canonical
├── vendor/                  lock manifest cho source YOLOv5
├── best.pt                  checkpoint baseline khóa hash
└── artifacts.manifest.json artifact registry canonical

Cache, raw data, output run và build product đều bị loại khỏi source control. README không embed ảnh legacy vì consent và quyền phân phối hình ảnh chưa được xác minh.

📚 Bản đồ tài liệu

Khi bạn cần…	Đọc
Hiểu model, taxonomy, metric và giới hạn	Model card
Xem provenance và phát hiện forensic	Audit
Tái lập dataset v2 và benchmark	Dataset v2
Tích hợp JSON output	Prediction run schema v2
Vận hành timeout, telemetry, retention	Operations
Theo dõi quá trình hiện đại hóa	Modernization
Review/migrate taxonomy	Taxonomy review
Kiểm tra third-party dependency	Third-party notices

🧰 Phát triển

python -m pip install -e ".[dev]"
python -m ruff check src tests
python -m ruff format --check src tests
python -m pytest -q

Integration thật cần cả source YOLOv5 đã bootstrap và ảnh baseline riêng tư được cung cấp ngoài Git:

$env:YOLOV5_REPO = (Resolve-Path .cache\food_detection\yolov5-100a423b66fee81e0a2915d5da934d7872f12c8c)
$env:FOOD_DETECTION_H060_IMAGE = 'C:\secure-data\H-060.jpg'
python -m pytest -q -m integration

⚠️ Bảo mật, quyền dữ liệu và giới hạn

• best.pt là checkpoint pickle-style legacy; chỉ loader allowlist với đúng SHA-256 mới được dùng. Không thay checkpoint bằng file không tin cậy.
• API key Roboflow không nằm trong source; dùng biến môi trường ROBOFLOW_API_KEY.
• Raw dataset và ảnh legacy không được publish trong cây hiện tại. Registry ghi CC BY 4.0, nhưng owner/consent/license review nội bộ vẫn chưa đóng.
• Repository chưa có LICENSE riêng cho code, data hoặc weights. Sự hiện diện của artifact không tự tạo quyền dùng thương mại hay tái phân phối.
• Backend YOLOv5 đã pin tuyên bố AGPL-3.0; hãy review nghĩa vụ license trước khi phân phối hoặc triển khai hệ thống kết hợp.
• Taxonomy 156 ID giữ nguyên để tương thích output, chưa phải ontology đã human-review.

Không dùng output của model cho quyết định an toàn, y tế, dinh dưỡng hoặc kiểm soát chất lượng nếu chưa có validation độc lập phù hợp use case.