← Back to The Associate Track

// What's Next · Done · The Associate Track

Introduction to Embeddings with the OpenAI API

Completed Nov 06, 2026 · 3 hrs

Embeddings map text into a multi-dimensional vector space so that similar meanings sit close together, enabling semantic search, recommendations, and zero-shot classification by comparing cosine distances. ChromaDB stores and queries these vectors efficiently at scale.

Embedding fundamentals

  • embeddings: Numerical representations of text mapped into a multi-dimensional vector space, where more similar texts sit closer together.
  • semantic meaning: The full context and intent captured by an embedding, so paraphrases like supermarket and shop are recognized as related.
  • vector space: The multi-dimensional space where each text's position is given by the numbers the model outputs.
  • cosine distance: A metric from scipy.spatial ranging from 0 to 2, where smaller values indicate greater similarity between two vectors.
  • t-SNE: A dimensionality reduction technique used to project embeddings down to 2 dimensions for visualization, at the cost of some information.

Creating embeddings with the OpenAI API

  • Embeddings endpoint: The OpenAI API route called through client.embeddings.create(), requiring an API key and taking model and input arguments.
  • input: The text to embed, which accepts a single string or a list of strings for batching multiple inputs in one call.
  • model_dump(): Converts the response object into a dictionary for easier access to keys such as data, model, and usage.
  • data: The list in the response holding one dictionary per input, each containing an embedding, index, and object.
  • batching: Passing a list of texts to create() so embeddings come back in a single API call, one dictionary per input.
  • usage: The response key reporting token counts such as total_tokens.

Embedding applications

  • semantic search: Embeds the query and candidate texts, computes cosine distances, and returns the closest matches.
  • enriched embeddings: Combining headline, topic, and keywords into one formatted string before embedding to improve relevance.
  • recommendation systems: Embed the items and the user's history, average history vectors with numpy.mean, filter seen items, and recommend the nearest unseen.
  • zero-shot classification: Embeds class descriptions as reference points, computes cosine distances, and assigns the label with the smallest distance.
  • find_n_closest: A helper that computes distances, sorts them, and returns the n closest results with their indices.
  • user history: Multiple viewed articles combined by taking the mean of their embeddings to base recommendations on.

Vector databases and ChromaDB

  • vector database: Stores embeddings, source text, and metadata, and computes similarity much more efficiently than in-memory rescanning.
  • ChromaDB: An open-source vector database with local and client/server modes, used to embed, store, update, and query vectors.
  • collection: Analogous to a table, created with create_collection() from a name and an embedding_function such as OpenAIEmbeddingFunction.
  • query(): Retrieves the n_results nearest items to query_texts, embedding the query automatically and returning ids, documents, metadatas, and distances.
  • metadata: Small extra data such as type and release_year used to filter results with where clauses and operators like $eq, $ne, $gt, and $and.
  • tiktoken: OpenAI's tokenizer used to count tokens and estimate embedding costs before inserting a large dataset.

// Module notes

What embeddings are

The point of an embedding is position: similar texts land near each other in a multi-dimensional vector space, dissimilar ones far apart.

  • Words, phrases, or entire documents are mapped to numbers by an embedding model.
  • Proximity is semantic meaning, the full context and intent behind a word: supermarket and shop sit close, so a model treats those queries as related.
  • Every vector holds 1536 numbers, no matter the input.
  • t-SNE projects 1536 dimensions down to 2D for plotting, and some information is lost in the squeeze.

Watch the squeeze: the 2D view is a map, not the territory.

Creating embeddings

One API call can embed a whole batch of texts, so batch instead of looping.

  • The embeddings endpoint takes a model and an input, a single string or a list of strings.
  • Batching a list is more efficient than one call per text and returns one embedding per input.
  • model_dump() turns the response into a dictionary; data holds one entry per input with embedding, index, and object.
  • usage reports total_tokens.
  • Loop with enumerate to assign each embedding back to its article.

Batch early: it is the difference between one request and hundreds.

Similarity and applications

Every embedding application is the same three moves: embed the query and the candidates, compute cosine distances, return the closest.

  • Cosine distance runs from 0 to 2; smaller means more similar.
  • Semantic search enriches text by combining headline, topic, and keywords into one string before embedding.
  • Recommendations average user-history vectors with numpy.mean and filter out seen items.
  • Zero-shot classification embeds class descriptions as reference points and assigns the nearest label.

Vague class descriptions mislabel: a one-word label like Business carries too little meaning, so write detailed descriptions.

Vector databases with ChromaDB

At scale, holding millions of 13kB embeddings in memory and rescanning them per query stops working, so the vectors move into a vector database that stores embeddings, source text, and metadata and computes similarity far more efficiently.

  • ChromaDB runs in local or client/server mode; PersistentClient saves to disk.
  • create_collection takes a name and an embedding_function like OpenAIEmbeddingFunction.
  • Add documents with add(ids=..., documents=...), inspect with count() and peek(), query with query(query_texts=[...], n_results=...), which embeds the query automatically.
  • update, upsert, and delete modify items; where filters like $eq or $and narrow results.

Read the query return carefully: Chroma nests results in a list per query text.

In plain terms

Embeddings are a map of meaning: the OpenAI API turns text into 1536 numbers, so supermarket and shop land in the same neighbourhood and cosine distance is just the distance between two addresses. Search, recommendations, and zero-shot classification all become a nearest-neighbour lookup on that map, and ChromaDB is the filing cabinet that keeps millions of coordinates searchable.

Worth sitting with

  • What does an embedding space do with two texts that share every keyword but mean opposite things, like a sarcastic review and a glowing one?
  • If a query vector lands almost exactly between two class descriptions, what should the classifier do, and what does that gap tell you about the space?
  • When a Chroma collection grows from thousands to millions of vectors, which breaks first: embedding cost, query latency, or metadata filtering?

// Where this fits

The concepts above are the ones this module turns on, and the notes below explain each in turn. The course page carries the whole track, and the certificate page carries the plan it belongs to.