# ruBLAS
[English](../../README.md) | [简体中文](../zh/README.md) | [日本語](../ja/README.md) | [Deutsch](../de/README.md) | **Русский**
**Английский** | [简体中文](../zh/README.md)
Линейная алгебра и умножение матриц для Ruda.
- Cargo пакет: `rublas`
- Крейт Rust: `rublas`
## Feature
| Feature |Операции|
| --- | --- |
|`tensor-matmul`|Умножение матриц|
|`tensor-matmul-autotune`|Автонастройка умножения матриц|
|`tensor-vector`|Векторные операции|
|`tensor-grouped`|Групповое умножение матриц|
|`tensor-int4`|INT4 весовые операции|
## Краткое руководство
Сборка из рабочей области RUDA:
```sh
git clone https://github.com/shuqi2077/RUDA.git
cd RUDA
cargo build --release --locked -p rublas --features tensor-matmul
```
## Документация
- [Руководство пользователя](../../../docs/ru/libraries/rublas.md)
- [Настройка среды](../../../docs/ru/getting-started.md)
- [Функции Cargo](../../Cargo.toml) · [Экспорт модулей](../../src/lib.rs)
## ruBLAS Руководство пользователя
[Вычислительные библиотеки](../../../docs/ru/libraries/README.md) · [Среда выполнения API](../../../docs/ru/runtime-api.md) · [中文](../zh/README.md)
### 1. Обзор и возможности
ruBLAS предоставляет операции линейной алгебры и интерфейсы тензоров устройств.
| Feature |Модуль|
| --- | --- |
|`tensor-vector`|`rublas::tensor_vector`|
|`tensor-matmul`|`rublas::tensor_matmul`|
|`tensor-matmul-autotune`|Автонастройка умножения тензорной матрицы|
|`tensor-int4`|`rublas::tensor_int4`|
|`tensor-grouped`|`rublas::tensor_grouped`|
Пакет Cargo — `rublas`. Выберите необходимые функции и отключите ненужные значения по умолчанию для путей общего назначения. См. [Cargo.toml](../../Cargo.toml).
### 2. Умножение матриц, векторы и INT4
#### Умножение тензорной матрицы
`rublas::tensor_matmul::matmul` принимает lhs, rhs, необязательный выход out, MatmulStrategy и выходной DType. Возвращает тензор устройства или MatmulSetupError. Передайте существующий выход через out либо не задавайте его для выделения нового.
Стратегии включают Ruda, CmmaResidueFirst, Naive и Autotune при включённом `tensor-matmul-autotune`. Без этого feature по умолчанию используется Ruda, с ним — Autotune. Для квантованных входов Naive может после сбоя исходного пути деквантовать данные и выполнить вычисление; это не нативное вычисление INT4.
`CmmaResidueFirst` явно выбирает путь Tensor Core, который сначала обрабатывает частичный фрагмент K32, не требуя материализованной дополненной матрицы. lhs и rhs должны иметь совпадающие неквантованные BF16 или F16 dtype и совместимые размеры матрицы. Устройство должно поддерживать матричные инструкции пути. Эта функция возвращает вывод F32:
```rust
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)
}
```
Входы `[M, K]` и `[K, N]` создают `[M, N]`. Неверная настройка или отсутствие возможностей устройства возвращают `MatmulSetupError` вместо переключения на Naive.
См. [точку входа умножения матрицы](../../src/tensor_matmul/base.rs).
#### Векторное произведение
`rublas::tensor_vector::cross(lhs, rhs, dim)` требует длину 3 выбранного измерения и возвращает тензор устройства. Вычисление вдоль измерения, отличного от последнего, включает перестановку осей и преобразование в непрерывное размещение. См. [cross.rs](../../src/tensor_vector/cross.rs).
#### AWQ INT4
`rublas::tensor_int4::AwqGemm::new` использует qweight, qzeros, scales, дополнительные bias и group_size для построения упакованных весов. `forward` принимает входные данные F16 и возвращает выходные данные F16 или Int4Error.
Для входного измерения K, выходного измерения N и размера группы G:
|Данные|Тип данных|Форма|
| --- | --- | --- |
|qweight| Упакованный I32 |[K, N/8]|
|qzeros| Упакованный I32 |[K/G, N/8]|
|scales|F16|[K/G, N]|
|bias (дополнительно)|F16|[N]|
K, N и G должны быть ненулевыми; K должен делиться на G и N на 8. Конечная размерность входных данных — K, заменяемая на N на выходе. Все операнды должны использовать общее устройство. Порядок упакованных битов должен соответствовать [ядру AWQ](../../src/tensor_int4/kernel.rs); произвольный файл INT4 не может использоваться непосредственно как qweight.
См. [Интерфейс INT4](../../src/tensor_int4/mod.rs) для объекта и его проверок.
### 3. Групповое умножение матриц
`rublas::tensor_grouped::grouped_matmul_nt<R: Runtime>` принимает входные данные, веса и row_experts как значения `RudaTensor<R>`. Он возвращает `Result<RudaTensor<R>, GroupedMatmulError>`.
|Аргумент|Форма|Требования|
| --- | --- | --- |
|ввод|[M, K]|Неквантованный F32, F16 или BF16|
|веса|[E, N, K]| Те же dtype и устройство, что у входа |
|row_experts|[M]|Неквантованный U32 на том же устройстве|
|Вывод|[M, N]|Тот же dtype, что и для ввода.|
Строка m выбирает матрицу весов, индексированную row_experts[m], и вычисляет скалярное произведение между входной строкой и каждой строкой этой матрицы. Последние два весовых измерения участвуют в транспонированной форме, не требуя материализованного транспонирования.
### 4. Семантика группового умножения
- K, N и E должны быть положительными; М может быть нулевым.
- Индексы экспертов вне допустимого диапазона обозначают заполнение; соответствующие выходные строки заполняются нулями.
- Ядро накапливает данные в FP32, а затем преобразует их во входные данные dtype.
- Точка входа при необходимости делает ввод и веса непрерывными, что может привести к копированию данных.
- Количество соответствующих элементов должно соответствовать индексу U32.
- Неверные аргументы возвращают `GroupedMatmulError`. Обработка ошибок асинхронного выполнения во время обратного чтения или синхронизации.
Источник: [сгруппированный интерфейс](../../src/tensor_grouped/mod.rs) и [ядро](../../src/tensor_grouped/kernel.rs).
### 5. Интеграция с другими библиотеками
[ruDNN MoE](../../../docs/ru/libraries/rudnn.md) использует групповое умножение для экспертных прогнозов. Квантованные веса используют отдельный модуль `tensor_int4`; обычное групповое умножение с плавающей запятой не является экспертным вычислением INT4.
Сгруппированное ядро использует скалярное накопление. Измерьте стратегии умножения матриц для вашего dtype, формы и бэкенда.