Spring Boot 4 Complete Guide · 강의

ChatClient, 프롬프트 및 구조화된 출력

프롬프트 템플릿과 형식이 지정된 구조화 출력 매핑을 사용해 ChatClient로 대화 모델을 호출합니다.

ChatClient, 프롬프트 및 구조화된 출력은(는) CoddyKit의 무료 Spring Boot 4 Complete Guide 강의입니다. 이것은 4개 중 1번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 Spring Boot 4 Complete Guide 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. Spring Boot 4 Complete Guide 강의에는 총 4개의 강의가 포함되어 있습니다.

이 강의의 일부는 아직 번역되지 않았으며 영어로 표시됩니다.

Why ChatClient?

Spring AI gives you a fluent, high-level API for talking to LLMs: the ChatClient. Instead of hand-building HTTP requests to OpenAI, Anthropic, or Ollama, you describe what you want and let the framework handle transport, retries, and message assembly.

ChatClient — fluent builder for one-shot or streaming calls.
Prompt — a list of messages (system, user, assistant) plus options.
Structured output — map the model's text reply directly into a typed Java object.

It is portable: swap the underlying ChatModel (OpenAI → Anthropic) and your ChatClient code stays the same.

Auto-configuration and dependencies

Add a Spring AI model starter and Spring Boot auto-configures a ChatModel bean plus a ChatClient.Builder you can inject.

The starter (e.g. spring-ai-starter-model-openai) reads your API key and model from properties.
You never construct ChatClient directly — you inject the builder and call .build().

Typical configuration in application.yml:

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4o
          temperature: 0.2

Creating a ChatClient

Inject the auto-configured ChatClient.Builder and build a client once, usually in your service constructor. You can attach default system prompts or options here so every call inherits them.

Building per-service (not per-request) keeps configuration in one place and is cheap.

@Service
public class AssistantService {

    private final ChatClient chatClient;

    public AssistantService(ChatClient.Builder builder) {
        this.chatClient = builder
            .defaultSystem("You are a concise Spring expert. Answer in one sentence.")
            .build();
    }
}

A first call: prompt().user().content()

The fluent chain reads like a sentence. Start with prompt(), add a user(...) message, then terminate with call() for a blocking response and content() to get the plain text.

call() — synchronous request/response.
content() — extracts the assistant's text.
chatResponse() — returns metadata (token usage, finish reason) instead.

public String ask(String question) {
    return chatClient.prompt()
        .user(question)
        .call()
        .content();
}

System vs user messages

An LLM prompt is a sequence of messages with roles:

System — instructions and persona; sets behavior.
User — the actual request from the end user.
Assistant — prior model replies (for multi-turn context).

You can override the default system message per call. Keep untrusted user input in user(...), never inside the system instruction, to reduce prompt-injection risk.

String answer = chatClient.prompt()
    .system("You are a senior Java reviewer. Be blunt and specific.")
    .user("Review this code: " + snippet)
    .call()
    .content();

Prompt templates with variables

Hard-coding strings does not scale. Spring AI uses template placeholders (default {name} syntax via StringTemplate) that you fill with param(...). The framework substitutes values before the request is sent.

Define the template text once with {placeholders}.
Bind values with .user(u -> u.text(...).param(...)).

This separates wording from data and keeps user values clearly bound.

String reply = chatClient.prompt()
    .user(u -> u
        .text("Summarize the topic {topic} for a {level} audience.")
        .param("topic", "reactive streams")
        .param("level", "beginner"))
    .call()
    .content();

How template substitution works

Under the hood Spring AI builds a PromptTemplate and renders it. You can also use the template directly when you want to reuse it or load it from a resource file.

Here is the same idea as a plain Java program you can run to see substitution — no Spring needed, just string formatting that mirrors what the renderer does:

import java.util.Map;

public class TemplateDemo {
    static String render(String tmpl, Map<String, String> vars) {
        String out = tmpl;
        for (var e : vars.entrySet()) {
            out = out.replace("{" + e.getKey() + "}", e.getValue());
        }
        return out;
    }

    public static void main(String[] args) {
        String t = "Summarize {topic} for a {level} audience.";
        System.out.println(render(t, Map.of("topic", "reactive streams", "level", "beginner")));
    }
}

Structured output: entity()

Often you do not want prose — you want a typed object. Spring AI's structured output converters do three things: inject a format instruction into the prompt, receive the model's text, and deserialize it into your type.

Define a plain Java record, then call .entity(MyType.class) instead of .content().

public record MovieReview(String title, int year, double rating, String verdict) {}

public MovieReview review(String movie) {
    return chatClient.prompt()
        .user("Give a short structured review of the movie: " + movie)
        .call()
        .entity(MovieReview.class);
}

Generic types with ParameterizedTypeReference

For collections or generic containers, Java erases the type parameter at runtime, so List.class is not enough. Pass a ParameterizedTypeReference so Spring AI knows the element type and generates the right JSON schema instruction.

import org.springframework.core.ParameterizedTypeReference;
import java.util.List;

public record Actor(String name, List<String> films) {}

public List<Actor> castOf(String movie) {
    return chatClient.prompt()
        .user("List the main cast of " + movie)
        .call()
        .entity(new ParameterizedTypeReference<List<Actor>>() {});
}

What entity() does to the prompt

It is worth understanding the mechanism: entity() uses a BeanOutputConverter that generates a JSON Schema from your record and appends a format instruction telling the model to reply with matching JSON only.

The model returns JSON text.
The converter parses it (via Jackson) into your record.
If the model adds stray prose, parsing can fail — lower temperature and keep records flat for reliability.

You can call the converter yourself to inspect the injected instruction:

import org.springframework.ai.converter.BeanOutputConverter;

record Weather(String city, double celsius) {}

var converter = new BeanOutputConverter<>(Weather.class);
String formatInstruction = converter.getFormat();
// This text is appended to your user prompt by entity()
System.out.println(formatInstruction);

Streaming and response metadata

For long answers, stream tokens as they arrive using stream() instead of call(), which returns a reactive Flux<String>. For observability, grab the full ChatResponse to read token usage and the finish reason.

.stream().content() — Flux<String> of incremental chunks.
.call().chatResponse().getMetadata().getUsage() — prompt/completion tokens.

import reactor.core.publisher.Flux;

public Flux<String> streamAnswer(String question) {
    return chatClient.prompt()
        .user(question)
        .stream()
        .content();
}

Quick Check

You need the model's reply mapped into a List<Actor>. Which terminal call is correct?

Recap

You learned to call LLMs the Spring way with ChatClient:

Inject ChatClient.Builder, set defaultSystem, and build() once per service.
Use the fluent chain: prompt().system(...).user(...).call().content().
Keep system instructions and untrusted user input in separate messages.
Use {placeholder} templates with .param(...) to separate wording from data.
Map replies to typed records with .entity(Type.class), and use ParameterizedTypeReference for generics like List<T>.
Stream with .stream().content() and inspect token usage via chatResponse().getMetadata().

For reliable structured output, keep records flat and lower the temperature.

자주 묻는 질문

“ChatClient, 프롬프트 및 구조화된 출력” 강의는 무료인가요?

네 — “ChatClient, 프롬프트 및 구조화된 출력” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 Spring Boot 4 Complete Guide 강의 전체를 잠금 해제할 수 있습니다. Spring Boot 4 Complete Guide 강의에는 총 4개의 강의가 포함되어 있습니다.

“ChatClient, 프롬프트 및 구조화된 출력”에서 뭘 배우나요?

프롬프트 템플릿과 형식이 지정된 구조화 출력 매핑을 사용해 ChatClient로 대화 모델을 호출합니다. 브라우저에서 직접 실행하는 실습 코드로 Spring Boot 4 Complete Guide을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

Spring Boot 4 Complete Guide을(를) 시작하는 데 경험이 필요한가요?

사전 경험은 필요하지 않습니다. CoddyKit의 Spring Boot 4 Complete Guide은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 1번째 강의입니다.

“ChatClient, 프롬프트 및 구조화된 출력” 강의는 얼마나 걸리나요?

대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.

이 Spring Boot 4 Complete Guide 강의에서 코드를 작성하고 실행할 수 있나요?

네. 모든 Spring Boot 4 Complete Guide 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.

이 강의의 모든 강의

← Spring Boot 4 Complete Guide(으)로 돌아가기