oracle-ads 2.11.9__py3-none-any.whl → 2.11.11__py3-none-any.whl

ads/aqua/{finetune.py → finetuning/finetuning.py}

@@ -5,9 +5,8 @@
 
 import json
 import os
-from dataclasses import asdict, dataclass, field
-from enum import Enum
-from typing import Dict, Optional
+from dataclasses import asdict, fields, MISSING
+from typing import Dict
 
 from oci.data_science.models import (
     Metadata,
@@ -16,11 +15,14 @@ from oci.data_science.models import (
 )
 
 from ads.aqua import ODSC_MODEL_COMPARTMENT_OCID, logger
-from ads.aqua.base import AquaApp
-from ads.aqua.data import AquaResourceIdentifier, Resource, Tags
-from ads.aqua.exception import AquaFileExistsError, AquaValueError
-from ads.aqua.job import AquaJobSummary
-from ads.aqua.utils import (
+from ads.aqua.app import AquaApp
+from ads.aqua.common.enums import Resource, Tags
+from ads.aqua.common.errors import AquaFileExistsError, AquaValueError
+from ads.aqua.common.utils import (
+    get_container_image,
+    upload_local_to_os,
+)
+from ads.aqua.constants import (
     DEFAULT_FT_BATCH_SIZE,
     DEFAULT_FT_BLOCK_STORAGE_SIZE,
     DEFAULT_FT_REPLICA,
@@ -28,14 +30,16 @@ from ads.aqua.utils import (
     JOB_INFRASTRUCTURE_TYPE_DEFAULT_NETWORKING,
     UNKNOWN,
     UNKNOWN_DICT,
-    get_container_image,
-    upload_local_to_os,
 )
+from ads.aqua.config.config import get_finetuning_config_defaults
+from ads.aqua.data import AquaResourceIdentifier
+from ads.aqua.finetuning.constants import *
+from ads.aqua.finetuning.entities import *
 from ads.common.auth import default_signer
 from ads.common.object_storage_details import ObjectStorageDetails
-from ads.common.serializer import DataClassSerializable
 from ads.common.utils import get_console_link
 from ads.config import (
+    AQUA_FINETUNING_CONTAINER_OVERRIDE_FLAG_METADATA_NAME,
     AQUA_JOB_SUBNET_ID,
     AQUA_MODEL_FINETUNING_CONFIG,
     COMPARTMENT_OCID,
@@ -54,100 +58,6 @@ from ads.model.model_metadata import (
 from ads.telemetry import telemetry
 
 
-class FineTuneCustomMetadata(Enum):
-    FINE_TUNE_SOURCE = "fine_tune_source"
-    FINE_TUNE_SOURCE_NAME = "fine_tune_source_name"
-    FINE_TUNE_OUTPUT_PATH = "fine_tune_output_path"
-    FINE_TUNE_JOB_ID = "fine_tune_job_id"
-    FINE_TUNE_JOB_RUN_ID = "fine_tune_job_run_id"
-    SERVICE_MODEL_ARTIFACT_LOCATION = "artifact_location"
-    SERVICE_MODEL_DEPLOYMENT_CONTAINER = "deployment-container"
-    SERVICE_MODEL_FINE_TUNE_CONTAINER = "finetune-container"
-
-
-@dataclass(repr=False)
-class AquaFineTuningParams(DataClassSerializable):
-    epochs: int = None
-    learning_rate: float = None
-    sample_packing: str = "True"
-
-
-@dataclass(repr=False)
-class AquaFineTuningSummary(AquaJobSummary, DataClassSerializable):
-    parameters: AquaFineTuningParams = field(default_factory=AquaFineTuningParams)
-
-
-@dataclass(repr=False)
-class CreateFineTuningDetails(DataClassSerializable):
-    """Dataclass to create aqua model fine tuning.
-
-    Fields
-    ------
-    ft_source_id: str
-        The fine tuning source id. Must be model ocid.
-    ft_name: str
-        The name for fine tuning.
-    dataset_path: str
-        The dataset path for fine tuning. Could be either a local path from notebook session
-        or an object storage path.
-    report_path: str
-        The report path for fine tuning. Must be an object storage path.
-    ft_parameters: dict
-        The parameters for fine tuning.
-    shape_name: str
-        The shape name for fine tuning job infrastructure.
-    replica: int
-        The replica for fine tuning job runtime.
-    validation_set_size: float
-        The validation set size for fine tuning job. Must be a float in between [0,1).
-    ft_description: (str, optional). Defaults to `None`.
-        The description for fine tuning.
-    compartment_id: (str, optional). Defaults to `None`.
-        The compartment id for fine tuning.
-    project_id: (str, optional). Defaults to `None`.
-        The project id for fine tuning.
-    experiment_id: (str, optional). Defaults to `None`.
-        The fine tuning model version set id. If provided,
-        fine tuning model will be associated with it.
-    experiment_name: (str, optional). Defaults to `None`.
-        The fine tuning model version set name. If provided,
-        the fine tuning version set with the same name will be used if exists,
-        otherwise a new model version set will be created with the name.
-    experiment_description: (str, optional). Defaults to `None`.
-        The description for fine tuning model version set.
-    block_storage_size: (int, optional). Defaults to 256.
-        The storage for fine tuning job infrastructure.
-    subnet_id: (str, optional). Defaults to `None`.
-        The custom egress for fine tuning job.
-    log_group_id: (str, optional). Defaults to `None`.
-        The log group id for fine tuning job infrastructure.
-    log_id: (str, optional). Defaults to `None`.
-        The log id for fine tuning job infrastructure.
-    force_overwrite: (bool, optional). Defaults to `False`.
-        Whether to force overwrite the existing file in object storage.
-    """
-
-    ft_source_id: str
-    ft_name: str
-    dataset_path: str
-    report_path: str
-    ft_parameters: dict
-    shape_name: str
-    replica: int
-    validation_set_size: float
-    ft_description: Optional[str] = None
-    compartment_id: Optional[str] = None
-    project_id: Optional[str] = None
-    experiment_id: Optional[str] = None
-    experiment_name: Optional[str] = None
-    experiment_description: Optional[str] = None
-    block_storage_size: Optional[int] = None
-    subnet_id: Optional[str] = None
-    log_id: Optional[str] = None
-    log_group_id: Optional[str] = None
-    force_overwrite: Optional[bool] = False
-
-
 class AquaFineTuningApp(AquaApp):
     """Provides a suite of APIs to interact with Aqua fine-tuned models within the Oracle
     Cloud Infrastructure Data Science service, serving as an interface for creating fine-tuned models.
@@ -190,17 +100,22 @@ class AquaFineTuningApp(AquaApp):
             try:
                 create_fine_tuning_details = CreateFineTuningDetails(**kwargs)
             except:
+                allowed_create_fine_tuning_details = ", ".join(
+                    field.name for field in fields(CreateFineTuningDetails)
+                ).rstrip()
                 raise AquaValueError(
                     "Invalid create fine tuning parameters. Allowable parameters are: "
-                    f"{', '.join(list(asdict(CreateFineTuningDetails).keys()))}."
+                    f"{allowed_create_fine_tuning_details}."
                 )
 
         source = self.get_source(create_fine_tuning_details.ft_source_id)
-        if source.compartment_id != ODSC_MODEL_COMPARTMENT_OCID:
-            raise AquaValueError(
-                f"Fine tuning is only supported for Aqua service models in {ODSC_MODEL_COMPARTMENT_OCID}. "
-                "Use a valid Aqua service model id instead."
-            )
+
+        # todo: revisit validation for fine tuned models
+        # if source.compartment_id != ODSC_MODEL_COMPARTMENT_OCID:
+        #     raise AquaValueError(
+        #         f"Fine tuning is only supported for Aqua service models in {ODSC_MODEL_COMPARTMENT_OCID}. "
+        #         "Use a valid Aqua service model id instead."
+        #     )
 
         target_compartment = (
             create_fine_tuning_details.compartment_id or COMPARTMENT_OCID
@@ -247,9 +162,12 @@ class AquaFineTuningApp(AquaApp):
                 **create_fine_tuning_details.ft_parameters,
             )
         except:
+            allowed_fine_tuning_parameters = ", ".join(
+                field.name for field in fields(AquaFineTuningParams)
+            ).rstrip()
             raise AquaValueError(
                 "Invalid fine tuning parameters. Fine tuning parameters should "
-                f"be a dictionary with keys: {', '.join(list(asdict(AquaFineTuningParams).keys()))}."
+                f"be a dictionary with keys: {allowed_fine_tuning_parameters}."
             )
 
         experiment_model_version_set_id = create_fine_tuning_details.experiment_id
@@ -307,19 +225,20 @@ class AquaFineTuningApp(AquaApp):
 
         ft_model_custom_metadata = ModelCustomMetadata()
         ft_model_custom_metadata.add(
-            key=FineTuneCustomMetadata.FINE_TUNE_SOURCE.value,
+            key=FineTuneCustomMetadata.FINE_TUNE_SOURCE,
             value=create_fine_tuning_details.ft_source_id,
         )
         ft_model_custom_metadata.add(
-            key=FineTuneCustomMetadata.FINE_TUNE_SOURCE_NAME.value,
+            key=FineTuneCustomMetadata.FINE_TUNE_SOURCE_NAME,
             value=source.display_name,
         )
         service_model_artifact_location = source.custom_metadata_list.get(
-            FineTuneCustomMetadata.SERVICE_MODEL_ARTIFACT_LOCATION.value
+            FineTuneCustomMetadata.SERVICE_MODEL_ARTIFACT_LOCATION
         )
         service_model_deployment_container = source.custom_metadata_list.get(
-            FineTuneCustomMetadata.SERVICE_MODEL_DEPLOYMENT_CONTAINER.value
+            FineTuneCustomMetadata.SERVICE_MODEL_DEPLOYMENT_CONTAINER
         )
+
         ft_model_custom_metadata.add(
             key=service_model_artifact_location.key,
             value=service_model_artifact_location.value,
@@ -350,8 +269,8 @@ class AquaFineTuningApp(AquaApp):
         )
 
         ft_job_freeform_tags = {
-            Tags.AQUA_TAG.value: UNKNOWN,
-            Tags.AQUA_FINE_TUNED_MODEL_TAG.value: f"{source.id}#{source.display_name}",
+            Tags.AQUA_TAG: UNKNOWN,
+            Tags.AQUA_FINE_TUNED_MODEL_TAG: f"{source.id}#{source.display_name}",
         }
 
         ft_job = Job(name=ft_model.display_name).with_infrastructure(
@@ -381,10 +300,19 @@ class AquaFineTuningApp(AquaApp):
         ft_config = self.get_finetuning_config(source.id)
 
         ft_container = source.custom_metadata_list.get(
-            FineTuneCustomMetadata.SERVICE_MODEL_FINE_TUNE_CONTAINER.value
+            FineTuneCustomMetadata.SERVICE_MODEL_FINE_TUNE_CONTAINER
         ).value
-
-        batch_size = (
+        is_custom_container = False
+        try:
+            # Check if the container override flag is set. If set, then the user has chosen custom image
+            if source.custom_metadata_list.get(
+                AQUA_FINETUNING_CONTAINER_OVERRIDE_FLAG_METADATA_NAME
+            ).value:
+                is_custom_container = True
+        except Exception:
+            pass
+
+        ft_parameters.batch_size = ft_parameters.batch_size or (
             ft_config.get("shape", UNKNOWN_DICT)
             .get(create_fine_tuning_details.shape_name, UNKNOWN_DICT)
             .get("batch_size", DEFAULT_FT_BATCH_SIZE)
@@ -398,7 +326,6 @@ class AquaFineTuningApp(AquaApp):
                 dataset_path=ft_dataset_path,
                 report_path=create_fine_tuning_details.report_path,
                 replica=create_fine_tuning_details.replica,
-                batch_size=batch_size,
                 finetuning_params=finetuning_params,
                 val_set_size=(
                     create_fine_tuning_details.validation_set_size
@@ -406,6 +333,7 @@ class AquaFineTuningApp(AquaApp):
                 ),
                 parameters=ft_parameters,
                 ft_container=ft_container,
+                is_custom_container=is_custom_container,
             )
         ).create()
         logger.debug(
@@ -422,11 +350,11 @@ class AquaFineTuningApp(AquaApp):
         )
 
         ft_model_custom_metadata.add(
-            key=FineTuneCustomMetadata.FINE_TUNE_JOB_ID.value,
+            key=FineTuneCustomMetadata.FINE_TUNE_JOB_ID,
             value=ft_job.id,
         )
         ft_model_custom_metadata.add(
-            key=FineTuneCustomMetadata.FINE_TUNE_JOB_RUN_ID.value,
+            key=FineTuneCustomMetadata.FINE_TUNE_JOB_RUN_ID,
             value=ft_job_run.id,
         )
         updated_custom_metadata_list = [
@@ -435,16 +363,17 @@ class AquaFineTuningApp(AquaApp):
         ]
 
         source_freeform_tags = source.freeform_tags or {}
-        source_freeform_tags.pop(Tags.LICENSE.value, None)
-        source_freeform_tags.update({Tags.READY_TO_FINE_TUNE.value: "false"})
-        source_freeform_tags.update({Tags.AQUA_TAG.value: UNKNOWN})
+        source_freeform_tags.pop(Tags.LICENSE, None)
+        source_freeform_tags.update({Tags.READY_TO_FINE_TUNE: "false"})
+        source_freeform_tags.update({Tags.AQUA_TAG: UNKNOWN})
+        source_freeform_tags.pop(Tags.BASE_MODEL_CUSTOM, None)
 
         self.update_model(
             model_id=ft_model.id,
             update_model_details=UpdateModelDetails(
                 custom_metadata_list=updated_custom_metadata_list,
                 freeform_tags={
-                    Tags.AQUA_FINE_TUNED_MODEL_TAG.value: (
+                    Tags.AQUA_FINE_TUNED_MODEL_TAG: (
                         f"{source.id}#{source.display_name}"
                     ),
                     **source_freeform_tags,
@@ -489,7 +418,7 @@ class AquaFineTuningApp(AquaApp):
             id=ft_model.id,
             name=ft_model.display_name,
             console_url=get_console_link(
-                resource=Resource.MODEL.value,
+                resource=Resource.MODEL,
                 ocid=ft_model.id,
                 region=self.region,
             ),
@@ -500,7 +429,7 @@ class AquaFineTuningApp(AquaApp):
                 id=experiment_model_version_set_id,
                 name=experiment_model_version_set_name,
                 url=get_console_link(
-                    resource=Resource.MODEL_VERSION_SET.value,
+                    resource=Resource.MODEL_VERSION_SET,
                     ocid=experiment_model_version_set_id,
                     region=self.region,
                 ),
@@ -509,7 +438,7 @@ class AquaFineTuningApp(AquaApp):
                 id=source.id,
                 name=source.display_name,
                 url=get_console_link(
-                    resource=Resource.MODEL.value,
+                    resource=Resource.MODEL,
                     ocid=source.id,
                     region=self.region,
                 ),
@@ -518,18 +447,22 @@ class AquaFineTuningApp(AquaApp):
                 id=ft_job.id,
                 name=ft_job.name,
                 url=get_console_link(
-                    resource=Resource.JOB.value,
+                    resource=Resource.JOB,
                     ocid=ft_job.id,
                     region=self.region,
                 ),
             ),
             tags=dict(
-                aqua_finetuning=Tags.AQUA_FINE_TUNING.value,
+                aqua_finetuning=Tags.AQUA_FINE_TUNING,
                 finetuning_job_id=ft_job.id,
                 finetuning_source=source.id,
                 finetuning_experiment_id=experiment_model_version_set_id,
             ),
-            parameters=ft_parameters,
+            parameters={
+                key: value
+                for key, value in asdict(ft_parameters).items()
+                if value is not None
+            },
         )
 
     def _build_fine_tuning_runtime(
@@ -539,15 +472,19 @@ class AquaFineTuningApp(AquaApp):
         dataset_path: str,
         report_path: str,
         replica: int,
-        batch_size: int,
         val_set_size: float,
         parameters: AquaFineTuningParams,
         ft_container: str = None,
         finetuning_params: str = None,
+        is_custom_container: bool = False,
     ) -> Runtime:
         """Builds fine tuning runtime for Job."""
-        container = get_container_image(
-            container_type=ft_container,
+        container = (
+            get_container_image(
+                container_type=ft_container,
+            )
+            if not is_custom_container
+            else ft_container
         )
         runtime = (
             ContainerRuntime()
@@ -562,9 +499,12 @@ class AquaFineTuningApp(AquaApp):
                             },
                         }
                     ),
-                    "OCI__LAUNCH_CMD": (
-                        f"--micro_batch_size {batch_size} --num_epochs {parameters.epochs} --learning_rate {parameters.learning_rate} --training_data {dataset_path} --output_dir {report_path} --val_set_size {val_set_size} --sample_packing {parameters.sample_packing} "
-                        + (f"{finetuning_params}" if finetuning_params else "")
+                    "OCI__LAUNCH_CMD": self._build_oci_launch_cmd(
+                        dataset_path=dataset_path,
+                        report_path=report_path,
+                        val_set_size=val_set_size,
+                        parameters=parameters,
+                        finetuning_params=finetuning_params,
                     ),
                     "CONDA_BUCKET_NS": CONDA_BUCKET_NS,
                 }
@@ -575,6 +515,30 @@ class AquaFineTuningApp(AquaApp):
 
         return runtime
 
+    @staticmethod
+    def _build_oci_launch_cmd(
+        dataset_path: str,
+        report_path: str,
+        val_set_size: float,
+        parameters: AquaFineTuningParams,
+        finetuning_params: str = None,
+    ) -> str:
+        """Builds the oci launch cmd for fine tuning container runtime."""
+        oci_launch_cmd = f"--training_data {dataset_path} --output_dir {report_path} --val_set_size {val_set_size} "
+        for key, value in asdict(parameters).items():
+            if value is not None:
+                if key == "batch_size":
+                    oci_launch_cmd += f"--micro_{key} {value} "
+                elif key == "epochs":
+                    oci_launch_cmd += f"--num_{key} {value} "
+                elif key == "lora_target_modules":
+                    oci_launch_cmd += f"--{key} {','.join(str(k) for k in value)} "
+                else:
+                    oci_launch_cmd += f"--{key} {value} "
+
+        oci_launch_cmd += f"{finetuning_params}" if finetuning_params else ""
+        return oci_launch_cmd.rstrip()
+
     @telemetry(
         entry_point="plugin=finetuning&action=get_finetuning_config", name="aqua"
     )
@@ -592,4 +556,69 @@ class AquaFineTuningApp(AquaApp):
             A dict of allowed finetuning configs.
         """
 
-        return self.get_config(model_id, AQUA_MODEL_FINETUNING_CONFIG)
+        config = self.get_config(model_id, AQUA_MODEL_FINETUNING_CONFIG)
+        if not config:
+            logger.info(f"Fetching default fine-tuning config for model: {model_id}")
+            config = get_finetuning_config_defaults()
+        return config
+
+    @telemetry(
+        entry_point="plugin=finetuning&action=get_finetuning_default_params",
+        name="aqua",
+    )
+    def get_finetuning_default_params(self, model_id: str) -> Dict:
+        """Gets the default params set in the finetuning configs for the given model. Only the fields that are
+        available in AquaFineTuningParams will be accessible for user overrides.
+
+        Parameters
+        ----------
+        model_id: str
+            The OCID of the Aqua model.
+
+        Returns
+        -------
+        Dict:
+            Dict of parameters from the loaded from finetuning config json file. If config information is not available,
+            then an empty dict is returned.
+        """
+        default_params = {"params": {}}
+        finetuning_config = self.get_finetuning_config(model_id)
+        config_parameters = finetuning_config.get("configuration", UNKNOWN_DICT)
+        dataclass_fields = {field.name for field in fields(AquaFineTuningParams)}
+        for name, value in config_parameters.items():
+            if name == "micro_batch_size":
+                name = "batch_size"
+            if name in dataclass_fields:
+                default_params["params"][name] = value
+
+        return default_params
+
+    def validate_finetuning_params(self, params: Dict = None) -> Dict:
+        """Validate if the fine-tuning parameters passed by the user can be overridden. Parameter values are not
+        validated, only param keys are validated.
+
+        Parameters
+        ----------
+        params :Dict, optional
+            Params passed by the user.
+
+        Returns
+        -------
+            Return a list of restricted params.
+        """
+        try:
+            AquaFineTuningParams(
+                **params,
+            )
+        except Exception as e:
+            logger.debug(str(e))
+            allowed_fine_tuning_parameters = ", ".join(
+                f"{field.name} (required)" if field.default is MISSING else field.name
+                for field in fields(AquaFineTuningParams)
+            ).rstrip()
+            raise AquaValueError(
+                f"Invalid fine tuning parameters. Allowable parameters are: "
+                f"{allowed_fine_tuning_parameters}."
+            )
+
+        return dict(valid=True)

ads/aqua/model/__init__.py

@@ -0,0 +1,8 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*--
+
+# Copyright (c) 2024 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+from ads.aqua.model.model import AquaModelApp
+
+__all__ = ["AquaModelApp"]

ads/aqua/model/constants.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# Copyright (c) 2024 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+
+"""
+aqua.model.constants
+~~~~~~~~~~~~~~~~~~~~
+
+This module contains constants/enums used in Aqua Model.
+"""
+from ads.common.extended_enum import ExtendedEnumMeta
+
+
+class ModelCustomMetadataFields(str, metaclass=ExtendedEnumMeta):
+    ARTIFACT_LOCATION = "artifact_location"
+    DEPLOYMENT_CONTAINER = "deployment-container"
+    EVALUATION_CONTAINER = "evaluation-container"
+    FINETUNE_CONTAINER = "finetune-container"
+
+
+class ModelTask(str, metaclass=ExtendedEnumMeta):
+    TEXT_GENERATION = "text-generation"
+
+
+class FineTuningMetricCategories(str, metaclass=ExtendedEnumMeta):
+    VALIDATION = "validation"
+    TRAINING = "training"
+
+
+class ModelType(str, metaclass=ExtendedEnumMeta):
+    FT = "FT"  # Fine Tuned Model
+    BASE = "BASE"  # Base model
+
+
+# TODO: merge metadata key used in create FT
+class FineTuningCustomMetadata(str, metaclass=ExtendedEnumMeta):
+    FT_SOURCE = "fine_tune_source"
+    FT_SOURCE_NAME = "fine_tune_source_name"
+    FT_OUTPUT_PATH = "fine_tune_output_path"
+    FT_JOB_ID = "fine_tune_job_id"
+    FT_JOB_RUN_ID = "fine_tune_jobrun_id"
+    TRAINING_METRICS_FINAL = "train_metrics_final"
+    VALIDATION_METRICS_FINAL = "val_metrics_final"
+    TRAINING_METRICS_EPOCH = "train_metrics_epoch"
+    VALIDATION_METRICS_EPOCH = "val_metrics_epoch"