Documentação

Ajuste fino

laya.train importa-se por si só (from laya.train import finetune, TrainConfig); não é reexportado do pacote de topo. laya-train é a sua linha de comandos. O guia de ajuste fino mostra ambos em uso.

Executar um ajuste fino

Os nomes, tipos, valores predefinidos e código mantêm-se em inglês; o resto é traduzido (as entradas ainda não traduzidas são mostradas no original em inglês).

TrainConfig

TrainConfig()

Parâmetros de treino. As predefinições treinam como o notebook publicado o faz.

O lote efetivo de 64 do notebook é 8 por micro-lote x 2 GPUs x 4 passos de acumulação; num só dispositivo isso é micro_batch=8, grad_accum=8.

max_len / head_max_len têm por predefinição a configuração do próprio checkpoint. O que for usado é escrito na configuração guardada, pelo que a inferência vê os mesmos orçamentos que o treino viu. amp está ativado por predefinição apenas para CUDA; gradient_checkpointing segue amp por predefinição. option_layout tem por predefinição o do próprio checkpoint ("sequential" para todos os publicados); "parallel" treina sobre common.parallel_layout e é escrito na configuração guardada.

finetune

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

Pré-processa, treina, calibra e guarda; devolve um resumo da execução.

data é um ficheiro JSONL de linhas {state, questions, gold} ou {state, questions, expected}, ou um ficheiro CSV com colunas de texto e etiqueta. model_dir é um diretório de checkpoint local -- o layout que laya.load lê. O resultado em output_dir carrega-se com 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]

Inspeciona o conjunto de dados e constrói os itens sem carregar os pesos do modelo; devolve estatísticas do conjunto de dados.

Parâmetros

datastr
model_dirstr
configOptional[TrainConfig]= None

As duas metades 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]

Treina model no lugar sobre items; devolve a perda média 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,
)

Registos (qtype, logits, target, k) para fit_temperature_map, opções por ordem canónica.

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 pergunta: quantos itens de calibração havia, o que foi ajustado e do que duvidar.

records são os calibration_records sobre os quais as temperaturas foram ajustadas, e temperature os escalares por tipo que fit_temperature_map devolveu. Cada tipo recebe items, temperature, accuracy e mean_confidence (a probabilidade máxima à temperatura ajustada) sobre os itens de calibração, e uma lista issues, vazia quando nada parece errado:

  • menos de MIN_TYPE_N itens: a temperatura não foi ajustada e permanece 1.0;
  • menos de CALIB_WARN_N itens: foi ajustada, com pouca evidência;
  • caiu no limite [TEMP_MIN, TEMP_MAX];
  • voltou inalterada em 1.0 apesar de ter sido ajustada, o que normalmente significa que os itens não deram ao ajuste nada para corrigir -- o que produz um modelo já certo e correto neles.

Um tipo sem quaisquer itens de calibração não tem issues; não estava nos dados.

Parâmetros

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

Leitura de dados

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

Lê linhas de treino/avaliação de um ficheiro JSONL ou de um ficheiro 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]]

Lê um ficheiro CSV com uma coluna etiquetada por linha para linhas {state, questions, expected}.

Descobre as etiquetas distintas em label_column (preservando a ordem de aparecimento) e constrói uma pergunta choice com essas etiquetas como lista de criteria para representar cada opção uma vez. Usa a codificação utf-8-sig, para que os cabeçalhos com BOM UTF-8 do Excel sejam tratados de forma transparente.

Parâmetros

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

Construção de itens de treino

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

Itens a partir de linhas {state, questions, gold} ou {state, questions, expected}; devolve (items, skipped).

skipped conta, por motivo, as perguntas que foram etiquetadas mas não puderam tornar-se um item: empty_text, empty_label, invalid_question e invalid_target (um ValueError de to_internal, target_from_gold ou target_from_expected), mais os motivos que make_item dá. As perguntas sem entrada gold nem expected não são contadas -- a linha simplesmente não as 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]

A distribuição alvo normalizada para uma pergunta interna (to_internal), por ordem de opções.

gold_q["probabilities"] tem como chaves a etiqueta da choice, "false"/"true" para noul, e o índice do nível como string para score -- o esquema {state, questions, gold} em docs/finetune.md. Uma etiqueta de choice que não seja string é também procurada pela sua chave JSON. Uma linha cujas probabilidades somam zero torna-se uniforme, como nos scripts. Uma probabilidade negativa ou não finita lança 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]

A distribuição alvo normalizada a partir de uma única resposta esperada, por ordem de opções.

expected_val é:

  • uma etiqueta de choice (str ou valor que corresponde a um criterion) para perguntas choice
  • um booleano para perguntas noul
  • um índice de nível inteiro ou string de nível para perguntas score

Quando label_smoothing > 0, suaviza a massa de probabilidade uniformemente: 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]

A pergunta tal como a inferência a vê: Agent._check_question e depois Agent._to_internal.

Treinar com qualquer outra representação ensinaria ao modelo textos de opções que nunca vê na inferência -- uma choice em forma de lista, labels personalizados de noul, uma instrução que não seja string.

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), ou (None, reason) quando a pergunta não pode ser treinada tal como está escrita.

q é uma pergunta interna (to_internal). Os motivos são target_mismatch (o alvo não tem uma entrada por opção), options_collapsed (o orçamento da cabeça deixou duas opções com o mesmo span de tokens, #538) e, quando max_len é dado, options_beyond_max_len (a cabeça é mais longa do que max_len, pelo que build_sequence descarta os marcadores das últimas opções -- o caso que Agent recusa na inferência com "only N of its M option markers fit"). Treinar sobre qualquer deles ensinaria ao modelo a distinguir opções que não consegue ver como diferentes, ou faria rebentar o lote com um alvo mais longo do que os seus 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]

A entrada do modelo para um item, com as opções em option_order e o alvo a corresponder.

build_sequence coloca a opção option_order[s] no lugar s, pelo que o alvo ordenado por lugar é target[option_order[s]] -- o inverso do que unpermute_probs faz na inferência.

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

Uma permutação aleatória para itens cujo tipo está em shuffle_types, caso contrário 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), com a fração de calibração retirada antes de qualquer treino.

Ajustar temperaturas sobre itens em que a execução já treinou mede o ajuste, não a calibração (docs/finetune.md). A divisão depende apenas de seed e do número de itens, pelo que cada rank DDP e cada nova execução reservam os mesmos itens.

Parâmetros

itemsSequence[Any]
calib_maxint
calib_fracfloat
seedint

Perdas

soft_ce_loss

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

Entropia cruzada contra uma distribuição alvo, apenas sobre as opções de cada linha.

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

O objetivo do notebook: um termo de gradiente de política sobre logits ruidosos mais entropia cruzada suave.

É adicionado ruído gaussiano de média zero (escalado por sigma, projetado sobre as opções de cada linha) a logits destacados; cada amostra é recompensada por proper_reward contra o alvo, e a vantagem normalizada pondera a log-densidade gaussiana da amostra.

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

Resolve um caminho local, um alias de modelo ('multilingual', 'english') ou um ID de repositório do Hub num diretório local.

Parâmetros

model_id_or_pathstr
tokenOptional[str]= None

load_checkpoint

load_checkpoint(model_dir: str)

(model, tokenizer, cfg) de um diretório de checkpoint local ou ID do Hub, modelo na CPU em fp32.

Parâmetros

model_dirstr

save_checkpoint

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

Escreve o layout que laya.load lê: pesos em fp16, configuração do encoder, tokenizer, configuração.

Parâmetros

model
tok
cfgDict[str, Any]
pathstr