---
name: sdcpp_python_load
kind: function
lang: py
domain: ml
version: "1.0.0"
purity: impure
signature: "def sdcpp_python_load(model: ModelRef, n_threads: int = -1, wtype: str = 'default', rng_type: str = 'cuda') -> Any"
description: "Carga un StableDiffusion via stable-diffusion-cpp-python con cache global por (model_key, wtype, n_threads). Segunda llamada con mismos params retorna instancia cacheada sin recargar disco."
tags: [ml, stable-diffusion, sdcpp, inference, backend, cache, load]
uses_functions: []
uses_types: [model_ref_py_ml]
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [stable_diffusion_cpp]
params:
  - name: model
    desc: "Referencia al modelo. model.path se usa si presente; si no, model.name como ruta local o HuggingFace hub."
  - name: n_threads
    desc: "Numero de hilos CPU para inferencia. -1 usa todos los disponibles."
  - name: wtype
    desc: "Tipo de pesos en memoria: 'default' | 'f32' | 'f16' | 'q8_0' | 'q5_1' | 'q5_0' | 'q4_1' | 'q4_0'. 'default' respeta el tipo original del checkpoint."
  - name: rng_type
    desc: "Generador de aleatorios: 'std_default' | 'cuda'. 'cuda' produce resultados compatibles con la implementacion CUDA incluso en CPU."
output: "Instancia StableDiffusion (stable_diffusion_cpp.StableDiffusion) lista para llamar a generate_image()."
tested: true
tests:
  - "load retorna objeto StableDiffusion"
  - "segunda llamada retorna instancia cacheada"
test_file_path: "python/functions/ml/tests/test_sdcpp_python_backend.py"
file_path: "python/functions/ml/sdcpp_python_load.py"
---

## Ejemplo

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

model = ModelRef(
    name="sd-turbo",
    model_type="sd15",
    quantization="fp16",
    path="/home/lucas/vaults/imagegen_models/diffusers/sd-turbo/sd_turbo.safetensors",
)
sd = sdcpp_python_load(model, n_threads=-1, wtype="default")
# sd listo para sd.generate_image(...)
```

## Notas

- El cache evita recargas de disco en bucles de generacion con el mismo modelo.
- `wtype="default"` respeta el tipo de cuantizacion del checkpoint; util para safetensors mixtos.
- `rng_type="cuda"` produce seeds compatibles con la implementacion GPU aunque se corra en CPU.
- Para limpiar el cache en tests: `sdcpp_python_load._clear_sd_cache()`.
- Compilacion sin CUDA: `CMAKE_ARGS="-DSD_CUDA=OFF" pip install stable-diffusion-cpp-python`.
- El binding 0.4.7 usa `generate_image()` (no `txt_to_img` que era la API de versiones anteriores).
---