🤩 Enhanced Structured Output for Training and Testing Logs

[yyq19990828]

trafficstars

Search before asking

• [x] I have searched the RF-DETR issues and found no similar feature requests.

Description

Add structured and human-readable output formatting for training and testing logs to improve debugging experience and log readability. Currently, training logs and test results are displayed as dense, single-line outputs that are difficult to parse and understand at a glance.

Use case

Who would use it:

• ML Engineers: Debugging training runs and analyzing loss patterns across decoder layers
• Researchers: Comparing performance metrics and understanding model behavior
• Data Scientists: Monitoring training progress and identifying issues quickly
• DevOps: Automated training pipelines that need clean, parseable logs

How it would be used:

The feature provides two modes:

1. Default Mode: Clean, categorized output with summary information
2. Verbose Mode: Expanded view showing all metrics in structured format

Current Problem:

Training logs currently look like:

Epoch: [9]  [0/5]  eta: 0:00:04  lr: 0.000100  class_error: 75.00  loss: 10.3353 (10.3353)  loss_ce: 0.9611 (0.9611)  loss_bbox: 0.3982 (0.3982)  loss_giou: 0.2315 (0.2315)  loss_ce_0: 1.1544 (1.1544)  loss_bbox_0: 0.9748 (0.9748)  loss_giou_0: 0.3213 (0.3213)  ... [continues for 20+ more metrics]

Test results currently look like:

Test results: {'class_error': 100.0, 'loss': 9.2314453125, 'loss_ce': 2.370361328125, 'loss_bbox': 0.0, 'loss_giou': 0.0, 'loss_ce_0': 1.630126953125, ... [continues with 30+ more fields]}

Proposed Solution:

Training logs would become:

Epoch: [9] [0/5] eta: 0:00:04 time: 0.8787 data: 0.2267 max mem: 1663
├─ lr: 0.000100
├─ Main: class_error: 75.00 loss: 10.3353 loss_ce: 0.9611 loss_bbox: 0.3982 loss_giou: 0.2315
├─ Dec0: loss_ce_0: 1.1544 loss_bbox_0: 0.9748 loss_giou_0: 0.3213
├─ Dec1: loss_ce_1: 0.9570 loss_bbox_1: 0.5812 loss_giou_1: 0.3028
├─ Dec2: loss_ce_2: 0.9437 loss_bbox_2: 0.5892 loss_giou_2: 0.2628
├─ Enc: loss_ce_enc: 0.9149 loss_bbox_enc: 1.1436 loss_giou_enc: 0.5990
└─ Unscaled: 21 metrics (use --verbose-logging to expand)

Test results would become:

Test Results Summary:
==================================================
📊 Performance Metrics:
├─ mAP@[0.5:0.95]: 0.456
├─ Precision: 0.789
└─ Recall: 0.623

📋 Per-Class Results:
├─ person: mAP@[0.5:0.95]=0.654, [email protected]=0.823
├─ car: mAP@[0.5:0.95]=0.432, [email protected]=0.698
└─ bike: mAP@[0.5:0.95]=0.287, [email protected]=0.567

📉 Loss Metrics:
├─ Main: class_error: 12.5 loss: 1.234 loss_ce: 0.456 loss_bbox: 0.321 loss_giou: 0.123
├─ Dec0: loss_ce_0: 0.543 loss_bbox_0: 0.234 loss_giou_0: 0.098
├─ Dec1: loss_ce_1: 0.432 loss_bbox_1: 0.198 loss_giou_1: 0.076
├─ Dec2: loss_ce_2: 0.398 loss_bbox_2: 0.165 loss_giou_2: 0.054
├─ Enc: loss_ce_enc: 0.621 loss_bbox_enc: 0.287 loss_giou_enc: 0.134
└─ Unscaled: 21 metrics (use --verbose-logging to expand)

Additional

Implementation Details:

• Backward Compatibility: Original format still available via --raw-json-output flag
• Configurable Verbosity: --verbose-logging flag controls detail level
• Tree Structure: Uses Unicode box-drawing characters for clear hierarchy
• Performance: Minimal overhead, only affects display formatting
• Integration: Works with existing logging infrastructure (tensorboard, wandb)

Benefits:

1. Improved Debugging: Easy to spot issues in specific decoder layers
2. Better Monitoring: Quick visual assessment of training progress
3. Enhanced UX: Reduced cognitive load when reading logs
4. Tool Integration: Cleaner logs for automated analysis tools
5. Educational: Helps users understand RF-DETR's multi-layer architecture

Technical Approach:

• Extend MetricLogger class in rfdetr/util/misc.py
• Add format_test_results() function for test output
• Modify engine.py and main.py to use structured formatting
• Add command-line options for verbosity control

Are you willing to submit a PR?

• [x] Yes I'd like to help by submitting a PR!

[isaacrob-roboflow]

feel free to submit a pr! :) this looks like a great addition to the repo, but we don't have bandwidth to make it happen for the foreseeable future

[fazrigading]

@yyq19990828 this would make the system better. please add this feature ASAP.

[yyq19990828]

@yyq19990828 this would make the system better. please add this feature ASAP.

I'll try... I've added many other things since then, so it may be difficult to pick the necessary part.When I finished, I will make a PR.