Fix: Add filename parameter support for ONNX file caching from Hugging Face Hub (Issue #2218)

[ada-ggf25]

Fix: Add filename parameter support for ONNX file caching from Hugging Face Hub

Fixes #2218

What does this PR do?

This PR fixes issue #2218 by adding support for the filename and local_filename parameters when downloading and caching files from Hugging Face Hub repositories. This is particularly important for repositories like xenova that require specific naming conventions for cached ONNX files.

Problem

Previously, when downloading files from Hugging Face Hub using snapshot_download, there was no way to specify a custom local filename for the cached file. This caused issues when users needed to cache files (especially ONNX models) with specific filenames that differ from the original repository filename.

Solution

• Added a new download_file_with_filename() utility function that uses hf_hub_download instead of snapshot_download when a specific filename is requested
• Updated TasksManager.get_model_files() to accept filename and local_filename parameters
• When filename is provided, the function now uses hf_hub_download which supports the local_filename parameter for custom caching

Changes

1. New function: optimum.utils.file_utils.download_file_with_filename()

   • Downloads a specific file from Hugging Face Hub with optional custom local filename
   • Supports subfolders, revisions, tokens, and different repo types
   • Uses hf_hub_download which properly handles the local_filename parameter

2. Enhanced function: TasksManager.get_model_files()

   • Added filename parameter: when specified, downloads only that specific file
   • Added local_filename parameter: allows custom naming for cached files
   • Backward compatible: all existing code continues to work without changes

3. Tests: Added comprehensive test suite in tests/utils/test_file_utils.py

   • Tests for default filename behaviour
   • Tests for custom local filename
   • Tests for subfolders, revisions, tokens, and different repo types
   • All 7 tests passing

Example Usage

from optimum.exporters.tasks import TasksManager

# Download a specific ONNX file with custom local filename
files, error = TasksManager.get_model_files(
    model_name_or_path="xenova/model-name",
    filename="model.onnx",
    local_filename="custom_model.onnx",  # Now works!
    cache_dir="./cache"
)

Or using the utility function directly:

from optimum.utils import download_file_with_filename

file_path = download_file_with_filename(
    repo_id="xenova/model-name",
    filename="model.onnx",
    local_filename="custom_model.onnx",
    cache_dir="./cache"
)

Before submitting

• This PR fixes a typo or improves the docs (you can dismiss the other checks if that's the case).
• Did you make sure to update the documentation with your changes? (Function docstrings included)
• Did you write any new necessary tests? (7 new tests added)

Testing

All new tests pass successfully:

tests/utils/test_file_utils.py::TestDownloadFileWithFilename::test_download_file_with_default_filename PASSED
tests/utils/test_file_utils.py::TestDownloadFileWithFilename::test_download_file_with_custom_local_filename PASSED
tests/utils/test_file_utils.py::TestDownloadFileWithFilename::test_download_file_with_subfolder PASSED
tests/utils/test_file_utils.py::TestDownloadFileWithFilename::test_download_file_with_revision_and_token PASSED
tests/utils/test_file_utils.py::TestDownloadFileWithFilename::test_download_file_with_dataset_repo_type PASSED
tests/utils/test_file_utils.py::TestValidateFileExists::test_validate_file_exists_local_directory PASSED
tests/utils/test_file_utils.py::TestValidateFileExists::test_validate_file_exists_remote_repo PASSED

Files Changed

• optimum/utils/file_utils.py: Added download_file_with_filename() function
• optimum/utils/__init__.py: Exported new function in public API
• optimum/exporters/tasks.py: Enhanced get_model_files() with filename support
• tests/utils/test_file_utils.py: Added comprehensive test suite

Backward Compatibility

This change is fully backward compatible. All existing code will continue to work without modification. The new parameters are optional and only affect behaviour when explicitly provided.

[github-actions]

This PR has been marked as stale because it has been open for 90 days with no activity. This thread will be automatically closed in 30 days if no further activity occurs.