Documentation

Ajustement fin

laya.train s’importe à part (from laya.train import finetune, TrainConfig) ; il n’est pas ré-exporté depuis le paquet de premier niveau. laya-train est sa ligne de commande. Le guide d’ajustement fin montre les deux à l’usage.

Exécuter un ajustement fin

Les noms, types, valeurs par défaut et le code restent en anglais ; le reste est traduit (les entrées non encore traduites s'affichent dans l'original anglais).

TrainConfig

TrainConfig()

Paramètres d’entraînement. Les défauts entraînent comme le fait le notebook publié.

Le lot effectif de 64 du notebook est 8 par micro-lot x 2 GPU x 4 étapes d’accumulation ; sur un seul appareil, c’est micro_batch=8, grad_accum=8.

max_len / head_max_len prennent par défaut la config du checkpoint lui-même. Ce qui est utilisé est écrit dans la config enregistrée, pour que l’inférence voie les mêmes budgets que l’entraînement. amp est activé par défaut pour CUDA seulement ; gradient_checkpointing suit amp par défaut. option_layout prend par défaut celui du checkpoint ("sequential" pour tous les checkpoints publiés) ; "parallel" entraîne sur common.parallel_layout et est écrit dans la config enregistrée.

finetune

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

Prétraite, entraîne, calibre et enregistre ; renvoie un résumé de l’exécution.

data est un fichier JSONL de lignes {state, questions, gold} ou {state, questions, expected}, ou un fichier CSV avec des colonnes de texte et de libellé. model_dir est un dossier de checkpoint local -- la disposition que lit laya.load. Le résultat dans output_dir se charge avec laya.load(output_dir).

Paramètres

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]

Inspecte le jeu de données et construit les éléments sans charger les poids du modèle ; renvoie les stats du jeu de données.

Paramètres

datastr
model_dirstr
configOptional[TrainConfig]= None

Les deux moitiés 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]

Entraîne model en place sur items ; renvoie la perte moyenne de chaque époque.

Paramètres

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,
)

Enregistrements (qtype, logits, target, k) pour fit_temperature_map, options dans l’ordre canonique.

Paramètres

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]]

Par type de question : combien d’éléments de calibration il y avait, ce qui a été ajusté, et ce dont il faut douter.

records sont les calibration_records sur lesquels les températures ont été ajustées, et temperature les scalaires par type que fit_temperature_map a renvoyés. Chaque type reçoit items, temperature, accuracy et mean_confidence (probabilité de tête à la température ajustée) sur les éléments de calibration, et une liste issues, vide quand rien ne semble anormal :

  • moins de MIN_TYPE_N éléments : la température n’a pas été ajustée et reste à 1.0 ;
  • moins de CALIB_WARN_N éléments : elle a été ajustée, sur peu de preuves ;
  • elle a atterri sur l’écrêtage [TEMP_MIN, TEMP_MAX] ;
  • elle est revenue inchangée à 1.0 bien qu’ajustée, ce qui signifie généralement que les éléments n’ont rien laissé à corriger à l’ajustement -- ce que produit un modèle déjà certain et juste sur eux.

Un type sans aucun élément de calibration n’a pas d’issues ; il n’était pas dans les données.

Paramètres

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

Lire les données

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]]

Lit des lignes d’entraînement/éval depuis un fichier JSONL ou un fichier CSV.

Paramètres

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]]

Lit un fichier CSV avec une colonne étiquetée par ligne en lignes {state, questions, expected}.

Découvre les libellés distincts dans label_column (en préservant l’ordre d’apparition) et construit une question choice avec ces libellés comme liste de criteria pour rendre chaque option une fois. Utilise l’encodage utf-8-sig pour que les en-têtes UTF-8 à BOM d’Excel soient gérés de façon transparente.

Paramètres

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

Construire les éléments d’entraînement

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]]

Éléments à partir de lignes {state, questions, gold} ou {state, questions, expected} ; renvoie (items, skipped).

skipped compte, par raison, les questions qui étaient étiquetées mais n’ont pas pu devenir un élément : empty_text, empty_label, invalid_question et invalid_target (un ValueError de to_internal, target_from_gold ou target_from_expected), plus les raisons que donne make_item. Les questions qui n’ont ni entrée gold ni entrée expected ne sont pas comptées -- la ligne ne les étiquette simplement pas.

Paramètres

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 distribution cible normalisée pour une question interne (to_internal), dans l’ordre des options.

gold_q["probabilities"] est indexée par libellé choice, par "false"/"true" pour noul, et par l’index de niveau sous forme de chaîne pour score -- le schéma {state, questions, gold} de docs/finetune.md. Un libellé choice qui n’est pas une chaîne est aussi cherché comme sa clé JSON. Une ligne dont les probabilités somme à zéro devient uniforme, comme dans les scripts. Une probabilité négative ou non finie lève ValueError.

Paramètres

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 distribution cible normalisée à partir d’une seule réponse attendue, dans l’ordre des options.

expected_val est :

  • un libellé choice (str ou valeur correspondant à un critère) pour les questions choice
  • un booléen pour les questions noul
  • un index de niveau entier ou une chaîne de niveau pour les questions score

Quand label_smoothing > 0, lisse la masse de probabilité uniformément : target[i] = (1 - eps) * one_hot[i] + eps / K.

Paramètres

qDict[str, Any]
expected_valAny
label_smoothingfloat= 0.0

to_internal

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

La question telle que l’inférence la voit : Agent._check_question puis Agent._to_internal.

S’entraîner sur un autre rendu apprendrait au modèle des textes d’options qu’il ne voit jamais à l’inférence -- une choice en forme de liste, des labels noul personnalisés, une instruction non-chaîne.

Paramètres

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), ou (None, reason) quand la question ne peut pas être entraînée telle qu’écrite.

q est une question interne (to_internal). Les raisons sont target_mismatch (la cible n’a pas une entrée par option), options_collapsed (le budget de tête a laissé deux options avec le même intervalle de jetons, #538) et, quand max_len est donné, options_beyond_max_len (la tête est plus longue que max_len, donc build_sequence abandonne les marqueurs des dernières options -- le cas que Agent refuse à l’inférence avec « only N of its M option markers fit »). S’entraîner sur l’une d’elles apprendrait au modèle à distinguer des options qu’il ne peut pas voir comme différentes, ou ferait planter le lot sur une cible plus longue que ses marqueurs.

Paramètres

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]

L’entrée du modèle pour un élément, avec les options dans option_order et la cible à apparier.

build_sequence place l’option option_order[s] dans l’emplacement s, donc la cible ordonnée par emplacement est target[option_order[s]] -- l’inverse de ce que fait unpermute_probs à l’inférence.

Paramètres

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]]

Une permutation aléatoire pour les éléments dont le type est dans shuffle_types, sinon None (canonique).

Paramètres

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), la tranche de calibration étant prise avant tout entraînement.

Ajuster les températures sur des éléments que l’exécution a entraînés mesure l’ajustement, pas la calibration (docs/finetune.md). Le découpage ne dépend que de seed et du nombre d’éléments, donc chaque rang DDP et chaque réexécution mettent de côté les mêmes éléments.

Paramètres

itemsSequence[Any]
calib_maxint
calib_fracfloat
seedint

Pertes

soft_ce_loss

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

Entropie croisée contre une distribution cible, sur les options propres à chaque ligne seulement.

Paramètres

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

L’objectif du notebook : un terme de gradient de politique sur des logits bruités plus une entropie croisée souple.

Un bruit gaussien de moyenne nulle (mis à l’échelle par sigma, projeté sur les options de chaque ligne) est ajouté aux logits détachés ; chaque échantillon est récompensé par proper_reward contre la cible, et l’avantage normalisé pondère la log-densité gaussienne de l’échantillon.

Paramètres

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

Résout un chemin local, un alias de modèle ('multilingual', 'english') ou un id de dépôt Hub en un dossier local.

Paramètres

model_id_or_pathstr
tokenOptional[str]= None

load_checkpoint

load_checkpoint(model_dir: str)

(model, tokenizer, cfg) depuis un dossier de checkpoint local ou un id Hub, modèle sur CPU en fp32.

Paramètres

model_dirstr

save_checkpoint

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

Écrit la disposition que lit laya.load : poids en fp16, config d’encodeur, tokenizer, config.

Paramètres

model
tok
cfgDict[str, Any]
pathstr