Behind File Search: What Actually Makes Retrieval Work

Unit 9, Lesson 2 covered file search as a built-in tool: upload documents to a vector store, and the platform automatically retrieves the passages relevant to a given question. That lesson deliberately treated the retrieval mechanism as a black box — the platform handles chunking, indexing, and similarity search internally, and nothing about using file search requires understanding what happens inside it. This unit opens that box. Embeddings are the underlying representation that makes semantic retrieval possible at all, and understanding them directly is what lets you build custom retrieval systems beyond what the built-in file search tool covers — a specialized similarity metric, a hybrid search combining several signals, retrieval over data that isn't naturally organized as uploadable files.

The Problem: Comparing Meaning, Not Just Words

Suppose you want to find, out of a thousand stored customer support tickets, the ones most similar in meaning to a new incoming ticket. A simple approach — checking whether the same words appear in both — fails in an obvious way: "my package hasn't arrived" and "shipment is delayed" describe the same underlying problem but share almost no words in common. Any retrieval approach based purely on literal word overlap misses this kind of match entirely, even though a human reading both sentences would immediately recognize them as related.

Embeddings solve this by representing meaning numerically rather than representing words literally. An embedding model converts a piece of text into a list of numbers — a vector, typically with hundreds or thousands of dimensions — positioned in a high-dimensional space such that pieces of text with similar meaning end up close together in that space, and pieces of text with different meaning end up far apart, regardless of whether they share any specific words at all. Nothing here requires understanding the underlying mathematics of how that positioning is learned; what matters practically is the behavior it produces — similar meaning maps to nearby vectors — and how to make use of that behavior, which is exactly what this lesson and the two that follow it cover.

Generating an Embedding

response = client.embeddings.create(
    model="text-embedding-4",
    input="My package hasn't arrived yet.",
)

embedding_vector = response.data[0].embedding
print(f"Vector length: {len(embedding_vector)}")
print(f"First five values: {embedding_vector[:5]}")

Note: The exact embedding model name, the resulting vector's dimensionality, and the exact response shape can vary by SDK version and by which embedding model is current. Confirm the current model name and its output dimensionality against your installed SDK version's documentation before relying on these specifics.

Running this produces a list of floating-point numbers — not a summary, not a category label, just a long list of numbers with no individually meaningful interpretation on their own. The vector as a whole is what carries meaning, and that meaning only becomes useful in comparison to other vectors, which is the subject of Lesson 3. A single embedding vector in isolation tells you almost nothing; the value comes entirely from measuring how close or far two (or more) embedding vectors are from each other.

Why Similar Meanings End Up Close Together

An embedding model is trained on enormous amounts of text, learning statistical patterns in which words and phrases co-occur and in what contexts. Through this training, the model learns to place text with related meaning near each other in the vector space — not because anyone manually labeled "these two sentences mean the same thing," but because the patterns of real language usage the model was trained on make semantically related text naturally cluster together as a side effect of learning to predict and represent language well. This is the same underlying kind of model as the language models this course has used throughout (in the sense that both are trained on large amounts of text to capture patterns in language), but an embedding model's job is specifically to produce a fixed-length numerical representation of a piece of text, rather than to generate new text as client.responses.create() does.

pairs_to_compare = [
    ("My package hasn't arrived yet.", "The shipment is delayed."),
    ("My package hasn't arrived yet.", "What's your refund policy?"),
]

for text_a, text_b in pairs_to_compare:
    response = client.embeddings.create(model="text-embedding-4", input=[text_a, text_b])
    vector_a = response.data[0].embedding
    vector_b = response.data[1].embedding
    print(f"'{text_a}' vs '{text_b}': vectors generated, length {len(vector_a)} each")

Passing a list of strings to a single embeddings.create() call, as shown here, generates an embedding for each string in one request rather than requiring a separate call per string — worth doing whenever multiple pieces of text need embedding at once, since it's both more efficient and typically cheaper than issuing one request per string. Lesson 3 covers actually computing how similar vector_a and vector_b are to each other; for now, the important idea is that the first pair (both about a delayed shipment) would be expected to produce vectors much closer together than the second pair (a shipment complaint versus a refund policy question), purely because of what each sentence means, independent of shared vocabulary.

Embeddings Are Not the Same as Structured Outputs

It's worth being precise about how embeddings relate to structured outputs (Unit 6), since both involve the SDK producing something other than free-form text, and conflating the two is an easy early mistake.

A structured output is meant to be read and used directly — a category field, an amount field, each with a clear meaning. An embedding vector is not meant to be read directly at all; it exists purely as an intermediate representation to be compared against other embedding vectors.

What Embeddings Are Used For

Embeddings underlie a range of tasks beyond the retrieval-augmented generation Unit 9, Lesson 2 covered: semantic search (finding documents or passages similar in meaning to a query, which is exactly what powers file search internally), clustering (grouping a large set of texts into naturally occurring topics without predefined categories), classification (comparing a new piece of text's embedding against embeddings of known example categories), recommendation (finding items similar to ones a user has previously engaged with), and deduplication (identifying near-duplicate pieces of text that differ in wording but say essentially the same thing). Each of these tasks reduces, at its core, to the same underlying operation: compute embeddings for the relevant pieces of text, then measure and compare distances between them. This course focuses in depth on the first of these — semantic search — across Lessons 2 through 5, since it is the most immediately practical starting point and the one that most directly extends Unit 9's built-in file search.

Vectors From Different Embedding Models Are Not Comparable

An easy mistake once a collection of embeddings has been built up over time is assuming any two embedding vectors can be meaningfully compared, regardless of which model produced them. They cannot. Two different embedding models place text in entirely different, unrelated vector spaces — even if both happen to produce vectors of the same length, a vector from one model and a vector from another have no consistent geometric relationship to each other, since each model learned its own positioning during its own training process.

response_model_a = client.embeddings.create(model="text-embedding-4", input="Return policy inquiry")
# A different embedding model, hypothetically:
# response_model_b = client.embeddings.create(model="some-other-embedding-model", input="Return policy inquiry")

# Comparing response_model_a's vector against a vector from a different model
# would produce a similarity score with no meaningful interpretation, even
# though both vectors describe the exact same input text.

Note: If an application ever changes which embedding model it uses — whether deliberately, or because a model is deprecated — every previously stored embedding needs to be regenerated with the new model before being compared against anything newly embedded. Mixing vectors from two different embedding models in the same collection silently produces meaningless similarity scores rather than an obvious error, which makes this an easy mistake to miss until search results start looking wrong for no apparent reason.

This is a practical, recurring concern for any long-lived application built on embeddings: a model upgrade is not a drop-in replacement the way upgrading a language model version usually is, since the entire stored collection depends on having been embedded consistently with whatever model is currently in use.

Common Mistakes

Treating an embedding vector as something to read or interpret directly, when its only meaningful use is in comparison to other embedding vectors, not as a standalone summary or feature extraction of a text's content.

Confusing embeddings with structured outputs, expecting a vector's individual values to have the same kind of direct, human-readable meaning a structured-output field has.

Assuming literal word overlap and semantic similarity are the same thing, missing the entire point of embeddings, which exist specifically to capture meaning that plain keyword matching cannot.

Expecting to need to understand the underlying mathematics of how embeddings are learned before using them productively, when what actually matters for building with them is their practical behavior — similar meaning maps to nearby vectors — not the training process that produces that behavior.

Comparing or mixing embedding vectors produced by two different models, which silently produces a meaningless similarity score rather than a visible error, since nothing about the vectors themselves signals which model produced them.

Best Practices

Batch multiple texts into a single embeddings.create() call when embedding several pieces of text at once, rather than issuing one request per string.

Reach for embeddings specifically when a task requires comparing meaning rather than exact text, and reach for structured outputs (Unit 6) when a task requires extracting or generating data in a predictable, directly readable shape.

Remember that file search (Unit 9, Lesson 2) already handles embedding generation and comparison internally — build a custom embeddings pipeline only when a specific requirement (a custom similarity metric, a non-file-based data source, a need to inspect or manipulate the vectors directly) goes beyond what the built-in tool already provides.

Regenerate every stored embedding with the new model whenever an embedding model changes, rather than mixing vectors from an old and a new model in the same collection.