aqua-finetuning

name: aqua-finetuning description: Fine-tune LLM models using LoRA on OCI AI Quick Actions (AQUA). Covers dataset preparation (instruction, conversational, multimodal, tokenized formats), hyperparameter tuning, distributed training, and training metrics. Triggered when user wants to fine-tune or customize a model. user-invocable: true disable-model-invocation: false

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