API de entrenamiento

Lanza un fine-tuning con LoRA en una GPU rentada. El entrenamiento corre solo en la máquina y termina en un adapter que descargas o publicas.

Antes de empezar

Una API Key.
Nombre completo, teléfono y correo confirmado en tu perfil.
Créditos para al menos una hora de la GPU que elijas. Se recargan en Facturación.
Un dataset en ChatML. Ve cómo crearlo en API de datasets.

Elige una GPU

bash

curl "https://app.astrapp.lat/api/v1/gpu/offers?min_gpu_ram=24&limit=10" \
  -H "Authorization: Bearer $ASTRAPP_API_KEY"

La respuesta trae las ofertas en data. De cada una te sirven id (el offerId), gpu_name, gpu_vram_gb, price_per_hour (en USD, lo que pagas) y plan_restricted: una oferta restringida no la puedes rentar con tu plan. Qué GPUs entran en cada plan está en GPUs por plan.

Lanza en los siguientes 5 minutos

El precio de cada oferta se guarda 5 minutos. Pasado ese tiempo, o si la buscaste filtrando por gpu_name, num_gpus, precio o location (esas búsquedas no guardan precios), el lanzamiento puede responder 409 OFFER_UNAVAILABLE. No se te cobra nada: vuelve a buscar y lanza de inmediato.

Lanza el entrenamiento

bash

curl -X POST https://app.astrapp.lat/api/v1/gpu/instances/training \
  -H "Authorization: Bearer $ASTRAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "offerId": 12345678,
    "modelId": "qwen-3-8b",
    "modelHuggingfaceId": "Qwen/Qwen3-8B",
    "modelParameterValue": 8,
    "modelChatTemplate": "chatml",
    "datasetId": "8d2b6f41-0a3c-4e59-b7d8-21f5c9043ae6",
    "trainingName": "Bot de ventas v1",
    "hyperparameters": {
      "epochs": 3,
      "learningRate": 0.0002,
      "batchSize": 4
    },
    "autoShutdownHours": 6
  }'

json

{
  "success": true,
  "data": {
    "instanceId": "b45e7a10-9c38-4f2d-8e61-05ad3b7c9241",
    "trainingJobId": "c7d1e2f3-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "vastaiInstanceId": 23456789,
    "gpu": "RTX 4090",
    "pricePerHour": 0.48,
    "status": "creating",
    "trainingName": "Bot de ventas v1"
  },
  "message": "Entrenamiento lanzado. La máquina estará lista en unos minutos."
}

La ruta admite 12 lanzamientos por hora. Las validaciones corren antes de rentar la máquina: si la ruta rechaza el lanzamiento, no se te cobra nada.

Sigue el entrenamiento

La máquina descarga el modelo, entrena y reporta su progreso sola. Con la misma API Key puedes seguirla:

GET /training/history lista tus entrenamientos, del más reciente al más antiguo, con status, progress, errorMessage y el adapter cuando termina. Acepta page, limit (hasta 100), status y provider=vastai.
GET /gpu/instances/{instanceId}, con el instanceId de la respuesta, trae el estado de la máquina, sus horas y su costo.
DELETE /gpu/instances/{instanceId} destruye la máquina y cobra el tiempo que falte por facturar.

Consultar un entrenamiento por su id (GET /training-jobs/{jobId}) y cancelarlo (POST /training/{jobId}/cancel) todavía solo funcionan con la sesión de la app. En la app también lo ves:

El progreso y el resultado, en Entrenar › Historial de entrenamientos.
La máquina, en Rentar GPU › Mis instancias.
El adapter terminado, en Archivos › Adaptadores LoRA. Descargarlo requiere Professional. Más en Adaptadores LoRA.

Al terminar, fallar o cancelarse el entrenamiento, AstrApp libera la máquina. Con autoShutdownHours pones además un tope de horas por si algo se atora.

Cuerpo de la petición

Campo	Tipo	Requerido	Descripción
`offerId`	number	Sí	El id de la oferta de GPU que elegiste en /gpu/offers.
`modelId`	string	Sí	Id del modelo en el catálogo de AstrApp, como qwen-3-8b.
`modelHuggingfaceId`	string	Sí	Repo base del modelo, como Qwen/Qwen3-8B. Debe estar en el catálogo.
`modelParameterValue`	number	Sí	Tamaño del modelo en miles de millones de parámetros (8 para un 8B).
`modelChatTemplate`	string	Sí	Plantilla de chat del modelo, como chatml.
`trainingName`	string	Sí	Nombre del entrenamiento, de 1 a 200 caracteres.
`hyperparameters`	object	Sí	Ver la tabla de abajo. Puede ir vacío ({}) para usar los valores por defecto.
`datasetId`	string	Uno de los tres	UUID de un dataset tuyo.
`datasetStoragePath`	string	Uno de los tres	La ruta que devuelve /datasets/upload.
`hfDatasetId`	string	Uno de los tres	Id de un dataset público de Hugging Face.
`projectId`	string	No	UUID del proyecto donde se registra el entrenamiento.
`trainingMethod`	string	No	unsloth, lora o qlora. Por defecto unsloth.
`image`	string	No	Imagen de la máquina. Por defecto astrapp, la única probada de punta a punta.
`diskSize`	number	No	Disco en GB, de 10 a 2000. Por defecto 50.
`autoShutdownHours`	number	No	Apaga la máquina tras estas horas, de 0 a 48.
`enableEvaluation`	boolean	No	Corre una evaluación al terminar. Por defecto false.
`evalSplitRatio`	number	No	Fracción del dataset que se aparta para evaluar, de 0.01 a 0.5.
`evalDatasetId`	string	No	UUID de un dataset aparte para evaluar.
`hfRepoId`	string	No	Repo de Hugging Face donde publicar el adapter.
`autoPushHF`	boolean	No	Publica el adapter en hfRepoId al terminar. Por defecto false.
`ggufQuantizations`	string[]	No	Hasta 5 cuantizaciones GGUF a generar.

El esquema es estricto: un campo que no está en esta tabla, o un nombre en otro formato como learning_rate, hace que la ruta responda 400. Solo se entrenan modelos del catálogo con licencia Apache 2.0 o MIT; elige uno en ¿Qué modelo usar?.

hyperparameters

Campo	Por defecto	Rango
`learningRate`	2e-4	De 1e-7 a 1.
`epochs`	3	De 1 a 20.
`batchSize`	4	De 1 a 128.
`loraR`	Opcional	Rango de LoRA, de 1 a 256.
`loraAlpha`	Opcional	De 1 a 512.
`loraDropout`	Opcional	De 0 a 1.
`maxSeqLength`	Opcional	Tokens por ejemplo, de 128 a 131072.
`warmupRatio`	Opcional	De 0 a 1.
`weightDecay`	Opcional	De 0 a 1.
`gradientAccumulationSteps`	Opcional	De 1 a 64.
`maxGradientNorm`	Opcional	De 0 a 10.
`lrSchedulerType`	Opcional	linear, cosine o constant.

Qué mueve cada uno está en Hiperparámetros.

Por qué se rechaza un lanzamiento

Estado	Motivo
403	Tu perfil no tiene nombre completo o teléfono, o tu correo no está confirmado.
403	Tus créditos no alcanzan para una hora de la GPU elegida.
400	La GPU no tiene la VRAM que pide el modelo, o el disco no alcanza.
400	El modelo no está en el catálogo o su licencia no es Apache 2.0 ni MIT.
400	Falta el dataset, o el dataset no tiene conversaciones válidas.
409	La oferta ya no está en la caché de precios (OFFER_UNAVAILABLE). Vuelve a buscar ofertas.

El mensaje de cada error dice qué corregir. El formato está en Códigos de error.

No uses la ruta antigua

POST /api/v1/projects/{projectId}/training no entrena

Esa ruta solo crea un registro en estado pending: nada lo ejecuta, y a los 10 minutos el barrido de trabajos lo marca como fallido con el mensaje Job expiró sin respuesta (timeout automático). Además lee con la sesión, así que con una API Key responde 404.

Sus campos tampoco sirven aquí: usa snake_case (learning_rate, batch_size, gpu_type) y la ruta de GPU los rechaza. Lo mismo aplica al stream /api/v1/training/{jobId}/stream, que pertenece a ese flujo.

Configurar desde la app

Si prefieres elegir modelo, dataset y GPU con ayuda visual, usa Entrenar › Entrenar modelo: lanza este mismo entrenamiento. La guía paso a paso está en Entrenamiento.