Guides

Model bundle requirements

FlashML accepts gzipped tar archives containing one ONNX model, one preprocess.json file, and optional task-specific labels or tokenizer files.

Before you start

FlashML expects ONNX because it gives models trained in different frameworks one standardized runtime target. That portability is what makes the one-upload, one-endpoint flow possible without requiring FlashML to host separate PyTorch, TensorFlow, scikit-learn, and transformer runtime stacks for every model.

Export your trained model to ONNX first, then package the ONNX file with the preprocessing metadata and task assets FlashML needs at inference time.

PyTorch ONNX export

Use torch.onnx.export for PyTorch models and review exporter options for dynamic shapes and opsets.

Hugging Face Optimum

Use Optimum's ONNX exporter for transformer workflows and common Hugging Face model architectures.

ONNX converters

Review the official ONNX converter overview for framework-specific conversion paths and limitations.

Archive format

Filename

Use a simple name ending in .tar.gz, such as sentiment-classifier.tar.gz. Letters, numbers, dots, underscores, and hyphens are supported.

Archive shape

A top-level folder is fine. Nested folders are fine. FlashML recursively finds required files and flattens them before validation.

Required core files

Every supported bundle needs exactly one .onnx file and exactly one preprocess.json file.

Size limit

Bundles must be 500 MB or smaller. size_bytes is optional on reservation, but the actual uploaded object is checked during completion.

sentiment-classifier/
  model.onnx
  preprocess.json
  labels.txt
  tokenizer.json
  tokenizer_config.json
  special_tokens_map.json

tar -czf sentiment-classifier.tar.gz -C ./sentiment-classifier .
tar -tzf sentiment-classifier.tar.gz

Supported tasks

Modality	Tasks	Inference input	Notes
`image`	classification, object_detection	Multipart image file	Use image_classification or image_object_detection pipelines.
`text`	classification, embedding	JSON text, multipart text field, or UTF-8 text file	Text uploads are enriched with tokenizer assets during validation.

Required files

Model type	Required	Optional
Image classification	Exactly one .onnx file and one preprocess.json file.	labels.txt for human-readable class labels, and a matching .onnx.data file when the ONNX model references external data.
Image object detection	Exactly one .onnx file, one preprocess.json file, and labels.txt. labels.txt must match the model class count.	A matching .onnx.data file when the ONNX model references external data.
Text classification	Exactly one .onnx file and one preprocess.json file.	labels.txt, tokenizer files, and a matching .onnx.data file when the ONNX model references external data. If tokenizer files are omitted, preprocess.json must include a tokenizer name that FlashML can resolve.
Text embedding	Exactly one .onnx file and one preprocess.json file.	Tokenizer files and a matching .onnx.data file when the ONNX model references external data.

preprocess.json

preprocess.json tells FlashML how to convert incoming images or text into ONNXRuntime inputs. Keep these values aligned with training.

For image models, fields like resize, crop_size, mean, and std should match the transforms used before export. For text models, tokenizer, max_length, padding, and truncation should match the tokenizer and input length used during training.

{
  "resize": 256,
  "crop_size": 224,
  "normalize": true,
  "mean": [0.485, 0.456, 0.406],
  "std": [0.229, 0.224, 0.225]
}

{
  "tokenizer": "distilbert-base-uncased",
  "max_length": 128,
  "padding": "max_length",
  "truncation": true
}

Unknown or incorrectly typed fields are not accepted as a separate schema step today; they usually fail later during validation, preprocessing, or ONNXRuntime input binding. Treat validation success as confirmation that the file can be loaded, then test at least one real inference request before depending on a new bundle.

Image preprocess fields

Field	Type	Behavior
`resize`	`number \| [width, height] \| { width, height }`	Optional. Classification resizes the shortest side to this value; detection uses it as model input size if the ONNX input shape is dynamic.
`crop_size`	`number`	Optional classification center crop size after resize.
`normalize`	`boolean`	Optional. Default false. When true, applies (pixel - mean) / std after scaling pixels to 0..1.
`mean`	`number[3]`	Optional. Default [0, 0, 0]. RGB channel means used only when normalize is true.
`std`	`number[3]`	Optional. Default [1, 1, 1]. RGB channel standard deviations used only when normalize is true.
`letterbox_fill`	`number`	Optional detection fill value. Default 114.
`confidence_threshold`	`number`	Optional detection score cutoff. Default 0.25.
`iou_threshold`	`number`	Optional detection NMS IoU threshold. Default 0.45.
`max_detections`	`number`	Optional detection output cap. Default 100.
`box_format`	`xywh \| xyxy`	Optional detection format for raw model boxes. Default xywh.
`boxes_normalized`	`boolean`	Optional detection hint. If omitted, FlashML infers normalized coordinates from box values.

Text preprocess fields

Field	Type	Behavior
`tokenizer`	`string`	Required unless tokenizer files are included in the bundle. Hugging Face tokenizer name used to enrich text bundles during validation.
`max_length`	`number`	Optional. Default 128. Inputs longer than this token limit are rejected before inference.
`padding`	`string \| boolean`	Optional. Default max_length. Passed to the tokenizer.
`truncation`	`boolean`	Optional. Default true. Passed to the tokenizer.