Skip to content
AvraAvra
Esc
↑↓navigate↵open⌘Jpreview
On this page

Model versioning

How models are versioned, evaluated, and promoted, with aliases you control from the dashboard.

Every model available to your organization — an RFM model for one of your targets, a GFM model, or a downstream model trained on GFM embeddings — has its own version history. You decide which version serves your traffic.

The workflow has two halves. Avra releases each new version as a governed release, evaluated before it’s offered to you. Then you decide what to do with it: run it beside the version in production, point the production alias at it when it has earned that, and point the alias back if something regresses. Your code doesn’t change at any step, because it calls the alias.

1. Todayversion 2version 3version 4productionchallengerproduction servesversion 32. Promoteversion 2version 3version 4productionremove challenger, thenreassign production3. Roll backversion 2version 3version 4productionreassign productionback to version 3
An alias moves; the versions stay. Promoting reassigns production to another version, and rolling back reassigns it again. A version holds at most one alias, so challenger comes off version 4 first.

Models and versions

Each model is identified by a model_id. Each version has a unique, immutable version_id, and only active versions can serve predictions. Several versions of a model can be active at once, so you can run a challenger beside the version serving production or test a new version without disrupting production. You can also serve different versions to different segments or workflows, and roll back at once when something regresses.

GET /v1/api/models/{model_id}/versions lists a model’s versions. Each one has its model_version_id, a version number, is_active, the date it was trained as trained_at, and its alias when it holds one.

Aliases

An alias is a name that points at one version of a model, such as production or challenger. Calls that use an alias go to whichever version holds it.

You choose the names. Common ones are production, challenger, and baseline, but none is built in. An alias points at a single version, and a version carries at most one alias. A model’s aliases apply to every workspace in your organization.

Alias names are lowercase. Avra turns spaces and underscores into hyphens, removes accents, and drops any other character that isn’t a letter, a digit, or a hyphen, so Champion 2 becomes champion-2. In the path of a call, Avra reads a UUID as a version ID and anything else as an alias.

The life of a version

A version is either active or inactive, and it can hold an alias in either state. Only an active version serves live calls. You assign and remove aliases from the dashboard.

State Calls by version_id Calls by alias
Active Served No alias to call
Active, holds an alias Served Served
Inactive 400 model version is not active No alias to call
Inactive, holds an alias 400 model version is not active 400 model version is not active

An archived version is retired: it’s inactive and takes no new batches. When a model is archived, so are its versions.

An alias doesn’t move when its version becomes inactive. Calls through that alias fail until you reassign it to an active version.

Pin a version or follow an alias

Follow an alias, such as production, to pick up promotions without changing code: POST /v1/api/prediction/{model_id}/production calls whichever version holds it. Pin an exact version when you need determinism, such as for backtests, audit replays, or staged rollouts: POST /v1/api/prediction/{model_id}/{version_id} always reaches the same immutable version.

The prediction response doesn’t name the version that answered. To know exactly which version produced each result, read the version an alias points at, store its model_version_id, and call that ID:

MODEL_ID="<model_id>"

# Follow the alias: reaches whichever version holds production at the time.
curl -X POST "https://api.avra.ai/v1/api/prediction/$MODEL_ID/production" \
  -H "Authorization: Bearer $AVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cnpj": "12345678000199"}'

# Pin: resolve the alias once, then call the exact version.
VERSION_ID=$(curl -s "https://api.avra.ai/v1/api/models/$MODEL_ID/versions/production" \
  -H "Authorization: Bearer $AVRA_API_KEY" | jq -r '.model_version_id')

curl -X POST "https://api.avra.ai/v1/api/prediction/$MODEL_ID/$VERSION_ID" \
  -H "Authorization: Bearer $AVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cnpj": "12345678000199"}'
import os

import requests

API = "https://api.avra.ai"
MODEL_ID = "<model_id>"
headers = {"Authorization": f"Bearer {os.environ['AVRA_API_KEY']}"}
inputs = {"cnpj": "12345678000199"}

# Follow the alias: reaches whichever version holds production at the time.
following = requests.post(
    f"{API}/v1/api/prediction/{MODEL_ID}/production", headers=headers, json=inputs, timeout=35
)
following.raise_for_status()

# Pin: resolve the alias once, store the version ID, then call it.
version = requests.get(
    f"{API}/v1/api/models/{MODEL_ID}/versions/production", headers=headers, timeout=30
)
version.raise_for_status()
version_id = version.json()["model_version_id"]

pinned = requests.post(
    f"{API}/v1/api/prediction/{MODEL_ID}/{version_id}", headers=headers, json=inputs, timeout=35
)
pinned.raise_for_status()
print(version_id, pinned.json()["result"])
const API = "https://api.avra.ai";
const MODEL_ID = "<model_id>";
const headers = {
  Authorization: `Bearer ${process.env.AVRA_API_KEY}`,
  "Content-Type": "application/json",
};
const body = JSON.stringify({ cnpj: "12345678000199" });

// Follow the alias: reaches whichever version holds production at the time.
const following = await fetch(`${API}/v1/api/prediction/${MODEL_ID}/production`, {
  method: "POST",
  headers,
  body,
});
if (!following.ok) throw new Error(`${following.status} ${await following.text()}`);

// Pin: resolve the alias once, store the version ID, then call it.
const version = await fetch(`${API}/v1/api/models/${MODEL_ID}/versions/production`, { headers });
if (!version.ok) throw new Error(`${version.status} ${await version.text()}`);
const { model_version_id: versionId } = await version.json();

const pinned = await fetch(`${API}/v1/api/prediction/${MODEL_ID}/${versionId}`, {
  method: "POST",
  headers,
  body,
});
if (!pinned.ok) throw new Error(`${pinned.status} ${await pinned.text()}`);
console.log(versionId, (await pinned.json()).result);

Batches take the same choice. Send alias or model_version_id to POST /v2/api/batches. If you send both, they must point at the same version, or the request fails with 409. A batch keeps the version it resolved when you created it, so moving an alias doesn’t change a batch that’s already running. See Batch inference.

Promote and roll back

Aliases are managed in the dashboard. Open a model under Models to see its versions and which ones are active, and reassign an alias, such as production, to another active version. Managing aliases needs the matching permission. See Roles & permissions. A reassignment takes effect on the next call, with no code change or deployment on your side.

Check that the new version is active

On the model’s page, an active version shows Live & Batch. Calls by its version_id reach it, while the alias still points at the version in production.

Free it from any other alias

A version carries at most one alias. If the new version holds one, such as challenger, remove that alias first.

Reassign production

In the version’s ⋯ menu, select Manage aliases and enter production. The alias is already in use, so turn on Reassign existing alias and save. The next call to production reaches the new version.

Watch the new version

While the previous version is active, a rollback is one reassignment away.

Roll back by reassigning the alias to the previous version, the same way. This works while the previous version is active, because an alias on an inactive version can’t serve calls.

Events

Version changes send model-version-* events to your webhooks:

Event Sent when
model-version-promotion An alias is assigned to a version, including a reassignment
model-version-demotion An alias is removed from a version
model-version-activation A version is activated
model-version-deactivation A version is deactivated

A reassignment sends one model-version-promotion, for the version that receives the alias, and no demotion for the version that loses it. Subscribe to model-version-promotion to know when to refresh what you store, such as embeddings.

Every version is governed

A version reaches your organization only as a governed release: authorized by Avra’s research team and approved by someone who didn’t train it.

You choose when, and whether, to promote it. See Evaluation.

When versions change what you store

Embeddings and scores from different versions aren’t interchangeable. When you move to a new version of an embedding model, embed again and retrain the models built on those embeddings. When you move to a new version of a scoring model, revalidate the thresholds and risk bands that depend on it. See the embeddings technical guide.

Where to go next

Was this page helpful?