---
name: diffusers_load_pipeline
kind: function
lang: py
domain: ml
version: "1.0.0"
purity: impure
signature: "def diffusers_load_pipeline(model: ModelRef, device: str = 'auto', dtype: str = 'fp16') -> Any"
description: "Carga un pipeline diffusers (AutoPipelineForText2Image) con cache global por (model_key, dtype, device). Segunda llamada con mismos parametros retorna el objeto cacheado sin recargar disco."
tags: [diffusers, ml, image-generation, pipeline, cache, torch]
uses_functions: [torch_device_select_py_ml]
uses_types: [model_ref_py_ml]
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [torch, diffusers]
params:
  - name: model
    desc: "Referencia al modelo. model.path si disponible (ruta local), model.name si no (HuggingFace Hub o nombre corto)."
  - name: device
    desc: "Preferencia de device: 'auto' (CUDA>MPS>CPU), 'cuda', 'cuda:N', 'mps', 'cpu'. Default 'auto'."
  - name: dtype
    desc: "Precision del modelo: 'fp16' (torch.float16 + variant=fp16), 'bf16' (bfloat16), 'fp32' (float32). Default 'fp16'."
output: "Pipeline diffusers cargado y movido al device. Callable via pipe(prompt=..., ...). Cacheado en _PIPELINE_CACHE."
tested: true
tests:
  - "carga pipeline y retorna callable"
  - "segunda carga usa cache (< 100ms)"
test_file_path: "python/functions/ml/tests/test_diffusers_backend.py"
file_path: "python/functions/ml/diffusers_load_pipeline.py"
---

## Ejemplo

```python
import sys
sys.path.insert(0, "python/functions/ml")
from diffusers_load_pipeline import diffusers_load_pipeline
from model_ref import ModelRef

model = ModelRef(
    name="sd-turbo",
    model_type="sd15",
    quantization="fp16",
    path="/home/lucas/vaults/imagegen_models/diffusers/sd-turbo",
)
pipe = diffusers_load_pipeline(model, device="cuda", dtype="fp16")
# Segunda llamada: cache hit, < 100ms
pipe2 = diffusers_load_pipeline(model, device="cuda", dtype="fp16")
assert pipe is pipe2
```

## Notas

Cache global `_PIPELINE_CACHE` indexado por `(model_key, dtype, resolved_device)`.
`model_key` es `model.path` si no es None, sino `model.name`.

Para liberar memoria: usar `diffusers_unload(pipe=None)` que llama `_clear_pipeline_cache()`.

Imports lazy de torch y diffusers dentro de la funcion — ImportError descriptivo si no instalados.