Aqua Finetuning

AQUA Model Fine-Tuning

Use this skill when the user wants to fine-tune LLMs using LoRA on OCI Data Science AI Quick Actions.

Method: LoRA (Low-Rank Adaptation)

AQUA uses LoRA for parameter-efficient fine-tuning. Default configuration:

{
    "r": 32,
    "lora_alpha": 16,
    "lora_dropout": 0.05
}

All linear modules are targeted by default.

Dataset Formats

All datasets must be JSONL format. Every row must be valid JSON with consistent schema.

Four formats are supported — copy the relevant example file from examples/:

Note: Instruction format is auto-converted to conversational format for chat models if chat_template is available. Tokenized data ({"input_ids": [...]}) is also supported — no formatting is applied to it.

Python SDK Usage

Import

from ads.aqua.finetuning import AquaFineTuningApp
ft_app = AquaFineTuningApp()

Create Fine-Tuning Job

from ads.aqua.finetuning.entities import CreateFineTuningDetails

details = CreateFineTuningDetails(
    ft_source_id="ocid1.datasciencemodel.oc1.iad.xxx",  # Base model OCID
    ft_name="llama-3.1-8b-customer-support",
    dataset_path="oci://my-bucket@my-namespace/datasets/customer_support.jsonl",
    report_path="oci://my-bucket@my-namespace/ft-output/",
    shape_name="VM.GPU.A10.2",
    replica=1,
    compartment_id="ocid1.compartment.oc1..xxx",
    project_id="ocid1.datascienceproject.oc1.iad.xxx",
    log_group_id="ocid1.loggroup.oc1.iad.xxx",
    log_id="ocid1.log.oc1.iad.xxx",
    ft_parameters={
        "epochs": 3,
        "learning_rate": 2e-5,
    },
)
ft_job = ft_app.create(create_fine_tuning_details=details)
print(f"Fine-tuning job: {ft_job.id} | State: {ft_job.lifecycle_state}")

With Advanced LoRA Parameters

details = CreateFineTuningDetails(
    ft_source_id="ocid1.datasciencemodel.oc1.iad.xxx",
    ft_name="llama-3.1-8b-custom",
    dataset_path="oci://my-bucket@my-namespace/datasets/train.jsonl",
    report_path="oci://my-bucket@my-namespace/ft-output/",
    shape_name="BM.GPU.A10.4",
    replica=1,
    ft_parameters={
        "epochs": 5,
        "learning_rate": 1e-5,
        "batch_size": 4,
        "sequence_len": 2048,
        "pad_to_sequence_len": True,
        "sample_packing": "auto",
        "lora_r": 64,
        "lora_alpha": 32,
        "lora_dropout": 0.1,
        "lora_target_linear": True,
    },
)

With Validation Split

details = CreateFineTuningDetails(
    ft_source_id="ocid1.datasciencemodel.oc1.iad.xxx",
    ft_name="llama-3.1-8b-validated",
    dataset_path="oci://my-bucket@my-namespace/datasets/train.jsonl",
    report_path="oci://my-bucket@my-namespace/ft-output/",
    shape_name="VM.GPU.A10.2",
    replica=1,
    val_set_size=0.1,  # 10% validation split
    ft_parameters={
        "epochs": 3,
        "learning_rate": 2e-5,
    },
)

Get Fine-Tuning Config for a Model

config = ft_app.get_finetuning_config(model_id="ocid1.datasciencemodel.oc1.iad.xxx")
print(config.shape)          # Supported shapes
print(config.configuration)  # Configuration per shape

CLI Usage

Create Fine-Tuning Job

ads aqua fine_tuning create \
  --ft_source_id "ocid1.datasciencemodel.oc1.iad.xxx" \
  --ft_name "llama-3.1-8b-customer-support" \
  --dataset_path "oci://my-bucket@my-namespace/datasets/train.jsonl" \
  --report_path "oci://my-bucket@my-namespace/ft-output/" \
  --shape_name "VM.GPU.A10.2" \
  --replica 1 \
  --compartment_id "ocid1.compartment.oc1..xxx" \
  --project_id "ocid1.datascienceproject.oc1.iad.xxx" \
  --log_group_id "ocid1.loggroup.oc1.iad.xxx" \
  --log_id "ocid1.log.oc1.iad.xxx" \
  --ft_parameters '{"epochs": 3, "learning_rate": 0.00002}'

Hyperparameters Reference

Distributed Training

• Use replica > 1 for multi-node training
• Requires VCN + Subnet and Logging configuration
• DeepSpeed and FSDP are auto-configured
• Multi-node overhead is significant; only recommended with 5+ replicas
• Single replica with multi-GPU shape (e.g., BM.GPU.A10.4) is preferred when possible

Training Metrics

At the end of each epoch:

• Loss: Should decrease over epochs
• Accuracy: Should increase over epochs
• Watch for overfitting: validation loss stops decreasing while training loss continues to drop

Deploying Fine-Tuned Models

Fine-tuned models (V2) are deployed as stacked deployments sharing the base model:

ads aqua deployment create \
  --model_id "ocid1.datasciencemodel.oc1.iad.fine_tuned_model" \
  --instance_shape "VM.GPU.A10.2" \
  --display_name "ft-stacked-deployment"

The SDK auto-detects V2 fine-tuned models and creates stacked deployments.

For legacy fine-tuned models, convert first:

ads aqua model convert_fine_tune --model_id "ocid1.datasciencemodel.oc1.iad.legacy_ft"

Key Source Files

• ads/aqua/finetuning/finetuning.py — AquaFineTuningApp (create, get config)
• ads/aqua/finetuning/entities.py — CreateFineTuningDetails, AquaFineTuningParams
• ads/aqua/finetuning/constants.py — Fine-tuning metadata keys, restricted params