Constructor FastAPI desde Modelo de HF
Qué hace esta habilidad
Toma un model_id de Hugging Face y genera un proyecto FastAPI autónomo, local y de grado de producción a su alrededor: estructura de aplicación en capas, modelo cargado una vez al inicio (nunca por solicitud), un endpoint de inferencia apropiado para la tarea, procesamiento por lotes con límites explícitos, validación de entrada/salida, health y readiness probes, manejo estructurado de errores y scripts opcionales de evaluación/benchmark.
Soporta cuatro familias de tareas, cada una con una forma de endpoint diferente y una biblioteca subyacente:
| Familia de tarea | Concepto en HF | Biblioteca | Archivo de referencia |
|---|---|---|---|
| Clasificación de texto | AutoModelForSequenceClassification | transformers | references/text-classification.md |
| Clasificación de tokens (NER) | AutoModelForTokenClassification | transformers | references/token-classification-ner.md |
| Embeddings de texto | modelo de sentence embedding | sentence-transformers | references/embeddings.md |
| Generación de imágenes | diffusion pipeline | diffusers | references/image-generation.md |
Límites del alcance — lea esto antes de empezar
- Solo local. Sin Docker, sin Kubernetes, sin despliegue en la nube (Railway, AWS, etc.). El resultado es un proyecto que el usuario ejecuta con
uvicornen su propia máquina. - Solo backend. Nunca genere código de frontend/cliente (React, Next.js, llamadas fetch, etc.). Si el usuario quiere una interfaz para llamar a la API, dígale que es un asunto aparte y deténgase en el límite de la API. Está bien habilitar CORS local permisivo para que un servidor de desarrollo frontend pueda llamar a la API más tarde; eso es una preocupación de configuración del backend, no código de frontend.
- Servir, no entrenar. Si el usuario quiere ajustar o entrenar un modelo, esta habilidad no es la herramienta adecuada — dígaselo.
- Modelo de amenaza local y de un solo usuario. Los servicios generados NO tienen autenticación NI limitación de velocidad por diseño — están pensados para ejecutarse en
localhost. Sí imponen límites de costo de entrada (tamaño de lote, longitud por cadena, parámetros de generación y un límite de tamaño del cuerpo de la solicitud → 413). Siempre advierta al usuario que no vincule el servicio a0.0.0.0ni lo exponga más allá de localhost sin agregar primero autenticación, limitación de velocidad y una política de CORS reforzada — todo eso está fuera del alcance aquí. - No instale ni lance nada sin preguntar. Andamie el proyecto y dé al usuario los comandos exactos para ejecutar. Solo ejecute
pip installo inicieuvicornsi el usuario le pide explícitamente que verifique que funciona; algunas de estas dependencias (torch,diffusers) son descargas grandes.
Flujo de trabajo
Paso 1: Recopilar entradas
Necesita:
model_id(obligatorio) — el ID del Hub de Hugging Face, p. ej.distilbert-base-uncased-finetuned-sst-2-english.- Directorio de salida (pregunte si no se proporciona, de lo contrario, por defecto
./<nombre-del-modelo-en-slug>-apien el directorio de trabajo actual). - Opcional: una ruta a un pequeño conjunto de datos de evaluación etiquetado (para la evaluación de corrección más adelante), un puerto (por defecto
8000).
Si el usuario solo describe lo que hizo en un cuaderno ("Lo cargo con pipeline(...), clasifica sentimientos"), pregunte por el model_id exacto si no se indica; todo lo que sigue depende de ello.
Paso 2: Inspeccionar el modelo
Ejecute el inspector incluido; solo accede a la API pública del Hub de HF, nunca descarga los pesos del modelo:
python scripts/inspect_model.py <model_id>
Imprime JSON con task_family, pipeline_tag, library_name, architectures, id2label (si está disponible), num_labels, un recuento aproximado de parámetros y una nota de recomendación de dispositivo.
- Si
task_familydevuelve una de las cuatro familias compatibles, continúe. - Si devuelve
"unknown"o no está de acuerdo con la suposición (algunos repositorios tienen metadatos faltantes/incorrectos), pregunte al usuario cuál de las cuatro familias de tareas corresponde; no adivine en silencio incorrectamente, la forma de todo el endpoint depende de ello. - Si el script informa
not_found_or_gated, la API pública de HF devolvió 401/403/404 — esto significa que elmodel_ides incorrecto/mal escrito, o el repositorio está restringido/privado. No puede indicarle cuál de los dos casos es. Primero confirme elmodel_idexacto con el usuario (los errores tipográficos y los espacios de nombres de organización incorrectos son la causa más común); solo si se confirma que es correcto, debe tratarlo como restringido y pedir al usuario que acepte la licencia en la página del modelo y se autentique. Prefiera pasar el token a través de la variable de entornoHF_TOKEN(HF_TOKEN=hf_xxx python scripts/inspect_model.py <model_id>) ohuggingface-cli login; evite la bandera--token, ya que un token en la línea de comandos se filtra en el historial del shell y en la lista de procesos.
Paso 3: Leer el archivo de referencia correspondiente
Antes de andamiar, lea references/<task-family>.md para la familia de tareas del Paso 2. Contiene el código exacto de carga del modelo/pipeline, el esquema de solicitud/respuesta y los problemas específicos de la tarea (por ejemplo, mapeo de etiquetas para clasificación, agregación de entidades para NER, estrategia de pooling para embeddings, codificación de imágenes para generación). También hoje references/architecture.md una vez por sesión; cubre las partes que son idénticas en las cuatro familias de tareas (carga en lifespan, health probes, CORS, manejo de errores) para que no tenga que derivarlas cada vez.
Utilice la habilidad transformers-huggingface ya instalada para cualquier cosa sobre carga de modelos, tokenización, colocación de dispositivos (CPU/CUDA/MPS) o elección de dtype que surja más allá de lo que cubre el archivo de referencia; contiene los patrones autorizados para la propia biblioteca transformers.
Paso 4: Andamiar el proyecto
Ejecute el generador con la familia de tareas y cualquier información de etiquetas/configuración que haya obtenido en el Paso 2:
python scripts/scaffold_project.py \
--model-id "<model_id>" \
--task <text-classification|token-classification|embeddings|image-generation> \
--output-dir "<output_dir>" \
--id2label-json "<ruta-al-json-o-json-en-línea>" # opcional, solo clasificación/NER
Ejecute python scripts/scaffold_project.py --help para ver todas las banderas (puerto, tamaño máximo de lote, longitud máxima de entrada/tamaño de imagen, etc.) — pase cualquier información relevante que haya aprendido en el Paso 2 en lugar de dejar los valores predeterminados generados si tiene mejores valores.
Esto produce:
<output_dir>/
├── app/
│ ├── main.py # FastAPI() + lifespan (cargar modelo una vez, warm up), CORS, montaje de router
│ ├── core/
│ │ ├── config.py # pydantic-settings: MODEL_ID, DEVICE, MAX_BATCH_SIZE, etc. desde env
│ │ └── model.py # load_model() / función de inferencia para la familia de tareas elegida
│ ├── api/
│ │ └── routes.py # endpoint de tarea + /health/live + /health/ready + /v1/info
│ └── schemas.py # Modelos de solicitud/respuesta de Pydantic con restricciones de Field
├── tests/
│ ├── test_health.py
│ └── test_inference.py # camino feliz + un caso de error de validación
├── requirements.txt # solo lo que necesita esta familia de tareas
├── .env.example
├── README.md # instrucciones de ejecución, documentación de endpoints, nota de CORS
└── .gitignore
El andamiador completa lo que puede determinar programáticamente (id del modelo, familia de tareas, etiquetas si se las pasó). Aún necesita revisar app/core/model.py y app/schemas.py generados contra el archivo de referencia del Paso 3; el andamiador no llama al modelo, por lo que no puede saber cosas como el conjunto exacto de etiquetas si no pasó --id2label-json, o si un modelo NER necesita aggregation_strategy="simple". Complete cualquier marcador # TODO que deje.
Paso 5: Verificar las preocupaciones transversales de producción
Cada proyecto generado debe tener todos estos elementos; revíselos explícitamente, ya que es fácil omitirlos silenciosamente al editar manualmente el código generado:
- Modelo cargado en
lifespan, no en tiempo de importación ni por solicitud (app/main.py) - Una llamada de warm-up (una inferencia ficticia) justo después de la carga, para que la primera solicitud real no sea la lenta; consulte
references/architecture.md /health/live(proceso vivo, sin comprobaciones de dependencias) es una función diferente de/health/ready(comprueba que el modelo está cargado); combinarlas causa cascadas de reinicio, consultereferences/architecture.md- Cada respuesta de inferencia incluye el id/versión del modelo; no es negociable, es como se depura "qué modelo produjo esto" más tarde
- La entrada por lotes tiene una longitud/tamaño máximo impuesto por el servidor (
Field(..., max_length=...)); un lote sin límite es un gasto de GPU/CPU sin límite. El andamiador también limita cada cadena individual (StringConstraints(max_length=...), ajustar con--max-chars-per-text) y rechaza cuerpos de solicitud demasiado grandes a través de un middleware413enmain.py(--max-request-mb); verifique que ambos hayan sobrevivido a cualquier edición manual, ya que la comprobación del tamaño del cuerpo es la única protección que se activa antes de que el payload se analice en la memoria - La inferencia con uso intensivo de CPU/GPU se ejecuta a través de
anyio.to_thread.run_sync(...), nunca directamente en un manejadorasync def; de lo contrario, bloquea el bucle de eventos para todas las demás solicitudes en curso - Los errores de validación devuelven 422 con un mensaje útil; los errores de modelo/tiempo de ejecución se capturan y se asignan a un error HTTP tipificado, nunca un 500 no manejado con un traceback que se filtra al cliente
Consulte references/batching.md para conocer el patrón de matriz de lotes utilizado por defecto y cuándo (rara vez, para una configuración local de un solo usuario) el micro-batching dinámico valdría la complejidad añadida.
Paso 6: Pruebas
El andamiador genera tests/test_health.py y tests/test_inference.py usando fastapi.testclient.TestClient (consulte references/testing-and-evaluation.md). Léalos, ajuste la entrada de muestra/forma esperada para que coincida con el modelo real e indique al usuario que ejecute:
pytest
Paso 7: Evaluación y benchmark (opcional, solo si el usuario lo desea)
Se incluyen dos scripts independientes; cópielos en el directorio del proyecto generado (no forman parte de la propia aplicación FastAPI, son herramientas que llaman al servidor en ejecución):
scripts/evaluate.py— corrección: ejecuta un conjunto de datos etiquetado (CSV/JSONL) contra la API en ejecución e informa precisión/F1 (clasificación, NER) o comprobaciones de cordura de similitud de coseno (embeddings). Necesita los datos etiquetados del usuario; solicite una ruta, u omita esto si aún no tiene ninguno.scripts/benchmark.py— rendimiento: envía solicitudes concurrentes a la API en ejecución e informa latencia p50/p95/p99 y throughput. No necesita datos etiquetados, solo algunas entradas de ejemplo.
Consulte references/testing-and-evaluation.md para conocer el uso exacto y cómo interpretar la salida.
Paso 8: Concluir
Proporcione al usuario los comandos exactos para ejecutar localmente:
cd <output_dir>
python -m venv .venv && source .venv/bin/activate # o .venv\Scripts\activate en Windows
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000
Señálele /docs para pruebas interactivas (la interfaz OpenAPI automática de FastAPI). Indique explícitamente lo que no hizo: ninguna imagen Docker, ningún despliegue en la nube, ningún código de frontend. Si quieren algo de eso a continuación, está fuera de esta habilidad.
Solución de problemas
inspect_model.pydevuelvetask_family: unknown: los metadatos del repositorio están incompletos. Pregunte al usuario directamente cuál de las cuatro familias es y pase--taskexplícitamente al andamiador.- El modelo necesita
trust_remote_code=True/ código personalizado: indíqueselo al usuario antes de andamiar; significa que el código arbitrario del Hub se ejecuta localmente; obtenga una confirmación explícita antes de generar un proyecto que establezca esa bandera. - El usuario quiere una familia de tareas que no está en la tabla (p. ej., voz, traducción, VQA): diga claramente que esta habilidad actualmente solo cubre las cuatro familias enumeradas y ofrezca construir el wrapper FastAPI manualmente usando los mismos patrones arquitectónicos de
references/architecture.mden lugar de forzarlo en uno de los cuatro archivos de referencia. - La instalación de
requirements.txtgenerado es lenta/enorme:torchydiffusersson grandes; advierta al usuario antes de que ejecutepip installsi la familia de tareas los incluye.