Isaac Quarenta commited on
Commit
76ddd08
Β·
1 Parent(s): 3dab236

feat: OpenRouter Nemotron 3 Embed 1B as tier 1, Cloudflare bge-m3 tier 2, auto-fallback

Browse files
Files changed (1) hide show
  1. modules/cloudflare_embeddings.py +210 -125
modules/cloudflare_embeddings.py CHANGED
@@ -1,18 +1,11 @@
1
  """
2
- Cloudflare Workers AI Embeddings Module
3
 
4
- Wraps the Cloudflare Workers AI bge-m3 model for text embeddings via their REST API.
5
- bge-m3 is a 1024-dimensional multilingual embedding model optimized for retrieval
6
- tasks, supporting over 100 languages with strong performance on semantic similarity
7
- and information retrieval benchmarks.
8
 
9
- Usage:
10
- from modules.cloudflare_embeddings import get_cloudflare_embeddings
11
-
12
- embedder = get_cloudflare_embeddings()
13
- if embedder.is_available():
14
- vector = embedder.embed("Hello world")
15
- vectors = embedder.embed_batch(["Hello", "World"])
16
  """
17
 
18
  import os
@@ -24,175 +17,267 @@ import requests
24
  from loguru import logger
25
 
26
 
27
- class CloudflareEmbeddings:
 
 
 
 
28
  """
29
- Wrapper for Cloudflare Workers AI bge-m3 embedding model.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
30
 
31
- bge-m3 produces 1024-dimensional multilingual embeddings optimized for
32
- retrieval. Supports single and batch embedding via Cloudflare's REST API.
 
33
 
34
- Credentials are read from environment variables:
35
- - CLOUDFLARE_ACCOUNT_ID
36
- - CLOUDFLARE_API_KEY or CLOUDFALRE_API_KEY (legacy typo supported)
 
37
  """
38
 
39
  EMBEDDING_DIM = 1024
40
  API_URL_TEMPLATE = "https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/@cf/baai/bge-m3"
41
- MIN_REQUEST_INTERVAL = 0.1 # seconds between requests (rate limit)
42
 
43
  def __init__(self, account_id: Optional[str] = None, api_key: Optional[str] = None):
44
- """
45
- Initialize CloudflareEmbeddings.
46
-
47
- Args:
48
- account_id: Cloudflare account ID. Falls back to CLOUDFLARE_ACCOUNT_ID env var.
49
- api_key: Cloudflare API key. Falls back to CLOUDFLARE_API_KEY or CLOUDFALRE_API_KEY env var.
50
- """
51
  self._account_id = account_id or os.getenv("CLOUDFLARE_ACCOUNT_ID")
52
- # Support both correct and legacy typo env var names
53
  self._api_key = api_key or os.getenv("CLOUDFLARE_API_KEY") or os.getenv("CLOUDFALRE_API_KEY")
54
  self._last_request_time = 0.0
55
 
56
  def is_available(self) -> bool:
57
- """Check if required credentials are configured."""
58
  return bool(self._account_id and self._api_key)
59
 
60
- def _rate_limit(self) -> None:
61
- """Enforce minimum interval between API requests."""
62
  elapsed = time.time() - self._last_request_time
63
  if elapsed < self.MIN_REQUEST_INTERVAL:
64
  time.sleep(self.MIN_REQUEST_INTERVAL - elapsed)
65
  self._last_request_time = time.time()
66
 
67
- def _build_headers(self) -> dict:
68
- """Build authorization headers for the API request."""
69
- return {
70
- "Authorization": f"Bearer {self._api_key}",
71
- "Content-Type": "application/json",
72
- }
73
-
74
  def _post(self, payload: dict) -> Optional[dict]:
75
- """
76
- Send a POST request to the Cloudflare AI endpoint.
77
-
78
- Args:
79
- payload: JSON body to send.
80
-
81
- Returns:
82
- Parsed JSON response dict, or None on failure.
83
- """
84
  if not self.is_available():
85
- logger.warning("Cloudflare embeddings not available: missing credentials")
86
  return None
87
-
88
  self._rate_limit()
89
  url = self.API_URL_TEMPLATE.format(account_id=self._account_id)
90
-
91
  try:
92
- response = requests.post(url, headers=self._build_headers(), json=payload, timeout=30)
93
- response.raise_for_status()
94
- data = response.json()
95
-
96
  if not data.get("success"):
97
- errors = data.get("errors", [])
98
- logger.error(f"Cloudflare API error: {errors}")
99
  return None
100
-
101
  return data
102
-
103
- except requests.exceptions.Timeout:
104
- logger.error("Cloudflare embeddings request timed out")
105
- return None
106
- except requests.exceptions.ConnectionError:
107
- logger.error("Cloudflare embeddings connection failed")
108
- return None
109
- except requests.exceptions.HTTPError as e:
110
- status = e.response.status_code if e.response else "unknown"
111
- logger.error(f"Cloudflare embeddings HTTP error {status}: {e}")
112
- return None
113
  except Exception as e:
114
- logger.error(f"Cloudflare embeddings unexpected error: {e}")
115
  return None
116
 
117
  def embed(self, text: str) -> Optional[np.ndarray]:
118
- """
119
- Embed a single text string.
120
-
121
- Args:
122
- text: The text to embed.
123
-
124
- Returns:
125
- 1024-dimensional numpy array, or None on failure.
126
- """
127
  try:
128
  result = self._post({"input": text})
129
- if result is None:
130
  return None
131
-
132
- embedding = result.get("result", {}).get("data")
133
- if not embedding:
134
- logger.error("Cloudflare embeddings: empty result data")
135
  return None
136
-
137
- vector = np.array(embedding, dtype=np.float32)
138
- if vector.shape != (self.EMBEDDING_DIM,):
139
- logger.warning(
140
- f"Cloudflare embeddings: unexpected dimension {vector.shape}, expected ({self.EMBEDDING_DIM},)"
141
- )
142
- return vector
143
-
144
  except Exception as e:
145
  logger.error(f"Cloudflare embed failed: {e}")
146
  return None
147
 
148
  def embed_batch(self, texts: List[str]) -> Optional[np.ndarray]:
149
- """
150
- Embed multiple texts in a single API call.
151
-
152
- Args:
153
- texts: List of text strings to embed.
154
-
155
- Returns:
156
- (N, 1024) numpy array, or None on failure.
157
- """
158
  if not texts:
159
  return np.array([], dtype=np.float32).reshape(0, self.EMBEDDING_DIM)
160
-
161
  try:
162
  result = self._post({"input": texts})
163
- if result is None:
164
  return None
165
-
166
  data = result.get("result", {}).get("data")
167
  if not data:
168
- logger.error("Cloudflare embeddings batch: empty result data")
169
  return None
170
-
171
- vectors = np.array(data, dtype=np.float32)
172
- if vectors.ndim != 2 or vectors.shape[1] != self.EMBEDDING_DIM:
173
- logger.warning(
174
- f"Cloudflare embeddings batch: unexpected shape {vectors.shape}, "
175
- f"expected (N, {self.EMBEDDING_DIM})"
176
- )
177
- return vectors
178
-
179
  except Exception as e:
180
  logger.error(f"Cloudflare embed_batch failed: {e}")
181
  return None
182
 
183
 
184
- # Singleton instance
185
- _cloudflare_embeddings_instance: Optional[CloudflareEmbeddings] = None
186
-
187
 
188
- def get_cloudflare_embeddings() -> CloudflareEmbeddings:
189
  """
190
- Get or create the singleton CloudflareEmbeddings instance.
191
-
192
- Returns:
193
- The shared CloudflareEmbeddings instance.
194
  """
195
- global _cloudflare_embeddings_instance
196
- if _cloudflare_embeddings_instance is None:
197
- _cloudflare_embeddings_instance = CloudflareEmbeddings()
198
- return _cloudflare_embeddings_instance
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
  """
2
+ Remote Embeddings Module β€” Multi-Provider with Fallback Chain
3
 
4
+ TIER 1: OpenRouter Nemotron 3 Embed 1B (free, no limit, 1024d)
5
+ TIER 2: Cloudflare Workers AI bge-m3 (free 10k/day, 1024d)
6
+ TIER 3: SentenceTransformer local (offline fallback)
 
7
 
8
+ All providers produce 1024-dimensional embeddings for compatibility.
 
 
 
 
 
 
9
  """
10
 
11
  import os
 
17
  from loguru import logger
18
 
19
 
20
+ # ============================================================
21
+ # TIER 1: OpenRouter Nemotron 3 Embed 1B (free, no limit)
22
+ # ============================================================
23
+
24
+ class OpenRouterEmbeddings:
25
  """
26
+ OpenRouter Nemotron 3 Embed 1B β€” free text embedding model.
27
+ 1024 dimensions, high quality for RAG/retrieval tasks.
28
+ API: OpenAI-compatible /v1/embeddings endpoint.
29
+ """
30
+
31
+ EMBEDDING_DIM = 1024
32
+ MODEL = "nvidia/nemotron-3-embed-1b-v2"
33
+ API_URL = "https://openrouter.ai/api/v1/embeddings"
34
+ MIN_REQUEST_INTERVAL = 0.1
35
+
36
+ def __init__(self, api_key: Optional[str] = None):
37
+ self._api_key = api_key or os.getenv("OPENROUTER_API_KEY")
38
+ self._last_request_time = 0.0
39
+
40
+ def is_available(self) -> bool:
41
+ return bool(self._api_key)
42
+
43
+ def _embed_via_openai(self, input_data, api_key: str) -> Optional[dict]:
44
+ """Call OpenRouter embeddings endpoint (OpenAI-compatible)."""
45
+ headers = {
46
+ "Authorization": f"Bearer {api_key}",
47
+ "Content-Type": "application/json",
48
+ }
49
+ payload = {
50
+ "model": self.MODEL,
51
+ "input": input_data,
52
+ }
53
+ elapsed = time.time() - self._last_request_time
54
+ if elapsed < self.MIN_REQUEST_INTERVAL:
55
+ time.sleep(self.MIN_REQUEST_INTERVAL - elapsed)
56
+ self._last_request_time = time.time()
57
+
58
+ try:
59
+ resp = requests.post(self.API_URL, headers=headers, json=payload, timeout=30)
60
+ resp.raise_for_status()
61
+ return resp.json()
62
+ except Exception as e:
63
+ logger.error(f"OpenRouter embeddings error: {e}")
64
+ return None
65
+
66
+ def embed(self, text: str) -> Optional[np.ndarray]:
67
+ """Embed a single text string β†’ 1024-dim numpy array."""
68
+ try:
69
+ data = self._embed_via_openai(text, self._api_key)
70
+ if not data:
71
+ return None
72
+ emb_list = data.get("data", [{}])[0].get("embedding")
73
+ if not emb_list:
74
+ logger.error("OpenRouter embeddings: empty result")
75
+ return None
76
+ return np.array(emb_list, dtype=np.float32)
77
+ except Exception as e:
78
+ logger.error(f"OpenRouter embed failed: {e}")
79
+ return None
80
+
81
+ def embed_batch(self, texts: List[str]) -> Optional[np.ndarray]:
82
+ """Embed multiple texts β†’ (N, 1024) numpy array."""
83
+ if not texts:
84
+ return np.array([], dtype=np.float32).reshape(0, self.EMBEDDING_DIM)
85
+ try:
86
+ data = self._embed_via_openai(texts, self._api_key)
87
+ if not data:
88
+ return None
89
+ items = data.get("data", [])
90
+ vectors = [item.get("embedding", []) for item in items]
91
+ if not vectors or not vectors[0]:
92
+ logger.error("OpenRouter embeddings batch: empty result")
93
+ return None
94
+ return np.array(vectors, dtype=np.float32)
95
+ except Exception as e:
96
+ logger.error(f"OpenRouter embed_batch failed: {e}")
97
+ return None
98
+
99
 
100
+ # ============================================================
101
+ # TIER 2: Cloudflare Workers AI bge-m3 (free 10k/day)
102
+ # ============================================================
103
 
104
+ class CloudflareEmbeddings:
105
+ """
106
+ Cloudflare Workers AI bge-m3 β€” multilingual embedding model.
107
+ 1024 dimensions, optimized for retrieval in 100+ languages.
108
  """
109
 
110
  EMBEDDING_DIM = 1024
111
  API_URL_TEMPLATE = "https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/@cf/baai/bge-m3"
112
+ MIN_REQUEST_INTERVAL = 0.1
113
 
114
  def __init__(self, account_id: Optional[str] = None, api_key: Optional[str] = None):
 
 
 
 
 
 
 
115
  self._account_id = account_id or os.getenv("CLOUDFLARE_ACCOUNT_ID")
 
116
  self._api_key = api_key or os.getenv("CLOUDFLARE_API_KEY") or os.getenv("CLOUDFALRE_API_KEY")
117
  self._last_request_time = 0.0
118
 
119
  def is_available(self) -> bool:
 
120
  return bool(self._account_id and self._api_key)
121
 
122
+ def _rate_limit(self):
 
123
  elapsed = time.time() - self._last_request_time
124
  if elapsed < self.MIN_REQUEST_INTERVAL:
125
  time.sleep(self.MIN_REQUEST_INTERVAL - elapsed)
126
  self._last_request_time = time.time()
127
 
 
 
 
 
 
 
 
128
  def _post(self, payload: dict) -> Optional[dict]:
 
 
 
 
 
 
 
 
 
129
  if not self.is_available():
 
130
  return None
 
131
  self._rate_limit()
132
  url = self.API_URL_TEMPLATE.format(account_id=self._account_id)
133
+ headers = {"Authorization": f"Bearer {self._api_key}", "Content-Type": "application/json"}
134
  try:
135
+ resp = requests.post(url, headers=headers, json=payload, timeout=30)
136
+ resp.raise_for_status()
137
+ data = resp.json()
 
138
  if not data.get("success"):
139
+ logger.error(f"Cloudflare API error: {data.get('errors', [])}")
 
140
  return None
 
141
  return data
 
 
 
 
 
 
 
 
 
 
 
142
  except Exception as e:
143
+ logger.error(f"Cloudflare embeddings error: {e}")
144
  return None
145
 
146
  def embed(self, text: str) -> Optional[np.ndarray]:
 
 
 
 
 
 
 
 
 
147
  try:
148
  result = self._post({"input": text})
149
+ if not result:
150
  return None
151
+ emb = result.get("result", {}).get("data")
152
+ if not emb:
 
 
153
  return None
154
+ return np.array(emb, dtype=np.float32)
 
 
 
 
 
 
 
155
  except Exception as e:
156
  logger.error(f"Cloudflare embed failed: {e}")
157
  return None
158
 
159
  def embed_batch(self, texts: List[str]) -> Optional[np.ndarray]:
 
 
 
 
 
 
 
 
 
160
  if not texts:
161
  return np.array([], dtype=np.float32).reshape(0, self.EMBEDDING_DIM)
 
162
  try:
163
  result = self._post({"input": texts})
164
+ if not result:
165
  return None
 
166
  data = result.get("result", {}).get("data")
167
  if not data:
 
168
  return None
169
+ return np.array(data, dtype=np.float32)
 
 
 
 
 
 
 
 
170
  except Exception as e:
171
  logger.error(f"Cloudflare embed_batch failed: {e}")
172
  return None
173
 
174
 
175
+ # ============================================================
176
+ # UNIFIED PROVIDER with 3-tier fallback
177
+ # ============================================================
178
 
179
+ class RemoteEmbeddings:
180
  """
181
+ Unified embedding provider with automatic fallback:
182
+ 1. OpenRouter Nemotron 3 Embed 1B (free, no limit)
183
+ 2. Cloudflare bge-m3 (free 10k/day)
184
+ 3. Returns None (caller uses SentenceTransformer local fallback)
185
  """
186
+
187
+ def __init__(self):
188
+ self._openrouter = OpenRouterEmbeddings()
189
+ self._cloudflare = CloudflareEmbeddings()
190
+ self._active_provider = None
191
+ self._init_provider()
192
+
193
+ def _init_provider(self):
194
+ if self._openrouter.is_available():
195
+ self._active_provider = "openrouter"
196
+ logger.info("πŸ€— [EMBEDDINGS] Tier 1: OpenRouter Nemotron 3 Embed 1B (free, no limit)")
197
+ elif self._cloudflare.is_available():
198
+ self._active_provider = "cloudflare"
199
+ logger.info("πŸ€— [EMBEDDINGS] Tier 2: Cloudflare bge-m3 (free 10k/day)")
200
+ else:
201
+ self._active_provider = None
202
+ logger.info("πŸ€— [EMBEDDINGS] No remote provider β€” using SentenceTransformer local fallback")
203
+
204
+ def is_available(self) -> bool:
205
+ return self._active_provider is not None
206
+
207
+ def embed(self, text: str) -> Optional[np.ndarray]:
208
+ """Embed with automatic provider fallback."""
209
+ if self._active_provider == "openrouter":
210
+ result = self._openrouter.embed(text)
211
+ if result is not None:
212
+ return result
213
+ # Fallback to Cloudflare
214
+ if self._cloudflare.is_available():
215
+ result = self._cloudflare.embed(text)
216
+ if result is not None:
217
+ self._active_provider = "cloudflare"
218
+ return result
219
+ return None
220
+
221
+ if self._active_provider == "cloudflare":
222
+ result = self._cloudflare.embed(text)
223
+ if result is not None:
224
+ return result
225
+ # Fallback to OpenRouter if available
226
+ if self._openrouter.is_available():
227
+ result = self._openrouter.embed(text)
228
+ if result is not None:
229
+ self._active_provider = "openrouter"
230
+ return result
231
+ return None
232
+
233
+ return None
234
+
235
+ def embed_batch(self, texts: List[str]) -> Optional[np.ndarray]:
236
+ """Embed batch with automatic provider fallback."""
237
+ if not texts:
238
+ return None
239
+
240
+ if self._active_provider == "openrouter":
241
+ result = self._openrouter.embed_batch(texts)
242
+ if result is not None:
243
+ return result
244
+ if self._cloudflare.is_available():
245
+ result = self._cloudflare.embed_batch(texts)
246
+ if result is not None:
247
+ self._active_provider = "cloudflare"
248
+ return result
249
+ return None
250
+
251
+ if self._active_provider == "cloudflare":
252
+ result = self._cloudflare.embed_batch(texts)
253
+ if result is not None:
254
+ return result
255
+ if self._openrouter.is_available():
256
+ result = self._openrouter.embed_batch(texts)
257
+ if result is not None:
258
+ self._active_provider = "openrouter"
259
+ return result
260
+ return None
261
+
262
+ return None
263
+
264
+
265
+ # ============================================================
266
+ # Singleton
267
+ # ============================================================
268
+
269
+ _remote_embeddings_instance: Optional[RemoteEmbeddings] = None
270
+
271
+
272
+ def get_remote_embeddings() -> RemoteEmbeddings:
273
+ """Get or create the singleton RemoteEmbeddings instance."""
274
+ global _remote_embeddings_instance
275
+ if _remote_embeddings_instance is None:
276
+ _remote_embeddings_instance = RemoteEmbeddings()
277
+ return _remote_embeddings_instance
278
+
279
+
280
+ # Legacy alias
281
+ def get_cloudflare_embeddings() -> RemoteEmbeddings:
282
+ """Legacy alias β€” returns RemoteEmbeddings with fallback chain."""
283
+ return get_remote_embeddings()