ShareGPT vs Alpaca vs ChatML: Which Dataset Format and When

TL;DR

Alpaca, ShareGPT, and ChatML are the three dataset formats you will encounter in LLM fine-tuning. They are not interchangeable. Each one structures the relationship between instruction, input, and output differently, which changes how the model learns role boundaries and when it expects to start and stop generating. Using the wrong format for your task produces models that behave inconsistently in ways that are difficult to diagnose. This post explains what each format is, what it is designed for, how to recognize which one your existing data is in, and how to choose the right one before you start training.

Here is a mistake that is more common than people admit.

You prepare a dataset in alpaca format because that is what the tutorial used. Your task is actually a multi-turn conversation. The training run completes cleanly. But the model at inference time does not handle conversation history the way you expected. It generates weird role labels. It stops generating at the wrong moment. The loss curve looked fine but the model behavior did not.

The problem was the format mismatch, not the data, not the config, not the model size.

Format choice is not a minor detail. It determines how your model learns to read and generate structured conversations. Here is how to get it right.

What Format Choice Actually Controls

When you fine-tune a model, the text in your training examples is tokenized and fed to the model as a sequence. The model does not see separate fields. It sees one long string of tokens with special markers indicating where the system prompt ends, where the user turn begins, where the assistant should generate, and where generation should stop.

Different formats use different special tokens and different structures to define those boundaries. If you train in one format and run inference with a different format, the model is reading a different signal than it was trained on. That produces the inconsistent behavior that looks like a model quality problem but is actually a format problem.

Alpaca Format

Alpaca is the simplest format. Each example is a single-turn instruction-response pair.

{
  "instruction": "Classify the sentiment of this review.",
  "input": "The product arrived damaged and support was useless.",
  "output": "Negative"
}

Three fields. Instruction describes the task. Input is the content to operate on. Output is the correct response. The input field is optional. If your task has no additional context, leave it empty or omit it.

Use Alpaca when:

Your task is single-turn. One input, one output, no conversation history needed. Classification, extraction, summarization, translation, simple question answering. If you can describe your task in a single instruction and get a complete response in a single output, Alpaca is the right choice.

Do not use Alpaca when:

Your task requires multi-turn conversation, tool use, or conversation history to produce the right response. Alpaca has no mechanism for representing previous turns. If your model needs to see earlier parts of a conversation to answer correctly, Alpaca cannot represent that.

Alpaca is also increasingly considered a legacy format for instruction fine-tuning on modern models. ChatML is the preferred modern alternative for single-turn tasks on most base models released in 2024 and later. But Alpaca is still widely supported, well-documented, and perfectly appropriate for the tasks it was designed for.

ShareGPT Format

ShareGPT represents conversations as a list of turns. Each turn has a from field and a value field.

{
  "conversations": [
    {"from": "system", "value": "You are a helpful customer support agent."},
    {"from": "human", "value": "My order hasn't arrived yet."},
    {"from": "gpt", "value": "I'm sorry to hear that. Can you share your order number?"},
    {"from": "human", "value": "It's ORDER-12345."},
    {"from": "gpt", "value": "Thank you. Let me look that up for you right now."}
  ]
}

The from field uses human and gpt rather than user and assistant. This is a naming convention from the format's origin in the open-source community, specifically from datasets scraped from ShareGPT conversations.

Use ShareGPT when:

Your task is multi-turn and you are using Axolotl or a framework that has strong native ShareGPT support. Many community datasets on Hugging Face are in ShareGPT format. If you are starting from one of those and fine-tuning with Axolotl, ShareGPT is the path of least resistance.

Do not use ShareGPT when:

You are targeting a modern base model that uses ChatML tokenization natively. ShareGPT and ChatML are semantically equivalent but use different field names and different special tokens. Using ShareGPT with a ChatML-native model requires your framework to handle the conversion. Axolotl does this well. Not all frameworks do.

ShareGPT is being gradually phased out in favor of ChatML in newer tooling, but it remains well-supported in Axolotl and widely used in the open-source fine-tuning community.

ChatML Format

ChatML is the modern standard for multi-turn conversations. It uses role and content fields, which map directly to how most modern models represent conversation internally.

{
  "messages": [
    {"role": "system", "content": "You are a helpful customer support agent."},
    {"role": "user", "content": "My order hasn't arrived yet."},
    {"role": "assistant", "content": "I'm sorry to hear that. Can you share your order number?"},
    {"role": "user", "content": "It's ORDER-12345."},
    {"role": "assistant", "content": "Thank you. Let me look that up for you right now."}
  ]
}

The underlying tokenization uses special tokens like <|im_start|> and <|im_end|> to mark role boundaries. These tokens are part of how most modern models including Llama 3, Qwen, Mistral, and Phi handle conversation natively.

Use ChatML when:

You are fine-tuning a modern base model released in 2024 or later, your task involves multi-turn conversation, you want the cleanest alignment between training format and inference format, or you are using OpenAI's fine-tuning API or any framework that treats ChatML as the primary format.

ChatML is also the right choice when you plan to use structured outputs, tool use, or function calling. The role structure makes it straightforward to represent those additional turn types.

Do not use ChatML when:

You are working with a framework that only supports Alpaca or ShareGPT and does not convert to ChatML. In that case, use what the framework supports natively rather than trying to force a format conversion that the framework handles poorly.

How to Tell Which Format Your Existing Data Is In

If you downloaded a dataset from Hugging Face or received data from someone else, here is how to identify the format.

Open the file and look at the top-level keys.

If you see instruction, input, and output: it is Alpaca.

If you see conversations with from and value fields inside: it is ShareGPT.

If you see messages with role and content fields inside: it is ChatML.

import json

with open("your_data.jsonl") as f:
    example = json.loads(f.readline())

if "instruction" in example:
    print("Alpaca format")
elif "conversations" in example:
    first_turn = example["conversations"][0]
    if "from" in first_turn:
        print("ShareGPT format")
elif "messages" in example:
    first_turn = example["messages"][0]
    if "role" in first_turn:
        print("ChatML format")

Converting Between Formats

Axolotl handles ShareGPT natively and converts to the model's expected tokenization automatically. If you are using Axolotl, set the type field in your dataset config to match your format:

datasets:
  - path: your_data.jsonl
    type: sharegpt        # for ShareGPT format
    # or
    type: alpaca          # for Alpaca format
    # or
    type: chat_template   # for ChatML format

If you need to convert between formats manually, here is a simple ShareGPT to ChatML conversion:

import json

def sharegpt_to_chatml(example):
    role_map = {"human": "user", "gpt": "assistant", "system": "system"}
    messages = []
    for turn in example["conversations"]:
        messages.append({
            "role": role_map.get(turn["from"], turn["from"]),
            "content": turn["value"]
        })
    return {"messages": messages}

converted = []
with open("sharegpt_data.jsonl") as f:
    for line in f:
        converted.append(sharegpt_to_chatml(json.loads(line)))

with open("chatml_data.jsonl", "w") as f:
    for example in converted:
        f.write(json.dumps(example) + "\n")

The Decision in Plain Terms

Single-turn task with no conversation history needed: use Alpaca or ChatML. Alpaca is simpler. ChatML is the modern standard and the better long-term choice for most model families.

Multi-turn conversational task, using Axolotl: use ShareGPT. It is natively supported and widely used in community datasets.

Multi-turn conversational task, using a modern model or OpenAI-compatible framework: use ChatML. It maps directly to how these models represent conversation internally.

The one rule that overrides everything else: be consistent. Every example in your dataset must use the same format. Mixing formats within a dataset produces models that respond inconsistently to different prompt structures. Decide on one format before you generate or collect any data and stick with it throughout.