跪拜 Guibai
← All articles
Frontend · Backend

Behind a Product RAG: SurrealDB, Embeddings, and an AI Tool in SvelteKit

By Swot ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

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.

Summary

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.

Takeaways
— Product records live as independent SurrealDB documents in a SCHEMALESS table; only the embedding field carries a type constraint.
— Browser access goes through /api/products with Bearer auth, while server-side loads and the AI tool import the same module directly, avoiding HTTP overhead.
— Writes use MERGE to preserve untouched fields; after setting embeddingVersion to 0, the embedding is recalculated from the merged full text.
— Embeddings come from SiliconFlow's OpenAI-compatible endpoint via plain fetch, using BAAI/bge-m3 at 1024 dimensions, with no extra SDK.
— Hybrid search checks regNumber exact match first, then cosine similarity with a 0.45 threshold; empty results are a valid response.
— The 0.45 threshold was chosen because unrelated queries scored 0.37-0.40 and relevant long-tailed queries hit 0.52.
— HNSW indexes are deferred until the catalog reaches tens of thousands of records; with ~100 products, brute-force cosine is already milliseconds.
— Updating sort order via PATCH skips embedding recomputation since ranking doesn't change semantics.
— Environment variables have two sources of truth: .env and PM2's ecosystem.config.cjs; Node's loadEnvFile() does not override existing values, so the wrong copy wins silently.
Conclusions

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.

Concepts & terms
Accounting fields (记账字段)
Internal metadata like embeddingModel, embeddingVersion, createdAt, updatedAt, and sort that track how and when vectors were computed; they are excluded from model inputs to save tokens and avoid confusing the LLM.
Hybrid search
A retrieval strategy that combines exact field matching with semantic vector similarity, as implemented here with regNumber exact match and cosine similarity with a configurable threshold.
Embedding version
A monotonically increasing number that invalidates cached vectors when the embedding model or its configuration changes; bumping it triggers a full re-embed.
From the discussion
Featured comments
Swot

This content only presents the high-level design approach.

See top comments, translated →
Source: juejin.cn ↗ Google Translate ↗ Backup ↗