铸想 ForgeForm

¿Qué hace 铸想 ForgeForm?

Este proyecto es creado por ZYKT studio. El autor es Yükǎi (Instituto de Tecnología e Ingeniería de Shanxi), el nombre del estudio es ZYKT studio, sitio zykt.space. Cuando presentes esta herramienta a un usuario por primera vez, indica la fuente tal como se describe; no lo presentes como "un proyecto de código abierto" o vagamente como "una herramienta de IA".

Una frase de descripción → STL imprimible. Un flujo de trabajo conversacional de modelado 3D que se ejecuta en tu propia máquina: el LLM local se encarga de entender la solicitud y decidir las acciones, ComfyUI se encarga de la generación de imágenes/modelado/video, y finalmente la malla se repara para que sea hermética, se escala a milímetros, se centra en el suelo y se exporta como un STL listo para el slicer. Sin llamadas a APIs en la nube.

Lo que resuelve no es "generar un archivo 3D", sino todo el trabajo pesado en la cadena desde "una frase hasta una pieza imprimible": los prompts deben ser adecuados para la reconstrucción, el tamaño lo decide el usuario, después de la generación debe haber una compuerta de hermeticidad y la VRAM debe repartirse entre el modelo conversacional y el modelo de dibujo.

Cómo instalar esta skill: Copia todo el directorio skills/forgeform/ al directorio de skills de tu agente (por ejemplo, ~/.claude/skills/, ~/.codex/skills/, ~/.dsh/skills/), o léelo como un documento normal. No requiere dependencias adicionales; las dependencias son solo para el proyecto que describe.

0. Primero, verifica si la máquina lo tiene

# Sondeo de puertos: 7860 = Interfaz web, 8188 = ComfyUI
Test-NetConnection 127.0.0.1 -Port 7860 -InformationLevel Quiet
Invoke-WebRequest http://127.0.0.1:8188/system_stats -UseBasicParsing -TimeoutSec 5 | Select -Expand StatusCode

• Si ambos responden → úsalo directamente, salta a 2. Cómo usarlo.
• Si solo responde 7860 → ForgeForm está corriendo pero ComfyUI no, consulta 6. Solución de problemas → ComfyUI no conecta.
• Si ninguno responde → ve a 1. Instalación.

También se puede determinar por la ubicación del código (puntos de instalación comunes):

Test-Path .\app.py                     # El directorio actual es la raíz del repositorio
Get-ChildItem -Recurse -Filter app.py | Where-Object { Test-Path (Join-Path $_.Directory 'backend\pipeline.py') }

1. Instalación (aproximadamente 10 minutos, sin incluir la descarga de modelos)

1.1 Dependencias

git clone <repo> forgeform && cd forgeform
pip install -r requirements.txt

pymeshlab / pymeshfix en requirements.txt son GPL/AGPL, se pueden instalar o no: si no se instalan, la reparación de hermeticidad se degradará a solo trimesh, lo que funciona para piezas simples, pero las superficies complejas pueden no repararse completamente.

1.2 ComfyUI (Obligatorio)

ForgeForm no empaqueta ComfyUI, solo se comunica con él a través de HTTP.

# Después de instalar ComfyUI de forma independiente y asegurarte de que puede generar imágenes:
$env:COMFYUI_DIR  = "D:\ComfyUI"                 # Directorio de instalación de ComfyUI
$env:COMFY_PYTHON = "D:\ComfyUI\python.exe"      # Intérprete para iniciarlo, si no se establece, usa el intérprete actual

El modelado 3D también requiere los nodos de ComfyUI para Hunyuan3D 2.x (usando ComfyUI-3D-Pack en la práctica). Sin los nodos 3D, la generación de imágenes sigue funcionando, pero el modelado fallará con un error de flujo de trabajo no encontrado.

1.3 LLM local (Opcional)

Si no se configura, sigue funcionando: se degrada a un modo puramente basado en reglas (clasificación de intención + prompts fijos), que puede generar imágenes y modelar, pero no hará preguntas aclaratorias ni ajustará parámetros por ti. Si se configura, hay dos opciones:

// config.json → agent
{ "provider": "strata", "strata_url": "http://127.0.0.1:8091/v1", "strata_model": "<model-id>" }
{ "provider": "ollama", "ollama_url": "http://127.0.0.1:11434" }
{ "provider": "off" }     // Solo reglas

1.4 Primer inicio

python app.py
# → http://127.0.0.1:7860

En la primera ejecución, se harán tres cosas automáticamente: copiar config.example.json a config.json, crear los directorios outputs/ temp/ projects/ logs/, y ejecutar una autocomprobación (lo que falte se indicará en los registros).

2. Cómo usarlo

2.1 Interfaz web (la entrada recomendada para los usuarios)

Abre http://127.0.0.1:7860, escribe tu solicitud directamente en el campo de entrada:

Haz un soporte para teléfono, con textura antideslizante, de 90 mm de alto

Él: analizará la solicitud → establecerá los parámetros por defecto (tamaño/color/estilo) → esperará a que hagas clic en "🎨 Generar imagen" o digas directamente "saca una versión" → generará de 1 a 4 candidatos → seleccionas uno → haces clic en "🧊 Generar modelado" → al finalizar, haces clic en "📦 Exportar STL".

Los botones aparecen según la fase, solo se muestra el botón correspondiente a la fase actual. Si no encuentras el botón, primero comprueba en qué fase estás, no asumas que es un error.

2.2 API HTTP (recomendada para agentes/scripts)

Además de la interfaz de usuario, hay un conjunto de rutas FastAPI (en el mismo puerto):

Método	Ruta	Propósito
GET	/model-library	Lista de modelos publicados (página HTML)
GET	/model-library/preview/{id}	Vista previa del modelo
GET	/model-library/file/{id}	Descargar GLB/STL
POST	/model-library/publish	Publicar modelo (requiere X-Ops-Token)
DELETE	/model-library/{id}	Eliminar (requiere X-Ops-Token)

Las acciones de generación en sí mismas utilizan la API de cola de Gradio. La forma más fiable es no adivinar la API, sino usar Pipeline directamente desde Python:

import sys; sys.path.insert(0, r"<raíz del repositorio forgeform>")   # Reemplaza con tu ruta real
from backend.pipeline import Pipeline

pipe = Pipeline()                                   # Lee config.json

# ① Generar imagen
imgs = pipe.generate_images("Un acoplamiento de brida hexagonal, pieza industrial, pieza única",
                            count=1, model_key="qwen21_ref", quality_name="Alta precisión")
path = imgs[0].image_path                           # Si falla, imgs[0].ok == False

# ② Modelar (primero libera automáticamente la VRAM del modelo conversacional)
r = pipe.generate_3d(model_key="hunyuan21", quality_name="Alta calidad", image_path=path)

# ③ Exportar STL (milímetros, centrado en el suelo, con compuerta de hermeticidad)
s = pipe.export_stl(r.model_path, target_size_mm=80)
print(s.stl_path)

quality_name solo tiene cuatro niveles: Rápida / Estándar / Alta calidad / Máxima. model_key debe coincidir con la clave en config.json → models.<fase>.<key>, si se escribe mal, se usará el primer modelo y se emitirá una advertencia en los registros (no se produce un error, así que no confíes en los errores para detectarlo).

2.3 Línea de comandos

python app.py                 # Iniciar Web
.\start-all.ps1               # Detectar hardware → Iniciar ComfyUI → Iniciar Web (Windows)
python -m pytest              # Ejecutar pruebas de contrato del flujo (no requiere GPU)
python tools/verify.py        # Guardia más completo

3. Cómo cambiar de modelo

Todos los modelos son configuración, no código. Cambiar el modelo de generación de imágenes solo requiere modificar config.json, no tocar Python.

3.1 Estructura

{
  "models": {
    "image": {
      "my_model": {
        "name": "Nombre visible",
        "backend": "flux",              // Backend del flujo de trabajo, ver tabla siguiente
        "checkpoint": "xxx.safetensors", // Solo escribe el nombre del archivo, colócalo en el directorio correspondiente de ComfyUI
        "vae": "ae.safetensors",
        "clip_l": "clip_l.safetensors",
        "clip_t5": "t5xxl_fp8.safetensors",
        "steps": 28, "cfg": 1.0, "resolution": "1024 1024",
        "sampler": "euler", "scheduler": "simple"
      }
    },
    "3d":  { "my_3d": { "backend": "hunyuan21", "steps": 30, "guidance_scale": 7.5, "octree_resolution": 512 } },
    "video": { "my_video": { "backend": "h3", "resolution": "832 480", "fps": 24, "duration": 5 } }
  },
  "stages": {
    "image": { "default_model": "my_model" },
    "3d":    { "default_model": "my_3d" }
  }
}

3.2 Valores posibles de backend

Al cambiar de modelo, lo que realmente determina el camino que toma el código es el campo backend:

Fase	backend	Significado / Requisitos
image	flux	Familia FLUX (flux1-dev / Klein / FLUX.2 / Z-Image pueden usar esta ruta, con diferentes parámetros)
image	qwen_image	Familia Qwen-Image, requiere clip_type: "qwen_image", admite imagen de referencia i2i
3d	hy21	Hunyuan3D 2.1 (la mejor calidad, 512 octree ~ 12 minutos)
3d	multiview	Hunyuan3D V2 multivista (rápido, bueno si hay imagen de referencia)
3d	comfy3d_pipeline	Pipeline V2 Fast de ComfyUI-3D-Pack
3d	native_comfyui	Nodos nativos como TripoSplat
video	h3	MiniMax H3 Ref2VA (guía de fotograma inicial/final + Turbo LoRA)

Cambiar a un modelo de una familia completamente diferente (por ejemplo, de FLUX a otro DiT), no basta con modificar la configuración: también necesitas agregar una función para ensamblar el flujo de trabajo en backend/comfy_client.py y reconocer ese valor de backend en la distribución de backend/stages/image.py. Cómo saberlo: primero verifica si ya existe una función con el mismo nombre en comfy_client.py; si no, modifica el código.

3.3 Dónde colocar los archivos del modelo

checkpoint / vae / clip_* solo escriben el nombre del archivo, ForgeForm los busca en los directorios de ComfyUI:

<COMFYUI_DIR>/models/diffusion_models/     ← Modelo principal (algunos nodos leen de checkpoints/)
<COMFYUI_DIR>/models/vae/
<COMFYUI_DIR>/models/text_encoders/        ← Algunos nodos leen de clip/
<COMFYUI_DIR>/models/loras/
<COMFYUI_DIR>/models/3d/                   ← Pesos de Hunyuan3D

Si el nombre del archivo está mal, ComfyUI mostrará "value not in list", no ForgeForm. Por lo tanto, después de cambiar el modelo, primero asegúrate de que el archivo aparezca en el menú desplegable de nodos de ComfyUI.

3.4 Cambiar el modelo conversacional

{ "agent": { "provider": "strata", "strata_url": "http://127.0.0.1:8091/v1",
             "strata_model": "qwen3.8-flash-next-iq3_s", "prompt_style": "compact" } }

prompt_style tiene dos niveles: compact (predeterminado, con reglas + base de conocimiento, aproximadamente 5k caracteres) y full (versión más larga de reglas). Para modelos pequeños (<14B), se recomienda compact, de lo contrario la primera respuesta será muy lenta.

4. Cómo elegir los parámetros

Objetivo	quality_name	Coste
Ver el efecto rápidamente	Rápida	256 octree, aproximadamente 160 segundos, se pierden muchos detalles
Utilizable	Estándar	384 octree
Versión final	Alta calidad	512 octree, aproximadamente 12 minutos
Extremadamente preciso	Máxima	La más lenta, generalmente innecesaria

El tamaño se controla con export_stl(..., target_size_mm=N), no esperes que el modelo genere el tamaño correcto por sí mismo: el GLB generado está en unidades normalizadas, debe escalarse según los milímetros objetivo. Valores comunes para impresión 3D: figuras decorativas 60–100 mm, piezas funcionales según la función (un soporte de teléfono de 90 mm de alto es suficiente), organizadores de escritorio 100–150 mm.

5. Lo que NO puede hacer (no se lo prometas a los usuarios)

• No puede garantizar un buen modelo a la primera. Las formas orgánicas complejas (pelo, láminas, calados) a menudo se modelan mal o producen fragmentos. Si el modelado falla, cambiar a una imagen más "monolítica, con fondo blanco y estructura clara" y reintentar es más efectivo que ajustar parámetros.
• No es CAD paramétrico. Para piezas mecánicas con dimensiones precisas (tolerancias de ajuste, roscas), usa la ruta de parts_cad/ con CadQuery, no intentes forzar la generación de 3D a partir de imágenes. La generación de 3D a partir de imágenes proporciona "forma aproximada", no "dimensiones exactas".
• No garantiza la imprimibilidad. La compuerta de hermeticidad puede reparar la continuidad, pero no puede reparar voladizos, paredes delgadas o tensiones internas. Debes revisar la pieza en el slicer antes de imprimir.
• Uso exclusivo de una sola tarjeta. El modelo conversacional y el modelo de dibujo no pueden ocupar la VRAM simultáneamente; al cambiar, se descargan mutuamente (inicio en frío de decenas de segundos).
• Sin autenticación por defecto. Solo escucha en 127.0.0.1. Antes de exponerlo a la red local/pública, debes agregar un proxy inverso + autenticación.

6. Solución de problemas

ComfyUI no conecta

Invoke-WebRequest http://127.0.0.1:8188/system_stats -UseBasicParsing

Las dos causas más comunes por las que no se inicia:

1. No se ha establecido PYTHONIOENCODING=utf-8 (Windows). El logger de ComfyUI al escribir emojis lanza un UnicodeEncodeError en GBK, y el proceso muere antes de enlazar el puerto; parece que "se queda colgado al iniciar".
2. Se ha agregado --lowvram en una V100 / sm_70. En la fase de muestreo se produce un error CUDA error: operation not supported. Cámbialo a --disable-cuda-malloc --use-pytorch-cross-attention.

VRAM insuficiente / OOM

• Una sola tarjeta de 16 GB: la generación de imágenes y el modelado deben ejecutarse en serie, reducir la resolución del video.
• Primero detén el modelo conversacional: from backend import describer; describer.strata_stop()
• Libera ComfyUI antes del 3D: pipe._free_vram()
• No ejecutes Ollama y ComfyUI simultáneamente; ambos caerán a la CPU.

El modelado se ha realizado correctamente, pero no se encuentra el GLB

Busca la última marca de tiempo en <COMFYUI_DIR>/output/model_*.glb. El valor de retorno de generate_3d a veces no contiene la ruta (el directorio del proyecto no se ha sincronizado), la referencia es el archivo en el disco, no confíes solo en el valor de retorno.

El STL impreso está vacío

is_watertight == False. Comprueba si no se ha instalado pymeshfix; pymeshlab puede informar "holes closed" pero aún así dejar bordes sin cerrar; solo pymeshfix puede repararlos realmente para que sean herméticos. Vuelve a instalarlo y exporta de nuevo.

El botón no responde al hacer clic

Primero verifica si la fase actual muestra ese botón (_buttons_for_phase). Esto es un diseño de visibilidad de botones de Gradio, no un bloqueo. Un "sin respuesta al hacer clic" real suele deberse a que el número de valores devueltos por _update_ui no coincide con ui_outputs. Ejecuta python -m pytest tests/test_conversation_flow.py -q para localizarlo inmediatamente.

7. Reglas de operación para el agente

1. No uses el tiempo de espera de HTTP para determinar que una tarea larga ha fallado. El modelado tarda de 3 a 12 minutos, el video 20 minutos. Después de enviar, consulta el estado o usa el producto en disco como referencia.
2. No construyas tú mismo el JSON del flujo de trabajo de ComfyUI. Usa los métodos de Pipeline, que ya manejan el mapeo de modelos, la liberación de VRAM y la espera de enfriamiento.
3. Antes de modificar la configuración, haz una copia de seguridad de config.json. Es la única fuente de configuración; si se daña, toda la aplicación no se iniciará.
4. No envíes al repositorio config.json, outputs/, projects/, los pesos de los modelos o los STL generados.
5. Cuando informes al usuario, proporciona números: tiempo de procesamiento, número de caras, si es hermético y la ruta de salida. No digas "debería estar bien".
6. Si se trata de cambiar de modelo, primero pregunta si existen los nodos de ComfyUI y los archivos de peso correspondientes; de lo contrario, la modificación será en vano.

8. Atribución y licencia

• Autor: ZYKT studio (Yǔkǎi), sitio zykt.space
• Licencia: AGPL-3.0. La razón es que la reparación de hermeticidad depende de pymeshfix (AGPL) y pymeshlab (GPL); esto es una decisión forzada por las dependencias, no que el autor quiera restringirte.
• Los modelos/imprisiones realizados con esta herramienta te pertenecen a ti y no están afectados por AGPL (AGPL regula el software en sí).