Cosine distance measures how different two vectors point by subtracting cosine similarity from one. A distance of 0 means identical direction; 2 means opposite direction. section 6.2.2 section 6.1.3
Use this mental model when interpreting retrieval scores:
- Compare direction rather than vector magnitude, making the metric useful when document length should not dominate retrieval. section 6.1.3
- Read smaller distances as better matches: 0 indicates identical items, while larger values indicate greater semantic dissimilarity. section 6.2.2
- Watch for false matches with extremely sparse vectors, where a few rare shared terms can create a similar angle. section 6.1.3
Retrieving documents with Chroma DB
Convert documents and a query into embeddings, store the document embeddings in a Chroma collection, and query for the nearest results. Chroma returns distances alongside identifiers and document text, so rank results by the lowest scores. section 6.2.2
Listing 6.5 document_query_chromadb.py (relevant code sections)
embeddings = [get_embedding(doc) for doc in documents] #1
ids = [f"id{i}" for i in range(len(documents))] #2
chroma_client = chromadb.Client() #2
collection = chroma_client.create_collection( #2
name="documents") #2
collection.add( #3
embeddings=embeddings,
documents=documents,
ids=ids
)
def query_chromadb(query, top_n=2): #4
query_embedding = get_embedding(query)
results = collection.query(
query_embeddings=[query_embedding],
n_results=top_n
)
return [(id, score, text) for id, score, text in
zip(results['ids'][0],
results['distances'][0],
results['documents'][0])]
while True: #5
query = input("Enter a search query (or 'exit' to stop): ")
if query.lower() == 'exit':
break
top_n = int(input("How many top matches do you want to see? "))
search_results = query_chromadb(query, top_n)
print("Top Matched Documents:")
for id, score, text in search_results:
print(f"""
ID:{id} TEXT: {text} SCORE: {round(score, 2)}
""") #5
print("\n")
###Output
Enter a search query (or 'exit' to stop): dogs are lazy
How many top matches do you want to see? 3
Top Matched Documents:
ID:id7 TEXT: The dog is lazy but the brown fox is quick! SCORE: 0.24
ID:id5 TEXT: The brown fox is quick and the blue dog is lazy! SCORE: 0.28
ID:id2 TEXT: The quick brown fox jumps over the lazy dog. SCORE: 0.29
Inspect the smallest working pattern: create embeddings, add documents to a Chroma collection, embed a query, and return identifiers, distances, and text. section 6.2.2
