Ballerina library

azure.openai.finetunes

Module azure.openai.finetunes

OverviewPrerequisitesQuickstart

API

Client

Definitions

ApiKeysConfig
Capabilities
ClientHttp1Settings
ConnectionConfig
Deprecation
Error
ErrorResponse
Event
EventList
File
FileImport
FileList
Files_body
FileStatistics
FineTune
FineTuneCreation
FineTuneList
HyperParameters
InnerError
Model
ModelList
ProxyConfig

ScaleType
LifeCycleStatus
LogLevel
InnerErrorCode
TypeDiscriminator
Purpose
State
ErrorCode

ballerinax/azure.openai.finetunes Ballerina library

1.0.2

Overview

The Azure OpenAI Files API connector(https://learn.microsoft.com/en-us/rest/api/cognitiveservices/azureopenaistable/files/), Azure OpenAI Fine Tunes API, and Azure OpenAI Models API OpenAPI specification.

The Azure OpenAI Files API gives access to data files related operations such as delete, get, get content, import, list, and upload. The Azure OpenAI Fine Tunes API gives access to fine-tuning of base models and related operations such as create, cancel, delete, get, get event, and list. The Azure OpenAI Models API gives access to details about the existing models.

Key Features

  • Programmatic access to create and manage resources via REST API
  • Send and publish data through the API
  • Manage user accounts and profiles
  • Support for webhooks and event-driven workflows

Prerequisites

Quickstart

To use the Azure OpenAI Fine Tunes connector in your Ballerina application, update the .bal file as follows:

Step 1: Import the connector

Import the ballerinax/azure.openai.finetunes module into the Ballerina project.

Copy
import ballerinax/azure.openai.finetunes;

Step 2: Create a new connector instance

Create and initialize a finetunes:Client with the obtained apiKey and a serviceUrl from the Azure OpenAI resource

Copy
final finetunes:Client finetunesClient = check new (
    apiKeyConfig = {auth: {apiKey: apiKey}},
    serviceUrl = serviceUrl
);

Step 3: Invoke connector operation

  1. Now you can use the operations available within the connector.

Note: that they are in the form of remote operations.

Following is an example of uploading a file and finetuning curie base model:

Uploading the data file from the local machine.

Copy
finetunes:Files_body filePayload = {
    purpose: "fine-tune",
    file: {fileContent: check io:fileReadBytes("sample.jsonl"), fileName: "sample.jsonl"}
};

finetunes:File fileResult = check finetunesClient->/files.post("2022-12-01", filePayload);

Once the file is uploaded, get the file ID from the response and use it to finetune the base model.

Copy
finetunes:FineTuneCreation finetunePayload = {
    training_file: "file-5272129a77284a188239a68656fc7890", 
    model: "curie"
};

finetunes:FineTune fineTune = check finetunesClient->/fine\-tunes.post("2022-12-01", finetunePayload);
  1. Use bal run command to compile and run the Ballerina program.

Clients

azure.openai.finetunes: Client

Isolated

APIs for fine-tuning and managing deployments of OpenAI models.

Constructor

Gets invoked to initialize the connector. The connector initialization requires setting the API credentials. Create an Azure account, an Azure OpenAI resource and refer this guide to learn how to generate and use tokens

init (ApiKeysConfig apiKeyConfig, string serviceUrl, ConnectionConfig config)
  • serviceUrl string - URL of the target service
  • config ConnectionConfig {} - The configurations to be used when initializing the connector

get files

Isolated FunctionResource Function
function get files(string apiVersion) returns FileList|error

Gets a list of all files owned by the Azure OpenAI resource. These include user uploaded content like files with purpose "fine-tune" for training or validation of fine-tunes models as well as files that are generated by the service such as "fine-tune-results" which contains various metrics for the corresponding fine-tune job.

Parameters
  • apiVersion string - The requested API version.
Return Type

post files

Isolated FunctionResource Function
function post files(string apiVersion, Files_body payload) returns File|error

Creates a new file entity by uploading data from a local machine. Uploaded files can, for example, be used for training or evaluating fine-tuned models.

Parameters
  • apiVersion string - The requested API version.
Return Type
  • File|error - The file has been successfully created.

get files/[string fileId]

Isolated FunctionResource Function
function get files/[string fileId](string apiVersion) returns File|error

Gets details for a single file specified by the given file-id including status, size, purpose, etc.

Parameters
  • apiVersion string - The requested API version.
Return Type

delete files/[string fileId]

Isolated FunctionResource Function
function delete files/[string fileId](string apiVersion) returns Response|error

Deletes the file with the given file-id. Deletion is also allowed if a file was used, e.g., as training file in a fine-tune job.

Parameters
  • apiVersion string - The requested API version.
Return Type

get files/[string fileId]/content

Isolated FunctionResource Function
function get files/[string fileId]/content(string apiVersion) returns byte[]|error

Gets the content of the file specified by the given file-id. Files can be user uploaded content or generated by the service like result metrics of a fine-tune job.

Parameters
  • apiVersion string - The requested API version.
Return Type

post files/'import

Isolated FunctionResource Function
function post files/'import(string apiVersion, FileImport payload) returns File|error

Creates a new file entity by importing data from a provided url. Uploaded files can, for example, be used for training or evaluating fine-tuned models.

Parameters
  • apiVersion string - The requested API version.
  • payload FileImport - The definition of the file to create including its purpose, the file name and the url of the file location.
Return Type
  • File|error - The file has been successfully created.

get 'fine-tunes

Isolated FunctionResource Function
function get 'fine\-tunes(string apiVersion) returns FineTuneList|error

Gets a list of all fine-tune jobs owned by the Azure OpenAI resource. The details that are returned for each fine-tune job contain besides its identifier the base model, training and validation files, hyper parameters, time stamps, status and events. Events are created when the job status changes, e.g. running or complete, and when results are uploaded.

Parameters
  • apiVersion string - The requested API version.
Return Type

post 'fine-tunes

Isolated FunctionResource Function
function post 'fine\-tunes(string apiVersion, FineTuneCreation payload) returns FineTune|error

Creates a job that fine-tunes a specified model from a given training file. Response includes details of the enqueued job including job status and hyper parameters. The name of the fine-tuned model is added to the response once complete.

Parameters
  • apiVersion string - The requested API version.
  • payload FineTuneCreation - The specification of the fine-tuned model to create.
Return Type

get 'fine-tunes/[string fineTuneId]

Isolated FunctionResource Function
function get 'fine\-tunes/[string fineTuneId](string apiVersion) returns FineTune|error

Gets details for a single fine-tune job specified by the given fine-tune-id. The details contain the base model, training and validation files, hyper parameters, time stamps, status and events. Events are created when the job status changes, e.g. running or complete, and when results are uploaded.

Parameters
  • apiVersion string - The requested API version.
Return Type

delete 'fine-tunes/[string fineTuneId]

Isolated FunctionResource Function
function delete 'fine\-tunes/[string fineTuneId](string apiVersion) returns Response|error

Deletes the fine-tune job specified by the given fine-tune-id.

Parameters
  • apiVersion string - The requested API version.
Return Type

get 'fine-tunes/[string fineTuneId]/events

Isolated FunctionResource Function
function get 'fine\-tunes/[string fineTuneId]/events(string apiVersion, boolean? 'stream) returns EventList|error

Gets the events for the fine-tune job specified by the given fine-tune-id. Events are created when the job status changes, e.g. running or complete, and when results are uploaded.

Parameters
  • apiVersion string - The requested API version.
  • 'stream boolean? (default ()) - A flag indicating whether to stream events for the fine-tune job. If set to true, events will be sent as data-only server-sent events as they become available. The stream will terminate with a data: [DONE] message when the job is finished (succeeded, cancelled, or failed). If set to false, only events generated so far will be returned..
Return Type

post 'fine-tunes/[string fineTuneId]/cancel

Isolated FunctionResource Function
function post 'fine\-tunes/[string fineTuneId]/cancel(string apiVersion) returns FineTune|error

Cancels the processing of the fine-tune job specified by the given fine-tune-id.

Parameters
  • apiVersion string - The requested API version.
Return Type

get models

Isolated FunctionResource Function
function get models(string apiVersion) returns ModelList|error

Gets a list of all models that are accessible by the Azure OpenAI resource. These include base models as well as all successfully completed fine-tuned models owned by the Azure OpenAI resource.

Parameters
  • apiVersion string - The requested API version.
Return Type

get models/[string modelId]

Isolated FunctionResource Function
function get models/[string modelId](string apiVersion) returns Model|error

Gets details for the model specified by the given modelId.

Parameters
  • apiVersion string - The requested API version.
Return Type

Records

azure.openai.finetunes: ApiKeysConfig

Closed record

Provides API key configurations needed when communicating with a remote HTTP endpoint.

Fields
  • apiKey string - Provide your Cognitive Services Azure OpenAI account key here.

azure.openai.finetunes: Capabilities

The capabilities of a base or fine tune model.

Fields
  • fine_tune boolean - A value indicating whether a model can be used for fine tuning.
  • inference boolean - A value indicating whether a model can be deployed.
  • completion boolean - A value indicating whether a model supports completion.
  • embeddings boolean - A value indicating whether a model supports embeddings.
  • scale_types ScaleType[] - The supported scale types for deployments of this model.

azure.openai.finetunes: ClientHttp1Settings

Closed record

Provides settings related to HTTP/1.x protocol.

Fields
  • keepAlive KeepAlive(default http:KEEPALIVE_AUTO) - Specifies whether to reuse a connection for multiple requests
  • chunking Chunking(default http:CHUNKING_AUTO) - The chunking behaviour of the request

azure.openai.finetunes: ConnectionConfig

Closed record

Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.

Fields
  • httpVersion HttpVersion(default http:HTTP_2_0) - The HTTP version understood by the client
  • timeout decimal(default 60) - The maximum time to wait (in seconds) for a response before closing the connection
  • forwarded string(default "disable") - The choice of setting forwarded/x-forwarded header
  • cache? CacheConfig - HTTP caching related configurations
  • compression Compression(default http:COMPRESSION_AUTO) - Specifies the way of handling compression (accept-encoding) header
  • circuitBreaker? CircuitBreakerConfig - Configurations associated with the behaviour of the Circuit Breaker
  • retryConfig? RetryConfig - Configurations associated with retrying
  • validation boolean(default true) - Enables the inbound payload validation functionality which provided by the constraint package. Enabled by default

azure.openai.finetunes: Deprecation

Defines the dates of deprecation for the different use cases of a model. Usually base models support 1 year of fine tuning after creation. Inference is typically supported 2 years after creation of base or fine tuned models. The exact dates are specified in the properties.

Fields
  • fine_tune? int - The end date of fine tune support of this model. Will be null for fine tune models.
  • inference int - The end date of inference support of this model.

azure.openai.finetunes: Error

Error content as defined in the Microsoft REST guidelines (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).

Fields
  • code ErrorCode - Error codes as defined in the Microsoft REST guidelines (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).
  • message string - The message of this error.
  • target? string - The location where the error happened if available.
  • details? Error[] - The error details if available.
  • innererror? InnerError - Inner error as defined in the Microsoft REST guidelines (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).

azure.openai.finetunes: ErrorResponse

Error response as defined in the Microsoft REST guidelines (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).

Fields
  • 'error Error - Error content as defined in the Microsoft REST guidelines (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).

azure.openai.finetunes: Event

Fields
  • created_at int - A timestamp when this event was created (in unix epochs).
  • level LogLevel - The verbosity level of an event.
  • message string - The message describing the event. This can be a change of state, e.g., enqueued, started, failed or completed, or other events like uploaded results.

azure.openai.finetunes: EventList

Represents a list of events.

Fields
  • data? Event[] - The list of items.

azure.openai.finetunes: File

A file is a document usable for training and validation. It can also be a service generated document with result details.

Fields
  • status? State - The state of a job or item.
  • created_at? int - A timestamp when this job or item was created (in unix epochs).
  • updated_at? int - A timestamp when this job or item was modified last (in unix epochs).
  • id? string - The identity of this item.
  • bytes? int - The size of this file when available (can be null). File sizes larger than 2^53-1 are not supported to ensure compatibility with JavaScript integers.
  • purpose Purpose - The intended purpose of the uploaded documents. Use "fine-tune" for fine-tuning. This allows us to validate the format of the uploaded file.
  • filename string - The name of the file.
  • statistics? FileStatistics - A file is a document usable for training and validation. It can also be a service generated document with result details.
  • 'error? Error - Error content as defined in the Microsoft REST guidelines (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).

azure.openai.finetunes: FileImport

Defines a document to import from an external content url to be usable with Azure OpenAI.

Fields
  • purpose Purpose - The intended purpose of the uploaded documents. Use "fine-tune" for fine-tuning. This allows us to validate the format of the uploaded file.
  • filename string - The name of the JSON Lines file to be uploaded. If the purpose is set to "fine-tune", each line is a JSON record with "prompt" and "completion" fields representing your training examples.
  • content_url string - The url to download the document from (can be SAS url of a blob or any other external url accessible with a GET request).

azure.openai.finetunes: FileList

Represents a list of files.

Fields
  • data? File[] - The list of items.

azure.openai.finetunes: Files_body

Fields
  • purpose string - The intended purpose of the uploaded documents. Use "fine-tune" for fine-tuning. This allows us to validate the format of the uploaded file.
  • file record { fileContent byte[], fileName string } - Gets or sets the file to upload into Azure OpenAI.

azure.openai.finetunes: FileStatistics

A file is a document usable for training and validation. It can also be a service generated document with result details.

Fields
  • tokens? int - The number of tokens used in prompts and completions for files of kind "fine-tune" once validation of file content is complete.
  • examples? int - The number of contained training examples in files of kind "fine-tune" once validation of file content is complete.

azure.openai.finetunes: FineTune

Fine tuning is a job to tailor a model to specific training data.

Fields
  • status? State - The state of a job or item.
  • created_at? int - A timestamp when this job or item was created (in unix epochs).
  • updated_at? int - A timestamp when this job or item was modified last (in unix epochs).
  • id? string - The identity of this item.
  • model string - The identifier (model-id) of the base model used for the fine-tune.
  • fine_tuned_model? string - The identifier (model-id) of the resulting fine tuned model. This property is only populated for successfully completed fine-tune runs. Use this identifier to create a deployment for inferencing.
  • training_files File[] - The file identities (file-id) that are used for training the fine tuned model.
  • validation_files? File[] - The file identities (file-id) that are used to evaluate the fine tuned model during training.
  • result_files? File[] - The result file identities (file-id) containing training and evaluation metrics in csv format. The file is only available for successfully completed fine-tune runs.
  • events? Event[] - The events that show the progress of the fine-tune run including queued, running and completed.
  • organisation_id? string - The organisation id of this fine tune job. Unused on Azure OpenAI; compatibility for OpenAI only.
  • user_id? string - The user id of this fine tune job. Unused on Azure OpenAI; compatibility for OpenAI only.
  • hyperparams? HyperParameters - The hyper parameter settings used in a fine tune job.
  • suffix? string - The suffix used to identify the fine-tuned model.
  • 'error? Error - Error content as defined in the Microsoft REST guidelines (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).

azure.openai.finetunes: FineTuneCreation

Defines the values of a fine tune job.

Fields
  • model string - The identifier (model-id) of the base model used for this fine-tune.
  • training_file string - The file identity (file-id) that is used for training this fine tuned model.
  • validation_file? string - The file identity (file-id) that is used to evaluate the fine tuned model during training.
  • suffix? string - The suffix used to identify the fine-tuned model. The suffix can contain up to 40 characters (a-z, A-Z, 0-9,- and _) that will be added to your fine-tuned model name.
  • n_epochs? int - The number of epochs to train the model for. An epoch refers to one full cycle through the training dataset.
  • batch_size? int - The batch size to use for training. The batch size is the number of training examples used to train a single forward and backward pass. In general, we've found that larger batch sizes tend to work better for larger datasets. The default value as well as the maximum value for this property are specific to a base model.
  • learning_rate_multiplier? decimal - The learning rate multiplier to use for training. The fine-tuning learning rate is the original learning rate used for pre-training multiplied by this value. Larger learning rates tend to perform better with larger batch sizes. We recommend experimenting with values in the range 0.02 to 0.2 to see what produces the best results.
  • prompt_loss_weight? decimal - The weight to use for loss on the prompt tokens. This controls how much the model tries to learn to generate the prompt (as compared to the completion which always has a weight of 1.0), and can add a stabilizing effect to training when completions are short. If prompts are extremely long (relative to completions), it may make sense to reduce this weight so as to avoid over-prioritizing learning the prompt.
  • compute_classification_metrics? boolean - A value indicating whether to compute classification metrics. If set, we calculate classification-specific metrics such as accuracy and F-1 score using the validation set at the end of every epoch. These metrics can be viewed in the results file. In order to compute classification metrics, you must provide a validation_file.Additionally, you must specify classification_n_classes for multiclass classification or classification_positive_class for binary classification.
  • classification_n_classes? int - The number of classes in a classification task. This parameter is required for multiclass classification.
  • classification_positive_class? string - The positive class in binary classification. This parameter is needed to generate precision, recall, and F1 metrics when doing binary classification.
  • classification_betas? decimal[] - The classification beta values. If this is provided, we calculate F-beta scores at the specified beta values. The F-beta score is a generalization of F-1 score. This is only used for binary classification. With a beta of 1 (i.e.the F-1 score), precision and recall are given the same weight. A larger beta score puts more weight on recall and less on precision. A smaller beta score puts more weight on precision and less on recall.

azure.openai.finetunes: FineTuneList

Represents a list of fine tunes.

Fields

azure.openai.finetunes: HyperParameters

The hyper parameter settings used in a fine tune job.

Fields
  • batch_size? int - The batch size to use for training. The batch size is the number of training examples used to train a single forward and backward pass. In general, we've found that larger batch sizes tend to work better for larger datasets. The default value as well as the maximum value for this property are specific to a base model.
  • learning_rate_multiplier? decimal - The learning rate multiplier to use for training. The fine-tuning learning rate is the original learning rate used for pre-training multiplied by this value. Larger learning rates tend to perform better with larger batch sizes. We recommend experimenting with values in the range 0.02 to 0.2 to see what produces the best results.
  • n_epochs? int - The number of epochs to train the model for. An epoch refers to one full cycle through the training dataset.
  • prompt_loss_weight? decimal - The weight to use for loss on the prompt tokens. This controls how much the model tries to learn to generate the prompt (as compared to the completion which always has a weight of 1.0), and can add a stabilizing effect to training when completions are short. If prompts are extremely long (relative to completions), it may make sense to reduce this weight so as to avoid over-prioritizing learning the prompt.
  • compute_classification_metrics? boolean - A value indicating whether to compute classification metrics. If set, we calculate classification-specific metrics such as accuracy and F-1 score using the validation set at the end of every epoch. These metrics can be viewed in the results file. In order to compute classification metrics, you must provide a validation_file.Additionally, you must specify classification_n_classes for multiclass classification or classification_positive_class for binary classification.
  • classification_n_classes? int - The number of classes in a classification task. This parameter is required for multiclass classification.
  • classification_positive_class? string - The positive class in binary classification. This parameter is needed to generate precision, recall, and F1 metrics when doing binary classification.
  • classification_betas? decimal[] - The classification beta values. If this is provided, we calculate F-beta scores at the specified beta values. The F-beta score is a generalization of F-1 score. This is only used for binary classification. With a beta of 1 (i.e.the F-1 score), precision and recall are given the same weight. A larger beta score puts more weight on recall and less on precision. A smaller beta score puts more weight on precision and less on recall.

azure.openai.finetunes: InnerError

Inner error as defined in the Microsoft REST guidelines (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).

Fields
  • code? InnerErrorCode - Inner error codes as defined in the Microsoft REST guidelines (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).
  • innererror? InnerError - Inner error as defined in the Microsoft REST guidelines (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).

azure.openai.finetunes: Model

A model is either a base model or the result of a successful fine tune job.

Fields
  • status? State - The state of a job or item.
  • created_at? int - A timestamp when this job or item was created (in unix epochs).
  • updated_at? int - A timestamp when this job or item was modified last (in unix epochs).
  • id? string - The identity of this item.
  • model? string - The base model identity (model-id) if this is a fine tune model; otherwise null.
  • fine_tune? string - The fine tune job identity (fine-tune-id) if this is a fine tune model; otherwise null.
  • capabilities Capabilities - The capabilities of a base or fine tune model.
  • lifecycle_status LifeCycleStatus - The life cycle status of a model. Note: A model can be promoted from "preview" to "generally-available", but never from "generally-available" to "preview".
  • deprecation Deprecation - Defines the dates of deprecation for the different use cases of a model. Usually base models support 1 year of fine tuning after creation. Inference is typically supported 2 years after creation of base or fine tuned models. The exact dates are specified in the properties.

azure.openai.finetunes: ModelList

Represents a list of models.

Fields
  • data? Model[] - The list of items.

azure.openai.finetunes: ProxyConfig

Closed record

Proxy server configurations to be used with the HTTP client endpoint.

Fields
  • host string(default "") - Host name of the proxy server
  • port int(default 0) - Proxy server port
  • userName string(default "") - Proxy server username
  • password string(default "") - Proxy server password

String types

azure.openai.finetunes: ScaleType

string

ScaleType

Defines how scaling operations will be executed.

azure.openai.finetunes: LifeCycleStatus

string

LifeCycleStatus

The life cycle status of a model. Note: A model can be promoted from "preview" to "generally-available", but never from "generally-available" to "preview".

azure.openai.finetunes: LogLevel

string

LogLevel

The verbosity level of an event.

azure.openai.finetunes: InnerErrorCode

string

InnerErrorCode

Inner error codes as defined in the Microsoft REST guidelines (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).

azure.openai.finetunes: TypeDiscriminator

string

TypeDiscriminator

Defines the type of an object.

azure.openai.finetunes: Purpose

string

Purpose

The intended purpose of the uploaded documents. Use "fine-tune" for fine-tuning. This allows us to validate the format of the uploaded file.

azure.openai.finetunes: State

string

State

The state of a job or item.

azure.openai.finetunes: ErrorCode

string

ErrorCode

Error codes as defined in the Microsoft REST guidelines (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).

Import

import ballerinax/azure.openai.finetunes;Copy

Other versions

1.0.2

1.0.11.0.0

Metadata

Released date: 3 days ago

Version: 1.0.2

License: Apache-2.0

Compatibility

Platform: any

Ballerina version: 2201.8.0

GraalVM compatible: Yes

Pull count

Total: 35

Current verison: 0

Weekly downloads

Source repository

Keywords

Type/Connector

AI/Fine-tunes

Vendor/Microsoft

Area/AI & Machine Learning

Cost/Paid

Fine-tunes

Files

Models

Azure OpenAI

Contributors

Dependencies

ballerina/url/2.4.0ballerina/mime/2.9.0ballerina/constraint/1.5.0
See more...

Terms of service

Privacy policy

Cookie policy

Delete policy

© 2026 WSO2 LLC