This version is still in development and is not considered stable yet. For the latest stable version, please use Spring AI 2.1.0!

Quickstart

This guide builds a small web application that sends a question to a chat model and returns the answer. It uses OpenAI, and shows at the end how to run the same code against a local model.

Generate the Project

Go to start.spring.io and create a project with the Spring Web and OpenAI dependencies.

If you add Spring AI to an existing project instead, import the Spring AI BOM as described in Dependency Management and add the OpenAI starter:

  • Maven

  • Gradle

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>
dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-openai'
}

Add Your API Key

Create an API key in your OpenAI account and expose it as an environment variable:

export OPENAI_API_KEY=<your key>

Then reference it in src/main/resources/application.properties:

spring.ai.openai.api-key=${OPENAI_API_KEY}

Write a ChatClient Call

The starter auto-configures a ChatClient.Builder that you can inject. Add a controller that builds a ChatClient and uses it:

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
class ChatController {

    private final ChatClient chatClient;

    ChatController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();
    }

    @GetMapping("/ai")
    String ask(@RequestParam(defaultValue = "Tell me a joke") String message) {
        return this.chatClient.prompt()
            .user(message)
            .call()
            .content();
    }
}

The user method sets the user message, call sends the request to the model, and content returns the response as a String.

Run and Test

Start the application:

./mvnw spring-boot:run

Then call the endpoint:

curl 'http://localhost:8080/ai?message=Why+is+the+sky+blue'

Run Against a Local Model

The controller does not depend on OpenAI. To use a model served by Ollama on your machine, replace the starter with spring-ai-starter-model-ollama and replace the API key property with the model name:

spring.ai.ollama.chat.model=<a model you have pulled>

The Java code stays the same. See Ollama Chat for the details.

Next Steps