ruBLAS Benutzerhandbuch

English | 简体中文 | 日本語 | Deutsch | Русский

Compute-Bibliotheken · Laufzeit API · 中文

1. Übersicht und Funktionen

ruBLAS bietet lineare Algebraoperationen und Gerätetensorschnittstellen.

Das Cargo-Paket ist rublas. Wählen Sie die erforderlichen Funktionen aus und deaktivieren Sie unnötige Standardeinstellungen für allgemeine Pfade. Siehe Cargo.toml.

2. Matrixmultiplikation, Vektoren und INT4

Tensormatrixmultiplikation

rublas::tensor_matmul::matmul nimmt lhs, rhs, die optionale Ausgabe out, MatmulStrategy und den Ausgabe-DType entgegen. Zurückgegeben wird ein Gerätetensor oder MatmulSetupError. Übergeben Sie eine vorhandene Ausgabe über out oder lassen Sie out weg, um eine neue zuzuweisen.

Zu den Strategien gehören Ruda, CmmaResidueFirst, Naive und bei aktiviertem tensor-matmul-autotune auch Autotune. Ohne dieses Feature ist Ruda der Standard, mit ihm Autotune. Bei quantisierten Eingaben kann Naive nach dem Scheitern seines ersten Pfads dequantisieren und rechnen; dies ist keine native INT4-Berechnung.

CmmaResidueFirst wählt explizit den Tensor-Core-Pfad aus, der zuerst eine teilweise K32-Kachel verarbeitet, ohne dass eine materialisierte gepolsterte Matrix erforderlich ist. lhs und rhs müssen übereinstimmende unquantisierte BF16 oder F16 dtype und kompatible Matrixdimensionen haben. Das Gerät muss die Matrixanweisungen des Pfades unterstützen. Diese Funktion gibt die F32-Ausgabe zurück:

use ruda_core::tensor::DType;
use ruda_kernel::{dsl::Runtime, tensor::RudaTensor};
use rublas::{
    kernel_ir::definition::MatmulSetupError,
    tensor_matmul::{MatmulStrategy, matmul},
};

fn residue_matmul<R: Runtime>(
    lhs: RudaTensor<R>,
    rhs: RudaTensor<R>,
) -> Result<RudaTensor<R>, MatmulSetupError> {
    matmul(lhs, rhs, None, MatmulStrategy::CmmaResidueFirst, DType::F32)
}

Die Eingaben [M, K] und [K, N] erzeugen [M, N]. Ungültiges Setup oder fehlende Gerätefunktionen geben MatmulSetupError zurück, anstatt zu Naive zu wechseln.

Siehe Einstiegspunkt für die Matrixmultiplikation.

Vektorkreuzprodukt

rublas::tensor_vector::cross(lhs, rhs, dim) setzt die Länge 3 der gewählten Dimension voraus und gibt einen Gerätetensor zurück. Eine Berechnung entlang einer anderen als der letzten Dimension erfordert Permutation und Umwandlung in zusammenhängenden Speicher. Siehe cross.rs.

AWQ INT4

rublas::tensor_int4::AwqGemm::new verwendet qweight, qzeros, scales, optional bias und group_size, um gepackte Gewichte zu erstellen. forward akzeptiert die Eingabe F16 und gibt die Ausgabe F16 oder Int4Error zurück.

Für Eingabedimension K, Ausgabedimension N und Gruppengröße G:

K, N und G müssen ungleich Null sein; K muss durch G und N durch 8 teilbar sein. Die endgültige Dimension der Eingabe ist K, die in der Ausgabe durch N ersetzt wird. Alle Operanden müssen sich ein Gerät teilen. Die gepackte Bitreihenfolge muss mit dem AWQ-Kernel übereinstimmen. Eine beliebige INT4-Datei kann nicht direkt als qweight verwendet werden.

Informationen zum Objekt und seinen Prüfungen finden Sie in der INT4-Schnittstelle.

3. Gruppierte Matrixmultiplikation

rublas::tensor_grouped::grouped_matmul_nt<R: Runtime> übernimmt Eingaben, Gewichtungen und row_experts als RudaTensor<R>-Werte. Es wird Result<RudaTensor<R>, GroupedMatmulError> zurückgegeben.

Zeile m wählt die durch row_experts[m] indizierte Gewichtsmatrix aus und berechnet Skalarprodukte zwischen der Eingabezeile und jeder Zeile dieser Matrix. Die letzten beiden Gewichtsdimensionen nehmen in transponierter Form teil, ohne dass eine materialisierte Transponierung erforderlich ist.

4. Gruppierte Multiplikationssemantik

• K, N und E müssen positiv sein; M kann Null sein.
• Expertenindizes außerhalb des gültigen Bereichs kennzeichnen Padding und erzeugen mit Nullen gefüllte Ausgabezeilen.
• Der Kernel akkumuliert in FP32 und wandelt ihn dann in die Eingabe dtype um.
• Der Einstiegspunkt macht Eingaben und Gewichtungen bei Bedarf zusammenhängend, wodurch möglicherweise Daten kopiert werden.
• Die Anzahl der relevanten Elemente muss zur U32-Indizierung passen.
• Ungültige Argumente geben GroupedMatmulError zurück. Behandeln Sie asynchrone Ausführungsfehler während des Rücklesens oder der Synchronisierung.

Quelle: gruppierte Schnittstelle und Kernel.

5. Integration mit anderen Bibliotheken

ruDNN MoE verwendet gruppierte Multiplikation für Expertenprojektionen. Quantisierte Gewichte verwenden das separate Modul tensor_int4; Die gewöhnliche gruppierte Gleitkommamultiplikation ist keine INT4-Expertenberechnung.

grouped_matmul_nt verwendet Skalarakkumulation. Messen Sie Matrixmultiplikationsstrategien für Ihren dtype, Ihre Form und Ihr Backend.

6. Segmentierte Experten-Matrixmultiplikation

Mit tensor-grouped ergänzt rublas::tensor_grouped::grouped_matmul_nt_segmented(input, weights, row_experts, offsets, strategy) die bestehende gruppierte Schnittstelle um geräteseitige Expertensegmente. Input hat die Form [M, K], weights [E, N, K], row_experts U32 [M] und offsets U32 [E + 1]; das Ergebnis ist [M, N] im dtype der Eingabe. Operanden müssen nicht quantisiert sein und dasselbe Gerät und dieselbe Ausführungsqueue verwenden.

Dies ist eine unsafe-Rust-API: offsets muss ein monoton nicht fallendes exklusives Präfix sein, das bei 0 beginnt und bei M endet. Alle Zeilen in [offsets[e], offsets[e + 1]) müssen zum Experten e gehören. row_experts muss denselben unveränderlichen Dispatch beschreiben. Formprüfungen validieren diese geräteseitigen Werte nicht.

GroupedStrategy::Scalar verwendet den bestehenden skalaren Kernel. TensorCore verlangt explizit übereinstimmende F16/BF16-Eingaben, unterstützte kooperative 16×16×16-Matrixoperationen, eine Plane mit 32 Lanes, ausreichend Shared Memory und ein gültiges Launch-Grid; eine nicht unterstützte Konfiguration liefert GroupedMatmulError. Der Kernel akkumuliert in FP32 und verarbeitet unvollständige Kacheln. Auto wählt diesen Pfad, wenn er unterstützt wird, sonst den skalaren Kernel. Kompilierungs-, Launch- oder numerische Fehler sind keine Fallback-Bedingungen.

Für einen sicheren MoE-Einstieg mit intern erzeugten Offsets verwenden Sie rudnn::moe::SwiGluExperts::forward_dispatched_with_strategy. Der bestehende Einstieg forward_dispatched bleibt standardmäßig skalar.

7. Segmentierter Rückwärtslauf

grouped_matmul_nt_backward_segmented(input, weights, grad_output, row_experts, offsets) liefert GroupedBackward { dinput, dweights }. Input hat Form [M, K], weights [E, N, K], grad_output [M, N], jeweils mit gleichem F32/F16/BF16-dtype, Gerät und Queue. dinput behält den Eingabetyp; dweights ist FP32 mit Form [E, N, K]. Leere Expertensegmente erhalten Null als Gewichtsgradienten. Zeilen-IDs und Offsets erfüllen dieselben U32-Layouts und unveränderlichen Präfixbedingungen wie im Vorwärtslauf. Die API bleibt unsicher; Gerätemetadaten werden nicht zur Prüfung auf den Host übertragen.

Der Standard-Wrapper wählt GroupedStrategy::Scalar. grouped_matmul_nt_backward_segmented_with_strategy(..., strategy) wählt unabhängig vom Vorwärtslauf Scalar, Auto oder TensorCore. Der kooperative Pfad verwendet 16×16×16-Kacheln, FP32-Akkumulation und FP32-Gewichtsgradienten und benötigt unterstützte F16/BF16-Hardware sowie zulässige Launch-Größen. TensorCore meldet fehlende Unterstützung als Fehler; Auto fällt nur bei fehlenden Fähigkeiten zurück, nicht bei Kompilierungs- oder Ausführungsfehlern. Eingaben können zusammenhängend kopiert werden. Unterschiedliche Reduktionsreihenfolgen müssen nicht bitgleich sein.

Für sicheres Training auf Expertenebene verwenden Sie rudnn::moe::SwiGluExperts::forward_dispatched_training und anschließend ExpertTrainingCache::backward_with_strategy.