POST
/
agents
/
{agent_id}
/
tune
curl --request POST \
  --url https://api.contextual.ai/v1/agents/{agent_id}/tune \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'train_dataset_name=<string>' \
  --form 'test_dataset_name=<string>' \
  --form 'personas=<string>' \
  --form synth_data=false \
  --form 'hyperparams[learning_rate]=0.05' \
  --form 'hyperparams[warmup_ratio]=0.5' \
  --form 'hyperparams[lora_rank]=8' \
  --form 'hyperparams[lora_alpha]=8' \
  --form 'hyperparams[lora_dropout]=0.5' \
  --form 'hyperparams[num_epochs]=2'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
agent_id
string
required

ID of the Agent to list tuning jobs for

Body

multipart/form-data
​
training_file
file | null

Local path to the training data file.

The file should be in JSON array format, where each element of the array is a JSON object represents a single training example. The four required fields are guideline, prompt, reference, and knowledge.

  • knowledge (list[str]): Retrieved knowledge used to generate the reference answer. knowledge is a list of retrieved text chunks.

  • reference (str): The gold-standard answer to the prompt.

  • guideline (str): Guidelines for model output. If you do not have special guidelines for the model's output, you can use the System Prompt defined in your Agent configuration as the guideline.

  • prompt (str): Question for the model to respond to.

Example:

[
  {
    "guideline": "The answer should be accurate.",
    "prompt": "What was last quarter's revenue?",
    "reference": "According to recent reports, the Q3 revenue was $1.2 million, a 0.1 million increase from Q2.",
    "knowledge": [
        "Quarterly report: Q3 revenue was $1.2 million.",
        "Quarterly report: Q2 revenue was $1.1 million.",
        ...
    ],
  },
  ...
]
​
test_file
file | null

Optional. Local path to the test data file. The test file should follow the same format as the training data file.

​
train_dataset_name
string | null

Dataset to use for training, created through the /datasets/tune API. Either train_dataset_name or training_file must be provided, but not both.

​
test_dataset_name
string | null

Optional. Dataset to use for testing model checkpoints, created through the /datasets/evaluate API.

​
personas
string

Optional. Comma-separated list of personas to use to generate synthetic data for training

​
synth_data
boolean
default:false

Optional. Whether to generate synthetic data for training

​
hyperparams[learning_rate]
number

Controls how quickly the model adapts to the training data. Must be greater than 0 and less than or equal to 0.1.

Required range: 1 < x <= 0.1
​
hyperparams[warmup_ratio]
number

Fraction of training steps used for learning rate warmup. Must be between 0 and 1 (exclusive).

Required range: 0 <= x < 1
​
hyperparams[lora_rank]
enum<integer>

Controls the capacity of the LoRA adapters. Must be one of: 8, 16, 32, or 64.

Available options:
8,
16,
32,
64
​
hyperparams[lora_alpha]
enum<integer>

Scaling factor that controls the magnitude of LoRA updates. Higher values lead to stronger adaptation effects. The effective learning strength is determined by the ratio of lora_alpha/lora_rank. Must be one of: 8, 16, 32, 64 or 128

Available options:
8,
16,
32,
64,
128
​
hyperparams[lora_dropout]
number

LoRA dropout randomly disables connections during training to prevent overfitting and improve generalization when fine-tuning language models with Low-Rank Adaptation. Must be between 0 and 1 (exclusive).

Required range: 0 <= x < 1
​
hyperparams[num_epochs]
integer

Number of complete passes through the training dataset.

Required range: 1 <= x <= 4

Response

200
application/json
Successful Response

Response to POST /applications/{application_id}/tune request

​
id
string
required

ID of the created tune job

Was this page helpful?