liveBook · Manning

Similarity metric

As explained in Designing AI Systems

A similarity score is a numerical value representing how closely two items or vector representations match, with larger values indicating greater similarity.

A similarity metric turns a comparison between vectors into a score: larger values indicate closer matches. In vector search, the score ranks stored chunks against a query embedding and can determine whether a result is relevant enough for model context. section 5.4.1 section 5.4.3

A production search interface uses the score alongside retrieval controls:

  • Return the top-k chunks after ranking candidates by similarity. section 5.4.1
  • Discard results below score_threshold so weak matches do not consume context or confuse the response. section 5.4.1
  • Apply metadata filters before ranking, such as restricting results to legal-department documents. section 5.4.1
  • Return the score with chunk text, document identity, and metadata so callers can make inclusion and citation decisions. section 5.4.1

Cosine distance in pgvector

pgvector computes cosine distance with the <=> operator, where 0 means identical and larger values mean less similar. The implementation calculates 1 - distance, exposing a higher-is-better similarity score to the rest of the application. section 5.4.3

Listing 5.17 VectorStore abstract base class: search operation and result model
@dataclass
class SearchResult:
    chunk_id: str
    document_id: str
    text: str
    score: float    #A
    metadata: Dict[str, str]
 
class VectorStore(ABC):
    # ... write operations from Listing 5.16 ...
 
    @abstractmethod
    def search(
        self,
        index_name: str,
        query_embedding: List[float],
        top_k: int = 5,
        metadata_filters: Optional[Dict[str, str]] = None,
        score_threshold: Optional[float] = None
    ) -> List[SearchResult]:    #B
        """Find chunks most similar to the query embedding."""
        pass

Inspect the VectorStore search contract and SearchResult model, including query embeddings, top-k retrieval, metadata filters, thresholds, and returned scores. section 5.4.1

How Designing AI Systems covers it

How deep it goes
Defines score semantics and shows cosine-distance conversion, while leaving backend indexing details behind the interface.
Examples
Uses legal-department filtering, support-bot top-three retrieval, research-tool top-ten retrieval, and pgvector cosine scoring.
What it assumes
Assumes query embeddings, stored vectors, indexed chunks, and basic metadata filtering; defines the search contract rather than embedding generation.
What you can do after
Apply it via VectorStore or pgvector search by combining ranking, metadata filters, top-k limits, and score thresholds.
How it connects
Connects vector embeddings with vector stores, cosine distance, metadata filtering, top-k retrieval, and thresholding.

Also explained in

Compare how 14 books explain similarity metric →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Designing AI Systems. The section links point to the parts of the book it draws on.