Referencia de configuración del proyecto TrainingProject

Definir un proyecto y proteger sus datos

Este es el contrato de proyecto del esquema 1.0. Guarda el ejemplo del modo Automático como training.json. Resuelve las rutas dentro de la raíz del proyecto, indica el ID del modelo de referencia incluido y guarda la clave de API en el entorno del proceso. La configuración selecciona un modelo de referencia de pago y un modelo alumno que se entrena de forma independiente; nunca descarga los pesos del modelo de referencia.

Se rechazan las claves desconocidas. Las rutas del modelo, los datos, la rúbrica y los resultados deben quedar dentro de la raíz del proyecto.
El uso compartido con el modelo de referencia se limita a las fuentes de entrenamiento aprobadas. Los datos de validación y de prueba final permanecen locales.
TrainingClient sigue disponible para los flujos existentes de trabajos de pago y sesiones.

Proyecto, modelo y modelo docente
Campo o interfaz	Tipo o resultado	Valor predeterminado o código de salida	Comportamiento y validación
`schema_version`	`string`	`"1.0"`	Usa exactamente 1.0. Se rechazan otras versiones del esquema hasta que se admitan expresamente.
`mode`	`enum`	Obligatorio / sin valor predeterminado	Obligatorio: `automatic` o `advanced`. El modo Automático resuelve valores predeterminados compatibles; el modo Avanzado ofrece controles explícitos.
`objective`	`string`	Obligatorio / sin valor predeterminado	Descripción de tarea obligatoria, de 10 a 4000 caracteres. Indica el público, las capacidades y el resultado esperado.
`model.path`	`string`	Obligatorio / sin valor predeterminado	Ruta obligatoria a un modelo local dentro del directorio del proyecto, o identificador de repositorio asociado a una revisión inmutable. Nunca un endpoint de inferencia del modelo de referencia.
`model.adapter`	`string`	Obligatorio / sin valor predeterminado	ID obligatorio de un adaptador registrado. transformers-causal-lm selecciona el adaptador Transformers para modelos de lenguaje causal.
`model.revision`	`string \| null`	`null`	Los modelos locales se identifican mediante huellas. Los repositorios requieren una revisión inmutable de 40 o 64 caracteres.
`teacher.provider`	`string`	Obligatorio / sin valor predeterminado	Identificador obligatorio del proveedor incluido en tu plan de pago activo. No transfiere la propiedad del modelo.
`teacher.reference_model_id`	`integer`	Obligatorio / sin valor predeterminado	Número entero positivo obligatorio de los modelos incluidos en ese plan del proveedor; sustituye los marcadores.

Datos y privacidad
Campo o interfaz	Tipo o resultado	Valor predeterminado o código de salida	Comportamiento y validación
`data.sources`	`string[]`	`[]`	Rutas a fuentes locales de entrenamiento JSONL con un campo text. Las lecciones del modelo de referencia pueden complementarlas si teacher_sharing es approved_only.
`data.teacher_sharing`	`enum`	`"approved_only"`	approved_only permite contenido de entrenamiento revisado; none prohíbe enviar contenido de clientes al docente. Los datos de evaluación reservados siempre se excluyen.
`data.validation_path`	`string \| null`	`null`	Ruta opcional a JSONL de validación independiente. Si no se especifica, el plan revisado define una partición determinista antes del entrenamiento.
`data.test_path`	`string`	Obligatorio / sin valor predeterminado	Archivo de prueba final independiente obligatorio; nunca se usa en la preparación del docente ni en la optimización.
`data.deduplicate`	`boolean`	`true`	Elimina ejemplos duplicados o solapados entre particiones e informa de las exclusiones sin revelar texto privado.
`data.seed`	`integer`	`42`	Número entero no negativo para particiones deterministas e inicialización reproducible cuando el backend lo admita.

{
  "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"}
}

Elegir el modo de entrenamiento automático o avanzado

El modo automático resuelve ajustes compatibles una sola vez y los registra en el plan revisado. El modo avanzado requiere ajustes explícitos y acepta solo combinaciones compatibles de arquitectura, método, precisión y hardware. Los valores predeterminados no garantizan el uso de memoria ni el rendimiento en todos los casos. Las combinaciones no compatibles fallan antes de descargar archivos grandes o actualizar los pesos.

SFT actualiza parámetros aptos del modelo. LoRA y QLoRA generan adaptadores y requieren el modelo base correspondiente.
En DDP, el lanzador aprobado proporciona los rangos de los nodos y la configuración de rendezvous; todos deben coincidir en el número de procesos, las versiones y las huellas.
La arquitectura, el tokenizador y los límites de contexto del modelo siguen siendo obligatorios. Cada familia adicional necesita un adaptador con capacidades propias comprobadas.

Entorno de ejecución y distribución
Campo o interfaz	Tipo o resultado	Valor predeterminado o código de salida	Comportamiento y validación
`runtime.target`	`enum`	Obligatorio / sin valor predeterminado	Obligatorio: fusionpointai_hosting, customer_datacenter o colab. Selecciona un entorno existente; no compra hardware.
`runtime.devices`	`"auto" \| integer[]`	`"auto"`	auto selecciona dispositivos aprobados compatibles; una lista explícita contiene índices GPU visibles, únicos y no negativos.
`runtime.distributed.backend`	`enum`	`"none"`	none para un proceso o ddp con un adaptador compatible y un lanzador multiworker aprobado.
`runtime.distributed.nodes`	`integer`	`1`	Número entero positivo. Más de uno requiere DDP, acceso acordado a los nodos, rangos y un encuentro seguro; este valor no asigna capacidad.

Ajustes de entrenamiento
Campo o interfaz	Tipo o resultado	Valor predeterminado o código de salida	Comportamiento y validación
`training.method`	`enum`	`"auto"`	Uno de estos valores: auto, SFT, LoRA o QLoRA. El modo automático resuelve auto; el modo avanzado usa un método explícito compatible.
`training.epochs`	`number \| "auto"`	`"auto"`	Número positivo finito o auto únicamente en modo Automático; el número efectivo de pasos también queda limitado por el tiempo y los recursos aprobados.
`training.learning_rate`	`number \| "auto"`	`"auto"`	Número positivo finito inferior a 1 o auto únicamente en modo Automático. Las políticas comerciales y del adaptador pueden imponer límites más estrictos.
`training.batch_size`	`integer \| "auto"`	`"auto"`	Número entero positivo por dispositivo o auto únicamente en modo Automático; la adecuación a la memoria se comprueba antes de ejecutar.
`training.gradient_accumulation_steps`	`integer \| "auto"`	`"auto"`	Número entero positivo o auto únicamente en modo Automático. El tamaño efectivo del lote incluye el número de procesos y la acumulación.
`training.max_sequence_length`	`integer \| "auto"`	`"auto"`	Número entero positivo dentro de los límites del tokenizador y el modelo, o auto únicamente en modo Automático; nunca amplía el contexto del modelo de forma silenciosa.
`training.precision`	`enum`	`"auto"`	auto, fp32, fp16 o bf16 según el hardware y el backend; explícito en modo Avanzado.
`training.lora.rank`	`integer`	`16`	Rango positivo del adaptador. Solo se usa con LoRA/QLoRA y módulos de destino aptos.
`training.lora.alpha`	`number`	`32`	Valor positivo finito de escala del adaptador. Solo se usa con LoRA/QLoRA.
`training.lora.dropout`	`number`	`0.05`	Valor finito desde 0 inclusive hasta 1 exclusive. Solo se usa con LoRA/QLoRA.
`training.lora.target_modules`	`"auto" \| string[]`	`"auto"`	auto resuelve los nombres de módulos compatibles en el plan; también puedes proporcionar una lista no vacía de nombres aptos.

Controles del currículo
Campo o interfaz	Tipo o resultado	Valor predeterminado o código de salida	Comportamiento y validación
`curriculum.topics`	`string[]`	`[]`	Nombres de temas ordenados. Si está vacío, el modo Automático puede proponer requisitos previos; el modo Avanzado exige una secuencia explícita y revisada.
`curriculum.max_improvement_cycles`	`integer`	`3`	Número entero positivo, máximo 10. Detente antes si se aplican condiciones de presupuesto agotado, falta de progreso o regresión.
`curriculum.stop_on_regression`	`boolean`	`true`	Si es true, detiene la mejora ante una regresión definida por la rúbrica. Si es false, la regresión sigue haciendo que falle la aceptación final.

{
  "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"}
}

Establecer presupuestos finitos y criterios de aceptación medibles

Cada proyecto tiene presupuestos explícitos de tiempo, solicitudes al docente y almacenamiento. Detente cuando se agote el primer presupuesto, falle una comprobación de integridad, haya una regresión o no se avance. Guarda un estado de recuperación válido y explica los criterios no cumplidos. Una rúbrica define tareas de aceptación independientes; no convierte una puntuación de ejemplo en un resultado conseguido.

La rúbrica de ejemplo usa una escala normalizada de 0 a 1 y criterios obligatorios separados. Deben cumplirse todos los criterios obligatorios.
Cambiar los datos, el modelo, la evaluación, la topología o los presupuestos requiere un nuevo plan revisado, no forzar una reanudación incompatible.
Las exportaciones contienen archivos validados del modelo o del adaptador, el tokenizador y los manifiestos; no credenciales, datos de caché ajenos ni código de modelo sin revisar.

Presupuestos, recuperación y resultados
Campo o interfaz	Tipo o resultado	Valor predeterminado o código de salida	Comportamiento y validación
`budgets.max_training_minutes`	`number`	Obligatorio / sin valor predeterminado	Presupuesto de ejecución obligatorio, positivo y finito, en minutos; incluye el tiempo real de preparación y evaluación desde el inicio de la ejecución.
`budgets.max_teacher_requests`	`integer`	Obligatorio / sin valor predeterminado	Número entero positivo obligatorio; cuenta los intentos de preparación, revisión y reintento. Falla de forma segura antes de superarlo.
`budgets.max_storage_gib`	`number`	Obligatorio / sin valor predeterminado	Presupuesto obligatorio, positivo y finito de almacenamiento propio en GiB; incluye datos, puntos de control y artefactos. No borres archivos ajenos.
`checkpoints.every_steps`	`integer`	`100`	Intervalo positivo de pasos entre puntos de control. También guarda un punto de control atómico válido al pausar correctamente.
`checkpoints.keep_last`	`integer`	`3`	Número entero del 1 al 5. Elimina solo puntos de control propios obsoletos, después de validar uno más reciente.
`checkpoints.resume_validation`	`enum`	`"strict"`	Solo strict. Rechaza cambios en las huellas del modelo, los datos, la configuración, el evaluador o la topología distribuida.
`evaluation.rubric`	`string`	Obligatorio / sin valor predeterminado	Ruta obligatoria a una rúbrica válida con evaluadores fijados y criterios obligatorios medibles.
`evaluation.baseline_required`	`boolean`	`true`	Solo true en este contrato. Evalúa la línea base intacta antes de actualizar los pesos.
`output.directory`	`string`	Obligatorio / sin valor predeterminado	Directorio nuevo y propio para la ejecución, obligatorio. Las ejecuciones existentes pueden inspeccionarse o reanudarse, pero `run` nunca las sobrescribe.
`output.format`	`enum`	`"safetensors"`	safetensors o adapters, solo si son compatibles. Las exportaciones de adaptadores requieren el modelo base y el tokenizador fijados.

Campos de la rúbrica de evaluación
Campo o interfaz	Tipo o resultado	Valor predeterminado o código de salida	Comportamiento y validación
`schema_version`	`string`	`"1.0"`	Esquema de rúbrica 1.0, distinto de la versión del paquete.
`name`	`string`	Obligatorio / sin valor predeterminado	Nombre de rúbrica obligatorio y no vacío que se usa en los informes.
`scale.minimum`	`number`	`0`	Límite inferior de puntuación normalizada: 0 para este esquema.
`scale.maximum`	`number`	`1`	Límite superior de puntuación normalizada: 1 para este esquema.
`criteria`	`object[]`	Obligatorio / sin valor predeterminado	Lista no vacía. Deben cumplirse todos los criterios obligatorios; los ID deben ser únicos.
`criteria[].id`	`string`	Obligatorio / sin valor predeterminado	Identificador de criterio estable obligatorio, conservado en los informes.
`criteria[].description`	`string \| null`	`null`	Texto explicativo opcional. La descripción no es un evaluador semántico.
`criteria[].metric`	`string`	Obligatorio / sin valor predeterminado	Métrica registrada obligatoria: exact_match, macro_f1, text_similarity, chrf o un evaluador personalizado registrado.
`criteria[].minimum_score`	`number`	Obligatorio / sin valor predeterminado	Umbral obligatorio, finito y entre 0 y 1. Un umbral de ejemplo no garantiza un resultado.
`regression.maximum_score_drop`	`number`	`0.02`	Descenso absoluto normalizado máximo permitido respecto a la línea base intacta, de 0 a 1; se evalúa para cada criterio conservado.
`final_test.path`	`string`	Obligatorio / sin valor predeterminado	Obligatorio; debe identificar el mismo archivo independiente que data.test_path.
`final_test.allow_training_use`	`boolean`	`false`	Solo false. Rechaza configuraciones que permitan que las respuestas de prueba reservadas entren en el entrenamiento o en las entradas del docente.

SDK 0.2.0 CONFIGURATION RULES
Unknown fields, duplicate IDs, nonfinite numbers and unsafe paths are rejected.
All model, data, rubric and output paths must resolve inside the project root.
Automatic mode resolves "auto" once; save all resolved values in the plan manifest.
Advanced mode requires explicit method, epochs, learning_rate, batch_size,
gradient_accumulation_steps, max_sequence_length and precision.
SFT does not consume LoRA options. LoRA/QLoRA require a compatible adapter.
Model files and pinned revisions are verified within the project root.
Use the CLI for explicit GPU indexes; Python callers can set CUDA_VISIBLE_DEVICES
before starting Python and keep runtime.devices set to auto.
No automatic execution of untrusted model code, shell commands or plugins.
All three budgets must be finite, positive and explicitly supplied.
Storage includes owned checkpoints, datasets and artifacts, not unrelated files.
Held-out test data must not be sent to the teacher or used for weight updates.
CLI overrides are limited to the documented flags; never silently override a plan.
RUBRIC RULES
Every criterion requires a registered metric and minimum_score; descriptions are not semantic evaluators.
Built-in metrics: exact_match, macro_f1, text_similarity and chrf.
Custom deterministic scorers use register_evaluator(name, scorer, version="...").
Evaluator versions and scoring configuration are pinned in the plan.
0 <= minimum_score <= 1 for the example's normalized scale.
All required criteria must pass; do not average away a failed criterion.
The final_test.path must match data.test_path; allow_training_use must be false.
Scores and budgets in examples are requested settings, not measured results.

De la configuración a una ejecución reproducible

Definir un proyecto y proteger sus datos

Elegir el modo de entrenamiento automático o avanzado

Establecer presupuestos finitos y criterios de aceptación medibles

Continuar el flujo de trabajo