Communitygithub.com

nynuz/ml-serving-skills

Una colección de habilidades de agente para servir modelos de machine learning, desde el backend de API hasta el frontend.

¿Qué es ml-serving-skills?

Esta habilidad para agentes de IA (como Claude Code, Cursor, Codex) transforma un `model_id` de Hugging Face en un proyecto FastAPI local, autónomo y de grado de producción. Soporta cuatro familias de tareas (clasificación de texto, clasificación de tokens/NER, embeddings de texto y generación de imágenes), cada una con un endpoint específico y bibliotecas subyacentes como `transformers`, `sentence-transformers` y `diffusers`. La habilidad se encarga de toda la estructura del proyecto: carga del modelo al inicio (nunca por petición), validación de entrada/salida, health probes, manejo estructurado de errores, y scripts opcionales de evaluación y benchmark. Está diseñada exclusivamente para ejecución local, sin Docker, Kubernetes, autenticación ni frontend, y se enfoca en servir modelos, no en entrenarlos. El flujo de trabajo incluye inspección del modelo, lectura de archivos de referencia específicos para cada tarea, scaffolding del proyecto, revisión manual del código generado y verificación de preocupaciones transversales de producción, como tamaño máximo de lote y ejecución asíncrona segura. La habilidad es ideal para desarrolladores que necesitan exponer rápidamente un modelo de HF como API REST local para pruebas o integración con otras herramientas.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add nynuz/ml-serving-skills

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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 tareaConcepto en HFBibliotecaArchivo de referencia
Clasificación de textoAutoModelForSequenceClassificationtransformersreferences/text-classification.md
Clasificación de tokens (NER)AutoModelForTokenClassificationtransformersreferences/token-classification-ner.md
Embeddings de textomodelo de sentence embeddingsentence-transformersreferences/embeddings.md
Generación de imágenesdiffusion pipelinediffusersreferences/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 uvicorn en 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 a 0.0.0.0 ni 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 install o inicie uvicorn si 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>-api en 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_family devuelve 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 el model_id es incorrecto/mal escrito, o el repositorio está restringido/privado. No puede indicarle cuál de los dos casos es. Primero confirme el model_id exacto 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 entorno HF_TOKEN (HF_TOKEN=hf_xxx python scripts/inspect_model.py <model_id>) o huggingface-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, consulte references/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 middleware 413 en main.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 manejador async 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.py devuelve task_family: unknown: los metadatos del repositorio están incompletos. Pregunte al usuario directamente cuál de las cuatro familias es y pase --task explí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.md en lugar de forzarlo en uno de los cuatro archivos de referencia.
  • La instalación de requirements.txt generado es lenta/enorme: torch y diffusers son grandes; advierta al usuario antes de que ejecute pip install si la familia de tareas los incluye.

Skills relacionados