Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /v0.43.0 /fr /modular_diffusers /auto_docstring.md

mishig

2 days ago

preview code

download

raw

5.88 kB

# Modèles de docstring et de paramètres automatiques

Chaque [ModularPipelineBlocks](/docs/diffusers/v0.43.0/fr/api/modular_diffusers/pipeline_blocks#diffusers.ModularPipelineBlocks) possède une propriété `doc` générée automatiquement à partir de ses `description`, `inputs`, `intermediate_outputs`, `expected_components` et `expected_configs`. Le système de docstring automatique maintient les docstrings synchronisées avec l'interface réelle du bloc. Les modèles de paramètres fournissent des descriptions standardisées pour les paramètres qui apparaissent dans de nombreuses pipelines.

## Docstring automatique

Les blocs de pipeline modulaires sont composables — vous pouvez les imbriquer, les enchaîner en séquences et les réorganiser librement. Leurs docstrings suivent le même modèle. Lorsqu'un [SequentialPipelineBlocks](/docs/diffusers/v0.43.0/fr/api/modular_diffusers/pipeline_blocks#diffusers.SequentialPipelineBlocks) agrège les entrées et les sorties de ses sous-blocs, la documentation doit se mettre à jour automatiquement sans réécriture manuelle.

Le marqueur `# auto_docstring` génère des docstrings à partir des propriétés du bloc. Ajoutez-le au-dessus d'une définition de classe pour marquer la classe en vue de la génération automatique de docstrings.

```py
# auto_docstring
class FluxTextEncoderStep(SequentialPipelineBlocks):
    ...
```

Exécutez la commande suivante pour générer et insérer les docstrings.

```bash
python utils/modular_auto_docstring.py --fix_and_overwrite
```

L'utilitaire lit la propriété `doc` du bloc et l'insère en tant que docstring de la classe.

```py
# auto_docstring
class FluxTextEncoderStep(SequentialPipelineBlocks):
    """
    Text input processing step that standardizes text embeddings for the pipeline.
    Inputs:
        prompt_embeds (`torch.Tensor`) *required*:
            text embeddings used to guide the image generation.
        ...
    Outputs:
        prompt_embeds (`torch.Tensor`):
            text embeddings used to guide the image generation.
        ...
    """
```

Vous pouvez également vérifier sans écraser, ou cibler un fichier ou un répertoire spécifique.

```bash
# Check that all marked classes have up-to-date docstrings
python utils/modular_auto_docstring.py
# Check a specific file or directory
python utils/modular_auto_docstring.py src/diffusers/modular_pipelines/flux/
```

Si une classe marquée est dépourvue de docstring, la vérification échoue et énumère les classes devant être mises à jour.

```
Found the following # auto_docstring markers that need docstrings:
- src/diffusers/modular_pipelines/flux/encoders.py: FluxTextEncoderStep at line 42
Run `python utils/modular_auto_docstring.py --fix_and_overwrite` to fix them.
```

## Modèles de paramètres

`InputParam` et `OutputParam` définissent les entrées et les sorties d'un bloc. Créez-les directement ou utilisez `.template()` pour des définitions standardisées de paramètres courants tels que `prompt`, `num_inference_steps` ou `latents`.

### Paramètre d'entrée

`InputParam` décrit une seule entrée d'un bloc.

| Champ | Type | Description |
|---|---|---|
| `name` | `str` | Nom du paramètre |
| `type_hint` | `Any` | Annotation de type (par exemple, `str`, `torch.Tensor`) |
| `default` | `Any` | Valeur par défaut (si non définie, le paramètre n'a pas de valeur par défaut) |
| `required` | `bool` | Si le paramètre est obligatoire |
| `description` | `str` | Description lisible par un humain |
| `kwargs_type` | `str` | Nom du groupe pour les paramètres associés (par exemple, `"denoiser_input_fields"`) |
| `metadata` | `dict` | Informations supplémentaires arbitraires |

#### Créer InputParam directement

```py
from diffusers.modular_pipelines import InputParam
InputParam(
    name="guidance_scale",
    type_hint=float,
    default=7.5,
    description="Scale for classifier-free guidance.",
)
```

#### Utilisation d'un modèle

```py
InputParam.template("prompt")
# Equivalent to:
# InputParam(name="prompt", type_hint=str, required=True,
#            description="The prompt or prompts to guide image generation.")
```

Les modèles définissent automatiquement `name`, `type_hint`, `default`, `required` et `description`. Vous pouvez remplacer n'importe quel champ ou ajouter du contexte avec le paramètre `note`.

```py
# Override the default value
InputParam.template("num_inference_steps", default=28)
# Add a note to the description
InputParam.template("prompt_embeds", note="batch-expanded")
# description becomes: "text embeddings used to guide the image generation. ... (batch-expanded)"
```

### OutputParam

`OutputParam` décrit une seule sortie d'un bloc.

| Champ | Type | Description |
|---|---|---|
| `name` | `str` | Nom du paramètre |
| `type_hint` | `Any` | Annotation de type |
| `description` | `str` | Description lisible par un humain |
| `kwargs_type` | `str` | Nom du groupe pour les paramètres associés |
| `metadata` | `dict` | Informations supplémentaires arbitraires |

#### Créer OutputParam directement

```py
from diffusers.modular_pipelines import OutputParam
OutputParam(name="image_latents", type_hint=torch.Tensor, description="Encoded image latents.")
```

#### Utilisation d'un modèle

```py
OutputParam.template("latents")
# Add a note to the description
OutputParam.template("prompt_embeds", note="batch-expanded")
```

## Modèles disponibles

`INPUT_PARAM_TEMPLATES` et `OUTPUT_PARAM_TEMPLATES` sont définis dans [modular_pipeline_utils.py](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py). Ils incluent des paramètres courants tels que `prompt`, `image`, `num_inference_steps`, `latents`, `prompt_embeds`, et d'autres. Reportez-vous à la source pour la liste complète des noms de modèles disponibles.

Xet Storage Details

Size:: 5.88 kB
Xet hash:: b89cb01df791ee9265d3a3e93bc3d5421444ddc4307869aa0fc1f60ce888ff22

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

	# Modèles de docstring et de paramètres automatiques

	Chaque [ModularPipelineBlocks](/docs/diffusers/v0.43.0/fr/api/modular_diffusers/pipeline_blocks#diffusers.ModularPipelineBlocks) possède une propriété `doc` générée automatiquement à partir de ses `description`, `inputs`, `intermediate_outputs`, `expected_components` et `expected_configs`. Le système de docstring automatique maintient les docstrings synchronisées avec l'interface réelle du bloc. Les modèles de paramètres fournissent des descriptions standardisées pour les paramètres qui apparaissent dans de nombreuses pipelines.

	## Docstring automatique

	Les blocs de pipeline modulaires sont composables — vous pouvez les imbriquer, les enchaîner en séquences et les réorganiser librement. Leurs docstrings suivent le même modèle. Lorsqu'un [SequentialPipelineBlocks](/docs/diffusers/v0.43.0/fr/api/modular_diffusers/pipeline_blocks#diffusers.SequentialPipelineBlocks) agrège les entrées et les sorties de ses sous-blocs, la documentation doit se mettre à jour automatiquement sans réécriture manuelle.

	Le marqueur `# auto_docstring` génère des docstrings à partir des propriétés du bloc. Ajoutez-le au-dessus d'une définition de classe pour marquer la classe en vue de la génération automatique de docstrings.

	```py
	# auto_docstring
	class FluxTextEncoderStep(SequentialPipelineBlocks):
	...
	```

	Exécutez la commande suivante pour générer et insérer les docstrings.

	```bash
	python utils/modular_auto_docstring.py --fix_and_overwrite
	```

	L'utilitaire lit la propriété `doc` du bloc et l'insère en tant que docstring de la classe.

	```py
	# auto_docstring
	class FluxTextEncoderStep(SequentialPipelineBlocks):
	"""
	Text input processing step that standardizes text embeddings for the pipeline.

	Inputs:
	prompt_embeds (`torch.Tensor`) required:
	text embeddings used to guide the image generation.
	...

	Outputs:
	prompt_embeds (`torch.Tensor`):
	text embeddings used to guide the image generation.
	...
	"""
	```

	Vous pouvez également vérifier sans écraser, ou cibler un fichier ou un répertoire spécifique.

	```bash
	# Check that all marked classes have up-to-date docstrings
	python utils/modular_auto_docstring.py

	# Check a specific file or directory
	python utils/modular_auto_docstring.py src/diffusers/modular_pipelines/flux/
	```

	Si une classe marquée est dépourvue de docstring, la vérification échoue et énumère les classes devant être mises à jour.

	```
	Found the following # auto_docstring markers that need docstrings:
	- src/diffusers/modular_pipelines/flux/encoders.py: FluxTextEncoderStep at line 42

	Run `python utils/modular_auto_docstring.py --fix_and_overwrite` to fix them.
	```

	## Modèles de paramètres

	`InputParam` et `OutputParam` définissent les entrées et les sorties d'un bloc. Créez-les directement ou utilisez `.template()` pour des définitions standardisées de paramètres courants tels que `prompt`, `num_inference_steps` ou `latents`.

	### Paramètre d'entrée

	`InputParam` décrit une seule entrée d'un bloc.

	\| Champ \| Type \| Description \|
	\|---\|---\|---\|
	\| `name` \| `str` \| Nom du paramètre \|
	\| `type_hint` \| `Any` \| Annotation de type (par exemple, `str`, `torch.Tensor`) \|
	\| `default` \| `Any` \| Valeur par défaut (si non définie, le paramètre n'a pas de valeur par défaut) \|
	\| `required` \| `bool` \| Si le paramètre est obligatoire \|
	\| `description` \| `str` \| Description lisible par un humain \|
	\| `kwargs_type` \| `str` \| Nom du groupe pour les paramètres associés (par exemple, `"denoiser_input_fields"`) \|
	\| `metadata` \| `dict` \| Informations supplémentaires arbitraires \|

	#### Créer InputParam directement

	```py
	from diffusers.modular_pipelines import InputParam

	InputParam(
	name="guidance_scale",
	type_hint=float,
	default=7.5,
	description="Scale for classifier-free guidance.",
	)
	```

	#### Utilisation d'un modèle

	```py
	InputParam.template("prompt")
	# Equivalent to:
	# InputParam(name="prompt", type_hint=str, required=True,
	# description="The prompt or prompts to guide image generation.")
	```

	Les modèles définissent automatiquement `name`, `type_hint`, `default`, `required` et `description`. Vous pouvez remplacer n'importe quel champ ou ajouter du contexte avec le paramètre `note`.

	```py
	# Override the default value
	InputParam.template("num_inference_steps", default=28)

	# Add a note to the description
	InputParam.template("prompt_embeds", note="batch-expanded")
	# description becomes: "text embeddings used to guide the image generation. ... (batch-expanded)"
	```

	### OutputParam

	`OutputParam` décrit une seule sortie d'un bloc.

	\| Champ \| Type \| Description \|
	\|---\|---\|---\|
	\| `name` \| `str` \| Nom du paramètre \|
	\| `type_hint` \| `Any` \| Annotation de type \|
	\| `description` \| `str` \| Description lisible par un humain \|
	\| `kwargs_type` \| `str` \| Nom du groupe pour les paramètres associés \|
	\| `metadata` \| `dict` \| Informations supplémentaires arbitraires \|

	#### Créer OutputParam directement

	```py
	from diffusers.modular_pipelines import OutputParam

	OutputParam(name="image_latents", type_hint=torch.Tensor, description="Encoded image latents.")
	```

	#### Utilisation d'un modèle

	```py
	OutputParam.template("latents")

	# Add a note to the description
	OutputParam.template("prompt_embeds", note="batch-expanded")
	```

	## Modèles disponibles

	`INPUT_PARAM_TEMPLATES` et `OUTPUT_PARAM_TEMPLATES` sont définis dans [modular_pipeline_utils.py](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py). Ils incluent des paramètres courants tels que `prompt`, `image`, `num_inference_steps`, `latents`, `prompt_embeds`, et d'autres. Reportez-vous à la source pour la liste complète des noms de modèles disponibles.