# See what an embedding actually is

An embedding represents an item as a list of numbers. A text embedding model
learns to produce representations that can be compared for useful relationships.
If a person asks how to reset a password while a document says choose a new
password, comparing these representations can find a useful passage despite the
different wording.

This original LockedIn exercise runs a real, small embedding model on your CPU.
All passages are fictional. You need Python 3.11 or later, about 91 MB for model
assets plus space for the Python environment, and an internet connection for
installation and explicit preparation. No GPU, provider account or API key.

Keep these parts separate:

- **Tokenizer:** turns text into vocabulary IDs.
- **Embedding model / encoder:** turns the input into numeric features.
- **Vector:** the ordered list of those numbers.
- **Similarity search:** compares vectors to find candidates.
- **Generator:** would write an answer using selected evidence; this lab has none.

## 1. Prepare the local model

Download the Python exercise and its pinned requirements into a new folder.
Create an environment, then install:

```sh
python3 -m venv .venv
source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -r fde-embeddings-first-search-requirements.txt
python fde-embeddings-first-search.py prepare
python fde-embeddings-first-search.py test
```

`prepare` downloads the publisher's ONNX model and tokenizer at revision
`1110a243fdf4706b3f48f1d95db1a4f5529b4d41` and checks their SHA-256 hashes.
The files are cached in `.embedding-cache` beside your working directory. Set
`FDE_EMBEDDING_CACHE` if you need another cache location. Keep using the same
location after preparation. Model: `sentence-transformers/all-MiniLM-L6-v2`,
published under Apache-2.0. No model weights are bundled with this download.

Other commands load local files and block Python socket connections and DNS
resolution. Missing or changed model assets require explicit preparation.
The ONNX Runtime CPU provider executes the model; the browser lesson shows
recorded results from this exercise rather than running inference.

## 2. Follow a sentence into its vector

```sh
python fde-embeddings-first-search.py inspect
python fde-embeddings-first-search.py inspect --full
```

Start with the readable `text` fields. Each allowed passage and query becomes
384 numbers. `preview` contains the first 12 rounded values. `--full` also
includes complete vectors. The lab averages token representations while
excluding padding, then normalizes each sentence vector to length one.

Think of map coordinates as an analogy for representation and comparison.
The analogy stops at the axes: these are learned features, not latitude and
longitude or named properties such as trust. One dimension cannot be read as
the word password. Compare the pattern across the full vector.

Try explaining this to a teammate without saying “vector database” first.
Our collection is small enough to compare every vector directly. A database
becomes useful for storing, indexing and searching a larger collection.

## 3. Predict the ranking, then inspect the result

Before revealing the output, predict the top two passages for each case:

| Query | Observation from the pinned local reference |
| --- | --- |
| Same P1 sentence | P1: 1.0000; P4: 0.8948 |
| How do I reset my password? | P1: 0.6954; P4: 0.5891 |
| Same P4 negative instruction | P4: 1.0000; P1: 0.8948 |
| What is the weather forecast for tomorrow? | P3: 0.0048, still first in this collection |

Scores are cosine similarities computed from all 384 full-precision values.
Small floating-point differences can occur across runtimes. The displayed
first 12 numbers alone cannot reproduce the ranking.

Cosine compares vector directions and ranges from −1 to +1. For normalized
vectors, a dot product produces the same result. A score is not a percentage
probability that a sentence is true or an answer is correct.

P1 says to use the account recovery page. P4 says **not** to use it.
Their similarity is high because the language and topic are closely related,
but the instructions conflict. Read the text and resolve source authority.
The weather case has a first result without an answer. Do not drop this case
just because it is inconvenient for the retrieval score.

## 4. Change the query without changing the model

```sh
python fde-embeddings-first-search.py inspect --query "I forgot my login secret."
python fde-embeddings-first-search.py inspect --query "How do I recover access?"
```

Record your prediction before running each query. Preserve the actual top two
results, whether they met your expectation and what evidence is still missing.
Add one new fictional ambiguous query or a similar-topic negative example.
No text is sent to a provider by these commands.

Empty text and input beyond 256 word pieces are rejected rather than silently
truncated. If a passage is too long, split it deliberately and preserve its
source location and important qualifications. A short paragraph model is not
a reason to discard a sentence that changes the instruction.

## 5. Keep access and answer support separate

The fixed trusted `north` scope admits four current teaching passages. P5 is
retired and P9 belongs to another organization. They are excluded before
encoding and ranking, even though both contain the password query verbatim.
Their text is absent from the inspection output. A real system needs current
authorization in its data layer; this local fixture is not an identity service.

Store the embedding model, preprocessing version and source identity with the
index. A different model can output the same number of values while using an
incompatible representation. Plan re-embedding and evaluation for a model
change. Similarity does not grant permission or establish freshness.

The next application step could select a passage for an evidence packet.
Generation and source-support evaluation would follow separately. This lab
produces no answer, makes no generative-model call and sets no universal
production similarity threshold.

## 6. Keep a receiving packet

Save:

- A five-box explanation: text → encoder → vector → search → source review.
- Python/package versions, model revision and the eight-check result.
- Predictions and actual top-two results for the four reference queries.
- Two new query observations, including a miss or ambiguity if observed.
- An explanation of the contradiction, the no-answer result and the two excluded sources.
- One condition that requires rebuilding the index and one next evaluation.

For a real collection, compare lexical, vector and hybrid retrieval on questions
whose useful passages have been labeled before tuning. Include questions that
cannot be answered and sources that must not be disclosed.

## Sources and model provenance

Primary references checked 20 October 2026:

- [Publisher model card and license](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2)
- [Sentence Transformers: semantic similarity](https://sbert.net/docs/sentence_transformer/usage/semantic_textual_similarity.html)
- [Sentence Transformers: semantic search](https://www.sbert.net/examples/sentence_transformer/applications/semantic-search/README.html)
- [ONNX Runtime: Python inference](https://onnxruntime.ai/docs/get-started/with-python.html)

These are instructional references, not a certification or partnership claim.