Kernel

Registry

libreyolo/kernels/ adalah registry runtime kecil untuk implementasi pluggable. Slot operasi adalah nama seperti fake_quant_fp8 atau ms_deform_attn. Pemanggil meminta sebuah slot dari registry dan memperoleh implementasi terdaftar pertama yang lolos predicate, dengan pendaftaran terbaru sebagai pemenang, lalu kembali ke implementasi referensi jika tidak ada yang berlaku.

Struktur ini memastikan dependency opsional tidak pernah menjadi persyaratan keras. Mesin tanpa Triton, CUDA, atau paket kernels menjalankan kode yang sama dan menghasilkan angka yang sama, hanya lebih lambat.

import libreyolo.kernels as kernels # Slot operasi ke nama implementasi yang dipilih, atau "unavailable".print(kernels.active())

# off dan reference memiliki arti yang sama, serta melewati# import provider terakselerasi sepenuhnya.LIBREYOLO_KERNELS=off python train.py

LIBREYOLO_HUB_KERNELS=0 python predict.py

from libreyolo import LibreYOLOfrom libreyolo.kernels.attention import set_fused_attention model = LibreYOLO("LibreSwinIRs.pt") # Mengembalikan jumlah modul attention yang beralih.print(set_fused_attention(model))

import libreyolo.kernels as kernels kernels.register(    "fake_quant_fp8",    my_impl,    name="mybackend",    predicate=my_check,)

Predicate yang memunculkan error ditangkap dan menghasilkan peringatan, tidak pernah diteruskan. Dengan demikian, implementasi pihak ketiga yang rusak kembali ke jalur portabel alih-alih merusak prediksi.

Tata letak

Tree diatur berdasarkan tujuan terlebih dahulu dan backend kemudian, sehingga slot ditemukan berdasarkan yang dihitung, bukan library yang kebetulan mengimplementasikannya saat ini.

Batas antara simulate dan execute ditentukan oleh apakah model telah difinalisasi, bukan apakah sedang dilatih atau diterapkan. Implementasi referensi tetap berada di libreyolo/quant/, yang mendefinisikan arti angka; kernels/ hanya mempercepatnya. Packing bobot tidak memiliki varian karena merupakan kontrak checkpoint.

Slot GEMM dan attention tidak memiliki implementasi referensi. Pemanggil harus memeriksa apakah resolve() mengembalikan nilai dan mempertahankan jalur portabelnya sendiri. Karena itu, graph ONNX, TensorRT, dan torch.export selalu memuat matematika portabel.

Override pemilihan

LIBREYOLO_KERNELS=off atau =reference memaksa implementasi referensi dan menghentikan import provider terakselerasi sepenuhnya. Nilai lain membatasi pemilihan ke implementasi yang terdaftar dengan nama tersebut. LIBREYOLO_QUANT_KERNELS dipatuhi sebagai alias lama dari saat registry berada di bawah libreyolo/quant/, dan hanya dibaca ketika LIBREYOLO_KERNELS tidak ditetapkan. Keduanya tercantum bersama variabel lain pada pengaturan.

Kernel Hub

Kernel CUDA terkompilasi yang dipublikasikan pada Hugging Face Hub dimuat saat runtime melalui paket kernels opsional. Tidak ada yang disertakan ke LibreYOLO; artefak diambil dan disimpan dalam cache oleh paket tersebut, dan setiap provider menetapkan revisi commit yang telah diaudit. Karena itu, perubahan pin memerlukan run paritas GPU sebelum diterapkan.

Menginstal ekstra berarti ikut serta:

pip install "libreyolo[hub-kernels]"

Tanpa paket tersebut, tidak ada yang berubah dan tidak ada permintaan jaringan. LIBREYOLO_HUB_KERNELS=0 menonaktifkan pengambilan tanpa menghapus instalasi. Kernel yang gagal dimuat atau dijalankan menonaktifkan diri selama sisa process dan kembali ke fallback dengan satu peringatan.

Saat ini satu slot didukung Hub: ms_deform_attn, forward dan backward multi-scale deformable attention terkompilasi dari Deformable DETR, berdasarkan Apache 2.0. Slot ini dihubungkan ke seluruh lineage deformable: RF-DETR, Deformable DETR, DINO-DETR, LW-DETR, Grounding DINO, RT-DETR, RT-DETRv2, D-FINE, RT-DETRv4, DEIM, DEIMv2, EC, dan OV-DEIM. Karena backward juga dikompilasi, pelatihan dan prediksi sama-sama memperoleh manfaat.

Kelayakannya sengaja dibatasi. Input harus menggunakan CUDA dan float32, serta eksekusi harus eager: provider menolak ketika torch.jit.is_tracing(), torch.compiler.is_compiling(), torch.compiler.is_exporting(), dan torch.onnx.is_in_onnx_export() aktif. Dua tata letak input juga kembali ke jalur portabel, yaitu jumlah titik per level yang berbeda antarlevel dan sampling indeks bilangan bulat diskret. Varian pose EC tidak dihubungkan.

Kernel ini baru dapat dijangkau

Baca bagian ini sebelum menginstal ekstra pada project yang sudah ada.

Pada v1.4.0, slot diperiksa dari dalam helper di balik kondisi yang mengharuskan pasangan spatial-shape tidak ada. RF-DETR selalu meneruskan pasangan tersebut melalui decoder, sehingga kondisi tidak pernah terpenuhi dan kernel tidak pernah dijalankan dalam eager forward. Pemeriksaan dipindahkan pada v1.5.0, dan kini kernel benar-benar berjalan.

Konsekuensi praktisnya adalah upgrade ke v1.5.0 sekaligus instalasi libreyolo[hub-kernels] pada CUDA membuat RF-DETR dan lineage-nya menggunakan forward dari binary terkompilasi untuk pertama kalinya. Prediksi dan metrik dapat bergeser dalam toleransi float. Instalasi standar tanpa ekstra tidak terpengaruh. Saat membandingkan metrik lintas upgrade, pertahankan ekstra yang sama atau tetapkan LIBREYOLO_HUB_KERNELS=0 pada kedua sisi.

Fused attention

Fused scaled dot-product attention tidak memerlukan dependency opsional, hanya PyTorch standar, sehingga diatur oleh kebijakan, bukan ketersediaan. Dua aturan berlaku.

Pertama, graph capture tidak pernah menggunakannya. Setiap call site yang diganti mempertahankan persamaan operasi primitif di balik pemeriksaan ekspor. Hal ini mencakup ekspor ONNX, yang opset default-nya tidak memiliki symbolic SDPA, serta torch.jit.trace, yang digunakan TorchScript, CoreML, dan NCNN. Capture Dynamo sengaja berada di luar gate karena torch.compile menurunkan SDPA lebih baik daripada matematika manual, sedangkan Core AI dan ExecuTorch mendekomposisi SDPA ke core ATen sendiri.

Kedua, standar paritas untuk menjadikannya default adalah sama persis per byte. Family yang lolos menggunakan SDPA secara default: SegFormer, Depth Anything dan MoGe-2, BERT, Grounding DINO, SwinIR, dan PP-OCR. Family yang tidak lolos mempertahankan matematika manual dan menyediakan flag fused_attn, yang diubah oleh set_fused_attention(model): Swin, backbone Swin milik DINO-DETR, BiRefNet dan FeyNobg, OWLv2, LW-DETR, SigLIP 2, ZipDepth, dan MobileSAM. ViT dan DeiT memiliki flag yang sama, tetapi default-nya aktif mengikuti upstream, sehingga pemanggilan yang sama dengan enabled=False menonaktifkannya.

Fitur ini layak digunakan jika berlaku. Pada RTX 5070 Ti dengan autocast fp16, Swin window attention turun dari 1.278 ms ke 0.721 ms, peningkatan 1.77x, dan OWLv2 vision attention dari 6.483 ms ke 1.735 ms, peningkatan 3.74x.

Perangkat keras

Menambahkan implementasi

Panggil register() dengan nama dan predicate. Kernel terkompilasi di luar tree dapat disediakan sebagai paket libreyolo_kernels terpisah yang mendaftarkan diri saat import, sehingga backend privat sepenuhnya berada di luar tree LibreYOLO.

Paritas adalah gate bagi semua implementasi dalam tree: forward harus cocok persis dengan referensi, dan gradien harus berada dalam 1e-6 dari estimator straight-through, pada kumpulan bentuk yang dibawa test suite.

Pemilihan kernel berinteraksi dengan CUDA graph: matriks paritas inferensi dijalankan tanpa paket kernels terinstal, sehingga keamanan capture dengan kernel terkompilasi aktif tidak dicakup olehnya.