HF Adapter Not Loading: Fix & Understand 'converted' Dir

Sep 16, 2025 by Square 57 views

HF Adapter Export Issues: Decoding the Mystery of the 'converted' Directory and Loading Errors

Hey folks, let's dive into a common head-scratcher when working with Hugging Face (HF) and adapters, especially after exporting them from tools like MS-Swift. If you're anything like me, you've probably run into this: you export your adapter checkpoint, push it to HF, and then... boom, errors when you try to load it. We'll break down what's happening, address the "converted" directory confusion, and get you back on track. Specifically, we're going to focus on the issue of HF adapter loading errors and the related 'converted' directory problem.

The Scenario: Exporting and Uploading Your Adapter

First off, let's recap the steps. You used a script, likely something like this, to export your adapter checkpoint and upload it to Hugging Face:

swift export \
    --adapters 'v0-20250828-230749/checkpoint-2733/' \
    --push_to_hub true \
    --hub_model_id 'chio4696/Ovis-2.5-SFT-2733' \
    --hub_token 'REDACTED' \
    --use_hf true

This is pretty standard – you're telling the tool to grab your adapter (specified by the --adapters flag), push it to the Hugging Face Hub (--push_to_hub true), give it a model ID on the Hub (--hub_model_id), use your token (--hub_token), and make sure it plays nice with Hugging Face (--use_hf true). Great! But then… you hit the wall when trying to load it.

The 'converted' Directory Conundrum: Where Does Your Adapter Live?

Now, the million-dollar question: After the export, you might see a 'converted' subdirectory in your HF model repo. This can be super confusing. Do you use the files in the main directory or the ones inside 'converted'? The answer, in most cases, is: you should generally not need to directly access or load from the 'converted' directory. This directory often contains files generated during the conversion process for compatibility with different frameworks or formats. The key adapter files should typically be in the root directory of your HF repo. Think of the 'converted' directory as an internal working space, not the final destination for your adapter. Your primary focus should be on the files in the root of the repository.

Decoding the Error: SafetensorError and Loading Time Woes

So, you tried to load your adapter using code similar to this:

import torch
from transformers import AutoModelForCausalLM

peft_model_id = "chio4696/Ovis-2.5-SFT-2733"  # Your HF model ID

model = AutoModelForCausalLM.from_pretrained(
    peft_model_id,
    torch_dtype=torch.bfloat16,
    trust_remote_code=True,
).cuda()

And you got this error message:

SafetensorError: Error while deserializing header: header too large

This SafetensorError is your main clue. It means there's a problem reading the adapter weights, specifically, the header of the safetensors file is corrupted or too large. Safetensors is a secure format for storing your model weights, so this error indicates that the file is either corrupted or not in the expected format. The long loading times you experienced further suggest something is amiss.

Troubleshooting Steps: Getting Your Adapter to Load

Let's walk through the potential solutions to get your adapter loading correctly. I'll break it down step-by-step:

Check the Basics: Double-check that your peft_model_id in the code matches the correct Hugging Face model ID where your adapter is stored. This seems obvious, but it's easy to make a typo.
Permissions: Make sure you have the necessary permissions to access the model on the Hugging Face Hub. If it's a private model, ensure your Hugging Face token is correctly set up in your environment.
File Corruption: If you suspect file corruption, try re-exporting your adapter from the original source. Sometimes, during the export or upload process, files can get corrupted. Redoing the export and push-to-hub steps can fix this.
Update Libraries: Ensure you have the latest versions of transformers and peft installed:
```
pip install --upgrade transformers peft
```
Older versions might have bugs that cause loading issues.
Verify Adapter Files: Look at the files in the root directory of your HF repository. You should see files like adapter_config.json, adapter_model.bin (or a safetensors equivalent like adapter_model.safetensors), and possibly config.json if you're loading the base model. These files are the core of your adapter.
Loading with peft: When you're loading the adapter, use the peft library correctly. The provided code snippet seems correct, but double-check the documentation to ensure there are no changes in loading methods. Check the documentation of the library you are using. Sometimes there might be some version differences.
Check for Large Files: The error message mentions a large header. This can sometimes happen with very large adapters or if there are issues with the file storage. Inspect the file sizes of your adapter files. Extremely large files (gigabytes) might cause problems, especially with older hardware or network issues. If you're working with large models, consider using techniques to reduce memory usage during loading. If you can, consider reducing the size of the adapter. For example, you can try a lower rank for your adapter.
Network Issues: If you're experiencing slow loading times, it might be a network issue. Ensure you have a stable internet connection, or try downloading the adapter locally first and then loading it from your local directory.
Consider Loading with device_map and offload_folder: For large models, you can try using device_map and offload_folder parameters in the from_pretrained method to manage the memory usage. This will offload the model weights to the CPU or even the disk. This can be useful for large models. You can use this parameters to make it load much faster. However, this requires more time in your initial setup.
```
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    peft_model_id,
    torch_dtype=torch.bfloat16,
    trust_remote_code=True,
    device_map="auto",
    offload_folder="offload",
)
```

Step-by-Step Fix for SafetensorError

Let's focus on how to specifically tackle the SafetensorError:

Re-export and Re-upload: The most straightforward solution is to re-export the adapter from your original training setup. Double-check all settings in the export script. If that doesn't work, it could be a network issue, file corruption on the Hub, or your local setup.
Update Transformers and PEFT: Ensure that your transformers and peft libraries are up to date. There can be bugs fixed in newer versions. An older version of transformers or peft could be the cause of the issue.
Inspect the Files: If possible, manually inspect the files in the root directory of your HF repo. This will provide a visual verification of whether the files are present, and if they are not corrupted.
Try a Different Machine: If you have access to another machine, try loading the adapter there. This helps isolate whether the problem is specific to your current environment.
Use safetensors Version: Ensure that the model is loading the safetensors version. The library should automatically detect the safetensors format and load accordingly.

Avoiding Problems in the Future

Here are some proactive measures:

Monitor Uploads: After uploading, always double-check that the necessary files (adapter config, model weights) are in the root directory of your HF repo.
Test Locally: After uploading, test the adapter locally to ensure it loads and runs correctly. This catches errors early.
Version Control: Use version control (like Git) for your training scripts, export scripts, and environment setup. This allows you to revert to working configurations if needed.
Document Your Steps: Keep detailed records of your export commands, library versions, and any custom settings. This makes it easier to troubleshoot later.

If you've tried all of these and are still facing problems, you may need to investigate deeper. This could involve debugging the export script, verifying the adapter's internal structure, or seeking assistance from the libraries' developers. Good luck, and happy adapting, guys!