SYNTHESIS RECIPE SCHEMA

OVERVIEW

A synthesis recipe defines how Oumi generates a dataset. This page describes the request body used to create one. For complete general and improved-sample requests, see Synthesis recipes.

REQUEST

{
  "displayName": "",
  "description": "",
  "recipeConfig": {
    "type": "synthesize",
    "modelIdentifier": {},
    "inferenceConfig": {},
    "synthesisConfig": {},
    "datasetDistribution": {},
    "agenticInferenceConfig": {}
  }
}

Field	Type	Required	Description
displayName	string	✓	Display name for the recipe
description	string		Description of the initial version
recipeConfig	object	✓	Dataset synthesis configuration

RECIPECONFIG

Field	Type	Required	Description
type	string	✓	Must be `synthesize`
modelIdentifier	object	✓	Hosted model used for synthesis
inferenceConfig	object	✓	Inference settings
synthesisConfig	object	✓	Configuration selected by `synthesisType`
datasetId	integer		Existing dataset that receives the generated training data
datasetDistribution	object		Output split fractions; defaults to `1.0` train
agenticInferenceConfig	object		Tool calling and simulated user settings; see AGENTICINFERENCECONFIG

When datasetId is set, the validation and test fractions must be 0.

MODELIDENTIFIER

Synthesis accepts hosted models.

Field	Type	Required	Description
modelType	string	✓	Hosted model provider
modelName	string	✓	Provider model name
apiKeys	object		Provider API keys; Oumi does not bill usage made with these keys

modelType accepts ANTHROPIC_API, OPENAI_API, GEMINI_API, VERTEX_API, or OUMI_API.

INFERENCECONFIG

Field	Type	Description
inferenceTemperature	number	Sampling temperature
inferenceMaxNewTokens	integer	Maximum number of generated tokens
inferenceSeed	integer	Seed for deterministic generation
requestsPerMinute	integer	Request rate limit
guidedDecoding	object	Not supported for synthesis; omit this field

SYNTHESISCONFIG

synthesisType selects one of the following configurations.

GENERAL

{
  "synthesisType": "general",
  "synthesisConfig": {
    "strategy": "general",
    "numSamples": 100,
    "strategyParams": {}
  }
}

Field	Type	Description
strategy	string	Synthesis strategy; defaults to `general`
numSamples	integer	Number of samples; defaults to `1`
outputPath	string	Output JSONL path
strategyParams	object	Inputs, generated fields, and transformations

strategyParams supports these fields:

Field	Type	Description
inputData	object[]	Dataset or structured data source inputs
inputDocuments	object[]	Document inputs
inputExamples	object[]	Inline example inputs
sampledAttributes	object[]	Attributes sampled from weighted values
combinationSampling	object[]	Sampling rates for attribute combinations
generatedAttributes	object[]	Attributes generated by the model
transformedAttributes	object[]	String, list, dictionary, or chat transformations
passthroughAttributes	string[]	Output fields to retain

Each inputData item contains either datasetId or datasourceId. It may also contain attributeMap.

DOCUMENT Q&A

Field	Type	Required	Description
synthesisType	string	✓	Must be `docqa`
documentTagId	integer	✓	Tag that identifies the source documents
numSamples	integer	✓	Number of samples
segmentationConfig	object		Tokenizer, segment size, and overlap settings

segmentationConfig accepts segmentationType, tokenizer, segmentSize, and segmentOverlap. The only current segmentation type is tokens.

IMPROVED SAMPLES

Field	Type	Required	Description
synthesisType	string	✓	Must be `generate_improved_samples`
evalId	integer	✓	Evaluation used to find failed data items
failureModeIds	integer[]		Failure modes to include
dataItemIds	string[]		Data items to include
numSamplesPerItem	integer	✓	Samples per item, from `1` to `20`
generateResponses	boolean		Must be `true`; defaults to `true`
generateNewConversations	boolean		Generate new conversations; defaults to `true`
outputItemType	string		`train_data` or `eval_data`; defaults to `train_data`

With generateNewConversations set to true, each data item produces numSamplesPerItem new conversations. Each one keeps the original’s subject but makes a different request, and the assistant avoids the original’s mistakes. With false, each data item produces one corrected version of itself, and numSamplesPerItem is ignored. See Generate from failure modes. Data items that called tools are skipped unless agenticInferenceConfig sets tool implementations.

AGENTICINFERENCECONFIG

Makes the synthesis model call tools and, optionally, continue each conversation with a simulated user. Omit it for plain single-turn synthesis. Generate completions and evaluation requests take the same object. For how-tos, see synthesis and evaluations.

{
  "agenticInferenceConfig": {
    "toolImplementations": [{"toolImplementationId": 22}],
    "userModelSpec": {
      "modelIdentifier": {"modelType": "ANTHROPIC_API", "modelName": "claude-sonnet-5"},
      "inferenceConfig": {}
    },
    "maxUserTurns": 5
  }
}

Field	Type	Description
toolImplementations	object[]	Tool implementations the model may call, each with a `toolImplementationId`; at most one per tool name
userModelSpec	object	Hosted model that writes later user turns, with `modelIdentifier` and `inferenceConfig` (`inferenceConfig` may be `{}`)
maxUserTurns	integer	Maximum user messages per conversation, including the first, from `1` to `20`; defaults to `20`; requires `userModelSpec`

An empty agenticInferenceConfig behaves the same as omitting it.

DATASETDISTRIBUTION

Field	Type	Required	Range	Description
train	number	✓	0–1	Training split fraction
validation	number	✓	0–1	Validation split fraction
test	number	✓	0–1	Test split fraction

The three fractions must sum to 1.0.

DOCUMENT Q&A EXAMPLE

{
  "displayName": "Product documentation Q&A",
  "recipeConfig": {
    "type": "synthesize",
    "modelIdentifier": {
      "modelType": "OUMI_API",
      "modelName": "zai-org/GLM-5"
    },
    "inferenceConfig": {
      "inferenceTemperature": 0.7,
      "inferenceMaxNewTokens": 512
    },
    "synthesisConfig": {
      "synthesisType": "docqa",
      "documentTagId": 12,
      "numSamples": 100,
      "segmentationConfig": {
        "segmentationType": "tokens",
        "tokenizer": "openai-community/gpt2",
        "segmentSize": 2048,
        "segmentOverlap": 0
      }
    },
    "datasetDistribution": {
      "train": 0.8,
      "validation": 0.1,
      "test": 0.1
    }
  }
}

VALIDATION RULES

Synthesis accepts hosted model identifiers only.
Positive integer IDs and sample counts must be greater than 0.
numSamples must cover every nonzero dataset split.
combinationSampling rates must sum to no more than 1.0.
Each tool name can be served by at most one tool implementation in agenticInferenceConfig.toolImplementations.
Document Q&A synthesis does not accept tool implementations.
maxUserTurns requires userModelSpec.
A job that attaches an interactive tool implementation must set userModelSpec.
When tool implementations are attached, the synthesis model must support tool calling.
guidedDecoding is not supported for synthesis.

Resources

Recipe configs

Agent schemas

Recipe examples

SYNTHESIS RECIPE SCHEMA

OVERVIEW

REQUEST

RECIPECONFIG

MODELIDENTIFIER

INFERENCECONFIG

SYNTHESISCONFIG

GENERAL

DOCUMENT Q&A

IMPROVED SAMPLES

AGENTICINFERENCECONFIG

DATASETDISTRIBUTION

DOCUMENT Q&A EXAMPLE

VALIDATION RULES

​OVERVIEW

​REQUEST

​RECIPECONFIG

​MODELIDENTIFIER

​INFERENCECONFIG

​SYNTHESISCONFIG

​GENERAL

​DOCUMENT Q&A

​IMPROVED SAMPLES

​AGENTICINFERENCECONFIG

​DATASETDISTRIBUTION

​DOCUMENT Q&A EXAMPLE

​VALIDATION RULES

OVERVIEW

REQUEST

RECIPECONFIG

MODELIDENTIFIER

INFERENCECONFIG

SYNTHESISCONFIG

GENERAL

DOCUMENT Q&A

IMPROVED SAMPLES

AGENTICINFERENCECONFIG

DATASETDISTRIBUTION

DOCUMENT Q&A EXAMPLE

VALIDATION RULES