Embeddings and semantic search

Search that understands meaning is the first half of RAG (retrieval-augmented generation). A customer types "something cold and strong, not sweet", and a keyword search finds nothing because the menu says "Cold Brew: slow-steeped, bold, unsweetened". Embeddings let the computer see that these mean nearly the same thing. In this lesson you will learn what an embedding is, how similarity is measured, and how to build a small semantic search in about 30 lines of Python.

An embedding is a list of numbers (a vector) that represents the meaning of a piece of text. An embedding model reads your text and outputs, for example, 768 numbers. Texts with similar meaning get vectors that point in similar directions; unrelated texts get vectors that point elsewhere.

Think of a map. On a map of India, each city has two numbers, latitude and longitude, and nearby numbers mean nearby places. An embedding is a map of meaning with hundreds or thousands of directions instead of two. "Cold Brew" and "iced coffee" are neighbours; "Cold Brew" and "income tax" are far apart.

Important facts:

- The numbers have no meaning one by one. Only the distance between vectors matters. - Every text, short or long, becomes a vector of the same length for a given model. - Vectors from different models cannot be compared. If you change the model, you must re-embed everything.

The standard measure is cosine similarity: the cosine of the angle between two vectors. It ranges from -1 to 1. Vectors pointing the same way score near 1; unrelated ones score near 0 (in practice, many text pairs sit well above 0, so only compare scores against each other); opposite ones score near -1. It ignores vector length and looks only at direction.

Real embeddings work the same way, just with hundreds of numbers. The formula is the dot product of the two vectors divided by the product of their lengths. If vectors are already normalised (length 1), cosine similarity is just the dot product, which is why many systems normalise once and then use fast dot products.

Gemini offers embedding models through the same SDK. You pass a list of texts and get one vector per text. Model names change, so check the embeddings page in the Gemini API docs. At the time of writing (2026), gemini-embedding-001 is a text embedding model that lets you choose the output size and a task type, and a newer multimodal model, gemini-embedding-2, exists too (it works a little differently, for example without task types). The code below uses gemini-embedding-001.

import numpy as np
from dotenv import load_dotenv
from google import genai
from google.genai import types

load_dotenv()
client = genai.Client()

EMBED_MODEL = "gemini-embedding-001"  # check the docs for the current embedding model
DIMS = 768


def embed(texts: list[str], task_type: str) -> np.ndarray:
    result = client.models.embed_content(
        model=EMBED_MODEL,
        contents=texts,
        config=types.EmbedContentConfig(task_type=task_type, output_dimensionality=DIMS),
    )
    vectors = np.array([e.values for e in result.embeddings], dtype=np.float32)
    # Smaller-than-default sizes are not normalised for this model, so do it ourselves
    vectors /= np.linalg.norm(vectors, axis=1, keepdims=True)
    return vectors


if __name__ == "__main__":
    v = embed(["Cold Brew: slow-steeped, bold and unsweetened"], "RETRIEVAL_DOCUMENT")
    print(v.shape)          # (1, 768)
    print(v[0][:5])         # the first five of 768 numbers
    print(np.linalg.norm(v[0]))  # about 1.0 after normalising

A reusable helper. It returns one normalised vector per text.

Those five numbers mean nothing alone. The power appears when you compare vectors.

import numpy as np

from embed_util import embed

DOCS = [
    "Espresso: a short, intense shot of coffee.",
    "Cappuccino: espresso with steamed milk and a thick layer of foam.",
    "Cold Brew: coffee steeped slowly in cold water, smooth, bold and unsweetened.",
    "Filter Coffee: South Indian style coffee with hot milk, served in a steel tumbler.",
    "Masala Chai: black tea simmered with milk and spices like ginger and cardamom.",
    "Butter Croissant: flaky, buttery pastry baked fresh every morning.",
    "Banana Bread: moist, lightly sweet loaf made with ripe bananas.",
    "Veg Grilled Sandwich: grilled bread with vegetables and cheese.",
    "Opening hours: we are open from 8 am to 10 pm every day.",
]

doc_vectors = embed(DOCS, "RETRIEVAL_DOCUMENT")  # embed once, reuse many times


def search(query: str, k: int = 3):
    q = embed([query], "RETRIEVAL_QUERY")[0]
    scores = doc_vectors @ q            # dot product = cosine similarity (normalised)
    top = np.argsort(scores)[::-1][:k]  # indexes of the k highest scores
    return [(DOCS[i], float(scores[i])) for i in top]


for query in ["something cold and strong, not sweet", "a snack for the morning", "when do you close?"]:
    print("\nQuery:", query)
    for text, score in search(query):
        print(f"  {score:.2f}  {text}")

Embeds the documents once, embeds each query, and ranks by dot product. RETRIEVAL_DOCUMENT and RETRIEVAL_QUERY tell the model which side each text is on.

The first query shares almost no words with the Cold Brew line, yet it ranks first. A keyword search could not do that. The last query finds the opening hours even though the word "close" is not in that sentence.

Because of these limits, strong search systems often combine embeddings with keyword search and re-ranking. That is covered in the chunking lesson. Other uses of embeddings: removing near-duplicate questions in a forum, grouping customer feedback by topic, and classifying text by finding the nearest labelled example.

Typical questions: "What is an embedding?", "Why cosine similarity instead of Euclidean distance?" (direction matters more than length; with normalised vectors the rankings are the same), "How would you build semantic search?" (chunk, embed, store, embed the query, take top-k by similarity), and "Why might semantic search miss an exact product code?" (embeddings capture meaning, not exact tokens, so add keyword search).

I built semantic search with text embeddings. For the query "[query]" my top 3 results were:

1. [score] [text]
2. [score] [text]
3. [score] [text]

The result I expected was: [expected text]. Suggest the most likely reasons it was not ranked first (chunk size, wording, model choice, missing keyword match), and give me 3 experiments to try, cheapest first.

What to expect: A useful answer lists concrete, testable changes, such as rewriting the document text, adding keyword search or trying a multilingual model.