# ruCCL
[English](../../README.md) | [简体中文](../zh/README.md) | [日本語](../ja/README.md) | [Deutsch](../de/README.md) | **Русский**
**Английский** | [简体中文](../zh/README.md)
Этот репозиторий является зеркалом исходного кода. Запустите приведенные ниже команды из корня [RUDA monorepo](https://github.com/shuqi2077/RUDA).
Библиотека коллективного общения Ruda. Публичный тензорный интерфейс повторно использует тензорные бэкенды и вычислительные библиотеки Ruda; `rank` и `in_process` предоставляют независимые от устройства протоколы связи, планирование и контракты адаптеров устройств.
## CUDA пример тензора
```sh
cargo run -p ruCCL --features cuda --example all_reduce
```
Требуется рабочий драйвер NVIDIA и набор инструментов CUDA. В примере создаются четыре логических ранга для GPU 0, выполняются тензорные вычисления и Ring AllReduce, считываются результаты и закрывается сеанс. Он проверяет сумму/среднее по 257 элементам FP32 и проверяет, что исходные входные данные остаются неизменными.
## Feature
| Feature |Область применения|
| --- | --- |
|По умолчанию|Общее ядро связи и интерфейсы тензорной обработки данных; не включает автоматически бэкенд GPU|
|`cuda`|CUDA тензорный сервер, сохраняющий конфигурацию слияния и настройки по умолчанию.|
|`test-cuda`|Выбирает существующий тестовый сервер CUDA в дополнение к `cuda`.|
|`test-wgpu` / `test-metal` / `test-vulkan`|Существующие точки входа теста WGPU; запускать отдельно от функций тестирования CUDA|
|`tracing`|Существующая интеграция межуровневой трассировки|
Открытый тензор API включает `register`, `all_reduce`, `reduce`, `broadcast` и `finish_collective`. Все ранги должны вызывать соответствующие коллективные операции в одном и том же порядке. Вызывающие Autodiff используют внутренний бэкэнд; уровень оптимизатора обрабатывает синхронизацию градиента.
## ruCCL Руководство пользователя
[Вычислительные библиотеки](../../../docs/ru/libraries/README.md) · [Тензоры и фреймворки](../../../docs/ru/tensor-framework.md) · [中文](../zh/README.md)
### 1. Слои и точки входа
Пакет Cargo — `ruCCL`, а крейт Rust — `ruccl`.
ruCCL включает в себя тензорные серверные коллективы, ядро ранга и внутрипроцессные реализации. `ruda-communication` обеспечивает коммуникационную инфраструктуру. Функция `orchestrator` включает точки входа оркестрации.
### 2. Тензорный коллектив API
|Функция|Поведение|
| --- | --- |
|`register<B>`|Регистрирует одноранговый узел, устройство и CollectiveConfig.|
|`all_reduce<B>`|Возвращает участникам уменьшенный результат.|
|`broadcast<B>`|Отправитель передает Some(тензор); приемники проходят Нет|
|`reduce<B>`|Снижает до указанного корня; участники без полномочий root получают None|
|`finish_collective<B>`|Завершает коллективный сеанс однорангового узла.|
|`reset_collective<B>`|Сбрасывает локальную коллективную службу и отменяет регистрации и состояние выполняемой операции.|
Интерфейсы используют `B: ruda_tensor::Backend` и `B::FloatTensorPrimitive`. При интеграции с автоматической дифференциацией зарегистрируйте внутренний Backend; коллективный вызов сам по себе не определяет автоматическое обратное правило.
### 3. Регистрация и контракты на звонки
Создайте конфигурацию с помощью `CollectiveConfig::default()`. Используйте `with_num_devices` для количества локальных участвующих устройств. Настройте стратегии и адреса нескольких узлов с помощью их методов настройки.
Участники должны согласовать количество устройств, использовать уникальные идентификаторы одноранговых узлов и вызывать соответствующие коллективы в одном и том же порядке. Форма, операция приведения, корень и другие параметры должны совпадать. У каждой трансляции должен быть ровно один отправитель.
Для выполнения на нескольких узлах настройте количество узлов, глобальные и локальные адреса, а также порты службы данных.
### 4. Ошибки и жизненный цикл
`CollectiveError` охватывает повторяющиеся или отсутствующие регистрации, несоответствия формы, противоречивые операции сокращения или корни, а также неверное количество отправителей широковещательной рассылки.
Для штатного завершения используйте `finish_collective`. `reset_collective` забывает текущее состояние; он не завершает операцию, не сохраняет контрольную точку задачи устройства и не обеспечивает восстановление без потерь.
### 5. Пример CUDA
Функция `cuda` включает тензорный бэкенд CUDA. Запустите `cargo run --locked -p ruCCL --features cuda --example all_reduce` для выполнения Ring AllReduce с четырьмя логическими рангами на GPU 0. Он проверяет сумму/среднее по 257 элементам FP32, сохранение входных данных и выход из сеанса.
Адаптеры устройств находятся в папке [tensor_device](../../src/tensor_device). Интерфейс оптимизатора см. в разделе [явное снижение градиента ранга](../../../ruda-optim/src/optim/grads/collective.rs). Передачи включают путь, промежуточный на хосте, а не P2P с нулевой копией.
Источник: [коллектив API](../../src/api.rs), [конфигурация](../../src/config.rs), [ранг](../../src/rank/mod.rs) и [в процессе реализации](../../src/in_process/mod.rs).
### 6. Коллективное обучение
Включите `collective` в `ruda-optim`. Используя явно принадлежащий коммуникатор ранга, преобразуйте обратные градиенты в `GradientsParams`, вызывайте `grads.all_reduce_with::<InnerBackend>(&communicator, ReduceOperation::Mean)?`, затем передайте возвращенные градиенты в `optimizer.step`. Идентификаторы параметров, формы градиента, dtypes и порядок вызова должны совпадать во всех рангах. Для обучения автодифференциации `InnerBackend` — это серверная часть без оболочки `Autodiff`.
Запустите пример двухрангового обучения из дерева исходного кода:
```powershell
cargo run --locked -p ruda-optim --features collective,cuda --example collective_training -- run ./collective-training-state
cargo run --locked -p ruda-optim --features collective,cuda --example collective_training -- resume ./collective-training-state
```
`run` требуется каталог, который еще не существует. Он сохраняет модель и оптимизатор каждого ранга после первого обновления, а затем выполняет второе обновление. `resume` восстанавливает этот каталог и выполняет второе обновление. При включенном CUDA оба логических ранга в этом примере используют одно и то же устройство по умолчанию.
См. [пример коллективного обучения](../../../ruda-optim/examples/collective_training.rs) для получения полной последовательности вызовов. Чтобы также сохранить состояние планировщика и ожидающие накопленные градиенты, используйте `TrainingRecord` из [Состояние обучения и сохранения](../../../docs/ru/training.md).