Search results seem semantically wrong even though the embedding model is known to work well. What layers would you check to isolate the problem?

When the model is fine but the results are wrong, the problem is almost always in the pipeline between the model and the search result. The first layer to check is the distance metric. If the model expects dot product and the collection uses cosine, the ranking changes because cosine normalizes the vectors. For most modern sentence embedding models this difference is small, but for some it is significant. If the model expects cosine and the collection uses Euclidean, the results can be very wrong because Euclidean is not bounded and does not have the same ordering. The second layer is normalization. Cosine similarity requires vectors to be normalized to unit length; if the client normalizes before upsert but not before query, or vice versa, the results are inconsistent. Some models output normalized vectors and some do not, and the pipeline must be consistent about whether normalization happens. The third layer is the vector field. In a multi-vector collection, querying the wrong field (or omitting the field and getting a default) produces results that are semantically unrelated to the query. The fourth layer is data staleness or duplication: if the collection has old and new embeddings for the same content, or if a re-embedding job partially completed, the index contains a mix of representations and the results reflect that mix.

The mechanism that makes this hard to diagnose is that all of these produce plausible-looking results. The search does not error, it returns points ranked by vector similarity - it is just that the similarity is computed in the wrong space or against the wrong vectors. The systematic approach is to isolate each layer. Start with a single query vector and a small set of known points whose expected ranking you can compute by hand. Compute the dot product, cosine similarity, and Euclidean distance between the query and each point in your application, and compare the ordering with what Qdrant returns. If the orderings differ, the metric or the normalization is the cause. If the orderings match, the problem is elsewhere. Then check the vector field: retrieve the vector from a point by ID and verify it matches what you would get by embedding the original text. Then check for duplicates and stale points by scrolling through the collection and looking for repeated IDs or unexpected payloads. This is tedious but it is the only way to isolate the cause with confidence.

The trade-off in debugging is between a quick check of the most common causes and a thorough investigation. The most common causes - metric mismatch, normalization inconsistency, and wrong field - account for the majority of cases and can be checked in minutes. If those are clean, the investigation becomes more involved and should be scoped to a small set of queries and points so that you can reason about the expected results. The common mistake is to assume the model is at fault and start looking at model quality, when the model is the one component that is known to work. The second mistake is to change multiple things at once - re-normalize, change the metric, rebuild the index - which destroys the ability to isolate the cause. The third mistake is to trust that the ingest pipeline is consistent because it worked in development; production often has different data, different clients, or a partially completed migration. Version note: the distance metric options and the behavior of normalization have been stable, but the query API has changed - query_points in qdrant-client 1.10+ replaced the older search API, and the way a named vector is selected in the query has a different shape. If you are debugging against an older version, the field selection semantics may differ.

Version-dependent: the distance metric options and their semantics have been stable, but the retrieval API and the way a vector field is specified have changed. The query_points API in qdrant-client 1.10+ uses using= to select a named vector; earlier versions had different shapes. Quantization behavior and rescoring settings have also evolved, so if the collection uses quantization, verify the rescoring configuration before concluding the metric is wrong.