fn_registry/python/functions/ml/comfyui_inject_ipadapter.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params, output, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path
comfyui_inject_ipadapter	function	py	ml	1.0.0	pure	def comfyui_inject_ipadapter(workflow: dict, ref_image: str, *, mode: str = "style", weight: float = 0.8, preset: str | None = None, weight_type: str | None = None, start_at: float = 0.0, end_at: float = 1.0, weight_faceidv2: float = 1.0, lora_strength: float = 0.6, combine_embeds: str = "concat", embeds_scaling: str = "V only", provider: str = "CPU", model_node: str | None = None) -> dict	Inyecta una rama IPAdapter (LoadImage + UnifiedLoader + IPAdapter, modo style o faceid) en un workflow ComfyUI ya construido (API format), repuntando el KSampler.model al MODEL condicionado por una imagen de referencia. La fuente del MODEL es la que hoy alimenta el KSampler (tras las LoRAs, no el checkpoint crudo). Version ENCADENABLE-sobre-dict del builder comfyui_build_ipadapter_workflow; reutiliza sus defaults de preset/weight_type. Pensada para componerse con inject_lora/inject_controlnet/inject_hires_fix. Pura: no muta el dict de entrada.	comfyui comfyui-skill ml ipadapter faceid stable-diffusion workflow	comfyui_build_ipadapter_workflow_py_ml			false			name desc workflow dict en API format (ej. salida de comfyui_build_txt2img_workflow, posiblemente con LoRAs). No se muta; se devuelve una copia. name desc ref_image Nombre del archivo de imagen de referencia en input/ del servidor. En faceid debe contener una cara nitida; en style es la imagen de estilo. No puede estar vacio (raise ValueError). name desc mode 'style' (transfiere estilo/composicion) o 'faceid' (rostro consistente via insightface + FaceID). keyword-only. name desc weight Peso de la influencia IPAdapter (0..1+). 0.8 buen punto de partida. keyword-only. name desc preset Preset del UnifiedLoader. None = default del modo ('STANDARD (medium strength)' style, 'FACEID PLUS V2' faceid). keyword-only. name desc weight_type Tipo de ponderacion del nodo IPAdapter/FaceID. None = default del modo ('standard' style, 'linear' faceid). keyword-only. name desc start_at Fraccion del sampling donde empieza a aplicar IPAdapter (0..1). keyword-only. name desc end_at Fraccion del sampling donde deja de aplicar (0..1). keyword-only. name desc weight_faceidv2 Peso del embedding FaceID v2 (solo mode='faceid'). keyword-only. name desc lora_strength Fuerza de la LoRA FaceID que carga el UnifiedLoaderFaceID (solo faceid). keyword-only. name desc combine_embeds Como combinar embeddings si hay varias caras ('concat'|'add'|...). Solo faceid. keyword-only. name desc embeds_scaling Escalado de embeddings ('V only'|'K+V'|...). Solo faceid. keyword-only. name desc provider Backend de insightface ('CPU'|'CUDA'|...). CPU por defecto para no competir por VRAM. Solo faceid. keyword-only. name desc model_node node_id cuya salida MODEL (slot 0) alimentara la rama IPAdapter. None = detecta la fuente del KSampler.model (CheckpointLoader como fallback). keyword-only.	copia del workflow con LoadImage + (UnifiedLoader|UnifiedLoaderFaceID) + (IPAdapter|IPAdapterFaceID) insertados y el KSampler.model repuntado a la salida MODEL de la rama IPAdapter. node_ids = max id numerico + 1/2/3.	true	mode style inyecta IPAdapterUnifiedLoader + IPAdapter y repunta KSampler.model mode faceid inyecta IPAdapterUnifiedLoaderFaceID + IPAdapterFaceID la rama toma el MODEL actual del KSampler (tras loras, no el checkpoint) respeta weight/preset/weight_type no muta el dict de entrada (pureza) mode invalido lanza ValueError ref_image vacio lanza ValueError api format valido	python/functions/ml/tests/test_comfyui_inject_ipadapter.py	python/functions/ml/comfyui_inject_ipadapter.py

Ejemplo

import sys, os
sys.path.insert(0, os.path.join(os.environ["HOME"], "fn_registry", "python", "functions"))
from ml.comfyui_build_txt2img_workflow import comfyui_build_txt2img_workflow
from ml.comfyui_inject_multi_lora import comfyui_inject_multi_lora
from ml.comfyui_inject_ipadapter import comfyui_inject_ipadapter

base = comfyui_build_txt2img_workflow("dreamshaper_8.safetensors", "portrait of a knight")
wf = comfyui_inject_multi_lora(base, [{"name": "detail_tweaker_sd15.safetensors", "strength_model": 0.5}])
wf = comfyui_inject_ipadapter(wf, "hero_face.png", mode="faceid", weight=0.9)
# KSampler.model viene de IPAdapterFaceID(model=ultimo LoraLoader, image=hero_face)

Cuando usarla

Cuando quieras condicionar un workflow txt2img ya construido con una imagen de referencia (estilo en style, rostro consistente en faceid) encadenando sobre el mismo dict que las LoRAs, sin reconstruir el grafo. Es la pieza IPAdapter del mixer comfyui_compose_capabilities. Para un workflow IPAdapter aislado desde cero usa comfyui_build_ipadapter_workflow.

Gotchas

• Pura: no muta el workflow de entrada y NO valida que los modelos IPAdapter esten instalados. La imagen de referencia debe estar subida al input/ del servidor ANTES de submit.
• ref_image obligatorio y mode in {style, faceid}: ambos validados con ValueError. Es el error path tipico al activar la capacidad sin referencia.
• Compatibilidad de checkpoint: usa modelos IPAdapter SD1.5 con checkpoints SD1.5 (dreamshaper_8) y SDXL con SDXL. Mezclar familias da un error de shape en ejecucion.
• faceid carga insightface (provider CPU por defecto) + un FaceID .bin + su LoRA: es la rama mas pesada. En 8GB lowvram funciona pero apilarla con ControlNet + hires + facedetailer a la vez puede dar OOM — baja resolucion o desactiva capacidades.
• Se aplica DESPUES de las LoRAs (toma el MODEL actual del KSampler), que es el orden correcto del mixer.