# Nghiệp vụ mô tả sản phẩm — Tại sao cần AI viết mô tả?

> **Tóm tắt:** Tài liệu giải thích tại sao Canifa cần pipeline AI 5 bước để sinh mô tả sản phẩm thay vì dùng con người hoặc LLM thuần. Phân tích cơ chế Guardrails chống hallucinate, Vision AI nhận diện ảnh, và chiến lược tách ground truth khỏi nội dung sáng tạo.

---

## 1. Vấn đề: Tại sao không viết mô tả thủ công?

Canifa có hàng **ngàn SKU** sản phẩm. Mỗi sản phẩm cần ít nhất 28 trường mô tả (tên, chất liệu, phong cách, dịp mặc, gợi ý phối đồ, hướng dẫn size, hook quảng cáo...). 

**Con số thực tế:**
- Catalog hiện tại: ~2000+ SKU
- Mỗi SKU cần ~28 trường mô tả chi tiết
- Mỗi mùa BST mới ra ~200-500 SKU
- Thời gian viết thủ công 1 SKU: **15-30 phút** (bởi content writer)
- Thời gian AI sinh 1 SKU: **~15 giây** (tự động hoàn toàn)

| Phương pháp | 500 SKU mới | Chi phí | Chất lượng |
|-------------|-------------|---------|-----------|
| Content Writer | 125-250 giờ (~1 tháng) | Cao (nhân sự) | Tốt nhưng không nhất quán |
| LLM thuần (ChatGPT/Gemini) | ~2 giờ | Thấp | ⚠️ Hallucinate tên, chất liệu, size |
| **Ultra Description Pipeline** | ~2 giờ | Thấp | ✅ Chính xác + sáng tạo |

> **Insight quan trọng:** LLM thuần sẽ "bịa đặt" tên sản phẩm, chất liệu, và size nếu không có cơ chế kiểm soát. Ví dụ: Sản phẩm tên "Áo Sơ Mi Nam Dài Tay" → LLM đổi thành "Áo Sơ Mi Lịch Lãm Premium" (nghe hay nhưng **sai tên chính thức**). Khách search trên web không tìm được.

---

## 2. Giải pháp: Pipeline 5 bước

Thay vì tin LLM 100%, Canifa xây dựng pipeline **5 bước tuần tự**, mỗi bước có một nhiệm vụ cụ thể:

![Ultra Description Pipeline](data/37-ultra-description-logic/ultra_pipeline.svg)

### Bước 1: Fetch Product Data (Ground Truth)

Lấy dữ liệu thật từ **StarRocks** database:
- Tên sản phẩm chính thức (không đổi)
- Giới tính (Nam/Nữ/Bé)
- Độ tuổi (Người lớn/Trẻ em)
- Bảng màu có sẵn
- Doanh số bán (để biết sản phẩm hot)
- Chất liệu từ Magento description

**Tại sao bước này quan trọng?** Vì nó tạo ra **bộ dữ liệu bất biến** — các trường này AI **không được phép thay đổi** dù sáng tạo đến đâu.

---

### Bước 2: Vision AI (Phân tích ảnh)

Sử dụng **Llama 4 Scout 17B** (model multimodal) để nhìn ảnh sản phẩm và nhận diện:
- Form dáng: slim fit, regular, oversize
- Hoa tiết: trơn, kẻ sọc, caro, in họa tiết
- Kiểu cổ: tròn, bẻ, chữ V, polo
- Chi tiết đặc biệt: túi ngực, khuy, kéo khóa

**Tại sao cần Vision AI?**
Database chỉ chứa metadata cơ bản (tên, mã, giá). Nó **không biết** áo có cổ bẻ hay cổ tròn, có hoa tiết hay trơn. Vision AI bổ sung thông tin thị giác mà text không capture được.

> **Guardrail quan trọng:** Vision AI chỉ mô tả **những gì nhìn thấy**. Nó không được phép đặt lại tên sản phẩm hay đoán chất liệu từ ảnh.

---

### Bước 3: Writer AI (Sinh 28 trường mô tả)

Sử dụng **GPT-OSS 120B** để sinh nội dung sáng tạo dựa trên:
- Ground truth từ Bước 1
- Visual details từ Bước 2

**28 trường bao gồm:**

| Nhóm | Các trường | Mô tả |
|------|-----------|-------|
| **Thông tin cứng** | `ten_san_pham`, `gioi_tinh`, `do_tuoi`, `chat_lieu` | Từ DB, AI không sửa |
| **Nội dung sáng tạo** | `tagline`, `mo_ta_chinh`, `hook_quang_cao` | AI tự do viết |
| **Thời trang** | `phong_cach`, `dip_mac`, `phoi_do`, `mua` | AI dựa trên metadata + vision |
| **Kỹ thuật** | `tinh_nang_vai`, `luu_y_size` | Dựa trên DB + bảng size |

**Nguyên tắc phân tách:**
- **Ground truth** (tên, giới tính, chất liệu) → **DB wins**, AI không được sửa
- **Nội dung sáng tạo** (tagline, mô tả, hook) → **AI tự do**
- **Hybrid** (phối đồ, dịp mặc) → AI viết nhưng dựa trên dữ liệu thật

---

### Bước 4: Size Guide (Hướng dẫn size từ bảng thật)

Nếu có bảng size thực tế từ Magento → AI sinh hướng dẫn chọn size tự nhiên:
- *"Người cao 170cm, nặng 65kg → nên chọn size L"*
- *"Áo phông cotton nên chọn đúng size, jean slim fit nên tăng 1 size"*

**Tại sao không để Writer sinh luôn?** Vì Writer model (120B) quá mạnh, nó sẽ **bịa số đo size** nếu không có dữ liệu thật. Bước riêng biệt dùng model nhẹ hơn (20B) + bảng size Magento → **100% chính xác**.

---

### Bước 5: Reviewer (Tự sửa lỗi)

AI Reviewer **kiểm tra lại** toàn bộ output của Writer:
- Tên sản phẩm có bị đổi không?
- Giới tính có bị lẫn không? (Nam → Nữ?)
- Chất liệu có khớp với DB không?
- Mô tả có nhất quán không?

**Đây là lớp phòng thủ cuối cùng** — nếu Writer lỡ hallucinate, Reviewer sẽ bắt lỗi và sửa.

---

## 3. Guardrails — Chống Hallucinate

Đây là phần **quan trọng nhất** của pipeline. 3 lớp bảo vệ:

| Lớp | Cơ chế | Ví dụ |
|-----|--------|-------|
| **Force-inject** | Sau Writer, code ghi đè các trường ground truth | `desc["ten_san_pham"] = state["product_name"]` |
| **Reviewer check** | AI Reviewer đối chiếu output vs DB | "Tên SP bị đổi → revert" |
| **Final force-inject** | Sau Reviewer, code ghi đè lần nữa | Chặn trường hợp Reviewer cũng hallucinate |

**Tại sao cần 3 lớp?**
Thực tế cho thấy ngay cả Reviewer đôi khi cũng "sáng tạo" thêm. Lớp force-inject cuối cùng (code thuần, không AI) đảm bảo **tuyệt đối không bao giờ sai** các trường cốt lõi.

> **Triết lý:** AI được phép sáng tạo ở nội dung marketing (tagline, mô tả). AI **KHÔNG** được phép thay đổi sự thật (tên, giới tính, chất liệu). Ranh giới này phải được enforce bằng code, không phải bằng prompt.

---

## 4. Kết quả đầu ra

Sau pipeline, mỗi sản phẩm có:
1. **`description_data`** — JSON 28 trường chi tiết
2. **`clean_description`** — Text thuần để hiển thị
3. **`luu_y_size`** — Hướng dẫn chọn size

Tất cả lưu vào **PostgreSQL** (`ultra_descriptions` table), sẵn sàng serve cho:
- Website Canifa (SEO content)
- AI Chatbot (khi tư vấn sản phẩm)
- Social media (hook quảng cáo)

---

## 5. Tổng kết

| Quyết định thiết kế | Lý do nghiệp vụ |
|---------------------|-----------------|
| Pipeline 5 bước thay vì LLM 1 shot | Tách biệt ground truth và nội dung sáng tạo |
| Vision AI riêng biệt | Database không chứa visual details (form, hoa tiết) |
| 3 lớp Guardrails | Chống hallucinate tuyệt đối cho tên, giới tính, chất liệu |
| Size Guide bước riêng | Dùng bảng size thật từ Magento, không để AI bịa |
| Reviewer tự sửa | Lớp phòng thủ cuối trước khi save vào DB |
| GPT-OSS 120B + Llama Scout | Kết hợp model mạnh (viết) + model vision (nhìn) |

---

## References

1. Canifa Engineering. *"Ultra Description Agent v2"* — `agent/ultra_descriptions_agent/agent.py`
2. Canifa Engineering. *"Size Guide Worker"* — `worker/size_guide_worker.py`
3. LangGraph Documentation. *"StateGraph Pattern"* — Graph-based agent orchestration.
