Converters refactor [transformers-utils]: Generalize model utilities for broader transformer support

[markurtz]

Summary

Refactors transformer utilities from Eagle-specific implementations to comprehensive, generalized utilities. Extracts and enhances existing functionality into a dedicated transformers_utils module that supports multiple weight formats, authentication, caching, and robust error handling while maintaining backward compatibility.

Details

• Removed Eagle-specific utility functions from src/speculators/convert/eagle/utils.py in favor of src/speculators/utils/transformers_utils.py module:
  • Removed: download_checkpoint_from_hub(), ensure_checkpoint_is_local(), load_checkpoint_config(), load_checkpoint_weights(), detect_fusion_bias_and_layernorms()
  • Added download_model_checkpoint_from_hub() - Enhanced downloading with authentication, caching, and revision support
  • Added check_download_model_checkpoint() - Smart path/model instance handling with automatic downloads
  • Added check_download_model_config() - Flexible config loading from various sources
  • Added load_model_config() - Unified config loading with AutoConfig integration
  • Added load_model_checkpoint_config_dict() - Dictionary-based config loading
  • Added load_model_checkpoint_weight_files() - Multi-format weight file discovery
  • Added load_model_checkpoint_index_weight_files() - Indexed/sharded weight file support
  • Added load_model_checkpoint_state_dict() - Complete state dictionary loading with format detection
• Enhanced features compared to original Eagle utilities:
  • Support for both SafeTensors (.safetensors) and PyTorch (.bin) weight formats
  • Automatic format detection and sharded checkpoint support
  • Authentication token support for private models
  • Comprehensive type hints and modern Python syntax (union types, Path objects)
  • Robust error handling with detailed exception messages
  • Model instance support (PreTrainedModel, nn.Module) alongside path-based loading
• Updated init.py to export all new transformer utility functions
• Replaced Eagle-specific tests with comprehensive test suite for transformers_utils:
  • Enhanced test coverage with smoke, sanity, and regression test categories
  • Parameterized testing for multiple input types and edge cases
• Migrated current eagle converters to use the new transformers utils.

Test Plan

• Expanded and added unit tests to for the full functionality

Related Issues

N/A

[github-actions]

📦 Build Artifacts Available
The build artifacts (`.whl` and `.tar.gz`) have been successfully generated and are available for download: https://github.com/vllm-project/speculators/actions/runs/17588650303/artifacts/3966570476.
They will be retained for up to 30 days.
Commit: bcb5bfe

[Copilot]

Pull Request Overview

This PR refactors transformer utilities from Eagle-specific implementations to comprehensive, generalized utilities. It extracts and enhances existing functionality into a dedicated transformers_utils module that supports multiple weight formats, authentication, caching, and robust error handling while maintaining backward compatibility.

• Generalized utilities: Replaced Eagle-specific functions with enhanced, reusable transformer utilities
• Enhanced functionality: Added support for SafeTensors, authentication, caching, and model instances
• Comprehensive testing: Replaced Eagle-specific tests with expanded test coverage for the new utilities

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/speculators/utils/transformers_utils.py	New comprehensive module with generalized transformer utilities
src/speculators/utils/__init__.py	Export new transformer utility functions
tests/unit/utils/test_transformers_utils.py	Comprehensive test suite for new utilities
tests/unit/convert/test_eagle_utils.py	Removed Eagle-specific tests
src/speculators/convert/eagle/utils.py	Removed Eagle-specific utility functions

Comments suppressed due to low confidence (1)

tests/unit/utils/test_transformers_utils.py:1

• The noqa comment indicates a linting issue that should be addressed. The comment references SIM118 which suggests using dict comprehension instead of iterating over keys.

"""

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[rahul-tuli]

nice!