Copyright 2025 Google LLC.

Gemini API: Getting started with Gemini embedding models

Embeddings are numerical representations that capture the relationships between different inputs. Text embeddings achieve this by converting text into arrays of floating-point numbers known as vectors. The primary purpose of these vectors is to encapsulate the semantic meaning of the text. The dimensionality of the vector, which is the length of the embedding array, can be quite large, with a passage of text sometimes being represented by a vector with hundreds of dimensions.

The Gemini API generates state-of-the-art text embeddings. An embedding is a list of floating point numbers that represent the meaning of a word, sentence, or paragraph. You can use embeddings in many downstream applications like document search.

This notebook provides quick code examples that show you how to get started generating embeddings.

Table of Contents

1. Setup: Install the SDK and set up your API key.
2. Embed content: Generate text embeddings for single or multiple inputs.
3. Truncating embeddings: Explore how to reduce the dimensionality of embeddings.
4. Embeddings in practice - Sentences similarity analysis: Use embeddings to analyze the similarity between sentences using cosine similarity and visualize the results with a heatmap.
5. Using task_type for different scenarios: Learn how to use task_type for various applications like Retrieval Augmented Generation (RAG), including an example of building a simple FAQ system.

Setup

Install SDK

Install the SDK from PyPI.

Setup your API key

To run the following cell, your API key must be stored it in a Colab Secret named GOOGLE_API_KEY. If you don't already have an API key or you aren't sure how to create a Colab Secret, see Authentication for an example.

Initialize SDK client

With the new SDK, now you only need to initialize a client with you API key (or OAuth if using Vertex AI). The model is now set in each call.

Choose a model

Select the model you want to use in this guide. You can either select one from the list or enter a model name manually.

For a full overview of all Gemini models, check the documentation.

Embed content

Call the embed_content method with the model to generate text embeddings.

Batch embed content

You can embed a list of multiple prompts with one API call for efficiency.

Setting embeddings dimensionality

The embedding models also supports lower embedding dimensions. Specify output_dimensionality to truncate the output.

Embeddings in practice - Sentences similarity analysis

Sentence similarity analysis leverages embedding models to transform sentences into numerical vectors that encapsulate their semantic meaning. This allows for the comparison of sentences by measuring the distance or angle between their respective vectors in a high-dimensional space - This way, texts with similar meanings will have vectors that are closer together.

For this example, you will use a Pandas dataframe to store sentences and calculate the similarity of an external sentence against them.

Now you will create a new dataframe column called embeddings to generate the embeddings for each text using the embedding model.

Analyzing the similarity of text examples with cosine similarity

By converting text into embeddings, you can calculate similarity scores. There are many ways to calculate similarity scores, and a common technique is to use cosine similarity.

In the example above, two of the sentences in the text column refer to enjoying a movie, and the other two relate to enjoying programming. The cosine similarity scores should be higher (close to 1.0) when making pairwise comparisons between semantically related sentences, and the scores should be lower between semantically different sentences.

The DataFrame output below shows the resulting cosine similarity scores between the embeddings:

To make this easier to understand, you can use a heatmap. Naturally, the text is most similar when they are identical (score of 1.0). The next highest scores are when the sentences are semantically similar. The lowest scores are when the sentences are quite different in meaning.

Using task_type for different scenarios

When generating embeddings, especially for complex systems like Retrieval Augmented Generation (RAG), a one-size-fits-all approach can sometimes lead to lower-quality results. For instance, a question like "Why is the sky blue?" and its answer, "The scattering of sunlight causes the blue color," have distinct meanings as statements, and a general-purpose embedding model might not recognize their strong relationship. To solve this, you can specify a task_type when creating embeddings. This instructs the model to produce vectors that are specifically optimized for your intended use case, which can significantly improve performance while also saving time and cost.

The Gemini embedding model supports several task types, each tailored for a specific goal. Here’s a general overview of the available types and their applications:

• SEMANTIC_SIMILARITY: Use this when your goal is to assess how semantically similar two pieces of text are.
• RETRIEVAL_QUERY and RETRIEVAL_DOCUMENT: These are essential for information retrieval tasks. Use RETRIEVAL_QUERY for the user's search query and RETRIEVAL_DOCUMENT for the texts in your database that you want to search through. This is the foundation for building effective semantic search and RAG systems.
• CLASSIFICATION: Choose this task type when you intend to use the embeddings to train a model that classifies text into a set of predefined categories.
• CLUSTERING: If your goal is to group similar texts together to identify hidden trends or topics without pre-existing labels, this task type will generate embeddings optimized for that purpose.

This example is an intuition of how more complex RAG systems work - like when you are building one FAQ system. You will:

• define some information, representing data from documents
• use the embedding model to generate the embeddings for those information
• look for information similar to the question asked
• then use a Gemini generative model to customize one answer to the question.

First you will declare the information representing the documents, create one structure including document titles and contents and create a dataframe from it.

Now you will create the embeddings using the (RETRIEVAL_DOCUMENT task type) column into the dataframe:

Now you will create a function to do the interaction between questions and the search in the dataframe.

The find_best_passage function to, instead of searching for simple keywords, it searches for meaning.

Here’s a step-by-step breakdown of what it does when you ask a question:

• First, the function takes your query (e.g., "how do I change gears?") and uses the embedding model to convert it into an embedding using the RETRIEVAL_QUERY task type.
• Then the function compares the embeddings from your question to the numbers of every single document. It calculates a similarity score for each pair. A higher score means the meanings are more closely aligned.
• Finally, the function identifies the document with the single highest similarity score and returns its original text as the most relevant answer to your question

Per example, for the question "how to make the fan speed stronger on the car cooling system" you have the following passage as the closest one:

Now you can do one augmented generation (the last step of the RAG process) using the best passage found by the first step, but still having custom answers for users instead of simply pasting large documents chunks directly:

Learning more

Check out these examples in the Cookbook to learn more about what you can do with embeddings:

• Search Reranking: Use embeddings from the Gemini API to rerank search results from Wikipedia.
• Anomaly detection with embeddings: Use embeddings from the Gemini API to detect potential outliers in your dataset.
• Train a text classifier: Use embeddings from the Gemini API to train a model that can classify different types of newsgroup posts based on the topic.

Embeddings have many applications in Vector Databases, too. Check out these examples:

• With Chroma DB
• With LangChain
• With LlamaIndex
• With Qdrant
• With Weaviate

You can learn more about embeddings in general on ai.google.dev in the embeddings guide