# Utilitários para o Trainer Esta página lista todas as funções utilitárias usadas pelo [Trainer](/docs/transformers/main/pt/main_classes/trainer#transformers.Trainer). A maioria delas só é útil se você estiver estudando o código do Trainer na biblioteca. ## Utilitários[[transformers.EvalPrediction]] #### transformers.EvalPrediction[[transformers.EvalPrediction]] ```python transformers.EvalPrediction(predictions: numpy.ndarray | tuple[numpy.ndarray], label_ids: numpy.ndarray | tuple[numpy.ndarray], inputs: numpy.ndarray | tuple[numpy.ndarray] | None = None, losses: numpy.ndarray | tuple[numpy.ndarray] | None = None) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_utils.py#L210) **Parâmetros:** predictions (`np.ndarray`) : Previsões do modelo. label_ids (`np.ndarray`) : Alvos a serem correspondidos. inputs (`np.ndarray`, *opcional*) : Dados de entrada passados para o modelo. losses (`np.ndarray`, *opcional*) : Valores de perda calculados durante a avaliação. Saída de avaliação (sempre contém rótulos), a ser usada para calcular métricas. #### transformers.IntervalStrategy[[transformers.IntervalStrategy]] ```python transformers.IntervalStrategy(value, names = None, module = None, qualname = None, type = None, start = 1, boundary = None) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_utils.py#L389) #### transformers.enable_full_determinism[[transformers.enable_full_determinism]] ```python transformers.enable_full_determinism(seed: int, warn_only: bool = False) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_utils.py#L154) Função auxiliar para comportamento reprodutível durante o treinamento distribuído. Consulte https://pytorch.org/docs/stable/notes/randomness.html para o pytorch #### transformers.set_seed[[transformers.set_seed]] ```python transformers.set_seed(seed: int, deterministic: bool = False) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_utils.py#L180) **Parâmetros:** seed (`int`) : A semente a ser definida. deterministic (`bool`, *opcional*, padrão `False`) : Se deve usar algoritmos determinísticos quando disponíveis. Pode reduzir a velocidade do treinamento. Função auxiliar para comportamento reprodutível, definindo a semente em `random`, `numpy` e `torch` (se instalado). #### transformers.torch_distributed_zero_first[[transformers.torch_distributed_zero_first]] ```python transformers.torch_distributed_zero_first(local_rank: int) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_pt_utils.py#L309) **Parâmetros:** local_rank (`int`) : O rank do processo local. Decorador para fazer com que todos os processos no treinamento distribuído aguardem cada local_master para executar algo. ## Internos dos callbacks[[transformers.trainer_callback.CallbackHandler]] #### transformers.trainer_callback.CallbackHandler[[transformers.trainer_callback.CallbackHandler]] ```python transformers.trainer_callback.CallbackHandler(callbacks, model, processing_class, optimizer, lr_scheduler) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L429) Classe interna que apenas chama a lista de callbacks em ordem. ## Argument Parser do Trainer[[transformers.HfArgumentParser]] #### transformers.HfArgumentParser[[transformers.HfArgumentParser]] ```python transformers.HfArgumentParser(dataclass_types: typing.Union[transformers.hf_argparser.DataClassType, collections.abc.Iterable[transformers.hf_argparser.DataClassType], NoneType] = None, **kwargs) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/hf_argparser.py#L111) **Parâmetros:** dataclass_types (`DataClassType` ou `Iterable[DataClassType]`, *opcional*) : Tipo de dataclass, ou lista de tipos de dataclass para os quais preencheremos instâncias com os argumentos analisados. kwargs (`dict[str, Any]`, *opcional*) : Passado para `argparse.ArgumentParser()` da maneira usual. Esta subclasse de `argparse.ArgumentParser` usa type hints em dataclasses para gerar argumentos. A classe é projetada para funcionar bem com o argparse nativo. Em particular, você pode adicionar mais argumentos (não baseados em dataclass) ao parser após a inicialização e obterá a saída após o parsing como um namespace adicional. Opcional: para criar grupos de argumentos secundários, use o atributo `_argument_group_name` no dataclass. #### parse_args_into_dataclasses[[transformers.HfArgumentParser.parse_args_into_dataclasses]] ```python parse_args_into_dataclasses(args = None, return_remaining_strings = False, look_for_args_file = True, args_filename = None, args_file_flag = None) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/hf_argparser.py#L272) **Parâmetros:** args : Lista de strings para analisar. O valor padrão é obtido de sys.argv. (igual a argparse.ArgumentParser) return_remaining_strings : Se for true, também retorna uma lista de strings de argumentos restantes. look_for_args_file : Se true, procurará um arquivo ".args" com o mesmo nome base que o script de ponto de entrada deste processo e adicionará seu conteúdo potencial aos argumentos da linha de comando. args_filename : Se não for None, usará este arquivo em vez do arquivo ".args" especificado no argumento anterior. args_file_flag : Se não for None, procurará um arquivo nos argumentos de linha de comando especificados com esta flag. A flag pode ser especificada várias vezes e a precedência é determinada pela ordem (a última prevalece). **Retorna:** `Tuple consisting of` - as instâncias de dataclass na mesma ordem em que foram passadas para o inicializador. - se aplicável, um namespace adicional para mais argumentos (não baseados em dataclass) adicionados ao parser após a inicialização. - A lista potencial de strings de argumentos restantes. (igual a argparse.ArgumentParser.parse_known_args) Analisa os argumentos da linha de comando em instâncias dos tipos de dataclass especificados. Isso depende do `ArgumentParser.parse_known_args` do argparse. Consulte a documentação em: docs.python.org/3/library/argparse.html#argparse.ArgumentParser.parse_args #### parse_dict[[transformers.HfArgumentParser.parse_dict]] ```python parse_dict(args: dict, allow_extra_keys: bool = False) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/hf_argparser.py#L358) **Parâmetros:** args (`dict`) : dicionário contendo os valores de configuração allow_extra_keys (`bool`, *opcional*, padrão `False`) : O padrão é False. Se for False, uma exceção será lançada se o dicionário contiver chaves que não são analisadas. **Retorna:** `Tuple consisting of` - as instâncias de dataclass na mesma ordem em que foram passadas para o inicializador. Método auxiliar alternativo que não usa `argparse` de forma alguma, em vez disso, usa um dicionário e preenche os tipos de dataclass. #### parse_json_file[[transformers.HfArgumentParser.parse_json_file]] ```python parse_json_file(json_file: str | os.PathLike, allow_extra_keys: bool = False) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/hf_argparser.py#L386) **Parâmetros:** json_file (`str` ou `os.PathLike`) : Nome do arquivo json a ser analisado allow_extra_keys (`bool`, *opcional*, padrão `False`) : O padrão é False. Se for False, uma exceção será lançada se o arquivo json contiver chaves que não são analisadas. **Retorna:** `Tuple consisting of` - as instâncias de dataclass na mesma ordem em que foram passadas para o inicializador. Método auxiliar alternativo que não usa `argparse` de forma alguma, carregando em vez disso um arquivo json e preenchendo os tipos de dataclass. #### parse_yaml_file[[transformers.HfArgumentParser.parse_yaml_file]] ```python parse_yaml_file(yaml_file: str | os.PathLike, allow_extra_keys: bool = False) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/hf_argparser.py#L408) **Parâmetros:** yaml_file (`str` ou `os.PathLike`) : Nome do arquivo yaml a ser analisado allow_extra_keys (`bool`, *opcional*, padrão `False`) : O padrão é False. Se for False, uma exceção será lançada se o arquivo json contiver chaves que não são analisadas. **Retorna:** `Tuple consisting of` - as instâncias de dataclass na mesma ordem em que foram passadas para o inicializador. Método auxiliar alternativo que não usa `argparse` de forma alguma, carregando um arquivo yaml e preenchendo os tipos de dataclass. ## Utilitários de depuração[[transformers.debug_utils.DebugUnderflowOverflow]] #### transformers.debug_utils.DebugUnderflowOverflow[[transformers.debug_utils.DebugUnderflowOverflow]] ```python transformers.debug_utils.DebugUnderflowOverflow(model, max_frames_to_save = 21, trace_batch_nums = None, abort_after_batch_num = None) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/debug_utils.py#L27) **Parâmetros:** model (`nn.Module`) : O modelo a ser depurado. max_frames_to_save (`int`, *opcional*, padrão 21) : Quantos frames para trás registrar trace_batch_nums(`list[int]`, *opcional*, padrão `[]`) : Quais números de lote rastrear (desativa a detecção de turnos) abort_after_batch_num (`int``, *opcional*) : Se deve abortar após a conclusão de um determinado número de lote Esta classe de depuração ajuda a detectar e compreender onde o modelo começa a ficar muito grande ou muito pequeno e, mais importante, elementos de pesos e ativações `nan` ou `inf`. Há 2 modos de operação: 1. Detecção de subfluxo/sobrefluxo (padrão) 2. Rastreamento absoluto de mín./máx. de lote específico sem detecção Modo 1: Detecção de subfluxo/sobrefluxo Para ativar a detecção de underflow/overflow, inicialize o objeto com o modelo: ```python debug_overflow = DebugUnderflowOverflow(model) ``` em seguida, execute o treinamento normalmente e, se `nan` ou `inf` for detectado em pelo menos um dos elementos de peso, entrada ou saída, este módulo lançará uma exceção e exibirá `max_frames_to_save` quadros que levaram a esse evento, com cada quadro reportando 1. o nome de módulo totalmente qualificado mais o nome da classe cujo `forward` foi executado 2. o valor mínimo e máximo absoluto de todos os elementos para cada peso do módulo, bem como as entradas e a saída Por exemplo, aqui estão o cabeçalho e os últimos quadros do relatório de detecção para `google/mt5-small` executado em fp16 precisão mista : ``` Detected inf/nan during batch_number=0 Last 21 forward frames: abs min abs max metadata [...] encoder.block.2.layer.1.DenseReluDense.wi_0 Linear 2.17e-07 4.50e+00 weight 1.79e-06 4.65e+00 input[0] 2.68e-06 3.70e+01 output encoder.block.2.layer.1.DenseReluDense.wi_1 Linear 8.08e-07 2.66e+01 weight 1.79e-06 4.65e+00 input[0] 1.27e-04 2.37e+02 output encoder.block.2.layer.1.DenseReluDense.wo Linear 1.01e-06 6.44e+00 weight 0.00e+00 9.74e+03 input[0] 3.18e-04 6.27e+04 output encoder.block.2.layer.1.DenseReluDense T5DenseGatedGeluDense 1.79e-06 4.65e+00 input[0] 3.18e-04 6.27e+04 output encoder.block.2.layer.1.dropout Dropout 3.18e-04 6.27e+04 input[0] 0.00e+00 inf output ``` Aqui é possível ver que `T5DenseGatedGeluDense.forward` resultou em ativações de saída cujo valor máximo absoluto foi de aproximadamente 62,7K, muito próximo do limite superior de 64K do fp16. No próximo frame, temos `Dropout`, que renormaliza os pesos após zerar alguns dos elementos, o que faz com que o valor máximo absoluto ultrapasse 64K, resultando em um estouro. Como você pode ver, são os quadros anteriores que precisamos examinar quando os números começam a ficar muito grandes para números fp16. O rastreamento é realizado em um hook de forward, que é acionado imediatamente após a conclusão de `forward`. Por padrão, os últimos 21 quadros são exibidos. Você pode alterar o padrão para se adequar às suas necessidades. Por exemplo: ```python debug_overflow = DebugUnderflowOverflow(model, max_frames_to_save=100) ``` Para validar que você configurou esse recurso de depuração corretamente e que pretende usá-lo em um treinamento que pode levar horas para ser concluído, execute-o primeiro com o rastreamento normal habilitado para alguns lotes, conforme explicado na próxima seção. Modo 2. Rastreamento absoluto de min/máx. de lote específico sem detecção O segundo modo de operação é o rastreamento por lote com o recurso de detecção de underflow/overflow desativado. Suponha que você queira observar os valores absolutos mínimos e máximos de todos os ingredientes de cada chamada `forward` de um dado um lote, e faça isso apenas para os lotes 1 e 3. Em seguida, você instancia essa classe como: ```python debug_overflow = DebugUnderflowOverflow(model, trace_batch_nums=[1, 3]) ``` E agora os lotes completos 1 e 3 serão rastreados usando o mesmo formato explicado acima. Os lotes são indexados a partir de 0. Isso é útil se você souber que o programa começa a apresentar problemas após um determinado número de lote, pois assim você pode avançar rapidamente até essa região. Parada antecipada: Você também pode especificar o número de lote após o qual deseja interromper o treinamento, com: ```python debug_overflow = DebugUnderflowOverflow(model, trace_batch_nums=[1, 3], abort_after_batch_num=3) ``` Este recurso é principalmente útil no modo de rastreamento, mas você pode usá-lo em qualquer modo. **Desempenho**: Como este módulo mede o `min`/``max` absoluto de cada peso do modelo a cada forward, ele vai retardar o treinamento. Portanto, lembre-se de desativá-lo assim que as necessidades de depuração forem atendidas.