A fine-tuning dataset is a behavioral specification expressed as examples. Each record tells the model what a successful response looks like for a particular input, context, and constraint. The work is therefore closer to writing tests and product policy than collecting a large pile of text.
Start with a prompt-only baseline and a held-out evaluation set. Fine-tuning is justified when the baseline shows a repeated, measurable behavior gap: inconsistent structure, incorrect tool selection, a specialized classification scheme, or a response style that is expensive to demonstrate in every prompt. It is not a reliable way to inject frequently changing facts; retrieval is usually easier to update and audit for that job.
This guide focuses on supervised fine-tuning (SFT), where each example contains an input and the desired output. Provider formats and limits change, so schema and platform statements below were checked against official documentation on 2026-07-24. Confirm the selected model’s current requirements before uploading data.
Choose the right intervention first
Fine-tuning changes model behavior, but it is not the only way to close a quality gap. Use the least complex intervention that meets the acceptance criteria:
| Intervention | Best fit | Dataset implication | Main operational trade-off |
|---|---|---|---|
| Prompting | The desired behavior can be stated clearly in each request | Maintain a compact evaluation set, not a training set | Long instructions consume context and may be inconsistently followed |
| Retrieval-augmented generation (RAG) | Answers depend on current, private, or frequently changing knowledge | Curate documents and retrieval evaluations | Retrieval quality and source freshness become runtime dependencies |
| Supervised fine-tuning (SFT) | A repeated transformation, format, classification scheme, or response policy is hard to demonstrate in every prompt | Build reviewed input-output examples plus held-out evaluation data | Dataset errors become learned behavior, and updates require another training cycle |
These approaches can be combined. For example, SFT can teach when and how to use retrieval without embedding changing facts in model weights. See fine-tuning versus RAG for a fuller decision framework.
Define the target behavior
Write a one-sentence behavior contract before collecting examples. It should name the input, the transformation, the output, and the failure boundary. For example:
Given a customer-support message and an approved label list, return one label and a brief evidence span; do not invent a label.
Turn that contract into a scoring rubric. A useful rubric separates hard requirements from preferences:
| Dimension | Pass condition | Failure example |
|---|---|---|
| Task correctness | Output has the approved label | Uses a plausible but nonexistent label |
| Format | Valid object with required keys | Adds prose outside the object |
| Grounding | Evidence is present in the input | Cites a detail the customer did not provide |
| Safety | Refuses or escalates defined cases | Gives instructions prohibited by policy |
| Style | Concise, neutral language | Adds marketing copy or unnecessary apology |
Run the base model against a small, representative evaluation set using the best prompt you can reasonably deploy. Save its failures by category. The dataset should target those failures rather than teach behavior the base model already performs reliably.
Google’s current Vertex AI tuning guidance recommends establishing an effective prompt first, moving to tuning only when needed, and making training examples resemble the prompts, formats, and contexts seen in production (official tuning overview). That is a useful general rule even if another training stack will be used.
Keep the evaluation records out of the training pool from this point forward. If examples are repeatedly moved from evaluation into training, create new held-out cases for the same failure class; otherwise, the score can improve through memorization rather than broader behavior.
Collect representative examples
Build a coverage matrix before setting a record-count target. Rows can represent task variants, while columns capture the conditions that change difficulty:
- common, uncommon, and boundary inputs;
- short and long requests;
- clear, ambiguous, malformed, and adversarial wording;
- supported languages or locales;
- each output class, tool, or workflow branch;
- successful responses, refusals, abstentions, and escalations.
Sample from production only when collection is permitted and sensitive data can be handled safely. Record provenance, consent or license status, collection window, transformation history, and an owner for each source. Remove secrets and personal data that are not essential to the behavior. If a sensitive attribute matters to evaluation, consider a synthetic substitute that preserves the test condition without retaining a real identity.
Before uploading records to a hosted provider, review the provider’s current storage, retention, and deletion controls for both files and fine-tuning jobs. For example, OpenAI documents endpoint-specific application-state retention separately from abuse-monitoring retention (official data-controls documentation). This is a deployment check, not a substitute for minimizing or redacting the dataset first. For a practical preprocessing workflow, see how to redact personal data before an LLM API call.
Correct class imbalance deliberately. A dataset copied from routine traffic may teach the model to overproduce the most frequent label and ignore rare but important escalation cases. Do not blindly duplicate rare examples; add genuinely different phrasing, contexts, and edge conditions. Synthetic examples can fill a known coverage gap, but label them as synthetic and review them against the same rubric as human-authored data.
There is no universal sufficient size. Google’s Gemma documentation says some example applications can influence behavior with as few as 20 prompt-response pairs, while its Vertex AI overview suggests thinking in terms of 100 or more labeled examples for customized tuning. Both sources emphasize that the required amount depends on the task and variation (official Gemma fine-tuning guide, official Vertex AI tuning overview). Treat those numbers as platform guidance, not a quality threshold. Add examples when error analysis identifies missing coverage, not merely to make the file larger.
Format training records
Choose the target model, training method, and chat template before serializing records. A provider API may accept conversation objects, while an open-weight training pipeline may require a model-specific rendered string. Mixing templates can teach literal control tokens or cause the loss to be calculated over the wrong text.
Keep a provider-neutral source representation and generate the upload format from it. A simple internal record might look like this:
{
"example_id": "support-0042",
"messages": [
{"role": "system", "content": "Classify the request using the approved labels."},
{"role": "user", "content": "I was charged twice for one order."},
{"role": "assistant", "content": "{\"label\":\"duplicate_charge\",\"evidence\":\"charged twice\"}"}
],
"metadata": {
"source": "synthetic",
"scenario": "billing",
"review_status": "approved"
}
}Export only fields supported by the destination. OpenAI’s current fine-tuning API requires a JSONL training file uploaded with the fine-tune purpose; the record structure differs by model format and by supervised, preference, or reinforcement method (official fine-tuning API reference). Vertex AI also accepts JSONL for supervised tuning and can take separate training and optional validation dataset URIs (official Vertex AI API reference).
Make every line valid, independent JSON when using JSONL. Preserve role order, required system instructions, tool definitions, tool calls, and tool results if those are part of the learned behavior. Do not train on hidden reasoning or private annotations. Store reviewer notes in metadata outside the assistant target, then remove unsupported metadata during export.
For open-weight chat models, use the tokenizer’s model-specific chat template rather than inventing control tokens. Hugging Face’s Transformers documentation recommends applying the chat template as a preprocessing step and setting add_generation_prompt=False for training data (official chat-template documentation). Render a small sample and decode its tokens before exporting the full dataset; this catches duplicated beginning/end tokens and missing assistant boundaries.
Clean and deduplicate data
Run deterministic normalization before human review so reviewers see the same form that training will use. Normalize line endings and Unicode, trim accidental outer whitespace, reject invalid encoding, and parse structured outputs. Do not lowercase or rewrite content when capitalization, punctuation, spacing, or exact syntax is part of the desired behavior.
Deduplicate at three levels:
- Exact duplicates: identical normalized inputs and targets.
- Conflicting duplicates: the same input paired with different target behavior.
- Near duplicates: templated or lightly edited examples that add little new coverage.
Exact duplicates silently reweight a behavior. That may be intentional, but it should be a documented sampling decision. Conflicting duplicates are more dangerous because the loss receives incompatible instructions. Send them to an adjudicator who applies the rubric and records why one label won. For near duplicates, compare normalized text, stable hashes, and similarity candidates, then use human review before deletion; two almost identical inputs may represent an important boundary.
Also scan for contamination. Search training data for evaluation prompts, expected answers, benchmark items, copied documentation examples, and records derived from the held-out set. Group related records before splitting: multiple turns from one conversation, translations of one item, paraphrases, and documents from the same source can leak the answer across partitions.
Finally, inspect length distributions rather than only averages. Flag empty targets, unusually long conversations, truncated messages, repeated boilerplate, unbalanced roles, and outputs that violate the rubric. Vertex AI’s tuning API exposes dropped-example counts and reasons for cases such as excessive tokens or invalid media, but local validation should catch those problems before a paid or time-consuming training job begins (official API schema).
Split training and validation sets
Create splits after deduplication and grouping, but before iterative model development. The training split updates the model. The validation split helps compare runs and tune training choices. A test or evaluation split should remain untouched until a candidate is ready for a decision.
An 80/10/10 or 90/10 split can be a starting policy, not a universal rule. Small datasets may need cross-validation or a larger evaluation share; large datasets can produce stable estimates with a smaller percentage. What matters is enough independent coverage in every decision-critical slice.
Random row-level splitting is unsafe when examples share a source. Use a group-aware split so all turns from one conversation, records from one customer-safe source ID, or paraphrases of one seed remain in the same partition. For time-dependent workflows, consider a chronological test set that simulates future traffic. For imbalanced classification, stratify by label while preserving groups.
Hugging Face defines train as data exposed to the model, validation as data reserved for evaluation and hyperparameter improvement, and test as data reserved for evaluation only (official splits documentation). Maintain that separation operationally: restrict write access to the test set, record every evaluation, and never tune a prompt, dataset, or checkpoint based on repeated test-set inspection.
For a deeper evaluation workflow, see how to build an LLM evaluation dataset. The training data and evaluation data can use the same rubric, but they must not contain the same examples or close variants.
Run quality checks
Create a preflight command that fails closed. At minimum, it should report:
- total records and counts by split, source, language, label, and scenario;
- schema, encoding, and JSON parsing errors;
- missing or unknown roles, labels, tools, and required keys;
- empty inputs or targets and unexpected null values;
- exact, conflicting, and candidate near duplicates;
- overlap among train, validation, and test groups;
- input, output, and total token-length distributions using the target tokenizer;
- rubric violations for structured outputs, refusals, citations, or tool calls;
- provenance, license, consent, and sensitive-data review status.
Then sample manually by slice. Review random records, every rare class, the longest examples, every refusal category, every synthetic source, and all automatically repaired records. Two reviewers should independently assess a small shared sample before scaling annotation; low agreement usually means the rubric is ambiguous, not that reviewers need to guess harder.
Use an automated grader only for properties it can reliably observe. JSON validity, allowed labels, required keys, evidence substring checks, and tool-schema validation are strong machine gates. Nuance, factual correctness, tone, and safety boundaries may require expert or human review. Keep grader prompts and versions with the dataset so a changing judge does not silently redefine quality.
For implementation patterns, see machine gates for AI output.
Produce a signed quality report containing checks, thresholds, exceptions, and reviewer approval. A dataset is not ready merely because it uploads successfully. It is ready when its coverage matches the behavior contract, known risks are visible, and a held-out evaluation can distinguish improvement from regression.
Version the dataset
Treat the dataset as a release artifact. Give each immutable release a version, content hash, and manifest. The manifest should identify source snapshots, selection queries, transformation code, schema version, tokenizer, split seed or grouping logic, deduplication settings, review results, excluded records, and the exact files produced.
Keep raw, normalized, reviewed, and exported layers separate. Raw data should be access-controlled and immutable; normalized data should be reproducible from raw inputs; reviewed data should contain adjudicated labels; exported data should contain only the fields accepted by the training platform. Do not overwrite a release after a model has trained on it.
A compact dataset card should answer:
- What behavior is this release intended to teach?
- Which populations and scenarios are represented or missing?
- Where did the records come from, and what usage rights apply?
- Which sensitive-data controls were run?
- How were groups, splits, and duplicates handled?
- Which rubric and reviewers approved the targets?
- Which known biases, gaps, and unresolved exceptions remain?
Link every fine-tuning job to the dataset version, base model identifier, training configuration, code revision, and evaluation report. If a new release improves one slice but damages another, that chain makes rollback and diagnosis possible.
The final handoff should therefore contain more than train.jsonl: include validation and test artifacts, the schema, behavior contract, rubric, coverage report, quality report, dataset card, manifest, and reproducible export command. That package turns a one-off upload into an auditable training input—and makes the next dataset improvement a controlled change instead of a reconstruction exercise.
Frequently asked questions
How many examples do I need to fine-tune an LLM?
There is no universal minimum that guarantees improvement. Start with enough reviewed examples to cover each important scenario and failure class, then add data in response to held-out evaluation errors. Provider guidance such as 20 or 100 examples is a planning reference, not a substitute for coverage and label quality.
Does a fine-tuning dataset have to be JSONL?
It depends on the training stack, but hosted APIs commonly accept JSONL, with one independent JSON object per line. Keep a provider-neutral source dataset and generate the exact upload schema required by the chosen model and tuning method.
What train, validation, and test split should I use?
An 80/10/10 or 90/10 policy is a reasonable starting point, but the correct split depends on dataset size and slice coverage. More importantly, group conversations, paraphrases, and records from the same source into one partition so closely related examples cannot leak across splits.
Can I use synthetic data for fine-tuning?
Yes, synthetic examples can cover rare or sensitive scenarios, but they should be labeled by provenance, checked for repetition, and reviewed against the same rubric as human-authored examples. Keep real held-out evaluation cases so the model is not judged only on patterns generated by another model.
How do I prevent overfitting and evaluation leakage?
Deduplicate before splitting, use group-aware partitions, and keep the final test set access-controlled. Track every prompt, dataset, and checkpoint decision made from evaluation results; repeated tuning against the same test set turns it into development data.
Official sources added in this revision
- OpenAI, Data controls in the OpenAI platform — file and fine-tuning endpoint retention controls. Checked 2026-07-24: official documentation.
- Hugging Face Transformers, Chat templates — model-specific formatting and training preprocessing guidance. Checked 2026-07-24: official documentation.