File size: 3,593 Bytes
c59d808 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 |
# 🚨 Embedding Troubleshooting Quick Start
## Common Error Messages & Instant Fixes
### ⚠️ "shapes (768,) and (384,) not aligned"
**What it means:** Your query embeddings (768D) don't match stored embeddings (384D)
**Instant fix:**
```bash
# Open .env file and change:
EMBEDDING_PROVIDER=huggingface
HUGGINGFACE_EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
# Restart your application
```
### ⚠️ "shapes (384,) and (768,) not aligned"
**What it means:** Your query embeddings (384D) don't match stored embeddings (768D)
**Instant fix:**
```bash
# Open .env file and change:
EMBEDDING_PROVIDER=ollama
OLLAMA_EMBEDDING_MODEL=nomic-embed-text:v1.5
# Make sure Ollama is running: ollama serve
# Pull the model: ollama pull nomic-embed-text:v1.5
# Restart your application
```
### ⚠️ "shapes (1536,) and (384,) not aligned"
**What it means:** Your query embeddings (1536D) don't match stored embeddings (384D)
**Instant fix:**
```bash
# Open .env file and change:
EMBEDDING_PROVIDER=huggingface
HUGGINGFACE_EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
# Restart your application
```
## 🔧 5-Minute Fix Guide
### Step 1: Identify Your Error (30 seconds)
Look at your error message and find the dimension numbers:
- `shapes (X,) and (Y,)` → X = query dimensions, Y = stored dimensions
### Step 2: Choose Matching Model (1 minute)
| Stored Dimensions (Y) | Set in .env |
|---------------------|-------------|
| 384 | `EMBEDDING_PROVIDER=huggingface`<br/>`HUGGINGFACE_EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2` |
| 768 | `EMBEDDING_PROVIDER=ollama`<br/>`OLLAMA_EMBEDDING_MODEL=nomic-embed-text:v1.5` |
| 1024 | `EMBEDDING_PROVIDER=ollama`<br/>`OLLAMA_EMBEDDING_MODEL=mxbai-embed-large` |
| 1536 | `EMBEDDING_PROVIDER=openai`<br/>`OPENAI_EMBEDDING_MODEL=text-embedding-3-small` |
### Step 3: Update Configuration (2 minutes)
```bash
# Edit your .env file
nano .env # or use your preferred editor
# Find the EMBEDDING_PROVIDER lines and update them
# Save the file
```
### Step 4: Restart Application (1 minute)
```bash
# Kill current process (Ctrl+C)
# Restart
uvicorn app:app --reload
```
### Step 5: Test (30 seconds)
```bash
# Test with a simple query
curl -X POST "http://localhost:8080/chat" \
-H "Content-Type: application/json" \
-d '{"message": "chicken recipe"}'
```
## 🔍 Alternative: Start Fresh
If you prefer to use a different embedding model permanently:
### Option A: Regenerate Database (5 minutes)
```bash
# 1. Choose your preferred model in .env
EMBEDDING_PROVIDER=ollama
OLLAMA_EMBEDDING_MODEL=nomic-embed-text:v1.5
# 2. Enable database refresh
DB_REFRESH_ON_START=true
# 3. Restart application (this will rebuild everything)
uvicorn app:app --reload
# 4. IMPORTANT: Disable refresh after startup
DB_REFRESH_ON_START=false
```
### Option B: Switch Vector Store (2 minutes)
```bash
# Switch to ChromaDB (will create fresh database)
VECTOR_STORE_PROVIDER=chromadb
# Restart application
uvicorn app:app --reload
```
## ⚡ Prevention Tips
### Document Your Choice
Add a comment to your .env file:
```bash
# Created 2025-08-27 with all-MiniLM-L6-v2 (384 dimensions)
EMBEDDING_PROVIDER=huggingface
HUGGINGFACE_EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
```
### Consistent Development
If working in a team, ensure everyone uses the same configuration:
```bash
# Share this in your team chat:
# "Use EMBEDDING_PROVIDER=huggingface with all-MiniLM-L6-v2"
```
---
**Still stuck?** Check the full [Embedding Compatibility Guide](./embedding-compatibility-guide.md) for detailed explanations.
|