Chapter 1: Getting started with Spring AI

Introduction

The introduction explains what generative AI offers users and developers, and why Spring AI makes it accessible in Java applications.

• Generative AI interaction: Explain that generative AI uses models to produce content from natural-language prompts, letting people ask questions or request creative work by chatting with an application.
  Why it matters: This is the basic interaction the Spring AI applications in the book will provide.
• Developer application opportunity: Describe why the section presents building generative AI into applications as an opportunity for developers, beyond using AI as a coding assistant.
  Why it matters: It distinguishes building AI features for users from merely using AI to help write code.
• Spring AI for Java: Explain how Spring AI lets Java developers add generative AI capabilities using Spring and Spring Boot, including in existing applications.
  Why it matters: It explains why the book uses Spring AI rather than requiring Java developers to switch ecosystems.

Key terms: generative AI, natural language prompts, large language models (LLMs), applications, menus and forms, Spring AI, Spring, Spring Boot, Java

1.1 Hello, Spring AI!

This section introduces Spring AI as a provider-independent client abstraction for sending prompts to AI models and receiving generated responses.

• Spring AI client abstraction: Explain why a developer might use Spring AI instead of calling an AI provider’s REST API directly, and how its consistent interface helps when working with different providers.
  Why it matters: This explains the benefit Spring AI offers over making provider-specific HTTP calls yourself.
• Prompt and response flow: Trace the basic interaction between an application, Spring AI, and a provider’s LLM when generating a response.
  Why it matters: The flow shows which work belongs to the application and which work Spring AI handles.
• Natural language prompt purposes: Describe what a prompt contains and give examples of the kinds of responses or tasks it can request.
  Why it matters: These examples show that prompting covers tasks beyond asking a model a question.

Key terms: Spring AI, client abstraction, AI providers, LLMs, prompt, generated response, LLM, AI provider, natural language, sentiment

1.1.1 Initializing the project

The section explains how to initialize the book’s Spring AI application with Spring Initializr and the dependencies and build settings it needs.

• Spring Boot starting point: Explain why starting a Spring AI application is similar to starting another Spring Boot application.
  Why it matters: It explains why familiar Spring Boot setup practices apply to this project.
• Initializr project choices: Describe how to initialize this project and identify its specified build, Java, packaging, and dependency choices.
  Why it matters: These choices produce the starting project used for the application.
• Spring AI dependency management: Explain how the generated build manages the Spring AI libraries used by the project.
  Why it matters: It connects the generated build file to the version and dependency management used for Spring AI.

Key terms: Spring Boot starter dependencies, autoconfiguration, Spring Initializr, Groovy-based Gradle, Spring Web, Spring AI’s OpenAI starter dependencies, Project Metadata, Spring AI version 1.0.3, bill of materials (BOM), build.gradle

1.1.2 Submitting prompts

This section builds a question-answering REST endpoint with Spring AI’s ChatClient and explains how to supply an OpenAI API key without committing it to source control.

• ChatClient question submission: Trace how SpringAiBoardGameService turns a Question into an Answer using ChatClient, including the fluent calls that submit the prompt and retrieve its text.
  Why it matters: This is the path from a Java question to generated answer text in the application.
• REST request handoff: Describe how AskController exposes the service through the /ask endpoint and returns its answer to the requester.
  Why it matters: The controller makes the question-answering service available to an HTTP client.
• OpenAI key configuration: Explain why the application needs an OpenAI API key and how to provide it without placing the secret in source control.
  Why it matters: The key lets Spring AI make OpenAI requests without exposing a private credential in the repository.
• Model usage costs: Describe the section’s basic cost considerations for using hosted LLMs and its stated local alternative.
  Why it matters: It helps you anticipate the cost of model calls while recognizing the local option mentioned in the section.

Key terms: SpringAiBoardGameService, ChatClient.Builder, ChatClient, prompt(), user(), call(), AskController, POST, /ask, Question

1.1.3 Writing a test

The section explains why live LLM responses are difficult to assert against and shows how to test a Spring AI service using a deterministic WireMock response.

• Nondeterministic LLM test challenge: Explain why a test cannot reliably assert that a live LLM completion equals a fixed answer, and why this test substitutes a known response to check the service’s behavior.
  Why it matters: Controlling the response makes it possible to test the service without depending on what an LLM happens to generate.
• WireMock service test flow: Trace how the test routes Spring AI requests to WireMock, returns predefined JSON for the completion endpoint, and checks the Answer returned by askQuestion().
  Why it matters: This setup tests how the service handles an API response while keeping the response predictable.

Key terms: LLM, nondeterministic, completion request, WireMock, @EnableWireMock, @SpringBootTest, spring.ai.openai.base-url, /v1/chat/completions, askQuestion()

1.1.4 Trying it out

Shows how to try the Spring AI question-and-answer application and explains why repeated requests can produce different answers.

• Application request workflow: Describe how to start the application and ask it a question: run the Spring Boot application, then send a POST request to http://localhost:8080/ask with the question in a JSON body using an HTTP client such as curl or HTTPie.
  Why it matters: This is how you can try the question-and-answer application yourself.
• Probabilistic response variation: Explain why the same question can receive different answers, even when sent repeatedly with the same HTTP client.
  Why it matters: Different answers to the same request do not necessarily mean the HTTP client changed the result.

Key terms: Spring Boot application, POST request, /ask, JSON, question, generative AI, nondeterministic, probabilistic, prompts

1.2 Choosing a model

This section explains the range of models available through Spring AI, what to consider when choosing one, and why changing providers usually requires little application-code change.

• OpenAI-compatible API options: Explain that Spring AI’s OpenAI starter can work with providers and tools offering mostly OpenAI-compatible APIs, not only OpenAI itself.
  Why it matters: The starter you already used may be an option for more than one AI service.
• Model selection criteria: Describe the section’s criteria for choosing a provider and model: price, context window, training, and capabilities. Explain why token limits matter more as prompts include conversation history or document context.
  Why it matters: A model that fits one application’s budget, prompt size, and feature needs may not fit another’s.
• Spring AI code portability: Explain what usually changes, and what usually stays the same, when an application switches its chosen AI service or model.
  Why it matters: You can consider different providers without assuming that the application’s Spring AI code must be rewritten.

Key terms: OpenAI starter, OpenAI-compatible APIs, price, context window, tokens, training, capabilities, starter dependency, credentials, application configuration

1.2.1 Configuring OpenAI models

This section explains how Spring AI connects to OpenAI models, how to select a model, and what changes when using Azure OpenAI.

• OpenAI starter and ChatClient: Explain how the OpenAI starter helps a Spring Boot application submit prompts through Spring AI.
  Why it matters: It connects the project dependency to the code used to send a prompt.
• OpenAI model selection: Describe the default OpenAI model and how to choose a different one, including the tradeoffs illustrated in the section.
  Why it matters: Model selection lets the application move beyond the default when capability or cost calls for it.
• Azure OpenAI configuration differences: Distinguish Azure OpenAI from direct OpenAI access and describe the configuration differences covered here.
  Why it matters: Using an OpenAI model through Azure does not mean the direct OpenAI credentials and settings will work.

Key terms: OpenAI integration, starter, ChatClient.Builder, ChatClient, prompt(), GPT-4o mini, GPT-4.1, GPT-4.1 nano, spring.ai.openai.chat.options.model, Azure OpenAI

1.2.2 Serving models locally with Ollama

This section explains how to run Ollama models locally and configure Spring AI to use them.

• Local Ollama model setup: Describe how to prepare a local Ollama model for use in a Spring AI project: install Ollama, pull a model, run Ollama, and add Spring AI’s Ollama starter dependency.
  Why it matters: These are the basic steps that make a local model available to the application.
• Local model tradeoffs: Explain why Ollama is appealing for development and why model choice must account for the machine running it.
  Why it matters: A model that is convenient for local development still has to fit the available hardware.
• Ollama credentials and model selection: Distinguish Ollama’s local setup from a cloud AI service, and state how Spring AI chooses an Ollama chat model.
  Why it matters: It prevents unnecessary API-key setup and makes the application’s model choice explicit.
• Automatic model pulling strategy: Explain how Spring AI can pull an Ollama model automatically and why that convenience may be unsuitable for production startup.
  Why it matters: Automatic pulls simplify development and testing, but can delay application startup.

Key terms: Ollama, ollama pull, Ollama starter dependency, open-source LLMs, model size, hardware, API key, Mistral 7B, spring.ai.ollama.chat.model, spring.ai.ollama.init.pull-model-strategy

1.3 Previewing Spring AI’s capabilities

The section explains why Spring AI applications may need more than a single text prompt and response, introducing templates, conversational context, document access, and application tools.

• Prompt Template Placeholders: Explain why Spring AI offers prompt templates for more involved prompts and what their placeholders are filled with.
  Why it matters: Templates help when a prompt needs more instructions or context than a one-sentence question.
• Conversation History as Context: Explain why a back-and-forth conversation needs chat history and how Spring AI uses it when sending prompts.
  Why it matters: Passing along prior conversation gives the model the context needed to respond to follow-up questions.
• RAG for Document Gaps: Explain the information gaps that motivate RAG and what it lets an application ask about.
  Why it matters: RAG addresses questions the model's training alone cannot answer from an application's documents.
• Tools for Application Functionality: Distinguish the document questions described for RAG from the application functionality that model tools can provide.
  Why it matters: Some requests call for application data or actions rather than answers drawn from documents.

Key terms: prompt templates, placeholders, parameter values, context, chat history, chat memory, retrieval-augmented generation (RAG), documents, training, RAG

1.4 Summary