⚠️ This is a pre-alpha version of the AI SDK for Java. The APIs are subject to change.⚠️
- Introduction
- General Requirements
- Connecting to SAP AI Core
- Getting Started
- Documentation
- FAQs
- Contribute, Support and Feedback
- Security / Disclosure
- Code of Conduct
- Licensing
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.
To use the SDK in a Java application, it is necessary to understand the technical prerequisites and required versions for common dependencies.
- SAP AI Core Service enabled in your SAP BTP account.
- SAP AI Core Credentials to access the AI Core service.
The following table lists the required versions, based on the latest release:
| Dependency | Minimum Version | Recommended Version |
|---|---|---|
| JDK | 17 (LTS) | 21 (LTS) |
| SAP Cloud SDK | 5.6.0 | latest |
| (optional) CAP Java | 3.0.0 | latest |
| (optional) Spring Boot | 3.0 | latest |
See an example pom.xml in our Spring Boot application.
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 | Create an .env file containing an 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
ServiceBindingorServiceBindingAccessorin your application
Click to view detailed steps
1. Obtain Service Credentials:
- Log into the SAP BTP Cockpit
- Navigate to Services -> Instances and Subscriptions -> Instances -> AI Core
- Click View Credentials and copy the JSON content
2. Create .env file:
- Create an
.envfile in the root directory of your application - Add a one line entry
AICORE_SERVICE_KEY={...}with the copied JSON
Set an environment variable instead of .env
2. Set an Environment Variable: (alternative)
-
In your IDE or terminal, set the environment variable
AICORE_SERVICE_KEYwith the copied JSON contentℹ️ The environment variable has priority over the
.envfile.
Example Linux/MacOS:
export AICORE_SERVICE_KEY='{ "clientid": "...", "clientsecret": "...", "url": "...", "serviceurls": { "AI_API_URL": "..." } }'Example Windows:
$env:AICORE_SERVICE_KEY='{ "clientid": "...", "clientsecret": "...", "url": "...", "serviceurls": { "AI_API_URL": "..." } }'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": "..."
}
}
]
}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] - Proxy Type:
Internet - Authentication:
OAuth2ClientCredentials - Client ID:
[clientid] - Client Secret:
[clientsecret] - Token Service URL Type:
Dedicated - Token Service URL:
[url]
- Name:
3. Use the Destination in Your Application:
Destination destination = DestinationAccessor.getDestination("my-aicore");
AiCoreService aiCoreService = new AiCoreService().withDestination(destination);
DeploymentApi client = new DeploymentApi(aiCoreService);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.
Before you begin, ensure you have:
- Met the General Requirements.
- Met the OpenAI Chat Completion module specific requirements
- Set up the AI Core credentials using (1) Environment variable or env-file or (2) Regular Service Binding.
- Deployed the OpenAI GPT-3.5 Turbo model in SAP AI Core.
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?");Then, compile and run your application:
cd your-spring-app/
mvn compile
mvn spring-boot:runWhen 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 pushThat's it! Your application should now be running on Cloud Foundry, and the AI Core credentials are provided securely via service binding.
For more detailed information and advanced usage, please refer to the following:
Create a HeaderProvider.
This is a known false-positive finding. Depending on the tooling any product called "SAP Cloud SDK" or similar with a low version number may be marked as vulnerable, incorrectly. Please consider suppressing the warning, as we do.
Explore example applications and code snippets:
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.
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.
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.
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.