AI Concepts를 먼저 읽어야 Spring AI가 보인다
Spring AI 문서를 처음 읽을 때 가장 과소평가하기 쉬운 페이지가 AI Concepts다.
대부분은 빨리 코드로 내려가고 싶어서 Getting Started나 ChatClient 예제부터 본다. 그런데 그렇게 들어가면 뒤에서 나오는 RAG, Tool Calling, Structured Output, Evaluation이 각각 따로 노는 기능처럼 보이기 쉽다.
반대로 AI Concepts를 먼저 읽으면 Spring AI가 무엇을 공통 추상화로 묶고 있는지 한 번에 보인다.
이 글은 그 페이지를 기준으로, Spring AI를 읽을 때 꼭 잡아야 할 개념 지형도를 한국어로 정리한 것이다.
왜 이 페이지가 중요한가
Spring AI는 단순히 “OpenAI 호출을 쉽게 해 주는 라이브러리”로 보기엔 범위가 넓다.
문서가 초반에 따로 개념 페이지를 둔 이유는 분명하다.
- 모델은 무엇이고
- 프롬프트는 왜 단순 문자열이 아니며
- 임베딩은 왜 검색과 연결되고
- 토큰은 왜 비용 문제가 아니라 설계 문제가 되며
- 구조화 출력, RAG, Tool Calling, Evaluation이 왜 한 흐름으로 이어지는지
를 먼저 잡아야 이후 API 문서가 자연스럽게 읽히기 때문이다.
즉 이 페이지는 입문용 배경지식이 아니라, Spring AI 전체를 읽는 해석기에 가깝다.
1) 모델: 텍스트 생성기보다 넓은 개념
문서가 처음부터 강조하는 건 모델의 입출력이 생각보다 다양하다는 점이다.
우리는 보통 ChatGPT 같은 텍스트 대화를 먼저 떠올리지만, 실제 AI 모델은 훨씬 넓다.
- 텍스트 입력 → 텍스트 출력
- 텍스트 입력 → 이미지 출력
- 오디오 입력 → 텍스트 출력
- 텍스트 입력 → 숫자 벡터 출력(임베딩)
Spring AI가 흥미로운 이유는 이 다양한 모델을 Spring 스타일의 공통 API 감각으로 다루려 한다는 데 있다.
그래서 Spring AI를 볼 때는 특정 공급자 SDK보다 먼저, 모델 종류를 통합적으로 다루려는 프레임워크라는 관점을 잡는 편이 좋다.
2) 프롬프트: 문자열 한 줄이 아니라 역할이 있는 메시지 묶음
문서에서 특히 중요한 부분은 프롬프트 설명이다.
초보 단계에서는 프롬프트를 그냥 “모델에 보내는 문장” 정도로 생각하기 쉽다. 하지만 현대 LLM API에서 프롬프트는 보통 역할이 분리된 메시지들의 조합이다.
system: 모델의 태도, 규칙, 제약user: 사용자의 실제 요청- 경우에 따라 메모리, 검색 결과, 도구 결과
이 구조를 먼저 이해하면 나중에 ChatClient의 fluent API가 왜 그런 모양인지도 쉽게 이해된다.
그리고 여기서 바로 이어지는 주제가 Prompt Template이다. Spring AI는 프롬프트를 하드코딩 문자열보다, 템플릿과 파라미터로 조립 가능한 대상으로 본다. 이 지점이 Spring MVC에서 뷰를 다루는 감각과도 닮아 있다.
3) 임베딩: 수학보다 검색 감각이 더 중요하다
임베딩 설명도 실무적으로 잘 읽어야 한다.
문서가 말하는 핵심은 복잡한 선형대수 자체가 아니다. 텍스트·이미지 같은 데이터를 의미를 비교할 수 있는 벡터로 바꾼다는 점이다.
이 감각이 중요한 이유는 RAG 때문이다.
임베딩이 있어야 질문과 의미적으로 가까운 문서 조각을 찾을 수 있고, 그래야 검색 기반 문맥 주입이 가능해진다. 즉 임베딩은 그 자체가 목적이 아니라,
- 의미 기반 검색
- 문서 유사도 비교
- 추천 및 분류
- RAG의 검색층
으로 이어지는 출발점이다.
Spring AI를 실무에서 쓸 때는 임베딩을 “AI가 쓰는 내부 숫자” 정도로 넘기지 말고, 검색 가능한 의미 표현으로 이해하는 편이 훨씬 유용하다.
4) 토큰: 비용 문제가 아니라 애플리케이션 설계 문제
토큰 설명은 짧지만 굉장히 중요하다.
문서가 말하듯 토큰은 곧 비용이고, 동시에 컨텍스트 윈도우 한계다. 그래서 이건 단순한 과금 이슈가 아니라 구조 설계 문제로 바뀐다.
예를 들면 이런 질문이 생긴다.
- 긴 문서를 어떻게 나눌 것인가
- 무엇을 먼저 검색해서 붙일 것인가
- 메모리를 어디까지 유지할 것인가
- 한 번에 얼마만큼 문맥을 넣을 것인가
결국 RAG, ETL, Chat Memory, Advisors가 전부 이 문제를 다른 방식으로 다루는 셈이다.
즉 토큰은 “모델이 비싸다” 정도가 아니라, 문서를 자르고 우선순위를 정하고 문맥을 선별하게 만드는 제약이다.
5) 구조화 출력: JSON처럼 보이는 문자열에서 실제 데이터 구조로
Spring AI 문서가 구조화 출력을 따로 강조하는 이유도 현실적이다.
모델에게 “JSON으로 답해”라고 말해도, 애플리케이션 입장에서는 여전히 문자열을 받은 것일 뿐이다. 형식이 흔들릴 수도 있고, 실제 파싱 단계에서 깨질 수도 있다.
그래서 Spring AI는 단순 문자열 응답을 넘어,
- 원하는 스키마를 유도하고
- 필요하면 재질문 또는 변환을 거쳐
- 애플리케이션에서 바로 쓸 수 있는 구조로 연결하는
흐름을 중요하게 본다.
이건 데모에서는 사소해 보이지만, 운영 환경에서는 굉장히 크다. 문자열을 받아 사람이 읽는 데서 끝나는 앱과, 그 결과를 다시 시스템에 연결하는 앱은 요구사항이 전혀 다르기 때문이다.
6) RAG: 내 문서를 모델에 억지로 넣는 게 아니라 검색 가능한 흐름으로 바꾸는 것
문서 후반부에서 설명하는 RAG는 결국 “내 데이터와 AI를 연결하는 방법”의 핵심이다.
여기서 문서가 강조하는 포인트는 두 가지다.
첫째, 긴 문서를 그대로 넣는 게 아니라 의미 경계를 살려 잘게 나눠야 한다는 점. 둘째, 그 조각들을 벡터 저장소에 넣고 유사한 것만 찾아 프롬프트에 붙인다는 점.
즉 RAG는 프롬프트에 문서를 무식하게 많이 넣는 기술이 아니라,
- 문서 분할
- 임베딩 생성
- 벡터 저장
- 유사도 검색
- 프롬프트 문맥 주입
의 연쇄다.
Spring AI를 제대로 쓰려면 이 과정을 별도 해킹이 아니라 공식 애플리케이션 흐름으로 본다는 점이 중요하다.
7) Tool Calling: 모델이 실행하는 게 아니라 앱이 통제하는 것
개념 페이지에서 Tool Calling을 설명하는 방식도 꽤 좋다.
핵심은 단순하다.
- 모델은 어떤 도구를 써야 할지 요청한다.
- 애플리케이션이 그 도구를 실행한다.
- 결과를 다시 모델에 넘긴다.
- 모델이 최종 응답을 만든다.
이 흐름을 이해하면 Tool Calling을 “모델이 외부 시스템을 마음대로 조작하는 기능”으로 오해하지 않게 된다.
실제 책임은 여전히 애플리케이션에 있다.
- 어떤 도구를 공개할지
- 어떤 인자를 허용할지
- 읽기와 쓰기 도구를 어떻게 분리할지
- 결과를 얼마나 그대로 돌려줄지
즉 Tool Calling은 모델의 마법이 아니라 애플리케이션 설계와 제어 계층이다.
8) Evaluation: 응답이 나왔다는 것과 좋은 응답이라는 것은 다르다
개념 페이지가 Evaluation까지 연결해 주는 점도 중요하다.
많은 프로젝트가 “일단 답이 나온다”에서 만족하지만, 운영으로 가면 질문이 달라진다.
- 이 답변이 관련성 있는가
- 사실성은 괜찮은가
- 검색 결과와 맞는가
- 바뀐 프롬프트가 실제로 더 좋아졌는가
Spring AI는 이 문제를 별도 평가 축으로 다룬다. 이건 앞으로 RAG, Tool Calling, Agentic Workflow를 붙일수록 더 중요해진다.
Spring AI를 읽는 권장 순서도 이 개념에서 나온다
개인적으로는 이 페이지를 읽고 나면 이후 문서를 이렇게 보는 게 가장 자연스럽다.
Getting StartedChat Client APIPromptsChat MemoryTool CallingRetrieval Augmented GenerationVector DatabasesModel Evaluation
이 순서의 장점은 기능 이름이 아니라 개념 연결을 따라간다는 데 있다.
마무리
Spring AI의 AI Concepts 페이지는 사전지식 정리 문서처럼 보이지만, 실제로는 훨씬 중요하다.
여기서 한 번 정리해 두면 이후 문서들이 이렇게 이어진다.
- 모델 → 어떤 종류의 AI 기능을 다루는가
- 프롬프트 → 어떻게 요청을 구성하는가
- 임베딩 → 왜 검색과 RAG가 가능한가
- 토큰 → 왜 문맥 설계가 중요한가
- 구조화 출력 → 결과를 어떻게 시스템에 연결하는가
- Tool Calling → 외부 기능을 어떻게 안전하게 붙이는가
- Evaluation → 결과가 좋은지 어떻게 판단하는가
즉 이 페이지는 입문용 부록이 아니라, Spring AI 전체를 이해하기 위한 첫 번째 지도다.
참고한 원문 문서
시리즈 이어보기
- 1부. Spring AI 2.0, 왜 지금 다시 볼 만한가
- 2부. Spring AI 시작하기: BOM, 저장소, 의존성에서 막히지 않는 법
- 3부. ChatClient가 사실상 Spring AI의 진입점인 이유
- 4부. RAG를 Spring AI에서 구현하면 뭐가 쉬워지나
- 5부. Tool Calling은 모델 기능이 아니라 애플리케이션 설계다
- 6부. Advisors를 이해하면 Spring AI 설계가 보인다
- 7부. MCP가 Spring 개발자에게 중요한 이유
- 8부. Vector Store 선택은 모델보다 운영에 더 가깝다
- 9부. Observability, Evaluation, Upgrade Notes를 같이 봐야 하는 이유