동블

그래프 뷰

01. Spring AI 학습 로드맵과 버전 선택

9 min read

이 문서를 통해 아래 질문들에 답할 수 있게 됩니다.

  • Spring AI를 어떤 순서로 공부해야 입문에서 운영 입문-고급까지 갈 수 있는가?
  • Spring AI 2.0.x와 Spring Boot 4.x를 기준으로 삼을 때 Boot 3.x 서비스는 무엇을 조심해야 하는가?
  • OpenAI와 Ollama를 각각 어떤 학습 목적으로 써야 하는가?
  • 이 폴더를 끝까지 읽었을 때 어떤 능력을 갖춰야 하는가?
flowchart LR
    subgraph ENTRY["입문 구간"]
        VERSION["[Version]<br/>Spring AI 2.x / Boot 4.x<br/>Boot 3.x는 호환성 판단"]
        FIRST["[First Chat]<br/>ChatClient 첫 호출<br/>OpenAI 기본, Ollama 보조"]
    end

    subgraph BACKEND["백엔드 설계 구간"]
        GATEWAY["[AI Gateway]<br/>호출 경계 분리<br/>promptVersion, usage 기록"]
        CONFIG["[Model Profile]<br/>provider 설정<br/>model, timeout, secret"]
        CONTEXT["[Context Harness]<br/>prompt, advisor, memory<br/>CONVERSATION_ID 관리"]
    end

    subgraph CAPABILITY["핵심 기능 구간"]
        STRUCTURED["[Structured Output]<br/>DTO 계약화<br/>Bean Validation"]
        TOOL["[Tool / MCP]<br/>외부 실행 연결<br/>approval, audit"]
        RAG["[RAG]<br/>문서 검색 연결<br/>VectorStore, source"]
    end

    subgraph OPS["운영 구간"]
        EVAL["[Eval]<br/>회귀 검증<br/>golden set, regression"]
        OBS["[Observability]<br/>장애 대응<br/>metrics, logs, traces"]
        CAPSTONE["[Capstone]<br/>고객지원 RAG<br/>end-to-end 설계"]
    end

    VERSION --> FIRST --> GATEWAY --> CONFIG --> CONTEXT --> STRUCTURED --> TOOL --> RAG --> EVAL --> OBS --> CAPSTONE

    classDef entry fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20;
    classDef backend fill:#E3F2FD,stroke:#1565C0,color:#0D47A1;
    classDef capability fill:#FFF3E0,stroke:#EF6C00,color:#E65100;
    classDef ops fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C;
    class VERSION,FIRST entry;
    class GATEWAY,CONFIG,CONTEXT backend;
    class STRUCTURED,TOOL,RAG capability;
    class EVAL,OBS,CAPSTONE ops;

개요

Spring AI는 Spring Boot 애플리케이션 안에서 LLM, embedding, vector store, tool calling, MCP, observability를 다루게 해주는 프레임워크다. 이 폴더의 목표는 AI 연구자가 되는 것이 아니라, 백엔드 개발자가 Spring 서비스에 AI 기능을 붙이고 운영할 수 있게 되는 것이다.

현재 기준은 Spring AI 2.0.x와 Spring Boot 4.x다. 다만 실무에는 Boot 3.x 서비스가 많으므로 최신 학습과 운영 적용을 분리해서 봐야 한다. 최신 API를 학습하되 기존 서비스에 붙일 때는 호환 버전과 migration 비용을 먼저 확인한다.

원리

Spring AI를 배우는 순서는 기능 나열이 아니라 책임 확장 순서로 가야 한다.

  • 첫 호출: 모델을 호출하고 응답을 받는다.
  • 계층 분리: Controller, service, AI gateway를 나눈다.
  • 설정: provider key, model, retry, profile을 관리한다.
  • context: prompt, advisor, memory로 모델 입력을 통제한다.
  • 구조화: DTO와 validation으로 모델 출력을 서버 계약으로 바꾼다.
  • 실행: tool calling과 MCP로 외부 시스템을 연결한다.
  • 검색: embedding, vector store, RAG로 사내 지식을 연결한다.
  • 운영: eval, observability, 장애 런북, 인프라 협업을 준비한다.

이 순서를 건너뛰면 데모는 빨리 만들 수 있지만 운영 문제를 설명하기 어렵다.

실습

학습 환경은 두 갈래로 잡는다.

spring:
  ai:
    model:
      chat: openai
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        model: gpt-4o-mini
        temperature: 0.2
spring:
  ai:
    model:
      chat: ollama
    ollama:
      base-url: http://localhost:11434
      chat:
        model: llama3.1

성공 경로는 OpenAI로 먼저 확인하는 것이다. managed provider의 key, model, quota, retry, 비용 감각을 익힐 수 있다. Ollama는 반복 실습과 로컬 모델의 latency, memory, 품질 제약을 느끼는 데 쓴다. Spring AI OpenAI 문서의 기본 모델은 더 최신 모델일 수 있지만, GPT-5 계열은 temperature를 지원하지 않는다고 명시되어 있다. 이 문서의 입문 예시는 temperature 설명을 위해 non-reasoning 모델 예시를 사용한다.

자주 나는 오류는 버전 불일치다. Spring AI 2.0 문서를 보고 Boot 3.x 프로젝트에 그대로 붙이면 dependency resolution이나 property 차이에서 막힐 수 있다. 또한 Ollama는 모델을 pull하지 않았거나 모델명이 다르면 호출이 실패한다.

운영에서는 provider 선택이 학습 편의가 아니라 SLO, 비용, 개인정보, 데이터 위치, 장애 대응의 문제가 된다.

실전 판단

학습자는 다음 질문에 답할 수 있어야 한다.

  • 이 기능은 동기 API로 충분한가, 비동기 job으로 빼야 하는가?
  • 모델 호출 실패 시 사용자는 무엇을 보게 되는가?
  • prompt와 model 변경은 어떻게 rollback하는가?
  • RAG 검색 결과에 권한 필터가 적용되는가?
  • tool calling이 side effect를 만들 때 idempotency가 있는가?
  • 인프라팀이 볼 지표와 로그는 무엇인가?

이 질문에 답하지 못하면 Spring AI API를 아는 상태이지 운영 가능한 AI 백엔드 개발자는 아니다.

실전 팁

  • 최신 문서는 2.0.x 기준으로 읽고, 기존 서비스 적용은 compatibility matrix부터 확인한다.
  • 예제 코드에서 Controller 호출이 보여도 운영 코드에서는 gateway로 감싼다.
  • OpenAI와 Ollama 결과를 품질 비교가 아니라 운영 조건 비교로도 본다.
  • prompt, model, index, tool schema는 모두 배포 자산으로 기록한다.
  • 각 장을 읽은 뒤 확인 질문에 답하지 못하면 다음 장으로 넘어가지 않는다.

위험 신호!

  • Spring AI를 단순 SDK wrapper로만 이해한다.
  • Boot 버전을 확인하지 않고 최신 dependency를 추가한다.
  • provider key와 prompt를 Controller에 직접 둔다.
  • 데모가 성공했다는 이유로 eval, 로그, 비용, 장애 대응을 생략한다.
  • Ollama 실습 성공을 기업 운영 가능성으로 착각한다.

확인 질문

확인 질문

  • 이 폴더의 학습 목표는 무엇인가?
    • Spring AI 기능을 백엔드 서비스에 붙이고 테스트, 관측, 장애 대응, 인프라 협업까지 설명할 수 있게 되는 것이다.
  • 왜 Spring AI 2.0.x를 본류로 두면서 Boot 3.x도 언급하는가?
    • 최신 학습은 2.0.x가 중요하지만 실무 서비스는 Boot 3.x에 남아 있을 수 있어 적용 판단이 필요하기 때문이다.
  • OpenAI와 Ollama의 학습 역할은 어떻게 다른가?
    • OpenAI는 managed provider 운영 감각을 익히고, Ollama는 로컬 반복 실습과 self-hosted 제약을 익히는 데 좋다.
  • 졸업 기준은 단순 API 호출과 어떻게 다른가?
    • 구조, 검증, 권한, 비용, 관측성, 장애 런북까지 다룰 수 있어야 한다.

학습 연결

참고 문서

관련 문서

백링크