D-FINE

Instalação

O D-FINE não precisa de nenhum extra opcional. Tudo que ele importa já está na instalação base.

pip install libreyolo

O fine-tuning com adaptadores via lora=True é a exceção, e precisa do extra lora.

pip install "libreyolo[lora]"

Predição

Os pesos são baixados do Hugging Face no primeiro uso e ficam em cache localmente.

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreDFINEn.pt")result = model(SAMPLE_IMAGE, save=True) for box in result.boxes:    print(box.cls, box.conf, box.xyxy)

libreyolo predict model=LibreDFINEn.pt source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg save=True

from libreyolo import LibreYOLO, SAMPLE_IMAGE # O sufixo -seg no nome do arquivo seleciona a cabeça de máscaras, então# nenhum argumento task é necessário aqui.model = LibreYOLO("LibreDFINEn-seg.pt")result = model(SAMPLE_IMAGE, save=True) print(result.masks.data.shape)

O objeto Results retornado é o mesmo que todas as famílias retornam, então trocar por outro detector é uma mudança de uma linha. Um nome de arquivo com -seg já resolve sozinho para a tarefa de segmentação, e aí result.masks carrega as máscaras de instância junto com as caixas. conf e max_det filtram a seleção de queries; iou é aceito por paridade de API mas não tem efeito, porque o decoder é um preditor de conjuntos sem etapa de NMS. Veja predição para fontes, streaming e tratamento de resultados.

Variantes

Cinco tamanhos. Todos rodam na mesma resolução de entrada, então a tabela os separa por número de parâmetros e acurácia.

A segmentação reaproveita o backbone, o encoder e o decoder da detecção e acrescenta uma cabeça de máscaras, então um checkpoint -seg aceita os mesmos argumentos que o irmão de detecção. A família RT-DETRv4 do LibreYOLO é escrita como uma subclasse do wrapper do D-FINE: ela herda essa linhagem de decoder e depois fixa sua lista de tarefas de volta em detecção, porque não traz cabeça de máscaras.

Treinamento

O treinamento parte de um checkpoint publicado, para as duas tarefas.

from libreyolo import LibreYOLO model = LibreYOLO("LibreDFINEn.pt")model.train(data="my-dataset.yaml", epochs=50, imgsz=640, batch=8, lr0=2e-4)

libreyolo train model=LibreDFINEn.pt data=my-dataset.yaml \  epochs=50 imgsz=640 batch=8 lr0=2e-4

# Continua a partir de pesos de segmentação publicados, cabeça de máscaras incluída.libreyolo train model=LibreDFINEn-seg.pt data=my-dataset.yaml \  task=segment epochs=50 imgsz=640

# Os pesos de detecção não trazem cabeça de máscaras, então isto é uma# transferência explícita: a cabeça começa sem treinamento e só serve depois# de treinada. Pedir task=segment aqui é o que autoriza a transferência.libreyolo train model=LibreDFINEn.pt data=my-dataset.yaml \  task=segment epochs=50 imgsz=640

from libreyolo import LibreYOLO model = LibreYOLO("LibreDFINEn.pt")model.train(data="my-dataset.yaml", epochs=50, lora=True)

libreyolo train model=LibreDFINEn.pt data=my-dataset.yaml \  epochs=50 device=0,1 batch=16

Por padrão, o trainer roda 132 épocas com lr0=2e-4, amp=True e amp_dtype="float16", batch de 16 e early stopping após 50 épocas sem melhora. O libreyolo train parte da mesma receita para as duas tarefas: AdamW com um schedule de cosseno plano, weight_decay=1e-4, 2 épocas de warmup, um clip de norma do gradiente de 0.1, e sem augmentation de mosaic, MixUp, HSV ou afim. Sem name=, suas execuções vão para runs/train/dfine_exp. Pesos de detecção são um ponto de partida válido para treinamento de segmentação, mas só como transferência explícita, pois a cabeça de máscaras começa sem treinamento e, de outro modo, retornaria máscaras sem sentido. Passar task=segment na CLI autoriza a transferência. Em Python, o caminho é mais restrito: é preciso construir LibreDFINE diretamente com allow_detect_to_segment_transfer=True, porque a factory LibreYOLO() não aceita esse argumento, e a construção direta não faz download, então o arquivo de pesos já deve estar no disco.

lora=True vale para detecção. O treinamento de segmentação o rejeita e aponta para freeze='backbone' no lugar, porque a cabeça de máscaras não foi testada com adaptadores. No Apple silicon o trainer move a execução inteira para a CPU: o backward pass do matmul por bins do Integral esbarra em uma falha de compilação do Metal. A inferência em MPS não é afetada.

Veja treinamento para datasets, data augmentation, multi-GPU e loggers.

Validação

val() retorna um dicionário indexado pelo nome da métrica, e imprime os resultados por classe quando verbose fica ligado.

from libreyolo import LibreYOLO model = LibreYOLO("LibreDFINEn.pt")metrics = model.val(data="my-dataset.yaml") print(metrics["metrics/mAP50-95"])print(metrics["metrics/mAP50"])

libreyolo val model=LibreDFINEn.pt data=my-dataset.yaml

from libreyolo import LibreYOLO model = LibreYOLO("LibreDFINEn-seg.pt")metrics = model.val(data="my-dataset.yaml") print(metrics["metrics/mAP50-95(M)"])   # máscarasprint(metrics["metrics/mAP50-95(B)"])   # caixas

Contra um checkpoint -seg, a chave metrics/mAP50-95 pura contém a pontuação das máscaras, e a mesma execução também reporta as caixas em (B) e as máscaras em (M), então as duas ficam disponíveis em uma única passada.

Exportação

Um artefato exportado é recarregado pelo LibreYOLO() a partir do sufixo do arquivo, então um arquivo .onnx ou .engine se comporta como um checkpoint e devolve o mesmo Results. Os caminhos de OpenVINO, Paddle, MNN e Core AI exportam com um canvas fixo em vez de formas dinâmicas. Exportação lista os argumentos que todo formato aceita e os extras que alguns deles acrescentam.

from libreyolo import LibreYOLO model = LibreYOLO("LibreDFINEn.pt")model.export(format="onnx", imgsz=640)model.export(format="tensorrt", imgsz=640, half=True)

libreyolo export model=LibreDFINEn.pt format=onnx imgsz=640libreyolo export model=LibreDFINEn.pt format=tensorrt imgsz=640 half=True

from libreyolo import LibreYOLO, SAMPLE_IMAGE # A factory decide pelo sufixo do arquivo, então um artefato exportado# carrega como qualquer checkpoint e devolve o mesmo objeto Results.model = LibreYOLO("LibreDFINEn.onnx")result = model(SAMPLE_IMAGE) print(result.boxes.xyxy)

Entradas e saídas ONNX

Checkpoints

Todos os arquivos de pesos publicados desta família.

Licenciamento

Citação

@misc{peng2024dfine,
      title={D-FINE: Redefine Regression Task in DETRs as Fine-grained Distribution Refinement},
      author={Yansong Peng and Hebei Li and Peixi Wu and Yueyi Zhang and Xiaoyan Sun and Feng Wu},
      year={2024},
      eprint={2410.13842},
      archivePrefix={arXiv},
      primaryClass={cs.CV}
}