How to generate sparse embeddings with Sentence Transformers

Sparse retrieval represents text as weighted vocabulary features instead of filling every dimension in a dense vector. Sentence Transformers exposes SPLADE-style SparseEncoder models for producing those sparse query and document representations before they are stored in a search index.

Information-retrieval workloads should keep encode_query() and encode_document() separate because models can apply different prompts or routing to each input type. Both outputs still use the model vocabulary as their width, so the query and document tensors must agree on that dimension.

The max_active_dims limit bounds how many nonzero features each embedding retains. A successful smoke test should return positive active-dimension counts, a query that is more than 99 percent sparse, and the certificate-renewal document as the highest-scoring match.

1. Initialize sparse_embeddings_generate.py with the sparse encoder plus sample retrieval text.

   sparse_embeddings_generate.py

   from sentence_transformers import SparseEncoder
    
    
   model = SparseEncoder("rasyosef/splade-tiny", max_active_dims=64)
    
   documents = [
       "Reset expired password links from the account security page.",
       "Renew TLS certificates before the web server reload.",
       "Export customer invoices from the finance dashboard.",
   ]
   query = "web server certificate renewal"

   rasyosef/splade-tiny keeps the smoke test small. Production corpora need a sparse encoder trained for their language and retrieval domain.
   Related: How to choose a Sentence Transformers model for semantic search

2. Encode the document batch and one-item query list below the input block.

   document_embeddings = model.encode_document(
       documents,
       convert_to_sparse_tensor=True,
       show_progress_bar=False,
   )
   query_embedding = model.encode_query(
       [query],
       convert_to_sparse_tensor=True,
       show_progress_bar=False,
   )

   The one-item query list preserves a two-dimensional tensor shape that can be compared directly with the document batch.

3. Calculate the retrieval diagnostics below the encoding block.

   document_stats = SparseEncoder.sparsity(document_embeddings)
   query_stats = SparseEncoder.sparsity(query_embedding)
   query_tokens = model.decode(query_embedding, top_k=4)[0]
   scores = model.similarity(query_embedding, document_embeddings)[0]
   best_index = int(scores.argmax())

4. Add fail-capable embedding checks and result output below the statistics block.

   if document_embeddings.shape[1] != query_embedding.shape[1]:
       raise SystemExit("query and document vocabulary widths differ")
   if document_stats["active_dims"] <= 0 or query_stats["active_dims"] <= 0:
       raise SystemExit("the encoder returned an empty sparse embedding")
   if query_stats["sparsity_ratio"] < 0.99:
       raise SystemExit("the query embedding is not at least 99% sparse")
   if best_index != 1:
       raise SystemExit(f"unexpected top match: doc-{best_index + 1}")
    
   print(f"document shape: {tuple(document_embeddings.shape)}")
   print(f"query shape: {tuple(query_embedding.shape)}")
   print(f"document active dims: {document_stats['active_dims']:.1f}")
   print(f"query active dims: {query_stats['active_dims']:.1f}")
   print(f"query sparsity: {query_stats['sparsity_ratio']:.4f}")
   print("top query tokens:")
   for token, weight in query_tokens:
       print(f"  {token}: {weight:.3f}")
   print(f"top match: doc-{best_index + 1}")
   print(f"text: {documents[best_index]}")

5. Run the completed sparse embedding script.

   $ python sparse_embeddings_generate.py
   document shape: (3, 30522)
   query shape: (1, 30522)
   document active dims: 22.7
   query active dims: 15.0
   query sparsity: 0.9995
   top query tokens:
     certificate: 2.085
     web: 2.036
     server: 1.926
     renewal: 1.857
   top match: doc-2
   text: Renew TLS certificates before the web server reload.

   The script exits with an error if the vocabulary widths differ, either embedding is empty, the query falls below 99 percent sparsity, or another sample document ranks first.