Importing Fine-Tuned Models

You can import a fine-tuned version of a model listed in Compatible Models for Import. Its model-family page lists the requirements and compatible hardware.

The fine-tuned export must retain a compatible architecture, meet the base model's Transformers version requirement, and have a total parameter count within ±10% of the original base model. This count includes the whole model, not only the trainable adapter parameters.

For low-rank adaptation (LoRA), merge one adapter into the base model before import. Each imported fine-tuned model can contain the merged weights of only one LoRA adapter.

Use the same compatible hardware options as the base model. The model-family tables list the minimum unit shape for each supported hardware family. Select a compatible shape at or above that minimum from the options available in your region. See Hardware Unit Shapes by Region.

For example, Compatible Alibaba Models lists H100_X1 as the minimum H100 shape for Qwen/Qwen3.8-27B. You can also select H100_X2 when it is offered as a compatible option.

OCI Generative AI doesn't fine-tune imported models. Fine-tuning the service's supported pretrained models is a separate workflow. The only model available for fine-tuning in the service is the standard Meta Llama 3.3 (70B) model in supported commercial (OC1) regions. See Fine-Tuning the Base Models in Generative AI.

To train on OCI, review Fine-Tuning with OCI Data Science AI Quick Actions for its supported models and prerequisites. A model trained in another service must still meet the Generative AI import requirements.

Merge the adapter into the base model to create a complete model. Adapter-only files, such as adapter_model.safetensors and adapter_config.json, depend on the base model.

1. Load the base model revision used for training and the adapter.
2. Merge the adapter into the base model. With Hugging Face PEFT, use merge_and_unload() for a supported LoRA configuration. See Merge the weights.
3. Save the complete model and its tokenizer to a new export directory, using a precision supported for the compatible base model. Retain the original base model and adapter for future exports.

Use a precision supported for the compatible base model. Training and merging can change the stored tensor datatype. Inspect the saved weights before loading them with a datatype conversion.

To change precision, convert the actual tensors and save a new export. Editing torch_dtype or dtype in config.json doesn't convert the weights. For quantized models, follow the model and tool's supported merge and export procedure.

Use one complete export in Hugging Face format. The model artifact directory contains config.json and the files needed to load the model:

• Full model weights, such as model.safetensors, or every weight shard referenced by an index such as model.safetensors.index.json.
• The matching tokenizer, tokenizer configuration, special-token definitions, and chat template, where applicable.
• Generation configuration and any processor files required by the model.

Keep each export in its own directory so that configuration and weight files from different runs aren't mixed. For chat models, see the Hugging Face chat template guidance.

Upload the complete export to a model artifact directory in an Object Storage bucket, or make it available in a Hugging Face model repository. Use that directory or repository when you import the fine-tuned model.

The transformers_version field in config.json records the Hugging Face Transformers library version used when saving the configuration. This value is separate from the library currently installed in your training environment and the model version label you enter in the Console.

The exported value must meet the version requirement described on the compatible model's family page. Compare it with the configuration for the base model revision used for training.

The following table describes the configuration fields relevant to import. Compare the exported config.json with the base model's configuration and the saved weights and tokenizer. The configuration must describe the model files in your export.

Follow the standard model import workflow, using your fine-tuned export as the source:

1. Complete the source prerequisites in Managing Imported Models and set up the required imported model permissions.
2. Import your fine-tuned model from an Object Storage bucket or from Hugging Face.
3. Wait for the import to complete. See Getting an Imported Model's Details.
4. Create a hosting dedicated AI cluster. Select a compatible unit shape for the model from the options available in your region, as described in Models and Hardware.
5. Create an endpoint for the imported model, then send requests to the endpoint.

Use a descriptive name and version to distinguish the fine-tuned model from its base model and other exports.

An import can fail with this message when the exported model doesn't meet a compatibility requirement:

The imported model architecture is not yet validated for serving.

The message doesn't identify the specific difference. A mismatch in transformers_version metadata can cause this error even when the architecture is unchanged.

1. Compare the base and exported config.json files using Configuration Metadata and the requirements on the compatible model's family page.
2. Review the export for datatype changes, missing weight shards, or tokenizer files from a different model. For LoRA, use the complete merged model rather than the adapter-only checkpoint.
3. After correcting the export, save it to a separate artifact directory and import that version.