Guides

Building Valid JSONL Fine-Tuning Datasets from CSV & JSON

Format valid OpenAI chat, Alpaca, and Gemini fine-tuning .jsonl files from spreadsheets and JSON arrays locally with per-line validation.

3 min read

Quick Answer: AI fine-tuning APIs require newline-delimited `JSONL` (`.jsonl`) where each line is an independent JSON object, whereas tabular training sets usually start as spreadsheets or `.csv`. Streaming rows locally into `JSONL` maps columns into OpenAI `messages`, Alpaca `instruction/output`, or raw structured JSON objects offline.

Why fine-tuning & batch APIs require JSONL instead of JSON

Standard JSON wraps records inside an outer `[ ... ]` array, forcing parsers to buffer the entire file before yielding record zero. JSONL (Newline-Delimited JSON) writes one compact, self-contained JSON object per line.

Training pipelines on OpenAI, Anthropic Batch API, and Vertex AI stream millions of JSONL lines independently and validate schema compliance per line.

  • Every line must be single-line minified JSON (no pretty-printed multi-line objects).
  • Blank trailing lines or trailing commas trigger upload validation errors.
  • Each example typically maps into a role-based `messages` array.

Formatting OpenAI Chat and Alpaca training records from CSV

Curated evaluation and training examples often start inside Excel or Google Sheets with `system`, `prompt`/`user`, and `completion`/`assistant` columns. Converting each CSV row manually via custom scripts slows iteration.

CSV to JSONL ships built-in Raw, OpenAI Chat (`messages[]`), and Alpaca (`instruction/input/output`) templates so spreadsheets export straight to ready-to-train JSONL locally.

json
{"messages":[{"role":"user","content":"Explain UTF-8 BOM"},{"role":"assistant","content":"A 3-byte EF BB BF header telling Excel to decode UTF-8."}]}

Convert CSV datasets to OpenAI/Alpaca JSONL

Extracting nested JSON arrays into validated JSONL

If your source export is a nested API object such as `{ "data": { "samples": [...] } }`, pass the dot path `data.samples` into JSON to JSONL to unwrap the array and validate every emitted line.

Convert JSON arrays or validate JSONL

Estimating dataset token cost locally

Proprietary training examples should never be pasted into third-party token counters. Measure your generated JSONL prompt footprint offline before kicking off fine-tuning runs.

Count tokens across GPT-5, Claude 4 & Gemini 2.5

References

Frequently asked questions

What column names work with the OpenAI Chat CSV preset?

Columns named system, user/prompt/question, and assistant/completion/answer map cleanly into the messages role array; extra columns fall back cleanly when using Raw mode.

Can I convert an existing JSONL log file back into a JSON array?

Yes. Switch JSON to JSONL's direction option to JSONL -> JSON to collect every line into a single formatted JSON array.

Why did my fine-tuning upload fail on line 142?

Most often an unescaped quote, empty line, or NaN token broke JSON syntax on that row. Enabling Validate Every Line flags bad lines immediately.

Related formats

Related Comparisons

Related Guides