Документация

Дообучение

laya.train импортируется отдельно (from laya.train import finetune, TrainConfig); он не реэкспортируется из пакета верхнего уровня. laya-train — его командная строка. Руководство по дообучению показывает оба в деле.

Запуск дообучения

Имена, типы, значения по умолчанию и код остаются на английском; остальное переведено (ещё не переведённые записи показываются в английском оригинале).

TrainConfig

TrainConfig()

Параметры обучения. Значения по умолчанию обучают так же, как опубликованный ноутбук.

Эффективный батч 64 из ноутбука — это 8 на микро-батч x 2 GPU x 4 шага накопления; на одном устройстве это micro_batch=8, grad_accum=8.

max_len / head_max_len по умолчанию берутся из собственной конфигурации чекпойнта. Что бы ни использовалось, оно записывается в сохранённую конфигурацию, так что инференс видит те же бюджеты, что и обучение. amp по умолчанию включён только для CUDA; gradient_checkpointing по умолчанию следует за amp. option_layout по умолчанию берётся из самого чекпойнта ("sequential" для каждого опубликованного); "parallel" обучает на common.parallel_layout и записывается в сохранённую конфигурацию.

finetune

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

Предобрабатывает, обучает, калибрует и сохраняет; возвращает сводку прогона.

data — это файл JSONL со строками {state, questions, gold} или {state, questions, expected}, либо файл CSV со столбцами текста и метки. model_dir — это локальный каталог чекпойнта -- структура, которую читает laya.load. Результат в output_dir загружается через laya.load(output_dir).

Параметры

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]

Изучает набор данных и строит элементы без загрузки весов модели; возвращает статистику набора данных.

Параметры

datastr
model_dirstr
configOptional[TrainConfig]= None

Две половины 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]

Обучает model на месте на items; возвращает средние потери каждой эпохи.

Параметры

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) для fit_temperature_map, варианты в каноническом порядке.

Параметры

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

По каждому типу вопроса: сколько было калибровочных элементов, что было подобрано и чему стоит не доверять.

records — это calibration_records, на которых подбирались температуры, а temperature — скаляры по типам, которые вернул fit_temperature_map. Каждый тип получает items, temperature, accuracy и mean_confidence (верхняя вероятность при подобранной температуре) на калибровочных элементах, а также список issues, пустой, когда всё выглядит верно:

  • меньше MIN_TYPE_N элементов: температура не подбиралась и остаётся 1.0;
  • меньше CALIB_WARN_N элементов: она подобрана, но на малых свидетельствах;
  • она попала на ограничение [TEMP_MIN, TEMP_MAX];
  • она вернулась без изменений на 1.0, хотя подбиралась, что обычно означает, что элементы не дали подгонке ничего исправить -- это то, что даёт модель, уже уверенная и правая на них.

Тип без калибровочных элементов вообще не имеет issues; его не было в данных.

Параметры

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

Чтение данных

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

Читает строки обучения/оценки из файла JSONL или из файла CSV.

Параметры

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

Читает файл CSV, где у каждой строки одна размеченная колонка, в строки {state, questions, expected}.

Обнаруживает различные метки в label_column (сохраняя порядок появления) и строит вопрос choice с этими метками в виде списка критериев, чтобы отрендерить каждый вариант один раз. Использует кодировку utf-8-sig, так что заголовки UTF-8 BOM из Excel обрабатываются прозрачно.

Параметры

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

Построение обучающих элементов

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

Элементы из строк {state, questions, gold} или {state, questions, expected}; возвращает (items, skipped).

skipped считает по причине вопросы, которые были размечены, но не смогли стать элементом: empty_text, empty_label, invalid_question и invalid_target (это ValueError из to_internal, target_from_gold или target_from_expected), плюс причины, которые даёт make_item. Вопросы, у которых нет ни записи gold, ни expected, не считаются -- строка просто не размечает их.

Параметры

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]

Нормализованное целевое распределение для внутреннего вопроса (to_internal), в порядке вариантов.

gold_q["probabilities"] имеет ключи по метке choice, по "false"/"true" для noul и по индексу уровня в виде строки для score -- схема {state, questions, gold} в docs/finetune.md. Метка choice, не являющаяся строкой, также ищется по её ключу JSON. Строка, вероятности которой в сумме дают ноль, становится равномерной, как в скриптах. Отрицательная или неконечная вероятность возбуждает ValueError.

Параметры

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]

Нормализованное целевое распределение из одного ожидаемого ответа, в порядке вариантов.

expected_val — это:

  • метка choice (строка или значение, совпадающее с критерием) для вопросов choice
  • булево значение для вопросов noul
  • целочисленный индекс уровня или строка уровня для вопросов score

Когда label_smoothing > 0, равномерно сглаживает массу вероятностей: target[i] = (1 - eps) * one_hot[i] + eps / K.

Параметры

qDict[str, Any]
expected_valAny
label_smoothingfloat= 0.0

to_internal

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

Вопрос в том виде, в каком его видит инференс: Agent._check_question, затем Agent._to_internal.

Обучение на любом другом рендеринге научило бы модель текстам вариантов, которых она никогда не видит при инференсе -- choice в виде списка, пользовательские labels noul, нестроковая инструкция.

Параметры

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) или (None, reason), когда на вопросе нельзя обучить в том виде, как он записан.

q — это внутренний вопрос (to_internal). Причины: target_mismatch (у цели нет по одной записи на каждый вариант), options_collapsed (бюджет головы оставил два варианта с одинаковым отрезком токенов, #538) и, когда задан max_len, options_beyond_max_len (голова длиннее max_len, поэтому build_sequence отбрасывает маркеры последних вариантов -- тот случай, который Agent отвергает при инференсе сообщением "only N of its M option markers fit"). Обучение на любой из них научило бы модель различать варианты, которые она не может видеть разными, или уронило бы батч на цели длиннее её маркеров.

Параметры

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]

Вход модели для элемента, с вариантами в порядке option_order и целевым распределением для сопоставления.

build_sequence помещает вариант option_order[s] в слот s, поэтому цель, упорядоченная по слотам, — это target[option_order[s]] -- обратное тому, что делает unpermute_probs при инференсе.

Параметры

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

Случайная перестановка для элементов, чей тип входит в shuffle_types, иначе None (канонический порядок).

Параметры

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), причём калибровочный срез берётся до любого обучения.

Подбор температур на элементах, на которых прогон уже обучался, измеряет подгонку, а не калибровку (docs/finetune.md). Разделение зависит только от seed и числа элементов, поэтому каждый ранг DDP и каждый повторный запуск откладывают одни и те же элементы.

Параметры

itemsSequence[Any]
calib_maxint
calib_fracfloat
seedint

Функции потерь

soft_ce_loss

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

Кросс-энтропия против целевого распределения, только по собственным вариантам каждой строки.

Параметры

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

Цель из ноутбука: терм градиента политики по шумным логитам плюс мягкая кросс-энтропия.

Гауссов шум с нулевым средним (масштабированный на sigma, спроецированный на варианты каждой строки) добавляется к отсоединённым логитам; каждая выборка вознаграждается proper_reward против цели, а нормализованное преимущество взвешивает гауссову лог-плотность выборки.

Параметры

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

Чекпойнты

resolve_checkpoint_dir

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

Разрешает локальный путь, псевдоним модели ('multilingual', 'english') или id репозитория Hub в локальный каталог.

Параметры

model_id_or_pathstr
tokenOptional[str]= None

load_checkpoint

load_checkpoint(model_dir: str)

(model, tokenizer, cfg) из локального каталога чекпойнта или id Hub, модель на CPU в fp32.

Параметры

model_dirstr

save_checkpoint

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

Записывает структуру, которую читает laya.load: веса в fp16, конфигурация энкодера, токенизатор, конфигурация.

Параметры

model
tok
cfgDict[str, Any]
pathstr