{
    "title": "AI Image Search",
    "description": "Chi tiết luồng tìm kiếm hình ảnh kết hợp giữa Vision LLM (để bóc tách thuộc tính) và Vector Similarity Search trên StarRocks.",
    "diagram": "diagrams/image-search.svg",
    "sections": [
        {
            "title": "1. Tổng quan (Overview)",
            "type": "text",
            "content": "Image Search cho phép khách hàng up 1 tấm ảnh (Ví dụ: Ảnh người mẫu mặc váy hoa nhí) để tìm các sản phẩm tương tự trong kho Canifa. Điểm khác biệt là hệ thống không dùng thuật toán Image-to-Image thuần túy (rất đắt và chậm) mà dùng kiến trúc <b>Image-to-Text-to-Vector</b>."
        },
        {
            "title": "2. Kiến trúc & Luồng dữ liệu (Data Flow)",
            "type": "text",
            "content": "Quy trình tìm kiếm bằng ảnh tốn chưa tới 1.5 giây, qua 4 bước:<br><br><b>1. Vision Analysis:</b> Khi User gửi ảnh Base64 lên, API gọi qua Llama-4-Scout (hoặc GPT-4o) để bóc tách các đặc điểm thị giác (Áo sơ mi tay ngắn, kẻ sọc xanh, cổ đức...).<br><b>2. Text-to-Embedding:</b> Dịch chuỗi text mô tả trên thành một Vector toán học (Array float32) bằng model <code>text-embedding-3-small</code> (1536 chiều).<br><b>3. Vector Search (HNSW):</b> Quét Vector vừa tạo với hàng ngàn Vector sản phẩm trong <code>StarRocks</code> bằng thuật toán xấp xỉ <code>approx_cosine_similarity</code>.<br><b>4. LLM Reranking (Lọc lại):</b> Lấy top 10 kết quả từ DB đưa lại cho Agent để nó đối chiếu giá trị tồn kho, loại bỏ những SP sai giới tính/tuổi trước khi trả về Frontend."
        },
        {
            "title": "3. Core Logic: StarRocks Vector Index",
            "type": "text",
            "content": "Để StarRocks có thể quét Vector siêu tốc, bảng <code>magento_product_dimension</code> được thiết lập <b>HNSW Index</b> (Hierarchical Navigable Small World). Thuật toán này không tính khoảng cách Euclidean của tất cả bản ghi (Full Scan), mà nhảy qua các \"trạm trung chuyển\" (Graph nodes), giúp giảm độ trễ từ 3 giây xuống 200ms."
        },
        {
            "title": "4. API Image Search",
            "type": "api",
            "endpoints": [
                { "method": "POST", "path": "/api/image-search/chat", "description": "Gửi ảnh (Base64) kèm Text Query ('Tìm cho em cái áo giống thế này')." },
                { "method": "GET", "path": "/api/image-search/config", "description": "Lấy cấu hình Embedding Model đang dùng (OpenAI/Cohere)." }
            ]
        },
        {
            "title": "5. Code Snippet Thực Tế (Vector Query)",
            "type": "code",
            "language": "python",
            "code": "async def search_similar_products(query_vector: list[float], limit: int = 5):\n    \"\"\"Tìm Top K sản phẩm gần giống nhất bằng Cosine Similarity trên StarRocks\"\"\"\n    # Format vector thành chuỗi mảng SQL\n    vector_str = \"[\" + \",\".join(map(str, query_vector)) + \"]\"\n    \n    query = f\"\"\"\n        SELECT \n            internal_ref_code, \n            product_name,\n            approx_cosine_similarity(embedding_vector, {vector_str}) AS score\n        FROM magento_product_dimension_with_text_embedding\n        WHERE approx_cosine_similarity(embedding_vector, {vector_str}) > 0.75\n        ORDER BY score DESC\n        LIMIT {limit}\n    \"\"\"\n    return await db.execute(query)"
        },
        {
            "title": "6. Troubleshooting & Gotchas",
            "type": "text",
            "content": "<b>🚫 Lỗi Base64 Quá Lớn (Payload Too Large):</b><br>Nếu User chụp ảnh bằng iPhone 15 (10MB) và convert Base64, chuỗi sẽ dài hàng triệu ký tự khiến FastAPI quăng lỗi <code>413 Payload Too Large</code>. Phải có Middleware/Frontend tự động nén ảnh xuống dưới 1024x1024 (JPEG) trước khi gửi.<br><br><b>🚫 Lỗi Dimension Mismatch:</b><br>Nếu trong DB đang dùng model text-embedding-ada-002 (1536 chiều), mà API lại dùng nomic-embed-text (768 chiều), StarRocks sẽ crash ngay khi gọi hàm similarity. Luôn phải đồng nhất model Embedding khi tạo DB và khi truy vấn."
        }
    ]
}
