Hugging Face's logo

Spaces:
vk98
/
colpali-backend-api
Running

App Files Community
colpali-backend-api
File size: 3,908 Bytes 
5dfbe50
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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
 
# Hono Proxy - Next.js Compatibility Guide

This Hono proxy server is designed to be a **drop-in replacement** for the Next.js API routes, providing 100% compatibility with the existing frontend.

## Endpoint Mapping

The Hono proxy implements all endpoints exactly as they exist in the Next.js implementation:

| Next.js API Route | Backend Endpoint | Method | Description |
|-------------------|------------------|---------|-------------|
| `/api/colpali-search` | `/fetch_results` | GET | Search with ColPali ranking |
| `/api/full-image` | `/full_image` | GET | Get full resolution image |
| `/api/query-suggestions` | `/suggestions` | GET | Autocomplete suggestions |
| `/api/similarity-maps` | `/get_sim_map` | GET | Generate similarity visualization |
| `/api/visual-rag-chat` | `/get-message` | GET (SSE) | Stream chat responses |

## Parameter Compatibility

All query parameters are preserved exactly as in Next.js:

### Search
```
GET /api/colpali-search?query=annual+report&ranking=hybrid
```

### Full Image
```
GET /api/full-image?docId=abc123
```

### Suggestions
```
GET /api/query-suggestions?query=ann
```

### Similarity Maps
```
GET /api/similarity-maps?queryId=123&idx=0&token=report&tokenIdx=2
```

### Visual RAG Chat (SSE)
```
GET /api/visual-rag-chat?queryId=123&query=What+is+revenue&docIds=abc,def,ghi
```

## Frontend Integration

To use the Hono proxy with your Next.js frontend:

1. Update your environment variable:
   ```env
   # .env.local
   NEXT_PUBLIC_API_URL=http://localhost:4000
   ```

2. Update your API calls (if using relative paths):
   ```typescript
   // If currently using relative paths like:
   const response = await fetch('/api/colpali-search?query=...');
   
   // Change to:
   const response = await fetch(`${process.env.NEXT_PUBLIC_API_URL}/api/colpali-search?query=...`);
   ```

3. Or use a base URL configuration:
   ```typescript
   // utils/api.ts
   export const API_BASE = process.env.NEXT_PUBLIC_API_URL || '';
   
   // In components:
   const response = await fetch(`${API_BASE}/api/colpali-search?query=...`);
   ```

## Response Format

All responses are identical to what Next.js returns:

- Search results include the same Vespa response structure
- Full images return `{ base64_image: "..." }`
- Suggestions return `{ suggestions: [...] }`
- Similarity maps return HTML content
- SSE chat streams the same event format

## Additional Features

While maintaining 100% compatibility, the Hono proxy adds:

- **Caching**: Search results and images are cached
- **Rate Limiting**: Prevents backend overload
- **Health Checks**: Monitor backend availability
- **Request IDs**: Track requests across systems
- **Performance**: Faster response times with caching

## Migration Path

1. **No Frontend Changes Required**: The Hono proxy mimics Next.js API routes exactly
2. **Gradual Migration**: Can run both Next.js and Hono simultaneously on different ports
3. **Environment-based**: Use environment variables to switch between implementations

## Testing Compatibility

Test script to verify all endpoints work:

```bash
# Search
curl "http://localhost:4000/api/colpali-search?query=annual+report&ranking=hybrid"

# Full Image  
curl "http://localhost:4000/api/full-image?docId=abc123"

# Suggestions
curl "http://localhost:4000/api/query-suggestions?query=ann"

# Similarity Map
curl "http://localhost:4000/api/similarity-maps?queryId=123&idx=0&token=report&tokenIdx=2"

# Visual RAG Chat (SSE)
curl -N "http://localhost:4000/api/visual-rag-chat?queryId=123&query=What+is+revenue&docIds=abc,def"
```

## Benefits Over Next.js API Routes

1. **Independent Scaling**: Scale API separately from frontend
2. **Better Performance**: Dedicated API server with caching
3. **Deployment Flexibility**: Deploy anywhere (Docker, K8s, serverless)
4. **Monitoring**: Built-in health checks and metrics
5. **Security**: Rate limiting and request validation