Embeddings And Similarity

---
name: embeddings-and-similarity
description: "Dense SentenceTransformer embedding and similarity workflows for
  text or multimodal inputs, including construction,
  encode/encode_query/encode_document options, prompt and truncation decisions,
  precision, normalization, batching/devices, local cache cautions, and output
  validation."
disable-model-invocation: true
metadata:
  disco-role: operating
license: Apache 2.0
---

# Embeddings and Similarity

Use this sub-skill when the user needs dense `SentenceTransformer` embeddings or direct embedding similarity scores.

## Route Here

- Construct or load a `SentenceTransformer` for embedding inference.
- Encode text, images, audio, video, multimodal dicts, or chat-style message inputs with dense embedding models.
- Choose between `encode`, `encode_query`, and `encode_document`, including prompt-aware retrieval embedding.
- Tune `batch_size`, `device`, `precision`, `truncate_dim`, `normalize_embeddings`, output conversion, and similarity metric choices.
- Validate embedding shapes, dtypes, normalization, and similarity matrix or pairwise similarity results.

## Route Elsewhere

- Use `../retrieval-and-utilities/` for `util.semantic_search`, hard-negative mining, paraphrase mining, quantized retrieval indexes, or vector database workflows.
- Use `../evaluation-and-training/` for fine-tuning, losses, trainers, evaluators, and dataset formatting.
- Use `../backend-export-optimization/` for ONNX/OpenVINO backend selection, export, optimization, or deployment packaging.
- Use `../reranking-cross-encoder/` for `CrossEncoder.predict`, `CrossEncoder.rank`, or reranker scoring.
- Use `../sparse-encoder-search/` for `SparseEncoder`, SPLADE-style sparse vectors, sparse search, or sparsity diagnostics.

## Fast Workflow

1. Confirm the task is dense embedding inference, not retrieval orchestration or model training.
2. Load a model with explicit network/cache policy, e.g. `SentenceTransformer(model_id_or_path, local_files_only=True)` for offline use.
3. Prefer `encode_query` and `encode_document` for retrieval models with query/document prompts; use `encode` for symmetric STS, clustering, or classification features.
4. Set output options deliberately: `convert_to_numpy=True` for NumPy workflows, `convert_to_tensor=True` for Torch workflows, and avoid both being ambiguous in reusable code.
5. Validate the returned row count, embedding dimension, dtype, finite values, and similarity output shape before using scores downstream.

## References

- API details: `references/api-reference.md`
- Workflow recipes: `references/workflows.md`
- Failure diagnosis: `references/troubleshooting.md`
- Safe smoke helper: `scripts/dense_embedding_smoke.py`