LeetLLM
My PlanLearnGlossaryTracksPracticeBlog
LeetLLM

Your go-to resource for mastering AI & LLM systems.

Product

  • Learn
  • Glossary
  • Tracks
  • Practice
  • Blog
  • RSS

Legal

  • Terms of Service
  • Privacy Policy

© 2026 LeetLLM. All rights reserved.

All Topics
Your Progress
0%

0 of 158 articles completed

🛠️Computing Foundations0/9
Git, Shell, Linux for AIDocker for Reproducible AIPython for AI EngineeringNumPy and Tensor ShapesCUDA for ML TrainingMPS & Metal for ML on MacData Structures for AISQL and Data ModelingAlgorithms for ML Engineers
📊Math & Statistics0/8
Gradients and BackpropVectors, Matrices & TensorsLinear Algebra for MLAdam, Momentum, SchedulersProbability for Machine LearningStatistics and UncertaintyDistributions and SamplingHypothesis Tests, Intervals, and pass@k
📚Preparation & Prerequisites0/13
Neural Networks from ScratchCNNs from ScratchTraining & BackpropagationSoftmax, Cross-Entropy & OptimizationRNNs, LSTMs, GRUs, and Sequence ModelingAutoencoders and VAEsThe Transformer Architecture End-to-EndLanguage Modeling & Next TokensFrom GPT to Modern LLMsPrompt Engineering FundamentalsCalling LLM APIs in ProductionFirst AI App End-to-EndThe LLM Lifecycle
🧮ML Algorithms & Evaluation0/11
Linear Regression from ScratchLogistic Regression and MetricsDecision Trees, Forests, and BoostingReinforcement Learning BasicsValidation and LeakageClustering and PCACore Retrieval AlgorithmsDecoding AlgorithmsExperiment Design and A/B TestingPyTorch Training LoopsDataset Pipelines and Data Quality
📦Production ML Systems0/6
Feature Engineering for Production MLBatch and Streaming Feature PipelinesGradient Boosted Trees in ProductionRanking and Recommendation SystemsForecasting and Anomaly DetectionMonitoring Predictive Models
🧪Core LLM Foundations0/8
The Bitter Lesson & ComputeBPE, WordPiece, and SentencePieceStatic to Contextual EmbeddingsPerplexity & Model EvaluationFile Ingestion for AIChunking StrategiesLLM Benchmarks & LimitationsInstruction Tuning & Chat Templates
🧰Applied LLM Engineering0/24
Dimensionality Reduction for EmbeddingsCoT, ToT & Self-Consistency PromptingFunction Calling & Tool UseMCP & Tool Protocol StandardsContext EngineeringPrompt Injection DefenseResponsible AI GovernanceData Labeling and Human FeedbackEvaluating AI AgentsProduction RAG PipelinesHybrid Search: Dense + SparseReranking and Cross-Encoders for RAGRAG Evaluation for Reliable AnswersLLM-as-a-Judge EvaluationBias & Fairness in LLMsHallucination Detection & MitigationLLM Observability & MonitoringExperiment Tracking with MLflow and W&BPrompt Optimization with DSPyModel Versioning & DeploymentSemantic Caching & Cost OptimizationLLM Cost Engineering & Token EconomicsModel Gateways, Routing, and FallbacksDesign an Automated Support Agent
🎓Portfolio Capstones0/8
Capstone: Delivery ETA PredictionCapstone: Product RankingCapstone: Demand ForecastingCapstone: Image Damage ClassifierCapstone: Production ML PipelineCapstone: Document QACapstone: Eval DashboardCapstone: Fine-Tuned Classifier
🧠Transformer Deep Dives0/8
Sentence Embeddings & Contrastive LossEmbedding Similarity & QuantizationScaled Dot-Product AttentionVision Transformers and Image EncodersPositional Encoding: RoPE & ALiBiLayer Normalization: Pre-LN vs Post-LNMechanistic InterpretabilityDecoding Strategies: Greedy to Nucleus
🧬Advanced Training & Adaptation0/15
Scaling Laws & Compute-Optimal TrainingPre-training Data at ScaleBuild GPT from Scratch LabContinued Pretraining for Domain ShiftSynthetic Data PipelinesSupervised Fine-Tuning PipelineMixed Precision TrainingDistributed Training: FSDP & ZeROLoRA & Parameter-Efficient TuningReward Modeling from Preference DataRLHF & DPO AlignmentConstitutional AI & Red TeamingRLVR & Verifiable RewardsKnowledge Distillation for LLMsModel Merging and Weight Interpolation
🤖Advanced Agents & Retrieval0/16
Vector DB Internals: HNSW & IVFAdvanced RAG: HyDE & Self-RAGGraphRAG & Knowledge GraphsRAG Security & Access ControlStructured Output GenerationReAct & Plan-and-ExecuteGuardrails & Safety FiltersCode Generation & SandboxingComputer-Use / GUI / Browser AgentsHuman-in-the-Loop Agent ArchitectureAI Coding Workflow with AgentsAgent Memory & PersistenceAgent Failure & RecoveryRecursive Language Models (RLM)Multi-Agent OrchestrationCapstone: Production Agent
⚡Inference & Production Scale0/19
Inference: TTFT, TPS & KV CacheMulti-Query & Grouped-Query AttentionKV Cache & PagedAttentionPrefix Caching and Prompt CachingFlashAttention & Memory EfficiencyContinuous Batching & SchedulingScaling LLM InferenceModel Parallelism for LLM InferenceModel Quantization: GPTQ, AWQ & GGUFLocal LLM DeploymentSLM Specialization & Edge DeploymentSpeculative DecodingLong Context Window ManagementMixture of Experts ArchitectureMamba & State Space ModelsReasoning & Test-Time ComputeAdvanced MLOps & DevOps for AIGPU Serving & AutoscalingA/B Testing for LLMs
🏗️System Design Capstones0/9
Content Moderation SystemCode Completion SystemMulti-Tenant LLM PlatformLLM-Powered Search EngineVision-Language Models & CLIPMultimodal LLM ArchitectureDiffusion Models: Images & TextReal-Time Voice AI AgentReasoning & Test-Time Compute
🎤AI Lab Interviewing0/4
AI Lab Coding Interview: Python SystemsAI Lab System Design InterviewAI Lab Behavioral InterviewAI Lab Technical Presentation
Back to Topics
LearnTransformer Deep DivesSentence Embeddings & Contrastive Loss
📐HardEmbeddings & Vector Search

Sentence Embeddings & Contrastive Loss

Learn how contrastive losses train sentence embeddings, why hard negatives matter, and how retrieval systems combine bi-encoders, rerankers, and dimension tradeoffs.

38 min read
Learning path
Step 88 of 158 in the full curriculum
Capstone: Fine-Tuned ClassifierEmbedding Similarity & Quantization

In the production-agent capstone, document_qa_v2 found api-key-rotation-v3 before the agent drafted an answer about a credential rollover. That contract deliberately hid one important mechanism: how did a technical passage become a good candidate for the question in the first place?

A sentence embedding maps a query or passage to one fixed-width vector. A retriever can then find passages near a developer question even when wording changes:

QueryPassage that should rank near itTempting non-match
"How do I rotate an API key?""Create a replacement key, deploy it, then revoke the old key.""A billing export token expired yesterday."

Contrastive learning shapes that vector space. The agent still needs evidence and authorization gates; embeddings decide which text gets considered before those gates run.

From word embeddings to sentence embeddings

Word embeddings gave individual tokens numerical coordinates. Retrieval needs one vector for an entire query or docs passage. A sentence encoder compresses variable-length text into a fixed-size representation whose neighborhood ordering is useful for the task.

Averaging context-free word vectors is a useful baseline, but it loses order and context. Don't confuse that baseline with mean pooling contextual token outputs inside a trained sentence encoder: pooling specifies how to produce one vector; the training objective determines whether its geometry supports retrieval. A common objective is contrastive learning, which rewards a relevant pair for scoring above irrelevant candidates.


Naive approaches (and why they fail)

Mean pooling of word embeddings

A simple approach to creating a sentence embedding is to calculate the word vectors for each token in the sentence and then average them. This naive baseline is fast but loses important structural information. This function uses a tiny local vector table so you can run the baseline and see exactly what it throws away:

mean-pooling-of-word-embeddings.py
1word_vectors: dict[str, tuple[float, float, float]] = { 2 "compiler": (0.9, 0.1, 0.0), 3 "calls": (0.8, 0.2, 0.1), 4 "linker": (0.7, 0.1, 0.2), 5 "build": (0.1, 0.9, 0.2), 6 "failed": (0.2, 0.8, 0.1), 7} 8 9def mean_pool( 10 sentence: str, 11 vectors: dict[str, tuple[float, float, float]], 12) -> tuple[float, float, float]: 13 tokens = [token.lower() for token in sentence.split()] 14 token_vectors = [vectors[token] for token in tokens if token in vectors] 15 16 if not token_vectors: 17 width = len(next(iter(vectors.values()))) 18 return tuple(0.0 for _ in range(width)) 19 20 return tuple( 21 sum(vector[dim] for vector in token_vectors) / len(token_vectors) 22 for dim in range(len(token_vectors[0])) 23 ) 24 25pooled_a = mean_pool("compiler calls linker", word_vectors) 26pooled_b = mean_pool("linker calls compiler", word_vectors) 27 28print("A:", tuple(round(value, 3) for value in pooled_a)) 29print("B:", tuple(round(value, 3) for value in pooled_b)) 30print("Same vector:", pooled_a == pooled_b)
Output
1A: (0.8, 0.133, 0.1) 2B: (0.8, 0.133, 0.1) 3Same vector: True

The final line is the problem: both sentences produce the same vector because averaging ignores order.

Problems

  • Ignores word order: "compiler calls linker" and "linker calls compiler" have identical embeddings because the sum of vectors is commutative (A+B=B+AA+B = B+AA+B=B+A), even though the sentences reverse which component calls the other.
  • Common-word dilution: Frequent words and boilerplate phrasing can wash out the signal from rare, informative tokens.
  • No context: Polysemous words like "port" (network socket vs. code migration) get averaged into a single messy vector.

[CLS] token from BERT

Using the [CLS] (Classification) token from BERT (Bidirectional Encoder Representations from Transformers) directly as a sentence embedding isn't a sound retrieval baseline. Reimers & Gurevych (2019) showed that BERT's paired-input architecture is impractical for large semantic search and introduced SBERT so independently encoded sentence vectors could be compared with cosine similarity.[1]Reference 1Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks.https://arxiv.org/abs/1908.10084 A pretrained task token hasn't been trained to make nearest-neighbor distance a relevance score.

The anisotropy problem

Contextual token representations aren't isotropic in every layer: their directions aren't spread evenly through the available space.[2]Reference 2How Contextual are Contextualized Word Representations? Comparing the Geometry of BERT, ELMo, and GPT-2 Embeddings.https://arxiv.org/abs/1909.00512 This anisotropy can give sentence embeddings from an untuned encoder poorly discriminative geometry. Many API-doc passages can all point toward one generic "technical docs" direction, so their cosine scores look high even when they answer different questions. Contrastive objectives can improve this geometry by rewarding aligned positives while penalizing competing candidates.

Two-dimensional intuition for embedding anisotropy and contrastive geometry. Before training, API-key, KMS-key, and billing-doc vectors occupy a narrow 12-degree cone; an unrelated KMS-key vector only 6 degrees from an API-key query has cosine 0.995. After contrastive training, API-key positives remain 6 degrees apart with cosine 0.995, while the KMS-key cluster is 120 degrees from the API-key query with cosine negative 0.500. Billing docs form a third separated direction. The angles are an illustrative geometric example, not benchmark measurements. Two-dimensional intuition for embedding anisotropy and contrastive geometry. Before training, API-key, KMS-key, and billing-doc vectors occupy a narrow 12-degree cone; an unrelated KMS-key vector only 6 degrees from an API-key query has cosine 0.995. After contrastive training, API-key positives remain 6 degrees apart with cosine 0.995, while the KMS-key cluster is 120 degrees from the API-key query with cosine negative 0.500. Billing docs form a third separated direction. The angles are an illustrative geometric example, not benchmark measurements.
Raw contextual vectors can bunch into one generic direction, while contrastive fine-tuning creates separable semantic neighborhoods that make nearest-neighbor search meaningful.

Contrastive learning for sentence embeddings

The core idea

The goal of contrastive learning is simple: reshape the embedding space so that sentences with similar meaning land close to each other, while unrelated sentences are pushed apart.

Before formalizing it, recall what "close" means here. Cosine similarity measures how aligned two vectors point (their angle), ignoring their length. For two unit vectors (length 1), it's their dot product. A value of +1 means same direction, 0 means orthogonal directions, and a negative value means opposing directions. None of those numbers proves semantic identity or irrelevance by itself; only an evaluated embedding model makes cosine ranking useful. The next lesson studies this scoring rule in detail.

Contrastive training teaches the model to:

  • Pull embeddings of similar sentences toward each other (high cosine similarity)
  • Push embeddings of dissimilar sentences away (low cosine similarity)

SimCSE (Simple Contrastive Learning of Sentence Embeddings)[3]Reference 3SimCSE: Simple Contrastive Learning of Sentence Embeddings.https://arxiv.org/abs/2104.08821 demonstrated an unusually small self-supervised construction: pass the same sentence through the encoder twice while dropout supplies different noisy views, then treat those views as a positive pair. Wang and Isola's analysis gives useful vocabulary for the resulting geometry: alignment asks whether positives are close, and uniformity asks whether normalized representations avoid crowding into a small region of the hypersphere.[4]Reference 4Understanding Contrastive Representation Learning through Alignment and Uniformity on the Hyperspherehttps://arxiv.org/abs/2005.10242 E5 later trained single-vector text embeddings contrastively from a large weakly supervised pair corpus.[5]Reference 5Text Embeddings by Weakly-Supervised Contrastive Pre-training.https://arxiv.org/abs/2212.03533

The batch-ranking objective used below is commonly called InfoNCE: for one anchor sentence, the model should rank the true match above every other candidate in the batch.

Contrastive ranking chart for one anchor query, how do I rotate an API key. The relevant passage, Replace old API token, ranks first with cosine similarity 0.91. The lexical hard negative, Rotate KMS key material, scores 0.42, giving a positive margin of 0.49 and strong downward training pressure. The unrelated easy negative, GPU driver matrix, scores 0.11, giving a margin of 0.80 and weak downward pressure. Training raises the positive score and focuses most negative pressure on the confusing hard negative. Contrastive ranking chart for one anchor query, how do I rotate an API key. The relevant passage, Replace old API token, ranks first with cosine similarity 0.91. The lexical hard negative, Rotate KMS key material, scores 0.42, giving a positive margin of 0.49 and strong downward training pressure. The unrelated easy negative, GPU driver matrix, scores 0.11, giving a margin of 0.80 and weak downward pressure. Training raises the positive score and focuses most negative pressure on the confusing hard negative.
Contrastive training turns a batch into a ranking problem: the true match should outrank every in-batch negative for the same anchor query.
Diagram showing Approved query-passage pairs, Shared encoder one vector per text, Similarity matrix positive on diagonal, and InfoNCE loss rank true passage first. Diagram showing Approved query-passage pairs, Shared encoder one vector per text, Similarity matrix positive on diagonal, and InfoNCE loss rank true passage first.
Approved query-passage pairs, Shared encoder one vector per text, Similarity matrix positive on diagonal, and InfoNCE loss rank true passage first.

InfoNCE loss

Contrastive learning matches a developer question to the right API-doc passage while pushing away lookalike but irrelevant docs. You want the matching pair close together and every non-match farther away. InfoNCE mathematically formalizes this push-and-pull dynamic.

Before looking at the formula, walk through a tiny concrete case. Suppose you have a batch of 2 query-passage pairs, and after normalizing their embeddings you measure cosine similarities (which, for unit vectors, are just dot products):

QueryPositiveSimilarity
q1q_1q1​p1p_1p1​0.90
q1q_1q1​p2p_2p2​0.20
q2q_2q2​p1p_1p1​0.15
q2q_2q2​p2p_2p2​0.85

For query q1q_1q1​, the true match is p1p_1p1​ (similarity 0.90). The other passage in the batch, p2p_2p2​, acts as an in-batch negative (similarity 0.20). InfoNCE wants the model to make p1p_1p1​ look more likely than p2p_2p2​.

For this worked row, choose a sharp temperature τ=0.05\tau = 0.05τ=0.05 and compute the loss contribution for q1q_1q1​ step by step:

  1. Scale the similarities into logits: positive logit = 0.90/0.05=18.00.90 / 0.05 = 18.00.90/0.05=18.0, negative logit = 0.20/0.05=4.00.20 / 0.05 = 4.00.20/0.05=4.0
  2. Exponentiate (this turns logits into unnormalized probabilities): exp⁡(18.0)≈65,659,969\exp(18.0) \approx 65{,}659{,}969exp(18.0)≈65,659,969, exp⁡(4.0)≈54.6\exp(4.0) \approx 54.6exp(4.0)≈54.6
  3. Normalize with softmax into a probability for the positive: 65,659,969/(65,659,969+54.6)≈0.9999991765{,}659{,}969 / (65{,}659{,}969 + 54.6) \approx 0.9999991765,659,969/(65,659,969+54.6)≈0.99999917
  4. Take negative log: −log⁡(0.99999917)≈0.00000083-\log(0.99999917) \approx 0.00000083−log(0.99999917)≈0.00000083 (tiny loss; the model is already very confident)

If the model were wrong (q1q_1q1​ similarity to p1p_1p1​ only 0.20, to p2p_2p2​ 0.90), the positive probability would drop to about 8.3×10−78.3 \times 10^{-7}8.3×10−7 and the loss would jump to roughly 14 nats. The optimizer would receive a strong gradient pushing the correct pair closer.

Exact InfoNCE row calculation for a two-pair batch. The cosine similarity matrix is q1 to p1 0.90, q1 to p2 0.20, q2 to p1 0.15, and q2 to p2 0.85, with diagonal positives. For q1 at temperature 0.05, similarities 0.90 and 0.20 become logits 18 and 4. Subtracting the maximum gives stable logits 0 and negative 14; exponentials are 1 and about 8.3 times 10 to the negative 7; softmax probabilities are 0.99999917 and 0.00000083. Negative log positive probability is about 0.00000083. Swapping the scores makes the loss about 14. Exact InfoNCE row calculation for a two-pair batch. The cosine similarity matrix is q1 to p1 0.90, q1 to p2 0.20, q2 to p1 0.15, and q2 to p2 0.85, with diagonal positives. For q1 at temperature 0.05, similarities 0.90 and 0.20 become logits 18 and 4. Subtracting the maximum gives stable logits 0 and negative 14; exponentials are 1 and about 8.3 times 10 to the negative 7; softmax probabilities are 0.99999917 and 0.00000083. Negative log positive probability is about 0.00000083. Swapping the scores makes the loss about 14.
InfoNCE reads each similarity row as a multiple-choice question where the diagonal passage is the correct answer and off-diagonal passages are in-batch negatives.

The standard contrastive loss for a batch of NNN positive pairs:[6]Reference 6Representation Learning with Contrastive Predictive Coding.https://arxiv.org/abs/1807.03748

L=−1N∑i=1Nlog⁡exp⁡(sim(zi,zi+)/τ)∑j=1Nexp⁡(sim(zi,zj+)/τ)\mathcal{L} = -\frac{1}{N} \sum_{i=1}^{N} \log \frac{\exp(\text{sim}(z_i, z_i^+) / \tau)}{\sum_{j=1}^{N} \exp(\text{sim}(z_i, z_j^+) / \tau)}L=−N1​∑i=1N​log∑j=1N​exp(sim(zi​,zj+​)/τ)exp(sim(zi​,zi+​)/τ)​

Reading the formula

For each example iii, compare its similarity to the true match zi+z_i^+zi+​ (numerator) against the full batch-level denominator. That denominator includes the positive pair itself plus every other candidate in the batch. Temperature τ\tauτ controls how sharply the model distinguishes between similar and dissimilar pairs. The loss says: "make the true pair more likely than every alternative in the batch."

Where:

  • zi,zi+z_i, z_i^+zi​,zi+​ are embeddings of a positive pair (e.g., query and relevant document)
  • τ\tauτ is the temperature parameter
  • All non-matching examples in that denominator act as in-batch negatives

This copy-runnable implementation keeps the same calculation visible instead of hiding the matrix math behind a framework. Production training code would vectorize this in PyTorch or another tensor library, but the loop below makes the denominator explicit:

reading-the-formula.py
1from math import exp, log, sqrt 2 3def normalize(vector: list[float]) -> list[float]: 4 norm = sqrt(sum(value * value for value in vector)) 5 return [value / norm for value in vector] 6 7def dot(left: list[float], right: list[float]) -> float: 8 return sum(a * b for a, b in zip(left, right)) 9 10def logsumexp(values: list[float]) -> float: 11 peak = max(values) 12 return peak + log(sum(exp(value - peak) for value in values)) 13 14def row_cross_entropy(logits: list[float], correct: int) -> float: 15 return logsumexp(logits) - logits[correct] 16 17def info_nce_loss( 18 query_vectors: list[list[float]], 19 positive_vectors: list[list[float]], 20 temperature: float = 0.2, 21) -> float: 22 queries = [normalize(vector) for vector in query_vectors] 23 positives = [normalize(vector) for vector in positive_vectors] 24 losses: list[float] = [] 25 26 for row, query in enumerate(queries): 27 logits = [dot(query, candidate) / temperature for candidate in positives] 28 losses.append(row_cross_entropy(logits, row)) 29 30 return sum(losses) / len(losses) 31 32query_vectors = [[1.0, 0.0], [0.0, 1.0]] 33positive_vectors = [[0.95, 0.05], [0.10, 0.90]] 34 35loss = info_nce_loss(query_vectors, positive_vectors) 36score_pos = dot(normalize(query_vectors[0]), normalize(positive_vectors[0])) 37score_neg = dot(normalize(query_vectors[0]), normalize(positive_vectors[1])) 38extreme_loss = row_cross_entropy([1000.0, 986.0], correct=0) 39 40print("loss:", round(loss, 4)) 41print("q1 positive score:", round(score_pos, 4)) 42print("q1 negative score:", round(score_neg, 4)) 43print("stable large-logit loss:", f"{extreme_loss:.8f}")
Output
1loss: 0.0104 2q1 positive score: 0.9986 3q1 negative score: 0.1104 4stable large-logit loss: 0.00000083

The equation is often expanded into raw exponentials when calculating a small example on paper. Code should compute the same expression with log-sum-exp or a framework cross-entropy operation, so large logits don't overflow.

Triplet loss

A second contrastive objective, triplet loss, focuses on individual anchor-positive-negative triplets instead of comparing one anchor against a whole candidate pool:

L=max⁡(0,d(a,p)−d(a,n)+m)\mathcal{L} = \max(0, d(a, p) - d(a, n) + m)L=max(0,d(a,p)−d(a,n)+m)

Where:

  • d(⋅,⋅)d(\cdot, \cdot)d(⋅,⋅) is the Euclidean distance between embeddings
  • mmm is a margin hyperparameter
  • aaa is the anchor, ppp is the positive, nnn is the negative

The loss enforces that the anchor must be closer to the positive than to the negative by at least margin mmm: d(a,p)+m≤d(a,n)d(a, p) + m \leq d(a, n)d(a,p)+m≤d(a,n). If this constraint is already satisfied, the loss is zero. The margin prevents the model from wasting capacity pushing already-distant negatives even farther away.

Worked example: computing triplet loss by hand

Consider three sentences about API-key rotation:

RoleSentence
Anchor (aaa)"How do I rotate an API key?"
Positive (ppp)"Where can I replace an old API token?"
Negative (nnn)"How do I rotate a KMS encryption key?"

After encoding, suppose the distances are:

  • d(a,p)=0.2d(a, p) = 0.2d(a,p)=0.2 (the paraphrase is close)
  • d(a,n)=0.5d(a, n) = 0.5d(a,n)=0.5 (the hard negative is farther, but not by much)

With margin m=0.1m = 0.1m=0.1, plug into the formula:

0.2−0.5+0.1=−0.20.2 - 0.5 + 0.1 = -0.20.2−0.5+0.1=−0.2

max⁡(0,−0.2)=0\max(0, -0.2) = 0max(0,−0.2)=0

The loss is zero because the model already satisfies the margin constraint: the positive is closer than the negative by more than 0.1. Now imagine a bad model where d(a,p)=0.5d(a, p) = 0.5d(a,p)=0.5 and d(a,n)=0.3d(a, n) = 0.3d(a,n)=0.3 (the negative is closer than the positive):

0.5−0.3+0.1=0.30.5 - 0.3 + 0.1 = 0.30.5−0.3+0.1=0.3

max⁡(0,0.3)=0.3\max(0, 0.3) = 0.3max(0,0.3)=0.3

A non-zero loss tells the optimizer to push the anchor and positive together while pushing the negative away until the gap exceeds the margin.

Key differences from InfoNCE

  • Triplet loss compares a chosen negative against a margin, so mining determines most of its learning signal.
  • InfoNCE compares each anchor with a candidate pool. Batches supply negatives cheaply, but they can also contain false negatives.
  • Neither objective is an automatic win. Choose data construction deliberately and evaluate held-out retrieval failures, not training loss alone.

Temperature parameter τ

Temperature controls the "sharpness" of the softmax distribution over similarity scores:

For the worked similarity gap, 0.90−0.20=0.700.90 - 0.20 = 0.700.90−0.20=0.70, changing temperature changes the positive probability:

τP(positive)P(\text{positive})P(positive) for this rowWhat to inspect
0.01>0.9999>0.9999>0.9999Saturates quickly; a false negative receives extreme pressure.
0.050.9999990.9999990.999999Very sharp separation for this easy row.
0.100.99910.99910.9991Still confident, with less sharpness.
1.000.66820.66820.6682Much flatter signal.

There is no universal best temperature. Tune it against held-out retrieval failures and implement the loss stably. Low temperature amplifies mislabeled or false negatives; overflow is an implementation bug that stable log-softmax or cross-entropy avoids.

Exact temperature comparison for the same contrastive similarity row with positive score 0.90 and negative score 0.20. At temperatures 0.01, 0.05, 0.10, and 1.00, the scaled gaps are 70, 14, 7, and 0.7; positive probabilities are approximately 1, 0.999999, 0.999089, and 0.668188. Residual negative mass grows from about 4.0 times 10 to the negative 31 to 0.331812 as temperature rises. Exact temperature comparison for the same contrastive similarity row with positive score 0.90 and negative score 0.20. At temperatures 0.01, 0.05, 0.10, and 1.00, the scaled gaps are 70, 14, 7, and 0.7; positive probabilities are approximately 1, 0.999999, 0.999089, and 0.668188. Residual negative mass grows from about 4.0 times 10 to the negative 31 to 0.331812 as temperature rises.
Temperature is a sharpness knob: low values make hard negatives dominate training, while high values flatten the softmax and weaken the separation signal.
temperature-sharpens-the-same-row.py
1from math import exp 2 3def probability_of_positive( 4 positive_similarity: float, 5 negative_similarity: float, 6 temperature: float, 7) -> float: 8 scaled_gap = (positive_similarity - negative_similarity) / temperature 9 return 1.0 / (1.0 + exp(-scaled_gap)) 10 11for temperature in (0.01, 0.05, 0.10, 1.00): 12 probability = probability_of_positive(0.90, 0.20, temperature) 13 print(f"tau={temperature:.2f}: P(positive)={probability:.6f}")
Output
1tau=0.01: P(positive)=1.000000 2tau=0.05: P(positive)=0.999999 3tau=0.10: P(positive)=0.999089 4tau=1.00: P(positive)=0.668188


Training strategies for sentence embeddings

Training a good embedding model requires good training data. You need pairs of sentences that are either semantically similar or different, and you need enough diversity to teach the model real distinctions. Supervised NLI pairs and SimCSE's self-supervised dropout views make two useful constructions concrete.

Supervised: fine-tuning on NLI data

Natural Language Inference (NLI) labels whether a hypothesis follows from a premise (entailment), conflicts with it (contradiction), or does neither (neutral). Entailment is directional, not a promise that two texts are interchangeable.

SBERT trained Siamese and triplet architectures with NLI supervision and evaluated sentence similarity behavior.[1]Reference 1Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks.https://arxiv.org/abs/1908.10084 Supervised SimCSE uses entailment as a positive and the corresponding contradiction as a hard negative.[3]Reference 3SimCSE: Simple Contrastive Learning of Sentence Embeddings.https://arxiv.org/abs/2104.08821 This is a useful training construction, but you still need retrieval evaluation before treating two technical passages as substitutes.

SBERT's architectural move is simple but important: it runs both sentences through the same encoder with shared weights, pools each sentence into a single vector, and then trains on top of those pooled embeddings.[1]Reference 1Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks.https://arxiv.org/abs/1908.10084 During inference, you only keep the single-sentence encoding path. That shared-weight Siamese network setup (two inputs processed through the same shared encoder) is what makes precomputing document embeddings and doing nearest-neighbor search practical.

Self-supervised: SimCSE

What if you don't have labeled NLI data? SimCSE (Simple Contrastive Learning of Sentence Embeddings) from Gao et al. (2021)[3]Reference 3SimCSE: Simple Contrastive Learning of Sentence Embeddings.https://arxiv.org/abs/2104.08821 shows you don't need it. The method passes the same sentence through the encoder twice with different dropout masks. Since dropout randomly zeros out different neurons each time, you get two slightly different embedding vectors for the same sentence. These two views are positives (they should be similar), while all other sentences in the batch are negatives.

This gives surprisingly strong embeddings without labeled pairs, although supervised SimCSE performs better across the paper's reported STS tasks.[3]Reference 3SimCSE: Simple Contrastive Learning of Sentence Embeddings.https://arxiv.org/abs/2104.08821 The stochasticity in the transformer forward pass, normally just a regularization technique, becomes an implicit data augmentation mechanism for contrastive learning.

Data augmentation

Beyond dropout, augmentations are hypotheses about meaning preservation:

  • Dropout masks (SimCSE): different mask patterns per forward pass
  • Verified paraphrases or back-translations: use only after checking that technical scope and exceptions survive
  • Domain pairs: mine resolved duplicate questions that cite the same approved docs passage
  • Reranking with cross-encoders: score candidate paraphrases before accepting them as positives

Avoid casual word deletion or insertion for technical docs: dropping "not," a version condition, or an authorization requirement changes the rule while incorrectly labeling the pair positive.

In-batch negatives in practice

Most contrastive learning implementations use in-batch negatives by default: for a batch of NNN positive pairs, each anchor has one matching positive, and the other N−1N-1N−1 candidates in the batch act as negatives. This is efficient because you get many negatives "for free" without explicitly labeling them.

Larger batches increase the chance of informative competitors, but they also increase the chance of false negatives: another row may cite the same relevant docs passage as the anchor while the loss treats it as wrong. Distributed training commonly gathers embeddings across GPUs before computing this loss. Plain gradient accumulation doesn't create more in-batch negatives unless the implementation explicitly reuses embeddings across microbatches.

audit-false-negatives-before-training.py
1batch = [ 2 {"query": "How do I rotate an API key?", "doc_id": "api-key-rotation-v3"}, 3 {"query": "How do I replace an old API token?", "doc_id": "api-key-rotation-v3"}, 4 {"query": "How do service account tokens expire?", "doc_id": "service-token-lifecycle-v2"}, 5] 6 7false_negatives = [] 8for anchor_index, anchor in enumerate(batch): 9 for candidate_index, candidate in enumerate(batch): 10 if anchor_index == candidate_index: 11 continue 12 if candidate["doc_id"] == anchor["doc_id"]: 13 false_negatives.append( 14 f"row {anchor_index} treats row {candidate_index} as negative" 15 ) 16 17print("false negatives:", false_negatives) 18print("action: deduplicate shared-doc positives before InfoNCE")
Output
1false negatives: ['row 0 treats row 1 as negative', 'row 1 treats row 0 as negative'] 2action: deduplicate shared-doc positives before InfoNCE

Hard negative mining

Why hard negatives matter

Random negatives often become too easy. The model quickly learns to distinguish "API key rotation" from "GPU driver compatibility." Hard negatives force it to learn subtler semantic distinctions that broad topic separation misses.

Negative typeAnchorCandidateWhy it matters
Easy negative"How do I rotate an API key?""GPU driver compatibility matrix"Different topic; the model learns this separation almost immediately
Hard negative"How do I rotate an API key?""How do I rotate a KMS encryption key?"Same keywords, different intent; forces fine-grained learning
Hard-negative mining audit for the query How do I rotate an API key. Four candidates are compared by known relevance label, lexical token overlap, deterministic cross-encoder score, and mining decision. The true matching API-token passage has overlap 3 and score 0.92 but is protected as a positive. The service-account-key passage has overlap 5 and score 0.76 and becomes hard negative rank 1. The KMS-key passage has overlap 2 and score 0.68 and becomes hard negative rank 2. The GPU-driver passage has zero overlap and score 0.05 and is dropped. Hard-negative mining audit for the query How do I rotate an API key. Four candidates are compared by known relevance label, lexical token overlap, deterministic cross-encoder score, and mining decision. The true matching API-token passage has overlap 3 and score 0.92 but is protected as a positive. The service-account-key passage has overlap 5 and score 0.76 and becomes hard negative rank 1. The KMS-key passage has overlap 2 and score 0.68 and becomes hard negative rank 2. The GPU-driver passage has zero overlap and score 0.05 and is dropped.
Useful mined negatives can share words with the anchor while answering a different intent. Explicit relevance labels keep true positives out of the negative set.

Mining strategies

1. In-batch negatives

Use other examples in the batch. Simple, scales with batch size, but negatives may be too easy.

2. BM25 negatives

Use a lexical search algorithm like BM25 (Best Matching 25) to find documents that are lexically similar but semantically different:

text
1Query: "How do I rotate an API key?" 2Hard negative: "Rotate KMS encryption key material" # shares "rotate" and "key" but answers a different question 3Easy negative: "GPU driver compatibility matrix"

3. Cross-encoder-assisted mining

Start with lexical or dense retrieval, then keep known non-matches that still receive a high cross-encoder score. Labels, document identity, or human review establish that a candidate is wrong; a model score isn't ground truth by itself. The mining loop makes that control flow deterministic: lexical overlap stands in for BM25, a small scorer stands in for the cross-encoder, and explicit relevance labels prevent true positives from becoming negatives.

3-cross-encoder-mining.py
1def tokens(text: str) -> set[str]: 2 return {part.strip("?.!,").lower() for part in text.split()} 3 4def lexical_overlap(query: str, candidate: str) -> int: 5 return len(tokens(query) & tokens(candidate)) 6 7def cross_encoder_score(query: str, candidate: str) -> float: 8 query_terms = tokens(query) 9 candidate_terms = tokens(candidate) 10 11 if "api" in query_terms and "api" in candidate_terms: 12 return 0.92 13 if "service" in candidate_terms and "key" in candidate_terms: 14 return 0.76 15 if "kms" in candidate_terms and "key" in candidate_terms: 16 return 0.68 17 return 0.05 18 19def mine_hard_negatives( 20 query: str, 21 corpus: list[dict[str, str | bool]], 22 top_k: int = 2, 23) -> list[str]: 24 known_non_matches = [ 25 row 26 for row in corpus 27 if not row["relevant"] 28 and lexical_overlap(query, str(row["text"])) > 0 29 ] 30 ranked = sorted( 31 known_non_matches, 32 key=lambda row: cross_encoder_score(query, str(row["text"])), 33 reverse=True, 34 ) 35 return [str(row["text"]) for row in ranked[:top_k]] 36 37query = "How do I rotate an API key?" 38corpus = [ 39 {"text": "Where can I replace an old API token?", "relevant": True}, 40 {"text": "Rotate KMS encryption key material", "relevant": False}, 41 {"text": "How do I rotate a service account signing key?", "relevant": False}, 42 {"text": "GPU driver compatibility matrix", "relevant": False}, 43] 44 45print(mine_hard_negatives(query, corpus))
Output
1['How do I rotate a service account signing key?', 'Rotate KMS encryption key material']

4. Iterative mining

Re-mine hard negatives periodically using the improved model. This progressively finds harder examples as the model improves.


Bi-encoder vs cross-encoder

Structural comparison of three retrieval architectures. A bi-encoder precomputes one vector per document, encodes the query once, and compares vectors with dot product or cosine, making it suitable for corpus retrieval. A cross-encoder stores raw documents and runs one joint transformer pass per query-document pair, usually K passes for a K-candidate reranking shortlist. Late interaction precomputes one vector per document token, encodes query tokens once, and sums each query token maximum similarity over document tokens, trading a larger token-vector index for finer matching. Structural comparison of three retrieval architectures. A bi-encoder precomputes one vector per document, encodes the query once, and compares vectors with dot product or cosine, making it suitable for corpus retrieval. A cross-encoder stores raw documents and runs one joint transformer pass per query-document pair, usually K passes for a K-candidate reranking shortlist. Late interaction precomputes one vector per document token, encodes query tokens once, and sums each query token maximum similarity over document tokens, trading a larger token-vector index for finer matching.
Embedding retrieval architecture is a placement decision: bi-encoders interact at vector comparison time, cross-encoders interact inside attention, and late-interaction models keep token-level matching without full pairwise scoring.

Bi-encoder (dual encoder)

A bi-encoder encodes the query and document independently, then compares them with dot product or cosine similarity:

Advantages

Documents can be pre-encoded and indexed. At query time, you only encode the query once, then use an approximate nearest neighbor (ANN) search index to retrieve candidates without scanning every stored vector.

Disadvantages

No cross-attention between query and document; it may miss fine-grained relevance signals.

Cross-encoder

Concatenate query and document, process jointly through full transformer:

Advantages

Full attention can model phrase order, negation, and query-document interactions that a single-vector score misses. On a suitable shortlist, this often improves precision over first-stage vector scoring.

Disadvantages

You must run inference for every (query, document) pair. If you scored the full corpus directly, that's O(N) transformer passes per query, which is too slow for large-scale search.

Late interaction: ColBERT

ColBERT (Contextualized Late Interaction over BERT)[7]Reference 7ColBERT: Efficient and Effective Passage Search via Contextualized Late Interaction over BERT.https://arxiv.org/abs/2004.12832 uses late interaction as a middle ground between bi-encoder and cross-encoder:

Exact ColBERT MaxSim calculation for query tokens api and key against document tokens rotate, api, and key. The similarity rows are 0.12, 0.93, 0.08 and 0.19, 0.07, 0.91. MaxSim selects api-to-api 0.93 and key-to-key 0.91, then sums them to a final relevance score of 1.84. Exact ColBERT MaxSim calculation for query tokens api and key against document tokens rotate, api, and key. The similarity rows are 0.12, 0.93, 0.08 and 0.19, 0.07, 0.91. MaxSim selects api-to-api 0.93 and key-to-key 0.91, then sums them to a final relevance score of 1.84.
ColBERT stores token vectors for documents, then scores a query by taking each query token's best document-token match and summing those MaxSim values.

Instead of a single embedding per document, ColBERT stores per-token embeddings and computes relevance using MaxSim: for each query token, find the maximum similarity to any document token, then sum.

Advantages

Retains token-level matching signals while documents can still be pre-encoded.

Disadvantages

Much larger index size (one vector per token instead of per document).

This architecture choice is a budget tradeoff, not a universal ranking. A bi-encoder serves first-stage candidate generation at corpus scale and must be tuned for recall; a cross-encoder can improve precision for a bounded candidate set; late interaction spends more index space to preserve token-level evidence.

maxsim-keeps-token-matches.py
1similarities = { 2 "api": {"rotate": 0.12, "api": 0.93, "key": 0.08}, 3 "key": {"rotate": 0.19, "api": 0.07, "key": 0.91}, 4} 5 6best_by_query_token = { 7 query_token: max(document_scores.values()) 8 for query_token, document_scores in similarities.items() 9} 10score = sum(best_by_query_token.values()) 11 12print("best token scores:", best_by_query_token) 13print("MaxSim score:", round(score, 2))
Output
1best token scores: {'api': 0.93, 'key': 0.91} 2MaxSim score: 1.84

A production reranking pattern

Exact two-stage retrieval trace for query auth-cache unit test failure. Four documents are ranked by bi-encoder score: auth-cache-timeout 0.82, api-key-rotation 0.79, unit-test-failure-guide 0.77, and gpu-driver-notes 0.10. Candidate k equals 3, so gpu-driver-notes is excluded. Cross-encoder reranking changes the shortlist order to auth-cache-timeout 0.97, unit-test-failure-guide 0.91, and api-key-rotation 0.22. Top k equals 2, so the first two IDs are returned. Exact two-stage retrieval trace for query auth-cache unit test failure. Four documents are ranked by bi-encoder score: auth-cache-timeout 0.82, api-key-rotation 0.79, unit-test-failure-guide 0.77, and gpu-driver-notes 0.10. Candidate k equals 3, so gpu-driver-notes is excluded. Cross-encoder reranking changes the shortlist order to auth-cache-timeout 0.97, unit-test-failure-guide 0.91, and api-key-rotation 0.22. Top k equals 2, so the first two IDs are returned.
Bi-encoder retrieval protects recall across the whole corpus. Cross-encoder attention is reserved for a small shortlist where precision gains justify the latency cost.

In a production system, these two architectures are often combined in a two-stage pipeline. A reranker spends the expensive cross-encoder pass only on candidates admitted by the bi-encoder. This function makes that boundary visible with deterministic scores, then returns the highest-scoring two documents.

the-reranking-pattern-production-standard.py
1documents = [ 2 { 3 "id": "auth-cache-timeout", 4 "text": "Auth-cache timeout troubleshooting for CI runs", 5 "bi_score": 0.82, 6 "cross_score": 0.97, 7 }, 8 { 9 "id": "api-key-rotation", 10 "text": "API key rotation runbook", 11 "bi_score": 0.79, 12 "cross_score": 0.22, 13 }, 14 { 15 "id": "unit-test-failure-guide", 16 "text": "Unit-test failure triage guide", 17 "bi_score": 0.77, 18 "cross_score": 0.91, 19 }, 20 { 21 "id": "gpu-driver-notes", 22 "text": "GPU driver compatibility notes", 23 "bi_score": 0.10, 24 "cross_score": 0.05, 25 }, 26] 27 28def search_with_rerank( 29 query: str, 30 corpus: list[dict[str, str | float]], 31 candidate_k: int = 3, 32 top_k: int = 2, 33) -> list[str]: 34 candidates = sorted(corpus, key=lambda doc: float(doc["bi_score"]), reverse=True)[ 35 :candidate_k 36 ] 37 reranked = sorted( 38 candidates, 39 key=lambda doc: float(doc["cross_score"]), 40 reverse=True, 41 ) 42 return [str(doc["id"]) for doc in reranked[:top_k]] 43 44results = search_with_rerank("auth-cache unit test failure", documents) 45print(results)
Output
1['auth-cache-timeout', 'unit-test-failure-guide']

Instruction-tuned embeddings

The problem with task ambiguity

"Label" means different things for clustering (group issue-label documents), retrieval (find axis-label troubleshooting), and classification (is this about a bug, docs, or security?). An embedding call without task conditioning produces its representation from the text alone. That can limit one model serving several tasks with different notions of similarity.

Task-specific prefixes and instructions

Some embedding families expose task prefixes or lightweight instructions that steer the encoder toward retrieval, clustering, or classification. E5 is a simple example: it distinguishes inputs like query: and passage: during contrastive pre-training.[5]Reference 5Text Embeddings by Weakly-Supervised Contrastive Pre-training.https://arxiv.org/abs/2212.03533 INSTRUCTOR-style models go further and condition the embedding on an explicit task instruction.[8]Reference 8One Embedder, Any Task: Instruction-Finetuned Text Embeddings.https://arxiv.org/abs/2212.09741 The format is model-specific. Prefixes that help one family can hurt another, so follow its training or model documentation.

This example keeps the families separate on purpose. The exact prefix or instruction string depends on the embedding family you chose:

task-specific-prefixes-and-instructions.py
1def format_e5_pair(query: str, passage: str) -> tuple[str, str]: 2 """E5-style inputs are prefixed strings.""" 3 return f"query: {query}", f"passage: {passage}" 4 5def format_instructor_input(instruction: str, text: str) -> list[str]: 6 """INSTRUCTOR-style inputs are commonly [instruction, text] pairs.""" 7 return [instruction, text] 8 9e5_query, e5_passage = format_e5_pair( 10 "how do I rotate an API key?", 11 "Create a replacement key, deploy it, then revoke the old key.", 12) 13 14instructor_example = format_instructor_input( 15 "Represent the developer question for retrieving approved API docs:", 16 "how do I rotate an API key?", 17) 18 19assert e5_query.startswith("query: ") 20assert e5_passage.startswith("passage: ") 21assert instructor_example[0].startswith("Represent") 22assert instructor_example[1] == "how do I rotate an API key?"

This doesn't mean one prefix solves every task. It means some embedding families expect an extra conditioning signal. Use the format documented for that specific model family, then benchmark it on your own retrieval, clustering, or classification workload.


Matryoshka representation learning (MRL)

The idea

Matryoshka representation learning is named after nesting dolls because selected embedding prefix widths are trained to remain useful on their own. For example, a full 768-dimensional embedding can be trained together with 128- and 32-dimensional prefixes. You then choose among trained and evaluated widths based on the storage-quality budget.

Train embeddings so that selected prefix widths preserve useful representations under their own losses:[9]Reference 9Matryoshka Representation Learning.https://arxiv.org/abs/2205.13147

Matryoshka prefix training shown with one 768-dimensional embedding divided into 24 blocks of 32 dimensions. Training losses are attached at prefixes 32, 128, and 768, whose relative float storage is 4.17 percent, 16.67 percent, and 100 percent. A separate exact runnable toy computes InfoNCE losses 0.0088 at dimension 2, 0.0147 at dimension 4, and 0.0225 at dimension 6, then averages them to 0.0153. The toy losses are objective terms, not retrieval-quality scores. Matryoshka prefix training shown with one 768-dimensional embedding divided into 24 blocks of 32 dimensions. Training losses are attached at prefixes 32, 128, and 768, whose relative float storage is 4.17 percent, 16.67 percent, and 100 percent. A separate exact runnable toy computes InfoNCE losses 0.0088 at dimension 2, 0.0147 at dimension 4, and 0.0225 at dimension 6, then averages them to 0.0153. The toy losses are objective terms, not retrieval-quality scores.
Matryoshka training applies contrastive losses at multiple prefix sizes so smaller dimensions remain usable instead of becoming arbitrary truncations.

For a contrastively trained embedding model, the loss can be computed at several predefined truncation points simultaneously. This runnable toy implementation slices full embeddings down to smaller prefixes, calculates the same InfoNCE objective at each prefix, and averages the losses:

the-idea.py
1from math import exp, log, sqrt 2 3def normalize(vector: list[float]) -> list[float]: 4 norm = sqrt(sum(value * value for value in vector)) 5 return [value / norm for value in vector] 6 7def dot(left: list[float], right: list[float]) -> float: 8 return sum(a * b for a, b in zip(left, right)) 9 10def logsumexp(values: list[float]) -> float: 11 peak = max(values) 12 return peak + log(sum(exp(value - peak) for value in values)) 13 14def info_nce_loss( 15 query_vectors: list[list[float]], 16 positive_vectors: list[list[float]], 17 temperature: float = 0.2, 18) -> float: 19 queries = [normalize(vector) for vector in query_vectors] 20 positives = [normalize(vector) for vector in positive_vectors] 21 losses: list[float] = [] 22 23 for row, query in enumerate(queries): 24 logits = [dot(query, candidate) / temperature for candidate in positives] 25 losses.append(logsumexp(logits) - logits[row]) 26 27 return sum(losses) / len(losses) 28 29def matryoshka_loss( 30 embeddings_a: list[list[float]], 31 embeddings_b: list[list[float]], 32 dims: tuple[int, int, int] = (2, 4, 6), 33) -> float: 34 losses = [] 35 36 for dim in dims: 37 truncated_a = [row[:dim] for row in embeddings_a] 38 truncated_b = [row[:dim] for row in embeddings_b] 39 losses.append(info_nce_loss(truncated_a, truncated_b)) 40 41 return sum(losses) / len(losses) 42 43queries = [[1.0, 0.0, 0.9, 0.1, 0.5, 0.2], [0.0, 1.0, 0.1, 0.9, 0.2, 0.5]] 44positives = [[0.95, 0.05, 0.85, 0.15, 0.45, 0.25], [0.05, 0.95, 0.15, 0.85, 0.25, 0.45]] 45 46loss = matryoshka_loss(queries, positives) 47print(round(loss, 4))
Output
10.0153

Why it matters

BenefitWhy it matters
Flexible deploymentUse the full width when it wins your evaluation, or a smaller trained prefix when storage is constrained.
No retrainingOne model can serve several dimensionality budgets.
Graceful degradationPerformance should drop smoothly as dimensions shrink, but you still need to benchmark each cutoff.
Deployment constraintShorten only at dimensions a chosen model documents or you validate; arbitrary slicing isn't guaranteed to preserve rankings.

Evaluation: STS and MTEB

Semantic textual similarity (STS)

Before large-scale benchmarks like MTEB existed, a common benchmark for evaluating sentence embeddings was Semantic Textual Similarity (STS). Datasets like STS-B (STS Benchmark) provide sentence pairs rated by human annotators for semantic relatedness:

text
1"A CI build failed" / "A test run failed" => 4.5 2"A CI build failed" / "A password was reset" => 1.2

To evaluate a model, you compute the cosine similarity for every pair using the model's embeddings, and then calculate the Spearman rank correlation between the model's similarity scores and the human ratings. A high correlation means the model's embedding space aligns well with human judgment.

MTEB (Massive text embedding benchmark)

As models improved, optimizing only for STS was no longer sufficient. An embedding model excellent at STS might fail at information retrieval or clustering. To address this, the Massive Text Embedding Benchmark (MTEB) was introduced.[10]Reference 10MTEB: Massive Text Embedding Benchmark.https://arxiv.org/abs/2210.07316 The original MTEB paper evaluated models on 58 datasets grouped into 8 task categories, giving a much broader view of embedding quality than STS alone:

Task# DatasetsExample
Classification12Sentiment, topic
Clustering11Document clustering
Pair Classification3Paraphrase detection
Reranking4Passage reranking
Retrieval15Question-passage retrieval
STS10Semantic similarity
Summarization1Summary similarity
BitextMining2Parallel sentence mining
Sentence-embedding evaluation scope comparison. STS evaluates sentence pairs by comparing cosine-similarity rankings with human ratings from 0 to 5 using Spearman rank correlation. The original MTEB benchmark spans 58 datasets across eight categories: retrieval 15, classification 12, clustering 11, STS 10, reranking 4, pair classification 3, bitext mining 2, and summarization 1. Public benchmark breadth still needs workload-specific retrieval, language, latency, and storage validation. Sentence-embedding evaluation scope comparison. STS evaluates sentence pairs by comparing cosine-similarity rankings with human ratings from 0 to 5 using Spearman rank correlation. The original MTEB benchmark spans 58 datasets across eight categories: retrieval 15, classification 12, clustering 11, STS 10, reranking 4, pair classification 3, bitext mining 2, and summarization 1. Public benchmark breadth still needs workload-specific retrieval, language, latency, and storage validation.
STS is a useful narrow check, but production model choice should look across retrieval, reranking, clustering, classification, latency, and storage behavior.

Choosing a model in practice

Don't anchor on a single MTEB average. Deployment success usually depends on a few operational questions:

  • Does the model expect plain text, query/passage prefixes, or explicit instructions?
  • Can you shorten the embedding width safely, or are you locked into the full dimensionality?
  • How well does it handle your language mix, domain jargon, and query length distribution?
  • What are the latency, throughput, and memory costs once you batch and index it at production scale?
  • Do you still need BM25 or a cross-encoder reranker to hit Recall@K and NDCG targets?

Small leaderboard deltas can't compensate for a mismatched retrieval architecture, weak negatives, poor chunking, or a missing reranking stage. Evaluate the whole retrieval path instead of swapping model names in isolation.

The original MTEB finding is the durable lesson: no one model dominated every task category.[10]Reference 10MTEB: Massive Text Embedding Benchmark.https://arxiv.org/abs/2210.07316 Evaluate API-doc retrieval, reranking, languages, latency, and storage behavior that match your deployment instead of selecting by one aggregate score.

Carry the evidence boundary into retrieval evaluation

document_qa_v2 can use an embedding retriever to propose API-doc passages, but vector proximity isn't authorization. A release test should verify both retrieval quality and that unapproved text never becomes answer evidence:

docs-retrieval-release-gate.py
1approved_evidence = {"api-key-rotation-v3", "service-token-lifecycle-v2"} 2retrieval_cases = [ 3 { 4 "query": "How do I rotate an API key?", 5 "expected": "api-key-rotation-v3", 6 "candidates": ["private-incident-note-44", "api-key-rotation-v3"], 7 }, 8 { 9 "query": "How do service account tokens expire?", 10 "expected": "service-token-lifecycle-v2", 11 "candidates": ["service-token-lifecycle-v2", "draft-runbook-12"], 12 }, 13] 14attack_candidates = ["private-incident-note-44"] 15 16def approved_candidate(candidates: list[str]) -> str | None: 17 return next((doc for doc in candidates if doc in approved_evidence), None) 18 19served = [approved_candidate(case["candidates"]) for case in retrieval_cases] 20hits = sum( 21 evidence == case["expected"] 22 for evidence, case in zip(served, retrieval_cases) 23) 24attack_evidence = approved_candidate(attack_candidates) 25 26print("approved evidence recall@2:", f"{hits / len(retrieval_cases):.0%}") 27print("served evidence:", served) 28print("private-note attack evidence:", attack_evidence)
Output
1approved evidence recall@2: 100% 2served evidence: ['api-key-rotation-v3', 'service-token-lifecycle-v2'] 3private-note attack evidence: None

Key libraries and tools

Building embedding-based systems requires the right tooling:

ToolWhat it gives you
Sentence-Transformers (sentence-transformers)Pretrained sentence embedding models, pooling modules, contrastive training losses such as MultipleNegativesRankingLoss, and batched encoding utilities.
FAISS (Facebook AI Similarity Search)Efficient similarity search and clustering for dense vectors, including inverted-file and product-quantization approaches for approximate nearest neighbor search.[11]Reference 11Billion-scale similarity search with GPUs.https://arxiv.org/abs/1702.08734

Mastery check

Key concepts

  • alignment and uniformity in embedding space
  • InfoNCE numerator, denominator, and temperature
  • hard negatives vs easy negatives
  • bi-encoder vs cross-encoder vs late interaction
  • reranking as recall first, then precision
  • Matryoshka prefix training for safe dimension cuts

Evaluation rubric

  • Foundational: Derives the InfoNCE objective and explains what the numerator, denominator, and temperature do.
  • Intermediate: Explains why raw BERT [CLS] embeddings fail for semantic search without sentence-level contrastive fine-tuning.
  • Intermediate: Explains why hard negatives matter more than random negatives once the model already separates broad topics.
  • Advanced: Compares bi-encoders, cross-encoders, and late-interaction models by latency, indexability, accuracy, and storage.
  • Advanced: Explains ColBERT's MaxSim scoring and why it keeps more token-level signal than a single document vector.
  • Advanced: Explains Matryoshka embeddings and when shorter prefixes are worth the storage-accuracy tradeoff.
  • Advanced: Designs a two-stage production retrieval pipeline with recall and latency budgets defended quantitatively.

Follow-up questions

Common pitfalls

Raw [CLS] is treated like a search-ready sentence embedding

  • Symptom: Nearly every query-document pair gets suspiciously similar cosine scores.
  • Cause: Raw BERT [CLS] vectors weren't tuned for semantic retrieval and can inherit poorly discriminative anisotropic geometry.
  • Fix: Start from a sentence embedding model or fine-tune with a contrastive objective before building nearest-neighbor search.

Negatives stay too easy

  • Symptom: Training loss falls, but recall on realistic queries barely moves.
  • Cause: Random negatives stop teaching once the model separates unrelated topics.
  • Fix: Mine BM25 or cross-encoder negatives that share words with the anchor but answer a different intent.

The reranker is asked to save missing recall

  • Symptom: The reranker looks good in pairwise inspection, yet the right document is often absent in production results.
  • Cause: The correct passage never entered the shortlist.
  • Fix: Tune first-stage Recall@K separately, then widen candidate budget before blaming the reranker.

Dimensions are shortened blindly

  • Symptom: Index storage drops as expected, but retrieval quality falls off a cliff.
  • Cause: A standard embedding vector was truncated without prefix-aware training or provider support.
  • Fix: Use Matryoshka-trained or provider-documented shortening controls and benchmark each target width.

Task conditioning is ignored

  • Symptom: One embedding model works for clustering but underperforms on retrieval.
  • Cause: The model family expected query/passage prefixes or instructions, but every input was embedded as plain text.
  • Fix: Follow the model card format for retrieval, clustering, and classification separately.

Try it yourself

These exercises let you verify your understanding without needing a GPU cluster.

Exercise 1: compute triplet loss by hand

Given an anchor aaa, positive ppp, and negative nnn with distances d(a,p)=0.3d(a,p) = 0.3d(a,p)=0.3 and d(a,n)=0.7d(a,n) = 0.7d(a,n)=0.7, compute the triplet loss for margins m=0.1m = 0.1m=0.1 and m=0.5m = 0.5m=0.5. In which case does the model still have work to do?

Solution sketch: For m=0.1m = 0.1m=0.1: 0.3−0.7+0.1=−0.30.3 - 0.7 + 0.1 = -0.30.3−0.7+0.1=−0.3, so max⁡(0,−0.3)=0\max(0, -0.3) = 0max(0,−0.3)=0. The margin is already satisfied. For m=0.5m = 0.5m=0.5: 0.3−0.7+0.5=0.10.3 - 0.7 + 0.5 = 0.10.3−0.7+0.5=0.1, so max⁡(0,0.1)=0.1\max(0, 0.1) = 0.1max(0,0.1)=0.1. The larger margin forces the model to pull the positive even closer or push the negative farther away.

Exercise 2: spot the embedding mistake

A teammate reports that their semantic search system returns nearly identical similarity scores for every query-document pair. They are using a pretrained BERT model and taking the [CLS] token as the sentence embedding. What is the most likely cause, and what is the smallest change that would fix it?

Solution sketch: Raw BERT [CLS] embeddings weren't trained to make cosine distance a semantic-retrieval score, and anisotropic geometry can make their scores poorly discriminative. The smallest fix is to switch to a sentence embedding model that was fine-tuned with a sentence-level objective (for example, SBERT or E5), rather than using raw BERT.

Exercise 3: design a two-stage retrieval pipeline

You have 2 million documentation chunks and a latency budget of 200 ms per query. You own a bi-encoder that encodes a query in 10 ms and a cross-encoder that scores one query-document pair in 15 ms. Why is scoring the full corpus with the cross-encoder impossible, and what pipeline would hit the latency budget?

Solution sketch: 2,000,000×15 ms=30,000,000 ms≈8.32{,}000{,}000 \times 15\,\text{ms} = 30{,}000{,}000\,\text{ms} \approx 8.32,000,000×15ms=30,000,000ms≈8.3 hours per query. The cross-encoder is far too slow for the full corpus. Reserve 10 ms for query encoding and choose a top-10 shortlist only if ANN lookup and overhead fit inside the remaining 40 ms: reranking then costs 10×15 ms=150 ms10 \times 15\,\text{ms} = 150\,\text{ms}10×15ms=150ms, for at most 200 ms total. If Recall@10 is inadequate, the budget or reranker throughput must change; silently widening to top 100 violates the requirement.


What you have now

The production sentence-embedding path is explicit: raw transformer outputs fail for semantic search, contrastive learning reshapes the embedding space, and retrieval quality depends on hard negatives, concrete losses, and deployment constraints. InfoNCE, triplet loss, lexical-overlap mining, and two-stage retrieval now connect to one speed-and-accuracy trade-off.

The next article, Embedding Similarity & Quantization, builds directly on this foundation. It compares cosine similarity with dot product, shows how Matryoshka truncation changes the accuracy-storage tradeoff, and quantizes embeddings to 8-bit, 4-bit, or binary formats for large-scale indexes. Those techniques only make sense once you understand why the embedding space was shaped by contrastive loss in the first place.

Complete the lesson

Mastery Check

Answer every question, then check your score. Score above 75% to mark this lesson complete.

1.Two prototype encoders fail differently. Averaging context-free word vectors maps "compiler calls linker" and "linker calls compiler" to the same vector. Raw BERT [CLS] gives nearly identical cosine scores across passages. Which diagnosis and remedy are correct?
2.For q1, the positive similarity is 0.90, the only negative similarity is 0.20, and tau = 0.05. Why is the InfoNCE loss for this row nearly zero?
3.Triplet loss is L = max(0, d(a,p) - d(a,n) + m). If d(a,p) = 0.3 and d(a,n) = 0.7, what are the losses for m = 0.1 and m = 0.5?
4.A contrastive batch has two different queries that both cite api-key-rotation-v3 and a third query that cites service-token-lifecycle-v2. The implementation uses InfoNCE with in-batch negatives and plain gradient accumulation. What should you fix?
5.You have unlabeled sentences and a transformer with dropout. Which setup matches self-supervised SimCSE and its intended effect on embedding geometry?
6.A model already separates "API key rotation" from "GPU driver compatibility," but it confuses "How do I rotate an API key?" with "How do I rotate a KMS encryption key?" Which negative should you add, and why?
7.You have 2 million documentation chunks. Query encoding with a bi-encoder takes 10 ms, and a cross-encoder scores one query-document pair in 15 ms. With a 200 ms per-query budget, which pipeline is feasible?
8.In a ColBERT-style late-interaction scorer, the query has tokens "api" and "key." The best document-token similarities are 0.93 for "api" and 0.91 for "key." What score is produced, and what deployment tradeoff comes with this representation?
9.An E5-style model was embedded as plain text and selected only by a high MTEB average. The app also lets the nearest vector become answer evidence, even if it is a private incident note. What should change?
10.You have a 768-dimensional sentence embedding model and want to index only the first 128 coordinates. Which condition makes this truncation a defensible deployment choice?

10 questions remaining.

Next Step
Continue to Embedding Similarity & Quantization

Contrastive learning explains how useful sentence vectors are trained; similarity scoring and quantization show how those vectors are searched and stored efficiently at scale.

PreviousCapstone: Fine-Tuned Classifier
Share this article
XFacebookLinkedInBlueskyRedditHacker NewsEmail
References

Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks.

Reimers, N., & Gurevych, I. · 2019 · EMNLP 2019

How Contextual are Contextualized Word Representations? Comparing the Geometry of BERT, ELMo, and GPT-2 Embeddings.

Ethayarajh, K. · 2019

SimCSE: Simple Contrastive Learning of Sentence Embeddings.

Gao, T., Yao, X., & Chen, D. · 2021 · EMNLP 2021

Understanding Contrastive Representation Learning through Alignment and Uniformity on the Hypersphere

Wang, T., & Isola, P. · 2020 · ICML 2020

Text Embeddings by Weakly-Supervised Contrastive Pre-training.

Wang, L., et al. · 2022

Representation Learning with Contrastive Predictive Coding.

Oord, A. van den, Li, Y., & Vinyals, O. · 2018

ColBERT: Efficient and Effective Passage Search via Contextualized Late Interaction over BERT.

Khattab, O., & Zaharia, M. · 2020 · SIGIR 2020

One Embedder, Any Task: Instruction-Finetuned Text Embeddings.

Su, H., et al. · 2022 · arXiv preprint

Matryoshka Representation Learning.

Kusupati, A., et al. · 2022 · NeurIPS 2022

MTEB: Massive Text Embedding Benchmark.

Muennighoff, N., et al. · 2023 · EACL 2023

Billion-scale similarity search with GPUs.

Johnson, J., Douze, M., & Jégou, H. · 2017 · arXiv preprint

Discussion

Questions and insights from fellow learners.

Discussion loads when you reach this section.