An ID for every video,
before anyone watches it.
A sentence encoder and an RQ-VAE turn a video's title into three tokens, so related videos share a prefix and a brand-new video is addressable the moment it is uploaded. A recommender built on those tokens ranks what to watch next. Both run on a Chalk scaling group deployed from one Python script.
Encode, then recommend
Type a title to see its embedding, its three tokens, and the catalog videos that share its prefix. Then pick three watched videos, from the catalog or a title you just encoded, to get the ten most likely next ones. The catalog is the public titles of MicroLens-100K.
How it works
A recommender that keys on video IDs knows nothing about a video until people watch it. Semantic IDs derive the key from the content instead, following TIGER's generative retrieval recipe: the first token is coarse and later tokens refine it.
Embed
A MiniLM sentence encoder turns the title into a 384-dimensional vector. It runs from the ONNX export in MiniLM's own Hugging Face repo at a pinned revision, so the replica never imports torch.
Quantize
An RQ-VAE compresses the vector and quantizes it in three levels of 256 codes, each level encoding what the previous ones missed. Distinct titles that share their first two tokens average 0.62 cosine similarity, against 0.13 across the corpus.
Recommend
The recommender counts which semantic-ID prefixes follow which across 100,000 MicroLens watch sequences, then adds content similarity and per-video transition counts. For held-out users it puts the next video in the top 10 of 19,738 10.7% of the time, against 1.9% for content similarity alone.
One caveat on new videos. A brand-new title takes part as history the moment it is encoded. As a candidate, it still ranks best by content similarity: most two-token prefixes hold a single video, so prefix transitions say little about a prefix nobody has watched yet.
Train it, deploy it, call it from SQL
Every step in the example is a uv script with its dependencies inline, so there is no virtualenv to manage. Embed the titles, train the quantizer, build the recommender, and run the deploy script: Chalk builds the image and prints a URL that serves this exact demo.
To use the IDs in your own pipelines, deploy the encoder as a Chalk function with src/deploy_function.py and call it from Chalk SQL, chalkdf, or a stream resolver.
chalk-ai/chalk-semantic-idsgit clone https://github.com/chalk-ai/chalk-semantic-ids
cd chalk-semantic-ids
# Or export CHALK_CLIENT_ID and CHALK_CLIENT_SECRET.
chalk login
# Download MicroLens-100K into data/ (see the README), then:
./src/embed_titles.py # MiniLM title embeddings
./src/train_rqvae.py # quantizer + semantic IDs
./src/export_numpy_runtime.py # torch-free encoder
./src/build_recommender.py # next-video tables
# Builds the image and prints your demo's URL.
./demo/deploy_demo.py --env-id <your-environment-id>What Chalk handles
The model is the interesting part. Everything around it is the part Chalk does for you.
Images from Python
Image.debian_slim().pip_install(...) builds the container with the ONNX encoder, the trained codebooks, and the recommender tables baked in. No Dockerfile, no registry to manage.
Scale to zero
Deployed with min_replicas=0, the encoder scales to zero after about 30 seconds idle. A call that wakes it takes 8.1 seconds at the median on the 443 MB ONNX image; warm calls take about 100 ms.
One name in the catalog
Chalk SQL, chalkdf, and feature resolvers all reach the deployed encoder as function.semantic-id-embed through catalog_call.
Computed at ingest
Put catalog_call in a stream resolver's output_features and each video's ID is computed once per message and stored with it, so reads never call the model.
An HTTPS URL per group
A ScalingGroup with a readiness probe gets a URL on the environment's gateway. The demo above is that URL in an iframe.
Runs in your cloud
The encoder, codebooks, and recommender run in your Chalk environment, next to your data. Titles never pass through a third-party API.
Give new items an ID on day one
Videos, products, listings, or documents. Talk to an engineer about computing semantic IDs next to your data and serving them as features.