Skip to content

Latest commit

 

History

History
273 lines (188 loc) · 10.7 KB

README.md

File metadata and controls

273 lines (188 loc) · 10.7 KB
Raw

build CodeQL REUSE status Fosstars security rating

SAP Cloud SDK for AI (for Java)

⚠️ This is a pre-alpha version of the AI SDK for Java. The APIs are subject to change. ⚠️

Table of Contents

Introduction

Welcome to the SAP Cloud SDK for AI (for Java). This SDK enables developers to seamlessly integrate AI capabilities, such as chat completion, into their Java-based business applications using SAP's Generative AI Hub. Leverage powerful features like templating, grounding, data masking, and content filtering to build intelligent applications. The SDK simplifies the setup and interaction with SAP AI Core, allowing you to focus on delivering value through AI integration.

General Requirements

To use the SAP AI SDK for Java, the following general prerequisites must be met:

  • Java Development Kit (JDK) 17 or higher installed.
  • Apache Maven 3.9 or higher installed.
  • SAP AI Core Service enabled in your SAP BTP account.
  • SAP AI Core Credentials to access the AI Core service.
  • (Optional) Spring Boot version 3 or higher if you are using Spring Boot.

See an example pom.xml in our Spring Boot application.

Connecting to SAP AI Core

To interact with SAP AI Core services, the SAP AI SDK requires credentials available at application runtime. By default, the SDK automatically extracts these credentials from a service instance of type aicore bound to your application.

If running the application locally without this service binding, you may encounter an exception:

Could not find any matching service bindings for service identifier 'aicore'

There are multiple ways to provide these credentials:

Option Description
1 Set an environment variable explicitly: AICORE_SERVICE_KEY
2 Regular service binding in SAP BTP Cloud Foundry (results in VCAP_SERVICES environment variable entry)
3 Define and use a Destination in the SAP BTP Destination Service

Additional methods (not recommended for production):

  • Use the hybrid testing approach for CAP applications (e.g., cds bind --to aicore --exec mvn spring-boot:run)
  • Leverage a "user-provided" service binding
  • Define and use a custom ServiceBinding or ServiceBindingAccessor in your application

Option 1: Set Credentials as Environment Variable

Click to view detailed steps

1. Obtain Service Credentials:

  • Log into the SAP BTP Cockpit
  • Navigate to Instances and Subscriptions -> Instances -> AI Core
  • Click View Credentials and copy the JSON content

2. Set Environment Variable:

  • In your IDE or terminal, set the environment variable AICORE_SERVICE_KEY with the copied JSON content

Example:

export AICORE_SERVICE_KEY='{ "clientid": "...", "clientsecret": "...", "url": "...", "serviceurls": { "AI_API_URL": "..." } }'

Option 2: Regular Service Binding in SAP BTP Cloud Foundry

Click to view detailed steps

1. Bind an existing aicore service instance to your application

SAP BTP provides multiple ways to do this:

  • Using the web interface
  • Using the CLI
  • Using MTA or manifest files

Learn more about binding service instances to applications

After restarting your application, you should see an "aicore" entry in the VCAP_SERVICES environment variable:

{
  "aicore": [
    {
      "clientid": "...",
      "clientsecret": "...",
      "url": "...",
      "serviceurls": {
        "AI_API_URL": "..."
      }
    }
  ]
}

Option 3: Define and Use a Destination

Click to view detailed steps

1. Obtain Service Credentials: (Same as in Option 1)

2. Create a Destination:

  • In the SAP BTP Cockpit, go to Connectivity -> Destinations

  • Click New Destination and configure:

    • Name: my-aicore
    • Type: HTTP
    • URL: [serviceurls.AI_API_URL]/v2 (append /v2 to the URL)
    • Proxy Type: Internet
    • Authentication: OAuth2ClientCredentials
    • Client ID: [clientid]
    • Client Secret: [clientsecret]
    • Token Service URL Type: Dedicated
    • Token Service URL: [url]

3. Use the Destination in Your Application:

Destination destination = DestinationAccessor.getDestination("my-aicore");
ApiClient client = new AiCoreService().withDestination(destination);

Getting Started

What You'll Build

In this quickstart, you'll build a simple Spring Boot application that uses the OpenAI GPT-3.5 Turbo model for chat completion. The application will send a prompt to the AI model and display the generated response.

Prerequisites

Before you begin, ensure you have:

Write the Code

Add the following code to the controller or service class in your Spring Boot application:

// Initialize the client for GPT-3.5 Turbo model
OpenAiClient client = OpenAiClient.forModel(OpenAiModel.GPT_35_TURBO);

// Perform chat completion
OpenAiChatCompletionOutput result =
    client
        .withSystemPrompt("You are a helpful assistant.")
        .chatCompletion("Hello World! Why is this phrase so famous?");

Run and Test the Application Locally

Then, compile and run your application:

cd your-spring-app/

mvn compile
mvn spring-boot:run

Deploying to Cloud Foundry (Optional)

When deploying your productive application to Cloud Foundry, it is recommended to use service binding to provide the AI Core credentials as per Option 2.

Build your application using Maven and deploy it to Cloud Foundry:

cf push

That's it! Your application should now be running on Cloud Foundry, and the AI Core credentials are provided securely via service binding.

Documentation

For more detailed information and advanced usage, please refer to the following:

FAQs

How to add a custom header to AI Core requests?

To add a header to AI Core requests, use the following code:

ApiClient client = new AiCoreService().client().addDefaultHeader("header-key", "header-value");
DeploymentApi api = new DeploymentApi(client);

For more customization, creating a HeaderProvider is also possible.

More Examples

Explore example applications and code snippets:

Contribute, Support and Feedback

This project is open to feature requests/suggestions, bug reports etc. via GitHub issues. Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our Contribution Guidelines.

Security / Disclosure

If you find any bug that may be a security problem, please follow our instructions at in our security policy on how to report it. Please do not create GitHub issues for security-related doubts or problems.

Code of Conduct

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its Code of Conduct at all times.

Licensing

Copyright 2024 SAP SE or an SAP affiliate company and ai-sdk-java contributors. Please see our LICENSE for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available via the REUSE tool.