Documentación

Ajuste fino

laya.train se importa por su cuenta (from laya.train import finetune, TrainConfig); no se reexporta desde el paquete de nivel superior. laya-train es su línea de comandos. La guía de ajuste fino muestra ambos en uso.

Ejecutar un ajuste fino

Los nombres, los tipos, los valores por defecto y el código se mantienen en inglés; el resto está traducido (las entradas aún sin traducir se muestran en el original).

TrainConfig

TrainConfig()

Perillas de entrenamiento. Los valores por defecto entrenan como lo hace el notebook publicado.

El lote efectivo de 64 del notebook es 8 por micro-lote x 2 GPUs x 4 pasos de acumulación; en un solo dispositivo eso es micro_batch=8, grad_accum=8.

max_len / head_max_len toman por defecto la propia config del checkpoint. Lo que se use se escribe en la config guardada, así que la inferencia ve los mismos presupuestos que el entrenamiento. amp está activado por defecto solo para CUDA; gradient_checkpointing por defecto sigue a amp. option_layout toma por defecto el del propio checkpoint ("sequential" en todos los publicados); "parallel" entrena sobre common.parallel_layout y se escribe en la config guardada.

finetune

finetune(
    data: str,
    model_dir: str,
    output_dir: str,
    config: Optional[TrainConfig] = None,
    device: Optional[str] = "auto",
) -> Dict[str, Any]

Preprocesa, entrena, calibra y guarda; devuelve un resumen de la ejecución.

data es un archivo JSONL de filas {state, questions, gold} o {state, questions, expected}, o un archivo CSV con columnas de texto y etiqueta. model_dir es un directorio de checkpoint local -- la disposición que lee laya.load. El resultado en output_dir se carga con laya.load(output_dir).

Parámetros

datastr
model_dirstr
output_dirstr
configOptional[TrainConfig]= None
deviceOptional[str]= "auto"

dry_run

dry_run(
    data: str,
    model_dir: str,
    config: Optional[TrainConfig] = None,
) -> Dict[str, Any]

Inspecciona el conjunto de datos y construye elementos sin cargar los pesos del modelo; devuelve estadísticas del conjunto.

Parámetros

datastr
model_dirstr
configOptional[TrainConfig]= None

Las dos mitades de finetune

train_model

train_model(
    model,
    tok,
    items: Sequence[Dict[str, Any]],
    config: TrainConfig,
    device: torch.device,
    max_len: int,
    head_max_len: int,
    on_epoch_end: Optional[Callable[[int, float], None]] = None,
    parallel: bool = False,
) -> List[float]

Entrena model in situ sobre items; devuelve la pérdida media de cada época.

Parámetros

model
tok
itemsSequence[Dict[str, Any]]
configTrainConfig
devicetorch.device
max_lenint
head_max_lenint
on_epoch_endOptional[Callable[[int, float], None]]= None
parallelbool= False

calibration_records

calibration_records(
    model,
    tok,
    items: Sequence[Dict[str, Any]],
    device: torch.device,
    max_len: int,
    head_max_len: int,
    batch_size: int = 16,
    parallel: bool = False,
)

Registros (qtype, logits, target, k) para fit_temperature_map, con las opciones en orden canónico.

Parámetros

model
tok
itemsSequence[Dict[str, Any]]
devicetorch.device
max_lenint
head_max_lenint
batch_sizeint= 16
parallelbool= False

calibration_report

calibration_report(
    records: Sequence[Tuple[int, Any, Any, int]],
    temperature: Sequence[float],
) -> Dict[str, Dict[str, Any]]

Por tipo de pregunta: cuántos elementos de calibración había, qué se ajustó y de qué dudar.

records son los calibration_records sobre los que se ajustaron las temperaturas, y temperature los escalares por tipo que devolvió fit_temperature_map. Cada tipo recibe items, temperature, accuracy y mean_confidence (probabilidad superior a la temperatura ajustada) sobre los elementos de calibración, y una lista de issues, vacía cuando nada parece ir mal:

  • menos de MIN_TYPE_N elementos: la temperatura no se ajustó y se queda en 1.0;
  • menos de CALIB_WARN_N elementos: se ajustó, con poca evidencia;
  • aterrizó en el recorte [TEMP_MIN, TEMP_MAX];
  • volvió sin cambios en 1.0 aunque se ajustó, lo que normalmente significa que los elementos no dieron al ajuste nada que corregir -- lo que produce un modelo que ya está seguro y en lo correcto con ellos.

Un tipo sin ningún elemento de calibración no tiene issues; no estaba en los datos.

Parámetros

recordsSequence[Tuple[int, Any, Any, int]]
temperatureSequence[float]

Leer datos

read_data

read_data(
    path: str,
    text_column: str = "text",
    label_column: str = "label",
    question_id: str = "label",
    instructions: Optional[str] = None,
) -> List[Dict[str, Any]]

Lee filas de entrenamiento/evaluación desde un archivo JSONL o un archivo CSV.

Parámetros

pathstr
text_columnstr= "text"
label_columnstr= "label"
question_idstr= "label"
instructionsOptional[str]= None

rows_from_csv

rows_from_csv(
    path: str,
    text_column: str = "text",
    label_column: str = "label",
    question_id: str = "label",
    instructions: Optional[str] = None,
) -> List[Dict[str, Any]]

Lee un archivo CSV con una columna etiquetada por fila en filas {state, questions, expected}.

Descubre las etiquetas distintas en label_column (preservando el orden de aparición) y construye una pregunta choice con esas etiquetas como lista de criteria para renderizar cada opción una vez. Usa la codificación utf-8-sig para que las cabeceras UTF-8 BOM de Excel se manejen de forma transparente.

Parámetros

pathstr
text_columnstr= "text"
label_columnstr= "label"
question_idstr= "label"
instructionsOptional[str]= None

Construir elementos de entrenamiento

items_from_rows

items_from_rows(
    tok,
    rows: Iterable[Dict[str, Any]],
    max_len: int,
    head_max_len: int,
    label_smoothing: float = 0.0,
) -> Tuple[List[Dict[str, Any]], Dict[str, int]]

Elementos a partir de filas {state, questions, gold} o {state, questions, expected}; devuelve (items, skipped).

skipped cuenta, por motivo, las preguntas que estaban etiquetadas pero no pudieron convertirse en un elemento: empty_text, empty_label, invalid_question e invalid_target (un ValueError de to_internal, target_from_gold o target_from_expected), más los motivos que da make_item. Las preguntas sin una entrada gold ni expected no se cuentan -- la fila simplemente no las etiqueta.

Parámetros

tok
rowsIterable[Dict[str, Any]]
max_lenint
head_max_lenint
label_smoothingfloat= 0.0

target_from_gold

target_from_gold(q: Dict[str, Any], gold_q: Dict[str, Any]) -> List[float]

La distribución objetivo normalizada para una pregunta interna (to_internal), en orden de opciones.

gold_q["probabilities"] se indexa por etiqueta de choice, por "false"/"true" para noul, y por el índice de nivel como cadena para score -- el esquema {state, questions, gold} de docs/finetune.md. Una etiqueta de choice que no es cadena también se busca como su clave JSON. Una fila cuyas probabilidades suman cero se vuelve uniforme, como en los scripts. Una probabilidad negativa o no finita lanza ValueError.

Parámetros

qDict[str, Any]
gold_qDict[str, Any]

target_from_expected

target_from_expected(
    q: Dict[str, Any],
    expected_val: Any,
    label_smoothing: float = 0.0,
) -> List[float]

La distribución objetivo normalizada a partir de una sola respuesta esperada, en orden de opciones.

expected_val es:

  • una etiqueta de choice (str o valor que coincide con un criterio) para preguntas choice
  • un booleano para preguntas noul
  • un índice de nivel entero o una cadena de nivel para preguntas score

Cuando label_smoothing > 0, suaviza la masa de probabilidad de forma uniforme: target[i] = (1 - eps) * one_hot[i] + eps / K.

Parámetros

qDict[str, Any]
expected_valAny
label_smoothingfloat= 0.0

to_internal

to_internal(qid: Any, question: Dict[str, Any]) -> Dict[str, Any]

La pregunta tal como la ve la inferencia: Agent._check_question y luego Agent._to_internal.

Entrenar sobre cualquier otra representación enseñaría al modelo textos de opciones que nunca ve en la inferencia -- una choice en forma de lista, labels personalizados de noul, una instrucción no textual.

Parámetros

qidAny
questionDict[str, Any]

make_item

make_item(
    tok,
    q: Dict[str, Any],
    target: Sequence[float],
    state_ids: List[int],
    head_max_len: int,
    max_len: Optional[int] = None,
) -> Tuple[Optional[Dict[str, Any]], Optional[str]]

(item, None), o (None, reason) cuando la pregunta no se puede entrenar tal como está escrita.

q es una pregunta interna (to_internal). Los motivos son target_mismatch (el objetivo no tiene una entrada por opción), options_collapsed (el presupuesto del head dejó dos opciones con el mismo tramo de tokens, #538) y, cuando se da max_len, options_beyond_max_len (el head es más largo que max_len, así que build_sequence descarta los marcadores de las últimas opciones -- el caso que Agent rechaza en la inferencia con "only N of its M option markers fit"). Entrenar sobre cualquiera de ellos enseñaría al modelo a distinguir opciones que no puede ver como distintas, o reventaría el lote con un objetivo más largo que sus marcadores.

Parámetros

tok
qDict[str, Any]
targetSequence[float]
state_idsList[int]
head_max_lenint
max_lenOptional[int]= None

encode_item

encode_item(
    tok,
    item: Dict[str, Any],
    max_len: int,
    head_max_len: int,
    option_order: Optional[List[int]] = None,
    parallel: bool = False,
) -> Dict[str, Any]

La entrada del modelo para un elemento, con las opciones en option_order y el objetivo a igualar.

build_sequence pone la opción option_order[s] en la ranura s, así que el objetivo ordenado por ranura es target[option_order[s]] -- el inverso de lo que hace unpermute_probs en la inferencia.

Parámetros

tok
itemDict[str, Any]
max_lenint
head_max_lenint
option_orderOptional[List[int]]= None
parallelbool= False

draw_option_order

draw_option_order(
    item: Dict[str, Any],
    rng: random.Random,
    shuffle_types: Sequence[str],
) -> Optional[List[int]]

Una permutación aleatoria para elementos cuyo tipo está en shuffle_types, si no None (canónico).

Parámetros

itemDict[str, Any]
rngrandom.Random
shuffle_typesSequence[str]

split_calibration

split_calibration(
    items: Sequence[Any],
    calib_max: int,
    calib_frac: float,
    seed: int,
) -> Tuple[List[Any], List[Any]]

(train, calibration), con la porción de calibración tomada antes de cualquier entrenamiento.

Ajustar temperaturas sobre elementos con los que la ejecución se ha entrenado mide el ajuste, no la calibración (docs/finetune.md). La división depende solo de seed y del número de elementos, así que cada rango DDP y cada repetición reservan los mismos elementos.

Parámetros

itemsSequence[Any]
calib_maxint
calib_fracfloat
seedint

Pérdidas

soft_ce_loss

soft_ce_loss(
    logits: torch.Tensor,
    target: torch.Tensor,
    mask: torch.Tensor,
) -> torch.Tensor

Entropía cruzada contra una distribución objetivo, solo sobre las opciones propias de cada fila.

Parámetros

logitstorch.Tensor
targettorch.Tensor
masktorch.Tensor

rlcd_loss

rlcd_loss(
    logits: torch.Tensor,
    target: torch.Tensor,
    mask: torch.Tensor,
    qtype: torch.Tensor,
    sigma: float,
    samples: int = 4,
    w_sph: float = 0.75,
    w_rps: float = 1.0,
) -> torch.Tensor

El objetivo del notebook: un término de gradiente de política sobre logits ruidosos más entropía cruzada suave.

Se añade ruido gaussiano de media cero (escalado por sigma, proyectado sobre las opciones de cada fila) a logits separados; cada muestra se recompensa con proper_reward contra el objetivo, y la ventaja normalizada pondera la log-densidad gaussiana de la muestra.

Parámetros

logitstorch.Tensor
targettorch.Tensor
masktorch.Tensor
qtypetorch.Tensor
sigmafloat
samplesint= 4
w_sphfloat= 0.75
w_rpsfloat= 1.0

Checkpoints

resolve_checkpoint_dir

resolve_checkpoint_dir(model_id_or_path: str, token: Optional[str] = None) -> str

Resuelve una ruta local, un alias de modelo ('multilingual', 'english') o un id de repo del Hub a un directorio local.

Parámetros

model_id_or_pathstr
tokenOptional[str]= None

load_checkpoint

load_checkpoint(model_dir: str)

(model, tokenizer, cfg) desde un directorio de checkpoint local o un id del Hub, modelo en CPU en fp32.

Parámetros

model_dirstr

save_checkpoint

save_checkpoint(model, tok, cfg: Dict[str, Any], path: str) -> None

Escribe la disposición que lee laya.load: pesos en fp16, config del encoder, tokenizer, config.

Parámetros

model
tok
cfgDict[str, Any]
pathstr