Skip to main content

Serverless Fine-Tuning quickstart

Follow this quickstart to fine-tune a base model for your use case or to test how the Serverless Fine-Tuning API works. For a more detailed walkthrough, see Fine-tune a model.

Prerequisites​

  • A training dataset in JSON Lines (JSONL) or Parquet format, 3 GB or smaller.
  • Python 3.9 or later (if you use the Python client), or curl.

1. Log in or create an account​

Log in to the Crusoe Cloud Console or Create an account.

After you log in, switch to the Intelligence Foundry using the product selector in the top-right corner of the console.

2. Generate an API key and authenticate​

To create an API key through the console:

  1. From the console, select the organization name in the top-left corner of the console and click Manage Organization.
  2. Select Security > Inference API keys from the left navigation.
  3. Click Create.
  4. (Optional) Enter an alias for your key.
  5. (Optional) Enter an expiration date for your key.
  6. Copy the API key. Make sure that you save the key in a secure location before leaving the page.

Authenticate against the API​

All API calls require an Intelligence API key and the API base URL.

  1. Export the token and base URL in your shell:

    export API_TOKEN='<your token>'
    export URL='https://api.intelligence.crusoecloud.com'

  2. Construct an OpenAI client pointed at the Crusoe gateway. Every Python example on this page assumes you have this openai_client in scope:

    from openai import OpenAI
    import httpx, os

    openai_client = OpenAI(
        api_key=os.environ["API_TOKEN"],
        base_url=f"{os.environ['URL']}/v1",
        http_client=httpx.Client(proxy=None, trust_env=False),
    )

    For more information, see Manage API keys.

3. Upload a training dataset​

The example below uses the openai Python client because the Serverless Fine-Tuning API is OpenAI-compatible. Substitute your dataset path for train.jsonl.

  1. Install the OpenAI Python client:

    pip install openai httpx

  2. Create a client pointed at the Crusoe gateway and upload the file:

    from openai import OpenAI
    import httpx, os

    openai_client = OpenAI(
        api_key=os.environ["API_TOKEN"],
        base_url=f"{os.environ['URL']}/v1",
        http_client=httpx.Client(proxy=None, trust_env=False),
    )

    with open("train.jsonl", "rb") as f:
        file_obj = openai_client.files.create(file=f, purpose="fine-tune")

    print(file_obj.id)

  3. Save the printed file ID. You'll pass it to the job creation call.

4. Launch a fine-tuning job​

  1. Create a job that references your uploaded file and a base model. Substitute the file ID and a supported base model ID:

    job = openai_client.fine_tuning.jobs.create(
        training_file="<file id from previous step>",
        model="model-qwen-qwen3-8b-2662a271",
        hyperparameters={
            "n_epochs": 3,
            "batch_size": 64,
            "learning_rate": 0.0001,
        },
    )
    print(job.id)

  2. Use retrieve to poll the job until it succeeds:

    retrieved = openai_client.fine_tuning.jobs.retrieve(job.id)
    print(retrieved.status)

    You can also watch live training loss, validation loss, and the estimated time to completion (ETA) on the Fine-Tuning page in the Intelligence Foundry.

5. (Optional) Download a checkpoint​

  1. List the checkpoints emitted by the finished job:

    checkpoints = openai_client.fine_tuning.jobs.checkpoints.list(job.id).data
    for ckpt in checkpoints:
        print(ckpt.id, ckpt.metrics)

  2. Download the checkpoint you want. The example uses curl for the binary stream:

    BEST_CHECKPOINT='<checkpoint id from the list above>'
    curl -s $URL/v1/files/${BEST_CHECKPOINT}/content \
      --header 'Accept: application/json' \
      --header "Authorization: Bearer $API_TOKEN" \
      --output checkpoint-best.zip

  3. Unzip the archive on the machine you'll serve from.

6. Self-serve a deployment for your checkpoint​

From the fine-tuned model's job details page, find the checkpoint you want to deploy, click the corresponding three-dot menu, and select Deploy. For more information on self-serve deployments, see Self-Serve Deployments.