Canifa AI Stylist - Lead Search Architecture

Bản vẽ chi tiết luồng hoạt động & Kiến trúc tối ưu Token (Cập nhật T4/2026)

1. Tổng quan (Overview)

Lead Search Tool là trung tâm truy xuất dữ liệu sản phẩm của Canifa AI Stylist. Sau đợt tái cấu trúc, hệ thống đã loại bỏ hoàn toàn OpenAI Embedding, thay thế bằng cơ chế Cascading Search 7 tầng (NGRAMBF + BITMAP Tags), mang lại tốc độ truy vấn < 300ms. Đồng thời, cấu trúc dữ liệu trả về được tối ưu hóa để giảm thiểu Token tiêu thụ cho LLM.

2. Kiến trúc Tối ưu Token (Token-Saving Architecture)

Thay vì trả về 15-20 sản phẩm chi tiết (gây tràn Context Window), hệ thống hiện tại sử dụng chiến lược: "Lấy ít sản phẩm chính, móc nhiều sản phẩm gợi ý".

• Main Products (Top 3): Trả về tối đa 3 sản phẩm match nhất với đầy đủ thông tin chi tiết (Size, Giá, Mô tả ngắn <200 ký tự, Tồn kho thực tế, Lý do phối đồ AI).
• Suggest Items (Phối cùng): Cho mỗi sản phẩm chính, lấy thêm tối đa 2 sản phẩm phối cùng (chỉ gồm SKU, Tên, Giá).
• Similar Items (Tương tự): Cho mỗi sản phẩm chính, lấy thêm tối đa 3 sản phẩm thay thế (chỉ gồm SKU, Tên, Giá).

Kết quả: LLM vẫn có 3 lựa chọn chính và 15 lựa chọn phụ để tư vấn, nhưng số lượng Token giảm xuống 75%.

3. Luồng dữ liệu (Data Flow)

1. Phân tích Ý định (Input parsing): Nhận các tham số từ Agent: keywords, tags, color, size, price_min, price_max.
2. Cascading Search (7 Tiers): Truy xuất StarRocks qua 7 tầng rớt mạng. Tầng 1 (Keywords + Hard Filters), Tầng 2 (Tags + Filters), Tầng 5-6 (Nới giá 1.5x - 2.0x).
3. Lọc Tồn Kho (Stock API): Gửi các mã sản phẩm sang Canifa Stock API qua httpx. Chỉ giữ lại những mã đang CÒN HÀNG, kèm theo danh sách chi tiết các size còn trống.
4. Bổ sung Styling (SQLite 123.db): Đọc file SQLite local để lấy ai_description và ai_matches (lý do phối đồ), cung cấp 'bộ não' thời trang cho LLM chốt sale.
5. Định dạng Đầu ra (Output Formatter): Gom nhóm dữ liệu, cắt ngắn mô tả, fetch suggest/similar items và trả về JSON nhẹ nhất cho AI.

4. Đầu ra của hệ thống (JSON Format)

Dưới đây là cấu trúc minh hoạ cho 1 sản phẩm chính sau khi được format gọn nhẹ:

{
  "sku": "8TP24S001-SB060",
  "name": "Áo polo nam phom regular",
  "price": 349000,
  "in_stock": true,
  "stock": [{"size": "M", "qty": 10}, {"size": "L", "qty": 14}],
  "ai_matches": {
    "phoi_voi": ["Quần khaki nam"],
    "ly_do": "Màu áo hợp quần khaki tạo vẻ thanh lịch..."
  },
  "suggest_items": [
    {"sku": "8QK24S002", "name": "Quần khaki nam", "price": 450000}
  ],
  "similar_items": [
    {"sku": "8TP24S003", "name": "Áo polo sọc", "price": 399000}
  ]
}