# 6. Troubleshooting & Gotchas

**🚫 Lỗi JSON Parsing từ LLM:**
LLM thường hay rườm rà chèn thêm markdown như ` ```json ... ``` ` hoặc sinh ra text ngoài JSON. 
**Giải pháp:** Sử dụng hàm `_extract_json()` hỗ trợ RegEx quét sạch text rác để tìm cục `{...}` hoặc mảng `[...]`.

**🚫 Model Vision không chạy được vì Proxy:**
Các cổng proxy trung gian (ví dụ LiteLLM) thỉnh thoảng sẽ block payload chứa image base64 mảng cực lớn. 
**Giải pháp:** Đối với các model Gemini (vd: `gemini-3.1-flash-lite-preview`), gọi trực tiếp (Native API) lên Endpoint của Google API bằng HTTPX.

**🚫 Cập nhật Data Base bị lỗi Transaction:**
Trong psycopg2, khi gọi hàm `cur.execute("UPDATE ...")` nhưng quên gọi `conn.commit()`, lệnh sẽ không báo lỗi nhưng Data không được lưu xuống đĩa. 
**Giải pháp:** Đảm bảo mọi method thao tác DB trong `UltraDescriptionDB` đều gọi `conn.commit()` và có luồng `try-except-finally` đóng kết nối `conn.close()`.

**🚫 Block HTTP Request khi Batch Generate:**
Thay vì để Frontend đứng chờ xử lý hàng chục sản phẩm dẫn tới Gateway Timeout (504), API sử dụng kiến trúc **Producer-Consumer**. 
**Giải pháp:** Endpoint `/batch-generate` lập tức đẩy job vào **Redis Queue** (`desc:queue`) và trả về `job_id`. Trình duyệt sẽ gọi Polling tới `/batch-status/{job_id}` để lấy tiến độ `done / total`.