Last reviewed: August 26, 2026.

Direct answer

A CometAPI embedding fallback is safe to use with an existing vector index only when it preserves the index’s complete vector-space contract. A successful response and a matching vector length are not enough. Verify the resolved model identity, output dimensions, normalization policy, distance metric, task or instruction format, input preprocessing, and destination index.

For ordinary vector retrieval without a separately validated mapping between embedding spaces, use the same embedding model and configuration for documents and queries. This follows the practical rule in the Microsoft guidance for generating search embeddings : accurate results depend on using the same model for indexing and querying. The CometAPI embeddings documentation likewise identifies model and dimension consistency as an index requirement.

If a fallback candidate has a different contract, do not put its vectors into the primary index and do not query the primary index with them. Route it only to a separate, complete index built from that candidate’s embedding pipeline. If no compatible index exists, use an explicitly approved degraded retrieval mode or fail the operation cleanly.

Who this is for

This is for platform engineers, retrieval engineers, and on-call teams operating RAG, semantic-search, clustering, or recommendation systems through CometAPI or another multi-model gateway. It applies to both query-time embedding calls and ingestion pipelines that write document vectors.

The central risk differs from a text-generation fallback. A completion can be inspected as an independent response. An embedding is useful only in relation to other vectors produced under a compatible contract. That dependency makes a seemingly successful fallback capable of causing silent ranking damage.

Key takeaways

  • Treat an embedding space as a versioned data schema, not as a generic array of numbers.
  • Require an exact contract match before a fallback can read from or write to an existing index.
  • Matching dimensions prove only that two vectors have the same length; they do not prove semantic compatibility.
  • Keep an incompatible fallback in a dedicated index populated by the same model, settings, and preprocessing used for its queries.
  • Validate batch cardinality, finite values, dimensions, and routing before accepting a fallback response.
  • Record decisions and contract fingerprints without logging prompts, document text, full vectors, or response bodies.
  • Test retrieval quality before an incident and canary the route before increasing traffic.

Sources checked

  • The CometAPI Embeddings API documentation describes the OpenAI-compatible embedding route, model selection, response shape, batch input, common failures, and retry guidance.
  • The OpenAI vector embeddings guide explains that an embedding is a floating-point vector, ties requests to a model name, and documents controls over vector size for current embedding models.
  • The Google Gemini embeddings documentation shows that embedding behavior includes task-specific query and document formatting, and says those task conventions must be used consistently.
  • The Microsoft Learn embedding guide recommends using the same embedding model for indexing and querying, and discusses normalization, chunking, testing, and iteration.
  • The Qdrant collection documentation states that vectors in one collection share dimensionality and a comparison metric, while named vectors may have separate size and metric contracts.

Contract details to verify

Treat the vector space as a versioned schema

Keep a machine-readable contract beside each index. The precise fields will vary by stack, but a useful minimum looks like this:

contract_id: catalog-search-v3
model_id: embedding-model-a
model_revision: pinned-release-a
dimensions: 1536
numeric_format: float
normalization_policy: unit-length
distance_metric: cosine
task_profile: document-search-v2
preprocessing_version: chunk-v4
index_target: catalog-a

The contract should describe what was actually used to build the index, not merely what a deployment manifest intended to use. Store the resolved model identity where possible. If a friendly alias can change its target, alias resolution belongs in deployment evidence. The site’s model-alias drift controls provide a complementary rollout check.

Dimensions are a hard structural constraint. OpenAI’s documentation shows that vector size can vary by model and configuration, while Qdrant requires a defined size for each vector field. A length check therefore belongs on every fallback response. It is necessary, but it is not sufficient: two unrelated encoders can return equally long arrays whose coordinates represent different learned relationships.

Normalization and metric must also agree. Qdrant documents cosine search as dot product over normalized vectors and performs normalization on upload for that mode. Other storage and application paths may behave differently, so the gateway should record whether vectors arrive normalized, whether the store normalizes them, and which metric the index applies. Do not infer those facts from vector length.

Task formatting is part of the space as well. Google’s current Gemini guidance distinguishes asymmetric retrieval formatting for queries and documents from symmetric formats used for classification or similarity. It explicitly calls for consistent task usage. Changing a prefix, task type, title treatment, or document template during fallback can alter retrieval behavior even when the model and dimensions appear unchanged.

Finally, pin preprocessing. Chunk boundaries, text cleanup, title injection, language handling, and truncation rules determine the content represented by each stored vector. A fallback that silently uses a different chunker may satisfy the database schema while changing the retrieval unit.

Certify fallback states before an incident

Define three states for every candidate route:

  1. Same-space certified: The candidate resolves to the approved model contract, returns the expected shape, and passes retrieval tests against the primary index.
  2. Isolated-space certified: The candidate has a different contract but has its own fully populated index and passes tests against that index.
  3. Unavailable for fallback: The candidate lacks a compatible index, a complete contract, or sufficient retrieval evidence.

Do not promote a candidate from the third state during an outage merely because a probe returns HTTP 200. Before production use, run a stable set of representative queries, compare expected relevant documents, inspect top-result changes, and set explicit acceptance bounds. Include short queries, long queries, multilingual inputs where applicable, empty or malformed inputs, and the largest permitted batch.

Happy-path operator workflow

  1. A primary embedding call encounters an approved transient condition. CometAPI’s documentation identifies rate limiting and server-side failures as retryable with backoff, while request or configuration problems must be corrected before retrying.
  2. The router reads the index contract and selects only a pre-certified candidate. It does not choose an arbitrary model merely because that model supports the embeddings endpoint.
  3. The router compares the resolved candidate fingerprint with the planned route: model identity, dimensions, normalization, metric, task profile, preprocessing version, and index target.
  4. It sends one bounded canary request. The response must contain one vector per input item, preserve the expected item mapping, contain finite numeric values, and match the configured dimensions.
  5. For a query operation, it searches only the index named in the candidate contract. For ingestion, it writes only to that contract’s destination.
  6. A known canary query is checked for plausible expected results before traffic increases. The router then ramps gradually while watching fallback rate, response errors, vector validation failures, empty-result rate, and retrieval-quality indicators.
  7. The operator records the decision and keeps the attempt within the user action’s retry and latency budgets.

Error-path operator workflow

If any contract field or response invariant differs, stop before the vector store. Do not pad, truncate, concatenate, or relabel the vector to make it fit. Mark the candidate incompatible for that target and choose one of three explicit outcomes:

  • Route to the candidate’s already populated, isolated index.
  • Use an approved degraded path, such as lexical retrieval or a deliberately configured hybrid mode that does not consume the incompatible vector.
  • Return a controlled failure when retrieval correctness is more important than partial availability.

For a batch response with the wrong item count, invalid numbers, or uncertain item mapping, reject the entire batch unless the application has a proven record-level reconciliation design. Never allow unverified records to leak into the main index. Capture the choice using the site’s pattern for fallback decision logs .

Log the decision without logging the content

A sanitized event can contain operational fields like these:

event: embedding_fallback_decision
request_id: req-7f3a
operation: query_embedding
primary_model_id: embedding-model-a
fallback_model_id: embedding-model-b
contract_id: catalog-search-v3
index_target: catalog-b
dimensions_expected: 1536
dimensions_observed: 1536
distance_metric: cosine
normalization_policy: unit-length
task_profile: document-search-v2
attempt_number: 2
http_status: 503
decision: route_to_isolated_index
reason_code: primary_transient_failure
latency_ms: 428
input_size_bytes: 842
input_digest_prefix: 9c21a4d8

Omit raw query text, source documents, complete vectors, request and response headers, full response bodies, and direct user identifiers. A short internal request ID and a limited digest prefix can support correlation without turning the reliability log into a copy of user content.

Failure modes

A dimension mismatch causes a hard failure

The fallback returns a vector whose length differs from the vector field’s configured size. A client-side validator or the database rejects it. This is visible and comparatively easy to contain, provided validation occurs before a partial batch is written.

Equal dimensions hide an incompatible model

A more dangerous fallback returns the expected number of floats but uses a different learned coordinate system. The database accepts the query or write, and the result set can still look plausible. Relevant documents may move down the ranking without producing an API error. Model identity and retrieval tests, rather than length alone, catch this class of failure.

Normalization and metric drift alter scores

A primary path may produce unit-length vectors for cosine search while a fallback produces vectors with a different norm or expects another metric. Depending on where normalization occurs, score distributions and thresholds can shift. Record the policy on both sides of the vector-store boundary.

Task formatting changes between indexing and querying

Documents may have been embedded with a retrieval-specific document format while fallback queries omit the corresponding query instruction or use a similarity task. Google’s task guidance makes this a concrete contract concern. The response remains structurally valid, but semantic alignment weakens.

An alias changes without an index migration

An embedding alias can resolve to a different implementation while the index still contains vectors from the previous target. Query traffic then crosses spaces even though the configured name has not changed. Pin or record the resolved model and require recertification when it changes.

A batch is only partially trustworthy

Embedding APIs can accept multiple inputs, and CometAPI documents one response vector for each input item. A timeout, malformed response, unexpected count, or mapping bug can associate a vector with the wrong document. Validate cardinality and item mapping before any write, and make ingestion record IDs idempotent.

Fallback writes contaminate the primary index

During an ingestion incident, a router may send only failed records to a different model while continuing to write into the same vector field. The index then becomes a mixture of spaces. Recovery requires identifying and re-embedding affected records; changing the query model cannot repair mixed stored data.

Retry logic amplifies a contract error

Repeatedly retrying an invalid model, input, or dimension setting adds load without creating a compatible vector. Separate transient service failures from deterministic contract failures. Backoff does not make a semantic mismatch safe.

FAQ

Does HTTP 200 mean the fallback is compatible?

No. It means the endpoint returned a successful protocol response. Compatibility requires the expected response cardinality and dimensions plus a matching, certified vector-space contract and the correct index route.

Can two models share an index if they return the same dimensions?

Do not assume so. Equal dimensions satisfy an array-size requirement, not semantic alignment. Use the same model and configuration for indexing and querying unless a separately validated system provides a proven mapping and a retrieval test demonstrates acceptable behavior.

Can I trim or pad a fallback vector?

No. Arbitrary trimming or padding makes an array fit a field but does not align its learned coordinates. A provider’s documented dimension control is different: it must be deliberately configured, tested, and used consistently across the entire index and its queries.

Does the vector database solve normalization automatically?

It depends on the configured store and metric. Qdrant documents automatic normalization for cosine vectors, while Microsoft still recommends considering vector normalization as part of search design. Record the actual behavior instead of assuming that every database or metric handles it identically.

Can named vectors replace a separate collection?

They can provide isolation within one collection when the vector database supports independent named-vector contracts. Qdrant allows named vectors with their own sizes and metrics. Each named space still needs to be populated from the corresponding embedding pipeline, and queries must explicitly target the correct name.

What if a different model is the only healthy option?

It is usable only if a matching corpus index already exists and has been certified. Generating a fallback query vector does not make the primary corpus vectors compatible. Without that index, select a predefined degraded mode or return a controlled error.

How should retrieval quality be tested?

Maintain representative queries with expected relevant documents. Compare the primary and candidate routes using the same corpus snapshot and application filters. Review missed expected documents, top-result changes, empty results, score-distribution shifts, and latency. Then shadow-test the fallback route before exposing it to user traffic.

Reader next step

Inventory every production vector index and write down its model, resolved revision, dimensions, normalization policy, metric, task format, preprocessing version, and destination. Label every fallback candidate as same-space certified, isolated-space certified, or unavailable. Then exercise both the happy path and a forced mismatch in staging, confirming that incompatible vectors are rejected before the store.

If you need one API surface for embedding-capable models while keeping those routing controls in your application, Start with CometAPI . Build the contract check first, create a dedicated index for any genuinely different space, and promote the route only after retrieval evidence supports it.