Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /main /pt /api /parallel.md

mishig

1 day ago

preview code

download

raw

8.45 kB

# Paralelismo

As estratégias de paralelismo ajudam a acelerar os difusão transformers distribuindo os cálculos entre vários dispositivos, permitindo tempos de inferência/treino mais rápidos. Consulte o guia [Inferência distribuída](../training/distributed_inference) para saber mais.

## ParallelConfig[[diffusers.ParallelConfig]]

#### diffusers.ParallelConfig[[diffusers.ParallelConfig]]

```python
diffusers.ParallelConfig(context_parallel_config: diffusers.models._modeling_parallel.ContextParallelConfig | None = None, tensor_parallel_config: diffusers.models._modeling_parallel.TensorParallelConfig | None = None, _rank: int = None, _world_size: int = None, _device: device = None, _mesh: DeviceMesh = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/_modeling_parallel.py#L199)

**Parâmetros:**

context_parallel_config (`ContextParallelConfig`, *opcional*) : Configuração para paralelismo de contexto.

tensor_parallel_config (`TensorParallelConfig`, *opcional*) : Configuração para paralelismo de tensor.

Configuração para aplicar diferentes paralelismos.

## ContextParallelConfig[[diffusers.ContextParallelConfig]]

#### diffusers.ContextParallelConfig[[diffusers.ContextParallelConfig]]

```python
diffusers.ContextParallelConfig(ring_degree: int | None = None, ulysses_degree: int | None = None, convert_to_fp32: bool = True, rotate_method: typing.Literal['allgather', 'alltoall'] = 'allgather', mesh: typing.Optional[torch.distributed.device_mesh.DeviceMesh] = None, ulysses_anything: bool = False, ring_anything: bool = False, _rank: int = None, _world_size: int = None, _device: device = None, _mesh: DeviceMesh = None, _flattened_mesh: DeviceMesh = None, _ring_mesh: DeviceMesh = None, _ulysses_mesh: DeviceMesh = None, _ring_local_rank: int = None, _ulysses_local_rank: int = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/_modeling_parallel.py#L41)

**Parâmetros:**

ring_degree (`int`, *opcional*, padrão `1`) : Número de dispositivos a serem usados para Ring Attention. A sequência é dividida entre os dispositivos. Cada dispositivo calcula a atenção entre seus blocos locais de Q e KV, que são passados sequencialmente ao redor do anel. Menor uso de memória (mantém apenas 1/N de KV por vez), sobrepõe o cálculo à comunicação, mas requer N iterações para ver todos os tokens. Ideal para sequências longas com memória/largura de banda limitadas. Número de dispositivos a serem usados para ring attention dentro de uma região de paralelismo de contexto. Deve ser um divisor do número total de dispositivos na malha de paralelismo de contexto.
ulysses_degree (`int`, *opcional*, padrão `1`) : Número de dispositivos a serem usados para Ulysses Attention. A sequência é dividida entre os dispositivos. Cada dispositivo calcula o QKV local e, em seguida, faz o all-gather de todos os blocos KV para calcular a atenção completa em uma única passagem. Exige mais memória (armazena todos os KV) e requer comunicação all-to-all de alta largura de banda, mas oferece menor latência. Ideal para sequências de tamanho moderado com boa largura de banda de interconexão.

convert_to_fp32 (`bool`, *opcional*, padrão `True`) : Se deve converter a saída e o LSE para float32 para estabilidade numérica do ring attention.

rotate_method (`str`, *opcional*, padrão `"allgather"`) : Método a ser usado para rotacionar os estados de chave/valor entre dispositivos no ring attention. Atualmente, apenas `"allgather"` é suportado.
ulysses_anything (`bool`, *opcional*, padrão `False`) : Se deve ativar o modo "Ulysses Anything", que suporta comprimentos de sequência e contagens de cabeças arbitrárias que não são divisíveis uniformemente por `ulysses_degree`. Quando ativado, `ulysses_degree` deve ser maior que 1 e `ring_degree` deve ser 1.

ring_anything (`bool`, *opcional*, padrão `False`) : Se deve ativar o modo "Ring Anything", que suporta comprimentos de sequência arbitrários. Quando ativado, `ring_degree` deve ser maior que 1 e `ulysses_degree` deve ser 1.
mesh (`torch.distributed.device_mesh.DeviceMesh`, *opcional*) : Uma malha de dispositivos personalizada para usar em paralelismo de contexto. Se fornecida, esta malha será usada em vez de criar uma nova. Isso é útil ao combinar paralelismo de contexto com outras estratégias de paralelismo (por exemplo, FSDP, paralelismo de tensor) que compartilham a mesma malha de dispositivos. A malha deve ter as dimensões "ring" e "ulysses". Use tamanho 1 para dimensões que não estão sendo usadas (por exemplo, `mesh_shape=(2, 1, 4)` com `mesh_dim_names=("ring", "ulysses", "fsdp")` para apenas ring attention com FSDP).
Configuração para paralelismo de contexto.
#### diffusers.hooks.apply_context_parallel[[diffusers.hooks.apply_context_parallel]]
```python
diffusers.hooks.apply_context_parallel(module: Module, parallel_config: ContextParallelConfig, plan: dict[str, dict[str, dict[str | int, diffusers.models._modeling_parallel.ContextParallelInput | list[diffusers.models._modeling_parallel.ContextParallelInput] | tuple[diffusers.models._modeling_parallel.ContextParallelInput, ...]] | diffusers.models._modeling_parallel.ContextParallelOutput | list[diffusers.models._modeling_parallel.ContextParallelOutput] | tuple[diffusers.models._modeling_parallel.ContextParallelOutput, ...] | diffusers.models._modeling_parallel.Conditional]])
```
[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/context_parallel.py#L81)
Aplicar paralelismo de contexto em um modelo.
## TensorParallelConfig[[diffusers.TensorParallelConfig]]
#### diffusers.TensorParallelConfig[[diffusers.TensorParallelConfig]]
```python
diffusers.TensorParallelConfig(tp_degree: int = 1, mesh: typing.Optional[torch.distributed.device_mesh.DeviceMesh] = None, _rank: int = None, _world_size: int = None, _device: device = None, _mesh: DeviceMesh = None, _tp_degree: int = None)
```
[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/_modeling_parallel.py#L157)
**Parâmetros:**
tp_degree (`int`, padrão `1`) : Número de dispositivos para dividir. Deve ser um divisor do número de cabeças de atenção (e dimensões ocultas do FFN) do modelo que está sendo paralelizado.

mesh (`torch.distributed.device_mesh.DeviceMesh`, *opcional*) : Uma malha de dispositivos personalizada para usar. Se fornecida, `tp_degree` é inferida a partir de `mesh.size()` e o argumento é ignorado. Útil ao combinar TP com outras estratégias de paralelismo (por exemplo, CP) que compartilham a mesma malha.

Configuração para paralelismo de tensor.

O paralelismo de tensor divide as matrizes de pesos (por coluna e por linha) entre os dispositivos. Cada dispositivo calcula um resultado parcial; um AllReduce/AllGather nas fronteiras das camadas reconstrói a saída completa. Utiliza `torch.distributed.tensor.parallelize_module` com os estilos de sharding `ColwiseParallel` / `RowwiseParallel`. Os tipos de dispositivo suportados são `"cuda"`, `"neuron"` e `"tpu"`.

#### diffusers.hooks.apply_tensor_parallel[[diffusers.hooks.apply_tensor_parallel]]

```python
diffusers.hooks.apply_tensor_parallel(model: Module, config: TensorParallelConfig, tp_plan: dict, weights_already_sharded: bool = False)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/tensor_parallel.py#L518)

**Parâmetros:**

model (`torch.nn.Module`) : O modelo a ser fragmentado no local.

config (`TensorParallelConfig`) : A configuração de paralelismo de tensor. Sua malha de dispositivos já deve estar configurada com `config.setup(...)`.

tp_plan (`dict`) : Um mapeamento plano de globs de nomes de módulos para um estilo `"colwise"`/`"rowwise"` (ou uma variante empacotada), geralmente o `_tp_plan` do modelo.
weights_already_sharded (`bool`, padrão `False`) : Indica se os parâmetros planejados já são fragmentos de `DTensor`, como ocorre após um carregamento em streaming via `from_pretrained`. Se `True`, apenas os hooks de forward são registrados. Isso é passado explicitamente em vez de ser detectado, pois um parâmetro planejado ausente do checkpoint ainda seria um tensor meta e faria a detecção indicar "não fragmentado" para um modelo que, na verdade, está parcialmente fragmentado.

Aplique o paralelismo de tensor em um modelo a partir do seu `_tp_plan` plano.

Xet Storage Details

Size:: 8.45 kB
Xet hash:: b4301c51c23c2bd85d0de95f0b19a37ea6d701d4b68228b4c3aef5b5b04c7908

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

	# Paralelismo

	As estratégias de paralelismo ajudam a acelerar os difusão transformers distribuindo os cálculos entre vários dispositivos, permitindo tempos de inferência/treino mais rápidos. Consulte o guia [Inferência distribuída](../training/distributed_inference) para saber mais.

	## ParallelConfig[[diffusers.ParallelConfig]]

	#### diffusers.ParallelConfig[[diffusers.ParallelConfig]]

	```python
	diffusers.ParallelConfig(context_parallel_config: diffusers.models._modeling_parallel.ContextParallelConfig \| None = None, tensor_parallel_config: diffusers.models._modeling_parallel.TensorParallelConfig \| None = None, _rank: int = None, _world_size: int = None, _device: device = None, _mesh: DeviceMesh = None)
	```

	[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/_modeling_parallel.py#L199)

	Parâmetros:

	context_parallel_config (`ContextParallelConfig`, opcional) : Configuração para paralelismo de contexto.

	tensor_parallel_config (`TensorParallelConfig`, opcional) : Configuração para paralelismo de tensor.

	Configuração para aplicar diferentes paralelismos.

	## ContextParallelConfig[[diffusers.ContextParallelConfig]]

	#### diffusers.ContextParallelConfig[[diffusers.ContextParallelConfig]]

	```python
	diffusers.ContextParallelConfig(ring_degree: int \| None = None, ulysses_degree: int \| None = None, convert_to_fp32: bool = True, rotate_method: typing.Literal['allgather', 'alltoall'] = 'allgather', mesh: typing.Optional[torch.distributed.device_mesh.DeviceMesh] = None, ulysses_anything: bool = False, ring_anything: bool = False, _rank: int = None, _world_size: int = None, _device: device = None, _mesh: DeviceMesh = None, _flattened_mesh: DeviceMesh = None, _ring_mesh: DeviceMesh = None, _ulysses_mesh: DeviceMesh = None, _ring_local_rank: int = None, _ulysses_local_rank: int = None)
	```

	[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/_modeling_parallel.py#L41)

	Parâmetros:

	ring_degree (`int`, opcional, padrão `1`) : Número de dispositivos a serem usados para Ring Attention. A sequência é dividida entre os dispositivos. Cada dispositivo calcula a atenção entre seus blocos locais de Q e KV, que são passados sequencialmente ao redor do anel. Menor uso de memória (mantém apenas 1/N de KV por vez), sobrepõe o cálculo à comunicação, mas requer N iterações para ver todos os tokens. Ideal para sequências longas com memória/largura de banda limitadas. Número de dispositivos a serem usados para ring attention dentro de uma região de paralelismo de contexto. Deve ser um divisor do número total de dispositivos na malha de paralelismo de contexto.

	ulysses_degree (`int`, opcional, padrão `1`) : Número de dispositivos a serem usados para Ulysses Attention. A sequência é dividida entre os dispositivos. Cada dispositivo calcula o QKV local e, em seguida, faz o all-gather de todos os blocos KV para calcular a atenção completa em uma única passagem. Exige mais memória (armazena todos os KV) e requer comunicação all-to-all de alta largura de banda, mas oferece menor latência. Ideal para sequências de tamanho moderado com boa largura de banda de interconexão.

	convert_to_fp32 (`bool`, opcional, padrão `True`) : Se deve converter a saída e o LSE para float32 para estabilidade numérica do ring attention.

	rotate_method (`str`, opcional, padrão `"allgather"`) : Método a ser usado para rotacionar os estados de chave/valor entre dispositivos no ring attention. Atualmente, apenas `"allgather"` é suportado.

	ulysses_anything (`bool`, opcional, padrão `False`) : Se deve ativar o modo "Ulysses Anything", que suporta comprimentos de sequência e contagens de cabeças arbitrárias que não são divisíveis uniformemente por `ulysses_degree`. Quando ativado, `ulysses_degree` deve ser maior que 1 e `ring_degree` deve ser 1.

	ring_anything (`bool`, opcional, padrão `False`) : Se deve ativar o modo "Ring Anything", que suporta comprimentos de sequência arbitrários. Quando ativado, `ring_degree` deve ser maior que 1 e `ulysses_degree` deve ser 1.

	mesh (`torch.distributed.device_mesh.DeviceMesh`, opcional) : Uma malha de dispositivos personalizada para usar em paralelismo de contexto. Se fornecida, esta malha será usada em vez de criar uma nova. Isso é útil ao combinar paralelismo de contexto com outras estratégias de paralelismo (por exemplo, FSDP, paralelismo de tensor) que compartilham a mesma malha de dispositivos. A malha deve ter as dimensões "ring" e "ulysses". Use tamanho 1 para dimensões que não estão sendo usadas (por exemplo, `mesh_shape=(2, 1, 4)` com `mesh_dim_names=("ring", "ulysses", "fsdp")` para apenas ring attention com FSDP).

	Configuração para paralelismo de contexto.

	#### diffusers.hooks.apply_context_parallel[[diffusers.hooks.apply_context_parallel]]

	```python
	diffusers.hooks.apply_context_parallel(module: Module, parallel_config: ContextParallelConfig, plan: dict[str, dict[str, dict[str \| int, diffusers.models._modeling_parallel.ContextParallelInput \| list[diffusers.models._modeling_parallel.ContextParallelInput] \| tuple[diffusers.models._modeling_parallel.ContextParallelInput, ...]] \| diffusers.models._modeling_parallel.ContextParallelOutput \| list[diffusers.models._modeling_parallel.ContextParallelOutput] \| tuple[diffusers.models._modeling_parallel.ContextParallelOutput, ...] \| diffusers.models._modeling_parallel.Conditional]])
	```

	[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/context_parallel.py#L81)

	Aplicar paralelismo de contexto em um modelo.

	## TensorParallelConfig[[diffusers.TensorParallelConfig]]

	#### diffusers.TensorParallelConfig[[diffusers.TensorParallelConfig]]

	```python
	diffusers.TensorParallelConfig(tp_degree: int = 1, mesh: typing.Optional[torch.distributed.device_mesh.DeviceMesh] = None, _rank: int = None, _world_size: int = None, _device: device = None, _mesh: DeviceMesh = None, _tp_degree: int = None)
	```

	[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/_modeling_parallel.py#L157)

	Parâmetros:

	tp_degree (`int`, padrão `1`) : Número de dispositivos para dividir. Deve ser um divisor do número de cabeças de atenção (e dimensões ocultas do FFN) do modelo que está sendo paralelizado.

	mesh (`torch.distributed.device_mesh.DeviceMesh`, opcional) : Uma malha de dispositivos personalizada para usar. Se fornecida, `tp_degree` é inferida a partir de `mesh.size()` e o argumento é ignorado. Útil ao combinar TP com outras estratégias de paralelismo (por exemplo, CP) que compartilham a mesma malha.

	Configuração para paralelismo de tensor.

	O paralelismo de tensor divide as matrizes de pesos (por coluna e por linha) entre os dispositivos. Cada dispositivo calcula um resultado parcial; um AllReduce/AllGather nas fronteiras das camadas reconstrói a saída completa. Utiliza `torch.distributed.tensor.parallelize_module` com os estilos de sharding `ColwiseParallel` / `RowwiseParallel`. Os tipos de dispositivo suportados são `"cuda"`, `"neuron"` e `"tpu"`.

	#### diffusers.hooks.apply_tensor_parallel[[diffusers.hooks.apply_tensor_parallel]]

	```python
	diffusers.hooks.apply_tensor_parallel(model: Module, config: TensorParallelConfig, tp_plan: dict, weights_already_sharded: bool = False)
	```

	[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/tensor_parallel.py#L518)

	Parâmetros:

	model (`torch.nn.Module`) : O modelo a ser fragmentado no local.

	config (`TensorParallelConfig`) : A configuração de paralelismo de tensor. Sua malha de dispositivos já deve estar configurada com `config.setup(...)`.

	tp_plan (`dict`) : Um mapeamento plano de globs de nomes de módulos para um estilo `"colwise"`/`"rowwise"` (ou uma variante empacotada), geralmente o `_tp_plan` do modelo.

	weights_already_sharded (`bool`, padrão `False`) : Indica se os parâmetros planejados já são fragmentos de `DTensor`, como ocorre após um carregamento em streaming via `from_pretrained`. Se `True`, apenas os hooks de forward são registrados. Isso é passado explicitamente em vez de ser detectado, pois um parâmetro planejado ausente do checkpoint ainda seria um tensor meta e faria a detecção indicar "não fragmentado" para um modelo que, na verdade, está parcialmente fragmentado.

	Aplique o paralelismo de tensor em um modelo a partir do seu `_tp_plan` plano.