README.md

metadata

title: MUVERA
emoji: 🌍
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.45.0
app_file: app.py
pinned: false

🔎 MuVERA Demo: Multi‑Vector Retrieval vs Single‑Vector Search

This Hugging Face Space demonstrates the key ideas behind Google’s MuVERA research:

👉 Making multi‑vector retrieval (each document represented by multiple embeddings, one per passage) as efficient as single‑vector search (entire doc collapsed into one vector).

---

✨ Why This Matters

• Single‑Vector Search (Baseline):
  Each document gets one “centroid” embedding. Fast, but it often misses fine‑grained details in long documents.

• MuVERA‑Inspired Multi‑Vector Search:
  Each document is broken into multiple passage vectors. Queries can match exact passages, not just a fuzzy doc‑average.

---

🧠 Key Difference:

• Single‑Vector: Compress all document meaning into one vector → loses detail.
• Multi‑Vector (MuVERA): Keep multiple passage vectors → allows passage‑level precision while remaining efficient.

---

🚀 Quick Example

Upload "100 coding interview questions.docx" and search for:

Query: binary tree

• Single‑Vector Results (doc‑level):
  Returns the whole doc with generic preview text — it “knows” the doc is about coding, but isn’t confident about binary trees.

• MuVERA Results (snippet‑level):
  Returns precise questions like:

  • “Invert a binary tree”
  • “Check if a binary tree is balanced”
  • “Lowest Common Ancestor in a Binary Tree”

➡️ The difference is striking — showing why multi‑vector retrieval is more expressive and useful.

---

🛠 How It Works

1. Embeddings:

   • Uses sentence-transformers/all-MiniLM-L6-v2 (Apache 2.0 license, free to use).
   • Falls back to a dummy vectorizer if the model isn’t available.

2. Index Structures:

   • SingleVectorIndex: Stores one centroid vector per doc.
   • MuVERAIndex: Stores all passage vectors per doc, with a centroid used for fast filtering.

3. Retrieval Flow:

   • Single‑Vector: Compare query with doc centroids → return top docs
   • MuVERA:
     • Pre‑filter docs by centroid
     • Re‑rank all passages in shortlisted docs
     • Return globally top‑scoring snippets

---

📂 File Uploads

• Accepts .docx or .txt files
• Splits into paragraphs/lines → embeds each passage → indexed immediately

---

🚦 Getting Started (if you fork this Space)

1. Add files:

   • app.py → main Gradio application
   • requirements.txt → dependencies

2. Requirements:

gradio==4.29.0
numpy==1.26.4
python-docx==1.0.1
sentence-transformers==2.7.0

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference