Behind a Product RAG: SurrealDB, Embeddings, and an AI Tool in SvelteKit
Teams building RAG on small, well-defined catalogs get a concrete pattern here: one embedding model, one storage module, and a measured similarity threshold keep the stack simple. The documented SurrealDB gotchas, from id type differences to environment variable precedence, will save others the same debugging time.
The system stores products as independent records in a schema-less SurrealDB table, with only the embedding field constrained by type. Three access paths converge on one server-side module: the browser goes through /api/products with Bearer auth, SvelteKit page load functions import and call getAllProducts() directly, and the AI chat endpoint invokes searchProducts() through a streamText tool. Sharing the module keeps read/write logic to a single version and prevents SQL or endpoint forks.
Writes save text with MERGE, reset embeddingVersion to 0, then recompute embeddings via a plain-fetch call to SiliconFlow's OpenAI-compatible endpoint using BAAI/bge-m3 at 1024 dimensions. Vector generation failure preserves the text but marks the version stale, and an idempotent backfill script repairs outdated vectors. Search combines exact regNumber matching with cosine similarity gated by a 0.45 threshold, chosen because unrelated queries scored 0.37-0.40 and relevant long-tail queries hit 0.52. HNSW indexing is deferred; with roughly 100 products, brute-force cosine already runs in milliseconds.
Field projections trim what the model sees: MODEL_FIELDS excludes internal accounting metadata and content, while embeddings never leave the server. The post documents a common deployment trap: environment variables live in both .env and PM2's ecosystem.config.cjs, and Node's loadEnvFile() does not override existing values, so the wrong copy wins silently. It recommends one true source per environment and includes a verification script that checks keys, counts, vector versions, recall scores, and field leakage.
The threshold-based filtering is a pragmatic counter to semantic search's tendency to return plausible-sounding junk; a domain-specific cutoff beats generic ranking.
Keeping page loads and AI tools on direct function calls rather than HTTP is a sound way to avoid duplicated SQL or logic, at the cost of mixing server concerns into the client build process.
The two-truth environment variable trap is common in PM2 deployments; documenting it as a rule rather than a patch is the right call.
Choosing not to add HNSW for a small dataset shows a willingness to trade theoretical scalability for operational simplicity, a decision that should be revisited when data grows.
This content only presents the high-level design approach.