Importing Models

Import LoRA adapters from Hugging Face and deploy them for inference in AI Studio.

Learn how to import external LoRA (Low-Rank Adaptation) adapters into Hyperstack AI Studio from Hugging Face. This guide covers supported adapter formats, compatibility requirements, the import process, security scanning, and how to deploy and use these adapters for inference within AI Studio.

Importing LoRA Adapters from Hugging Face

AI Studio allows you to import Low-Rank Adaptation (LoRA) adapters hosted on Hugging Face for supported base models in order to perform inference. This makes it easy to leverage pre-trained adapters developed by the open-source community or your organization without requiring you to fine-tune models yourself.

Inference-only support

Fine-tuning, running benchmark or custom evaluations on imported LoRA adapters is currently not supported. These imported models are exclusively available for inference.

Supported LoRA Adapters

For a list of available LoRA adapters compatible with base models in AI Studio, refer to the Hugging Face adapter listings linked below. Adapters must not exceed the maximum file size specified for each model, and must meet the LoRA Adapter Import Requirements check during import:

Base Model	Hugging Face Adapter List	Max Size
Llama 3.1 8B Instruct	meta-llama/Llama-3.1-8B-Instruct	4GB
Mistral Small 24B Instruct 2501	mistralai/Mistral-Small-24B-Instruct-2501	6GB
Llama 3.3 70B Instruct	meta-llama/Llama-3.3-70B-Instruct	8GB
OpenAI gpt-oss-120b	openai/gpt-oss-120b	12GB

Adapter support and validation

Adapter compatibility is limited. Not all adapters available for these base models are supported or validated by AI Studio.

AI Studio supports only adapters that correspond to the original base models (e.g. Llama 3.1 8B Instruct). Adapters for modified or derived variants, such as Llama 3.1 8B Instruct GGUF, are not compatible. Derived versions often differ technically from the originals and are not supported by AI Studio.

LoRA Adapter Import Requirements

To successfully import a LoRA adapter into AI Studio, the following conditions must be met:

General Compatibility

• The adapter must be compatible with a base model supported by AI Studio.
• The adapter file size must be within the maximum allowed for the supported base model. See Supported LoRA Adapters for size limits.
• The adapter must pass the security scan. See Security Scanning and Import Safety for details.

Repository & Access

• The adapter must be hosted on Hugging Face in a repository that exists and is either publicly accessible, or private with a valid User Access Token that grants read permissions, provided during import. Learn more.
• The import must specify a valid branch name (e.g., main).
• The repository must contain both adapter_config.json and adapter_model.safetensors files at the root level; subdirectory structures are not supported.
• Gated adapters are not currently supported.

Adapter Configuration (adapter_config.json)

• The adapter_config.json file must be present and publicly accessible.
• The target_modules field in adapter_config.json must exist and be a non-empty list.
• The LoRA rank (r) must be 64 or lower.

Learn how to check the adapter_config.json file for validation requirements

To verify that an adapter meets key configuration requirements:

1. Go to the adapter's model page on Hugging Face and open the Files and versions tab.
2. Locate and open the adapter_config.json file.
   • The r field represents the LoRA rank (e.g., "r": 64). This value must be 64 or lower.
   • Ensure that the target_modules field exists and includes one or more module names (e.g., "q_proj", "v_proj").

Example adapter_config.json

To inspect the adapter_config.json file for this example, click here.

This model adapter uses a LoRA rank of 8 and includes a populated target_modules list, making it valid for import.

{
  "alpha_pattern": {},
  "auto_mapping": null,
  "base_model_name_or_path": "meta-llama/Llama-3.1-8B-Instruct",
  "bias": "none",
  "fan_in_fan_out": false,
  "inference_mode": true,
  "init_lora_weights": true,
  "layer_replication": null,
  "layers_pattern": null,
  "layers_to_transform": null,
  "loftq_config": {},
  "lora_alpha": 32,
  "lora_dropout": 0.05,
  "megatron_config": null,
  "megatron_core": "megatron.core",
  "modules_to_save": null,
  "peft_type": "LORA",
  "r": 8,
  "rank_pattern": {},
  "revision": null,
  "target_modules": [
    "o_proj",
    "down_proj",
    "up_proj",
    "gate_proj",
    "k_proj",
    "q_proj",
    "v_proj"
  ],
  "task_type": "CAUSAL_LM",
  "use_dora": false,
  "use_rslora": false
}

Tokenizer Configuration (tokenizer.json)

• The adapter must not include a custom tokenizer.json; adapters are expected to use the tokenizer configuration of the base model without modification.
• If a tokenizer.json is present, it must be a valid JSON file, and its added_tokens field must match the base model exactly.

Learn how to check the tokenizer.json file for validation requirements

To confirm compatibility of tokenizer.json:

1. Open the adapter's model page on Hugging Face and go to the Files and versions tab.
2. Look for a tokenizer.json file.
   • If it does not exist, the adapter will inherit the base model tokenizer and will pass validation.
   • If it does exist, open the file and ensure it is a valid JSON file, and compare the added_tokens field in the adapter's tokenizer.json with the base model’s tokenizer.json. They must match exactly.

Adapters with mismatched added_tokens or malformed tokenizer.json files will fail import.

Security Scanning and Import Safety

All LoRA adapters imported into Hyperstack AI Studio from Hugging Face must pass Hugging Face’s automated security scans.

How Security Scanning Works

When a LoRA adapter is uploaded to Hugging Face, adapter_model.safetensors and adapter_config.json are automatically scanned for malware or other unsafe content. Hugging Face runs multiple scanners to detect malicious payloads or insecure behavior, including Protect AI.

AI Studio checks the Hugging Face scan status of both required files:

• adapter_model.safetensors
• adapter_config.json

Both files must be marked safe. If either file is flagged as unsafe, or is still in pending state, AI Studio will block the import. AI Studio follows Hugging Face’s scan results and does not run separate security checks.

For more details, refer to Hugging Face's documentation on malware scanning.

If a file fails validation, you will see this error:

"This model contains files flagged as unsafe by HuggingFace security scan."

How to Import a LoRA Adapter from Hugging Face

1. Navigate to the My Models Page

   Go to the My Models page in Hyperstack AI Studio and click the Import From Hugging Face button in the top-right corner to open the import modal.

   

2. Specify LoRA Adapter for Import

   Complete the Import from Hugging Face modal with the following fields:

   a. Hugging Face Repo: Enter the name of the Hugging Face adapter repository, formatted as <username>/<modelname>. Choose from the list of supported LoRA adapters for each available base model.

   For example, nvidia/llama-3.1-nemoguard-8b-topic-control from the Llama 3.1 8B Instruct adapters page. This adapter corresponds to the meta-llama/Llama-3.1-8B-Instruct base model supported by AI Studio.

   b. Model Name (Alias): Provide a display name for the imported model.

   c. Version/Branch (Optional): To import a specific version, specify the branch name (e.g. dev). Defaults to main.

   d. Token (Optional): If the adapter is hosted in a private Hugging Face repository, you must provide your User Access Token with read access enabled. For details on how to generate and manage access tokens, see Hugging Face’s guide on User Access Tokens.

   

   e. Validate and Import: Confirm that you've reviewed the license, then click Validate & Import.

   You will see a confirmation message indicating Import in progress, with the following status stages:

   queued → downloading → validating → ready

   The imported LoRA adapter is validated against the LoRA Adapter Import Requirements.

   Once validation succeeds, the status will update to Ready with progress showing 100% complete. You can now close the modal. The imported model adapter will appear on the My Models - User Imported Models page.

   

3. Deploy the Model Adapter

   To deploy the imported adapter, click View model details on the My Models - User Imported Models page, then toggle the status from Ready to Deploy to Deploying. The status will transition to Deployed when complete.

   

4. Use the Imported Adapter in the Playground UI

   Once deployed, the adapter can be used in the Playground UI for inference by selecting the imported model and interacting with it via the chat interface or API. To learn how to use the Playground, click here.

   Inference-only support

   Fine-tuning, running benchmark or custom evaluations on imported LoRA adapters is currently not supported. These imported models are exclusively available for inference.

   

Back to top