Real embeddings on a static page

build note · 4 min · the demo on the main page runs exactly this way

The retrieval demo on my site had a credibility problem in its first life: it was a simulation. Plausible scores, deterministic theater, no actual math. For a page whose whole argument is evidence over adjectives, that could not stand. But the site deploys as static files — no backend, no API keys, no per-visitor inference cost. The usual fix (call an embeddings API) breaks the deployment model and, worse, means the demo dies the day a key expires.

The resolution is old-fashioned: separate the expensive computation from the cheap one, and do the expensive one once. Embedding a corpus is expensive-ish and happens rarely; comparing vectors is trivial and happens on every interaction. So: compute all embeddings offline, ship them as data, do the comparison math in the visitor's browser.

The pipeline

A 27-chunk municipal-governance corpus, embedded at three enrichment levels (raw text · heading + text · microsummary + heading + text) with three genuinely different model classes: a neural sentence encoder (Universal Sentence Encoder, 512d), averaged static word vectors (word2vec, 100d), and corpus TF-IDF as the lexical baseline. Ten ground-truth queries, embedded the same way. Everything lands in one embeddings.json — 0.64 MB, smaller than a hero image.

In the browser: cosine similarity, top-K, a real MMR implementation over pairwise chunk similarities, and a rerank stage that re-scores candidates with the strongest encoder on the richest text representation — a true two-stage retrieve-then-rerank, honestly labeled. Retrieval quality (Precision@K, Recall@K, MRR, nDCG) is computed live against the ground-truth labels, because an unmeasured pipeline is an opinion.

What the numbers showed

Two findings earn their place on the page. First, enrichment lift is real: corpus-average MRR climbs from .900 (raw text) to .950 (add the section heading) on the sentence encoder — the cheapest retrieval-quality upgrade available. Second, model class matters more than model size: the sentence encoder beats averaged word vectors by a wide margin on paraphrased queries, while TF-IDF stays surprisingly competitive on exact-vocabulary questions. The demo lets you feel all of this with a dropdown.

Costs and latency in the demo remain modeled — clearly labeled as such — because honest labeling of what is measured versus estimated is itself part of the method. The corpus is fully synthetic; every distinctive sentence was checked against the public web before shipping.