Saltar al contenido principal
Capítulos de la guía de entrenamiento Toda la documentación

TrainingProject: configuración y entrenamiento

Configura un proyecto reproducible, revisa el plan, entrena un modelo local y comprueba los resultados medidos.

Capítulos de la guía de entrenamiento

Los comandos y el código se mantienen en inglés en todos los idiomas. Sustituye los marcadores en mayúsculas por valores de tu cuenta y de tu tarea de pago; no pegues claves reales en cuadernos ni registros compartidos.

Flujo de TrainingProject

Una configuración de proyecto guía la planificación, el entrenamiento, la evaluación y la exportación.
  1. Proyecto Modelo, objetivo y política de datos
  2. Plan Compatibilidad, currículo y presupuestos
  3. Ejecutar Datos, entrenamiento y puntos de control
  4. Mejorar Evaluación limitada de temas y regresiones
  5. Exportar Artefacto validado e informe reproducible

Un proyecto y un plan reproducibles

SDK 0.2.0 incluye TrainingProject y fpai-training para configurar y ejecutar entrenamiento local. El proyecto reúne el modelo alumno, el acceso al modelo de referencia, el objetivo, los datos, el entorno de ejecución, el currículo, los presupuestos y los criterios de aceptación. Revisa el plan resuelto antes de solicitar contenido al modelo de referencia o actualizar pesos. TrainingClient sigue disponible para las integraciones existentes basadas en trabajos de pago y sesiones.

  • El plan valida la configuración, la compatibilidad, las huellas de los datos, el uso compartido, los presupuestos y las salidas sin entrenar el modelo ni llamar al modelo de referencia.
  • Las interfaces de Python y la CLI usan los mismos ajustes, huellas, presupuestos y resultados.
  • Fija las revisiones del modelo, los datos y el evaluador para poder reproducir la ejecución.
Ejemplo · json 
{
  "schema_version": "1.0",
  "mode": "automatic",
  "objective": "Classify support messages as billing, account_access or technical_issue.",
  "model": {"path": "./models/student", "adapter": "transformers-causal-lm", "revision": null},
  "teacher": {"provider": "openai", "reference_model_id": 123},
  "data": {
    "sources": ["./data/train.jsonl"], "teacher_sharing": "none",
    "validation_path": "./data/validation.jsonl", "test_path": "./data/test.jsonl",
    "deduplicate": true, "seed": 42
  },
  "runtime": {"target": "customer_datacenter", "devices": "auto"},
  "training": {"method": "auto"},
  "curriculum": {"topics": ["intent", "ambiguous_requests", "class_balance"], "max_improvement_cycles": 3, "stop_on_regression": true},
  "budgets": {"max_training_minutes": 120, "max_teacher_requests": 1000, "max_storage_gib": 20},
  "checkpoints": {"keep_last": 3},
  "evaluation": {"rubric": "./rubric.json", "baseline_required": true},
  "output": {"directory": "./runs/german-001", "format": "safetensors"}
}
Ejemplo · json 
{
  "schema_version": "1.0",
  "mode": "advanced",
  "model": {"path": "./models/student", "adapter": "transformers-causal-lm", "revision": null},
  "teacher": {"provider": "openai", "reference_model_id": 123},
  "objective": "Classify support messages as billing, account_access or technical_issue.",
  "data": {"sources": ["./data/train.jsonl"], "teacher_sharing": "none", "validation_path": "./data/validation.jsonl", "test_path": "./data/test.jsonl"},
  "runtime": {"target": "customer_datacenter", "devices": [0, 1], "distributed": {"backend": "ddp", "nodes": 1}},
  "training": {
    "method": "LoRA",
    "epochs": 3,
    "learning_rate": 0.0002,
    "batch_size": 1,
    "gradient_accumulation_steps": 16,
    "max_sequence_length": 2048,
    "precision": "bf16",
    "lora": {"rank": 16, "alpha": 32, "dropout": 0.05}
  },
  "curriculum": {
    "topics": ["intent", "ambiguous_requests", "class_balance"],
    "max_improvement_cycles": 3,
    "stop_on_regression": true
  },
  "checkpoints": {"every_steps": 100, "keep_last": 3, "resume_validation": "strict"},
  "budgets": {"max_training_minutes": 120, "max_teacher_requests": 1000, "max_storage_gib": 20},
  "evaluation": {"rubric": "./rubric.json", "baseline_required": true},
  "output": {"directory": "./runs/german-advanced-001", "format": "safetensors"}
}
Ejemplo · bash 
fpai-training init --directory ./german-project
fpai-training doctor --config ./german-project/training.json
fpai-training plan --config ./german-project/training.json --dry-run
fpai-training run --config ./german-project/training.json
fpai-training status --run ./german-project/runs/german-001
fpai-training pause --run ./german-project/runs/german-001
fpai-training resume --run ./german-project/runs/german-001
fpai-training cancel --run ./german-project/runs/german-001
fpai-training evaluate --run ./german-project/runs/german-001 --split test
fpai-training export --run ./german-project/runs/german-001 --format safetensors
# init creates a project; doctor checks local compatibility; plan makes no teacher call.
# run requires current paid reference access, enforces budgets and trains locally.
# pause saves a checkpoint; resume verifies project fingerprints; cancel is terminal.
# evaluate reads local held-out rows; export validates the accepted local artifact.
Ejemplo · python 
import os
from fusionpointai_training import TrainingProject

project = TrainingProject.from_file(
    "./german-project/training.json",
    api_key=os.environ["FUSIONPOINTAI_API_KEY"],
)
plan = project.plan(dry_run=True)
result = project.run()
evaluation = project.evaluate(split="test")
artifact = project.export(format="safetensors")
# Related controls: project.status(), project.pause(), project.resume(), project.cancel().

Entrenamiento local, compatibilidad y límites

TrainingProject valida las entradas locales, mide una línea base sin modificar el modelo, realiza optimización real, evalúa criterios con datos reservados y guarda informes y manifiestos. El adaptador Transformers para modelos de lenguaje causal comprueba el modelo, el método, la precisión, el hardware, la distribución y el formato de exportación. No admite todas las arquitecturas ni todas las configuraciones de GPU. Estas comprobaciones no son un benchmark ni garantizan la calidad.

  • Los métodos admitidos son SFT, LoRA y QLoRA, siempre que sean compatibles.
  • La ejecución se limita mediante presupuestos finitos y se detiene al aceptar, agotar el presupuesto, no avanzar, cancelar o detectar una regresión.
  • No inventes métricas: los informes recogen medidas reales y criterios no satisfechos.
Ejemplo · json 
{
  "schema_version": "1.0",
  "name": "support-category-evaluation",
  "scale": {"minimum": 0.0, "maximum": 1.0},
  "criteria": [
    {"id": "support_category", "description": "Match the expected support category.", "metric": "macro_f1", "minimum_score": 0.85}
  ],
  "regression": {"maximum_score_drop": 0.02},
  "final_test": {"path": "./data/test.jsonl", "allow_training_use": false}
}
Ejemplo · text 
SDK 0.2.0 CLI AND PROJECT CONTRACT
Configuration/rubric values above are examples, not achieved scores or guarantees.
doctor must reject incompatible architecture, precision, hardware and export settings.
plan --dry-run validates and estimates; it must not update weights or start paid work.
run uses the declared data-sharing policy and enforces all configured budgets.
pause saves a valid atomic checkpoint before stopping owned training workers.
resume validates the checkpoint's model/config/data/evaluator fingerprints.
cancel requests termination of this run's workers; preserve useful logs and artifacts.
evaluate --split test must never feed test examples into training.
export validates files and manifests; never include credentials or unrelated cache files.

Project API:
TrainingProject.from_file(path, *, api_key) -> TrainingProject
plan(*, dry_run=True) -> dict
run() -> dict
status() -> dict
pause() -> dict
resume() -> dict
cancel() -> dict
evaluate(*, split="test") -> dict
export(*, format="safetensors") -> dict

Exit codes:
0 accepted/success; 2 invalid configuration; 3 incompatible runtime/model;
4 authentication/access; 5 budget exhausted; 6 acceptance not met;
7 execution failed; 130 interrupted.
Reports must record stop_reason and unmet criteria, not just an exit code.

Evaluar y exportar los resultados

La evaluación usa filas locales de validación o de prueba final y mide cada criterio de la rúbrica con una métrica determinista registrada y un umbral mínimo. Los informes conservan las medidas, regresiones, huellas, presupuestos y requisitos pendientes. La exportación valida un modelo safetensors local o un paquete de adaptador y genera un manifiesto. Un adaptador sigue necesitando su modelo base y tokenizador exactos y fijados. Un resultado aceptado no demuestra calidad más allá de los criterios medidos.

  • Mantén los datos de prueba final separados del entrenamiento y de las solicitudes al modelo de referencia.
  • Revisa el informe de evaluación y el manifiesto antes de usar los archivos.
  • La exportación no sube el modelo ni despliega inferencia en producción.
Ejemplo · text 
TrainingProject delivery files
model/                   validated model or adapter weights and tokenizer assets
exports/<format>/        accepted delivery files with a SHA-256 manifest
run-manifest.json        pinned model/data/config/runtime versions
baseline-report.json     untouched student model's measured criteria
evaluation-report.json   final criteria, measured scores and regressions
artifact-manifest.json   safe relative paths, bytes and SHA-256 per file
training-report.json     real steps, timings, budgets and stop reason

Never export credentials, environment files or private cache directories.