AMZPET (Amazon Product Enrichment Tool) là công cụ nội bộ tự động điền và chuẩn hóa thuộc tính sản phẩm (product attributes) cho catalog Amazon của Spiraledge — pilot bắt đầu với ngành hàng SWIMWEAR (đồ bơi các house brand: Sporti, iSwim, ClubSwim). Khác với các công cụ “để AI điền tất”, AMZPET được xây trên đúng một nguyên tắc: “Để trống thì chấp nhận được. Dữ liệu không có căn cứ thì không.” Mỗi giá trị được điền đều phải có bằng chứng (evidence) và nguồn gốc (provenance); mỗi ô để trống đều phải có lý do (reason code).
🔗 Dùng thử (truy cập nội bộ): https://steve.id.vn/PETAMZ/
🎯 Bài toán — Vì sao điền attribute Amazon lại khó
Mỗi Product Type trên Amazon có một template khai báo 250–330 cột thuộc tính. Trong đó chỉ ~10 cột là bắt buộc, nhưng có tới 56–85 cột “bắt buộc có điều kiện” (conditionally required — bắt buộc tùy theo biến thể, cha/con, giá trị của cột khác) và hơn 100 cột tùy chọn. Đây mới là phần khó thật sự.
Cách làm cũ (tool Target+ đời trước) và cách làm tay có chung ba điểm đau:
- Accuracy thấp — điền sai giá trị, sai enum (Amazon từ chối listing).
- Coverage thấp — bỏ trống nhiều, hoặc điền bừa cho “đủ cột”.
- Không có evidence — không ai biết một giá trị từ đâu ra, đúng hay sai, có tái lập được không.
Còn giải pháp “để AI điền tất” nghe thì hấp dẫn nhưng lại đắt, không nhất quán, và tệ nhất là bịa (hallucinate) ra những giá trị không hề tồn tại trên sản phẩm — dẫn thẳng đến sai enum và listing bị suppress. AMZPET giải quyết cả ba pain point cùng lúc bằng một pipeline có bằng chứng, thay vì đặt cược vào AI.
⚙️ Cơ chế vận hành — Pipeline thác nước 8 tầng (T0–T8)
Mỗi thuộc tính của mỗi SKU được chạy qua tối đa 8 tầng nguồn. Mỗi tầng đề xuất candidate (giá trị + nguồn + evidence_id); tầng quyết định sẽ trọng tài các candidate đó. Nguyên tắc cốt lõi: ưu tiên nguồn tất định trước, AI đứng cuối cùng và chỉ được gọi khi thật sự cần.
| Tầng | Nguồn | Cơ chế | Tất định? |
|---|---|---|---|
| T0 | Protected existing | Giá trị đã có sẵn được khóa lại, không bao giờ bị ghi đè | ✓ |
| T1 | Amazon direct | Đọc thẳng Category Listings Report, khớp SKU chính xác (~1,2 triệu facts / 20k SKU đã test) | ✓ |
| T2 | Own-site | Cào swimoutlet.com / everydayyoga.com (JSON-LD + parser bảng thông số) | ✓ |
| T3 | Rule engine | Regex/chuẩn hóa, khóa theo enum (65 rule cho SWIMWEAR) | ✓ |
| T4 | Propagation | Kế thừa theo parent/family, có kiểm soát phạm vi (không lẫn màu/size giữa các biến thể) | ✓ |
| T5 | Historical | Dữ liệu QA đã duyệt trước đó (HUMAN_APPROVED) | ✓ |
| T6 | Competitor | Firecrawl tìm sản phẩm đối thủ (Speedo/Arena/TYR) — nguồn mềm | ✗ (QA review) |
| T7 | AI | OpenAI Structured Outputs, JSON khóa enum, bắt buộc kèm evidence — nguồn mềm | ✗ (QA review) |
| T8 | Decision engine | Hard gate + hybrid accept + gán reason code cho mọi ô để trống | ✓ (trọng tài) |
T0–T5 (tất định) chạy vô điều kiện. T6–T7 (nguồn mềm) chỉ chạy khi chưa có tầng nào resolve được thuộc tính đó. Đây là lý do một job chạy hoàn toàn không cần AI vẫn cho kết quả rất cao — xem số liệu bên dưới.
🧠 Logic enrichment — Làm sao biết giá trị nào là đúng
- Khóa theo enum (enum-lock): Rule và AI đều bắt buộc chọn từ danh sách
valid_valuescủa schema — không thể tự bịa giá trị mới. Mục tiêu bất di bất dịch: 0 giá trị ngoài enum. - Evidence & provenance 100%: Mọi giá trị được điền đều gắn evidence_id + tầng nguồn. Reviewer bấm vào là thấy bằng chứng.
- Reason code cho mọi blank: Ô để trống không phải là “quên” — nó mang mã lý do (UNSUPPORTED / CONFLICT / NOT_SOURCED…). “Blank có chủ đích” là một kết quả hợp lệ.
- Phân lớp rủi ro (risk class): REVIEW_ONLY (mặc định — mọi candidate phải qua QA review); DIRECT_ONLY (identity như UPC, brand — chỉ nhận nguồn trực tiếp T0/T1, rule/AI/competitor bị từ chối thẳng); AUTO_SAFE (nguồn tất định T0–T5 tự động chấp nhận nếu khớp enum).
- Row isolation & reproducibility: Không rò rỉ dữ liệu chéo SKU; cùng input + cùng schema version + cùng rule → cùng output, 100% tái lập.
📊 Kết quả thực tế — Job #33 (108 SKU, AI tắt, chi phí $0.00)
Job QA thật gần nhất: 108 SKU (10 style đồ bơi one-piece Sporti), schema v11, 65 rule, ngưỡng 0.98, AI tắt hoàn toàn. Mọi dự đoán được đăng ký trước khi chạy, và tất cả đều đúng.
| Chỉ số | Kết quả |
|---|---|
| EXACT (khớp chính xác truth) | 1844 / 2045 = 90,2% |
| PRESENCE (điền đúng chỗ cần điền) | 1102 / 1140 = 96,7% |
| BLANK (để trống đúng chỗ cần trống) | 972 / 972 = 100% |
| Số thuộc tính đạt 100% chính xác | 22 attribute |
| Auto-accept / vào queue review | 4118 / 2228 |
| Số candidate AI được gọi | 0 |
| Chi phí API | $0.00 |
So với chính file đó, cùng một bộ truth:
| Lần chạy | Cấu hình | Chi phí | EXACT |
|---|---|---|---|
| Job #11 (30/07) | AI BẬT, trước các bản fix | $40,12 | 54,7% |
| Job #33 (hôm nay) | AI TẮT | $0,00 | 90,2% |
Nói cách khác: chính xác hơn +35,5 điểm so với lần chạy AI tốn $40 — mà chi phí bằng 0. Đây là bằng chứng thực nghiệm cho triết lý tất định-trước.
🧑💻 Cách sử dụng — Ops Console 6 bước
- Upload — tải file danh sách SKU (Excel/CSV).
- Map — ánh xạ cột input của bạn sang attribute chuẩn (có UI column-mapping, không cần đúng format cứng).
- Configure — chọn schema version, ngưỡng confidence, bật/tắt AI và competitor.
- Run — engine chạy T0–T8 song song cho từng dòng (worker bất đồng bộ).
- Review — màn hình 3 vùng: thanh attribute (trái) + lưới AG Grid (giữa) + ngăn evidence (phải). Approve/sửa từng ô, hoặc bulk approve theo bộ lọc (ví dụ confidence ≥ 0.80). Mỗi quyết định QA đã duyệt được lưu lại làm dữ liệu Historical cho lần sau.
- Export — xuất Excel phẳng 1 dòng/SKU × các attribute đã enrich (không ghi ngược vào file template — template chỉ là nguồn schema).
💰 Hiệu quả
- Làm tay: ~5–7 phút/SKU × 69 attribute → hàng chục giờ công cho một batch, error rate 8–15%, không tái lập.
- AMZPET (deterministic run): chi phí API $0, EXACT 90,2%, phần còn lại vào review queue — nhưng từng ô đều kèm evidence để duyệt trong vài giây thay vì tra cứu thủ công.
- Nhất quán 100%: cùng input → cùng output, không sai do con người.
🔍 Minh bạch — Những gì tool CHƯA làm được (và đã đặt tên)
AMZPET không giấu điểm yếu. Job #33 còn 201 ô chưa khớp exact, và mỗi nhóm đều có “chủ”:
fit_type(62,6%) — trần của rule hằng; AI đo còn tệ hơn nên bị chặn.material— 8 ô xung đột giữa “Polyester Blend” của Amazon và thành phần thật (câu hỏi về thứ tự ưu tiên nguồn, đã ghi nhận).- Nhóm chưa có nguồn:
title_differentiation,pattern,lifestyle,unspsc_code— chưa nguồn tất định nào tạo ra được; đây là biên giới thành thật của pipeline.
🗺️ Roadmap
- Ngắn hạn: đóng các gap đã đặt tên ở trên; thêm Parent Code vào template upload để phủ nốt các SKU thiếu report.
- Trung hạn: mở rộng ngoài SWIMWEAR sang các Product Type Amazon khác (đã có sẵn 15 PT trong schema); import kho Historical (T5); bật Competitor (T6) có kiểm soát chi phí.
- Dài hạn: Precision Tracker tự động “thăng cấp” một attribute AI sang auto-accept khi đo được ≥ 98% precision trên ≥ 100 mẫu; tiến tới dashboard multi-marketplace.
Bài viết tổng hợp từ số liệu thực tế của các enrichment job trên pilot SWIMWEAR — cập nhật tháng 8/2026. Triết lý xuyên suốt: “Để trống thì chấp nhận được. Dữ liệu không có căn cứ thì không.”