🌐 HyMT Translation Web App

Ứng dụng dịch thuật AI hỗ trợ English ↔ Vietnamese và 33 ngôn ngữ, powered by AngelSlim/Hy-MT1.5-1.8B-1.25bit.

✨ Features

• 🇻🇳 English ↔ Vietnamese — Cặp ngôn ngữ mặc định
• 🌍 33 Languages — Hỗ trợ thêm Trung, Nhật, Hàn, Pháp, Đức, ...
• 🤖 Hy-MT1.5-1.8B-1.25bit — Model dịch thuật Sherry 1.25-bit (440MB)
• 🎨 Modern UI — Glassmorphism, dark/light theme
• 🐳 Docker Ready — Frontend (nginx) + Backend (FastAPI)

📁 Project Structure

translation-app/
├── frontend/                         ← Frontend (HTML/CSS/JS)
│   ├── index.html
│   ├── css/style.css
│   ├── js/
│   │   ├── app.js                    # Main controller (Mediator)
│   │   ├── api-client.js             # API facade
│   │   └── language-selector.js      # Language picker (Observer)
│   ├── nginx.conf                    # Nginx config (proxy to backend)
│   └── Dockerfile                    # Nginx container
├── backend/                          ← Backend (FastAPI + Python)
│   ├── app/
│   │   ├── main.py                   # FastAPI entry + Composition Root
│   │   ├── config.py                 # Settings (pydantic-settings)
│   │   ├── core/
│   │   │   ├── model_manager.py      # Singleton model loader
│   │   │   ├── prompt_builder.py     # Strategy + Factory patterns
│   │   │   └── language_registry.py  # Repository (33 languages)
│   │   ├── schemas/
│   │   │   └── translation.py        # DTO (Pydantic models)
│   │   ├── services/
│   │   │   └── translation_service.py
│   │   └── api/
│   │       └── routes.py             # REST endpoints
│   ├── requirements.txt
│   └── Dockerfile
├── docker-compose.yml
├── .env.example
└── README.md

🏗 Design Patterns

🚀 Hướng Dẫn Chạy Dự Án

Yêu Cầu Hệ Thống

---

Cách 1: Chạy bằng Docker (Khuyến nghị) 🐳

Bước 1 — Clone project và tạo file .env:

cd translation-app
cp .env.example .env

Bước 2 — Chỉnh sửa .env nếu cần (xem Cấu hình Environment bên dưới).

Bước 3 — Build và chạy cả 2 services:

# Chạy foreground (xem log trực tiếp)
docker compose up --build

# Hoặc chạy background (detached mode)
docker compose up --build -d

⏳ Lần đầu chạy sẽ mất thời gian vì Docker cần:

1. Build image Python + cài dependencies (~3-5 phút)
2. Download model từ HuggingFace (~440MB)
3. Load model vào bộ nhớ

Bước 4 — Truy cập ứng dụng:

Dừng ứng dụng:

docker compose down           # Dừng containers
docker compose down -v        # Dừng + xóa volume cache model

Xem logs:

docker compose logs -f backend    # Log backend (model loading, requests)
docker compose logs -f frontend   # Log nginx

Bật GPU (NVIDIA) cho Docker

Nếu máy có GPU NVIDIA, mở docker-compose.yml và uncomment phần deploy:

backend:
  # ...
  deploy:
    resources:
      reservations:
        devices:
          - driver: nvidia
            count: 1
            capabilities: [gpu]

Yêu cầu đã cài NVIDIA Container Toolkit.

---

Cách 2: Chạy Local (Development) 💻

Bước 1 — Cài đặt Backend

# Di chuyển vào thư mục backend
cd translation-app/backend

# Tạo virtual environment
python3 -m venv venv

# Kích hoạt virtual environment
source venv/bin/activate        # Linux/Mac
# venv\Scripts\activate         # Windows

# Cài đặt dependencies
pip install -r requirements.txt

Bước 2 — Cấu hình Environment

# Tạo file .env từ template (ở thư mục gốc)
cp ../.env.example .env

Hoặc tạo file .env trong thư mục backend/ với nội dung:

MODEL_NAME=AngelSlim/Hy-MT1.5-1.8B-1.25bit
MODEL_DEVICE=auto
CORS_ORIGINS=*

Bước 3 — Chạy Backend Server

# Chạy development server (có auto-reload khi sửa code)
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

⏳ Lần đầu chạy, server sẽ tự động download model từ HuggingFace (~440MB). Sau khi download xong, model được cache tại ~/.cache/huggingface/. Các lần chạy sau sẽ load trực tiếp từ cache (nhanh hơn).

Khi thấy log Model loaded successfully, backend đã sẵn sàng.

Bước 4 — Chạy Frontend (Terminal mới)

# Mở terminal mới, di chuyển vào thư mục frontend
cd translation-app/frontend

# Chạy simple HTTP server
python3 -m http.server 3000

Bước 5 — Truy cập ứng dụng

• Frontend: http://localhost:3000
• Backend API Docs: http://localhost:8000/docs
• Backend ReDoc: http://localhost:8000/redoc

---

⚙️ Cấu Hình Environment

Các biến môi trường trong file .env:

Lưu ý: Nếu chỉ có CPU, đặt MODEL_DEVICE=cpu. Dịch sẽ chậm hơn (~10-30s/request) nhưng vẫn hoạt động.

---

🔧 Troubleshooting

---

📡 API Endpoints

Example

curl -X POST http://localhost:8000/api/v1/translate \
  -H "Content-Type: application/json" \
  -d '{
    "source_text": "Hello, how are you?",
    "source_language": "en",
    "target_language": "vi"
  }'

📝 Model Info

• Model: AngelSlim/Hy-MT1.5-1.8B-1.25bit
• Size: ~440MB (Sherry 1.25-bit quantized)
• Base: Tencent HY-MT1.5-1.8B
• Languages: 33 languages, 1,056 translation directions