Tạo video clip từ văn bản và hình ảnh bằng MiniMax H3 trên Apple Silicon với TensorFold

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

Kho lưu trữ này đóng gói mô hình video MiniMax H3 cho TensorFold trên Apple Silicon. Dự án kết hợp dòng H3 của TensorFold với các kernel Metal int8 của MLX và bộ chuyển đổi LightX2V Turbo để tạo video có âm thanh stereo đồng bộ.

Gói này hỗ trợ cả chuyển văn bản thành video và, kể từ phiên bản 1.1, chuyển hình ảnh thành video bằng cách sử dụng khung hình đầu tiên được cung cấp. Trên Mac Studio M5 Ultra có bộ nhớ 256 GB trong phép đo, một đoạn video 864x480 dài 5 giây mất khoảng 50 giây với bộ chuyển đổi Turbo. Đoạn video 768x448 mất khoảng 40 giây theo các điều kiện benchmark được ghi trong tài liệu.

Kho lưu trữ này là một quy trình kết xuất dành cho phát triển, không phải máy chủ hay sản phẩm. Không có lệnh tensorfold generate; mô hình được tải lại cho mỗi lần kết xuất thông qua các tập lệnh đi kèm.

Tính năng chính

• Chuyển văn bản thành video: mô tả một cảnh và tạo tệp MP4 có video cùng âm thanh stereo.
• Chuyển hình ảnh thành video: cung cấp khung hình đầu tiên và mô tả diễn biến tiếp theo.
• Tạo video Turbo: bộ chuyển đổi LightX2V giảm quy trình kết xuất xuống còn ba lượt truyền trong đường dẫn nhanh được ghi trong tài liệu.
• Kernel MLX và int8: các thao tác transformer và decoder được chọn sử dụng kernel Metal int8 trên phần cứng tensor M5 tương thích.
• Thiết lập có thể tái lập: trình cài đặt cố định phiên bản TensorFold, MLX, các thư viện hỗ trợ, bản sửa đổi mô hình và checksum của bộ chuyển đổi.
• Kết xuất mô hình cơ sở tùy chọn: tắt bộ chuyển đổi và sử dụng khoảng 20 bước lấy mẫu khi muốn kết quả gần với mô hình cơ sở hơn.

Yêu cầu phần cứng và phần mềm

Các số liệu hiệu năng được công bố được đo trên Mac Studio M5 Ultra với 256 GB bộ nhớ hợp nhất, chạy macOS 27.0.1. Dự án ghi rõ cần ít nhất 128 GB bộ nhớ, trong khi quá trình hợp nhất bộ chuyển đổi có thể đạt mức sử dụng bộ nhớ tối đa khoảng 103 GB. Khi không dùng bộ chuyển đổi, mức sử dụng bộ nhớ tối đa được ghi nhận là khoảng 65 GB.

Các kernel int8 yêu cầu thao tác tensor Metal 4, vì vậy khả năng tăng tốc được báo cáo dành cho phần cứng M5 tương thích. Trên các hệ thống không hỗ trợ những thao tác này, dòng H3 chạy ở bfloat16 và có thể chậm hơn các phương án dựa trên C được mô tả trong README.

Bạn cũng cần Homebrew, Python 3.11, uv và FFmpeg. Bản tải xuống mô hình MiniMax H3 có dung lượng khoảng 144 GB, còn bộ chuyển đổi Turbo có dung lượng khoảng 1.96 GB.

Cài đặt dự án

Clone kho lưu trữ và cài đặt các công cụ máy chủ cần thiết:

git clone https://github.com/drowzeys/keys-Mac-TensorFold-MiniMax-H3-MLX.git
cd keys-Mac-TensorFold-MiniMax-H3-MLX
brew install python@3.11 uv ffmpeg

Chạy tập lệnh thiết lập một lần:

bash oneshot-setup.sh

Trình cài đặt tạo một môi trường tách biệt tại ~/.local/opt/tensorfold-h3 và cài đặt TensorFold 0.6.5 cùng dòng H3 và tệp khóa dependency cố định. Khi Docker khả dụng, trình cài đặt có thể lấy payload TensorFold đã xác minh checksum từ carrier dựng sẵn GHCR của dự án; nếu không, trình cài đặt sẽ lấy commit mã nguồn tương ứng từ Git.

Quá trình thiết lập cũng clone bản sửa đổi minimax-h3-mlx cần thiết, tải phân vùng MiniMax H3 FL2VA vào ~/h3-models/MiniMax-H3, tải bộ chuyển đổi Turbo và kết xuất một đoạn video thử nghiệm vào outputs/test.mp4.

Để kiểm tra một bản cài đặt hiện có mà không cài đặt lại, hãy chạy:

bash oneshot-setup.sh --verify

Để bỏ qua lần kết xuất thử nghiệm ban đầu, hãy dùng:

bash oneshot-setup.sh --no-render

Bạn có thể thay đổi vị trí cài đặt và vị trí mô hình mặc định thông qua các biến môi trường PREFIX và H3_MODEL_DIR.

Tạo đoạn video từ văn bản

Sử dụng scripts/generate.sh với prompt và tên tệp đầu ra:

bash scripts/generate.sh "Một chú chim ruồi lơ lửng trên những bông hoa đỏ, tiếng cánh vỗ nhẹ" out.mp4

Đường dẫn mặc định sử dụng bộ chuyển đổi Turbo đã cấu hình và các thiết lập tạo video mặc định của kho lưu trữ. Prompt mô tả cả cảnh quay và, khi cần, âm thanh mong muốn.

Để tạo một biến thể xác định, hãy cung cấp seed và chọn canvas được hỗ trợ:

WIDTH=768 HEIGHT=448 SEED=7 bash scripts/generate.sh "Một đoàn tàu yên tĩnh băng qua thung lũng phủ tuyết lúc bình minh" out.mp4

Bạn có thể lưu prompt trong một tệp văn bản. Khi đó, hãy truyền một đối số prompt trống và đặt PROMPT_FILE:

PROMPT_FILE=prompts/black-mirror-scene.txt SEED=2077 bash scripts/generate.sh "" out.mp4

Tạo đoạn video từ hình ảnh

Đặt FIRST_FRAME thành một tệp hình ảnh. Hình ảnh sẽ trở thành khung hình đầu tiên, còn prompt giải thích chuyển động hoặc sự kiện tiếp theo:

FIRST_FRAME=photo.jpg WIDTH=1344 HEIGHT=768 bash scripts/generate.sh "Cô ấy quay về phía máy quay và mỉm cười" out.mp4

Hình ảnh được kéo giãn theo canvas đã chọn, vì vậy hãy chọn kích thước có tỷ lệ khung hình tương ứng hoặc cắt hình ảnh trước khi kết xuất. README khuyến nghị 1344x768 cho tỷ lệ 16:9, 768x1344 cho 9:16 và 768x768 cho nội dung hình vuông.

Prompt chuyển hình ảnh thành video theo phong cách MiniMax có thể nêu rõ khung hình đầu tiên, chẳng hạn:

Đối với video đích, tại thời điểm 0.00 giây trong video đích, <Picture 1> (từ [Shot 1]) được tham chiếu đầy đủ. Chủ thể bước qua cửa và nhìn về phía cửa sổ.

Tạo khung hình đầu tiên khả dụng với bộ chuyển đổi Turbo và đường dẫn cơ sở 20 bước. Chế độ khung hình cuối và hình ảnh tham chiếu chưa được tích hợp vào gói này.

Kiểm soát khung hình, độ phân giải và lấy mẫu

Số lượng khung hình phải tuân theo dạng 17n + 5. README liệt kê các ví dụ được hỗ trợ, gồm 56, 73, 90, 124, 192, 243 và 362 khung hình. Chiều rộng và chiều cao phải là bội số của 32, còn giới hạn của mô hình đã phát hành là tổng canvas tối đa 768x1344 pixel.

Đường dẫn Turbo nhanh sử dụng ba lượt truyền tiến. Để tắt bộ chuyển đổi và dùng kết xuất 20 bước, đặt ADAPTER=none và POINTS=21:

ADAPTER=none POINTS=21 bash scripts/generate.sh "A lantern glowing beside a forest path" base-model.mp4

README mô tả thiết lập này là gần với mô hình cơ sở hơn, trong khi Turbo có thể tạo các khung hình sắc nét nhanh chóng nhưng đôi khi có thể lặp lại nhân vật. Hai chế độ có thể tạo ra bố cục khác nhau ngay cả khi dùng cùng một seed.

Hiểu các đánh đổi về tốc độ

Cải thiện tốc độ lớn nhất đến từ ba lượt truyền của bộ chuyển đổi Turbo thay vì 20 lượt. MLP SwiGLU int8, các phép toán QKV int8, đầu ra attention và kernel giải mã video mang lại thêm lợi ích trên phần cứng tensor M5 được hỗ trợ.

Trong bài benchmark được ghi nhận ở 864x480, đường dẫn Turbo mất khoảng 27,6 giây để khử nhiễu và khoảng 50 giây tổng cộng, bao gồm mã hóa văn bản, tải và lượng tử hóa, cũng như giải mã. Kết xuất TensorFold int8 20 bước mất tổng cộng khoảng 210 giây trong cùng phép so sánh.

Các con số này phụ thuộc vào phần cứng và không nên được xem là áp dụng chung. Repository cũng lưu ý rằng attention vẫn sử dụng attention tích vô hướng có scale của MLX, vì phương án kiểu flash int8 được đo thử không mang lại lợi thế tốc độ đáng kể.

Thiết lập nâng cao và mẹo quy trình làm việc

Sử dụng carrier dựng sẵn

Trình cài đặt có thể sử dụng carrier GHCR, nhưng carrier không phải môi trường chạy Mac. Metal không chạy bên trong container; carrier chỉ cung cấp wheel TensorFold, khóa phụ thuộc, script tạo và checksum để cài đặt gốc.

docker pull ghcr.io/drowzeys/keys-mac-tensorfold-minimax-h3-mlx:1.1
docker run --rm -v "$PWD":/out ghcr.io/drowzeys/keys-mac-tensorfold-minimax-h3-mlx:1.1 cp -a /payload/. /out/payload/

Để dựng lại và đẩy carrier, repository cung cấp:

PUSH=1 bash scripts/build-carrier.sh

Lưu ý mức sử dụng bộ nhớ

Việc tải mô hình và hợp nhất bộ chuyển đổi tiêu tốn nhiều bộ nhớ. Hãy đóng các ứng dụng không cần thiết trước khi bắt đầu kết xuất, đặc biệt khi sử dụng bộ chuyển đổi Turbo. Repository cho biết việc chiếu các bảng AdaLN một lần mỗi lượt chạy và giải phóng trọng số giúp tiết kiệm khoảng 24 GiB trong đường dẫn được đo.

Chọn canvas phù hợp cho image-to-video

Vì hình ảnh đầu tiên được kéo giãn thay vì tự động cắt để giữ nguyên bố cục, hãy chuẩn bị hình ảnh nguồn theo tỷ lệ khung hình đích. Điều này giúp tránh biến dạng không mong muốn khi tạo clip dọc, ngang hoặc vuông.

Sử dụng bộ chuyển đổi thay thế một cách thận trọng

Bộ tải có thể đọc FastH3 qua đường dẫn bộ chuyển đổi và POINTS=5, chẳng hạn với ADAPTER=.../adapter_model.safetensors. README cho biết đường dẫn này đã được thử nghiệm ở 864x480, mất 76 giây với prompt kiểm thử và có hình ảnh nhiều chi tiết hơn Turbo. Nó được phát hành cho 1344x768, nhưng chưa được thử nghiệm trong dự án.

Diễn giải đúng các so sánh chất lượng

README nhấn mạnh rằng chất lượng chưa được đánh giá toàn diện. Đường dẫn int8 có thể giữ nguyên bố cục bfloat16 nhưng thay đổi chi tiết, và kết xuất Turbo ba lượt truyền có thể khác với kết xuất Turbo bfloat16. Do đó, các bảng benchmark so sánh tốc độ đo được và một số khung hình tĩnh được chọn, thay vì đảm bảo chuyển động hoặc chất lượng âm thanh giống hệt nhau.

Giấy phép và trạng thái dự án

Gói này không kèm trọng số mô hình. Trước khi tải MiniMax H3, hãy đọc MiniMax H3 Community License, bao gồm các khu vực bị loại trừ. Đồng thời xem tài liệu ghi công của repository và trích dẫn phù hợp các tác giả của MiniMax, TensorFold, MLX, H3, bộ chuyển đổi và các dự án liên quan ban đầu.

Dòng H3 được sử dụng ở đây được mô tả là một pull request bản nháp đề xuất từ upstream, thay vì một phần của phiên bản TensorFold đã phát hành. Vì vậy, việc cố định các bản sửa đổi được ghi nhận là rất quan trọng để tái lập thiết lập.

Kết luận

Repository này cung cấp một cách chuyên biệt để chạy tạo video MiniMax H3 nguyên bản trên các máy Mac Apple Silicon tương thích. Sau khi cài đặt môi trường đã cố định phiên bản và tải mô hình, bạn có thể kết xuất clip text-to-video, tạo chuyển động từ khung hình đầu tiên, chuyển đổi giữa bộ chuyển đổi Turbo nhanh và đường dẫn cơ sở 20 bước, đồng thời điều chỉnh canvas, số lượng khung hình, seed và prompt. Hãy dự kiến nhu cầu đáng kể về bộ nhớ và dung lượng lưu trữ, đồng thời xem thời gian được công bố là số đo trên hệ thống M5 cụ thể, không phải cam kết chung.