Fine-tunes
Manage fine-tuning jobs to tailor a model to your specific training data.
Related guide: Fine-tune models
Create fine-tune
POST https://api.openai.com/v1/fine-tunes
Creates a job that fine-tunes a specified model from a given dataset.
Response includes details of the enqueued job including job status and the name of the fine-tuned models once complete.
Request body
training_filestringRequired
The ID of an uploaded file that contains training data.
See upload file for how to upload a file.
Your dataset must be formatted as a JSONL file, where each training example is a JSON object with the keys "prompt" and "completion". Additionally, you must upload your file with the purpose fine-tune.
See the fine-tuning guide for more details.
validation_filestringOptional
The ID of an uploaded file that contains validation data.
If you provide this file, the data is used to generate validation metrics periodically during fine-tuning. These metrics can be viewed in the fine-tuning results file. Your train and validation data should be mutually exclusive.
Your dataset must be formatted as a JSONL file, where each validation example is a JSON object with the keys "prompt" and "completion". Additionally, you must upload your file with the purpose fine-tune.
See the fine-tuning guide for more details.
modelstringOptionalDefaults to curie
The name of the base model to fine-tune. You can select one of "ada", "babbage", "curie", "davinci", or a fine-tuned model created after 2022-04-21. To learn more about these models, see the Models documentation.
n_epochsintegerOptionalDefaults to 4
The number of epochs to train the model for. An epoch refers to one full cycle through the training dataset.
batch_sizeintegerOptionalDefaults to null
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.
By default, the batch size will be dynamically configured to be ~0.2% of the number of examples in the training set, capped at 256 - in general, we've found that larger batch sizes tend to work better for larger datasets.
learning_rate_multipliernumberOptionalDefaults to null
The learning rate multiplier to use for training. The fine-tuning learning rate is the original learning rate used for pretraining multiplied by this value.
By default, the learning rate multiplier is the 0.05, 0.1, or 0.2 depending on final batch_size (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_weightnumberOptionalDefaults to 0.01
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_metricsbooleanOptionalDefaults to false
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_classesintegerDefaults to null
The number of classes in a classification task.
This parameter is required for multiclass classification.
classification_positive_classstringOptionalDefaults to null
The positive class in binary classification.
This parameter is needed to generate precision, recall, and F1 metrics when doing binary classification.
classification_betasarrayOptionalDefaults to null
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.
suffixstringOptionalDefaults to null
A string of up to 40 characters that will be added to your fine-tuned model name.
For example, a suffix of "custom-model-name" would produce a model name like ada:ft-your-org:custom-model-name-2022-02-15-04-21-04.
Example request:
curl:
curl https://api.openai.com/v1/fine-tunes \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"training_file": "file-XGinujblHPwGLSztz8cPS8XY"
}'
python:
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.FineTune.create(training_file="file-XGinujblHPwGLSztz8cPS8XY")
node.js:
const { Configuration, OpenAIApi } = require("openai");
const configuration = new Configuration({
apiKey: process.env.OPENAI_API_KEY,
});
const openai = new OpenAIApi(configuration);
const response = await openai.createFineTune({
training_file: "file-XGinujblHPwGLSztz8cPS8XY",
});
Response:
{
"id": "ft-AF1WoRqd3aJAHsqc9NY7iL8F",
"object": "fine-tune",
"model": "curie",
"created_at": 1614807352,
"events": [
{
"object": "fine-tune-event",
"created_at": 1614807352,
"level": "info",
"message": "Job enqueued. Waiting for jobs ahead to complete. Queue number: 0."
}
],
"fine_tuned_model": null,
"hyperparams": {
"batch_size": 4,
"learning_rate_multiplier": 0.1,
"n_epochs": 4,
"prompt_loss_weight": 0.1,
},
"organization_id": "org-...",
"result_files": [],
"status": "pending",
"validation_files": [],
"training_files": [
{
"id": "file-XGinujblHPwGLSztz8cPS8XY",
"object": "file",
"bytes": 1547276,
"created_at": 1610062281,
"filename": "my-data-train.jsonl",
"purpose": "fine-tune-train"
}
],
"updated_at": 1614807352,
}
List fine-tunes
GET https://api.openai.com/v1/fine-tunes
List your organization's fine-tuning jobs
Example request:
curl:
curl https://api.openai.com/v1/fine-tunes \
-H "Authorization: Bearer $OPENAI_API_KEY"
python:
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.FineTune.list()
node.js:
const { Configuration, OpenAIApi } = require("openai");
const configuration = new Configuration({
apiKey: process.env.OPENAI_API_KEY,
});
const openai = new OpenAIApi(configuration);
const response = await openai.listFineTunes();
Response:
{
"object": "list",
"data": [
{
"id": "ft-AF1WoRqd3aJAHsqc9NY7iL8F",
"object": "fine-tune",
"model": "curie",
"created_at": 1614807352,
"fine_tuned_model": null,
"hyperparams": { ... },
"organization_id": "org-...",
"result_files": [],
"status": "pending",
"validation_files": [],
"training_files": [ { ... } ],
"updated_at": 1614807352,
},
{ ... },
{ ... }
]
}
Retrieve fine-tune
GET https://api.openai.com/v1/fine-tunes/{fine_tune_id}
Gets info about the fine-tune job.
Path parameters
fine_tune_idstringRequired
The ID of the fine-tune job
Example request:
curl:
curl https://api.openai.com/v1/fine-tunes/ft-AF1WoRqd3aJAHsqc9NY7iL8F \
-H "Authorization: Bearer $OPENAI_API_KEY"
python:
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.FineTune.retrieve(id="ft-AF1WoRqd3aJAHsqc9NY7iL8F")
node.js:
const { Configuration, OpenAIApi } = require("openai");
const configuration = new Configuration({
apiKey: process.env.OPENAI_API_KEY,
});
const openai = new OpenAIApi(configuration);
const response = await openai.retrieveFineTune("ft-AF1WoRqd3aJAHsqc9NY7iL8F");
Response:
{
"id": "ft-AF1WoRqd3aJAHsqc9NY7iL8F",
"object": "fine-tune",
"model": "curie",
"created_at": 1614807352,
"events": [
{
"object": "fine-tune-event",
"created_at": 1614807352,
"level": "info",
"message": "Job enqueued. Waiting for jobs ahead to complete. Queue number: 0."
},
{
"object": "fine-tune-event",
"created_at": 1614807356,
"level": "info",
"message": "Job started."
},
{
"object": "fine-tune-event",
"created_at": 1614807861,
"level": "info",
"message": "Uploaded snapshot: curie:ft-acmeco-2021-03-03-21-44-20."
},
{
"object": "fine-tune-event",
"created_at": 1614807864,
"level": "info",
"message": "Uploaded result files: file-QQm6ZpqdNwAaVC3aSz5sWwLT."
},
{
"object": "fine-tune-event",
"created_at": 1614807864,
"level": "info",
"message": "Job succeeded."
}
],
"fine_tuned_model": "curie:ft-acmeco-2021-03-03-21-44-20",
"hyperparams": {
"batch_size": 4,
"learning_rate_multiplier": 0.1,
"n_epochs": 4,
"prompt_loss_weight": 0.1,
},
"organization_id": "org-...",
"result_files": [
{
"id": "file-QQm6ZpqdNwAaVC3aSz5sWwLT",
"object": "file",
"bytes": 81509,
"created_at": 1614807863,
"filename": "compiled_results.csv",
"purpose": "fine-tune-results"
}
],
"status": "succeeded",
"validation_files": [],
"training_files": [
{
"id": "file-XGinujblHPwGLSztz8cPS8XY",
"object": "file",
"bytes": 1547276,
"created_at": 1610062281,
"filename": "my-data-train.jsonl",
"purpose": "fine-tune-train"
}
],
"updated_at": 1614807865,
}
Cancel fine-tune
POST https://api.openai.com/v1/fine-tunes/{fine_tune_id}/cancel
Immediately cancel a fine-tune job.
Path parameters
fine_tune_idstringRequired
The ID of the fine-tune job to cancel
Example request:
curl:
curl https://api.openai.com/v1/fine-tunes/ft-AF1WoRqd3aJAHsqc9NY7iL8F/cancel \
-H "Authorization: Bearer $OPENAI_API_KEY"
python:
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.FineTune.cancel(id="ft-AF1WoRqd3aJAHsqc9NY7iL8F")
node.js:
const { Configuration, OpenAIApi } = require("openai");
const configuration = new Configuration({
apiKey: process.env.OPENAI_API_KEY,
});
const openai = new OpenAIApi(configuration);
const response = await openai.cancelFineTune("ft-AF1WoRqd3aJAHsqc9NY7iL8F");
Response:
{
"id": "ft-xhrpBbvVUzYGo8oUO1FY4nI7",
"object": "fine-tune",
"model": "curie",
"created_at": 1614807770,
"events": [ { ... } ],
"fine_tuned_model": null,
"hyperparams": { ... },
"organization_id": "org-...",
"result_files": [],
"status": "cancelled",
"validation_files": [],
"training_files": [
{
"id": "file-XGinujblHPwGLSztz8cPS8XY",
"object": "file",
"bytes": 1547276,
"created_at": 1610062281,
"filename": "my-data-train.jsonl",
"purpose": "fine-tune-train"
}
],
"updated_at": 1614807789,
}
List fine-tune events
GET https://api.openai.com/v1/fine-tunes/{fine_tune_id}/events
Get fine-grained status updates for a fine-tune job.
Path parameters
fine_tune_idstringRequired
The ID of the fine-tune job to get events for.
Query parameters
streambooleanOptionalDefaults to false
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.
Example request:
curl:
curl https://api.openai.com/v1/fine-tunes/ft-AF1WoRqd3aJAHsqc9NY7iL8F/events \
-H "Authorization: Bearer $OPENAI_API_KEY"
python:
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.FineTune.list_events(id="ft-AF1WoRqd3aJAHsqc9NY7iL8F")
node.js:
const { Configuration, OpenAIApi } = require("openai");
const configuration = new Configuration({
apiKey: process.env.OPENAI_API_KEY,
});
const openai = new OpenAIApi(configuration);
const response = await openai.listFineTuneEvents("ft-AF1WoRqd3aJAHsqc9NY7iL8F");
Response:
{
"object": "list",
"data": [
{
"object": "fine-tune-event",
"created_at": 1614807352,
"level": "info",
"message": "Job enqueued. Waiting for jobs ahead to complete. Queue number: 0."
},
{
"object": "fine-tune-event",
"created_at": 1614807356,
"level": "info",
"message": "Job started."
},
{
"object": "fine-tune-event",
"created_at": 1614807861,
"level": "info",
"message": "Uploaded snapshot: curie:ft-acmeco-2021-03-03-21-44-20."
},
{
"object": "fine-tune-event",
"created_at": 1614807864,
"level": "info",
"message": "Uploaded result files: file-QQm6ZpqdNwAaVC3aSz5sWwLT."
},
{
"object": "fine-tune-event",
"created_at": 1614807864,
"level": "info",
"message": "Job succeeded."
}
]
}
Delete fine-tune model
DELETE https://api.openai.com/v1/models/{model}
Delete a fine-tuned model. You must have the Owner role in your organization.
Path parameters
modelstringRequired
The model to delete
Example request:
curl:
curl https://api.openai.com/v1/models/curie:ft-acmeco-2021-03-03-21-44-20 \
-X DELETE \
-H "Authorization: Bearer $OPENAI_API_KEY"
python:
import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Model.delete("curie:ft-acmeco-2021-03-03-21-44-20")
node.js:
const { Configuration, OpenAIApi } = require("openai");
const configuration = new Configuration({
apiKey: process.env.OPENAI_API_KEY,
});
const openai = new OpenAIApi(configuration);
const response = await openai.deleteModel('curie:ft-acmeco-2021-03-03-21-44-20');
Response:
{
"id": "curie:ft-acmeco-2021-03-03-21-44-20",
"object": "model",
"deleted": true
}