Update README.md

README.md

@@ -8,59 +8,125 @@ tags:
   - seq2seq
   - bartpho
   - genz
+  - text-normalization
 ---
 
-# Model Card: TeenCode Translator BARTpho
+# Model Card for TeenCode Translator BARTpho
 
-Một mô hình Seq2Seq được tinh chỉnh (fine-tuned) chuyên sâu để dịch ngôn ngữ mạng, Teencode GenZ, và bình luận TikTok sang Tiếng Việt chuẩn mực.
+Hệ thống AI chuẩn hóa ngôn ngữ mạng xã hội (Teencode GenZ) sang Tiếng Việt tiêu chuẩn, bảo lưu trọn vẹn cảm xúc, biểu tượng và ngữ nghĩa gốc.
 
 ## Model Details
 
 ### Model Description
 
-Đây là mô hình dịch thuật Teencode sang Tiếng Việt được huấn luyện theo phương pháp Active Learning. Thay vì chỉ chuẩn hóa chính tả thông thường, mô hình được thiết kế để bảo tồn tối đa ngữ cảnh và cảm xúc của câu gốc, tuân thủ nghiêm ngặt các quy tắc xử lý ngôn ngữ tự nhiên (NLP) đặc thù.
+Đây là mô hình Seq2Seq được tinh chỉnh (fine-tuned) từ kiến trúc BARTpho. Mô hình được thiết kế đặc biệt để xử lý dữ liệu bình luận (comments) trên nền tảng TikTok và các đoạn chat GenZ. Điểm khác biệt của mô hình là khả năng dịch chuẩn xác các từ lóng phức tạp mà vẫn tuân thủ nghiêm ngặt các quy tắc bảo lưu ngoại ngữ, dấu câu, emoji và từ ngữ nhạy cảm gốc.
 
-- **Developed by:** lê Đan Sơn (Hust)
-- **Model type:** Text-to-Text Generation (Seq2Seq)
-- **Language(s) (NLP):** Tiếng Việt (vi)
+- **Developed by:** Lớp phó học tập (6GN1)
+- **Model type:** Text-to-Text Generation (Seq2Seq Transformer)
+- **Language(s) (NLP):** Tiếng Việt (vi) / Teencode
+- **License:** MIT
 - **Finetuned from model:** BARTpho
 
+### Model Sources
+
+- **Repository:** Đang cập nhật (GitHub Link)
+- **Demo:** Tích hợp sẵn giao diện Gradio Real-time Translation.
+
 ## Uses
 
 ### Direct Use
 
 Mô hình được sử dụng trực tiếp để:
-- Chuẩn hóa các văn bản chứa nhiều từ lóng, viết tắt (VD: `khum`, `đc`, `j`, `trc`).
-- Làm sạch dữ liệu văn bản (Data Cleaning) cho các bài toán NLP khác tiếng Việt (Phân tích cảm xúc, Chatbot).
-- Tích hợp vào các ứng dụng chat hoặc công cụ hỗ trợ đọc hiểu văn bản mạng.
+- Chuẩn hóa văn bản Teencode (VD: `khum`, `j`, `đc`, `ntn`, `htrc`).
+- Tiền xử lý dữ liệu (Data Preprocessing) cho các bài toán NLP Tiếng Việt khác (Phân tích cảm xúc, Phân loại văn bản).
+- Khôi phục văn bản viết tắt trên mạng xã hội thành văn bản hành chính/báo chí có thể đọc hiểu.
 
 ### Out-of-Scope Use
 
-- Mô hình không được thiết kế để dịch thuật đa ngôn ngữ (VD: Anh - Việt).
-- Không phải là mô hình đàm thoại (Chatbot/LLM) để trả lời câu hỏi. 
+- Mô hình không hỗ trợ dịch thuật đa ngôn ngữ (VD: Anh sang Việt).
+- Không phải là mô hình đàm thoại (Chatbot/LLM) để hỏi đáp kiến thức.
+- Sẽ gặp hiện tượng ảo giác (hallucination) nếu nhồi nguyên một đoạn văn dài hơn 64 token mà không băm nhỏ (chunking) theo dấu câu.
 
 ## Bias, Risks, and Limitations
 
-**Tính năng bảo lưu ngôn từ nhạy cảm:** Để đảm bảo tính nguyên bản của dữ liệu NLP, mô hình được huấn luyện để **TUYỆT ĐỐI KHÔNG KIỂM DUYỆT** từ chửi thề hay lóng thô tục (VD: `vcl`, `duma`). Người dùng tích hợp mô hình vào ứng dụng đại chúng cần tự xây dựng bộ lọc hậu xử lý (Post-processing) nếu cần thiết.
+**CẢNH BÁO VỀ KIỂM DUYỆT TỪ NGỮ:**
+Để đảm bảo tính nguyên bản của dữ liệu ngôn ngữ tự nhiên, mô hình được huấn luyện với quy tắc **Tuyệt đối không kiểm duyệt từ chửi thề, lóng thô tục** (VD: `vcl`, `duma`, `vl`...). Người dùng ứng dụng (Downstream Use) cần tự xây dựng bộ lọc từ ngữ (Profanity Filter) nếu triển khai cho môi trường học đường hoặc trẻ em.
+
+### Recommendations
 
-**Giới hạn độ dài:** Do được tinh chỉnh ở `max_length=64`, văn bản đầu vào quá dài (trên 50 từ) cần được băm nhỏ (chunking) theo dấu câu trước khi đưa vào mô hình để tránh hiện tượng ảo giác (hallucination).
+Nên sử dụng mô hình kết hợp với bộ lọc hậu xử lý (Post-processing Pipeline) để xử lý linh hoạt đại từ nhân xưng, ví dụ: tự động đổi "tôi" thành "tao" nếu trong câu xuất hiện chữ "mày" để đảm bảo tính tự nhiên trong văn hóa giao tiếp Tiếng Việt.
 
 ## How to Get Started with the Model
 
-Sử dụng thư viện `transformers` và `pipeline` để gọi mô hình:
+Sử dụng đoạn code dưới đây để gọi mô hình qua thư viện `transformers`:
 
 ```python
 from transformers import pipeline
 
-# Nạp mô hình từ Hugging Face
 translator = pipeline(
     "text2text-generation", 
     model="Tên-Tài-Khoản-Của-Bạn/TeenCode-Translator-BARTpho"
 )
 
-# Test nghiệm thu
+# Text đầu vào (chứa teencode, emoji và lóng)
 text = "mai ik cf k duma t thik m vcl =))"
+
+# Chạy inference
 result = translator(text, max_length=64, num_beams=5, early_stopping=True)
 
 print(result[0]['generated_text'])
-# Output kỳ vọng: "mai đi cà phê không duma tao thích mày vcl =))"
+# Output: "mai đi cà phê không duma tôi thích mày vcl =))"
+```
+
+## Training Details
+
+### Training Data
+
+Dữ liệu huấn luyện được thu thập từ các bình luận thực tế trên TikTok Việt Nam. 
+Tập dữ liệu đã trải qua quá trình lọc nhiễu bằng thuật toán Cross-Entropy Loss:
+- Loại bỏ dữ liệu rác/sai nhãn (Loss > 12.0).
+- Tập trung vào tập "Golden Dataset" chứa các ca Teencode khó (1.0 < Loss < 2.0).
+- Bổ sung dữ liệu nhân tạo (Active Learning) cho các cụm từ mô hình thường dịch sai (`cf`, `hnao`, `hsy`, `htrc`).
+
+### Training Procedure
+
+Mô hình được huấn luyện qua 2 giai đoạn:
+1. **Phase 1 (Full Fine-tune):** Huấn luyện trên toàn bộ tập dữ liệu gốc.
+2. **Phase 2 (Hard Examples Fine-tune):** Huấn luyện tập trung vào các câu khó với Learning Rate thấp để tránh Catastrophic Forgetting.
+
+#### Training Hyperparameters
+
+- **Training regime:** fp16
+- **Learning Rate:** 2e-5 phase 2 & 5e-5 phase 1
+- **Batch Size:** 64 (Train & Eval)
+- **Gradient Accumulation Steps:** 1
+- **Epochs:** 5
+- **Optimizer:** AdamW
+- **Weight Decay:** 0.01
+
+## Evaluation
+
+### Testing Data, Factors & Metrics
+
+#### Testing Data
+Tập kiểm thử (Test set) chiếm 10% tổng số dữ liệu Golden Dataset, được tách biệt ngẫu nhiên trước khi đưa vào huấn luyện Phase 2.
+
+#### Metrics
+Sử dụng **Cross-Entropy Loss (Eval Loss)** để đánh giá khả năng mô hình hóa ngôn ngữ.
+
+### Results
+
+- **Checkpoint:** 464
+- **Eval Loss:** ~0.200
+- **Grad Norm:** Ổn định ở mức 1.3 - 3.4.
+- **Tốc độ Inference:** ~512 samples/second trên RTX 4060 Ti.
+
+#### Summary
+Mức Loss hội tụ ở 0.2 chứng minh mô hình không bị Overfitting mà đã thực sự nắm bắt được quy luật chuyển đổi ngữ nghĩa phức tạp của Teencode.
+
+## Technical Specifications
+
+### Compute Infrastructure
+
+- **Hardware:** 1x NVIDIA GeForce RTX 4060 Ti (16GB VRAM)
+- **Software:** PyTorch, Hugging Face Transformers, Datasets.