How to use the PhariaFinetuning API

If you prefer to use the PhariaFinetuning API directly instead of the finetuning functionality from Studio UI you can do so as well. The API offers more configuration options. The API consists of multiple routes that can be used to start, cancel, and list both running and previous jobs. It also has a wider scope

Submitting a job via the Swagger UI

The PhariaFinetuning Swagger UI is accessible at:

https://pharia-finetuning-api.<YOUR_CONFIGURED_URL_POSTFIX>/docs#/

where <YOUR_CONFIGURED_URL_POSTFIX> is the URL postfix configured during the installation of the PhariaFinetuning Helm chart.

1. Authorize

To use the API, you need access to PhariaStudio token. Follow these steps to retrieve it:

1. Go to the PhariaStudio page and log in if necessary.
2. In the upper-right corner, click on your profile.
3. In the popup, click on Copy Bearer Token.

Once you have the token:

• Click on the "Authorize" button in the top-right corner of the Swagger UI.
• Paste your token to authenticate.
• After authorization, you can safely close the popup window.

The API routes include a {project_id} parameter. You need to make sure that you have access to the given project, otherwise you will not be able to interact with finetuning jobs (get jobs, submit jobs and so on) in that project.

---

2. Submit a job

Follow these steps to submit a finetuning job:

1. Click on the /api/v2/projects/{project_id}/finetuning/jobs endpoint to start a new job.
2. Click "Try it out" to enter your parameters.
3. Fill in the request body with the necessary parameters:

a. Supported base models (base_model_name)

• Aleph-Alpha/Pharia-1-LLM-7B-control-hf
• meta-llama/Llama-3.1-8B-Instruct
• roneneldan/TinyStories-1M

b. Dataset parameters

• dataset is required (no default values). You can optionally set limit_samples to limit the number of samples to train on.

c. Suffix

• You can configure a suffix that will be appended to the Job ID for easy identification.

d. Supported finetuning types

• full → Full finetuning
• lora → LoRA finetuning

e. Configurable finetuning hyperparameters

• n_epochs → Number of epochs for training.
• learning_rate_multiplier → Multiplier of the default learning rate (default lr = 2.0e-5).
• batch_size → Size of per-device batches.

4. Once submitted, you will receive an id that uniquely identifies your finetuning job in the response under job.id. This serves as the unique identifier for your job.

f. Evaluation config

• dataset → You can optionally set limit_samples to limit the number of samples to evaluate on.
• evaluation_interval → Run evaluation every evaluation_interval epochs. Defaults to 1 (evaluation after every epoch).
• [BETA] tasks → Run custom PhariaEngine skills on your evaluation dataset. A task is defined by a namespace and a skill_name. You can pass in multiple PhariaEngine skills as tasks.

[BETA] Using PhariaEngine Skills for Evaluation

Your input schema for the skill is expected to have the format shown below. Note the required input fields.

{
    "$defs": {
        "CriticModel": {
            "enum": [
                "llama-3.1-8b-instruct",
                "llama-3.3-70b-instruct",
                "deepseek-r1-distill-llama-8b",
                "deepseek-r1-distill-llama-70b-vllm"
            ],
            "title": "CriticModel",
            "type": "string"
        }
    },
    "properties": {
        "evaluation_model": {
            "$ref": "#/$defs/CriticModel"
        },
        "ground_truth": {
            "title": "Ground Truth",
            "type": "string"
        },
        "instruction": {
            "title": "Instruction",
            "type": "string"
        },
        "response": {
            "title": "Response",
            "type": "string"
        }
    },
    "required": [
        "instruction",
        "response",
        "ground_truth",
        "evaluation_model"
    ],
    "title": "DataTestCaseWithModel",
    "type": "object"
}

The expected output schema for the skill is expected to have the format shown below. Note the required output fields.

{
    "$defs": {
        "Metric": {
            "properties": {
                "aggregation_method": {
                    "enum": [
                        "mean",
                        "sum",
                        "min",
                        "max"
                    ],
                    "title": "Aggregation Method",
                    "type": "string"
                },
                "data_type": {
                    "enum": [
                        "int",
                        "float",
                        "bool"
                    ],
                    "title": "Data Type",
                    "type": "string"
                },
                "description": {
                    "title": "Description",
                    "type": "string"
                },
                "metric_name": {
                    "title": "Metric Name",
                    "type": "string"
                },
                "reason": {
                    "title": "Reason",
                    "type": "string"
                },
                "value": {
                    "anyOf": [
                        {
                            "type": "integer"
                        },
                        {
                            "type": "number"
                        },
                        {
                            "type": "boolean"
                        }
                    ],
                    "title": "Value"
                }
            },
            "required": [
                "metric_name",
                "description",
                "data_type",
                "aggregation_method",
                "value",
                "reason"
            ],
            "title": "Metric",
            "type": "object"
        }
    },
    "properties": {
        "metrics": {
            "items": {
                "$ref": "#/$defs/Metric"
            },
            "title": "Metrics",
            "type": "array"
        }
    },
    "required": [
        "metrics"
    ],
    "title": "EvaluationOutput",
    "type": "object"
}

You can check whether these match by calling https://pharia-kernel.<YOUR_CONFIGURED_URL_POSTFIX>.com/v1/skills/{namespace}/{skill_name}/metadata of your skill.

---

Viewing job status

The PharaiFinetuning API allows you to check the status of all jobs (running, canceled, or failed) or view details for a specific job.

View statuses of all jobs

To get a list of all jobs and their statuses, use the /api/v2/projects/{project_id}/finetuning/jobs route in Swagger UI.

• Since this is a GET route, simply click "Try it out", then "Execute".
• The response is a single JSON object containing job details as JobBasicInfo schema.

---

View status of a single job

To get the status of a specific job, use the /api/v2/projects/{project_id}/finetuning/jobs/{job_id} route.

• Since this is a POST route, click "Try it out".
• Enter the job_id you want details for and click "Execute".
• The response is a JSON array containing job details and statuses.

The schema of the response JobInfoResponse is as follows: