EmbeddingGemma retrieval: query and document prompts must stay distinct

EmbeddingGemma retrieval uses different input roles for a query and a source document, so a shared text-encoding call needs an explicit prompt contract. Preserve that distinction when moving an index between libraries or rebuilding it with another wrapper.

Read the model’s input convention

The author model card documents task-specific query prompts and document prompts carrying a title. These are part of the representation path, not optional display decorations. A plain question and a correctly prepared query need not create interchangeable vectors. Likewise, adding a title only when querying cannot supply document context that was absent during indexing. Keep the exact serialized input with a small diagnostic sample.

Avoid accidental double prompting

A framework can already apply a configured query or document prefix. Manually adding the same prefix before calling its role-specific method can therefore change the input twice. Inspect what reaches the tokenizer instead of judging from the outer application string. Preserve the wrapper version and selected prompt name. A successful embedding response with the expected dimension does not establish that the model received the intended task.

Keep document titles intentional

The official EmbeddingGemma documentation defines the model’s intended embedding use cases. For a corpus with reliable titles, test whether that source context helps the actual questions. Missing titles need a deliberate representation, not an arbitrary filename inserted by an importer. A document title and a query instruction serve different roles. Preserve their provenance separately so a future parser change does not silently alter every stored document representation.

Input role	Diagnostic field
Query	Selected retrieval task and final query string
Document	Source title and final document string
Wrapper	Whether it applies prompts automatically

Test asymmetric search explicitly

The Sentence Transformers semantic-search guide distinguishes query and document encoding for asymmetric retrieval. Build an illustrative fixture with a short question and longer answer-bearing passage. Compare the intended role-specific route against an intentionally unprompted control. The control can identify a configuration difference; it is not evidence that removing prompts is universally better. Keep original vectors and ranks so preprocessing errors can be separated from index-search behavior.

Treat a prompt change as representation migration

When document preprocessing changes, decide which stored embeddings need regeneration. Replacing only query preparation can leave incompatible old document vectors in the same collection. Conversely, adding another prompt to an already correct wrapper may degrade a previously valid profile. Label the generation of each vector set with model revision and input convention rather than reusing a generic “EmbeddingGemma” tag for all variants.

Preserve an executable specification of the input

Save representative raw text, title metadata, final serialized input and encoded role. Include a missing-title example and an ordinary retrieval question. That small artifact is easier to audit than a large index whose preprocessing history is unknown. An accepted setup should demonstrate compatible query/document representations for its corpus, without converting the model card or a benchmark average into a guarantee about every language or domain.