Bài 2: Cài đặt — Claude Code và các công cụ mã nguồn mở

Bài này là phần tốn thời gian nhưng chỉ làm một lần: cài Claude Code (bộ điều phối) và các công cụ mã nguồn mở. Phần lớn thời gian là máy tự tải model. Cách dùng Claude điều phối giúp bước cài nhẹ hơn: chỉ ba môi trường Python, và không cần cài model kiểm tra chất lượng (Claude tự nhìn khung hình để soát).

⚠️ Kiểm tra máy trước: chip Apple Silicon (M1+), 32 GB RAM, ~45 GB ổ trống, macOS 14+. Máy 16 GB RAM thường không đủ cho bước khớp khẩu hình. Nếu máy chưa đạt, vẫn nên đọc để hiểu quy trình.

1. Claude Code

Cài Claude Code theo hướng dẫn cài chính thức của Anthropic (bản chạy trong Terminal). Đây là “bộ não” sẽ viết và chạy lệnh giúp bạn ở các bài sau. Khi làm, bạn mở Claude Code ngay trong thư mục dự án để nó thao tác đúng chỗ.

💡 Từ đây, mỗi khi gặp lỗi, cách xử lý nhanh nhất là dán lỗi cho Claude và nhờ sửa.

2. Công cụ hệ thống

Cài Homebrew nếu chưa có, rồi:

xcode-select --install

brew install uv ffmpeg git

• uv — quản lý môi trường & gói Python (nhanh hơn pip nhiều).
• ffmpeg — xử lý âm thanh/video (ghép, cắt, phụ đề, chuẩn âm lượng, đo nhịp).
• git — tải mã nguồn.

Kiểm tra: uv --version, ffmpeg -version, git --version đều phải ra kết quả.

3. Môi trường mlx-video — tạo hình & video

uv venv .venv --python 3.12

VIRTUAL_ENV=.venv uv pip install "git+https://github.com/Blaizzy/mlx-video.git@87db56a51758fefb748a359b90a5283bb8ba4837" opencv-python soundfile librosa pillow numpy huggingface_hub

📌 Ghim đúng phiên bản. Commit @87db56a... của mlx-video giúp tái lập được — bản mới hơn có thể đổi API và gây lỗi. Nếu muốn, nhờ Claude kiểm bản mới sau.

Tải model (lưu vào models/, giữ đúng tên file):

• Wan2.2-TI2V-5B bản MLX 8-bit (~18 GB) — model tạo video:

.venv/bin/python -c "from huggingface_hub import snapshot_download; snapshot_download('Anes1032/Wan2.2-TI2V-5B-mlx-q8', local_dir='models/wan2.2-mlx')"

• LoRA FastWan (~0,66 GB) — tạo video chỉ 3 bước thay vì 40:

mkdir -p models/loras && curl -L -o models/loras/Wan2_2_5B_FastWanFullAttn_lora_rank_128_bf16.safetensors https://huggingface.co/hum-ma/Wan2.2-TI2V-5B-Turbo-GGUF/resolve/main/Wan2_2_5B_FastWanFullAttn_lora_rank_128_bf16.safetensors

4. Môi trường VieNeu-TTS — giọng đọc tiếng Việt

uv venv .venv-tts --python 3.12

VIRTUAL_ENV=.venv-tts uv pip install vieneu "onnxruntime==1.22.1"

⚠️ Phải ghim onnxruntime==1.22.1. Bản mới hơn báo lỗi “External data path escapes model directory”.

Model VieNeu-TTS tự tải (~0,9 GB) ở lần chạy đầu. Giọng chọn khi chạy (ví dụ Thùy Dung nữ miền Nam, Ngọc Huyền nữ miền Bắc, Hải Đăng nam) — Claude sẽ điền giúp ở Bài 4.

5. Môi trường LatentSync — khớp khẩu hình

Dùng bản 1.5 ở 256px, không dùng 1.6 (512px, ngốn ~18 GB, rất chậm trên máy 32 GB). Bản 1.5 nhanh hơn nhiều, với gương mặt cỡ vừa trong khung thì chất lượng gần như không khác.

Tải mã nguồn LatentSync bản MLX (repo công khai, có sẵn script convert_weights.py và inference.py):

mkdir -p third_party && git clone https://github.com/sb1992/latentsync-mlx.git third_party/latentsync-mlx
git clone https://github.com/bytedance/LatentSync.git third_party/latentsync-mlx/upstream

uv venv .venv-latentsync --python 3.11

VIRTUAL_ENV=.venv-latentsync uv pip install torch torchvision "mlx>=0.31" "numpy<2" opencv-python einops kornia onnxruntime insightface librosa soundfile scipy omegaconf tqdm matplotlib imageio imageio-ffmpeg tiktoken more-itertools huggingface_hub safetensors ffmpeg-python python_speech_features eva-decord diffusers transformers accelerate

Tải trọng số UNet 1.5 (~5 GB) và chuyển sang MLX bằng script có sẵn trong repo (scripts/convert_weights.py — xem README của latentsync-mlx). Bộ nhận diện mặt (~0,6 GB) tự tải ở lần chạy đầu.

Tạo một liên kết (symlink) mà code gốc cần (thiếu nó, chạy khớp khẩu hình sẽ báo lỗi cv2.error ... !_src.empty()):

ln -sfn upstream/latentsync third_party/latentsync-mlx/latentsync

🔧 Nếu gặp lỗi đòi CUDA (bộ nhận diện mặt InsightFace mặc định dùng card NVIDIA): nhờ Claude chuyển provider sang CPU — một sửa đổi nhỏ. Đây đúng là lúc “bộ điều phối Claude” phát huy: bạn dán lỗi, Claude vá.

6. Kiểm tra chất lượng: để Claude nhìn

Bạn không cần cài thêm model kiểm tra chất lượng (như VBench, VLM, nhận diện gương mặt). Vì Claude đọc được ảnh, ở các bước sau Claude sẽ tự mở các khung hình và soát: đồ vật còn trong tay không, có đúng một người không, tay có bình thường không, gương mặt có giống ảnh neo không.

🧩 (Nâng cao, tuỳ chọn) Nếu muốn tự động hoá kiểm tra bằng điểm số máy (VBench, ArcFace…), có thể cài thêm sau — nhưng không bắt buộc cho quy trình cơ bản. Bài 5 dùng cách để Claude nhìn.

7. Kiểm tra cài đặt

Mỗi lệnh in ok là môi trường đó sẵn sàng:

.venv/bin/python -c "import mlx_video, cv2; print('ok .venv')"

.venv-tts/bin/python -c "from vieneu import Vieneu; Vieneu(); print('ok .venv-tts')"

Với LatentSync, chạy thử theo hướng dẫn inference.py trong README của repo (có video/âm thanh mẫu). Nếu ra file kết quả là đạt.

✅ Đạt khi: hai lệnh trên in ok, và LatentSync chạy thử ra file.

🤝 Mẹo: nhờ Claude làm luôn phần kiểm tra: “Chạy các lệnh kiểm tra cài đặt cho từng môi trường và báo cái nào chưa ok.” Claude chạy và tóm tắt kết quả.

8. Lỗi cài đặt hay gặp

Lỗi	Nguyên nhân	Cách xử lý
External data path escapes model directory	onnxruntime quá mới	Cài đúng onnxruntime==1.22.1
No module named 'decord'	decord không có bản Mac ARM	Dùng eva-decord
Đòi CUDA / Device type must be 'cuda'	Model mặc định dùng NVIDIA	Nhờ Claude chuyển sang CPU
Khớp khẩu hình 20–40 phút/cảnh	Thiếu RAM, máy dùng swap	Tắt app nặng (Docker/OrbStack), dùng bản 1.5 (256px)

💡 Mẹo RAM: trước bước khớp khẩu hình, tắt mọi app nặng (đặc biệt Docker/OrbStack giữ 7–8 GB). Thiếu RAM khiến bước này chậm gấp 5–10 lần.

🧪 Tự kiểm tra

1. Bốn nhóm cần cài là gì?
2. Vì sao cách dùng Claude điều phối không cần cài model kiểm tra chất lượng?
3. Gặp lỗi đòi CUDA thì làm gì?

Tóm lại

Cài đặt gồm: Claude Code (bộ điều phối), công cụ hệ thống (uv, ffmpeg, git), ba môi trường Python (mlx-video, VieNeu-TTS, LatentSync) và tải model (~25 GB). Nhờ để Claude nhìn khung hình làm QC, bạn bớt được cả một môi trường và nhiều model so với cách tự động hoàn toàn. Mẹo quan trọng: ghim đúng vài phiên bản, dùng LatentSync 1.5/256px, tắt app nặng trước khâu khớp khẩu hình, và dán mọi lỗi cho Claude để nó vá. Khi các lệnh kiểm tra in ok, bạn đã sẵn sàng. Bài sau: mô tả ý muốn để Claude viết kịch bản.