Dokumentation

Fine-Tuning

laya.train wird eigens importiert (from laya.train import finetune, TrainConfig); es wird nicht aus dem Top-Level-Paket re-exportiert. laya-train ist seine Kommandozeile. Die Fine-Tuning-Anleitung zeigt beide in Gebrauch.

Einen Fine-Tune ausführen

Namen, Typen, Standardwerte und Code bleiben auf Englisch; der Rest ist übersetzt (noch nicht übersetzte Einträge werden im englischen Original angezeigt).

TrainConfig

TrainConfig()

Trainings-Stellschrauben. Die Standardwerte trainieren so wie das veröffentlichte Notebook.

Der effektive Batch von 64 des Notebooks ist 8 pro Mikro-Batch x 2 GPUs x 4 Akkumulationsschritte; auf einem Gerät ist das micro_batch=8, grad_accum=8.

max_len / head_max_len verwenden standardmäßig die eigene Konfiguration des Checkpoints. Was auch immer genutzt wird, wird in die gespeicherte Konfiguration geschrieben, sodass die Inferenz dieselben Budgets sieht wie das Training. amp ist standardmäßig nur für CUDA an; gradient_checkpointing richtet sich standardmäßig nach amp. option_layout verwendet standardmäßig das des Checkpoints ("sequential" für jeden veröffentlichten); "parallel" trainiert auf common.parallel_layout und wird in die gespeicherte Konfiguration geschrieben.

finetune

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

Vorverarbeiten, trainieren, kalibrieren und speichern; gibt eine Zusammenfassung des Laufs zurück.

data ist eine JSONL-Datei aus {state, questions, gold}- oder {state, questions, expected}-Zeilen oder eine CSV-Datei mit Text- und Label-Spalten. model_dir ist ein lokales Checkpoint-Verzeichnis -- das Layout, das laya.load liest. Das Ergebnis in output_dir lädt mit laya.load(output_dir).

Parameter

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]

Untersucht den Datensatz und baut Items, ohne Modellgewichte zu laden; gibt Datensatz-Statistiken zurück.

Parameter

datastr
model_dirstr
configOptional[TrainConfig]= None

Die zwei Hälften von 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]

Trainiert model in-place auf items; gibt den mittleren Verlust jeder Epoche zurück.

Parameter

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

(qtype, logits, target, k)-Records für fit_temperature_map, Optionen in kanonischer Reihenfolge.

Parameter

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

Pro Fragetyp: wie viele Kalibrierungs-Items es gab, was angepasst wurde und was anzuzweifeln ist.

records sind die calibration_records, auf denen die Temperaturen angepasst wurden, und temperature die Skalare pro Typ, die fit_temperature_map zurückgab. Jeder Typ bekommt items, temperature, accuracy und mean_confidence (Top-Wahrscheinlichkeit bei der angepassten Temperatur) auf den Kalibrierungs-Items und eine Liste issues, leer, wenn nichts falsch aussieht:

  • weniger als MIN_TYPE_N Items: die Temperatur wurde nicht angepasst und bleibt 1.0;
  • weniger als CALIB_WARN_N Items: sie wurde angepasst, auf dünner Evidenz;
  • sie landete auf dem Clamp [TEMP_MIN, TEMP_MAX];
  • sie kam unverändert bei 1.0 zurück, obwohl sie angepasst wurde, was meist bedeutet, dass die Items der Anpassung nichts zu korrigieren gaben -- was ein Modell erzeugt, das bei ihnen bereits sicher und richtig ist.

Ein Typ ganz ohne Kalibrierungs-Items hat keine Issues; er war nicht in den Daten.

Parameter

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

Daten lesen

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

Liest Trainings-/Eval-Zeilen aus einer JSONL-Datei oder einer CSV-Datei.

Parameter

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

Liest eine CSV-Datei mit einer beschrifteten Spalte pro Zeile in {state, questions, expected}-Zeilen.

Ermittelt die verschiedenen Labels in label_column (unter Bewahrung der Reihenfolge des Auftretens) und baut eine choice-Frage mit diesen Labels als Criteria-Liste, um jede Option einmal zu rendern. Nutzt die Kodierung utf-8-sig, sodass UTF-8-BOM-Header aus Excel transparent behandelt werden.

Parameter

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

Trainings-Items bauen

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

Items aus {state, questions, gold}- oder {state, questions, expected}-Zeilen; gibt (items, skipped) zurück.

skipped zählt nach Grund die Fragen, die beschriftet waren, aber kein Item werden konnten: empty_text, empty_label, invalid_question und invalid_target (ein ValueError aus to_internal, target_from_gold oder target_from_expected), plus die Gründe, die make_item nennt. Fragen ohne einen gold- und ohne einen expected-Eintrag werden nicht gezählt -- die Zeile beschriftet sie einfach nicht.

Parameter

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]

Die normalisierte Ziel-Verteilung für eine interne Frage (to_internal), in Optionsreihenfolge.

gold_q["probabilities"] ist nach choice-Label verschlüsselt, nach "false"/"true" für noul und nach dem Stufenindex als String für score -- das {state, questions, gold}-Schema in docs/finetune.md. Ein choice-Label, das kein String ist, wird auch über seinen JSON-Schlüssel nachgeschlagen. Eine Zeile, deren Wahrscheinlichkeiten zu null summieren, wird uniform, wie in den Skripten. Eine negative oder nicht endliche Wahrscheinlichkeit löst ValueError aus.

Parameter

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]

Die normalisierte Ziel-Verteilung aus einer einzelnen erwarteten Antwort, in Optionsreihenfolge.

expected_val ist:

  • ein choice-Label (String oder Wert, der zu einem Kriterium passt) für choice-Fragen
  • ein Boolescher Wert für noul-Fragen
  • ein ganzzahliger Stufenindex oder Stufen-String für score-Fragen

Wenn label_smoothing > 0, verteilt es die Wahrscheinlichkeitsmasse gleichmäßig: target[i] = (1 - eps) * one_hot[i] + eps / K.

Parameter

qDict[str, Any]
expected_valAny
label_smoothingfloat= 0.0

to_internal

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

Die Frage, wie die Inferenz sie sieht: Agent._check_question, dann Agent._to_internal.

Auf irgendeiner anderen Darstellung zu trainieren würde dem Modell Optionstexte beibringen, die es bei der Inferenz nie sieht -- eine choice in Listenform, benutzerdefinierte noul-labels, eine Nicht-String-Instruktion.

Parameter

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) oder (None, reason), wenn die Frage nicht so trainiert werden kann, wie sie geschrieben ist.

q ist eine interne Frage (to_internal). Die Gründe sind target_mismatch (das Ziel hat nicht einen Eintrag pro Option), options_collapsed (das Head-Budget ließ zwei Optionen mit derselben Token-Spanne, #538) und, wenn max_len angegeben ist, options_beyond_max_len (der Head ist länger als max_len, sodass build_sequence die Marker der letzten Optionen verwirft -- der Fall, den Agent bei der Inferenz mit "only N of its M option markers fit" ablehnt). Darauf zu trainieren würde dem Modell beibringen, Optionen zu unterscheiden, die es nicht als verschieden sehen kann, oder den Batch an einem Ziel abstürzen lassen, das länger als seine Marker ist.

Parameter

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]

Die Modelleingabe für ein Item, mit Optionen in option_order und dem passenden Ziel.

build_sequence setzt Option option_order[s] in Slot s, das slot-geordnete Ziel ist also target[option_order[s]] -- die Umkehrung dessen, was unpermute_probs bei der Inferenz tut.

Parameter

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

Eine zufällige Permutation für Items, deren Typ in shuffle_types liegt, sonst None (kanonisch).

Parameter

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), wobei die Kalibrierungsteilmenge vor jedem Training herausgenommen wird.

Temperaturen auf Items anzupassen, auf denen der Lauf trainiert hat, misst die Anpassung, nicht die Kalibrierung (docs/finetune.md). Die Aufteilung hängt nur von seed und der Item-Anzahl ab, jeder DDP-Rang und jeder erneute Lauf halten also dieselben Items zurück.

Parameter

itemsSequence[Any]
calib_maxint
calib_fracfloat
seedint

Losses

soft_ce_loss

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

Kreuzentropie gegen eine Ziel-Verteilung, nur über die eigenen Optionen jeder Zeile.

Parameter

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

Das Ziel des Notebooks: ein Policy-Gradient-Term über verrauschte Logits plus weiche Kreuzentropie.

Gaußsches Rauschen mit Mittelwert null (skaliert mit sigma, auf die Optionen jeder Zeile projiziert) wird zu detached Logits addiert; jede Stichprobe wird durch proper_reward gegen das Ziel belohnt, und der normalisierte Vorteil gewichtet die Gaußsche Log-Dichte der Stichprobe.

Parameter

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

Löst einen lokalen Pfad, einen Modell-Alias ('multilingual', 'english') oder eine Hub-Repo-ID in ein lokales Verzeichnis auf.

Parameter

model_id_or_pathstr
tokenOptional[str]= None

load_checkpoint

load_checkpoint(model_dir: str)

(model, tokenizer, cfg) aus einem lokalen Checkpoint-Verzeichnis oder einer Hub-ID, Modell auf der CPU in fp32.

Parameter

model_dirstr

save_checkpoint

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

Schreibt das Layout, das laya.load liest: Gewichte in fp16, Encoder-Konfiguration, Tokenizer, Konfiguration.

Parameter

model
tok
cfgDict[str, Any]
pathstr