Spring AI - Part 1: From Zero to a Simple AI Endpoint

This post assumes only basic Java and minimal Spring Boot knowledge. The goal is simple: by the end, you will have a running HTTP endpoint that talks to an AI model and returns its response as plain text.

Source: NotebookLM

1. What Problem Does Spring AI Solve?

Modern AI models (like ChatGPT-style models) are usually accessed via HTTP APIs: you send JSON, you get JSON back. Doing this directly involves:

• Writing and maintaining HTTP clients.

• Building request/response JSON structures.

• Handling errors, timeouts, and configuration.

• Managing different providers (OpenAI, local models, etc.)

Spring AI sits between your Spring Boot application and these AI providers. It gives you:

• A high-level ChatClient API for sending prompts and receiving responses.

• Auto-configuration via Spring Boot starters.

• Easy switching between providers (OpenAI, Ollama, others) using properties.

• Integration with the rest of the Spring ecosystem.

In other words, you focus on your business logic; Spring AI handles the low-level AI integration.

2. Project Setup

   
   

2.1  Generate a Spring Boot Project

Use Spring Initializr:

      1. Go to https://start.spring.io/

      2. Choose:

• Project: Maven

• Language: Java

• Spring Boot: 3.3.x (or the latest stable)

• Group: com.spring.ai

• Artifact: spring-ai-demo

      3. Add dependencies:

·       Spring Web

       4. Generate and unzip the project

      5. Open it in your IDE (IntelliJ IDEA, VS Code, etc).

2.2  Add Spring AI Dependency

Open pom.xml and add this dependency inside <dependencies>:

<dependency>
	<groupId>org.springframework.ai</groupId>
	<artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

Run a Maven reload in your IDE or use:

./mvnw dependency:resolve

Note: Add Spring AI BOM to <dependencyManagement>:

<dependencyManagement>
	<dependencies>
		<dependency>
			<groupId>org.springframework.ai</groupId>
			<artifactId>spring-ai-bom</artifactId>
			<version>${spring-ai.version}</version>
			<type>pom</type>
			<scope>import</scope>
		</dependency>
	</dependencies>
</dependencyManagement>

3.     Configuration: Connecting to a Model

3.1  Using OpenAI

Create or edit src/main/resources/application.properties:

spring.ai.openai.api-key=sk-your-openai-key-here
spring.ai.openai.chat.options.model=gpt-4o-mini
server.port=8080

Replace sk-your-openai-key-here with a real API key.

3.2  Using Ollama

If you prefer running models locally on your machine:

1.       Install Ollama from https://ollama.com/

2.      Pull a model (for example) in your terminal:

	ollama pull llama3.2

3.  In pom.xml, use this dependency instead of OpenAI:

	<dependency>
		<groupId>org.springframework.ai</groupId>
		<artifactId>spring-ai-starter-model-ollama</artifactId>
	</dependency>

4.       Update application.properties:

	spring.ai.ollama.base-url=http://localhost:11434
	spring.ai.ollama.chat.options.model=llama3.2
	server.port=8080

4.     The Core Code: A minimal AI Controller

Now we will create a REST controller that accepts a message from the user and returns the AI’s reply.

Create a file src/main/java/com/spring/ai/springaidemo/AiController.java (ensure the package matches your project):

package com.spring.ai.spring_ai_demo;

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
public class AiController {

    private final ChatClient chatClient;

    public AiController(ChatClient.Builder builder){
        // Spring injects a ChatClient.Builder configured for your chosen provider.
        this.chatClient = builder.build();
    }

    @GetMapping("/ai/hello")
    public String hello(@RequestParam(defaultValue = "Hello World!") String message){
        return chatClient
                .prompt()// Start building a prompt
                .user(message) // Set the user's message (What you want to ask the model)
                .call()  // Send the request to the AI provider and wait for a response
                .content();   // Extract the textual content from the response
    }
}

5.     Understanding the Code

Let’s break down the important pieces:

5.1 @RestController

@RestController
public class AiController {

• Marks the class as a REST controller.

• Methods annotated with @GetMapping, @PostMapping, etc., become HTTP endpoints.

• Return values (like String) are written directly to the HTTP response body.

5.2  Injecting ChatClient

private final ChatClient chatClient;

public AiController(ChatClient.Builder builder) {    
	this.chatClient = builder.build();
}

• ChatClient is the main abstraction provided by Spring AI for chat-based interactions.

• Spring Boot creates and injects a ChatClient.Builder based on your configuration.

• Calling builder.build() gives you a ready-to-use ChatClient instance.

• You do not manually create HTTP clients, set base URLs, or attach API keys; all of that is configured via properties and the starter.

5.3  Defining the Endpoint

@GetMapping("/ai/hello")
public String hello(@RequestParam(defaultValue = "Hello World!") String message){
	........
}

• Exposes a GET endpoint at /ai/hello.

• Expects a query parameter message, eg:

http://localhost:8080/ai/hello?message=Explain Spring AI in simple words

• The message is passed into the method and then to the AI model.

5.4  Building and Sending the Prompt

return chatClient        
		.prompt()        
		.user(message)         
		.call()         
		.content();	

• prompt() starts the definition of a chat interaction.

• user(message) sets the text coming from the user.

• call() sends this to the configured AI model and waits for the result.

• content() extracts the textual output from the model’s response object.

Conceptually, you take the input message, send it to the model, and return whatever the model replies with.

6.  Running and Testing the Application

From the project root, run:

./mvnw spring-boot:run

Once the app starts, open a browser or use curl/Postman:

http://localhost:8080/ai/hello?message=Explain Spring AI in simple words.

You should see a plain text explanation generated by the model.

Success! Spring AI endpoint responds with an explanation.

Try a few more examples:

• message=Tell me a short programming joke.

• message=Give me three ideas for a Spring Boot project.

If you encounter errors:

• Check the console logs for messages about missing API keys or connection issues.

• For OpenAI:

  • Verify spring.ai.openai.api-key is correct.

• For Ollama:

  • Ensure the Ollama server is running.

  • Confirm the model’s name in application.properties matches what you pulled.

7.   What You Have Achieved So Far

At this point, you have:

• A basic Spring Boot application.

• Spring AI is configured with either a cloud model (OpenAI) or a local one (Ollama).

• A simple HTTP endpoint that forwards user input to an AI model and returns the result.

In the next part, you can build on this by adding:

• Prompt templates.

• Basic validation.

• Different endpoints for different AI tasks (e.g., summarization, explanation, code help).

You’ve done it! From blank project to AI endpoint.

Feedback? Comment on your test results.