Creating a fine-tuned classifier model in Foundation Models

Written by

Updated at February 10, 2025

Getting started
Upload the dataset
Start tuning

Model tuning based on the LoRA method is at the Preview stage and available upon request. You can fill out the form in the management console.

If an out-of-the-box classifier model is not enough, you can fine-tune a YandexGPT Lite-based classifier model for it to classify your requests more accurately.

Getting started

To use the examples:

SDK

cURL

Create a service account and assign the ai.editor role to it.
Get the service account API key and save it.

The following examples use API key authentication. Yandex Cloud ML SDK also supports IAM token and OAuth token authentication. For more information, see Authentication in Yandex Cloud ML SDK.
Use the pip package manager to install the ML SDK library:
```
pip install yandex-cloud-ml-sdk
```

Get API authentication credentials as described in Authentication with the Yandex Foundation Models API.
Install gRPCurl.
To use the examples, install cURL.
(Optional) Install the jq JSON stream processor.
Get an IAM token used for authentication in the API.

Note

The IAM token has a short lifetime: no more than 12 hours.

Depending on the classification type the fine-tuned model will be used for, prepare UTF-8-encoded tuning data in JSON Lines format. If you want to split your data into two datasets for tuning and validation, repeat the steps below for each dataset. Use the IDs you got after uploading the datasets to start the fine-tuning process.

In this example, we only use the tuning dataset for fine-tuning.

Create a tuning dataset:

SDK

cURL

Create a file named dataset-create.py and add the following code to it:

#!/usr/bin/env python3

from __future__ import annotations
import asyncio
import pathlib
from yandex_cloud_ml_sdk import AsyncYCloudML
from yandex_cloud_ml_sdk.auth import YandexCloudCLIAuth


def local_path(path: str) -> pathlib.Path:
    return pathlib.Path(__file__).parent / path


async def main():

    sdk = AsyncYCloudML(
        folder_id="<folder_ID>",
        auth="<API_key>",
    )

    # Creating a tuning dataset for the YandexGPT Lite base model
    dataset_draft = sdk.datasets.draft_from_path(
        task_type="<classification_type>",
        path="<path_to_file>",
        upload_format="jsonlines",
        name="multiclass",
    )

    # Waiting for the data to be uploaded and the dataset to be created
    operation = await dataset_draft.upload_deferred()
    dataset = await operation
    print(f"new {dataset=}")


if __name__ == "__main__":
    asyncio.run(main())

Where:

<folder_ID>: ID of the folder the service account was created in.
<API_key>: Service account API key you got earlier required for authentication in the API.

The following examples use API key authentication. Yandex Cloud ML SDK also supports IAM token and OAuth token authentication. For more information, see Authentication in Yandex Cloud ML SDK.
<classification_type>: Classification type the model will be tuned for using the new dataset. The possible values are:
- TextClassificationMultilabel: Binary classification or multi-label classification.
- TextClassificationMulticlass: Multi-class classification.
<file_path>: Path to the file containing the ready-made examples for model tuning.

Run the created file:

python3 dataset-create.py

Result:

new dataset=AsyncDataset(id='fds7a7ieb0dh********', folder_id='b1gt6g8ht345********', name='YandexGPT tuning', description=None, metadata=None, created_by='ajegtlf2q28a********', created_at=datetime.datetime(2025, 1, 20, 16, 19, 33), updated_at=datetime.datetime(2025, 1, 20, 16, 20, 19), labels=None, status=<DatasetStatus.READY: 3>, task_type='<classification_type>', rows=0, size_bytes=5679)

Save the new dataset's ID (the id field value): you will need it when fine-tuning the model.

Create a dataset:

grpcurl \
  -H "Authorization: Bearer <IAM_token>" \
  -d @ \
  llm.api.cloud.yandex.net:443 yandex.cloud.ai.dataset.v1.DatasetService/Create <<EOM
  {
    "folder_id": "<folder_ID>", 
    "name": "My awesome dataset", 
    "task_type": "<classification_type>", 
    "upload_format": "jsonlines"
  }
EOM

Where:

<IAM_token>: IAM token of the service account you got before you started.
<folder_ID>: ID of the folder you are creating the dataset in.
<classification_type>: Classification type the model will be tuned for using the new dataset. The possible values are:
- TextClassificationMultilabel: Binary classification or multi-label classification.
- TextClassificationMulticlass: Multi-class classification.

Result:

{
  "datasetId": "fds8hd01tset********",
  "dataset": {
    "datasetId": "fds8hd01tset********",
    "folderId": "b1gt6g8ht345********",
    "name": "My awesome dataset",
    "status": "DRAFT",
    "taskType": "<issue_type_specified_in_the_query>",
    "createdAt": "2025-01-20T14:51:34Z",
    "updatedAt": "2025-01-20T14:51:34Z",
    "createdById": "ajeg2b2et02f********",
    "createdBy": "ajeg2b2et02f********"
  }
}

Save the new dataset's ID (the datasetId field value): you will need it to upload data to the dataset.

Get a link to upload data into the dataset:

grpcurl \
  -H "Authorization: Bearer <IAM_token>" \
  -d '{"dataset_id": "<dataset_ID>", "size_bytes": <dataset_size>}' \
  llm.api.cloud.yandex.net:443 yandex.cloud.ai.dataset.v1.DatasetService/GetUploadDraftUrl | jq

Where:

<IAM_token>: IAM token of the service account you got before you started.
<dataset_ID>: Dataset ID you saved in the previous step.
<dataset_size>: Size in bytes of the file with data for tuning. In the terminal, you can get the file size using the ls -l <file_path> command.

Result:

{
  "datasetId": "fdso08c1u1cq********",
  "uploadUrl": "https://storage.yandexcloud.net/ai-fomo-drafts-prod/b1gt6g8ht345********/fdso08c1u1cq********?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250120T105352Z&X-Amz-SignedHeaders=content-length%3Bhost&X-Amz-Expires=86400&X-Amz-Credential=YCAJE_WuJJ9D1r6huCoc8I3yO%2F20250120%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=611d7951994ae939acf4d32cc0c154c738d02adb2a04707a704f34ca********"
}

The uploadUrl field of the response contains a link you can use to upload your data into the dataset.

Tip

If you did not use jq, replace all \u0026 occurrences with & in the link to use it to upload the dataset.

Upload your data by specifying the link you got in the previous step and the path to the fine-tuning data file:
```
curl \
  --request PUT \
  --upload-file <path_to_file> \
  "<link>"
```

After the data upload is complete, run the dataset validation:

grpcurl \
  -H "Authorization: Bearer <IAM_token>" \
  -d '{"dataset_id": "<dataset_ID>"}' \
  llm.api.cloud.yandex.net:443 yandex.cloud.ai.dataset.v1.DatasetService/Validate

Where:

<IAM_token>: IAM token of the service account you got before you started.
<dataset_ID>: Dataset ID you saved in the previous step.

Result:

{
  "id": "fdso01v2jdd4********",
  "createdAt": "2025-01-20T11:03:48Z",
  "modifiedAt": "2025-01-20T11:03:48Z"
}

Save the validation operation ID (id field). You will need it in the next step.

Dataset validation may take some time. To find out validation status and get an error report (if any), send this request:

grpcurl \
  -H "Authorization: Bearer <IAM_token>" \
  -d '{"operation_id": "<validation_operation_ID>"}' \
  llm.api.cloud.yandex.net:443 yandex.cloud.operation.OperationService/Get

Where:

<IAM_token>: IAM token of the service account you got before you started.
<validation_operation_ID>: ID of the validation operation you saved in the previous step.

Result:

{
  "id": "fdso01v2jdd4********",
  "createdAt": "2025-01-20T11:03:48Z",
  "modifiedAt": "2025-01-20T11:04:46Z",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/yandex.cloud.ai.dataset.v1.ValidateDatasetResponse",
    "datasetId": "fdso08c1u1cq********",
    "isValid": true
  }
}

The isValid field is set to true. This means the loaded dataset was validated successfully.

Start tuning

SDK

cURL

Create a file named start-tuning.py and add the following code to it:

#!/usr/bin/env python3

from __future__ import annotations
import pathlib
import uuid
from yandex_cloud_ml_sdk import YCloudML


def local_path(path: str) -> pathlib.Path:
    return pathlib.Path(__file__).parent / path


def main():
    sdk = YCloudML(
        folder_id="<folder_ID>",
        auth="<API_key>",
    )

    # Viewing the list of valid datasets
    for dataset in sdk.datasets.list(status="READY", name_pattern="multiclass"):
        print(f"List of existing datasets {dataset=}")

    # Setting the tuning dataset and the base model
    train_dataset = sdk.datasets.get("<dataset_ID>")
    base_model = sdk.models.text_classifiers("yandexgpt-lite")

    # Defining minimum parameters
    # To control more parameters, use `base_model.tune_deferred()`
    tuned_model = base_model.tune(
        train_dataset, name=str(uuid.uuid4()), classification_type="<classification_type>"
    )
    print(f"Resulting {tuned_model}")

    # Starting the tuning
    classification_result = tuned_model.run("hey!")
    print(f"{classification_result=}")

    # Saving the URI of the tuned model
    tuned_uri = tuned_model.uri
    model = sdk.models.text_classifiers(tuned_uri)

    classification_result = model.run("hey!")
    print(f"{classification_result=}")


if __name__ == "__main__":
    main()

Where:

<folder_ID>: ID of the folder the service account was created in.
<API_key>: Service account API key you got earlier required for authentication in the API.

The following examples use API key authentication. Yandex Cloud ML SDK also supports IAM token and OAuth token authentication. For more information, see Authentication in Yandex Cloud ML SDK.
<dataset_ID>: The new dataset's ID you saved in the previous step.
<classification_type>: Classification type the model will be tuned for. The possible values are:
- binary: Binary classification.
- multilabel: Multi-label classification.
- multiclass: Multi-class classification.

Run the created file:

python3 start-tuning.py

Result:

Resulting TextClassifiersModel(uri=cls://b1gt6g8ht345********/yandexgpt-lite/latest@tamrjs1t1368c********, config=TextClassifiersModelConfig(task_description=None, labels=None, samples=None))
classification_result=TextClassifiersModelResult(predictions=(TextClassificationLabel(label='anger', confidence=0.5534219145774841), TextClassificationLabel(label='sadness', confidence=0.00046947275404818356), TextClassificationLabel(label='joy', confidence=0.12941128015518188), TextClassificationLabel(label='fear', confidence=0.3008902668952942), TextClassificationLabel(label='surprise', confidence=0.015807058662176132)), model_version='')
classification_result=TextClassifiersModelResult(predictions=(TextClassificationLabel(label='anger', confidence=0.5534219145774841), TextClassificationLabel(label='sadness', confidence=0.00046947275404818356), TextClassificationLabel(label='joy', confidence=0.12941128015518188), TextClassificationLabel(label='fear', confidence=0.3008902668952942), TextClassificationLabel(label='surprise', confidence=0.015807058662176132)), model_version='')

Model tuning may take up to one day depending on the dataset size and the system load.

Use the fine-tuned model's URI you got (the uri field value) when accessing the model.

Start tuning:

grpcurl \
  -H "Authorization: Bearer <IAM_token>" \
  -d @ \
  llm.api.cloud.yandex.net:443 yandex.cloud.ai.tuning.v1.TuningService/Tune <<EOM
  {
    "base_model_uri": "cls://<folder_ID>/yandexgpt-lite/latest",
    "train_datasets": [{"dataset_id": "<dataset_ID>", "weight": 1.0}],
    "name": "my first model",
    "<classification_type>": {}
  } 
EOM

Where:

<IAM_token>: IAM token of the service account you got before you started.
<folder_ID>: ID of the folder you are fine-tuning the model in.
<dataset_ID>: Dataset ID you saved in the previous step.
<classification_type>: Classification type the model will be tuned for. The possible values are:
- text_classification_multilabel: Binary classification or multi-label classification.
- text_classification_multiclass: Multi-class classification.

Result:

{
  "id": "ftnlljf53kil********",
  "createdAt": "2025-01-20T11:17:33Z",
  "modifiedAt": "2025-01-20T11:17:33Z",
  "metadata": {
    "@type": "type.googleapis.com/yandex.cloud.ai.tuning.v1.TuningMetadata"
  }
}

You will get the Operation object in response. Save the operation id you get in the response.

Model tuning may take up to one day depending on the dataset size and the system load. To check if the fine-tuning is complete, request the operation status:

grpcurl \
  -H "Authorization: Bearer <IAM_token>" \
  -d '{"operation_id": "<operation_ID>"}' \
  llm.api.cloud.yandex.net:443 yandex.cloud.operation.OperationService/Get

Where:

<IAM_token>: IAM token of the service account you got before you started.
<operation_ID>: Model fine-tuning operation ID you got in the previous step.

If the fine-tuning process is over, the Operation object will contain the tuned model's URI in the targetModelUri field:

{
  "id": "ftnc7at9r66t********",
  "createdAt": "2025-01-20T15:41:06Z",
  "modifiedAt": "2025-01-20T15:46:10Z",
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/yandex.cloud.ai.tuning.v1.TuningMetadata",
    "status": "COMPLETED",
    "tuningTaskId": "ftnc7at9r66t********"
  },
  "response": {
    "@type": "type.googleapis.com/yandex.cloud.ai.tuning.v1.TuningResponse",
    "status": "COMPLETED",
    "targetModelUri": "cls://b1gt6g8ht345********/yandexgpt-lite/latest@tamr8gqhetveg********",
    "tuningTaskId": "ftnc7at9r66t********"
  }
}

Use the fine-tuned model's URI you got (the targetModelUri field value) when accessing the model.

Creating a fine-tuned classifier model in Foundation Models

Getting started

Upload the dataset

Start tuning

See also

Was the article helpful?

Creating a fine-tuned classifier model in Foundation Models

Getting startedGetting started

Upload the datasetUpload the dataset

Start tuningStart tuning

See alsoSee also

Was the article helpful?

Getting started

Upload the dataset

Start tuning

See also