# 6. Troubleshooting & Gotchas

Khi làm việc với Image Search và Vision LLM trên production, hãy cẩn thận các lỗi sau:

### 1. Lỗi Payload Base64 Quá Lớn (Payload Too Large)
- **Triệu chứng:** FastAPI quăng lỗi `413 Payload Too Large` hoặc OOM (Out of Memory) trên Container khi upload.
- **Nguyên nhân:** Ảnh chụp từ điện thoại hiện đại (VD iPhone) thường nặng > 5MB. Khi encode sang Base64 chuỗi cực kỳ dài. Nếu người dùng gửi 3-4 ảnh, payload size vượt quá limit của web server.
- **Cách khắc phục:** Client (Mobile/Web) BẮT BUỘC phải nén ảnh xuống chuẩn (VD: JPEG, max resolution 1024x1024, chất lượng 80%) trước khi convert sang Base64 và push lên backend API.

### 2. Hallucination của Vision Planner (AI Bịa Đồ)
- **Triệu chứng:** Người dùng gửi ảnh 1 cái ly nước, nhưng Planner vẫn gọi tool tìm áo, tự tạo ra `product_line_vn=["Áo phông"]`.
- **Cách khắc phục:** Prompt `VISION_PLANNER_PROMPT` đã phải rào kỹ: *"NẾU KHÔNG CÓ QUẦN ÁO/PHỤ KIỆN... KHÔNG ĐƯỢC BỊA THÊM. KHÔNG GỌI TOOL"*. Việc nhắc lại mạnh mẽ trong prompt là bắt buộc đối với Vision model.

### 3. Dimension Mismatch trong Vector Database
- **Triệu chứng:** Lỗi StarRocks crash hoặc SQL Exception khi chạy `approx_cosine_similarity`.
- **Nguyên nhân:** Dữ liệu trong bảng `magento_product_dimension_with_text_embedding` được build bằng model `text-embedding-3-small` (1536 dimensions), nhưng API lại vô tình dùng một model embedding khác (VD Cohere hay nomic) có số chiều khác (VD 1024 hoặc 768). Hàm cosine trên database yêu cầu size của 2 vector phải bằng nhau.