Embedding configuration
Embeddings power Qry's RAG context (Retrieval-Augmented Generation): the system that surfaces relevant snippets from uploaded files, workspace memory, and other text-heavy artifacts at query time. The choice of embedding model affects what content is recallable, with what fidelity, and at what cost.
Two embedding types
| Type | Model | Chunk size | Use for |
|---|---|---|---|
| Text-only | gemini-embedding-001 | 2,000 chars | PDFs, Markdown, plain text, anything where layout doesn't matter |
| Multimodal | multimodalembedding@001 | 900 chars | PDFs with images, screenshots, diagrams — anything where pixels matter |
The chunk size differs because multimodal embeddings have a smaller per-vector context. A workspace using multimodal embeddings gets more, smaller chunks for the same source documents.
You cannot mix types within one context
A workspace's RAG context is either text-only or multimodal — never both. A database constraint enforces this: cross-type similarity scores are mathematically meaningless (different vector spaces), so allowing the mix would surface garbage on retrieval.
Pick one per workspace. Most tenants default to text-only because the cost is lower and the quality is adequate for the typical workspace content.
Which provider embeds text
Text embeddings use whatever AI credentials the installation already has. Set it in Admin > System Configuration > AI Models > Text Embedding Provider:
| Option | Needs | Model |
|---|---|---|
| Automatic (default) | see the order below | |
| Azure AI Foundry | Foundry enabled and Embedding Deployment set | your deployment (azure/<deployment>) |
| Gemini API key | Gemini API key | gemini-embedding-001 |
| Vertex AI | Use Vertex AI and a project (Vertex AI Project ID, or the project in GCP Credentials); authenticates as the installation's Google identity (the service-account JSON in GCP Credentials, or the pod's workload identity); Vertex AI Region must serve gemini-embedding-001 | gemini-embedding-001 |
| OpenAI | OpenAI API key | openai/text-embedding-3-small |
Every option produces 768-dimensional vectors, the width of the database column, so none needs a migration.
Automatic picks the first that is configured: Azure AI Foundry with an embedding deployment, then the Gemini API key, then Vertex AI, then the OpenAI key (not used when a custom OpenAI API Base URL is set, since such an endpoint may not serve the embedding model). An installation that worked before keeps the provider it had. The Gemini key and Vertex AI run the same model, so moving between them needs no re-indexing; Azure and OpenAI use different models.
A service-account JSON alone is enough only for Vertex AI: it does not work with the Gemini API key option, which needs an AI Studio key.
If nothing is configured there are no text embeddings, and uploads that need them fail with a message saying so. Multimodal embeddings (multimodalembedding@001) are separate and need Google Cloud credentials and a project in GCP Credentials.
The chunk size and the default embedding type are fixed by the product; the type is chosen per workspace (next section).
Check that it works
In the AI Models settings, use the embeddings test (POST /api/admin/system-config/ai-models/embeddings/test) to make one real embedding call with the active provider. It answers with the provider, the model, whether it worked and the error if not; GET .../ai-models/embeddings/status reads the same without calling the provider and lists the models your existing content was indexed with. Failures during real use appear in Admin > System > Platform health under embeddings, and on installations with AI turned off nothing is called.
Changing provider
Vectors from different models are not comparable. Qry records the model on each context, and when the active model differs from the one a context was indexed with it refuses to search that context (it returns nothing and logs the reason) instead of ranking noise. Switching between Azure, OpenAI and Gemini/Vertex therefore means re-indexing the content that was already uploaded. Automatic selection never moves an installation that already has a configured provider.
Configuring per-workspace
Each workspace can override the default. Workspace settings > Files > Embedding type.
Once a workspace has indexed even one file, the type is locked. Switching it would invalidate all existing embeddings — Qry doesn't auto-reindex; you'd have to delete the workspace and recreate it.
RETRIEVAL_DOCUMENT vs RETRIEVAL_QUERY
Gemini's embedding API takes a task_type parameter that affects vector orientation. Qry uses two:
RETRIEVAL_DOCUMENT— when indexing source files. Optimised for being-found.RETRIEVAL_QUERY— when embedding the user's chat input to retrieve against the index. Optimised for finding.
Mixing these (e.g. embedding a query as a document) drops retrieval quality silently. Qry handles this correctly internally — the gotcha is only relevant if you're customising the embedding pipeline.
The Gemini API param gotcha
Gemini's embedding API is contents (plural), not content. Easy to miss when reading provider docs. Qry's wrapper enforces contents correctly. Only relevant if you're calling the API directly.
Restart workers after config changes
This is the operational gotcha. The embedding service is loaded once per Celery worker on startup. Config changes (provider, model, chunk size, task_type) do not take effect until the worker restarts.
After making config changes:
kubectl rollout restart deployment/celery-worker -n qry-app
Or for in-flight queries to bleed out gracefully:
kubectl scale deployment/celery-worker --replicas=0 -n qry-app
# wait for pods to drain
kubectl scale deployment/celery-worker --replicas=N -n qry-app # whatever your normal count is
If you forget the restart, you'll see the old behaviour and assume the config didn't save. It saved; the worker hasn't picked it up.
Failures are never stored as zero vectors
Older versions stored a vector of zeros when the embedding call failed, so indexing looked successful while retrieval was dead. Now a failure stops the indexing of that file (it is marked as failed with the reason), memory writes keep the entry without an embedding, and the failure is logged and shown in Platform health. A provider that answers with zeros or a wrong width is treated as a failure. Content indexed by an older version while embeddings were failing may still hold zero vectors: re-index it.
Costs
Both embedding models charge per 1k tokens of input. Multimodal is more expensive per call. For a tenant with heavy file ingestion, expect embedding costs to be a meaningful line item — sample your usage and forecast before scaling.
Common issues
Files marked "Indexing" forever.
Either the embedding worker is stuck (check Celery health) or the API is returning errors silently. Look at worker logs for embedding error patterns.
Search recall feels worse after I changed the model. You changed model but didn't reindex existing files. New uploads are searched with the new model; old uploads still have the old model's vectors. Cross-model similarity is poor — same problem as cross-type.
Test query returns identical content for every prompt. Probably zero vectors stored by an older version. Run the embeddings test, fix what it reports, restart the workers and re-index the content.
Only Vertex AI (or only Azure, or only OpenAI) and RAG, memory or meaning-based search return nothing.
Run the embeddings test. With Text Embedding Provider on Automatic it should report the provider you have; if it says none is configured, check Use Vertex AI and the project, the Azure embedding deployment, or the OpenAI key. For Vertex AI also check that the region serves gemini-embedding-001.
Workspace switched from text-only to multimodal but no images are recallable. Switch only affects new uploads. Existing documents stay text-only-embedded. Either delete-and-reupload, or accept the mixed reality (which violates the no-mix rule — the database constraint will likely have prevented this).
Indexing speed degrades over time. The embedding API has rate limits. Qry batches and back-offs, but at scale you'll hit a ceiling. Either bump the API quota with Google or shard across multiple Gemini projects.
See also
- LLM providers — chat / reasoning models, separate from embeddings.
- Shared files and memory — what users see from the embedding pipeline.