Model structure
Upload a model's layers and weights, read them back, replay a prediction through them and see what every layer computes.
The architecture of a model: its layers, weights and biases as a kaimei.structure.v1 document, the scene the dashboard draws, a replay of one prediction through the graph, and what every layer computed for an input. The Python client builds the spec from a fitted estimator; these endpoints are what it calls, and what you call to write a converter of your own.
Executable families (networks of supported layers, trees and tree ensembles of any size, and models made of those) are run by the API for explanations, predictions and analyses. Anything else is drawable but needs a remote inference URL to be queried.
#The structure spec
A spec is a JSON object with format: "kaimei.structure.v1", a family and the layers or nodes. Tensors are nested lists, or references: {"$tensor": "key"} for a binary tensor uploaded separately, {"$b64": …} for an inline float32 buffer, or {"$shape": [...], "stats": {...}} for a tensor described without its values (drawable, not executable).
| family | Content | Executable |
|---|---|---|
network | layers: an ordered list. Each layer has an id, a type, its tensors and optional inputs naming the layers it reads (defaults to the previous one). Dense weights are (out, in): y = W x + b. A dotted path groups layers into blocks. | Yes, unless approximate |
tree | nodes: {id, feature, threshold, left, right} for splits, {id, leaf: true, output} for leaves (a class distribution or a value); root names the first node. Up to 8,000 nodes. | Yes |
ensemble | trees: a list of tree specs, averaged. Or, at any size, forest: flat arrays roots, feature, threshold, left, right, value and optional missing_left, each inline or as a binary tensor, with children after their parents, plus combine: method (mean, sum or median), weights, tree_class, base, scale and link (identity, sigmoid, softmax or exp). | Yes |
composite | members: full specs, plus combine with an op: mean, vote, ovr, calibrated, stack or target. The scene draws the first member; a prediction uses all of them. | When every member is |
ensemble_summary | importances per feature, for an ensemble Kaimei can't run itself. | No |
Two shorthands are accepted and normalised to a network: format: "linear" (weight, bias, feature_names, optional activation) and format: "mlp" (a list of dense layers).
| Layer type | Fields |
|---|---|
input | names (feature names) or shape [h, w, c] for an image input |
dense / linear | units, weight (out, in), bias, optional activation |
conv2d | weight (out, in/groups, kh, kw), bias, stride, padding (same, valid or explicit), dilation, groups, optional activation |
maxpool / avgpool | size, stride, padding, ceil_mode, count_include_pad |
adaptive_avgpool / adaptive_maxpool / global_avgpool / global_maxpool | output_size for adaptive pools |
batchnorm | gamma, beta, mean, var, eps |
normalize / rescaling | per-channel scale, offset, or mean and std |
standardize | center, scale per feature (a folded StandardScaler) |
layernorm | gamma, beta, eps |
embedding | weight (vocab, dim) |
activation | activation: relu, relu6, leaky_relu, elu, gelu, silu, hardswish, hardsigmoid, sigmoid, tanh, softmax; alpha for leaky_relu and elu |
add / concat / multiply | inputs: the layers to combine (residual add, channel concat, broadcasting multiply for squeeze-excitation) |
flatten | optional order: "chw" for PyTorch heads |
pad2d | padding per side |
dropout | no-op at inference; kept so the drawing matches the code |
opaque | a step Kaimei draws but does not run: op (the framework's own name), attrs (plain JSON), shape (the output without its batch axis, any rank; [h, w, c] for pictures), optional params ({name: tensor}, counted and served like any other tensor), reason, and inputs ([] for a constant). Any opaque step makes the whole model drawn, not run. |
Top-level fields: feature_names, task, labels or outputs, framework, name, summary, architecture, approximate: true when a layer was passed through unmodelled, and metadata: a plain JSON object (up to 8 KB) saying where the spec came from, kept on the document as sent. kaimei.extract_structure(estimator) in the Python client produces this document from scikit-learn, Keras and PyTorch objects, fills metadata with the model's class, the framework and its version, the Python and client versions and the time (add your own with metadata=), and turns operations it cannot replay into opaque steps, or raises unsupported_layers with on_unsupported="error". The compiled document's stats.opaque counts them.
{
"format": "kaimei.structure.v1",
"family": "network",
"framework": "sklearn",
"task": "binary_classification",
"feature_names": [
"tenure_months", "monthly_spend", "support_tickets"
],
"labels": ["stay", "churn"],
"layers": [
{
"id": "input",
"type": "input",
"names": [
"tenure_months", "monthly_spend", "support_tickets"
]
},
{
"id": "standardize",
"type": "standardize",
"center": [24.0, 62.0, 1.2],
"scale": [18.0, 30.0, 1.6]
},
{
"id": "hidden",
"type": "dense",
"units": 4,
"activation": "relu",
"weight": [
[0.8, -0.3, 0.5],
[-0.6, 0.9, 0.2],
[0.1, 0.4, -0.7],
[0.3, -0.2, 0.9]
],
"bias": [0.1, -0.2, 0.05, 0.0]
},
{
"id": "output",
"type": "dense",
"units": 1,
"activation": "sigmoid",
"weight": [[-1.2, 0.9, 0.7, 1.1]],
"bias": [-0.3]
}
]
}{
"format": "kaimei.structure.v1",
"family": "network",
"framework": "pytorch",
"task": "multiclass_classification",
"layers": [
{
"id": "input",
"type": "input",
"shape": [224, 224, 3]
},
{
"id": "normalize",
"type": "normalize",
"mean": [0.485, 0.456, 0.406],
"std": [0.229, 0.224, 0.225]
},
{
"id": "features.0.conv",
"path": "features.0",
"type": "conv2d",
"stride": 2,
"padding": "same",
"activation": "relu6",
"weight": {"$tensor": "features.0.conv.weight"},
"bias": {"$tensor": "features.0.conv.bias"}
},
{
"id": "features.1.dw",
"path": "features.1",
"type": "conv2d",
"groups": 32,
"padding": "same",
"weight": {"$tensor": "features.1.dw.weight"}
},
…,
{"id": "pool", "type": "global_avgpool"},
{
"id": "classifier",
"type": "dense",
"units": 1000,
"activation": "softmax",
"weight": {"$tensor": "classifier.weight"},
"bias": {"$tensor": "classifier.bias"}
}
]
}#Retrieve the structure document
/v1/models/{model}/structureAPI key or sessionThe architecture document the dashboard renders: stats and the rendering scale (tier, whether the browser can replay the forward pass), layers grouped from the spec, the blocks tree implied by node paths, a colour legend, the output head, the 3-D scene (nodes with position, kind, formula, inputs and args; edges; camera), the parameters with their stored dtype (f16, f32 or f64), statistics, previews and, when small enough, values, and the spec's metadata.
Models with an uploaded structure return it; built-in models return the reference architecture. Any other model gets a schematic: its inputs and output only, with architecture, fidelity and source set to schematic, schematic and derived, and a summary inviting a structure upload.
verification says what the numbers rest on: verified (a library check, or a reader that runs one), unchecked (stored with no check; it still runs), reupload (a client before 0.7.2 may have saved one tree of a forest as the whole model), drawn, builtin or schematic.
Path parameters
Model id or slug.
Query parameters
Inline parameter values when they are small enough.
Values per tensor to inline, 0 to 200,000.
Which member of a forest the scene draws.
Only this block of the model (a node path).
Block levels below root to include, 0 to 64.
full or summary; summary omits tensor previews.Returns
model.structure document.doc = client.models.structure("churn-net-docs", detail="summary")
print(doc.architecture, doc.fidelity, doc.runnable, doc.scale["tier"])
for layer in doc.layers:
print(layer["label"], layer["units"], layer["parameters"], layer["kinds"])
block = client.models.structure("encoder", root="encoder.layers.17", depth=2)curl https://api.kaimei.ai/v1/models/churn-net-docs/structure?detail=summary \
-H "Authorization: Bearer $KAIMEI_API_KEY"{
"object": "model.structure",
"version": 2,
"model_id": "mdl_ec2f5d3a8098280a8964",
"name": "Churn net (docs)",
"framework": "sklearn",
"task": "binary_classification",
"architecture": "network",
"fidelity": "exact",
"source": "upload",
"summary": "Uploaded architecture. Every dense weight and bias below is the tensor used to compute the prediction.",
"runnable": true,
"focus_node": "output",
"stats": {
"nodes": 11,
"scene_nodes": 13,
"edges": 12,
"parameters": 27,
"tensors": 10,
"layers": 4,
"depth": 6,
"blocks": 0,
"trees": 0
},
"scale": {
"tier": "small",
"parameters": 27,
"nodes": 11,
"tensors": 10,
"blocks": 0,
"browser_replay": true,
"weights_available": true,
"previews": false,
"collapse": false,
"truncated": false,
"root": "",
"depth": null
},
"layers": [
{
"id": "inputs",
"label": "Inputs",
"node_ids": [
"tenure_months", "monthly_spend", "support_tickets"
],
"block": "",
"units": 1,
"parameters": 0,
"position": 0,
"kinds": ["input"],
"repeat": null
},
{
"id": "hidden",
"label": "hidden",
"node_ids": ["hidden", "hidden__relu"],
"block": "",
"units": 4,
"parameters": 16,
"position": 6,
"kinds": ["activation", "linear"],
"repeat": null
},
…
],
"blocks": [],
"legend": [
{"kind": "input", "label": "Input", "color": "#3ec8ff"},
{
"kind": "linear",
"label": "Linear layer",
"color": "#8aa4ff"
},
{
"kind": "activation",
"label": "Activation",
"color": "#ff6bb5"
},
…
],
"head": {
"kind": "binary_classification",
"labels": ["stay", "churn"],
"positive_label": "churn",
"positive_index": 1,
"threshold": 0.5,
"vector_node": "probabilities",
"explanation_node": "output"
},
"scene": {
"nodes": [
{
"id": "hidden",
"kind": "linear",
"op": "dense",
"mesh": "slab",
"label": "hidden",
"formula": "W x + b",
"stage": 2.0,
"position": [6.1, 0.0, 0.0],
"units": 4,
"parameter_ids": ["hidden.weight", "hidden.bias"],
"executable": true,
"activation": "relu",
"inputs": [
"standardize__tenure_months",
"standardize__monthly_spend",
"standardize__support_tickets"
],
"args": {}
},
…
],
"edges": [
{
"id": "tenure_months>standardize__tenure_months",
"source": "tenure_months",
"target": "standardize__tenure_months",
"kind": "data"
},
…
],
"camera": {
"position": [9.02, 3.42, 20.28],
"target": [7.78, 0.0, 0.0]
}
},
"parameters": [
{
"id": "hidden.weight",
"node_id": "hidden",
"name": "weight",
"role": "weight",
"label": "hidden weight",
"learned": true,
"shape": [4, 3],
"numel": 12,
"stats": {
"min": -0.7,
"max": 0.9,
"mean": 0.191667,
"std": 0.528297,
"l2": 1.946792,
"abs_mean": 0.491667,
"sparsity": 0.0,
"numel": 12
},
"values_included": true,
"available": true,
"values": [0.8, -0.3, 0.5, …]
},
…
]
}#Upload a structure
/v1/models/{model}/structureAPI key or sessionStore a kaimei.structure.v1 spec on a registered model, replacing any previous one. The spec is compiled and validated; an unusable spec returns 400 with the code and param that failed (invalid_structure, unsupported_layers, tensor_missing).
A spec can hold check: rows and your library's answers to them. The API scores them with the engine that will run the model, and if they don't match, the model is drawn but not run. The rows aren't stored. A model too large for the server to hold in memory is also drawn but not run, and running it returns model_too_large_to_run.
Tensors referenced as {"$tensor": key} must already be uploaded with PUT …/structure/tensors/{key}. The Python client's upload_structure does both from a fitted estimator.
Path parameters
Model id or slug.
Body parameters
The spec itself. See the structure spec.
Returns
spec = {
"format": "kaimei.structure.v1", "family": "network", "task": "binary_classification",
"feature_names": ["tenure_months", "monthly_spend", "support_tickets"], "labels": ["stay", "churn"],
"layers": [
{"id": "input", "type": "input", "names": ["tenure_months", "monthly_spend", "support_tickets"]},
{"id": "standardize", "type": "standardize", "center": [24.0, 62.0, 1.2], "scale": [18.0, 30.0, 1.6]},
{"id": "hidden", "type": "dense", "units": 4, "activation": "relu", "weight": W1.tolist(), "bias": b1.tolist()},
{"id": "output", "type": "dense", "units": 1, "activation": "sigmoid", "weight": W2.tolist(), "bias": b2.tolist()},
],
}
client.models.upload_structure("churn-net-docs", spec)
# or straight from the estimator (extracts, uploads large tensors as binary, then PUTs the spec)
client.models.upload_structure("churn-net-docs", clf)curl -X PUT https://api.kaimei.ai/v1/models/churn-net-docs/structure \
-H "Authorization: Bearer $KAIMEI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"format": "kaimei.structure.v1", "family": "network", "task": "binary_classification",
"feature_names": ["tenure_months", "monthly_spend", "support_tickets"], "labels": ["stay", "churn"],
"layers": [
{"id": "input", "type": "input", "names": ["tenure_months", "monthly_spend", "support_tickets"]},
{"id": "hidden", "type": "dense", "units": 4, "activation": "relu", "weight": {"$tensor": "hidden.weight"}, "bias": [0.1, -0.2, 0.05, 0.0]},
{"id": "output", "type": "dense", "units": 1, "activation": "sigmoid", "weight": [[-1.2, 0.9, 0.7, 1.1]], "bias": [-0.3]}
]
}'{
"object": "model.structure",
"model_id": "mdl_ec2f5d3a8098280a8964",
"architecture": "network",
"fidelity": "exact",
"runnable": true,
"stats": {
"nodes": 11,
"parameters": 27,
"tensors": 10,
"layers": 4
},
…: …
}#Remove a structure
/v1/models/{model}/structureAPI key or sessionDelete the uploaded spec and its binary tensors. The model stays registered; it is no longer executable unless it has a remote or built-in inference.
Path parameters
Model id or slug.
Returns
object: "model.structure".client.models.delete_structure("churn-net-docs")curl -X DELETE https://api.kaimei.ai/v1/models/churn-net-docs/structure \
-H "Authorization: Bearer $KAIMEI_API_KEY"{
"id": "mdl_ec2f5d3a8098280a8964",
"object": "model.structure",
"deleted": true
}#Trace one prediction
/v1/models/{model}/structure/traceAPI key or sessionReplay one input through the architecture and narrate it: the output, the drivers of the final score (which incoming node moved it, and by how much), a narrative sentence per node, and a frame per node with its activation vector, a summary (size, max, mean, L2, active units, argmax), an intensity in [0, 1] for colouring and, for linear layers, the contributions of each input node and the bias. For a forest, tree picks the tree to walk; a trace still averages every tree for the output.
For large models pass detail: "summary" and nodes: frames then carry statistics and a sampled vector for the chosen nodes only; the output head is always included.
Path parameters
Model id or slug.
Body parameters
A feature row.
full or summary.Node ids to return frames for (up to 2,000). Default: every node.
Member of a forest to walk.
Returns
model.structure.trace.trace = client.models.trace_structure("churn-net-docs",
input={"tenure_months": 3, "monthly_spend": 91.5, "support_tickets": 4})
print(trace.output) # {'label': 'churn', 'probability': 0.9163, ...}
for line in trace.narrative:
print(line["text"])
# tenure months enters as 3.0.
# tenure months: (3 − 24) / 18 = -1.167.
# hidden = -0.2533. relu: relu(-0.2533) = 0. ...curl -X POST https://api.kaimei.ai/v1/models/churn-net-docs/structure/trace \
-H "Authorization: Bearer $KAIMEI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input": {"tenure_months": 3, "monthly_spend": 91.5, "support_tickets": 4}}'{
"object": "model.structure.trace",
"model_id": "mdl_ec2f5d3a8098280a8964",
"runnable": true,
"detail": "full",
"output": {
"label": "churn",
"probability": 0.91626639,
"probabilities": {"stay": 0.08373361, "churn": 0.91626639},
"value": 0.91626639,
"threshold": 0.5
},
"drivers": [
{
"from": "hidden__relu",
"label": "relu",
"input": [0.0, 1.735, 0.0, 1.0283],
"delta": 2.6927,
"share": 0.8998
},
{
"from": "bias",
"label": "Bias",
"input": -0.3,
"delta": -0.3,
"share": 0.1002
}
],
"narrative": [
{
"node_id": "tenure_months",
"label": "tenure months",
"text": "tenure months enters as 3.0."
},
{
"node_id": "standardize__tenure_months",
"label": "tenure months",
"text": "tenure months: (3 − 24) / 18 = -1.167."
},
…
],
"frames": [
{
"index": 6,
"node_id": "hidden",
"op": "dense",
"label": "hidden",
"intensity": 0.5611,
"value": [-0.2533, 1.735, -0.8983, 1.0283],
"summary": {
"size": 4,
"max_abs": 1.735,
"mean_abs": 0.97875,
"l2": 2.2224,
"active": 4,
"argmax": 1
},
"text": "hidden = -0.2533.",
"contributions": [
{
"from": "standardize__tenure_months",
"input": -1.1667,
"delta": [-0.9333, 0.7, -0.1167, -0.35],
"label": "tenure months"
},
…,
{
"from": "bias",
"input": [0.1, -0.2, 0.05, 0.0],
"delta": [0.1, -0.2, 0.05, 0.0],
"label": "Bias"
}
]
},
…
],
"path": [
"tenure_months", "monthly_spend", "support_tickets",
"standardize__tenure_months", …, "output__sigmoid"
]
}#Silence a stage
/v1/models/{model}/structure/responsibilityAPI key or sessionRun one input, then set each named stage to zero and report how far the output moves. Omitted nodes means one probe per layer, up to 24. Each probe carries node_id, delta, share, flipped and the output after that stage was silenced. Probes are ordered by delta, largest first.
Path parameters
Model id or slug.
Body parameters
A feature row.
Stage ids to silence, up to 24. Default: one per layer.
Member of a forest. Ignored for other families.
Returns
model.structure.responsibility record: baseline and probes.curl -X POST https://api.kaimei.ai/v1/models/churn-net-docs/structure/responsibility \
-H "Authorization: Bearer $KAIMEI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input": {"tenure_months": 3, "monthly_spend": 91.5, "support_tickets": 4}}'{
"object": "model.structure.responsibility",
"baseline": {"label": "churn", "probability": 0.9163},
"probes": [
{
"node_id": "hidden",
"label": "hidden",
"op": "dense",
"delta": 0.41,
"share": 0.62,
"flipped": false,
"output": {"label": "churn"}
},
…
]
}#How a forest voted
/v1/models/{model}/structure/votesAPI key or sessionEvery tree's leaf for one input: its value, label, weight and the features on the path, plus whether the forest agrees. A large forest returns a sample of ballots (ballots_truncated) and, for a score, bins instead of every number.
Path parameters
Model id or slug.
Body parameters
A feature row.
Which tree the scene draws. The votes are still every tree's.
Returns
model.structure.votes record: output, agreement, trees, features and ballots.curl -X POST https://api.kaimei.ai/v1/models/churn-net-docs/structure/votes \
-H "Authorization: Bearer $KAIMEI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input": {"tenure_months": 3, "monthly_spend": 91.5, "support_tickets": 4}}'{
"object": "model.structure.votes",
"trees": 100,
"agreement": 0.91,
"output": {"label": "churn"},
"features": [
{"feature": "tenure_months", "trees": 40, "share": 0.4}
],
"ballots": [
{
"index": 0,
"weight": 1.0,
"value": [0.12],
"label": "churn",
"features": ["tenure_months"]
}
],
"ballots_truncated": true
}#What every layer computes
/v1/models/{model}/structure/activationsAPI key or sessionRun one input through an uploaded network and return what each layer computed, the data behind the dashboard's Sight view. Every stage reports its intensity, active_fraction and top_units (strongest channels or units). The detailed stages (nodes, or by default up to 24 feature maps plus the output) add the Σ|a| energy of every channel, the maps of the channels strongest ones, a saliency map (mean |a| over channels) and, for vectors up to 4,096 units, every value.
Maps are area-averaged until their long side is at most max_side cells and travel as base64 uint8 with their value range; kaimei.activations.decode restores them. cam adds class attention (Grad-CAM) toward target at the named layers when it fits a time budget estimated from the forward pass; otherwise the stage says why.
Path parameters
Model id or slug.
Body parameters
A feature row (an image for a CNN).
Stages to detail, up to 64. Default: the API picks the feature maps worth seeing plus the output.
Strongest channel maps per detailed spatial stage, 1 to 32.
Longest side of a shipped map, 4 to 112 cells.
Strongest units or channels listed for every stage, 1 to 256.
Up to 4 layer ids to compute class attention for.
Class index or label the attention explains. Default: the predicted class.
Returns
model.structure.activations record: output, target, stages, the ids of the detailed stages and forward_ms.A spatial stage of a CNN adds shape [h, w, c], energy per channel, maps (the strongest channels, each {channel, range, data}), a saliency map and, when requested, cam with the attention map or a skipped reason. Forests have no activations.
result = client.models.activations("cats-dogs-photos", input={"photo": photo}, channels=8)
print(result.output["label"], result.forward_ms)
for stage in result.stages:
if stage["detailed"]:
print(stage["node_id"], stage["op"], stage["intensity"], stage["top_units"][:3])
focused = client.models.activations("cats-dogs-photos", input={"photo": photo},
nodes=["features.17"], cam=["features.17"], target="dog")curl -X POST https://api.kaimei.ai/v1/models/churn-net-docs/structure/activations \
-H "Authorization: Bearer $KAIMEI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input": {"tenure_months": 3, "monthly_spend": 91.5, "support_tickets": 4}, "units": 4}'{
"object": "model.structure.activations",
"model_id": "mdl_ec2f5d3a8098280a8964",
"runnable": true,
"output": {
"label": "churn",
"probability": 0.91626639,
"probabilities": {"stay": 0.08373361, "churn": 0.91626639},
"value": 0.91626639,
"threshold": 0.5
},
"target": {"index": 1, "label": "churn"},
"input": null,
"stages": [
{
"index": 0,
"node_id": "tenure_months",
"label": "tenure months",
"op": "input",
"kind": "input",
"units": 1,
"intensity": 0.6351,
"summary": {
"size": 1,
"max_abs": 3.0,
"mean_abs": 3.0,
"l2": 3.0,
"active": 1,
"argmax": 0
},
"active_fraction": 1.0,
"detailed": false,
"top_units": [
{"index": 0, "value": 3.0}
]
},
…,
{
"index": 6,
"node_id": "hidden",
"label": "hidden",
"op": "dense",
"kind": "linear",
"units": 4,
"intensity": 0.5611,
"summary": {
"size": 4,
"max_abs": 1.735,
"mean_abs": 0.97875,
"l2": 2.2224,
"active": 4,
"argmax": 1
},
"active_fraction": 1.0,
"detailed": true,
"top_units": [
{"index": 1, "value": 1.735},
{"index": 3, "value": 1.028333},
{"index": 2, "value": -0.898333},
{"index": 0, "value": -0.253333}
],
"values": {
"shape": [4],
"range": [-0.898333, 1.735],
"encoding": "u8",
"data": "PwD/Qw=="
}
},
…
],
"detailed": [
"standardize__tenure_months", "standardize__monthly_spend",
"standardize__support_tickets", "hidden", …
],
"channels": 8,
"max_side": 56,
"forward_ms": 0.47
}#List binary tensors
/v1/models/{model}/structure/tensorsAPI key or sessionThe binary tensors uploaded for this model with their shapes, sizes, statistics and whether the current spec referenced them.
Path parameters
Model id or slug.
Returns
total_bytes.tensors = client.models.tensors("churn-net-docs")
print(tensors.total_bytes)
for item in tensors.data:
print(item["key"], item["shape"], item["dtype"], item["bytes"], item["referenced"])curl https://api.kaimei.ai/v1/models/churn-net-docs/structure/tensors \
-H "Authorization: Bearer $KAIMEI_API_KEY"{
"object": "list",
"data": [
{
"object": "model.structure.tensor",
"model_id": "mdl_ec2f5d3a8098280a8964",
"key": "hidden.weight",
"shape": [4, 3],
"dtype": "f32",
"numel": 12,
"bytes": 50,
"compression": "zlib",
"stats": {
"min": -0.7,
"max": 0.9,
"mean": 0.191667,
"std": 0.528297,
"l2": 1.946792,
"abs_mean": 0.491667,
"sparsity": 0.0,
"numel": 12,
"histogram": {
"counts": [2, 0, …],
"edges": [-0.7, -0.566667, …]
}
},
"referenced": true
}
],
"total_bytes": 50
}#Upload a binary tensor
/v1/models/{model}/structure/tensors/{key}API key or sessionUpload one weight tensor as raw little-endian bytes, zlib-compressed by default, and reference it from the spec as {"$tensor": "key"}. Keys are dotted module paths with an optional parameter name (encoder.layers.0.q.weight): letters, digits, . _ - : /, at most 200 characters.
Up to 250 million values per tensor and 512 MB compressed per upload; 20,000 uploads per hour per organization. Uploading the same key again replaces the tensor.
Path parameters
Model id or slug.
Tensor key.
Query parameters
Comma-separated dimensions, for example 768,3072.
f16, f32 or f64, little-endian.zlib or none.Body parameters
The buffer, with Content-Type: application/octet-stream.
Returns
model.structure.tensor with statistics.import numpy as np
W1 = np.array([[0.8, -0.3, 0.5], [-0.6, 0.9, 0.2], [0.1, 0.4, -0.7], [0.3, -0.2, 0.9]], dtype=np.float32)
client.models.upload_tensors("churn-net-docs", {"hidden.weight": W1})
# then PUT a spec that says "weight": {"$tensor": "hidden.weight"}python -c "import numpy as np, zlib, sys; sys.stdout.buffer.write(zlib.compress(np.load('w1.npy').astype('<f4').tobytes()))" > w1.z
curl -X PUT "https://api.kaimei.ai/v1/models/churn-net-docs/structure/tensors/hidden.weight?shape=4,3&dtype=f32&compression=zlib" \
-H "Authorization: Bearer $KAIMEI_API_KEY" \
-H "Content-Type: application/octet-stream" \
--data-binary @w1.z{
"object": "model.structure.tensor",
"model_id": "mdl_ec2f5d3a8098280a8964",
"key": "hidden.weight",
"shape": [4, 3],
"dtype": "f32",
"numel": 12,
"bytes": 50,
"compression": "zlib",
"stats": {
"min": -0.7,
"max": 0.9,
"mean": 0.191667,
"std": 0.528297,
"l2": 1.946792,
"abs_mean": 0.491667,
"sparsity": 0.0,
"numel": 12
},
"referenced": null
}#Delete a tensor
/v1/models/{model}/structure/tensors/{key}API key or sessionRemove one uploaded tensor. A spec that still references it becomes unusable until the tensor is re-uploaded.
Path parameters
Model id or slug.
Tensor key.
Returns
{model_id}:{key}.client.models.delete_tensor("churn-net-docs", "hidden.weight")curl -X DELETE https://api.kaimei.ai/v1/models/churn-net-docs/structure/tensors/hidden.weight \
-H "Authorization: Bearer $KAIMEI_API_KEY"{
"id": "mdl_ec2f5d3a8098280a8964:hidden.weight",
"object": "model.structure.tensor",
"deleted": true
}#Read a parameter
/v1/models/{model}/structure/parameters/{parameter_id}API key or sessionA window of one weight or bias tensor. Parameter ids come from the structure document (hidden.weight, standardize__tenure_months.center). JSON windows are limited to 20,000 values; format=f32 streams raw little-endian float32 bytes for windows up to 4 million values, with the geometry in X-Kaimei-* headers.
Path parameters
Model id or slug.
Parameter id from the structure document.
Query parameters
First value, in flattened row-major order.
Values to return. At most 20,000 for JSON, 4,000,000 for f32.
json or f32.Include summary statistics (JSON only).
Side of a downsampled 2-D preview to include, 0 to 256 (JSON only).
Member of a forest.
Returns
model.structure.parameter, or application/octet-stream with headers X-Kaimei-Offset, X-Kaimei-Count, X-Kaimei-Total, X-Kaimei-Shape, X-Kaimei-Dtype and X-Kaimei-Available.window = client.models.structure_parameter("churn-net-docs", "hidden.weight", limit=6, stats=True)
print(window.shape, window.total, window.values) # [4, 3] 12 [0.8, -0.3, 0.5, -0.6, 0.9, 0.2]
# the whole tensor as float32, fetched as binary
weights = client.models.structure_parameter_values("churn-net-docs", "hidden.weight")
weights.reshape(window.shape)curl "https://api.kaimei.ai/v1/models/churn-net-docs/structure/parameters/hidden.weight?limit=6&stats=true" \
-H "Authorization: Bearer $KAIMEI_API_KEY"
# raw float32
curl "https://api.kaimei.ai/v1/models/churn-net-docs/structure/parameters/hidden.weight?format=f32&limit=1000000" \
-H "Authorization: Bearer $KAIMEI_API_KEY" -D - --output hidden.weight.f32
# X-Kaimei-Offset: 0 X-Kaimei-Count: 12 X-Kaimei-Total: 12 X-Kaimei-Shape: 4,3 X-Kaimei-Dtype: f32{
"object": "model.structure.parameter",
"id": "hidden.weight",
"model_id": "mdl_ec2f5d3a8098280a8964",
"node_id": "hidden",
"name": "weight",
"role": "weight",
"label": "hidden weight",
"shape": [4, 3],
"offset": 0,
"count": 6,
"total": 12,
"available": true,
"values": [0.8, -0.3, 0.5, -0.6, 0.9, 0.2],
"stats": {
"min": -0.7,
"max": 0.9,
"mean": 0.191667,
"std": 0.528297,
"l2": 1.946792,
"abs_mean": 0.491667,
"sparsity": 0.0,
"numel": 12
}
}