README.md

---
title: Real Estate Formatter
emoji: 🏠
colorFrom: indigo
colorTo: pink
sdk: gradio
sdk_version: 6.5.1
app_file: app.py
pinned: false
---

# 🏠 Real Estate Description Formatter

API sử dụng AI models nhẹ từ HuggingFace để format mô tả bất động sản từ dạng "xấu" (không cấu trúc) sang dạng HTML đẹp mắt với CSS inline.

## 🎯 Tính năng

- **Format tự động**: Chuyển đổi mô tả BDS xấu thành HTML được styling đẹp
- **Giữ nguyên nội dung**: Không thay đổi text gốc, chỉ thêm HTML/CSS
- **AI nhẹ & nhanh**: Sử dụng Small Language Models (1.7B params)
- **Free & Open-source**: Hoàn toàn miễn phí sử dụng

## 🤖 AI Models được sử dụng

Dự án hỗ trợ các model mạnh và miễn phí từ HuggingFace:

- **Qwen2.5-7B-Instruct** (mặc định) - 7B params, hỗ trợ tiếng Việt, instruction-tuned
- **Mistral-7B-Instruct-v0.3** - 7B params, outperforms Llama 2 13B
- **Gemma-2-7B-IT** - 7B params, Google, chat-optimized

### Models nhẹ hơn (nếu cần tiết kiệm tài nguyên):
- **Qwen2.5-3B-Instruct** - 3B params, cân bằng tốt
- **Phi-4-mini-instruct** - 3.8B params, Microsoft, reasoning tốt

Bạn có thể thay đổi model bằng biến môi trường `MODEL_NAME`.

## 📋 Ví dụ

**Input (form xấu):**
```
NHÀ 2 TẦNG HẺM OTO LIÊN HOA VĨNH NGỌC - TÂY NHA TRANG- Diện tích 92m² full ONT- Hướng Đông Bắc- Pháp lý sổ hồng hoàn công. Hẻm betong rộng 3m- Kết cấu 1 trệt 1 lầu với 4Pn, 2wc, bếp, p.khách, p.thờ, sân để xe ô tô... Full nội thất như hình..- Khu dân cư đông đúc, cách Bệnh viện Sài Gòn Nha Trang 450m, gần siêu thị Big C Go 700m.G.iá bán 4tỷ5 ( thương lượng )0905 124 ***
```

**Output (HTML đẹp):**
```html
<div class="property-card" style="background: linear-gradient(135deg, #f5f7fa 0%, #c3cfe2 100%); border-radius: 12px; padding: 24px; box-shadow: 0 4px 6px rgba(0,0,0,0.1);">
  <h1 class="title" style="color: #2c3e50; font-size: 24px; text-transform: uppercase; margin-bottom: 16px;">
    NHÀ 2 TẦNG HẺM OTO LIÊN HOA VĨNH NGỌC - TÂY NHA TRANG
  </h1>

  <div class="specs" style="display: flex; gap: 10px; flex-wrap: wrap; margin-bottom: 16px;">
    <span style="background: #3498db; color: white; padding: 6px 12px; border-radius: 20px; font-size: 14px;">
      92m²
    </span>
    <span style="background: #2ecc71; color: white; padding: 6px 12px; border-radius: 20px; font-size: 14px;">
      Đông Bắc
    </span>
    <span style="background: #9b59b6; color: white; padding: 6px 12px; border-radius: 20px; font-size: 14px;">
      Sổ hồng hoàn công
    </span>
  </div>

  <div class="description" style="background: white; padding: 16px; border-radius: 8px; margin-bottom: 16px;">
    <p style="margin-bottom: 8px;">Hẻm betong rộng 3m</p>
    <p style="margin-bottom: 8px;">Kết cấu: 1 trệt 1 lầu</p>
    <p style="margin-bottom: 8px;">4 <span title="Phòng ngủ">Pn</span>, 2 <span title="WC">wc</span>, bếp, phòng khách, phòng thờ, sân để xe ô tô</p>
    <p>Full nội thất</p>
  </div>

  <div class="location" style="background: #ecf0f1; padding: 16px; border-radius: 8px; margin-bottom: 16px;">
    <p style="margin-bottom: 8px;"><strong>Khu dân cư đông đúc</strong></p>
    <p style="margin-bottom: 8px;">Cách Bệnh viện Sài Gòn Nha Trang 450m</p>
    <p>Gần siêu thị Big C Go 700m</p>
  </div>

  <div class="price" style="background: linear-gradient(135deg, #f093fb 0%, #f5576c 100%); color: white; padding: 16px; border-radius: 8px; text-align: center; margin-bottom: 16px;">
    <p style="font-size: 28px; font-weight: bold; margin: 0;">4 tỷ 500 triệu</p>
    <p style="font-size: 14px; margin: 4px 0 0 0;">(Thương lượng)</p>
  </div>

  <div class="contact" style="text-align: center;">
    <p style="font-size: 18px; font-weight: bold; color: #2c3e50;">0905 124 ***</p>
  </div>
</div>
```

## 🚀 Cài đặt & Chạy

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

### 2. Chạy server
```bash
python app.py
```

Server sẽ chạy tại: `http://0.0.0.0:7860`

### 3. Sử dụng API

**Endpoint:** `POST /format`

**Request:**
```json
{
  "description": "NHÀ 2 TẦNG HẺM OTO LIÊN HOA VĨNH NGỌC..."
}
```

**Response:**
```json
{
  "original": "NHÀ 2 TẦNG HẺM OTO...",
  "formatted_html": "<div class=\"property-card\">...</div>",
  "success": true,
  "error": null
}
```

### 4. Test với cURL
```bash
curl -X POST "http://localhost:7860/format" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "NHÀ 2 TẦNG HẺM OTO LIÊN HOA VĨNH NGỌC - TÂY NHA TRANG- Diện tích 92m² full ONT- Hướng Đông Bắc- Pháp lý sổ hồng hoàn công..."
  }'
```

## ⚙️ Cấu hình

### Thay đổi model AI
Sử dụng biến môi trường `MODEL_NAME`:

```bash
# Model mặc định - Qwen2.5-7B-Instruct (khuyên dùng cho tiếng Việt)
python app.py

# Sử dụng Mistral-7B (mạnh, nhanh)
export MODEL_NAME="mistralai/Mistral-7B-Instruct-v0.3"
python app.py

# Sử dụng Gemma-2-7B (Google)
export MODEL_NAME="google/gemma-2-7b-it"
python app.py

# Sử dụng model nhẹ hơn nếu cần (3B params)
export MODEL_NAME="Qwen/Qwen2.5-3B-Instruct"
python app.py
```

### Sử dụng HuggingFace Token (cho private models)
```bash
export HF_TOKEN="your_huggingface_token"
python app.py
```

## 📚 API Documentation

Sau khi chạy server, truy cập:
- Swagger UI: `http://localhost:7860/docs`
- ReDoc: `http://localhost:7860/redoc`

## 🎨 Prompt Engineering

Prompt được thiết kế phức tạp để:
- ✅ Giữ nguyên nội dung text gốc
- ✅ Phân tích và nhận diện các thành phần (tiêu đề, specs, giá, liên hệ...)
- ✅ Thêm CSS inline với màu sắc hiện đại
- ✅ Xử lý viết tắt với tooltip
- ✅ Output HTML thuần, không kèm markdown

## 🌐 Deploy lên HuggingFace Spaces

1. Tạo Space mới trên HuggingFace
2. Chọn SDK: **Gradio** hoặc **Docker**
3. Upload code và đợi build
4. Truy cập URL của Space

## 📖 Tài liệu tham khảo

**AI Models:**
- [Qwen2.5-7B-Instruct](https://huggingface.co/Qwen/Qwen2.5-7B-Instruct) - Model mặc định, hỗ trợ tiếng Việt
- [10 Best Open-Source LLM Models 2025](https://huggingface.co/blog/daya-shankar/open-source-llms)
- [Open LLM Leaderboard](https://huggingface.co/collections/open-llm-leaderboard/open-llm-leaderboard-best-models)
- [HuggingFace Text Generation Models](https://huggingface.co/models?pipeline_tag=text-generation)
- [Best Open Source LLMs of 2025](https://klu.ai/blog/open-source-llm-models)

## 📝 License

MIT License - Free to use

## 👨‍💻 Author

Created with ❤️ using Claude Code