diff --git a/guides/databases/vector-embeddings.md b/guides/databases/vector-embeddings.md index 96344915f..302f2cd25 100644 --- a/guides/databases/vector-embeddings.md +++ b/guides/databases/vector-embeddings.md @@ -48,10 +48,9 @@ If the database calculates vector embeddings on write it automatically regenerat ::: info Local Testing with H2 and SQLite On H2 and SQLite the `CQL.vectorEmbedding` function is emulated using a hash-based algorithm to support local testing. For PostgreSQL, customers must define their own `vector_embedding` function for both testing and production use. -::: -> [!warning] Java only and -> The `vector_embedding` function is currently in beta and only supported by the CAP Java runtime. +In CAP Node.js, the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin adds an `ai-sqlite` database kind that generates real embeddings locally on SQLite with an [ONNX](https://onnx.ai) model. It requires a configured embedding model and is experimental, for local development only. +::: [Learn more about Vector Embeddings in CAP Java](../../java/cds-data#vector-embeddings) {.learn-more} @@ -100,15 +99,13 @@ Select.from(INCIDENTS) ``` ```js [Node.js] -const response = await new AzureOpenAiEmbeddingClient( - 'text-embedding-3-small' -).run({ - input: 'Any incidents with solar inverters this month? How were they resolved?' -}); - -const questionEmbedding = response.getEmbedding(); -let similarIncidents = await SELECT.from('Incidents') - .where`cosine_similarity(embedding, to_real_vector(${questionEmbedding})) > 0.75`; +const question = + 'Any incidents with solar inverters this month? How were they resolved?' + +// Compute the question's embedding and find related incidents, all in the database +const similarIncidents = await SELECT.from('Incidents').where` + cosine_similarity(embedding, + vector_embedding(${question}, 'QUERY', 'SAP_GXY.20250407')) > 0.75` ``` ::: @@ -139,11 +136,31 @@ vector_embedding(text, text_type, model_name, remote_source) → vector **Database Implementation:** - **HANA:** Uses real AI models (SAP built-in models or external remote sources) -- **SQLite & H2:** Hash-based deterministic implementation for testing. Can be overridden by application developers to use external embedding services. +- **SQLite & H2:** Hash-based deterministic implementation for testing. Can be overridden by application developers to use external embedding services. In CAP Node.js, the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin with the `ai-sqlite` database kind generates real embeddings locally via an [ONNX](https://onnx.ai) model. - **PostgreSQL:** No default implementation. Application developers must define their own `vector_embedding` function. ## Database-Specific Considerations +### SQLite +- Hash-based, deterministic `vector_embedding` implementation by default, suitable for local testing. +- In CAP Node.js, the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin adds an `ai-sqlite` database kind that generates real embeddings locally with an [ONNX](https://onnx.ai) model, without any external service. It is experimental and intended for local development only. + + Install the plugin with its peer dependencies: + ```sh + npm add -D @cap-js/ai @cap-js/sqlite \ + @huggingface/hub @huggingface/tokenizers onnxruntime-node@1.20.1 + ``` + Then set the database kind and configure an embedding model (there's no default): + ```json + { + "cds": { "requires": { "db": { + "kind": "ai-sqlite", + "embedding": { "model": "sentence-transformers/all-MiniLM-L6-v2" } + } } } + } + ``` + On first start, the model is downloaded to `.cds/models` and reused afterwards. See the [`@cap-js/ai` README](https://github.com/cap-js/ai#local-vector-embeddings-with-sqlite-experimental) for the full walkthrough and model selection. + ### PostgreSQL - Requires that the [pgvector extension](https://github.com/pgvector/pgvector) is installed on your PostgreSQL instance. Then create the extension in your database: ```sql