Atualização para 1.7.0

De 1.6.0 para 1.7.0

• Checkpoints YOLO9, YOLO9-E2E e YOLO9-P2 salvos pela 1.7.0 usam novos nomes de tensores e não carregam na 1.6.x: a 1.6.x carrega os de YOLO9 e YOLO9-P2 com um aviso de chaves faltando e não prevê nenhuma box, e levanta um erro de incompatibilidade de model_family para os de YOLO9-E2E. Atualize todo ambiente que os lê. Checkpoints float, quantizados e de treinamento escritos por releases anteriores carregam na 1.7.0, e as exportações ONNX não são afetadas.

• O código que acessa model.model de um modelo da família YOLO9 vê os nomes de módulos do MultimediaTechLab/YOLO, sem aliases. DDetect é YOLO9Head (anchor_convs / class_convs), RepConvN é RepConv, RepNBottleneck é Bottleneck, DFL é Anchor2Vec (anchor2vec), nc é num_classes, e as subcamadas dos blocos são conv1/conv2/bottleneck. No YOLO9-E2E, YOLO9E2EDetect é YOLO9E2EHead e one2one_cv2 / one2one_cv3 são one_to_one_anchor_convs / one_to_one_class_convs. LibreYOLO9Model.fuse(), RepConvN.fuse_convs(), Conv.forward_without_bn(), Concat e yolo9.utils.decode_boxes foram removidos. O changelog lista todas as renomeações.

• Os nomes dos nós ONNX seguem os novos nomes de módulos na cabeça, no backbone e no neck, por exemplo /head/anchor_convs.0/.... Atualize as ferramentas que dependem de nomes de nós, como as configs de end-node do Hailo. As entradas, as saídas e os nomes das saídas do modelo não mudaram.

• Um fine-tuning YOLO9 a partir de pesos sem tensores PGI, o que inclui os LibreYOLO9{t,s,m,c}.pt publicados, treina só a cabeça principal, como na 1.5.0; a 1.6.0 anexava um ramo PGI com inicialização aleatória em aux_weight=0.25. Pesos que trazem tensores PGI, e execuções do zero, continuam treinando com PGI. Passe aux_weight=0.25 para anexar um ramo novo mesmo assim, ou aux_weight=0 para forçar que fique desligado.

• Quando o PGI está anexado, YOLO9-m e YOLO9-c constroem o ramo auxiliar do MultimediaTechLab: 12.8M (m) e 25.7M (c) de parâmetros exclusivos do treinamento com 80 classes, contra 7.5M e 10.2M, então o treinamento PGI desses tamanhos precisa de mais memória e tempo por passo. Um checkpoint de treinamento m/c da 1.6.0 retoma e faz fine-tuning com o ramo com o qual foi treinado. A inferência e o YOLO9-t/s não mudaram.

• YOLO9, YOLO9-E2E e YOLO9-P2 limitam a norma L2 do gradiente a 10, e o assigner de treinamento deles pontua as âncoras em fp32, então os positivos escolhidos sob AMP fp16 podem diferir. Passe clip_max_norm=0 para o clipping da 1.6.0; uma execução iniciada na 1.6.0 e retomada na 1.7.0 também faz clipping, a menos que você passe isso. A atribuição em fp32 não tem chave para desligar.

• Um perspective diferente de zero faz o warp por deslocamento dos cantos em toda família que usa o warp afim compartilhado (YOLO9 e suas variantes E2E e P2, YOLOX, YOLOv7, YOLO-NAS, PP-YOLOE, RTMDet, PicoDet, RT-DETR e RT-DETRv2), inclusive execuções retomadas de um checkpoint da 1.6.0 que o definiu. Valores de 0.002 ou mais dão o mesmo warp máximo, e valores negativos levantam ValueError. Nenhuma configuração reproduz o warp da 1.6.0; o padrão perspective=0 não mudou.

• O pipeline de mosaic do YOLO9 sorteia a razão de mixup de Beta(1, 1) em vez de Beta(32, 32), sem configuração para o valor antigo. O treinamento padrão do YOLOv7 muda, porque o YOLOv7 ativa o mixup por padrão. YOLO9, YOLO9-E2E, YOLO9-P2, RT-DETR e RT-DETRv2 mudam só quando o mixup está ativado.

• libreyolo train sem name= grava as execuções de EC, D-FINE, SegFormer e LingBot-Vision em runs/train/ec_exp, dfine_exp, segformer_exp e lingbotvision_exp em vez de runs/train/exp, as sondas do V-JEPA 2 em runs/train/train, e as execuções do YOLO9-P2 em runs/train/yolo9_exp. Passe name=exp para o caminho antigo, ou name=yolo9_p2_exp para o YOLO9-P2.

• libreyolo train inicia D-FINE, SegFormer e LingBot-Vision com as suas próprias receitas. Para o D-FINE isso é 132 épocas, lr0=2e-4, weight_decay=1e-4, 2 épocas de warmup e sem augmentation de mosaic, mixup, HSV ou afim. Para enviar os valores que a 1.6.0 enviava, passe epochs=300 optimizer=sgd lr0=0.01 weight_decay=5e-4 warmup_epochs=5 mosaic=1.0 mixup=1.0 hsv_prob=1.0 degrees=10 translate=0.1 shear=2.0.

• libreyolo.validation.ConfusionMatrix indexa matrix[predicted, true] (era [actual, predicted]), conta as detecções em conf_thres=0.25 (era 0.15), recebe names= e task= só como argumentos nomeados, e o seu matrix não pode mais ser reatribuído. Transponha o código que indexava a matriz antiga, e passe conf_thres=0.15 para as contagens antigas. plots=True grava as contagens em confusion_matrix.png e o gráfico normalizado em confusion_matrix_normalized.png.

• predict(agnostic_nms=True) suprime caixas sobrepostas entre classes em vez de avisar. Tarefas sem caixas levantam ValueError, LibreEnsemble e HRNet levantam NotImplementedError, e o nível SAM rejeita o argumento com TypeError; remova o argumento dessas chamadas.

• Uma interpolation desconhecida de classificador levanta ValueError, inclusive os modos do torchvision LANCZOS, BOX, HAMMING e NEAREST_EXACT. Use bilinear, bicubic, nearest ou bilinear_no_antialias.

• Rode a validação de novo antes de comparar com os números da 1.6.0 para val(single_cls=True) em um modelo treinado com várias classes, datasets de segmentação que misturam linhas só com box e linhas com polígono, e o RTMDet-Ins, que mantém até max_det=300 máscaras por imagem por padrão; passe max_det=100 para a configuração do MMDetection.

• Sem libreyolo[rfdetr], chamadas da CLI com um nome de modelo RF-DETR ou DINOv2 saem com o código de erro JSON model_load_failed em vez de model_not_found, e a mensagem nomeia pip install libreyolo[rfdetr].

Veja o changelog para a versão completa.

De 1.5.0 para 1.6.0

• Atualize ambientes fixados abaixo do ONNX Runtime 1.18 para onnxruntime>=1.18.0 antes de instalar o extra ONNX.

• SAM 3D Body aceita o conjunto revisado de artefatos do snapshot. Instale libreyolo[hf], obtenha acesso ao modelo restrito e use a aquisição automática, ou forneça o diretório de snapshot inalterado e o artefato MHR fixado em um sistema de arquivos local confiável.

• Rode a validação novamente após as correções de redimensionamento do RF-DETR fora de pose e de normalização dos classificadores. Confira os limiares de confiança em deploy antes de comparar com resultados da 1.5.0; não existe flag de pré-processamento legado.

• D-FINE, DEIM, RT-DETRv4 e detecção YOLO-NAS ativam AMP FP16 por padrão. Passe amp=False para manter FP32.

• Para usar as escolhas anteriores de fine-tuning YOLO9, defina aux_weight=0, max_labels=100 e warmup_momentum=0.937. Defina letterbox_pad="topleft" quando uma nova conversão registrada como centralizada precisar reproduzir a geometria antiga. Checkpoints antigos de cabeça única retomam com seu grafo original. Novas execuções YOLO9 usam mais memória de GPU, então reduza batch se um tamanho de batch da 1.5.0 ficar sem memória.

• RF-DETR e DINOv2 criam diretórios de execução incrementados com o nome da família. Atualize consumidores dos caminhos de artefatos ou defina output_dir="runs/train", exist_ok=True para manter o local e o comportamento de reutilização antigos.

• Mantenha mixup + cutmix <= 1 na classificação; combinações inválidas agora geram erro na configuração.

• QAT desativa EMA, SyncBatchNorm e média de checkpoints. Use os checkpoints best/last de QAT sem depender desses estados.

• Loaders personalizados com hooks de alteração do dataset devem usar persistent_workers=False ou reconstruir os workers após a alteração. Cópias persistentes incompatíveis com múltiplos workers agora geram erro.

• Arrays de imagem NumPy são lidos como BGR, a ordem do OpenCV. Passe color_format="rgb" onde você passa um array RGB, como np.asarray(pil_image); a saída de cv2.imread() e os quadros de vídeo não precisam de mudança.

• Um array NumPy ou tensor 4D é um batch: predict() retorna uma lista com um Results por imagem em vez de usar só a primeira imagem.

• train(resume=True) e train(resume="path/to/last.pt") restauram os argumentos de treinamento salvos da execução e continuam gravando no seu diretório de execução; os argumentos que você passa explicitamente prevalecem. Retomar pesos publicados, ou uma execução que já atingiu suas epochs, gera ValueError.

• Com a validação ligada, a época final sempre valida, então execuções mais curtas que eval_interval agora reportam métricas e gravam best.pt. val=False desliga a validação, incluindo a época final. A validação durante o treinamento grava em <run>/val em vez de runs/val/.

• Falhas do train na CLI reportam seu tipo de erro, então erros de configuração saem com código 2 em vez de 1 com io_error.

Veja o changelog para o release completo e importação de pesos para conversão de checkpoints.

De 1.4.0 para 1.5.0

Esta página é sobre atualizar o próprio LibreYOLO. Se o que você procura é como carregar um checkpoint de um projeto upstream, isso é importar pesos existentes, um assunto diferente.

A entrada completa da versão está no changelog. O que vem a seguir é só a parte que exige algo de você.

Mudanças de código que você precisa fazer

allow_experimental=True não existe mais

A trava de confirmação sumiu, junto com o mecanismo ddp_aware(experimental_key=...) por trás dela. O treinamento e a exportação de EC, RTMDet, PicoDet e FOMO antes exigiam o argumento, então qualquer script que treine uma dessas famílias é afetado.

# 1.4.0model.train(data="data.yaml", epochs=100, allow_experimental=True) # 1.5.0: exclua o argumentomodel.train(data="data.yaml", epochs=100)

Não há camada de compatibilidade. Uma chamada que ainda passa o argumento recebe um aviso Unknown training config keys (ignored), e o argumento não tem efeito. BaseModel.EXPERIMENTAL_WEIGHT_FILENAMES foi removido junto. O hook get_download_notice() sobrevive, e continua sendo sobrescrito por MiDaS, SegFormer e YOLO9-P2.

Os níveis de suporte continuam publicados, só não são mais um argumento: veja níveis de estabilidade.

O tier de exportação "experimental" não existe mais

from libreyolo.export.support import Tier # 1.4.0: Literal["validated", "experimental", "blocked"]# 1.5.0: Literal["validated", "available", "blocked"]

Código que ramifica pela string do tier deve ler "available" onde lia "experimental". O BaseExporter não emite mais um RuntimeWarning para esses formatos. O estado de cada formato está listado na matriz de exportação.

pretrained=False com resume agora é rejeitado

Antes a combinação seguia adiante de forma incoerente. Agora ela levanta:

ValueError: pretrained=False cannot be combined with resume.

Escolha um. pretrained=False parte de uma inicialização nova com seed, que na 1.5.0 funciona para todas as famílias treináveis em vez de três delas, e resume continua uma execução interrompida a partir do checkpoint dela. Os dois estão documentados em treinamento.

O --imgsz da CLI é uma string, não um int

Mais restrito do que parece. Os dois casos abaixo não são afetados:

libreyolo predict --model yolo9-t --source img.jpg --imgsz 640   # continua ok

model.predict("img.jpg", imgsz=640)   # continua ok

Só precisa mudar o código que chama as funções de comando da CLI diretamente do Python, porque predict, train e val ampliaram --imgsz de int para str para que ele aceite tamanhos retangulares:

from libreyolo.cli.commands.predict import predict_cmd predict_cmd(..., imgsz=640)      # 1.4.0predict_cmd(..., imgsz="640")    # 1.5.0, e "480x640" agora também funciona

O padrão de train agora é a string "640". export --imgsz já era uma string, e profile não mudou.

Números que mudam

Três mudanças alteram métricas nas configurações padrão. Se você acompanha resultados entre versões, leia isto antes de comparar uma execução da 1.5.0 com uma da 1.4.0.

faster-coco-eval é o backend padrão de métricas COCO

val() e a validação de treinamento a cada época agora calculam as métricas COCO com o backend C++ faster-coco-eval em vez de pycocotools.

A troca foi decidida com base em paridade medida em todos os 100 splits de teste do RF100-VL: 1381 de 1400 valores de métrica idênticos bit a bit, desvio máximo de 2.22e-16, deltas das métricas principais exatamente 0, com 15.6x mais velocidade no geral e 56x em datasets com muitas detecções. Seus números não deveriam mudar. Ainda assim, eles são produzidos por uma implementação diferente, e é por isso que isto está na lista.

pycocotools continua sendo o fallback automático quando faster-coco-eval não está instalado. Para forçá-lo:

libreyolo val --model yolo9-t --data coco.yaml --no-faster-coco-eval

model.val(data="coco.yaml", faster_coco_eval=False)

LIBREYOLO_FASTER_COCO_EVAL=0 faz o mesmo globalmente. O backend efetivamente usado é registrado em nível INFO, exposto como model.last_eval_backend depois de val(), e incluído como eval_backend no payload JSON da CLI. Instale o caminho rápido com pip install libreyolo[fast-eval].

Checkpoints do YOLOX treinados antes da 1.5.0 precisam de um override de eps

Esta é a armadilha da versão. Leia se você já fez fine-tuning do YOLOX.

O YOLOX especifica BatchNorm com eps=1e-3 e momentum=0.03. Até a 1.5.0 esses valores eram aplicados como um conserto posterior que não sobrevivia à reconstrução por contagem de classes que o train() faz quando o nc do seu dataset difere do nc do checkpoint. Um fine-tuning assim treinava e reportava a validação durante o treinamento com o eps=1e-5 padrão do torch, e depois era recarregado para inferência com 1e-3: os mesmos tensores sob normalizações diferentes.

Os tamanhos com convolução regular quase não mudam. O n depthwise muda muito, porque o running_var por canal dele é pequeno o bastante para o eps dominar. No ball do RF100-VL, o mesmo checkpoint nano marca 0.566 de mAP50-95 avaliado com o eps de treinamento e 0.151 depois de um recarregamento padrão.

Um checkpoint treinado antes da 1.5.0 carrega a semântica de eps=1e-5. Para reportar números fiéis a ele, ou você avalia com o eps do BN sobrescrito para 1e-5:

import torchfrom libreyolo import LibreYOLO model = LibreYOLO("my-yolox-finetune.pt")for module in model.model.modules():    if isinstance(module, torch.nn.BatchNorm2d):        module.eps = 1e-5 model.val(data="data.yaml")

ou incorpora sqrt((var + 1e-3) / (var + 1e-5)) aos pesos do BN uma vez e salva o resultado. Checkpoints treinados na 1.5.0 ou depois não precisam de nenhum dos dois.

O treinamento multi-escala do D-FINE usa a receita por tamanho do upstream

base_size_repeat era fixado em 3 para todos os tamanhos. Agora ele é resolvido por tamanho como o upstream especifica: n treina em tamanho fixo com multi-escala desligado, s 20, m 6, l 4, x 3. Antes só o x batia, então n, s, m e l veem uma distribuição de escalas diferente e convergem para métricas diferentes.

Para restaurar o comportamento antigo, defina o valor explicitamente:

from libreyolo.training.config import DFINEConfig config = DFINEConfig(base_size_repeat=3)

O DEIM continua usando o 3 fixo. Os detalhes da família estão em D-FINE.

Vale saber, sem ação necessária

• Os resultados com imgsz retangular mudaram porque antes estavam errados. As coordenadas das caixas, o redimensionamento de máscaras do RTMDet, o reescalonamento do YOLO-NAS e o escalonamento do ground truth no validador agora usam altura e largura por eixo em vez de um único escalar. Com imgsz quadrado nada muda, bit a bit. Inferência ou validação retangular rodada na 1.4.0 saía com escala errada. O YOLO-NAS agora rejeita imgsz retangular de cara, em vez de produzir silenciosamente uma saída errada.
• Os dicionários de métricas ganharam chaves. max_det, ar_max_det e AR_max_det do avaliador COCO, e metrics/loss mais metrics/loss/ce do FOMO. Os valores nos padrões não mudaram, mas qualquer coisa que itere sobre as chaves de métricas, incluindo loggers personalizados e cabeçalhos de CSV, vê colunas novas.
• Execuções do YOLO9 com seed que disparam uma reconstrução da cabeça partem de uma inicialização diferente, porque a seed agora é aplicada antes da reconstrução, e não depois. Um fine-tuning com seed feito na 1.4.0 para uma contagem de classes diferente não é reproduzível bit a bit na 1.5.0.
• libreyolo[hub-kernels] em CUDA agora realmente ativa o kernel nativo de MS-deform-attn. A 1.4.0 o escondia atrás de uma condição que o RF-DETR nunca satisfazia, então o kernel nunca rodava. As predições podem variar dentro da tolerância de ponto flutuante no RF-DETR e nas outras famílias com atenção deformável. Instalações padrão não são afetadas, e LIBREYOLO_HUB_KERNELS=0 desativa o kernel.
• libreyolo predict descarta opções não suportadas em vez de levantar erro. A CLI filtra os kwargs pela assinatura de __call__ do modelo, então uma opção que a família não aceita é ignorada em vez de levantar TypeError. Um nome de flag desconhecido continua sendo rejeitado com No such option.
• Fontes ao vivo mudam o formato da saída JSON. Webcams, streams RTSP e captura de tela habilitam o streaming implicitamente, o que emite um registro por quadro em vez de um por chamada. Essas fontes são novas na 1.5.0, então nenhum script da 1.4.0 é afetado.
• Reexportar rfdetr-pose ou yolonas-pose para ONNX gera nomes de saída diferentes. A 1.4.0 interpretava as cabeças de pose multi-tensor deles como segmentação por causa de uma heurística de contagem de saídas. Arquivos .onnx que já estão no disco não são tocados.
• Em uma instalação sem torch, os resultados guardam arrays numpy em vez de torch.Tensor, então .boxes.data retorna um tipo diferente e o desempate do NMS pode divergir do torchvision. Com o torch instalado, o comportamento é idêntico byte a byte. Veja instalação leve.
• Os objetos de configuração validam mais na construção. TrainConfig ganhou um __post_init__ onde não tinha nenhum, então uma configuração que já era inválida agora levanta erro na hora em vez de falhar no meio de uma execução. A serialização de ValidationConfig ganhou uma chave edge_thresholds, o que quebra um round-trip estrito ValidationConfig(**dump) a partir de um dump da 1.4.0.
• Os nomes de arquivo de pesos das famílias com sufixo de tarefa são resolvidos de outro jeito. segformer-b0 agora resolve para LibreSegformerb0-sem.pt. Isso corrige os 404 do download automático e quebra qualquer script que tenha fixado o nome antigo sem sufixo.
• O marcador do pytest experimental_backend agora é extended_backend. Só importa se você roda a suíte de testes com -m.

Checkpoints e datasets

Checkpoints escritos pela 1.4.0 carregam sem mudança. O schema ganhou imgsz_h e imgsz_w para modelos retangulares, e continua escrevendo o escalar imgsz = max(h, w) para leitores mais antigos. As exportações ExecuTorch e MNN agora exigem um arquivo auxiliar, <program>.pte.json e <model>.mnn.json respectivamente, e as exportações de HRNet carregam pose_input: "person_crop". Os formatos de dataset não mudaram.