Skip to content

Commit 4525c8d

Browse files
MattSchurMatKuhrrenejeglinsky
authored
Vector Embeddings: Add example w/ Cloud SDK for AI (#1914)
Adds example code and link to [SAP Cloud SDK for AI](https://sap.github.io/ai-sdk) --------- Co-authored-by: Matthias Kuhr <52661546+MatKuhr@users.noreply.github.com> Co-authored-by: Rene Jeglinsky <rene.jeglinsky@sap.com>
1 parent 5fcd1df commit 4525c8d

1 file changed

Lines changed: 82 additions & 50 deletions

File tree

‎guides/databases-hana.md‎

Lines changed: 82 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,9 @@
11
---
22
status: released
3-
impl-variants: true
43
---
54

65
# Using SAP HANA Cloud for Production
76

8-
<ImplVariantsHint />
9-
107
[[toc]]
118

129

@@ -20,52 +17,42 @@ CAP isn't validated with other variants of SAP HANA, like "SAP HANA Database as
2017

2118
## Setup & Configuration
2219

23-
<div class="impl node">
24-
25-
Run this to use SAP HANA Cloud for production:
20+
To use SAP HANA Cloud for production, add a dependency to the _package.json_ for Node.js or to the _pom.xml_ for a CAP Java application:
2621

27-
```sh
22+
::: code-group
23+
```sh [Shell/Bash]
2824
npm add @cap-js/hana
2925
```
3026

31-
::: details Using other SAP HANA drivers...
32-
33-
Package `@cap-js/hana` uses the [`hdb`](https://www.npmjs.com/package/hdb) driver by default. You can override that by running [`npm add @sap/hana-client`](https://www.npmjs.com/package/@sap/hana-client), thereby adding it to your package dependencies, which then takes precedence over the default driver.
34-
35-
:::
36-
37-
::: tip Prefer `cds add`
38-
39-
... as documented in the [deployment guide](deployment/to-cf#_1-sap-hana-database), which also does the equivalent of `npm add @cap-js/hana` but in addition cares for updating `mta.yaml` and other deployment resources.
40-
41-
:::
42-
43-
</div>
44-
45-
<div class="impl java">
46-
47-
To use SAP HANA Cloud, [configure a module](../java/developing-applications/building#standard-modules), which includes the feature `cds-feature-hana`.
48-
For example, add a Maven runtime dependency to the `cds-feature-hana` feature:
49-
50-
```xml
27+
```xml [pom.xml]
5128
<dependency>
5229
<groupId>com.sap.cds</groupId>
5330
<artifactId>cds-feature-hana</artifactId>
5431
<scope>runtime</scope>
5532
</dependency>
5633
```
34+
:::
5735

58-
::: tip
36+
::: details Using other SAP HANA drivers...
5937

60-
The [modules](../java/developing-applications/building#standard-modules) `cds-starter-cloudfoundry` and `cds-starter-k8s` include `cds-feature-hana`.
38+
Package `@cap-js/hana` uses the [`hdb`](https://www.npmjs.com/package/hdb) driver by default. You can override that by running [`npm add @sap/hana-client`](https://www.npmjs.com/package/@sap/hana-client), thereby adding it to your package dependencies, which then takes precedence over the default driver.
6139

6240
:::
6341

64-
The datasource for HANA is then auto-configured based on available service bindings of type *service-manager* and *hana*.
42+
:::details In CAP Java ...
43+
The [modules](../java/developing-applications/building#standard-modules) `cds-starter-cloudfoundry` and `cds-starter-k8s` include `cds-feature-hana`.
44+
45+
The datasource for SAP HANA is then auto-configured based on available service bindings of type *service-manager* and *hana*.
6546

6647
[Learn more about the configuration of an SAP HANA Cloud Database](../java/cqn-services/persistence-services#sap-hana){ .learn-more}
48+
:::
49+
50+
::: tip Prefer `cds add`
51+
52+
... as documented in the [deployment guide](deployment/to-cf#_1-sap-hana-database), which also does the equivalent of `npm add @cap-js/hana` but in addition cares for updating `mta.yaml` and other deployment resources.
53+
54+
:::
6755

68-
</div>
6956

7057

7158

@@ -266,41 +253,86 @@ The HANA Service provides dedicated support for native SAP HANA features as foll
266253

267254
### Vector Embeddings { #vector-embeddings }
268255

269-
Vector embeddings are numerical representations that capture important features and semantics of unstructured data - such as text, images, or audio. This representation makes vector embeddings of similar data have high similarity and low distance to each other. These properties of vector embeddings facilitate tasks like similarity search, anomaly detection, recommendations and Retrieval Augmented Generation (RAG). Vector embeddings from a vector datastore such as the [SAP HANA Cloud Vector Engine](https://community.sap.com/t5/technology-blogs-by-sap/sap-hana-cloud-s-vector-engine-announcement/ba-p/13577010) can help get better generative AI (GenAI) results. This is achieved when the embeddings are used as context to the large language models (LLMs) prompts.
256+
Vector embeddings let you add semantic search, recommendations, and generative AI features to your CAP application. Embeddings are numeric arrays that represent the meaning of unstructured data (text, images, etc.), making it possible to compare and search for items that are semantically related to each other or a user query.
270257

271-
Typically vector embeddings are computed using an **embedding model**. The embedding model is specifically designed to capture important features and semantics of a specific type of data, it also determines the dimensionality of the vector embedding space. Unified consumption of embedding models and LLMs across different vendors and open source models is provided via the [SAP Generative AI Hub](https://community.sap.com/t5/technology-blogs-by-sap/how-sap-s-generative-ai-hub-facilitates-embedded-trustworthy-and-reliable/ba-p/13596153).
258+
#### Choose an Embedding Model
272259

273-
In CAP, vector embeddings are stored in elements of type [cds.Vector](../cds/types):
260+
Choose an embedding model that fits your use case and data (for example english or multilingual text). The model determines the number of dimensions of the resulting output vector. Check the documentation of the respective embedding model for details.
274261

275-
```cds
276-
entity Books : cuid { // [!code focus]
277-
title : String(111);
278-
description : LargeString; // [!code focus]
279-
embedding : Vector(1536); // vector space w/ 1536 dimensions // [!code focus]
280-
} // [!code focus]
262+
Use the [SAP Generative AI Hub](https://community.sap.com/t5/technology-blogs-by-sap/how-sap-s-generative-ai-hub-facilitates-embedded-trustworthy-and-reliable/ba-p/13596153) for unified consumption of embedding models and LLMs across different vendors and open source models. Check for available models on the [SAP AI Launchpad](https://help.sap.com/docs/ai-launchpad/sap-ai-launchpad-user-guide/models-and-scenarios-in-generative-ai-hub-fef463b24bff4f44a33e98bb1e4f3148#models).
263+
264+
#### Add Embeddings to Your CDS Model
265+
Use the `cds.Vector` type in your CDS model to store embeddings on SAP HANA Cloud. Set the dimension to match your embedding model (for example, 1536 embedding dimensions for OpenAI *text-embedding-3-small*).
266+
267+
```cds
268+
entity Books : cuid {
269+
title : String(111);
270+
description : LargeString;
271+
embedding : Vector(1536); // adjust dimensions to embedding model
272+
}
273+
```
274+
275+
#### Generate Embeddings
276+
Use an embedding model to convert your data (for example, book descriptions) into vectors. The [SAP Cloud SDK for AI](https://sap.github.io/ai-sdk/) makes it easy to call SAP AI Core services to generate these embeddings.
277+
278+
:::details Example using SAP Cloud SDK for AI
279+
```Java
280+
var aiClient = OpenAiClient.forModel(OpenAiModel.TEXT_EMBEDDING_3_SMALL);
281+
var response = aiClient.embedding(
282+
new OpenAiEmbeddingRequest(List.of(book.getDescription())));
283+
book.setEmbedding(CdsVector.of(response.getEmbeddingVectors().get(0)));
281284
```
285+
:::
282286

283-
At runtime, you can compute the similarity and distance of vectors in the SAP HANA vector store using the `cosineSimilarity` and `l2Distance` (Euclidean distance) functions in queries:
287+
#### Query for Similarity
288+
At runtime, use SAP HANA's built-in vector functions to search for similar items. For example, find books with embeddings similar to a user question:
284289

285290
::: code-group
286-
```js [Node.js]
287-
let embedding; // vector embedding as string '[0.3,0.7,0.1,...]';
291+
```Java [Java]
292+
// Compute embedding for user question
293+
var request = new OpenAiEmbeddingRequest(List.of("How to use vector embeddings in CAP?"));
294+
CdsVector userQuestion = CdsVector.of(
295+
aiClient.embedding(request).getEmbeddingVectors().get(0));
296+
// Compute similarity between user question and book embeddings
297+
var similarity = CQL.cosineSimilarity( // computed on SAP HANA
298+
CQL.get(Books.EMBEDDING), userQuestion);
299+
// Find Books related to user question ordered by similarity
300+
hana.run(Select.from(BOOKS).limit(10)
301+
.columns(b -> b.ID(), b -> b.title(),
302+
b -> similarity.as("similarity"))
303+
.orderBy(b -> b.get("similarity").desc()));
304+
```
288305

306+
```js [Node.js]
307+
const response = await new AzureOpenAiEmbeddingClient(
308+
'text-embedding-3-small'
309+
).run({
310+
input: 'How to use vector embeddings in CAP?'
311+
});
312+
const questionEmbedding = response.getEmbedding();
289313
let similarBooks = await SELECT.from('Books')
290-
.where`cosine_similarity(embedding, to_real_vector(${embedding})) > 0.9`
314+
.where`cosine_similarity(embedding, to_real_vector(${questionEmbedding})) > 0.9`;
291315
```
292316

293-
```java [Java]
294-
// Vector embedding of text, for example, from SAP GenAI Hub or via LangChain4j
295-
float[] embedding = embeddingModel.embed(bookDescription).content().vector();
317+
:::
296318

297-
Result similarBooks = service.run(Select.from(BOOKS).where(b ->
298-
CQL.cosineSimilarity(b.embedding(), CQL.vector(embedding)).gt(0.9)));
299-
```
319+
:::tip
320+
Store embeddings when you create or update your data. Regenerate embeddings if you change your embedding model.
300321
:::
301322

323+
:::tip SAP Cloud SDK for AI
324+
Use the [SAP Cloud SDK for AI](https://sap.github.io/ai-sdk/) for unified access to embedding models and large language models (LLMs) from [SAP AI Core](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/what-is-sap-ai-core).
325+
:::
326+
327+
328+
[Learn more about the SAP Cloud SDK for AI (Java)](https://sap.github.io/ai-sdk/docs/java/getting-started) {.learn-more}
329+
302330
[Learn more about Vector Embeddings in CAP Java](../java/cds-data#vector-embeddings) {.learn-more}
303331

332+
[Learn more about the SAP Cloud SDK for AI (JavaScript)](https://sap.github.io/ai-sdk/docs/js/getting-started) {.learn-more}
333+
334+
335+
304336

305337
### Geospatial Functions
306338

0 commit comments

Comments
 (0)