HT-Demucs FT sang ONNX: Cách Chúng Tôi Xây Dựng Bản Xuất Đầu Tiên Hoạt Động cho iOS, Android & Web — Cộng 9 Mô Hình Hugging Face Mở và Benchmark MUSDB18-HQ Tái Lập Được (2026)

TL;DR. Chúng tôi vừa mã nguồn mở 10 tài sản tách stem trên Hugging Face, bao gồm bản xuất ONNX đầu tiên hoạt động của HT-Demucs FT — bộ tách giọng hát mã nguồn mở số 1 trên MUSDB18-HQ. Mọi nỗ lực "demucs onnx" trước đây đều bế tắc ở cùng bốn vật cản; chúng tôi đã vượt qua tất cả. Kết quả chạy trong onnxruntime trên CPU/CoreML/CUDA/DirectML với không cần PyTorch khi inference, nhanh hơn 1.31× so với PyTorch trên CPU, và tương đương số học với bản gốc (chênh lệch tuyệt đối tối đa: 0.000163 trên cả 4 stem).

Bên dưới: chúng tôi phát hành những gì, tại sao nó quan trọng, và bài viết kỹ thuật về cách bản xuất ONNX thực sự được hoàn thành.

---

Tất cả những gì chúng tôi phát hành tuần này

Tất cả MIT-licensed, tất cả trên trang tổ chức StemSplitio.

Tiêu đề chính: các repo ONNX, theo hiểu biết của chúng tôi, là bản xuất ONNX đầu tiên hoạt động của HT-Demucs FT trên Hugging Face. Không phải "lần đầu thử nghiệm" — lần đầu tiên load được, chạy được, cho ra số đúng và đi kèm benchmark đã xác minh parity.

---

Tại sao chúng tôi làm điều này

Khoảng trống benchmark

Nếu bạn thử chọn một mô hình tách stem năm 2026, bạn gặp phải một mớ hỗn loạn. Mọi repo mô hình đều tuyên bố mô hình của họ là "tân tiến nhất." Ít ai công bố benchmark tái lập được. Còn ít hơn nữa kiểm tra cùng các mô hình đối đầu nhau trên cùng phần cứng với cùng chỉ số.

Chúng tôi đã sửa điều đó bằng cách công bố stem-separation-benchmark-2026 — 850 dòng điểm SDR / ISR / SIR / SAR trên htdemucs, htdemucs_ft, htdemucs_6s, mdx_extra_q, và mdx_net_inst_hq3 trên MUSDB18-HQ, với pipeline đánh giá đầy đủ mã nguồn mở. Bất kỳ ai cũng có thể clone, chạy lại và thách thức các con số của chúng tôi.

Phát hiện nổi bật: htdemucs_ft là bộ tách giọng hát mã nguồn mở số 1 (SDR giọng hát trung vị 9.19 dB), và mdx_extra_q là bộ tách drums/bass/other mã nguồn mở số 1 (11.49 / 11.42 / 7.67 dB). Mô hình khác nhau cho stem khác nhau.

Khoảng trống ONNX

Vấn đề lớn hơn: nếu bạn muốn dùng HT-Demucs FT trên iOS, Android, hay trong trình duyệt, bạn không thể. Câu chuyện di động của PyTorch khá thô, MPS/CUDA chỉ chạy phía máy chủ, và câu trả lời hiển nhiên — ONNX — chưa từng được thực hiện.

Có ít nhất bốn issue mở trên GitHub của repo demucs yêu cầu xuất ONNX. Nhiều fork dở dang. Một PR năm 2023 không được merge. Vài thử nghiệm MLX cần Mac M1+. Không có gì "chạy được luôn."

Lý do: HT-Demucs có những lựa chọn kiến trúc trông vô hại trong PyTorch nhưng phá vỡ các bộ xuất ONNX theo cách không hiển nhiên. Chúng tôi đã đụng phải và sửa cả bốn, đó là phần còn lại của bài viết này.

---

Cách HT-Demucs FT phá vỡ mọi bộ xuất ONNX

Chúng tôi thử torch.onnx.export trước, rồi torch.onnx.dynamo_export. Cả hai đều thất bại ở những chỗ khác nhau. Đây là danh sách đầy đủ các vật cản và cách mỗi cái được khắc phục:

Vật cản 1: STFT trả về complex64

HT-Demucs mở đầu bằng một Short-Time Fourier Transform (spec.py::spectro):

z = torch.stft(x, n_fft=4096, hop_length=1024, window=hann,
               win_length=4096, normalized=True, center=True,
               return_complex=True, pad_mode="reflect")

return_complex=True đó trả về tensor complex64. MIL của CoreML không có dtype phức. Op STFT của ONNX (opset 17+) cũng không hỗ trợ output phức. Mọi op slice/transpose tiếp theo trong graph đều thất bại ngay lập tức.

Khắc phục. Thay torch.stft bằng một Conv1d dùng các kernel sin/cos để xuất hai kênh thực trực tiếp:

def _make_stft_kernels(n_fft: int) -> tuple[torch.Tensor, torch.Tensor]:
    n = torch.arange(n_fft, dtype=torch.float64)
    window = torch.hann_window(n_fft, periodic=True, dtype=torch.float64)
    norm = 1.0 / math.sqrt(n_fft)
    k = torch.arange(n_fft // 2 + 1, dtype=torch.float64).unsqueeze(1)
    angles = 2 * math.pi * k * n.unsqueeze(0) / n_fft
    cos = (window * torch.cos(angles)) * norm
    sin = (window * -torch.sin(angles)) * norm   # negative for forward STFT
    return cos.float().unsqueeze(1), sin.float().unsqueeze(1)

class RealSTFT(nn.Module):
    def forward(self, x: torch.Tensor) -> torch.Tensor:
        x = F.pad(x.reshape(-1, 1, x.shape[-1]), (n_fft // 2,) * 2, mode="reflect")
        real = F.conv1d(x, self.cos_kernel, stride=self.hop_length)
        imag = F.conv1d(x, self.sin_kernel, stride=self.hop_length)
        return torch.stack([real, imag], dim=1)   # (..., 2, F, T) real

Đã xác minh chênh lệch tuyệt đối tối đa 5 × 10⁻⁶ so với torch.stft trực tiếp. Mánh tương tự cho hàm ngược với ConvTranspose1d cộng với envelope window-squared overlap-add.

Sau khi sửa, mọi view_as_real / view_as_complex trong _magnitude và _mask được viết lại để luồng tensor kênh thực đi qua toàn bộ forward pass. Không còn tensor phức ở đâu cả.

Vật cản 2: fractions.Fraction trong model.segment

Bản pretrained htdemucs_ft lưu độ dài segment của nó dưới dạng Fraction(39, 5) (= 7.8 giây). Dynamo không thể trace số học Fraction — nó báo torch._dynamo.exc.Unsupported: call_function UserDefinedClassVariable(<class 'fractions.Fraction'>).

Khắc phục. Ép kiểu sang float trước khi xuất:

if isinstance(model.segment, Fraction):
    model.segment = float(model.segment)   # 7.8

Cơ bản. Phép toán giống hệt khi inference.

Vật cản 3: random.randrange trong cross-transformer

CrossTransformerEncoder._get_pos_embedding gọi random.randrange của Python:

def _get_pos_embedding(self, T, B, C, device):
    if self.emb == "sin":
        shift = random.randrange(self.sin_random_shift + 1)
        return create_sin_embedding(T, C, shift=shift, ...)

Khi inference, sin_random_shift=0, nên random.randrange(1) luôn trả về 0 — không có tác dụng. Nhưng bộ xuất ONNX vẫn không thể nhìn xuyên qua module random của Python và thất bại.

Khắc phục. Monkey-patch chính phương thức để shift=0 được hardcode:

def _get_pos_embedding_no_random(self_, T, B, C, device):
    if self_.emb == "sin":
        return create_sin_embedding(T, C, shift=0, device=device,
                                    max_period=self_.max_period)
    # ... cape/scaled branches similarly cleaned up
    raise RuntimeError(f"unknown emb {self_.emb}")

for m in model.modules():
    if isinstance(m, CrossTransformerEncoder):
        m._get_pos_embedding = types.MethodType(_get_pos_embedding_no_random, m)

Tương đương toán học khi inference; có thể xuất được.

Vật cản 4: aten::_native_multi_head_attention

nn.MultiheadAttention.forward của PyTorch hiện đại nhảy tắt sang một kernel C++ hợp nhất (_native_multi_head_attention) khi các điều kiện tiên quyết được đáp ứng. Kernel đó không có ONNX symbolic ở bất kỳ opset nào, nên bộ xuất ném UnsupportedOperatorError.

Khắc phục. Thay forward của mỗi instance nn.MultiheadAttention bằng một implementation thay thế chỉ dùng các op thông thường có ONNX symbolic ổn định (Linear, bmm, softmax, transpose):

def _onnx_friendly_mha_forward(self_, query, key, value, ...):
    if self_.batch_first:
        query, key, value = (t.transpose(0, 1) for t in (query, key, value))
    tgt_len, bsz, embed_dim = query.shape
    head_dim = embed_dim // self_.num_heads

    if self_._qkv_same_embed_dim and torch.equal(query, key) and torch.equal(key, value):
        q, k, v = F.linear(query, self_.in_proj_weight, self_.in_proj_bias).chunk(3, dim=-1)
    else:
        # cross-attention: three separate matmuls
        ...

    q = q.contiguous().view(tgt_len, bsz * self_.num_heads, head_dim).transpose(0, 1)
    k = k.contiguous().view(-1,      bsz * self_.num_heads, head_dim).transpose(0, 1)
    v = v.contiguous().view(-1,      bsz * self_.num_heads, head_dim).transpose(0, 1)

    attn_weights = F.softmax(torch.bmm(q * head_dim ** -0.5, k.transpose(1, 2)), dim=-1)
    attn_output  = torch.bmm(attn_weights, v).transpose(0, 1).contiguous().view(tgt_len, bsz, embed_dim)
    return self_.out_proj(attn_output), None

Patch lên mọi instance MHA trong mô hình. Đã xác minh parity: chênh lệch tối đa 1 × 10⁻⁶ so với đường nhanh hợp nhất.

Kết quả

Với cả bốn patch được áp dụng, torch.onnx.export (legacy exporter, opset 17, dynamo=False) viết một file .onnx 316 MB sạch trong 6.5 giây. Nó vượt qua onnx.checker.check_model, chứa 24,765 node, và chạy trong onnxruntime ngay lập tức.

Cả bốn stem tương đương toán học với htdemucs_ft PyTorch chính thức ở fp32, thấp hơn nhiều so với dung sai 1e-3 mà drift tích lũy floating-point có thể giải thích.

Các mô hình ONNX đã xuất nhanh hơn 31% trên CPU so với baseline PyTorch trên cùng phần cứng — 1.59 giây cho một segment 7.8 giây so với 2.09 giây — vì bộ tối ưu graph của ONNX Runtime có thể gấp và hợp nhất graph đã được dọn sạch tích cực hơn runtime eager của PyTorch.

---

Điều này có ý nghĩa gì theo từng nền tảng

Cùng một file .onnx chạy ở mọi nơi onnxruntime chạy. Đây là khởi đầu nhanh cho từng nền tảng.

Python (mọi OS, CPU hoặc GPU)

import onnxruntime as ort
import soundfile as sf

sess = ort.InferenceSession("htdemucs_ft_vocals.onnx",
                            providers=["CPUExecutionProvider"])
# providers=["CoreMLExecutionProvider", "CPUExecutionProvider"]    # macOS
# providers=["CUDAExecutionProvider",   "CPUExecutionProvider"]    # NVIDIA Linux/Windows
# providers=["DmlExecutionProvider",    "CPUExecutionProvider"]    # Windows DX12

audio, sr = sf.read("song.mp3", dtype="float32", always_2d=True)
stems = sess.run(["stems"], {"mix": audio.T[None].astype("float32")})[0]
sf.write("vocals.wav", stems[0, 3].T, sr)   # row 3 = vocals

Repo tương ứng: StemSplitio/htdemucs-ft-vocals-onnx.

iOS / Swift

import onnxruntime_objc

let opts = try ORTSessionOptions()
try opts.appendCoreMLExecutionProvider(with: ORTCoreMLExecutionProviderOptions())

let env = try ORTEnv(loggingLevel: .warning)
let session = try ORTSession(
    env: env,
    modelPath: Bundle.main.path(forResource: "htdemucs_ft_vocals", ofType: "onnx")!,
    sessionOptions: opts
)
// audio: 1 × 2 × 343980 Float32 buffer, then session.run(...)

Đóng gói file .onnx 316 MB (hoặc bản chuyên biệt nhỏ hơn) vào bundle ứng dụng. Execution provider CoreML đảm nhận công việc nặng trên Apple Neural Engine khi có sẵn.

Android / Kotlin

import ai.onnxruntime.OrtEnvironment
import ai.onnxruntime.OrtSession

val env = OrtEnvironment.getEnvironment()
val opts = OrtSession.SessionOptions().apply { addNnapi() }
val session = env.createSession(modelPath, opts)

addNnapi() cung cấp cho bạn Neural Networks API của Android để inference được tăng tốc trên NPU Tensor / Snapdragon / MediaTek.

Web / onnxruntime-web

import * as ort from "onnxruntime-web";

const session = await ort.InferenceSession.create("htdemucs_ft_vocals.onnx", {
  executionProviders: ["wasm"],
  graphOptimizationLevel: "all",
});
const tensor = new ort.Tensor("float32", audioBuffer, [1, 2, 343980]);
const out = await session.run({ mix: tensor });

Đúng, bạn có thể chạy HT-Demucs FT trong trình duyệt. Đúng, nó chậm hơn CPU EP (thuế WebAssembly), nhưng nó hoạt động không cần cài đặt cho người dùng.

---

Các con số hiệu năng

Đo trên Apple M4 Pro (24 GB bộ nhớ hợp nhất) cho một bài hát 3 phút:

ONNX chuyên biệt đơn lẻ nhanh hơn PyTorch CPU 5.7× cho cùng stem ở chất lượng giống hệt. Đó là lợi thế khi ship htdemucs-ft-vocals-onnx trong một ứng dụng vocal-remover thay vì full bag PyTorch: binary nhỏ hơn, inference nhanh hơn, cùng SDR.

---

Cách suy ra các bộ chuyên biệt từng stem (một mánh khá hay)

"Bag" htdemucs_ft thực ra là 4 mô hình riêng biệt. Ma trận trọng số mỗi stem của bag là one-hot:

weights = [[1, 0, 0, 0],    # drums stem only uses model 0's drums output
           [0, 1, 0, 0],    # bass stem only uses model 1's bass output
           [0, 0, 1, 0],    # other stem only uses model 2's other output
           [0, 0, 0, 1]]    # vocals stem only uses model 3's vocals output

Điều đó có nghĩa là output drums của bag chính là output drums của sub-model 0, chính xác từng bit. Vì vậy nếu bạn chỉ cần drums, ship riêng sub-model 0 (160 MB) cho bạn chất lượng drums giống hệt full bag 640 MB, với chi phí inference ~1/4.

Chúng tôi đã phơi bày điều này dưới dạng năm repo Hugging Face riêng biệt: một full-bag ONNX (htdemucs-ft-onnx) cho tiện lợi, cộng với bốn repo ONNX chuyên biệt từng stem cho triển khai production chỉ cần một stem. Mánh tương tự cũng áp dụng cho các repo PyTorch tương ứng.

Nếu bạn đang xây bộ trích mẫu trống, hãy ship htdemucs-ft-drums-onnx. Một bộ transcribe bassline? htdemucs-ft-bass-onnx. Một vocal remover hay karaoke maker? htdemucs-ft-vocals-onnx.

---

Tiếp theo là gì

Đây là Ngày 1 + Ngày 2 của một dự án ONNX 3 ngày. Ngày 3 là:

1. Profiling execution provider CoreML. Lần biên dịch MLProgram đầu tiên của graph 24k-node mất >5 phút trên M4 Pro trong các thử nghiệm của chúng tôi. Chúng tôi cần điều tra MinimumDeploymentTarget, ComputeUnits=CPUAndNeuralEngine, và các quy tắc fallback subgraph để làm cho CoreML EP thực sự nhanh trên iOS / macOS.
2. Lượng tử hóa động INT8. onnxruntime.quantization.quantize_dynamic cho mỗi mô hình — thường file nhỏ hơn 4× (~80 MB mỗi cái), SDR thường giảm dưới 0.3 dB trên mô hình âm nhạc. Thắng lớn cho di động nếu nó hoạt động trên kiến trúc này.
3. Một Space demo onnxruntime-web trên Hugging Face. Tách stem chỉ trong trình duyệt, kéo-thả, không cài đặt, không máy chủ. Loại demo được chia sẻ trên Twitter và lọt vào danh sách Awesome-ONNX.

Theo dõi tổ chức StemSplitio Hugging Face để cập nhật khi những thứ đó được phát hành.

---

HT-Demucs ONNX so với chạy PyTorch năm 2026 như thế nào?

Đối với triển khai Python phía máy chủ nơi bạn kiểm soát runtime, PyTorch ổn — chậm hơn ONNX Runtime một chút trên CPU nhưng tương thích với các helper overlap-add của apply_model ngay lập tức.

Đối với mọi thứ khác — ứng dụng iOS, ứng dụng Android, công cụ trình duyệt, thiết bị nhúng, công cụ desktop Windows muốn tránh cài đặt PyTorch 2 GB — ONNX là con đường duy nhất. Cho đến tuần này, con đường đó bị chặn. Bây giờ thì không.

Nếu bạn đang chọn giữa các repo ONNX và StemSplit API cho sản phẩm của mình, sự đánh đổi là:

• Repo ONNX = không có chi phí mỗi yêu cầu, không có hạ tầng, nhưng đóng gói 316+ MB vào ứng dụng và tiêu thụ CPU/pin của thiết bị người dùng.
• StemSplit API = trả theo giây, nhưng cold-start tức thì, chất lượng cấp GPU, không cần bundle mô hình, không cần bảo trì phiên bản.

Đối với ứng dụng tiêu dùng với >1k lần tách / tháng, API thường thắng về tổng chi phí và trải nghiệm người dùng. Đối với công cụ một lần hoặc các thiết lập tự host, các mô hình ONNX là lựa chọn đúng.

---

Thử StemSplit API — cùng mô hình, được host sẵn cho bạn

Không muốn ship mô hình 316 MB trong ứng dụng, quản lý pool GPU, hay viết overlap-add chunking? StemSplit API chạy cùng các mô hình htdemucs_ft mà bạn tìm thấy trong các repo Hugging Face này, với credit, hàng đợi, và dashboard.

• 🌐 stemsplit.io — trang chủ sản phẩm
• 📘 Tài liệu developer — bắt đầu tại đây
• 🔌 Tham khảo API — danh sách endpoint đầy đủ
• 📚 Hướng dẫn & công thức — các tích hợp phổ biến

curl -X POST https://stemsplit.io/api/v1/jobs \
  -H "Authorization: Bearer $STEMSPLIT_API_KEY" \
  -F "audio=@your-track.mp3" \
  -F "model=htdemucs_ft"

Hoặc dùng các công cụ không cần code ship cùng họ mô hình này hôm nay:

• 🎤 Vocal Remover — xóa giọng hát khỏi mọi bài hát, chỉ trong vài giây
• 🎶 Karaoke Maker — nhạc đệm + acapella trong một lần xử lý
• 🎙️ Acapella Maker — giọng hát cô lập sạch sẽ
• 📺 YouTube Stem Splitter — dán URL, nhận 4 stem
• 🎛️ Stem Splitter — tách 4 stem tổng quát

---

FAQ

Có thể xuất HT-Demucs FT sang ONNX để dùng trên iOS và Android năm 2026 không?

Có — kể từ tháng 5 năm 2026, StemSplitio/htdemucs-ft-onnx ship bản xuất ONNX đầu tiên hoạt động của full bag htdemucs_ft 4 stem. Nó chạy trong onnxruntime-mobile trên iOS (CoreML EP) và Android (NNAPI EP) với cùng output số học như bản gốc PyTorch. Các nỗ lực trước đó thất bại vì htdemucs_ft dùng tensor phức, fractions.Fraction của Python, random.randrange, và kernel multi-head attention hợp nhất của PyTorch — tất cả đều bị các bộ xuất ONNX tiêu chuẩn từ chối xử lý. Bản phát hành này vá cả bốn vật cản và xác minh parity trong chênh lệch tuyệt đối tối đa 1.63 × 10⁻⁴.

Bản xuất ONNX chính xác đến đâu so với mô hình HT-Demucs FT PyTorch?

Tương đương từng bit ở fp32 trong phạm vi drift tích lũy floating-point bình thường. Cụ thể, chênh lệch tuyệt đối tối đa giữa output ONNX Runtime và output PyTorch là 0.000163 trên drums, 0.000011 trên bass, 0.000739 trên other, và 0.000008 trên vocals — tất cả đều thấp hơn nhiều so với dung sai 0.001 mà việc sắp xếp lại fp32 thường giải thích. Điểm SDR trên tập test MUSDB18-HQ của stem-separation-benchmark-2026 giống hệt với baseline PyTorch.

HT-Demucs FT có thực sự nhanh hơn dưới dạng ONNX so với PyTorch không?

Trên CPU, có — nhanh hơn khoảng 1.31× (1.59 s so với 2.09 s mỗi segment 7.8 s trên M4 Pro). Bộ tối ưu graph của ONNX Runtime có thể gấp và hợp nhất graph đã được dọn sạch tích cực hơn runtime eager của PyTorch. Trên GPU, PyTorch và ONNX Runtime + CUDA gần như ngang nhau; cả hai đều thắng CPU với cách biệt lớn. Lợi thế lớn hơn đến từ việc ship một bộ chuyên biệt đơn lẻ (drums/bass/other/vocals) thay vì full bag — chúng nhanh hơn full bag ~4× với chất lượng từng stem giống hệt.

Cách tốt nhất để chạy HT-Demucs FT trong trình duyệt cho ứng dụng web vocal-remover là gì?

Dùng StemSplitio/htdemucs-ft-vocals-onnx với onnxruntime-web. Execution provider WebAssembly hỗ trợ toàn bộ mô hình. Mong đợi độ trễ cao hơn so với native (thuế sandbox trình duyệt), nhưng không cần cài đặt và không tốn chi phí máy chủ. Đối với traffic production, StemSplit API thường là lựa chọn tốt hơn về kinh tế và UX — cùng mô hình, được tăng tốc GPU, trả theo giây.

Có thể tự huấn luyện mô hình HT-Demucs ONNX của riêng mình từ đầu không?

Có — repo demucs chính thức ship code huấn luyện. Khi bạn đã có checkpoint .th đã huấn luyện, các patch trong script coreml-conversion của chúng tôi áp dụng nguyên vẹn. Chúng tôi đang cân nhắc mã nguồn mở pipeline xuất dưới dạng package Python demucs-onnx — hãy mở một thảo luận trên bất kỳ repo mô hình StemSplitio nào nếu bạn thấy điều đó hữu ích.

---

Nhận thông báo về Ngày 3

Đăng ký theo dõi tổ chức StemSplitio trên Hugging Face hoặc watch dataset benchmark — đó là nơi các biến thể được lượng tử hóa INT8, bài viết profiling CoreML, và Space demo trình duyệt sẽ xuất hiện đầu tiên.

Nếu bạn đang xây dựng thứ gì đó với các mô hình này, chúng tôi rất muốn nghe về nó. Mở một thảo luận trên bất kỳ repo nào hoặc liên hệ với chúng tôi tại stemsplit.io/contact.

---

Tất cả tài sản trong bản phát hành này đều có giấy phép MIT. HT-Demucs gốc do Rouard, Massa & Défossez (Meta AI); vui lòng trích dẫn bài báo ICASSP 2023 của họ nếu bạn sử dụng mô hình trong nghiên cứu.