Deployment¶

Every supported export carries or can be paired with an inference manifest describing input schema, preprocessing expectations, objective/link semantics, outputs, build identity, and a deterministic model fingerprint.

model.export_inference_manifest("model.manifest.json")
model.save_model("model.json", model_format="json")

Save, resume, and inspect¶

JSON is the safe default for native CTBoost model persistence. Pickle supports Python convenience wrappers and resumable wrapper state, but it must be treated as trusted code/data. Training snapshots validate their saved configuration and data schema before resuming:

booster = ctboost.train(
    pool,
    {"objective": "RMSE", "learning_rate": 0.1},
    num_boost_round=200,
    snapshot_path="run_snapshot.ctb",
    resume_from_snapshot=True,
)

manifest = booster.get_inference_manifest()
booster.export_inference_manifest("model.manifest.json")

Snapshot resume is a validated warm-start convenience, not a blanket bit-for-bit equivalence promise for every training path. Use init_model when you intentionally change a later-stage configuration.

With a nonzero Pool.baseline, resumed and uninterrupted training can add floating-point updates in a different order. Small rounding differences can change later split decisions, so those runs need not produce identical models.

Starting in 0.1.60, enabling early stopping when resuming an untrimmed DART model starts selection from the full supplied ensemble if its historical best round is no longer recoverable. CTBoost evaluates that ensemble on the current validation data before adding rounds. It can then retain that checkpoint or a later improvement. DART rescales earlier trees, so taking a prefix of the supplied model would not recreate its historical best predictions. Already-trimmed DART resumes and Plain boosting keep their existing behavior. For the selected model's monitored score, use booster.eval_loss_history[booster.best_iteration]. The sklearn best_score_ dictionary continues to report each metric's historical minimum or maximum.

CPU prediction¶

Starting in 0.1.61, CTBoost caches a compact traversal representation on the first CPU prediction that uses trees. Matching scalar multiclass trees share a traversal, and root-only trees add their leaf updates directly. The cache keeps the original floating-point update order, physical tree indices, and leaf-index output. It does not change training or statistical feature selection.

The first call builds the cache for the complete ensemble, even when predicting only a prefix. This adds cold-call work and resident memory; later calls reuse it. Training, loading model state, or changing the quantization schema or learning rate invalidates the cache. The cache is derived state and is not written to model files. Saved models keep their existing format and behavior. Builds using fast-math, and GCC targets with fused multiply-add instructions, retain the previous score-accumulation path to preserve their rounding behavior.

Fitted preprocessing also avoids serializing its metadata on every prediction. Supported numeric arrays and uniform numeric frames use typed conversion. Float16 inputs and mixed numeric frames containing float32 columns retain object conversion to preserve NumPy warning, callback, and exception behavior. Categorical, text, embedding, and nullable values retain their established conversion rules.

Measure both the first prediction and repeated predictions with your actual batch sizes. Include preprocessing when comparing libraries, and report the model size and prediction quality alongside latency. See the 0.1.61 release notes for measured results and limitations.

Export choices¶

Install table-oriented CLI support with python -m pip install "ctboost[cli]". ONNX export additionally requires python -m pip install "ctboost[onnx]".

Format	Best for	Important limit
pickle	Python round-trip	Treat files as trusted code/data
JSON predictor	Python inference, including fitted preprocessing	CTBoost Python runtime; trusted artifact
generated Python	dependency-free numeric inference	prepared numeric features for fitted pipelines
generated C++ / C ABI	native embedding	model-specific generated interface
ONNX	interoperable numeric inference	prepared numeric features for fitted pipelines
R/JVM JSON scorers	portable inference	prepared numeric features only; inference-only

Scalar version-2 and vector version-3 JSON predictors can embed a fitted categorical, text, or embedding pipeline for the Python load_exported_predictor runtime. Raw-feature exports require a matching inference manifest, pipeline format 3 or 4, and categorical key encoding 2; fingerprints and the full native pipeline state are validated before construction. Treat the JSON as trusted input: its SHA-256 fingerprint detects accidental or uncoordinated changes but is not a signature or authenticity boundary.

Starting in 0.1.60, new fitted pipelines use format 4 for corrected fractional CTR smoothing. Release 0.1.59 uses format 3. Loaded format-3 pipelines retain their original smoothing and re-export as format 3. Older CTBoost runtimes that support only format 3 reject format-4 pipelines.

Generated Python/C++/ONNX predictors and the R/JVM scorers do not silently reproduce a fitted pipeline. Their manifest/profile requires prepared features. See portable inference for the cross-language boundary.

Compact multiclass vector predictors require the Python version-3 reader; the R/JVM source runtimes reject these artifacts. C++ and ONNX exports expand vector trees into scalar trees. See vector leaves for layout and compatibility details.

Classification exports preserve the fitted class-label order. Standalone Python and JSON predictors expose raw prediction; classification helpers also provide probabilities/classes where supported. A deterministic model fingerprint in the manifest binds the model state used for deployment.

CLI¶

ctboost train --input train.csv --target label --model model.ctboost
ctboost predict --model model.ctboost --input test.csv --output predictions.csv
ctboost inspect --model model.ctboost
ctboost export --model model.ctboost --format cpp --output generated_model.cpp

NumPy inputs are always loaded with pickling disabled. Output files are not overwritten unless requested. The unsafe-pickle opt-in applies to trusted model serialization, not NumPy input arrays.

The CLI accepts NPY, NPZ, CSV, TSV, Parquet, and Feather input. Prediction output additionally supports JSON. Explicit flags override values supplied by --params; expected input/model failures return a nonzero status with an actionable message. Loading or creating a pickle model requires the explicit unsafe-pickle opt-in.