Datasets

Overview

Your dataset is the single biggest lever on the quality of a fine-tuned model. This page covers the file formats Emissary accepts, the exact schema each task type expects, and best practices for preparing clean, high-quality data.

Each example in your dataset is an input → expected output pair. The precise shape of that pair depends on your task type (text classification looks different from a vision-language chat), so jump to the schema for your task type below.

---

Supported file formats

Emissary supports JSONL, JSON, and CSV.

Upload JSONL whenever you can

We strongly recommend JSONL (JSON Lines). When you upload a dataset, Emissary runs a profiling pass that validates every row against your task's schema and surfaces key metadata — row counts, class balance, token-length distributions, and outlier samples — before you train. Because each line in a JSONL file is one self-contained record, profiling is faster and far more reliable on JSONL than on any other format. It's also the only format that cleanly represents the structured and multimodal schemas (classification label maps, NER entities, image content blocks). CSV is fine for simple text input→output tasks, but JSONL is the safe default for everything.

JSONL (recommended)

One JSON object per line, no enclosing array, no trailing commas. Each line is one training example.

{"prompt": "What is the capital of France?", "completion": "Paris."}
{"prompt": "Explain photosynthesis.", "completion": "Plants convert light into chemical energy."}

JSON

A single JSON array of example objects. Functionally equivalent to JSONL but parsed as one document, which makes profiling and error-reporting coarser-grained.

CSV

Two columns, input and expected_output, for simple text-in / text-out tasks (completion, regression, single-text classification). Structured and multimodal task types (NER, embedding, CLIP, VLM, and label-map classification) require JSONL.

input,expected_output
"What is AI?","Artificial intelligence is the simulation of human intelligence in machines."
"Define machine learning.","A subset of AI where models learn patterns from data."

---

Schemas by task type

The examples below mirror the Schema guide drawer in the dataset upload screen — open it any time from the upload page to copy a sample or download a starter .jsonl. All examples are shown as JSONL (one object per line; multi-line here only for readability).

Classification

Assign labels from a fixed schema to each input. The completion is a map of label → 1/0 (applies / doesn't), and the label set is auto-detected from the keys across your file — so keep the same keys on every row.

Field	Type	Required	Description
prompt	string	required	The input text to classify.
completion	object<string, 0 | 1>	required	Map of label → binary relevance.

Pick the variant that matches how your labels relate:

• Binary — a single label key with value 0 or 1.
• Multi-class — labels are mutually exclusive; exactly one key is 1, the rest 0.
• Multi-label — an input can have several labels; more than one key may be 1.

{
  "prompt": "This is a sample text for multi-class classification",
  "completion": { "Label_1": 1, "Label_2": 0, "Label_3": 0 }
}

Profiling warns if any class has fewer than ~20 examples — aim for balanced representation across labels.

Completion

Teach a base model to produce a target completion for a given prompt.

Field	Type	Required	Description
prompt	string	required	The input text shown to the model.
completion	string	required	The target response. Exclude the prompt itself.

{"prompt": "Summarize the article in one sentence.", "completion": "The article argues that…"}
{"prompt": "Translate to French: I'm hungry", "completion": "J'ai faim."}

Chat

Fine-tune a conversational model on ordered multi-turn exchanges.

Field	Type	Required	Description
messages	array<object>	required	Ordered turns, each with a role and content.
messages[].role	"user" | "assistant" | "system"	required	Who is speaking on this turn.
messages[].content	string	required	The text of the turn.

{"messages": [
  {"role": "system", "content": "You are a helpful assistant."},
  {"role": "user", "content": "Tell me a joke."},
  {"role": "assistant", "content": "Why did the scarecrow win an award? He was outstanding in his field."}
]}

System messages are optional and prepended to the conversation at training time. By default, the last assistant turn is used as the training target.

Regression

Predict a continuous numeric value for each input.

Field	Type	Required	Description
prompt	string	required	The input text.
completion	float	required	The ground-truth numeric target.

{"prompt": "This is a sample text for a regression task.", "completion": 0.231}

For large or wide-ranging targets, normalize before training for stability. In CSV, use the input and expected_output columns.

Embedding

Train a text embedder so that similar inputs map close together in vector space.

Field	Type	Required	Description
itemA.text	string	required	First text in the pair.
itemB.text	string	required	Second text in the pair.
similarity	float · -1 to 1	required	Target similarity; 1 = identical, -1 = opposite.

{
  "itemA": { "text": "Example Text A" },
  "itemB": { "text": "Example Text B" },
  "similarity": 1
}

Cover both high- and low-similarity pairs for balanced training, and keep each text within the base model's context length.

NER (named-entity recognition)

Extract typed entity mentions from each input.

Field	Type	Required	Description
prompt	string	required	The input text to extract entities from.
completion	string (JSON)	required	A JSON-encoded string mapping entity type → list of mentions.

The completion is a serialized JSON string, not a nested object — use an empty array for entity types with no mentions, and keep entity-type names consistent across the file.

{
  "prompt": "This is a sample text for an NER task.",
  "completion": "{\"Entity_Type_A\": [\"sample\"], \"Entity_Type_B\": [\"NER task\"], \"Entity_Type_C\": []}"
}

CLIP Classification

Classify a pair of images as a policy violation or not.

Field	Type	Required	Description
prompt.content	array<ImageItem>	required	Two image items to compare.
completion.violation	0 | 1	required	1 if the pair is a violation, else 0.

{
  "prompt": { "content": [
    {"type": "image", "image": "data:image/jpeg;base64,/9j/..."},
    {"type": "image", "image": "data:image/jpeg;base64,/9j/..."}
  ]},
  "completion": { "violation": 1 }
}

Images may be base64 data URLs or S3/GCS URLs, and are auto-resized to 1024px on the long edge.

CLIP Embedding

Train a joint image/text embedder on paired images, with optional captions.

Field	Type	Required	Description
itemA.image	url | base64	required	First image.
itemB.image	url | base64	required	Second image.
itemA.text	string	optional	Caption for image A.
itemB.text	string	optional	Caption for image B.
similarity	0 | 1	required	1 if the images are similar, else 0.

{
  "itemA": { "image": "data:image/jpeg;base64,/9j/...", "text": "OPTIONAL_TEXT" },
  "itemB": { "image": "data:image/jpeg;base64,/9j/...", "text": "OPTIONAL_TEXT" },
  "similarity": 1
}

Captions are optional; PNG, JPEG, and WebP are supported.

VLM Generation

Fine-tune a vision-language model on multi-turn messages that mix images and text.

Field	Type	Required	Description
messages	array<Message>	required	Ordered turns.
messages[].role	"user" | "assistant"	required	Who is speaking.
messages[].content	array<ContentBlock>	required	Ordered blocks of {type:"image", image} or {type:"text", text}.

{
  "messages": [
    {"role": "user", "content": [
      {"type": "image", "image": "data:image/jpeg;base64,/9j/..."},
      {"type": "text",  "text":  "Your input text"}
    ]},
    {"role": "assistant", "content": [
      {"type": "text", "text": "Your output text"}
    ]}
  ]
}

Image and text blocks may appear in any order within a turn; images are auto-resized to 1024px on the long edge.

VLM Classification

Assign multiple labels to an input that can include images and text.

Field	Type	Required	Description
prompt.content	array<ContentBlock>	required	Input blocks — images and/or text.
completion	object<string, 0 | 1>	required	Map of label → binary relevance.

{
  "prompt": { "content": [
    {"type": "image", "image": "data:image/jpeg;base64,/9j/..."},
    {"type": "text",  "text":  "Your input text"}
  ]},
  "completion": { "Label_1": 1, "Label_2": 0, "Label_3": 0 }
}

At least one image block is expected per sample; the label set is auto-detected across the file.

---

Data formatting guidelines

• Consistent structure — every row must follow its task's schema exactly, with the same keys in the same shape. The first rows define the schema that profiling validates the rest against.
• UTF-8 encoding — encode files as UTF-8 to support the full range of characters and symbols.
• No missing fields — include every required field on every row.
• One record per line (JSONL) — no enclosing array, no trailing commas, no line breaks inside a record.

Data cleaning and preprocessing

• Remove noise — strip irrelevant content, broken samples, and duplicates.
• Normalize text — standardize capitalization, whitespace, and punctuation.
• Fix errors — correct obvious spelling and formatting mistakes that don't reflect real inputs.

Data quality and diversity

• Relevance — include data that closely matches the inputs your deployed model will see.
• Diversity — vary phrasing, length, and edge cases so the model generalizes.
• Balanced representation — for classification, give every class enough examples (profiling flags classes under ~20 samples).

Privacy and compliance

• Anonymize — remove or mask personally identifiable information (PII).
• Comply — ensure your data collection and use meet relevant regulations (GDPR, CCPA, etc.).

Tips for a successful upload

• Start small — upload a small slice first to confirm formatting and see the profiling result before committing the full dataset.
• Validate before uploading — check your JSON/JSONL parses and conforms to the schema.
• Use the Schema guide — copy a sample or download a starter .jsonl straight from the upload screen, then replace the placeholder values with your data.
• Review a sample — manually read a handful of rows to catch labeling or formatting mistakes early.