Bug Description

Description

With the recent official release of the gemini-embedding-2 model, Google updated their API requirements for how embedding task types are handled. During the gemini-embedding-2-preview phase, these requirements were not strictly documented or enforced, but they are now a mandatory part of the official Gemini API specification.

Currently, LlamaIndex's GoogleGenAIEmbedding passes the task_type parameter inside the EmbedContentConfig payload. While this is correct for gemini-embedding-001, for gemini-embedding-2 the task_type field is deprecated and the backend ignores this parameter, resulting in the model embedding raw text without task-specific optimization.

Instead, Google now strongly recommend to add the task instruction in your prompt.

• Queries: task: search result | query: {text}
• Documents: title: {title} | text: {text} (or title: none | text: {text})
• Other tasks: task: fact_verification | {text}, task: clustering | {text}, etc.

Impact on Users

Because LlamaIndex's BaseEmbedding implicitly routes standard operations through RETRIEVAL_QUERY and RETRIEVAL_DOCUMENT, the current integration handles gemini-embedding-2 incorrectly:

• Silent Accuracy Loss: Users believe they are using optimized retrieval task types, but the model is actually falling back to a default embedding state because the task_type parameter is ignored.
• Performance Degradation: The "massive accuracy improvements" promised by Gemini 2's asymmetric retrieval routing are lost without the string prefixes.

Proposed Solution

Modify _embed_texts and _aembed_texts in llama-index-embeddings-google-genai to conditionally handle "embedding-2" models:

1. Map LlamaIndex's core task types (RETRIEVAL_QUERY, RETRIEVAL_DOCUMENT, FACT_VERIFICATION, etc.) to the exact string prefixes mandated by the new Gemini API docs.
2. Format the texts list dynamically before making the API call.
3. Safely strip the task_type key from the EmbedContentConfig for v2 models to prevent API rejection.
4. Leave the logic completely untouched for gemini-embedding-001 for backward compatibility.

I have already implemented this fix with full test coverage mapping to the new API specifications. I will open a PR linking to this issue shortly.

References

https://ai.google.dev/gemini-api/docs/embeddings https://ai.google.dev/gemini-api/docs/embeddings#task-types-embeddings-2

Version

0.5.0

Steps to Reproduce

Because the Gemini API silently ignores the task_type parameter for gemini-embedding-2 (rather than throwing a 400 error), users experience a silent failure where they believe their embeddings are task-optimized, but they actually aren't.

You can prove this by requesting two different task types and seeing that the API returns the exact same vector:

from llama_index.embeddings.google_genai import GoogleGenAIEmbedding
from google.genai import types

# Use a dummy key for reproduction
API_KEY = "YOUR_API_KEY"
BASE_TEXT = "from llama_index.embeddings.google_genai import GoogleGenAIEmbedding"

# 1. Current behavior (Incorrect/No change in embedding)
model_retrieval = GoogleGenAIEmbedding(
    model_name="gemini-embedding-2", 
    api_key=API_KEY, 
    embedding_config=types.EmbedContentConfig(task_type="RETRIEVAL_QUERY")
)
model_code = GoogleGenAIEmbedding(
    model_name="gemini-embedding-2", 
    api_key=API_KEY, 
    embedding_config=types.EmbedContentConfig(task_type="CODE_RETRIEVAL_QUERY")
)

emb1 = model_retrieval.get_query_embedding(BASE_TEXT)
emb2 = model_code.get_query_embedding(BASE_TEXT)

print(f"Standard task_type comparison: {emb1 == emb2}") 
# Returns True (Incorrect: The vectors should be different)

# 2. Manual prefixing (The 'Gemini 2' way)
query_1 = f"task: retrieval_query | {BASE_TEXT}"
query_2 = f"task: code_retrieval_query | {BASE_TEXT}"

emb_manual_1 = model_retrieval.get_query_embedding(query_1)
emb_manual_2 = model_code.get_query_embedding(query_2)

print(f"Manual prefix comparison: {emb_manual_1 == emb_manual_2}") 
# Returns False (Correct: These are distinct task-specific vectors)

Relevant Logs/Tracebacks

Standard task_type comparison: True
Manual prefix comparison: False