Hướng dẫn AI

Huấn luyện LoRA MiniMax H3 Ref2VA trên Google Colab

Hướng dẫn này giải thích cách cài đặt skill Codex, tuyển chọn ảnh mục tiêu và ảnh tham chiếu, tạo chú thích và cặp ảnh có thể tái lập, chạy huấn luyện LoRA MiniMax H3 Ref2VA bằng Ostris AI Toolkit trên Google Colab, rồi tải xuống adapter safetensors thu được.

29 tháng 9, 2026Thời gian đọc khoảng 22 phút

Huấn luyện LoRA MiniMax H3 Ref2VA trên Google Colab

Dự án này làm gì

MiniMax H3 Ref2VA LoRA Colab Skill là một skill Codex có thể cài đặt để chuẩn bị các bộ dữ liệu hình ảnh ghép cặp và huấn luyện MiniMax H3 Ref2VA LoRA trên Google Colab. Trình chạy sắp xếp hình ảnh cục bộ, đóng gói bộ dữ liệu, khởi động notebook Colab đi kèm, lưu checkpoint và các tệp đầu ra của phiên chạy vào Google Drive, đồng thời tải adapter .safetensors cuối cùng về máy tính của bạn.

Quy trình này được thiết kế riêng cho transformer MiniMax H3. H3 sử dụng Qwen3-VL trong pipeline hiểu hình ảnh, nhưng Qwen Image là một mô hình riêng biệt. LoRA Qwen Image không tương thích với adapter H3.

Tính năng chính

Tạo các bộ dữ liệu hình ảnh ghép cặp gồm hình ảnh đích và hình ảnh tham chiếu/điều khiển.
Sử dụng các tệp chú thích có cùng tên cơ sở khi có sẵn.
Hỗ trợ kế hoạch bộ dữ liệu JSON để tái lập chú thích và lựa chọn hình ảnh tham chiếu.
Chạy huấn luyện MiniMax H3 Ref2VA LoRA thông qua Ostris AI Toolkit trên Google Colab.
Hỗ trợ cấu hình số bước huấn luyện, hạng LoRA, alpha, tốc độ học, loại GPU và yêu cầu bộ nhớ cao.
Đồng bộ checkpoint, mẫu, cấu hình và bản tóm tắt phiên chạy vào Google Drive.
Tải adapter .safetensors cuối cùng vào thư mục đầu ra cục bộ.
Cung cấp các lệnh kiểm tra dung lượng compute Colab và kiểm thử kết nối với runtime từ xa.

Điều kiện tiên quyết

Trước khi cài đặt skill, hãy đảm bảo hệ thống cục bộ của bạn có:

Python 3.10 trở lên.
Đã cài đặt và xác thực Google Colab CLI trước khi chạy các lệnh từ xa.
Tài khoản Colab có thể truy cập phần cứng GPU.
Quyền truy cập vào mô hình H3 cần thiết và các tài sản adapter huấn luyện, bao gồm việc chấp nhận mọi giấy phép áp dụng.
Đủ dung lượng compute Colab cho phiên huấn luyện dự kiến.

Notebook đi kèm kiểm tra ít nhất 60 GiB dung lượng đĩa trống và cảnh báo khi VRAM GPU dưới 48 GiB. Dự án khuyến nghị A100 bộ nhớ cao, mặc dù không có đảm bảo chính thức về VRAM tối thiểu.

Cài đặt Codex Skill

Sao chép repository và chạy trình cài đặt:

git clone https://github.com/killkli/minimax-h3-lora-colab-skill.git
cd minimax-h3-lora-colab-skill
./install.sh

Khi CODEX_HOME được thiết lập, trình cài đặt đặt skill vào $CODEX_HOME/skills. Nếu không, trình cài đặt sử dụng ~/.codex/skills.

Để cài đặt vào một thư mục skills khác, hãy cung cấp --dest:

./install.sh --dest /path/to/skills

Những bản cài đặt hiện có được giữ lại theo mặc định. Nếu bạn cố ý muốn thay thế một bản cài đặt, hãy sử dụng --force. Trình cài đặt di chuyển bản sao trước đó vào một bản sao lưu có dấu thời gian thay vì âm thầm xóa bản đó.

Xác minh cài đặt

Hiển thị trợ giúp của trình chạy mà không khởi chạy tác vụ Colab:

python3 ~/.codex/skills/minimax-h3-lora-colab/scripts/runner.py --help

Nếu CODEX_HOME được cấu hình, hãy thay ~/.codex/skills bằng $CODEX_HOME/skills. Việc cài đặt cục bộ và kiểm tra trợ giúp không khởi động huấn luyện hoặc tiêu tốn thời gian GPU Colab.

Chuẩn bị hình ảnh huấn luyện

Đặt ảnh đích vào một thư mục. Các ảnh này nên hiển thị cùng một người hoặc chủ thể. Bạn có thể thêm chú thích tùy chọn dưới dạng các tệp văn bản có tên cơ sở tương ứng. Ví dụ, photo01.jpg có thể có chú thích trong photo01.txt.

Từ repository đã sao chép, hãy chuẩn bị bộ dữ liệu bằng:

python3 scripts/runner.py prepare \
  --input-dir /path/to/target_photos \
  --name studio_subject \
  --trigger "studio_subject person" \
  --output-dir ./prepared_dataset

Thư mục đã chuẩn bị gồm:

prepared_dataset/
├── targets/
├── references/
└── dataset_manifest.json

targets/ chứa các hình ảnh đích và tệp chú thích có cùng tên cơ sở.
references/ chứa hình ảnh tham chiếu hoặc điều khiển với tên cơ sở tương ứng với hình ảnh đích.
dataset_manifest.json ghi lại nguồn, hình ảnh đích, hình ảnh tham chiếu và chú thích cho từng mẫu.

Việc chuẩn bị bộ dữ liệu được thực hiện cục bộ. Tác vụ này sao chép ảnh gốc vào bộ dữ liệu đã chuẩn bị nhưng không tải chúng lên Colab.

Tự động chọn hình ảnh tham chiếu

Nếu bạn không cung cấp thư mục tham chiếu riêng, trình chạy cần ít nhất hai ảnh đích. Trình chạy luân phiên qua các ảnh đó để tạo các cặp tham chiếu.

Khi có thể, hãy sử dụng các góc nhìn đa dạng và hữu ích của cùng một chủ thể. Hình ảnh đích không nên sử dụng chính nó làm hình ảnh tham chiếu.

Sử dụng thư mục tham chiếu riêng

Để chọn hình ảnh tham chiếu từ một thư mục khác, hãy thêm --reference-dir:

python3 scripts/runner.py prepare \
  --input-dir /path/to/target_photos \
  --reference-dir /path/to/reference_photos \
  --name studio_subject \
  --trigger "studio_subject person" \
  --output-dir ./prepared_dataset

Mọi hình ảnh tham chiếu được chọn phải thể hiện cùng chủ thể với tập hình ảnh đích. Nếu bạn chỉ tuyển chọn một phần của bộ sưu tập lớn hơn, hãy đặt các hình ảnh đích và tham chiếu đã chọn vào các thư mục trung gian, đồng thời giữ nguyên bộ sưu tập hình ảnh gốc.

Tạo kế hoạch bộ dữ liệu có thể tái lập

Kế hoạch bộ dữ liệu ghi lại chú thích riêng cho từng hình ảnh và các lựa chọn đích đến tham chiếu tùy chọn. Điều này giúp việc tuyển chọn thủ công hoặc có sự hỗ trợ của agent có thể tái lập.

{
  "captions": {
    "photo01.jpg": "studio_subject person, chân dung nửa người mặc áo khoác xanh, ngoài trời dưới ánh sáng ban ngày dịu",
    "photo02.jpg": "studio_subject person, chân dung nghiêng mặc áo sơ mi trắng, trong nhà cạnh cửa sổ"
  },
  "references": {
    "photo01.jpg": "front_reference.png",
    "photo02.jpg": "side_reference.png"
  }
}

Đối tượng captions phải bao gồm basename của mọi ảnh đích. Nếu có đối tượng tùy chọn references, đối tượng này cũng phải ánh xạ mọi basename đích tới một basename ảnh trong thư mục tham chiếu ứng viên.

Chú thích chỉ nên mô tả các chi tiết có thể nhìn thấy. Giữ những người hoặc chủ thể không liên quan trong các tập dữ liệu riêng biệt và không ánh xạ ảnh đích với chính nó.

Chuẩn bị tập dữ liệu theo kế hoạch:

python3 scripts/runner.py prepare \
  --input-dir /path/to/target_photos \
  --reference-dir /path/to/reference_photos \
  --dataset-plan /path/to/dataset-plan.json \
  --name studio_subject \
  --trigger "studio_subject person" \
  --output-dir ./prepared_dataset

Nếu bỏ qua --dataset-plan, runner sẽ sử dụng các chú thích sidecar hiện có và cung cấp giá trị mặc định đơn giản cho những chú thích bị thiếu.

Kiểm tra trước khi tải lên

Mở dataset_manifest.json trước khi huấn luyện và kiểm tra từng nguồn, ảnh đích, ảnh tham chiếu cùng chú thích. Đây là thời điểm tốt nhất để phát hiện các cặp không chính xác, mô tả bị thiếu hoặc ảnh thuộc về một chủ thể khác. Huấn luyện là bước tải các ảnh đã chuẩn bị lên môi trường chạy Colab.

Huấn luyện LoRA trên Google Colab

Sau khi kiểm tra tập dữ liệu đã chuẩn bị, hãy bắt đầu một lượt huấn luyện:

python3 scripts/runner.py train \
  --dataset-dir ./prepared_dataset \
  --name studio_subject \
  --trigger "studio_subject person" \
  --steps 1000 \
  --rank 16 \
  --alpha 16 \
  --gpu A100 \
  --output-dir ./outputs

Các thiết lập huấn luyện mặc định là:

1.000 bước huấn luyện.
Hạng LoRA 16.
Alpha 16.
Tốc độ học 1e-4.
Phiên Colab A100 có bộ nhớ cao.

Notebook sẽ tải xuống mô hình H3 và các tài sản bộ điều hợp cần thiết cho việc huấn luyện. Bộ điều hợp cuối cùng được đặt trong ./outputs/ dưới dạng tệp .safetensors.

Các tạo tác của lượt chạy cũng được đồng bộ tới:

MyDrive/MiniMax_H3_LoRAs/<name>/<run-id>/

Thư mục Drive bao gồm các checkpoint, mẫu được tạo, dữ liệu cấu hình và bản tóm tắt lượt chạy.

Thay đổi tham số huấn luyện một cách cẩn thận

Bạn có thể thay thế các giá trị ví dụ cho steps, rank, alpha, GPU và thư mục đầu ra. Để xem tất cả tùy chọn huấn luyện được hỗ trợ, hãy chạy:

python3 scripts/runner.py train --help

Chế độ bộ nhớ cao được yêu cầu theo mặc định. Chỉ thêm --no-high-mem khi phân bổ GPU Colab đã chọn không nên sử dụng yêu cầu này.

Kiểm tra mức sử dụng và kết nối Colab

Để đọc hạn mức tính toán Colab hiện tại ở dạng JSON, hãy sử dụng:

python3 scripts/runner.py usage --json

Để cấp phát môi trường GPU từ xa và xác minh quá trình thăm dò, truyền tệp cũng như đường dẫn Google Drive, hãy chạy:

python3 scripts/runner.py test

Lệnh test không phải là bước xác thực quá trình huấn luyện. Lệnh này không chứng minh rằng quá trình huấn luyện MiniMax H3 sẽ phù hợp với VRAM hiện có hoặc hoàn tất thành công.

Mẹo nâng cao và hướng dẫn vận hành

Giữ tập chủ thể tập trung

Sử dụng ảnh của một người hoặc một chủ thể cho mỗi tập dữ liệu. Việc tách các chủ thể không liên quan giúp chú thích và ánh xạ tham chiếu rõ ràng hơn, đồng thời tuân theo quy trình mà runner yêu cầu.

Sử dụng chú thích riêng cho từng ảnh

Thay vì chỉ dựa vào chú thích chung, hãy mô tả các thuộc tính có thể nhìn thấy như tư thế, trang phục, khung hình, môi trường và ánh sáng. Luôn đưa trigger đã chọn vào một cách nhất quán, nhưng tránh thêm những chi tiết không thể nhìn thấy trong ảnh.

Ưu tiên sự đa dạng tham chiếu hữu ích

Chọn các ảnh tham chiếu cung cấp góc nhìn đa dạng nhưng vẫn mô tả cùng một chủ thể. Ví dụ, ghép góc nhìn chính diện và góc nghiêng khi phù hợp. Không bao giờ ghép ảnh đích với chính nó.

Duy trì hồ sơ có thể kiểm tra

Giữ kế hoạch tập dữ liệu và manifest được tạo cùng với dự án. Hai tệp này cùng ghi lại các chú thích và cặp ảnh được sử dụng cho một lượt chạy, đồng thời giúp kiểm tra hoặc lặp lại quy trình chuẩn bị dễ dàng hơn.

Theo dõi đầu ra cục bộ và đám mây

Thư mục đầu ra cục bộ chứa bộ điều hợp cuối cùng đã tải xuống, trong khi Google Drive lưu giữ các tạo tác rộng hơn của lượt chạy. Sử dụng bản sao trên Drive để kiểm tra checkpoint, mẫu, cấu hình và bản tóm tắt lượt chạy nếu một lượt huấn luyện dừng bất ngờ.

Hiểu rằng khả năng tương thích phần cứng phụ thuộc thời gian chạy

A100 có bộ nhớ cao được khuyến nghị không đảm bảo thành công. Khả năng đáp ứng bộ nhớ thực tế phụ thuộc vào môi trường chạy Colab và cấu hình huấn luyện. Notebook cảnh báo khi VRAM dưới 48 GiB và kiểm tra 60 GiB dung lượng đĩa trống, nhưng các kiểm tra này không phải là bảo đảm phần cứng chính thức.

Hiểu trạng thái xác thực

Cấu hình ví dụ Ref2VA của AI Toolkit upstream được đánh dấu là chưa xác minh. Do đó, repository không tuyên bố rằng mọi lượt huấn luyện trên đám mây sẽ thành công. Notebook ghim commit mã nguồn AI Toolkit đã kiểm tra để tăng khả năng tái lập, nhưng việc cài đặt thành công hoặc thăm dò từ xa không nên được hiểu là bằng chứng cho việc hoàn tất huấn luyện đầu cuối.

Đọc thêm

Kết luận

MiniMax H3 Ref2VA LoRA Colab Skill cung cấp quy trình có thể lặp lại, từ tuyển chọn hình ảnh cục bộ đến adapter H3 có thể tải xuống. Chuẩn bị và xem xét các cặp hình ảnh mục tiêu-tham chiếu cục bộ, sử dụng kế hoạch tập dữ liệu khi cần chú thích và ánh xạ có thể tái tạo, xác nhận tài nguyên và giấy phép Colab, rồi bắt đầu huấn luyện. Hãy nhớ rằng cấu hình upstream vẫn chưa được xác minh và Qwen Image LoRA không thể thay thế cho adapter MiniMax H3.