Choose an embeddings task type

Vertex AI embeddings models can generate optimized embeddings forvarious task types, such as document retrieval, question and answering, and factverification. Task types are labels that optimize the embeddings that the modelgenerates based on your intended use case. This document describes how to choosethe optimal task type for your embeddings.

Supported models

Task types are supported by the following models:

  • text-embedding-005
  • text-multilingual-embedding-002
  • gemini-embedding-001

Benefits of task types

Task types can improve the quality of embeddings generated by an embeddingsmodel.

Questions and their answers aren't semantically similar
Figure 1. Questions and their answers aren't semantically similar, which means that embeddings won't automatically show their relation.

For example, when building Retrieval Augmented Generation (RAG) systems, acommon design is to use text embeddings andVector Search toperform a similarity search. In some cases this can lead to degraded searchquality, because questions and their answers are not semantically similar. Forexample, a question like "Why is the sky blue?" and its answer "The scatteringof sunlight causes the blue color," have distinctly different meanings asstatements, which means that a RAG system won't automatically recognize theirrelation, as demonstrated in figure 1. Without task types, a RAG developer wouldneed totrain their model to learn the relationship between queries and answerswhich requires advanced data science skills and experience,or useLLM-based query expansion orHyDE which can introduce high latency andcosts.

Task type puts questions and answers closer in the embeddings space
Figure 2. Task types optimize embeddings for specific tasks. In this case, questions and answers are brought closer together in the embeddings space.

Task types enable you to generate optimized embeddings for specific tasks,which saves you the time and cost it would take to develop your owntask-specific embeddings. The generated embedding for a query "Why is the skyblue?" and its answer "The scattering of sunlight causes the blue color" wouldbe in the shared embedding space that represents the relationship between them,as demonstrated in figure 2. In this RAG example, the optimized embeddingswould lead to improved similarity searches.

In addition to the query and answer use case, task types also provide optimizedembeddings space for tasks such as classification, clustering, and factverification.

Supported task types

Embeddings models that use task types support the following task types:

Task typeDescription
CLASSIFICATIONUsed to generate embeddings that are optimized to classify texts according to preset labels
CLUSTERINGUsed to generate embeddings that are optimized to cluster texts based on their similarities
RETRIEVAL_DOCUMENT,RETRIEVAL_QUERY,QUESTION_ANSWERING, andFACT_VERIFICATIONUsed to generate embeddings that are optimized for document search or information retrieval
CODE_RETRIEVAL_QUERYUsed to retrieve a code block based on a natural language query, such assort an array orreverse a linked list. Embeddings of the code blocks are computed usingRETRIEVAL_DOCUMENT.
SEMANTIC_SIMILARITYUsed to generate embeddings that are optimized to assess text similarity. This is not intended for retrieval use cases.

The best task type for your embeddings job depends on what use case you have foryour embeddings. Before you select a task type, determine your embeddings usecase.

Determine your embeddings use case

Embeddings use cases typically fall within one of four categories: assessingtext similarity, classifying texts, clustering texts, or retrieving informationfrom texts. If your use case doesn't fall into one of the preceding categories,use theRETRIEVAL_QUERY task type by default.

Key Point: If your embeddings use case doesn't align with a documented use case,use theRETRIEVAL_QUERY task type by default.

There are 2 types of task instruction formatting, asymmetric format and symmetric format. You'll need to use the correct one based on your use case.

Retrieval Use cases
(Asymmetric Format)		Query task typeDocument task type
Search QueryRETRIEVAL_QUERYRETRIEVAL_DOCUMENT
Question AnsweringQUESTION_ANSWERING
Fact CheckingFACT_VERIFICATION
Code RetrievalCODE_RETRIEVAL_QUERY



Single-input Use Cases
(Symmetric Format)		Input task type
ClassificationCLASSIFICATION
ClusteringCLUSTERING
Semantic Similarity
(Do not use for retrieval use cases;
intended for STS)		SEMANTIC_SIMILARITY

Classify texts

If you want to use embeddings to classify texts according to preset labels, usetheCLASSIFICATION task type. This task type generates embeddings in anembeddings space that is optimized for classification.

For example, suppose you want to generate embeddings for social media poststhat you can then use to classify their sentiment as positive, negative, orneutral. When embeddings for a social media post that reads "I don't liketraveling on airplanes" are classified, the sentiment would be classified asnegative.

Key Point: To get embeddings that are optimized to classify using predefinedlabels, use theCLASSIFICATION task type.

Cluster texts

If you want to use embeddings to cluster texts based on their similarities, usetheCLUSTERING task type. This task type generates embeddings that areoptimized for being grouped based on their similarities.

For example, suppose you want to generate embeddings for news articles so thatyou can show users articles that are topically-related to the ones they havepreviously read. After the embeddings are generated and clustered, you cansuggest additional sports-related articles to users who read a lot about sports.

Additional use cases for clustering include the following:

  • Customer segmentation: group customers with similar embeddings generatedfrom their profiles or activities for targeted marketing and personalizedexperiences.
  • Product segmentation: clustering product embeddings based on their producttitle and description, product images, or customer reviews can help businessesdo segment analysis on their products.
  • Market research: clustering consumer survey responses or social media dataembeddings can reveal hidden patterns and trends in consumer opinions,preferences, and behaviors, aiding market research efforts and informingproduct development strategies.
  • Healthcare: clustering patient embeddings derived from medical data canhelp identify groups with similar conditions or treatment responses, leadingto more personalized healthcare plans and targeted therapies.
  • Customer feedback trends: clustering customer feedback from variouschannels (surveys, social media, support tickets) into groups can helpidentify common pain points, feature requests, and areas for productimprovement.
Key Point: To get embeddings that are optimized for clustering based onsimilarities, use theCLUSTERING task type.

Retrieve information from texts

Key Point: To get embeddings that you can use for information retrieval, use theRETRIEVAL_DOCUMENT task type to embed your documents and theRETRIEVAL_QUERYtask type to embed user queries.

When you build a search or retrieval system, you work with two types of text:

  • Corpus: The collection of documents that you want to search over.
  • Query: The text that a user provides to search for information withinthe corpus.

To get the best performance, you must use different task types to generateembeddings for your corpus and your queries.

First, generate embeddings for your entire collection of documents. This is thecontent that will be retrieved by user queries. When embedding these documents,use theRETRIEVAL_DOCUMENT task type. You typically perform this step once toindex your entire corpus and then store the resulting embeddings in a vectordatabase.

Next, when a user submits a search, you generate an embedding for their querytext in real time. For this, you should use a task type that matches the user'sintent. Your system will then use this query embedding to find the most similardocument embeddings in your vector database.

The following task types are used for queries:

  • RETRIEVAL_QUERY: Use this for a standard search query where you want tofind relevant documents. The model looks for document embeddings that aresemantically close to the query embedding.
  • QUESTION_ANSWERING: Use this when all queries are expected to be proper questions, such as "Why is the sky blue?" or "How do I tie my shoelaces?".
  • FACT_VERIFICATION: Use this when you want to retrieve a document from your corpus that proves or disproves a statement. For example, the query "apples grow underground" might retrieve an article about apples that would ultimately disprove the statement.

Consider the following real-world scenario where retrieval queries would beuseful:

  • For an ecommerce platform, you want to use embeddings to enable users tosearch for products using both text queries and images, providing a moreintuitive and engaging shopping experience.
  • For an educational platform, you want to build a question-answering systemthat can answer students' questions based on textbook content or educationalresources, providing personalized learning experiences and helping studentsunderstand complex concepts.

Code Retrieval

text-embedding-005 supports a new task typeCODE_RETRIEVAL_QUERY,which can be used to retrieve relevant code blocks using plain text queries. Touse this feature, code blocks should be be embedded using theRETRIEVAL_DOCUMENT task type, while text queries embedded usingCODE_RETRIEVAL_QUERY.

To explore all task types, see themodel reference.

Here is an example:

REST

PROJECT_ID=PROJECT_IDcurl\-XPOST\-H"Authorization: Bearer $(gcloud auth print-access-token)"\-H"Content-Type: application/json"\https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/text-embedding-005:predict -d \$'{"instances":[{"task_type":"CODE_RETRIEVAL_QUERY","content":"Function to add two numbers"}],}'

Python

To learn how to install or update the Vertex AI SDK for Python, seeInstall the Vertex AI SDK for Python. For more information, see thePython API reference documentation.

fromvertexai.language_modelsimportTextEmbeddingInput,TextEmbeddingModelMODEL_NAME="gemini-embedding-001"DIMENSIONALITY=3072defembed_text(texts:list[str]=["Retrieve a function that adds two numbers"],task:str="CODE_RETRIEVAL_QUERY",model_name:str="gemini-embedding-001",dimensionality:int|None=3072,)->list[list[float]]:"""Embeds texts with a pre-trained, foundational model."""model=TextEmbeddingModel.from_pretrained(model_name)kwargs=dict(output_dimensionality=dimensionality)ifdimensionalityelse{}embeddings=[]# gemini-embedding-001 takes one input at a timefortextintexts:text_input=TextEmbeddingInput(text,task)embedding=model.get_embeddings([text_input],**kwargs)print(embedding)# Example response:# [[0.006135190837085247, -0.01462465338408947, 0.004978656303137541, ...]]embeddings.append(embedding[0].values)returnembeddingsif__name__=="__main__":# Embeds code block with a pre-trained, foundational model.# Using this function to calculate the embedding for corpus.texts=["Retrieve a function that adds two numbers"]task="CODE_RETRIEVAL_QUERY"code_block_embeddings=embed_text(texts=texts,task=task,model_name=MODEL_NAME,dimensionality=DIMENSIONALITY)# Embeds code retrieval with a pre-trained, foundational model.# Using this function to calculate the embedding for query.texts=["def func(a, b): return a + b","def func(a, b): return a - b","def func(a, b): return (a ** 2 + b ** 2) ** 0.5",]task="RETRIEVAL_DOCUMENT"code_query_embeddings=embed_text(texts=texts,task=task,model_name=MODEL_NAME,dimensionality=DIMENSIONALITY)

Assess text similarity

If you want to use embeddings to assess text similarity, use theSEMANTIC_SIMILARITY task type. This task type generates embeddings that areoptimized for generating similarity scores.

For example, suppose you want to generate embeddings to use to compare thesimilarity of the following texts:

  • The cat is sleeping
  • The feline is napping

When the embeddings are used to create a similarity score, the similarity scoreis high, because both texts have nearly the same meaning.

Consider the following real-world scenarios where assessing input similaritywould be useful:

  • For a recommendation system, you want to identify items (e.g., products,articles, movies) that are semantically similar to a user's preferred items,providing personalized recommendations and enhancing user satisfaction.
Key Point: To get embeddings that are optimized to assess text similarity, usetheSEMANTIC_SIMILARITY task type.Note:SEMANTIC_SIMILARITY is not intended for retrieval use cases, such as document search and information retrieval. For these use cases, useRETRIEVAL_DOCUMENT,RETRIEVAL_QUERY,QUESTION_ANSWERING, andFACT_VERIFICATION.

The following limitations apply when using these models:

  • Don't use these preview models on mission critical or production systems.
  • These models are available inus-central1 only.
  • Batch predictions are not supported.
  • Customization is not supported.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.