A high-performance serverless API built with Cloudflare Workers that generates, stores, and searches text embeddings using OpenAI's text-embedding-3-small model and Cloudflare Vectorize for hybrid search capabilities.
API URL: https://embedapi.kprudhvi71.workers.dev
- Vector Embeddings: Generate embeddings using OpenAI's latest models
- Hybrid Search: Combine semantic similarity with metadata filtering
- Global Performance: Deployed on Cloudflare's edge network
- Vectorize Storage: Native vector database for optimal performance
- Metadata Support: Rich metadata filtering and storage
- RESTful API: Clean, intuitive endpoints
- Comprehensive Testing: Full test suite with Vitest
- Hybrid Search:
/searchendpoint with similarity + metadata filtering - Better Performance: Native vector operations vs. key-value storage
- Scalability: Optimized for large-scale vector workloads
- Cost Efficiency: More economical than storing large arrays in KV
- Advanced Filtering: Complex metadata queries and constraints
Try the hybrid search API:
# 1. Create an embedding with metadata
curl -X POST https://embedapi.kprudhvi71.workers.dev/embed \
-H "Authorization: Bearer YOUR_OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Cloudflare Workers enable edge computing",
"metadata": {"category": "infrastructure", "topic": "serverless"}
}'
# 2. Search for similar content
curl -X POST https://embedapi.kprudhvi71.workers.dev/search \
-H "Authorization: Bearer YOUR_OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "edge computing platforms",
"filter": {"category": "infrastructure"},
"topK": 3
}'Generates embeddings for text and stores them in Vectorize with optional metadata.
Request:
curl -X POST https://embedapi.kprudhvi71.workers.dev/embed \
-H "Authorization: Bearer your-openai-api-key" \
-H "Content-Type: application/json" \
-d '{
"text": "Machine learning is transforming software development",
"metadata": {
"category": "technology",
"source": "blog",
"author": "jane_doe",
"timestamp": "2024-01-15"
}
}'Response:
{
"id": "a1b2c3d4e5f6789",
"message": "Embedding created successfully",
"metadata": {
"text": "Machine learning is transforming software development",
"category": "technology",
"source": "blog",
"author": "jane_doe",
"timestamp": "2024-01-15"
}
}Retrieves stored text, embedding, and metadata by ID.
Request:
curl https://embedapi.kprudhvi71.workers.dev/embed/a1b2c3d4e5f6789Response:
{
"id": "a1b2c3d4e5f6789",
"text": "Machine learning is transforming software development",
"embedding": [0.1, 0.2, 0.3, ...],
"metadata": {
"category": "technology",
"source": "blog",
"author": "jane_doe",
"timestamp": "2024-01-15"
}
}Performs semantic similarity search with optional metadata filtering.
Request:
curl -X POST https://embedapi.kprudhvi71.workers.dev/search \
-H "Authorization: Bearer your-openai-api-key" \
-H "Content-Type: application/json" \
-d '{
"query": "AI and software engineering",
"topK": 5,
"filter": {
"category": "technology",
"author": "jane_doe"
},
"includeValues": false,
"returnSimilarityScores": true
}'Response:
{
"query": "AI and software engineering",
"results": [
{
"id": "a1b2c3d4e5f6789",
"score": 0.94,
"text": "Machine learning is transforming software development",
"metadata": {
"category": "technology",
"source": "blog",
"author": "jane_doe"
}
}
],
"total": 1
}Search Parameters:
query(required): Text to search fortopK(optional, default: 5): Number of results to returnfilter(optional): Metadata filtering conditionsincludeValues(optional, default: false): Include embedding vectorsincludeMetadata(optional, default: true): Include metadatareturnSimilarityScores(optional, default: true): Include similarity scores
Removes an embedding from Vectorize.
Request:
curl -X DELETE https://embedapi.kprudhvi71.workers.dev/embed/a1b2c3d4e5f6789Response:
{
"message": "Embedding deleted successfully",
"id": "a1b2c3d4e5f6789"
}- Node.js 18+
- Cloudflare account with Workers and Vectorize access
- OpenAI API key
- Clone this repository:
git clone https://github.com/prudhvi1709/embedapi.git
cd embedapi- Install dependencies:
npm install- Login to Cloudflare:
npx wrangler login- Create the Vectorize index:
npx wrangler vectorize create embeddings-index --dimensions=1536 --metric=cosine- Create KV namespace (for backward compatibility):
npx wrangler kv namespace create "EMBEDDINGS_KV"- Update
wrangler.tomlwith your namespace IDs (commands above show the IDs to use).
Run locally:
npm run devNote: Local development uses mocked Vectorize operations. For full testing, deploy to Cloudflare.
Deploy to Cloudflare Workers:
npm run deployFind content by meaning, not just keywords:
# Search for conceptually similar content
curl -X POST .../search -d '{"query": "machine learning applications"}'Filter by metadata and find similar items:
curl -X POST .../search -d '{
"query": "user preferences",
"filter": {"content_type": "article", "language": "en"}
}'Power AI chatbots with contextual knowledge:
# Find relevant context for AI responses
curl -X POST .../search -d '{
"query": "customer support question",
"filter": {"domain": "technical_docs"},
"topK": 3
}'Find similar or duplicate content:
curl -X POST .../search -d '{
"query": "potential duplicate content",
"returnSimilarityScores": true
}'┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Cloudflare │ │ OpenAI │ │ Vectorize │
│ Workers │───▶│ Embeddings │ │ Database │
│ │ │ API │ │ │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │
└───────────────────────────────────────────────┘
Hybrid Search + Storage
- Native vector operations: Cosine similarity, dot product, euclidean distance
- Metadata filtering: Complex queries with multiple conditions
- Better performance: Optimized for high-dimensional vector operations
- Cost efficiency: No large JSON serialization/deserialization
- Scalability: Built for millions of vectors
- Vectorize: 200,000 vectors (free tier), 10M+ (paid)
- Workers: 100,000 requests/day (free tier)
- OpenAI: Rate limits vary by plan
- Vector dimensions: 1536 (text-embedding-3-small)
If you're upgrading from the KV-based version:
- Gradual migration: Both KV and Vectorize bindings are configured
- Backup data: Export existing embeddings before migration
- Update clients: Use new
/searchendpoint for hybrid search - Remove KV: After migration, remove KV binding from
wrangler.toml
- API Keys: OpenAI keys passed per-request, never stored
- CORS: Enabled for cross-origin requests
- Input validation: Comprehensive request validation
- Rate limiting: Inherit from Cloudflare Workers and OpenAI
// Store document with rich metadata
await fetch('/embed', {
method: 'POST',
headers: { 'Authorization': 'Bearer sk-...', 'Content-Type': 'application/json' },
body: JSON.stringify({
text: document.content,
metadata: {
title: document.title,
author: document.author,
category: document.category,
published_date: document.date,
tags: document.tags
}
})
});
// Search with filters
const results = await fetch('/search', {
method: 'POST',
headers: { 'Authorization': 'Bearer sk-...', 'Content-Type': 'application/json' },
body: JSON.stringify({
query: userQuery,
filter: {
category: selectedCategory,
published_date: { $gte: '2024-01-01' }
},
topK: 10
})
});// Product search with metadata filtering
const productSearch = await fetch('/search', {
method: 'POST',
body: JSON.stringify({
query: 'comfortable running shoes',
filter: {
category: 'footwear',
price_range: 'mid-tier',
brand: ['nike', 'adidas', 'asics']
},
topK: 20
})
});- Fork the repository
- Create a feature branch:
git checkout -b feature/vectorize-enhancement - Make changes and test:
npm test - Submit a pull request
- Added: Cloudflare Vectorize for vector storage
- Added:
/searchendpoint for hybrid search - Added:
/deleteendpoint for cleanup operations - Added: Rich metadata support and filtering
- Improved: Performance and scalability
- Improved: Error handling and validation
- Basic embedding generation and storage using KV
- OpenAI integration
- Simple CRUD operations
This is Demo. contains no confidential data/IP