📋 Thông tin sinh viên

Thông tin	Chi tiết
Họ tên	Nguyễn Duy Hào
MSSV	24120306
Lớp	24CTT5
Môn học	Tư Duy Tính Toán

---

🧠 Mô hình AI

• Tên mô hình: Salesforce/blip-vqa-base
• Hugging Face: https://huggingface.co/Salesforce/blip-vqa-base

---

📝 Mô tả

Hệ thống cho phép người dùng gửi ảnh kèm câu hỏi, mô hình AI sẽ phân tích ảnh và trả lời câu hỏi bằng ngôn ngữ tự nhiên (Visual Question Answering). Có thể để trống phần câu hỏi. Mô hình hiện tại chỉ hỗ trợ tiếng Anh.

Ví dụ: Gửi ảnh một con mèo + câu hỏi "What animal is this?" → AI trả lời "cat".

Hệ thống gồm 2 thành phần:

Thành phần	Mô tả
Server (Colab)	Chạy model AI trên Google Colab, expose API qua Cloudflare Tunnel
Client CLI	Ứng dụng dòng lệnh Python để gọi API

---

📁 Cấu trúc dự án

Image_Caption_API/
├── client/                  # Module client
│   ├── __init__.py
│   ├── config.py            # Quản lý biến môi trường
│   ├── api.py               # HTTP client gọi server AI
│   ├── validators.py        # Kiểm tra đường dẫn & định dạng ảnh
│   └── cli_app.py           # Giao diện dòng lệnh (CLI)
├── notebooks/
│   └── run_model_image_vqa.ipynb  # Notebook chạy server trên Colab
├── cli.py                   # Entry point chạy CLI
├── test_model.py            # Script test nhanh các endpoint
├── .env.example             # Template biến môi trường
├── requirements.txt         # Danh sách thư viện Python
└── README.md

---

⚙️ Hướng dẫn cài đặt

1. Clone dự án

git clone https://github.com/NguyenDuyHao-cheems/Image_Caption_API.git
cd Image_Caption_API

2. Tạo môi trường ảo

python -m venv .venv

Kích hoạt:

• Windows:

  .venv\Scripts\activate

• macOS/Linux:

  source .venv/bin/activate

3. Cài thư viện

pip install -r requirements.txt

4. Cấu hình biến môi trường

cp .env.example .env

Mở file .env và thay URL bằng địa chỉ server đang chạy:

API_URL=https://your-server-url.trycloudflare.com

Lưu ý: URL này lấy từ output khi chạy notebook trên Google Colab (xem bước tiếp theo).

---

🚀 Hướng dẫn chạy

Bước 1: Khởi động server AI trên Google Colab

1. Mở file notebooks/run_model_image_vqa.ipynb trên Google Colab
2. Chạy tất cả các cell
3. Copy URL Cloudflare Tunnel được tạo ra (dạng https://xxx.trycloudflare.com)
4. Dán URL vào file .env

Bước 2: Chạy Client

Cách 1 — CLI tương tác:

python cli.py

Chương trình sẽ hỏi bạn nhập đường dẫn ảnh và câu hỏi, sau đó trả kết quả từ AI.

Cách 2 — Test nhanh:

python test_model.py

Tự động test 3 endpoint: /, /health, /predict.

---

📡 Hướng dẫn gọi API

Server cung cấp 3 endpoint:

GET / — Kiểm tra server

curl https://your-server-url.trycloudflare.com/

Response:

{"message": "API có khả năng đọc và trả lời các câu hỏi liên quan đến ảnh đầu vào"}

GET /health — Kiểm tra sức khỏe

curl https://your-server-url.trycloudflare.com/health

Response:

{"status": "Hệ thống hoạt động bình thường"}

POST /predict — Hỏi AI về ảnh

Parameters

Field	Type	Required	Description
file	File	Yes	Hỗ trợ định dạng: JPG, PNG, WebP).
query	String	Yes	Câu hỏi muốn hỏi về bức ảnh.
Gửi ảnh kèm câu hỏi:

curl -X POST https://your-server-url.trycloudflare.com/predict \
  -F "file=@/path/to/your/test_image.jpg" \
  -F "query=What color is the shirt?"

Response:

{"answer": "blue"}

Ví dụ gọi bằng Python

import requests

url = "https://your-server-url.trycloudflare.com/predict"

with open("test_image.jpg", "rb") as f:
    response = requests.post(
        url,
        files={"file": ("test_image.jpg", f, "image/jpeg")},
        data={"query": "What is in this image?"}
    )

print(response.json())
# {"answer": "a cat sitting on a couch"}

Demo

demo_api.mp4

Phân mục video

• 0-17: giới thiệu mô hình
• 0:17 - 1:18 => mô tả source code
• 1:18 - 1:53 -> chạy server trên gg colab
• 1:53 - 3:40 -> chạy test_model
• 3:40 - hết -> chạy command line