Fine-tuning API

This reference documents the Fine-tuning endpoints in the PaiTIENT Secure Model Service REST API, allowing you to customize AI models for healthcare-specific use cases while maintaining HIPAA/SOC2 compliance.

Create Fine-tuning Job

Creates a new fine-tuning job.

Request

http

POST /v1/fine-tuning/jobs
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
X-Client-ID: YOUR_CLIENT_ID

json

{
  "base_model": "ZimaBlueAI/HuatuoGPT-o1-8B",
  "dataset_id": "ds_12345abcde",
  "validation_dataset_id": "ds_67890fghij",
  "fine_tuning_method": "lora",
  "model_name": "clinical-assistant-cardiology-v1",
  "hyperparameters": {
    "learning_rate": 1e-4,
    "batch_size": 8,
    "epochs": 3,
    "warmup_steps": 100,
    "lora_rank": 16,
    "lora_alpha": 32,
    "lora_dropout": 0.05,
    "target_modules": ["q_proj", "v_proj"]
  },
  "validation_frequency": 0.1,
  "compute_config": {
    "instance_type": "g5.2xlarge",
    "instance_count": 1,
    "max_runtime_hours": 24
  },
  "security_settings": {
    "network_isolation": true,
    "encryption_level": "maximum",
    "audit_logging": true,
    "compliance_mode": "hipaa"
  },
  "tags": {
    "department": "clinical-research",
    "project": "diabetes-assistant",
    "domain": "cardiology"
  }
}

Response

json

{
  "id": "ft_12345abcde",
  "base_model": "ZimaBlueAI/HuatuoGPT-o1-8B",
  "dataset_id": "ds_12345abcde",
  "validation_dataset_id": "ds_67890fghij",
  "fine_tuning_method": "lora",
  "model_name": "clinical-assistant-cardiology-v1",
  "status": "queued",
  "created_at": "2023-11-01T16:00:00Z",
  "updated_at": "2023-11-01T16:00:00Z",
  "validation_frequency": 0.1,
  "hyperparameters": {
    "learning_rate": 1e-4,
    "batch_size": 8,
    "epochs": 3,
    "warmup_steps": 100,
    "lora_rank": 16,
    "lora_alpha": 32,
    "lora_dropout": 0.05,
    "target_modules": ["q_proj", "v_proj"]
  },
  "compute_config": {
    "instance_type": "g5.2xlarge",
    "instance_count": 1,
    "max_runtime_hours": 24
  },
  "tags": {
    "department": "clinical-research",
    "project": "diabetes-assistant",
    "domain": "cardiology"
  }
}

Get Fine-tuning Job

Retrieves details about a specific fine-tuning job.

Request

http

GET /v1/fine-tuning/jobs/{job_id}
Authorization: Bearer YOUR_API_KEY
X-Client-ID: YOUR_CLIENT_ID

Response

json

{
  "id": "ft_12345abcde",
  "base_model": "ZimaBlueAI/HuatuoGPT-o1-8B",
  "dataset_id": "ds_12345abcde",
  "validation_dataset_id": "ds_67890fghij",
  "fine_tuning_method": "lora",
  "model_name": "clinical-assistant-cardiology-v1",
  "fine_tuned_model": "ft:ZimaBlueAI/HuatuoGPT-o1-8B:clinical-assistant-cardiology-v1:12345abcde",
  "status": "running",
  "created_at": "2023-11-01T16:00:00Z",
  "updated_at": "2023-11-01T16:05:30Z",
  "started_at": "2023-11-01T16:05:30Z",
  "validation_frequency": 0.1,
  "current_epoch": 1,
  "total_epochs": 3,
  "current_step": 250,
  "total_steps": 750,
  "training_loss": 1.532,
  "validation_loss": 1.645,
  "hyperparameters": {
    "learning_rate": 1e-4,
    "batch_size": 8,
    "epochs": 3,
    "warmup_steps": 100,
    "lora_rank": 16,
    "lora_alpha": 32,
    "lora_dropout": 0.05,
    "target_modules": ["q_proj", "v_proj"]
  },
  "compute_config": {
    "instance_type": "g5.2xlarge",
    "instance_count": 1,
    "max_runtime_hours": 24
  },
  "tags": {
    "department": "clinical-research",
    "project": "diabetes-assistant",
    "domain": "cardiology"
  }
}

List Fine-tuning Jobs

Retrieves a list of all fine-tuning jobs.

Request

http

GET /v1/fine-tuning/jobs
Authorization: Bearer YOUR_API_KEY
X-Client-ID: YOUR_CLIENT_ID

Query Parameters

Parameter	Type	Description
`limit`	integer	Maximum number of jobs to return (default: 20, max: 100)
`offset`	integer	Offset for pagination (default: 0)
`status`	string	Filter by status (e.g., "queued", "running", "completed", "failed", "cancelled")
`base_model`	string	Filter by base model
`tags`	object	Filter by tags (e.g., `tags[domain]=cardiology`)

Response

json

{
  "jobs": [
    {
      "id": "ft_12345abcde",
      "base_model": "ZimaBlueAI/HuatuoGPT-o1-8B",
      "model_name": "clinical-assistant-cardiology-v1",
      "fine_tuned_model": "ft:ZimaBlueAI/HuatuoGPT-o1-8B:clinical-assistant-cardiology-v1:12345abcde",
      "status": "running",
      "created_at": "2023-11-01T16:00:00Z",
      "updated_at": "2023-11-01T16:05:30Z",
      "fine_tuning_method": "lora",
      "tags": {
        "domain": "cardiology"
      }
    },
    {
      "id": "ft_67890fghij",
      "base_model": "ZimaBlueAI/HuatuoGPT-o1-8B",
      "model_name": "clinical-assistant-diabetes-v1",
      "fine_tuned_model": "ft:ZimaBlueAI/HuatuoGPT-o1-8B:clinical-assistant-diabetes-v1:67890fghij",
      "status": "completed",
      "created_at": "2023-10-15T09:00:00Z",
      "updated_at": "2023-10-15T11:30:45Z",
      "completed_at": "2023-10-15T11:30:45Z",
      "fine_tuning_method": "lora",
      "tags": {
        "domain": "endocrinology"
      }
    }
  ],
  "pagination": {
    "total": 7,
    "limit": 2,
    "offset": 0,
    "next_offset": 2
  }
}

Cancel Fine-tuning Job

Cancels a running or queued fine-tuning job.

Request

http

POST /v1/fine-tuning/jobs/{job_id}/cancel
Authorization: Bearer YOUR_API_KEY
X-Client-ID: YOUR_CLIENT_ID

Response

json

{
  "id": "ft_12345abcde",
  "status": "cancelling",
  "updated_at": "2023-11-01T16:30:00Z"
}

Get Fine-tuning Metrics

Retrieves detailed metrics for a fine-tuning job.

Request

http

GET /v1/fine-tuning/jobs/{job_id}/metrics
Authorization: Bearer YOUR_API_KEY
X-Client-ID: YOUR_CLIENT_ID

Response

json

{
  "job_id": "ft_12345abcde",
  "steps": [0, 50, 100, 150, 200, 250],
  "training_loss": [2.532, 2.126, 1.897, 1.743, 1.632, 1.532],
  "validation_loss": [2.678, 2.254, 2.031, 1.864, 1.732, 1.645],
  "learning_rate": [1e-5, 5e-5, 1e-4, 1e-4, 1e-4, 1e-4],
  "epochs": [0, 0.2, 0.4, 0.6, 0.8, 1.0],
  "accuracy": [0.76, 0.79, 0.82, 0.84, 0.85, 0.87],
  "perplexity": [12.58, 8.37, 6.67, 5.71, 5.11, 4.63],
  "created_at": "2023-11-01T16:35:00Z"
}

Get Fine-tuning Logs

Retrieves logs for a fine-tuning job.

Request

http

GET /v1/fine-tuning/jobs/{job_id}/logs
Authorization: Bearer YOUR_API_KEY
X-Client-ID: YOUR_CLIENT_ID

Query Parameters

Parameter	Type	Description
`limit`	integer	Maximum number of logs to return (default: 100, max: 1000)
`after`	string	Return logs after this token (for pagination)
`stream`	boolean	If true, logs will be streamed as they are generated (default: false)

Response

json

{
  "logs": [
    {
      "timestamp": "2023-11-01T16:05:30Z",
      "level": "info",
      "message": "Fine-tuning job ft_12345abcde started"
    },
    {
      "timestamp": "2023-11-01T16:05:35Z",
      "level": "info",
      "message": "Loading dataset ds_12345abcde with 1,045 examples"
    },
    {
      "timestamp": "2023-11-01T16:05:40Z",
      "level": "info",
      "message": "Loading validation dataset ds_67890fghij with 215 examples"
    },
    {
      "timestamp": "2023-11-01T16:05:45Z",
      "level": "info",
      "message": "Loading base model ZimaBlueAI/HuatuoGPT-o1-8B"
    },
    {
      "timestamp": "2023-11-01T16:06:30Z",
      "level": "info",
      "message": "Starting training with LoRA (rank=16, alpha=32, dropout=0.05)"
    }
  ],
  "pagination": {
    "after": "eyJsYXN0X2V2YWx1YXRlZF9rZXkiOnsidGltZXN0YW1wIjoiMjAyMy0xMS0wMVQxNjowNjozMFoifX0="
  }
}

Upload Dataset

Uploads a dataset for fine-tuning.

Request

http

POST /v1/datasets
Content-Type: multipart/form-data
Authorization: Bearer YOUR_API_KEY
X-Client-ID: YOUR_CLIENT_ID

--boundary
Content-Disposition: form-data; name="name"

Clinical Guidelines Dataset
--boundary
Content-Disposition: form-data; name="description"

Fine-tuning dataset for clinical guideline adherence
--boundary
Content-Disposition: form-data; name="format"

instruction
--boundary
Content-Disposition: form-data; name="tags"

{"domain":"cardiology","source":"guidelines"}
--boundary
Content-Disposition: form-data; name="file"; filename="clinical_guidelines_dataset.jsonl"
Content-Type: application/jsonl

{"instruction": "Explain the mechanism of action for metformin", "response": "Metformin primarily works by reducing glucose production in the liver (hepatic gluconeogenesis), improving insulin sensitivity in peripheral tissues, and enhancing glucose uptake in skeletal muscle. It also decreases intestinal absorption of glucose."}
{"instruction": "What are the symptoms of diabetic ketoacidosis?", "response": "The main symptoms of diabetic ketoacidosis include excessive thirst, frequent urination, nausea and vomiting, abdominal pain, weakness or fatigue, shortness of breath, fruity-scented breath, and confusion. It may also present with high blood glucose levels, high ketone levels in the urine, and electrolyte imbalances."}
...
--boundary--

Response

json

{
  "id": "ds_12345abcde",
  "name": "Clinical Guidelines Dataset",
  "description": "Fine-tuning dataset for clinical guideline adherence",
  "format": "instruction",
  "num_examples": 1045,
  "total_tokens": 245890,
  "created_at": "2023-11-01T15:30:00Z",
  "status": "processed",
  "tags": {
    "domain": "cardiology",
    "source": "guidelines"
  }
}

Get Dataset

Retrieves details about a specific dataset.

Request

http

GET /v1/datasets/{dataset_id}
Authorization: Bearer YOUR_API_KEY
X-Client-ID: YOUR_CLIENT_ID

Response

json

{
  "id": "ds_12345abcde",
  "name": "Clinical Guidelines Dataset",
  "description": "Fine-tuning dataset for clinical guideline adherence",
  "format": "instruction",
  "num_examples": 1045,
  "total_tokens": 245890,
  "created_at": "2023-11-01T15:30:00Z",
  "status": "processed",
  "token_distribution": {
    "prompt_tokens": 125765,
    "response_tokens": 120125
  },
  "tags": {
    "domain": "cardiology",
    "source": "guidelines"
  }
}

List Datasets

Retrieves a list of all datasets.

Request

http

GET /v1/datasets
Authorization: Bearer YOUR_API_KEY
X-Client-ID: YOUR_CLIENT_ID

Query Parameters

Parameter	Type	Description
`limit`	integer	Maximum number of datasets to return (default: 20, max: 100)
`offset`	integer	Offset for pagination (default: 0)
`format`	string	Filter by format (e.g., "instruction", "conversation")
`tags`	object	Filter by tags (e.g., `tags[domain]=cardiology`)

Response

json

{
  "datasets": [
    {
      "id": "ds_12345abcde",
      "name": "Clinical Guidelines Dataset",
      "format": "instruction",
      "num_examples": 1045,
      "total_tokens": 245890,
      "created_at": "2023-11-01T15:30:00Z",
      "status": "processed",
      "tags": {
        "domain": "cardiology"
      }
    },
    {
      "id": "ds_67890fghij",
      "name": "Validation Dataset",
      "format": "instruction",
      "num_examples": 215,
      "total_tokens": 50345,
      "created_at": "2023-11-01T15:35:00Z",
      "status": "processed",
      "tags": {
        "domain": "cardiology"
      }
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 2,
    "offset": 0,
    "next_offset": 2
  }
}

Delete Dataset

Deletes a dataset.

Request

http

DELETE /v1/datasets/{dataset_id}
Authorization: Bearer YOUR_API_KEY
X-Client-ID: YOUR_CLIENT_ID

Response

json

{
  "id": "ds_12345abcde",
  "deleted": true
}

Validate Dataset

Validates a dataset before uploading.

Request

http

POST /v1/datasets/validate
Content-Type: multipart/form-data
Authorization: Bearer YOUR_API_KEY
X-Client-ID: YOUR_CLIENT_ID

--boundary
Content-Disposition: form-data; name="format"

instruction
--boundary
Content-Disposition: form-data; name="file"; filename="clinical_guidelines_dataset.jsonl"
Content-Type: application/jsonl

{"instruction": "Explain the mechanism of action for metformin", "response": "Metformin primarily works by reducing glucose production in the liver (hepatic gluconeogenesis), improving insulin sensitivity in peripheral tissues, and enhancing glucose uptake in skeletal muscle. It also decreases intestinal absorption of glucose."}
{"instruction": "What are the symptoms of diabetic ketoacidosis?", "response": "The main symptoms of diabetic ketoacidosis include excessive thirst, frequent urination, nausea and vomiting, abdominal pain, weakness or fatigue, shortness of breath, fruity-scented breath, and confusion. It may also present with high blood glucose levels, high ketone levels in the urine, and electrolyte imbalances."}
...
--boundary--

Response

json

{
  "is_valid": true,
  "num_examples": 1045,
  "total_tokens": 245890,
  "token_distribution": {
    "prompt_tokens": 125765,
    "response_tokens": 120125
  },
  "format_details": {
    "format": "instruction",
    "has_instructions": true,
    "has_responses": true
  },
  "suggestions": [
    "Consider adding more examples for rare medical conditions",
    "Some responses exceed 500 tokens, which may impact training"
  ]
}

Merge Datasets

Merges multiple datasets into a single dataset.

Request

http

POST /v1/datasets/merge
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
X-Client-ID: YOUR_CLIENT_ID

json

{
  "dataset_ids": [
    "ds_12345abcde",
    "ds_67890fghij",
    "ds_klmno12345"
  ],
  "name": "Multi-specialty Guidelines Dataset",
  "description": "Combined dataset for multi-task fine-tuning",
  "tags": {
    "domain": "multi-specialty",
    "source": "guidelines"
  }
}

Response

json

{
  "id": "ds_merged12345",
  "name": "Multi-specialty Guidelines Dataset",
  "description": "Combined dataset for multi-task fine-tuning",
  "format": "instruction",
  "num_examples": 2845,
  "total_tokens": 698245,
  "created_at": "2023-11-01T16:45:00Z",
  "status": "processed",
  "source_datasets": [
    "ds_12345abcde",
    "ds_67890fghij",
    "ds_klmno12345"
  ],
  "tags": {
    "domain": "multi-specialty",
    "source": "guidelines"
  }
}

List Fine-tuned Models

Retrieves a list of all fine-tuned models.

Request

http

GET /v1/models
Authorization: Bearer YOUR_API_KEY
X-Client-ID: YOUR_CLIENT_ID

Query Parameters

Parameter	Type	Description
`limit`	integer	Maximum number of models to return (default: 20, max: 100)
`offset`	integer	Offset for pagination (default: 0)
`base_model`	string	Filter by base model
`fine_tuned_only`	boolean	If true, return only fine-tuned models (default: false)
`tags`	object	Filter by tags (e.g., `tags[domain]=cardiology`)

Response

json

{
  "models": [
    {
      "id": "ft:ZimaBlueAI/HuatuoGPT-o1-8B:clinical-assistant-cardiology-v1:12345abcde",
      "base_model": "ZimaBlueAI/HuatuoGPT-o1-8B",
      "name": "clinical-assistant-cardiology-v1",
      "fine_tuning_job_id": "ft_12345abcde",
      "created_at": "2023-11-01T18:30:45Z",
      "fine_tuning_method": "lora",
      "tags": {
        "domain": "cardiology"
      }
    },
    {
      "id": "ft:ZimaBlueAI/HuatuoGPT-o1-8B:clinical-assistant-diabetes-v1:67890fghij",
      "base_model": "ZimaBlueAI/HuatuoGPT-o1-8B",
      "name": "clinical-assistant-diabetes-v1",
      "fine_tuning_job_id": "ft_67890fghij",
      "created_at": "2023-10-15T11:30:45Z",
      "fine_tuning_method": "lora",
      "tags": {
        "domain": "endocrinology"
      }
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 2,
    "offset": 0,
    "next_offset": 2
  }
}

Error Codes

Code	Description
`invalid_request_error`	The request was malformed or missing required parameters
`authentication_error`	API key or client ID is invalid or missing
`permission_denied`	The API key doesn't have permission to perform the operation
`resource_not_found`	The requested resource (job, dataset, model) doesn't exist
`quota_exceeded`	Account quota for fine-tuning has been exceeded
`rate_limit_exceeded`	Too many requests in a given time period
`fine_tuning_error`	Error occurred during fine-tuning
`dataset_error`	Error with dataset format or content
`validation_error`	One or more parameters failed validation
`internal_error`	An internal error occurred

Webhook Notifications

Subscribe to webhook notifications to receive real-time updates about your fine-tuning jobs.

Fine-tuning Events

Event	Description
`fine_tuning.job.queued`	A new fine-tuning job has been queued
`fine_tuning.job.started`	A fine-tuning job has started
`fine_tuning.job.epoch_completed`	A fine-tuning epoch has completed
`fine_tuning.job.succeeded`	A fine-tuning job has succeeded
`fine_tuning.job.failed`	A fine-tuning job has failed
`fine_tuning.job.cancelled`	A fine-tuning job has been cancelled
`dataset.uploaded`	A new dataset has been uploaded
`dataset.processed`	A dataset has been processed
`dataset.failed`	Dataset processing has failed

Webhook Configuration

Configure webhooks through the PaiTIENT dashboard or API.

Fine-tuning API ​

Create Fine-tuning Job ​

Request ​

Response ​

Get Fine-tuning Job ​

Request ​

Response ​

List Fine-tuning Jobs ​

Request ​

Query Parameters ​

Response ​

Cancel Fine-tuning Job ​

Request ​

Response ​

Get Fine-tuning Metrics ​

Request ​

Response ​

Get Fine-tuning Logs ​

Request ​

Query Parameters ​

Response ​

Upload Dataset ​

Request ​

Response ​

Get Dataset ​

Request ​

Response ​

List Datasets ​

Request ​

Query Parameters ​

Response ​

Delete Dataset ​

Request ​

Response ​

Validate Dataset ​

Request ​

Response ​

Merge Datasets ​

Request ​

Response ​

List Fine-tuned Models ​

Request ​

Query Parameters ​

Response ​

Error Codes ​

Webhook Notifications ​

Fine-tuning Events ​

Webhook Configuration ​

Fine-tuning API

Create Fine-tuning Job

Request

Response

Get Fine-tuning Job

Request

Response

List Fine-tuning Jobs

Request

Query Parameters

Response

Cancel Fine-tuning Job

Request

Response

Get Fine-tuning Metrics

Request

Response

Get Fine-tuning Logs

Request

Query Parameters

Response

Upload Dataset

Request

Response

Get Dataset

Request

Response

List Datasets

Request

Query Parameters

Response

Delete Dataset

Request

Response

Validate Dataset

Request

Response

Merge Datasets

Request

Response

List Fine-tuned Models

Request

Query Parameters

Response

Error Codes

Webhook Notifications

Fine-tuning Events

Webhook Configuration