Skip to main content
Version: v2

Document Grounding

warning

This package is still in beta and is subject to breaking changes. Use it with caution.

The @sap-ai-sdk/document-grounding package incorporates generative AI document grounding capabilities into your AI activities in SAP AI Core and SAP AI Launchpad.

Installation​

$ npm install @sap-ai-sdk/document-grounding
important

This package contains generated code. Updates to this package may include breaking changes.

To ensure compatibility and manage updates effectively, we strongly recommend using the tilde (~) version range in your project instead of the caret (^). This approach will allow patch-level updates while preventing potentially breaking minor version changes.

Usage​

The examples below demonstrate the usage of the most commonly used APIs in SAP AI Core document grounding service. In addition to the examples below, you can find more sample code here.

tip

If you define a custom resource group, ensure that it has the label document-grounding: true in order to use the document grounding service. This label can be set in SAP AI Launchpad while creating the resource group. Alternatively, create a resource group via AI API by referring to the Creating a Resource Group for Grounding guide.

Create a Collection​

const response = await VectorApi.createCollection(
  {
    title: 'my-collection-title',
    embeddingConfig: {
      modelName: 'text-embedding-3-small'
    },
    metadata: []
  },
  {
    'AI-Resource-Group': 'default'
  }
).executeRaw();

const collectionId = (response.headers.location as string).split('/').at(-2);

Create a Document​

const response: DocumentsListResponse = await VectorApi.createDocuments(
  collectionId,
  {
    documents: [
      {
        metadata: [],
        chunks: [
          {
            content:
              'SAP Cloud SDK for AI is the official Software Development Kit (SDK) for SAP AI Core, SAP Generative AI Hub, and Orchestration Service.',
            metadata: []
          }
        ]
      }
    ]
  },
  {
    'AI-Resource-Group': 'default'
  }
).execute();

Custom Destination​

When calling the execute() method, it is possible to provide a custom destination for your SAP AI Core instance. For example, when querying deployments targeting a destination with the name my-destination, the following code can be used:

const response = await VectorApi.deleteCollectionById(collectionId, {
  'AI-Resource-Group': 'default'
}).execute({
  destinationName: 'my-destination'
});

By default, the fetched destination is cached. To disable caching, set the useCache parameter to false together with the destinationName parameter.

For more information about configuring a destination, refer to the Using a Destination section.