Image-to-Text Captioning 🖼️

Một ứng dụng tạo mô tả văn bản từ hình ảnh được xây dựng với kiến trúc Python chuẩn, sử dụng Vision Transformer + GPT-2 và giao diện web Gradio.

✨ Features

• 📸 Tạo mô tả từ hình ảnh - Upload ảnh và nhận mô tả tự động bằng tiếng Anh
• 🤖 Vision Transformer + GPT-2 - Model AI tiên tiến từ HuggingFace (nlpconnect/vit-gpt2-image-captioning)
• 🖥️ Giao diện web Gradio - UI thân thiện, dễ sử dụng
• ⚡ GPU/CPU Support - Tự động phát hiện và sử dụng GPU khi có
• 🎛️ Tùy chỉnh linh hoạt - Điều chỉnh độ dài caption và beam search
• 💾 Models lưu local - Tải model một lần, sử dụng offline
• 🔧 Kiến trúc chuẩn - Cấu trúc Python package professional
• 📷 Đa định dạng - Hỗ trợ JPG, PNG, GIF, BMP, TIFF

📁 Cấu Trúc Dự Án

python-image-to-text/
├── src/
│   └── text_to_image/
│       ├── __init__.py
│       ├── cli.py              # Command line interface
│       ├── core/
│       │   ├── __init__.py
│       │   └── generator.py    # Core generation logic
│       ├── ui/
│       │   ├── __init__.py
│       │   └── gradio_interface.py  # Web interface
│       └── utils/
│           ├── __init__.py
│           ├── config.py       # Configuration management
│           └── logger.py       # Logging utilities
├── tests/                      # Unit tests
├── models/                     # Local model storage
├── data/                       # Data directory
├── logs/                       # Application logs
├── app.py                      # Main application runner
├── pyproject.toml             # Modern Python packaging
├── requirements.txt           # Dependencies
└── README.md

🚀 Installation

Phương pháp 1: Chạy trực tiếp

# 1. Clone hoặc download project
git clone <your-repo-url>
cd python-image-to-text

# 2. Tạo virtual environment (khuyến nghị)
python -m venv venv
source venv/bin/activate  # Linux/Mac
# hoặc
venv\Scripts\activate     # Windows

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

# 4. Chạy ứng dụng
python app.py

Phương pháp 2: Cài đặt như package

# Cài đặt package ở chế độ development
pip install -e .

# Chạy bằng command line
image-to-text
# hoặc
python -m text_to_image.cli

🎮 Usage

Web Interface

1. Khởi động ứng dụng:

   python app.py

2. Mở trình duyệt và truy cập: http://localhost:7860

3. Sử dụng giao diện:

   • Upload Image: Tải ảnh lên (JPG, PNG, GIF, BMP, TIFF)
   • Caption Settings: Điều chỉnh các thông số:
     • Maximum Caption Length: 10-100 từ (mặc định: 50)
     • Number of Beams: 1-8 (mặc định: 4) - tăng để có caption chính xác hơn
   • Generate Caption: Nhấn nút hoặc tự động khi upload ảnh

Command Line Options

python app.py --help

# Các tùy chọn phổ biến:
python app.py --host 127.0.0.1 --port 8080
python app.py --share                    # Tạo public link
python app.py --force-cpu               # Buộc dùng CPU
python app.py --model custom/model-id   # Sử dụng model khác

📝 Examples

Các loại ảnh phù hợp:

• 📸 Ảnh chụp: Con người, động vật, phong cảnh
• 🎨 Nghệ thuật: Tranh vẽ, illustration, artwork
• 🏙️ Kiến trúc: Tòa nhà, đường phố, nội thất
• 🌸 Thiên nhiên: Hoa, cây cối, phong cảnh tự nhiên
• 🐾 Động vật: Thú cưng, động vật hoang dã

Kết quả mẫu:

• Ảnh chó chạy trên bãi cỏ → "A brown dog running on the grass"
• Ảnh thành phố ban đêm → "A busy street with tall buildings and cars at night"
• Ảnh hoa anh đào → "Pink cherry blossoms on a tree branch"
• Ảnh nội thất → "A modern living room with white furniture"

⚙️ Configuration

Environment Variables

# Buộc sử dụng CPU (không dùng GPU)
export FORCE_CPU=true

# Thay đổi model mặc định (ví dụ model khác cho image captioning)
export DEFAULT_MODEL_ID="Salesforce/blip-image-captioning-base"

Model Storage

• Models được tự động tải và lưu trong thư mục models/
• Lần đầu chạy sẽ tải model (~800MB cho ViT-GPT2), các lần sau sử dụng cached model
• Để xóa cache: rm -rf models/

💻 System Requirements

Component	Minimum	Recommended
Python	3.8+	3.10+
RAM	4GB	8GB+
GPU	Không bắt buộc	NVIDIA GPU 2GB+ VRAM
Storage	5GB trống	10GB+
OS	Windows/Mac/Linux	-

GPU Support

• NVIDIA GPU: Tự động sử dụng CUDA nếu có
• Apple Silicon: Tương thích với MPS backend
• CPU only: Chậm hơn nhưng vẫn hoạt động

🧪 Testing

# Chạy tests
pip install -e ".[dev]"
pytest

# Chạy với coverage
pytest --cov=src/text_to_image --cov-report=html

🛠️ Development

Code Style

# Format code
black src/ tests/
isort src/ tests/

# Linting
flake8 src/ tests/
mypy src/

Project Structure

• src/text_to_image/core/ - Logic tạo caption chính
• src/text_to_image/ui/ - Giao diện người dùng
• src/text_to_image/utils/ - Utilities và configuration
• tests/ - Unit tests
• models/ - Model storage (git-ignored)

📊 Troubleshooting

Lỗi thường gặp:

1. CUDA Out of Memory:

   python app.py --force-cpu

2. Model download fails:

   • Kiểm tra kết nối internet
   • Xóa thư mục models/ và thử lại
   • Thử dùng model khác với --model option

3. Lỗi upload ảnh:

   • Kiểm tra định dạng ảnh (JPG, PNG, GIF, BMP, TIFF)
   • Thử resize ảnh nếu quá lớn

4. Port already in use:

   python app.py --port 8080

5. ImportError:

   pip install -r requirements.txt

📄 License

MIT License - xem file LICENSE để biết thêm chi tiết.

🔗 Model Information

Mô hình sử dụng:

• Primary Model: nlpconnect/vit-gpt2-image-captioning
• Architecture: Vision Transformer (ViT) + GPT-2
• Size: ~800MB
• Language: English captions
• Performance: Balanced speed and accuracy

Alternative Models (có thể thử):

• Salesforce/blip-image-captioning-base - BLIP model, chất lượng cao hơn
• Salesforce/blip-image-captioning-large - Version lớn hơn, chậm hơn nhưng chính xác hơn
• microsoft/git-base-coco - GIT model từ Microsoft

🤝 Contributing