Text Embeddings with Model API

Introduction

Hello! In our last lesson, we explored the concept of text embeddings—how they represent text as dense numerical vectors in a high-dimensional space where distance signifies semantic similarity. We established what they are and why they are so powerful.

Today, we move from theory to practice. This lesson is all about the "how": you will learn to generate text embeddings using dedicated model APIs. As a software engineer, you'll find this process analogous to interacting with any other web service or library. We'll cover the two primary methods for doing this:

1. Using a cloud-based API, like the one provided by OpenAI.
2. Using an open-source model running locally on your machine via a library.

By the end of this lesson, you'll be able to convert any piece of text into its vector representation, a crucial skill for building the advanced LLM applications you're interested in, such as RAG and semantic search.

The General Workflow

Regardless of the specific tool you use, the process of generating an embedding is fundamentally the same. You take a piece of text, send it to an embedding model, and receive a vector (an array of numbers) in return.

The diagram below illustrates this workflow using OpenAI's embedding service as an example. Source documents are fed into the embedding engine, which produces vectors that can then be stored and used.

Method 1: Generating Embeddings with a Cloud API (OpenAI)

Using a cloud-based API is often the quickest and easiest way to get started. You benefit from using powerful, state-of-the-art models without needing to manage any infrastructure. OpenAI's API is a very common choice for this.

To generate an embedding, you'll make an API call to a specific endpoint, providing your text and specifying which model you want to use.

For a quick demonstration of this process, please watch the following short clip.

Step-by-Step Guide with Python

Now, let's walk through the practical steps to do this yourself using Python. The datacamp.com article below provides an excellent, code-first guide. We will focus on the core implementation part.

Let's break down the essential code from that guide into a minimal, runnable example.

1. Installation
First, you need the OpenAI Python library.

pip install openai

2. Setup and API Call
You will need an API key from OpenAI. It's a best practice to store this as an environment variable rather than hardcoding it in your script.

import os
from openai import OpenAI







# It's recommended to set your API key as an environment variable
# export OPENAI_API_KEY='your-key-here'
# The client will automatically pick it up from the environment.
client = OpenAI()







# Define the text you want to embed
text_to_embed = "The software engineer is debugging the new feature."







# Choose the embedding model. 'text-embedding-3-small' is a good, cost-effective choice.
model_id = "text-embedding-3-small"

try:






    # Make the API call
    response = client.embeddings.create(
        input=[text_to_embed],  # Input can be a list of strings
        model=model_id
    )







    # Extract the embedding vector
    embedding_vector = response.data[0].embedding

    print(f"Successfully generated embedding for the text.")
    print(f"Vector dimensions: {len(embedding_vector)}")
    print(f"First 5 dimensions: {embedding_vector[:5]}")

except Exception as e:
    print(f"An error occurred: {e}")

When you run this code, the output will be a long list of floating-point numbers. For the text-embedding-3-small model, this vector will have 1536 dimensions. This vector is the numerical representation of the sentence's meaning.

Method 2: Generating Embeddings with a Local Model

An alternative to cloud APIs is running an open-source embedding model directly on your own machine. This approach is great when:

• Data privacy is a major concern.
• You want to avoid ongoing API costs for high-volume tasks.
• You need to operate in an environment without internet access.

The sentence-transformers library is a fantastic tool for this, providing a simple interface to a wide range of pre-trained models available on the Hugging Face Hub.

Let's see how this is done in practice.

Here is a concise example based on the article.

1. Installation
You'll need sentence-transformers and its dependencies (like PyTorch).

pip install sentence-transformers

2. Setup and Encoding
The process is straightforward: load a model and call its encode method.

from sentence_transformers import SentenceTransformer







# 1. Load a pre-trained model from the Hugging Face Hub
# 'all-MiniLM-L6-v2' is a popular, lightweight model.
model = SentenceTransformer('all-MiniLM-L6-v2')







# 2. Define the text or list of texts to embed
sentences = [
    "The software engineer is debugging the new feature.",
    "The chef is preparing a delicious meal."
]







# 3. Generate the embeddings
embeddings = model.encode(sentences)







# The result is a NumPy array where each row is an embedding
print(f"Shape of the embeddings array: {embeddings.shape}")


```grasp
{
  "type": "exercise",
  "id": "65ce4cb0-f8c9-4ea2-b141-df8778273b3e"
}

Print the embedding for the first sentence

first_embedding = embeddings[0]
print(f"Vector dimensions: {len(first_embedding)}")
print(f"First 5 dimensions: {first_embedding[:5]}")

Notice that the `all-MiniLM-L6-v2` model produces a vector with **384** dimensions. Different models have different output dimensionalities, which is a trade-off between performance, size, and descriptive power.





```grasp
{
  "type": "exercise",
  "id": "759ae0ca-5955-427a-86c3-cba2925c0b05"
}

Choosing the Right Approach: API vs. Local

You've now seen two distinct ways to achieve the same goal. As an engineer, choosing the right tool for the job is critical. The decision between a cloud API and a self-hosted model depends on your project's specific constraints.

The Dataquest article you just reviewed contains an excellent summary of these trade-offs.

Here’s a quick summary of the key decision factors from the article:

Dimension	Self-hosted Models (e.g., sentence-transformers)	API Services (e.g., OpenAI)
Cost	No per-use cost, but requires computational hardware.	Pay-per-use, but no infrastructure to manage.
Performance	Speed depends on your hardware.	Very fast, uses optimized infrastructure. Can be limited by network latency and rate limits.
Privacy	All data remains on your infrastructure. Ideal for sensitive data.	Data is sent to a third-party provider.
Customization	You can fine-tune models on your own data for specific domains.	Limited to the models offered by the provider.
Infrastructure	You are responsible for managing dependencies, scaling, and updates.	No infrastructure management required.

In short:

• Use API Services for rapid prototyping, applications with variable workloads, or when you want to use the latest models without managing infrastructure.
• Use Self-Hosted Models when dealing with large volumes of data, sensitive information, or when you need to customize a model for a specific task.

Conclusion

In this lesson, we bridged the gap from the conceptual to the practical. You now have the tools to convert text into meaningful numerical vectors.

Key Takeaways:

• You can generate text embeddings using either a cloud API (like OpenAI) or a local, open-source model (with libraries like sentence-transformers).
• API-based generation is simple and provides access to powerful models without infrastructure overhead, making it great for getting started. The core is an API call like client.embeddings.create().
• Local model generation offers privacy, control, and no ongoing costs, but requires you to manage the computational resources. The core is a method call like model.encode().
• The choice between these two approaches is a strategic one, involving trade-offs between cost, privacy, performance, and control.

Now that we can generate these vectors, what can we do with them? In our next lesson, we will answer that question by learning how to compute the cosine similarity between embeddings. This will allow us to quantitatively measure how "close" two pieces of text are in meaning, unlocking capabilities like semantic search.