Upload a trained model

Upload a trained model

Turn a fitted scikit-learn, Keras or PyTorch model into a registered Kaimei model with one call.

client.models.upload(estimator, name=…) reads the live estimator in your process, extracts its layers and learned weights into a kaimei.structure.v1 spec, registers the model and uploads the spec. Small tensors travel inline as JSON; anything above externalize_above values (default 65,536) streams as a zlib-compressed float32 blob referenced from the spec, so models with millions of parameters upload at about four bytes per weight. The original .h5, .pt or pickle is never sent.

Arguments

estimatorobjectrequired

A fitted scikit-learn estimator or pipeline, a Keras model, a torch.nn.Module, or a wrapper that stores one on a conventional attribute (model_, estimator_, best_estimator_, module).

namestrrequired

Display name. The slug is derived from it unless you pass slug.

feature_names / featureslistoptional

Input names, or a full feature schema. Optional when the estimator knows its names (feature_names_in_, a DataFrame).

task, outputs, frameworkoptional

Inferred from the estimator when omitted. Pass outputs={"labels": [...]} to name the classes.

X, yarray-likeoptional

Reference rows (capped at 5,000) and optional labels, uploaded after the model is created.

inferencedictoptional
{"type": "remote", "url": ...} for models Kaimei cannot execute itself.
weightsstroptionaldefault "full"
"full" or "summary", which uploads shapes only, with statistics for layers of 256 values or more: the architecture is drawable, the weights never leave your environment, and explanations need a remote URL. A tree, or a model made of other models, sends only how many trees it has and how often each feature is split on. A larger tree model sends the shapes of its arrays and its feature importances.
externalize_aboveint | Noneoptionaldefault 65536

Values per tensor above which it uploads as binary. None keeps everything inline.

progresscallableoptional
progress(stage, done, total), called while tensors upload (stage is "tensors" then "structure").
input_shapetupleoptional

Image models in PyTorch: (channels, height, width). Keras models report their own.

preprocessdictoptional
{"mean": [...], "std": [...]} baked into the graph for torchvision-style models that expect Normalize on [0, 1] pixels.
value_rangelistoptional
[0, 255] when callers send and the model reads 0 to 255 pixels (a Keras Rescaling(1/255) model, for example).
slug, version, description, tags, metadata, project_idoptional
EstimatorWhat is uploadedExecutable
sklearn linear modelsExact coef_ / intercept_Yes
sklearn MLPClassifier / MLPRegressorExact layersYes
sklearn treeFull node listYes
sklearn forest / extra trees, any sizeEvery tree: a node list when small, flat binary arrays above thatYes
sklearn Pipeline + StandardScaler, MinMaxScaler, RobustScaler, MaxAbsScalerScalers folded into any tree model's splits or inserted as a layer, then the estimatorAs the final step
Keras / TensorFlowDense, Conv2D (any stride, padding, dilation, groups), Depthwise/SeparableConv2D, BatchNormalization, pooling, Add, Multiply, Concatenate, ZeroPadding2D, Rescaling, Normalization, Flatten, Dropout, LayerNorm; functional graphs and nested modelsYes, unless a layer is unrecognised
torch.nn CNNsTraced with torch.fx: Conv2d, BatchNorm2d, pooling, residual +, torch.cat, squeeze-excitation *, Flatten and the common activations (ResNet, MobileNet, EfficientNet, DenseNet, VGG, SqueezeNet)Yes, with input_shape
torch.nn dense netsLinear, activations, Dropout, LayerNorm, Embedding, BatchNorm1d, traced with torch.fx or in forward-hook order when that failsYes, when traced and it gives the module's own outputs
sklearn gradient boosting, histogram boosting, AdaBoostEvery tree, and how they combineYes, unless a split is categorical
XGBoost (gbtree, dart), LightGBM, CatBoostEvery tree, and how they combineYes, unless a split is categorical or the reading fails its check
Bagging, voting, stacking, calibration, one-vs-restEvery member, and how they combineYes, when every member is
LinearSVC, RidgeClassifier, hard voting and others without predict_probaExact weights, marked uncalibrated in every prediction: outputs are scores, not probabilitiesYes
SVC and NuSVC with probability=True, a hard vote or one-vs-rest of them, a linear SVC with more than two classesDrawn: its labels can disagree with its probabilities, or come from votes between pairs of classesNo: register the model with inference
A subclass with its own predict or your own class, anywhere in a model, one that refuses to answer on the check's rows, PyTorch or Keras models that don't reproduce their own outputs, and GELU in its default exact form (approximate="tanh" runs)Drawn: its learned numbers don't show what it doesNo: register the model with inference
SVC with a non-linear kernel, nearest neighbours, naive Bayes, pipelines with encodersRefused with an explanationComing soon. Until then, register the model with inference
Your own classesRefused with an explanationNo: register the model with inference
ONNX, Hugging Face, LLMsFramework label onlyComing soon. Until then, register the model with inference

Every scikit-learn, XGBoost, LightGBM and CatBoost upload is scored against the estimator on rows around and exactly on its splits. A reading that doesn't reproduce it is marked approximate, so it is drawn but not run. A model with several regression outputs is also drawn but not run, because a prediction reports one number or one class. The API repeats the check when the model arrives, for PyTorch and Keras models too, with the engine that will run it. A few rows and your library's answers to them go up with the model and aren't stored; weights="summary" doesn't send them. The same check scores rows with gaps: if the library accepts them and the reading matches, the model's numeric features get allow_missing and a row can send null. Shapley methods explain such a row, and rows with a gap count in reference averages and analyses as they are. A SimpleImputer in a pipeline sets each feature's baseline to its fill value, so a null gets what the imputer would give it; one that replaces a real number, like missing_values=-999, can't be read as part of the model. PyTorch and Keras models with layers the client can score are checked against their own outputs too, and logic in forward() that the reading can't see leaves them drawn but not run. From Python, a NaN sent to a feature that can't take a gap raises ValueError, because null there means the feature's baseline.

Unknown Keras or PyTorch layers that keep their input's shape are passed through and the spec is marked approximate: it visualises but cannot be queried without a remote URL. Shape-changing operations that cannot be replayed (a channel shuffle, an upsampling decoder) raise StructureError(code="unsupported_layers") naming them. kaimei.extract_structure(estimator, …) returns the spec and tensors without uploading; client.models.upload_structure(model, estimator_or_spec) attaches weights to a model you already registered.

from kaimei import Kaimei

client = Kaimei()

# a scikit-learn model with its validation rows as the reference population
model = client.models.upload(
    clf,
    name="Churn net",
    feature_names=list(X_valid.columns),
    X=X_valid, y=y_valid,
    outputs={"labels": ["stay", "churn"]},
    tags=["lifecycle"],
)
print(model.slug, model.framework)   # churn-net sklearn

# a model Kaimei cannot run: draw it, score it through your endpoint
client.models.upload(
    xgb_model,
    name="Churn forest",
    inference={"type": "remote", "url": "https://scoring.example.com/predict"},
)

# a PyTorch CNN: give the input size, bake in the normalization
client.models.upload(
    resnet,
    name="Defect classifier",
    task="multiclass_classification",
    outputs={"labels": ["ok", "scratch", "dent"]},
    input_shape=(3, 224, 224),
    preprocess={"mean": [0.485, 0.456, 0.406], "std": [0.229, 0.224, 0.225]},
    X=sample_images,                      # (n, 3, 224, 224) or (n, 224, 224, 3)
    progress=lambda stage, done, total: print(stage, done, "/", total),
)

# weights that must stay private: shapes and statistics only
client.models.upload(net, name="Pricing net", weights="summary",
                     inference={"type": "remote", "url": "https://..."})