Skip to content

Commit af877e8

Browse files
a-da-d
committed
Add doc
1 parent 461e0e4 commit af877e8

File tree

2 files changed

+153
-0
lines changed

2 files changed

+153
-0
lines changed

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,7 @@ For more detailed information and advanced usage, please refer to the following:
136136
- [<img src="sample-code/spring-app/src/main/resources/static/Open-AI-Logo.svg" width="16"/> OpenAI Chat Completion](docs/guides/OPENAI_CHAT_COMPLETION.md)
137137
- [<img src="https://spring.io/favicon-32x32.png" width="16"/> Spring AI Integration](docs/guides/SPRING_AI_INTEGRATION.md)
138138
- [🧰 AI Core Deployment](docs/guides/AI_CORE_DEPLOYMENT.md)
139+
- [<img src="sample-code/spring-app/src/main/resources/static/grounding.png" width="16"/> AI Core Grounding](docs/guides/GROUNDING.md)
139140

140141
For updating versions, please refer to the [**Release Notes**](docs/release-notes/release-notes-0-to-14.md).
141142

‎docs/guides/GROUNDING.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# Grounding Services
2+
3+
## Table of Contents
4+
5+
- [Introduction](#introduction)
6+
- [Prerequisites](#prerequisites)
7+
- [Maven Dependencies](#maven-dependencies)
8+
- [Usage](#usage)
9+
- [Data Ingestion](#data-ingestion)
10+
- [Pipeline API](#pipeline)
11+
- [Vector API](#vector)
12+
- [Data Retrieval](#data-retrieval)
13+
- [Retrieval API](#create-a-deployment)
14+
- [Grounding via Orchestration](#orchestration)
15+
16+
## Introduction
17+
18+
This guide provides examples on how to manage data in SAP Document Grounding.
19+
It's divided into two main sections: Data Ingestion and Data Retrieval.
20+
21+
> [!WARNING]
22+
> The below examples rely on generated model classes.
23+
> Please be aware of the [implications described here](/README.md#general-requirements).
24+
25+
## Prerequisites
26+
27+
Before using the Grounding module, ensure that you have met all the general requirements outlined in the [README.md](../../README.md#general-requirements).
28+
Additionally, include the necessary Maven dependency in your project.
29+
30+
### Maven Dependencies
31+
32+
Add the following dependency to your `pom.xml` file:
33+
34+
```xml
35+
<dependency>
36+
<groupId>com.sap.ai.sdk</groupId>
37+
<artifactId>grounding</artifactId>
38+
<version>${ai-sdk.version}</version>
39+
</dependency>
40+
```
41+
42+
See [an example pom in our Spring Boot application](../../sample-code/spring-app/pom.xml)
43+
44+
## Usage
45+
46+
In addition to the prerequisites above, we assume you have already set up the following to carry out the examples in this guide:
47+
48+
- A running instance of SAP AI Core with correctly setup credentials, including a resource group id.
49+
50+
## Data Ingestion
51+
52+
The following APIs are available for data ingestion: Pipeline and Vector.
53+
54+
### Pipeline API
55+
56+
Consider the following code sample to read pipelines, create a new one and get its status:
57+
58+
```java
59+
var api = new GroundingClient().pipelines();
60+
var resourceGroupId = "default";
61+
62+
// get all pipelines
63+
Pipelines pipelines = api.getAllPipelines(resourceGroupId);
64+
65+
// create new pipeline
66+
var type = "MSSharePoint"; // or "S3" or "SFTP"
67+
var pipelineSecret = "my-secret-name";
68+
var config = PipelinePostRequstConfiguration.create().destination(pipelineSecret);
69+
var request = PipelinesPostRequest.create().type(type)._configuration(config);
70+
PipelineId pipeline = api.createPipeline(resourceGroupId, request);
71+
72+
// get pipeline status
73+
PipelineStatus status = api.getPipelineStatus(resourceGroupId, pipeline.getPipelineId());
74+
```
75+
76+
### Vector API
77+
78+
```java
79+
var api = new GroundingClient().vector();
80+
var resourceGroupId = "default";
81+
82+
// resolve collection id
83+
var collectionId = UUID.fromString("12345-123-123-123-0123456abcdef");
84+
85+
var request = DocumentCreateRequest.create()
86+
.documents(BaseDocument.create()
87+
.chunks(TextOnlyBaseChunk.create()
88+
.content("The dog makes _woof_")
89+
.metadata(KeyValueListPair.create()
90+
.key("animal").value("dog")))
91+
.metadata(DocumentKeyValueListPair.create()
92+
.key("topic").value("sound")));
93+
DocumentsListResponse response = api.createDocuments(resourceGroupId, collectionId, request);
94+
```
95+
96+
Refer to the [DeploymentController.java](../../sample-code/spring-app/src/main/java/com/sap/ai/sdk/app/controllers/DeploymentController.java) in our Spring Boot application for a complete example.
97+
98+
## Data Retrieval
99+
100+
The following APIs are available for data retrieval: Retrieval and Orchestration.
101+
102+
103+
### Retrieval API
104+
105+
Consider the following code sample to search for relevant grounding data based on a query:
106+
107+
```java
108+
var api = new GroundingClient().retrieval();
109+
var resourceGroupId = "default";
110+
111+
var filter =
112+
RetrievalSearchFilter.create()
113+
.id("question")
114+
.dataRepositoryType(DataRepositoryType.VECTOR)
115+
.dataRepositories(List.of("*"))
116+
.searchConfiguration(SearchConfiguration.create().maxChunkCount(10));
117+
var search = RetrievalSearchInput.create().query("What is SAP Cloud SDK for AI?").filters(filter);
118+
RetievalSearchResults results = api.search(resourceGroupId, search);
119+
```
120+
121+
### Grounding via Orchestration
122+
123+
You can use the grounding service via orchestration.
124+
Please find the [documentation on Orchestration client in the dedicated document](ORCHESTRATION.md).
125+
126+
```java
127+
OrchestrationClient client;
128+
129+
var databaseFilter =
130+
DocumentGroundingFilter.create()
131+
.dataRepositoryType(DataRepositoryType.VECTOR)
132+
.searchConfig(GroundingFilterSearchConfiguration.create().maxChunkCount(3));
133+
var groundingConfigConfig =
134+
GroundingModuleConfigConfig.create()
135+
.inputParams(List.of("query"))
136+
.outputParam("results")
137+
.addFiltersItem(databaseFilter);
138+
var groundingConfig =
139+
GroundingModuleConfig.create()
140+
.type(GroundingModuleConfig.TypeEnum.DOCUMENT_GROUNDING_SERVICE)
141+
.config(groundingConfigConfig);
142+
var configWithGrounding = config.withGroundingConfig(groundingConfig);
143+
144+
var inputParams = Map.of("query", "What is SAP Cloud SDK for AI?");
145+
146+
var prompt =
147+
new OrchestrationPrompt(
148+
inputParams,
149+
Message.system("Context message with embedded grounding results. {{?results}}"));
150+
151+
OrchestrationChatResponse response = client.chatCompletion(prompt, configWithGrounding);
152+
```

0 commit comments

Comments
 (0)