local_setup_guide.md

Hướng dẫn Chạy Local - UI-VieNeu Backend

Tài liệu này ghi lại toàn bộ các bước để thiết lập và chạy dự án Video Subtitle & AI Voiceover ở môi trường máy tính cá nhân (Windows).

1. Cài đặt Công cụ Quản lý (uv)

Nếu máy bạn chưa có uv, hãy mở PowerShell và chạy lệnh sau:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Thiết lập Môi trường và Thư viện

Di chuyển vào thư mục dự án và cài bộ thư viện:

# Cài đặt toàn bộ thư viện từ pyproject.toml vào thư mục .venv
uv sync

3. Khởi động Máy chủ Redis (Memurai)

Dự án cần Redis để làm "bưu điện" chuyển tin nhắn cho Celery.

• Bước 1: Mở VSCode bằng quyền Administrator.
• Bước 2: Chạy lệnh bật dịch vụ:

Start-Service Memurai

(Kiểm tra màu xanh trong RedisInsight để chắc chắn đã bật thành công)

4. Chạy Hệ thống (Cần mở 2 Terminal song song)

Terminal 1: Chạy Celery Worker (Xử lý AI & FFmpeg)

Sử dụng uv run để đảm bảo dùng đúng thư viện trong môi trường ảo:

uv run celery -A worker worker --loglevel=info -P solo

Lưu ý: Tham số -P solo là bắt buộc để Celery có thể chạy được trên hệ điều hành Windows.

Terminal 2: Chạy FastAPI Server (Cổng kết nối API)

uv run uvicorn main:app --reload

• API sẽ chạy tại: http://127.0.0.1:8000
• Tài liệu API (Swagger UI): http://127.0.0.1:8000/docs

---

Các lỗi thường gặp và cách xử lý

1. ModuleNotFoundError: Hãy chắc chắn bạn luôn có chữ uv run ở đầu lệnh để nó nhận diện được thư viện trong .venv.
2. ConnectionError (Redis): Kiểm tra xem Memurai đã được Start chưa.
3. Permission Denied: Luôn chạy Terminal/VSCode với quyền Administrator khi can thiệp vào các Service như Memurai.