namerong 님의 블로그

냉파마스터 2차 프로젝트: AI 장보기 추천 Agent 연동과 LLM 사용량 관리 구현

namerong — Thu, 6 Aug 2026 18:58:03 +0900

이번 작업은 냉파마스터 2차 프로젝트의 리팩토링 및 확장 작업이다.

1차 프로젝트에서는 냉장고 재료 관리, 장보기 목록 관리, 사전 재료 검색, 관리자 사전 재료 관리 기능을 중심으로 기본 CRUD 흐름을 구현했다.

2차 프로젝트에서는 여기서 한 단계 확장해, 사용자의 냉장고와 장보기 상태를 기반으로 AI가 필요한 재료를 추천하고, 추천 결과를 사용자가 직접 승인해 장보기 목록에 추가할 수 있는 구조를 구현했다.

이번 작업 범위는 다음과 같다.

#238 AI 장보기 추천 MVP 구현
#239 AI 대화 세션 및 메시지 기록 구현
#240 LLM 사용량 로그 저장 구현
#316 프론트 AI 장보기 추천 화면 연동
#317 관리자 LLM 사용량 전체 조회 API 구현
#318 관리자 LLM 사용량 로그 화면 구현

1. 작업 배경

기존 장보기 기능은 사용자가 직접 재료를 검색하고 장보기 목록에 추가하는 방식이었다.

하지만 냉장고에 이미 있는 재료, 장보기 목록에 이미 담긴 재료, 사용자가 못 먹는 재료 등을 매번 직접 고려해서 장보기 목록을 구성하는 것은 번거롭다.

그래서 이번 작업에서는 AI Agent를 활용해 다음과 같은 흐름을 만들고자 했다.

사용자의 냉장고 상태 조회
→ 장보기 목록 조회
→ 못 먹는 재료와 선호 음식 정보 반영
→ 추천 후보 재료 생성
→ AI 추천 결과 반환
→ 사용자가 선택한 항목만 장보기 목록에 추가

중요한 점은 AI가 추천 결과를 바로 DB에 저장하지 않도록 한 것이다.

AI 추천은 어디까지나 제안이고, 실제 장보기 목록에 반영할지는 사용자가 직접 선택해야 한다고 판단했다.

2. 전체 구조

이번 AI 추천 기능은 Backend와 FastAPI Agent 서버를 분리해서 구성했다.

Backend는 기존 회원 인증, 냉장고, 장보기, 사전 재료 데이터를 관리한다.

FastAPI Agent는 Backend에서 전달받은 사용자 상태와 후보 재료를 기반으로 LLM 추천 결과를 생성한다.

전체 흐름은 다음과 같다.

사용자가 프론트에서 AI 추천 버튼 클릭
프론트가 Backend의 AI 추천 API 호출
Backend가 로그인한 사용자의 냉장고/장보기/못 먹는 재료/선호 음식 정보 조회
Backend가 추천 제외 상품 ID 목록 생성
Backend가 추천 후보 상품 목록을 Agent 서버에 전달
Agent가 LLM 또는 fallback 로직으로 추천 결과 생성
Backend가 추천 결과를 사용자에게 반환
Backend가 AI 대화 기록과 LLM 사용량 로그 저장
사용자가 원하는 추천 항목만 장보기 목록에 추가

3. #238 AI 장보기 추천 MVP 구현

먼저 AI 장보기 추천 API를 구현했다.

4. #239 AI 대화 세션 및 메시지 기록 구현

AI 추천은 단순히 결과만 보여주고 끝나는 기능이 아니라, 사용자가 나중에 이전 추천 내용을 다시 확인할 수 있어야 한다고 판단했다.

그래서 AI 대화 세션과 메시지 기록을 저장하는 구조를 추가했다.

구현한 주요 테이블은 다음과 같다.

conversation_sessions
conversation_messages

conversation_sessions는 AI 추천 요청 단위의 세션 정보를 저장한다.

conversation_messages는 해당 세션 안에서 사용자 요청 메시지와 AI 응답 메시지를 저장한다.

5. #240 LLM 사용량 로그 저장 구현

LLM 기능은 호출량, 실패 여부, 토큰 사용량, 예상 비용을 추적하는 것이 중요하다.

특히 추후 구독 정책이나 사용량 제한, 비용 분석을 고려한다면 LLM 사용 로그는 반드시 필요하다.

그래서 LLM 사용량 로그 저장 기능을 구현했다.

저장하는 주요 정보는 다음과 같다.

memberId
modelName
promptTokens
completionTokens
totalTokens
estimatedCost
status
failureMessage
createdAt

현재는 FastAPI Agent에서 usage 값을 내려주고, Backend가 해당 값을 저장한다.

실제 OpenAI 연동 전 fallback 또는 rule-based 추천이 동작하는 경우에는 modelName을 rule-based-mvp로 저장하고, 토큰 수와 비용은 0으로 처리했다.

실제 gpt-4.1-mini 사용 시에는 입력 토큰과 출력 토큰 단가를 기준으로 예상 비용을 계산하도록 구성했다.

Prompt는 입력 토큰, Completion은 출력 토큰, Total은 두 값을 합친 전체 토큰 수다.

6. #316 프론트 AI 장보기 추천 화면 연동

Backend와 Agent API가 준비된 뒤, 기존 장보기 화면에 AI 추천 기능을 연결했다.

기존 화면의 디자인과 사용자 흐름을 해치지 않는 것이 중요했기 때문에, 장보기 목록 화면 안에 AI 추천 버튼과 추천 결과 카드만 추가했다.

프론트에서 구현한 흐름은 다음과 같다.

사용자가 AI 추천 버튼 클릭
추천 API 호출
추천 결과를 카드 형태로 표시
추천 결과는 자동 저장하지 않음
사용자가 담기 버튼을 누른 항목만 장보기 목록에 추가
추가된 항목은 추천 목록에서 제거
기존 장보기 추가/수정/삭제/체크 흐름은 그대로 유지

특히 AI 추천 결과를 바로 DB에 저장하지 않고 화면 상태로만 관리했다.

이렇게 해야 사용자가 원하지 않는 재료가 자동으로 장보기 목록에 들어가는 문제를 막을 수 있다.

7. #317 관리자 LLM 사용량 전체 조회 API 구현

LLM 사용량은 일반 사용자 본인 조회뿐 아니라, 관리자 관점에서도 확인할 필요가 있다.

그래서 관리자 전용 전체 LLM 사용량 조회 API를 추가했다.

8. #318 관리자 LLM 사용량 로그 화면 구현

관리자 API를 만든 뒤에는 프론트 관리자 화면에서도 LLM 사용량 로그를 확인할 수 있도록 화면을 추가했다.

관리자 화면에서는 다음 정보를 확인할 수 있다.

사용자 이메일
닉네임
모델명
Prompt 토큰
Completion 토큰
Total 토큰
예상 비용
성공/실패 상태
실패 메시지
호출 일시

예상 비용은 달러 기준으로 저장되지만, 화면에서는 원화로도 볼 수 있도록 환율 API를 이용해 KRW 변환 표시를 추가했다.

다만 실제 운영 환경에서는 환율 API 장애나 변동성을 고려해 fallback 환율도 함께 두었다.

9. 트러블슈팅: Flyway Migration이 적용되지 않던 문제

이번 작업 중 가장 크게 막혔던 부분은 Flyway migration이었다.

AI 대화 세션과 LLM 사용량 로그를 저장하기 위해 새로운 테이블을 추가했고, 이를 Flyway migration으로 관리하려고 했다.

하지만 V4, V5 migration 파일을 추가했는데도 flyway_schema_history 테이블에 버전이 등록되지 않는 문제가 있었다.

처음에는 SQL 파일명 문제라고 생각했지만, 실제로는 DB 연결 정보와 migration 적용 대상 DB를 함께 확인해야 하는 문제였다.

발생 상황

Backend를 실행했는데 신규 migration이 적용되지 않았다.

flyway_schema_history를 조회해도 기대했던 V4, V5가 보이지 않았다.

또한 dev 브랜치를 병합한 뒤에는 Backend 실행 자체가 실패하는 상황도 발생했다.

확인한 쿼리

먼저 현재 Flyway가 어떤 migration을 적용했는지 확인했다.

SELECT installed_rank, version, description, script, success
FROM flyway_schema_history
ORDER BY installed_rank;

이 쿼리로 Flyway가 실제로 어떤 파일까지 실행했는지 확인할 수 있다.

다음으로 현재 내가 접속한 DB가 Backend가 바라보는 DB와 같은지 확인했다.

SELECT current_database();

현재 schema도 확인했다.

SELECT current_schema();

그리고 migration으로 생성되어야 하는 테이블이 실제로 존재하는지도 확인했다.

SELECT table_name
FROM information_schema.tables
WHERE table_schema = 'public'
  AND table_name IN (
    'conversation_sessions',
    'conversation_messages',
    'llm_usage_logs'
  );

원인 분석

원인은 크게 두 가지로 나눠 볼 수 있었다.

첫 번째는 application-secret.env의 DB 접속 정보가 현재 실행하려는 DB와 맞지 않았던 점이다.

두 번째는 Flyway가 바라보는 DB와 내가 직접 쿼리로 확인하던 DB가 일치하지 않을 가능성이 있었다는 점이다.

즉, migration 파일은 존재하지만 Backend 실행 시점에 다른 DB를 보고 있으면 flyway_schema_history에는 기대한 버전이 보이지 않는다.

또한 dev 브랜치를 병합하면서 환경 설정이나 migration 파일 순서가 바뀌면, 기존에 정상 실행되던 Backend도 다시 실패할 수 있다.

해결 과정

먼저 Backend 실행 로그에서 실제 DB URL을 확인했다.

그 다음 application-secret.env의 DB_URL, DB_USERNAME, DB_PASSWORD 값을 점검했다.

이후 현재 접속 DB와 schema를 SQL로 확인했다.

마지막으로 flyway_schema_history와 information_schema.tables를 조회해 migration 적용 여부와 실제 테이블 생성 여부를 함께 확인했다.

정리하면 확인 순서는 다음과 같다.

Backend 실행 로그에서 실제 DB URL 확인
application-secret.env의 DB 접속 정보 확인
current_database()로 현재 접속 DB 확인
current_schema()로 현재 schema 확인
flyway_schema_history에서 V4, V5 적용 여부 확인
information_schema.tables로 실제 테이블 생성 여부 확인
Backend 재실행 후 migration 정상 반영 확인

최종적으로 DB 연결 정보를 정리하고 Backend를 재실행하자 migration이 정상 반영되었다.

배운 점

Flyway 문제를 볼 때는 migration 파일만 보면 안 된다.

파일명이 맞는지, SQL 문법이 맞는지도 중요하지만, 그보다 먼저 “내가 지금 어느 DB를 보고 있는지”를 확인해야 한다.

이번 경험을 통해 Flyway migration을 점검할 때는 다음 기준이 중요하다는 것을 알게 되었다.

Backend가 실제로 연결한 DB 확인
내가 직접 쿼리로 확인하는 DB 확인
flyway_schema_history 확인
실제 테이블 생성 여부 확인
dev 병합 후 설정 변경 여부 확인

결국 Flyway 문제는 단순히 SQL 파일 문제가 아니라, DB 연결 정보와 migration 이력, 실제 schema 상태를 함께 확인해야 해결할 수 있었다.

10. 테스트 및 검증

이번 작업에서 확인한 내용은 다음과 같다.

Backend

AI 추천 API 200 응답 확인
냉장고 보유 재료 추천 제외 확인
미구매 장보기 항목 추천 제외 확인
못 먹는 재료 추천 제외 확인
excludeProductIds 기반 재추천 제외 확인
AI 대화 세션 저장 확인
AI 메시지 기록 저장 확인
LLM 사용량 로그 저장 확인
관리자 전체 LLM 로그 조회 확인

Frontend

장보기 화면 AI 추천 버튼 표시 확인
추천 결과 카드 표시 확인
추천 항목 장보기 담기 확인
기존 장보기 CRUD 영향 없음 확인
관리자 LLM 사용량 화면 표시 확인
빌드 성공 확인

Agent

FastAPI Agent 서버 추천 응답 확인
OpenAI API Key 없는 경우 fallback 동작 확인
사용량 응답 구조 확인
선호 음식 기반 prompt 전달 확인

11. 이번 작업에서 신경 쓴 점

이번 작업에서 가장 신경 쓴 부분은 AI가 직접 DB를 수정하지 않도록 한 것이다.

AI 추천 결과를 바로 장보기 목록에 저장하면 편해 보일 수 있지만, 사용자가 원하지 않는 재료가 자동으로 추가될 위험이 있다.

그래서 추천과 저장을 분리했다.

추천 API는 추천 결과만 반환하고, 실제 장보기 추가는 사용자가 선택한 항목만 별도 API로 저장한다.

또한 기존 장보기 중복 등록 방지 정책을 그대로 재사용했다.

이렇게 하면 일반 장보기 추가와 AI 추천 장보기 추가가 서로 다른 정책으로 동작하지 않고, 동일한 서비스 로직을 기준으로 관리된다.

12. 남은 개선 방향

현재 AI 장보기 추천 기능은 MVP 수준으로 동작한다.

다만 추천 품질과 속도 측면에서는 추가 개선 여지가 있다.

앞으로 개선할 수 있는 부분은 다음과 같다.

추천 후보 재료 수 최적화
LLM prompt 길이 축소
추천 이유 문장 길이 제한
같은 조건의 추천 캐싱
재추천 시 더 다양한 결과 제공
사용자 선호 음식과 식단 패턴 반영 강화
FREE/PREMIUM 권한 정책 적용
AI 대화 기록 화면 고도화
LLM 비용 통계 대시보드 개선

특히 추천 속도는 Agent에 넘기는 후보 재료 수와 prompt 길이에 영향을 많이 받는다.

따라서 다음 단계에서는 후보군을 DB에서 먼저 줄이고, Agent에는 꼭 필요한 정보만 전달하는 방향으로 개선할 예정이다.

13. 마무리

이번 작업을 통해 냉파마스터의 장보기 기능을 단순 CRUD에서 AI 기반 추천 흐름으로 확장했다.

기존 냉장고, 장보기, 못 먹는 재료, 선호 음식 데이터를 활용해 추천 후보를 만들고, FastAPI Agent와 LLM을 연결할 수 있는 기반을 구성했다.

또한 추천 결과를 저장하지 않고 사용자 승인 후 장보기 목록에 추가하는 방식으로 안전한 사용자 흐름을 유지했다.

이번 작업은 단순히 AI API를 붙이는 것이 아니라, 기존 서비스 정책과 AI 추천 흐름을 어떻게 연결할지 고민한 작업이었다.

앞으로는 추천 품질, 응답 속도, 구독 정책, 비용 관리까지 확장해 더 실사용에 가까운 AI 장보기 Agent로 발전시킬 수 있을 것 같다.

[TIL]CI/CD, GitHub Actions, Argo CD, Jenkins, Kubernetes, AWS 배포

namerong — Wed, 5 Aug 2026 16:16:05 +0900

1. 학습 주제

애플리케이션을 개발한 뒤 서버에 배포하는 흐름과, 이를 자동화하는 CI/CD 개념을 학습했다.
또한 AWS 환경에서 직접 배포를 진행하며 EC2와 Elastic Beanstalk 같은 배포 방식의 차이를 정리했다.

핵심 내용은 다음과 같다.

CI/CD 개념
GitHub Actions
Jenkins
Argo CD
Kubernetes
AWS EC2 배포
Elastic Beanstalk
VPC 기본 개념

2. CI/CD란?

CI/CD는 개발한 코드를 자동으로 검사하고 배포하기 위한 개발 자동화 흐름이다.

코드 작성
-> Git push
-> 빌드
-> 테스트
-> 이미지 생성
-> 서버 배포

CI와 CD는 역할이 조금 다르다.

구분	의미	역할
CI	Continuous Integration	코드 변경 사항을 자주 통합하고 빌드/테스트
CD	Continuous Delivery 또는 Continuous Deployment	검증된 코드를 배포 가능한 상태로 만들거나 실제 배포

CI는 “코드가 정상적으로 합쳐질 수 있는지 확인하는 단계”에 가깝다.
CD는 “검증된 결과물을 서버에 반영하는 단계”에 가깝다.

3. CI가 필요한 이유

여러 명이 동시에 개발하면 코드가 자주 바뀐다.
이때 사람이 매번 직접 빌드하고 테스트하면 실수하기 쉽고 시간이 많이 든다.

CI를 사용하면 Git에 코드가 올라갈 때마다 자동으로 확인할 수 있다.

push 또는 pull request
-> 의존성 설치
-> build
-> test
-> 결과 확인

CI의 목적은 문제가 있는 코드가 main 또는 dev 브랜치에 섞이는 것을 줄이는 것이다.

4. CD가 필요한 이유

CD는 배포 과정을 자동화한다.

수동 배포는 보통 다음 작업을 사람이 직접 해야 한다.

서버 접속
-> 최신 코드 받기
-> 빌드
-> 실행 중인 서버 중지
-> 새 버전 실행
-> 로그 확인

CD를 사용하면 이 흐름을 자동화할 수 있다.

배포 브랜치에 merge
-> 빌드
-> Docker 이미지 생성
-> 서버 또는 Kubernetes에 반영

배포 자동화의 장점은 다음과 같다.

반복 작업을 줄일 수 있다.
사람의 실수를 줄일 수 있다.
배포 속도가 빨라진다.
배포 이력을 추적하기 쉽다.

5. GitHub Actions

GitHub Actions는 GitHub에서 제공하는 CI/CD 자동화 도구이다.

GitHub 저장소 안에 workflow 파일을 작성하면 특정 이벤트에 맞춰 작업이 실행된다.

push
pull_request
workflow_dispatch

예를 들어 다음 흐름을 만들 수 있다.

GitHub에 push
-> GitHub Actions 실행
-> Gradle build
-> 테스트
-> Docker 이미지 빌드
-> 배포 서버로 전달

GitHub Actions는 GitHub 저장소와 바로 연결되어 있기 때문에, 개인 프로젝트나 팀 프로젝트에서 CI를 시작하기 쉽다.

6. Jenkins

Jenkins는 오래전부터 많이 사용된 CI/CD 도구이다.

GitHub Actions가 GitHub 중심의 자동화라면, Jenkins는 별도의 서버에 설치해서 사용하는 자동화 서버에 가깝다.

Jenkins 서버
-> Git 저장소 감지
-> 빌드
-> 테스트
-> 배포 스크립트 실행

Jenkins의 특징은 다음과 같다.

플러그인이 많다.
오래된 회사 시스템에서도 많이 사용된다.
자유도가 높다.
직접 서버를 운영해야 하므로 관리 부담이 있다.

정리하면 다음과 같다.

도구	특징
GitHub Actions	GitHub 저장소와 연동이 쉽고 설정이 간단
Jenkins	자유도가 높고 기존 기업 환경에서 많이 사용

7. Argo CD

Argo CD는 Kubernetes 환경에서 많이 사용하는 GitOps 기반 배포 도구이다.

GitOps는 Git 저장소를 배포 상태의 기준으로 삼는 방식이다.

Git에 배포 설정 변경
-> Argo CD가 감지
-> Kubernetes 상태와 비교
-> Git 상태와 다르면 자동 동기화

즉, Argo CD는 “Git에 적힌 상태가 실제 서버 상태가 되도록 맞춰주는 도구”라고 볼 수 있다.

예를 들어 Git에 다음 상태가 있다면:

backend image: v2
replicas: 3

Argo CD는 Kubernetes 클러스터가 실제로 이 상태가 되도록 반영한다.

8. Kubernetes

Kubernetes는 컨테이너를 여러 서버에서 안정적으로 실행하고 관리하는 플랫폼이다.

Docker가 컨테이너 하나를 실행하는 데 초점이 있다면, Kubernetes는 여러 컨테이너를 운영 환경에서 관리하는 데 초점이 있다.

Kubernetes가 해주는 일은 다음과 같다.

컨테이너 실행
여러 서버에 컨테이너 배치
장애가 난 컨테이너 재시작
트래픽 분산
배포 버전 관리
스케일 아웃
설정과 비밀값 관리

정리하면 다음과 같다.

Docker = 컨테이너 실행 도구
Kubernetes = 컨테이너 운영/관리 플랫폼

9. CI/CD 도구들의 관계

각 도구는 역할이 조금씩 다르다.

도구	주 역할
GitHub Actions	GitHub 이벤트 기반 빌드/테스트/배포 자동화
Jenkins	독립적인 CI/CD 자동화 서버
Argo CD	Kubernetes 배포 상태를 Git 기준으로 동기화
Kubernetes	컨테이너 실행과 운영 관리

예시 흐름은 다음과 같다.

GitHub Actions
-> 코드 빌드
-> 테스트
-> Docker 이미지 생성
-> 이미지 저장소에 push

Argo CD
-> Git의 Kubernetes 배포 설정 감지
-> Kubernetes 클러스터에 반영

10. AWS EC2 배포

EC2는 AWS에서 제공하는 가상 서버이다.
직접 Ubuntu 서버를 만들고, 그 안에 Java, Docker, Nginx 같은 필요한 도구를 설치해서 애플리케이션을 실행할 수 있다.

EC2 배포 흐름은 다음과 같다.

EC2 인스턴스 생성
-> SSH 접속
-> 필요한 런타임 설치
-> 프로젝트 파일 또는 Docker 이미지 준비
-> 서버 실행
-> 보안 그룹에서 포트 오픈
-> 외부 접속 확인

EC2만 사용해도 프로젝트 배포는 가능하다.
다만 로드 밸런싱, 자동 스케일링, 모니터링 같은 기능은 직접 추가로 구성해야 한다.

11. Elastic Beanstalk

Elastic Beanstalk는 AWS에서 애플리케이션 배포를 쉽게 해주는 서비스이다.

직접 EC2를 하나하나 설정하는 대신, 애플리케이션을 올리면 필요한 인프라 구성을 AWS가 대신 처리해준다.

Elastic Beanstalk가 도와주는 기능은 다음과 같다.

프로비저닝
로드 밸런싱
자동 스케일링
모니터링
애플리케이션 배포 관리

여기서 프로비저닝은 애플리케이션 실행에 필요한 서버, 네트워크, 환경을 준비하는 과정이다.

서버 생성
-> 런타임 준비
-> 네트워크 설정
-> 배포 환경 구성

12. EC2와 Elastic Beanstalk 차이

EC2는 서버를 직접 빌려서 직접 관리하는 방식이다.
Elastic Beanstalk는 애플리케이션 중심으로 배포하면 AWS가 필요한 EC2와 관련 리소스를 어느 정도 자동으로 관리해주는 방식이다.

구분	EC2	Elastic Beanstalk
관리 단위	서버	애플리케이션 환경
설정 자유도	높음	상대적으로 제한 있음
운영 편의성	직접 관리 필요	자동 구성 기능 제공
적합한 경우	서버 설정을 직접 제어하고 싶을 때	빠르게 배포 환경을 만들고 싶을 때

기존 프로젝트를 단순히 올려보는 단계라면 EC2만으로도 충분하다.
하지만 로드 밸런싱, 자동 스케일링, 모니터링까지 편하게 붙이고 싶다면 Elastic Beanstalk를 고려할 수 있다.

13. VPC

VPC는 AWS 안에서 사용하는 사용자 전용 가상 네트워크이다.

AWS 전체 공간 안에
내 서비스만 사용하는 네트워크 영역을 따로 만드는 것

VPC 안에서 다음을 설정할 수 있다.

IP 대역
Subnet
Routing Table
Internet Gateway
Security Group
Network ACL

EC2도 결국 특정 VPC와 Subnet 안에 생성된다.
외부에서 접속하려면 인터넷 연결 경로와 보안 그룹 설정이 맞아야 한다.

14. 실제 AWS 배포 흐름

실제 배포를 진행할 때는 코드 실행만 보면 안 되고, 서버와 네트워크까지 함께 확인해야 한다.

기본 흐름은 다음과 같다.

1. 애플리케이션 빌드
2. 서버 또는 배포 서비스 준비
3. 실행 환경 설정
4. 애플리케이션 업로드 또는 이미지 배포
5. 서버 실행
6. 포트 확인
7. AWS 보안 그룹 확인
8. 외부 접속 테스트

로컬에서 잘 실행되더라도 EC2에서 접속이 안 되면 다음을 확인해야 한다.

애플리케이션이 실제로 실행 중인가
서버 내부 포트가 열려 있는가
EC2 보안 그룹에서 해당 포트를 허용했는가
퍼블릭 IP 또는 도메인이 올바른가
방화벽 또는 네트워크 설정이 막고 있지 않은가

15. 핵심 정리

CI/CD는 빌드, 테스트, 배포 흐름을 자동화하는 방식이다.
CI는 코드 변경을 자동으로 빌드하고 테스트하는 단계이다.
CD는 검증된 결과물을 배포 가능한 상태로 만들거나 실제 서버에 배포하는 단계이다.
GitHub Actions는 GitHub 이벤트 기반으로 CI/CD를 구성하는 도구이다.
Jenkins는 별도 서버에서 운영하는 범용 CI/CD 자동화 도구이다.
Argo CD는 Kubernetes 환경에서 Git 상태를 기준으로 배포를 동기화하는 GitOps 도구이다.
Kubernetes는 컨테이너를 여러 서버에서 운영하고 관리하는 플랫폼이다.
EC2는 AWS에서 제공하는 가상 서버이며 직접 서버 설정과 배포를 관리해야 한다.
Elastic Beanstalk는 배포에 필요한 서버, 로드 밸런싱, 자동 스케일링, 모니터링을 대신 구성해주는 서비스이다.
VPC는 AWS 안에서 사용하는 사용자 전용 가상 네트워크이다.
EC2만으로도 배포는 가능하지만 운영 편의 기능은 직접 구성해야 한다.
실제 배포에서는 애플리케이션 실행뿐 아니라 포트, 보안 그룹, 네트워크 설정까지 함께 확인해야 한다.

냉파마스터 2차 프로젝트: 장보기 리팩토링과 AI Agent 확장 기반 만들기

namerong — Tue, 4 Aug 2026 17:42:11 +0900

1차 프로젝트에서는 냉장고, 사전 재료, 장보기 기능의 기본 CRUD와 프론트 연동을 중심으로 구현했다.
2차 프로젝트에서는 단순 기능 추가보다는 기존 기능을 더 안정적으로 다듬고,
이후 AI Agent 기능으로 확장할 수 있는 구조를 만드는 것을 목표로 잡았다.

이번 작업 범위는 크게 세 가지였다.

첫째, 장보기 항목 중복 등록 방지
둘째, AI Agent가 사용할 Tool API 구조 정리
셋째, 냉장고와 장보기 상태를 기반으로 한 장보기 추천 MVP 구현

1. 장보기 항목 중복 등록 방지

기존 장보기 기능은 같은 재료를 여러 번 추가할 수 있었다.
사용자가 직접 추가할 때는 물론이고, 이후 레시피 기반 추가나 AI 추천 추가가 붙으면 같은 재료가 반복해서 쌓일 가능성이 있었다.

그래서 동일 사용자 기준으로 다음 조건을 만족하는 장보기 항목은 중복 등록으로 판단했다.

같은 사용자
같은 productId
삭제되지 않은 항목
아직 구매 완료되지 않은 항목

즉, 사용자가 이미 “감자 1개”를 장보기 목록에 담아둔 상태에서 다시 감자를 추가하면 409 Conflict를 반환하도록 했다.

반대로 다음 경우는 재등록을 허용했다.

사용자가 기존 항목을 삭제한 경우
사용자가 기존 항목을 구매 완료 처리한 경우
다른 사용자가 같은 재료를 담은 경우

이렇게 처리한 이유는 장보기 목록이 “현재 구매 예정인 항목”을 관리하는 기능이기 때문이다.
이미 삭제했거나 구매 완료한 항목은 현재 구매 예정 목록이 아니므로 다시 추가할 수 있어야 한다.

2. Agent API 명세 정리

2차 프로젝트의 핵심 확장 방향은 AI Agent였다.
다만 AI가 바로 DB를 수정하도록 만들면 위험하다고 판단했다.

그래서 Agent API는 다음 원칙으로 설계했다.

AI는 필요한 데이터를 조회할 수 있다.
AI는 추천 결과를 만들 수 있다.
추천 결과는 DB에 바로 저장하지 않는다.
사용자가 승인한 항목만 장보기 목록에 저장한다.
저장 시에는 기존 ShoppingItemService 정책을 그대로 사용한다.

이 구조를 위해 API 번호는 기존 냉장고, 장보기 API와 충돌하지 않도록 700번대로 분리했다.

API ID	기능	Method	URL
API-700	Agent 냉장고 조회 Tool	GET	/api/v1/agent/tools/fridge-items
API-701	Agent 장보기 조회 Tool	GET	/api/v1/agent/tools/shopping-items
API-702	AI 장보기 추천 생성	POST	/api/v1/agent/shopping-recommendations
API-703	Agent 승인 항목 장보기 추가	POST	/api/v1/agent/tools/shopping-items

여기서 중요한 점은 추천 생성과 저장을 분리한 것이다.

추천 API는 “이 재료를 사면 좋겠다”는 후보만 반환하고,
장보기 추가 API는 사용자가 선택한 항목만 저장한다.

이렇게 하면 AI 추천이 잘못되더라도 사용자 데이터가 자동으로 변경되지 않는다.

3. Agent 냉장고/장보기 조회 Tool API 구현

AI가 장보기 추천을 하려면 먼저 사용자의 현재 상태를 알아야 한다.

그래서 Agent Tool API로 냉장고와 장보기 목록 조회 API를 만들었다.

GET /api/v1/agent/tools/fridge-items
GET /api/v1/agent/tools/shopping-items

이 API는 새 조회 로직을 따로 만들기보다는 기존 냉장고, 장보기 Service를 재사용했다.
이미 기존 Service에는 로그인 사용자 기준 조회와 소유자 검증 흐름이 들어가 있었기 때문이다.

Agent API라고 해서 별도 정책을 다시 만들면 같은 기능이 중복되고,
나중에 정책이 바뀔 때 한쪽만 수정되는 문제가 생길 수 있다.

그래서 Agent Tool API는 컨트롤러만 분리하고,
실제 데이터 조회는 기존 Service를 사용하도록 구성했다.

4. Agent 승인 항목 장보기 추가 Tool API 구현

AI가 추천한 항목을 사용자가 승인하면 장보기 목록에 추가해야 한다.

이때도 핵심은 기존 장보기 등록 정책을 재사용하는 것이었다.

기존 ShoppingItemService에는 다음 정책이 들어가 있다.

존재하지 않는 productId 차단
비활성 사전 재료 차단
중복 장보기 항목 차단
로그인 사용자 기준 저장

Agent 승인 항목 추가 API가 별도 저장 로직을 가지면 이 정책들이 중복되거나 누락될 수 있다.
그래서 Agent API는 요청을 받은 뒤 내부적으로 기존 장보기 등록 Service를 호출하도록 했다.

즉, Agent를 통해 추가하든 사용자가 직접 추가하든 같은 정책을 타게 된다.

이 구조 덕분에 #234에서 구현한 중복 등록 방지 정책도 Agent 추가 API에 그대로 적용된다.

5. AI 장보기 추천 MVP 구현

이번 단계의 AI 장보기 추천은 LLM을 직접 호출하는 형태는 아니다.
아직 FastAPI Agent 서버나 LLM 연동 정책이 확정되지 않았기 때문에, 먼저 Spring Boot 내부에서 규칙 기반 MVP로 구현했다.

현재 추천 흐름은 다음과 같다.

로그인한 사용자를 조회한다.
사용자의 냉장고 재료 목록을 조회한다.
사용자의 장보기 목록을 조회한다.
냉장고에 이미 있는 productId를 제외 목록에 추가한다.
장보기 목록 중 미구매 상태인 productId를 제외 목록에 추가한다.
활성 상태의 사전 재료 중 제외 목록에 없는 재료를 추천한다.
추천 결과는 DB에 저장하지 않고 응답으로만 반환한다.

예를 들어 사용자의 냉장고에 두부가 있고, 장보기 목록에 감자가 있다면 추천 후보에서는 두부와 감자를 제외한다.

사전 재료 전체: 두부, 감자, 양파, 대파, 계란
냉장고 보유: 두부
장보기 예정: 감자

6. 추천 결과를 바로 저장하지 않은 이유

AI 추천 기능에서 가장 조심해야 할 부분은 자동 저장이다.

AI가 추천한 결과를 바로 장보기 목록에 저장하면 사용자가 원하지 않는 재료가 목록에 들어갈 수 있다.
특히 장보기 목록은 실제 구매 행동으로 이어지는 기능이기 때문에, 사용자의 승인 단계가 필요하다고 봤다.

그래서 이번 구조는 다음처럼 나눴다.

추천 생성 API
→ 추천 목록만 반환
→ DB 저장 없음

승인 항목 추가 API
→ 사용자가 선택한 항목만 저장
→ 기존 장보기 등록 정책 적용

이렇게 분리하면 AI 기능을 붙이더라도 사용자 데이터 변경은 항상 사용자의 선택을 거치게 된다.

7. 테스트

이번 작업에서는 AI 장보기 추천 Service 테스트를 추가했다.

테스트한 내용은 다음과 같다.

냉장고 보유 재료는 추천에서 제외된다.
미구매 장보기 항목은 추천에서 제외된다.
추천 결과는 요청 limit 이하로 반환된다.
limit 값이 없으면 기본값이 적용된다.
존재하지 않는 회원이면 추천에 실패한다.

테스트 중 한 번 실패한 부분도 있었다.

처음에는 테스트에서 새로 만든 추천 가능 재료가 반드시 결과에 포함될 것이라고 기대했다.
하지만 로컬 DB에는 이미 활성 사전 재료가 많이 존재하고, 추천 결과는 limit 개수만큼 잘려 반환된다.
따라서 새로 만든 재료가 추천 후보에는 포함될 수 있어도, limit 안에 반드시 들어온다고 보장할 수 없었다.

그래서 테스트 기준을 다음처럼 수정했다.

제외되어야 하는 재료가 실제로 제외되는지 확인
추천 결과 개수가 limit을 넘지 않는지 확인

이렇게 수정하니 테스트가 실제 추천 로직의 목적과 더 잘 맞았다.

8. 현재 한계와 다음 단계

현재 #238은 LLM 연동 전 규칙 기반 MVP다.
따라서 다음 내용은 아직 남아 있다.

FastAPI Agent 서버 연동
LLM 호출 구조 구현
LLM 실패 시 예외 처리
추천 이유 생성 고도화
PREMIUM/FREE 권한 정책 연결
추천 결과 정렬 기준 개선

현재 프로젝트에는 아직 PREMIUM/FREE 구독 권한 구조가 없기 때문에, 무료/유료 사용자 분기는 바로 구현하지 않았다.
이 부분은 결제 또는 구독 정책이 확정된 뒤 연결하는 것이 맞다고 판단했다.

9. 정리

이번 작업은 단순히 AI 추천 API 하나를 만든 작업이라기보다는,
기존 장보기 기능을 AI Agent가 안전하게 사용할 수 있도록 기반을 만든 작업이었다.

특히 다음 세 가지를 중요하게 봤다.

기존 Service 정책 재사용
추천과 저장 흐름 분리
사용자 데이터 자동 변경 방지

아직 LLM이 붙은 완성형 AI 기능은 아니지만,
냉장고와 장보기 상태를 기반으로 추천 후보를 만들고,
사용자가 승인한 항목만 장보기 목록에 저장하는 구조를 만들었다는 점에서 2차 프로젝트의 출발점으로 의미가 있었다.

[TIL]Dockerfile, Docker Compose, AWS EC2 기초

namerong — Tue, 4 Aug 2026 16:18:34 +0900

1. 학습 주제

Dockerfile로 애플리케이션 이미지를 만들고, Docker Compose로 여러 컨테이너를 함께 실행하는 흐름을 학습했다.
추가로 AWS EC2 같은 클라우드 서버에 파일을 올리고, 서버에서 Docker 이미지로 실행하는 기본 배포 흐름도 정리했다.

핵심 내용은 다음과 같다.

Dockerfile
Docker 이미지와 컨테이너
JRE와 JDK 차이
Spring Boot JAR Docker 이미지 생성
scp로 EC2 서버에 파일 전송
EC2 방화벽 설정
Docker Compose
Docker Network
Docker Volume
Cloud, IaaS, PaaS, SaaS
AWS 주요 서비스

2. Dockerfile이란?

Dockerfile은 Docker 이미지를 만들기 위한 설명서이다.
이미지를 만들 때 필요한 실행 환경, 파일, 명령어, 실행 순서를 적어둔다.

FROM eclipse-temurin:21-jre

ARG JAR_FILE=build/libs/*.jar

COPY ${JAR_FILE} app.jar

ENTRYPOINT ["java", "-jar", "/app.jar"]

각 줄의 의미는 다음과 같다.

명령어	의미
FROM	어떤 기본 이미지에서 시작할지 지정
ARG	이미지 빌드 시 사용할 변수
COPY	로컬 파일을 이미지 안으로 복사
ENTRYPOINT	컨테이너가 실행될 때 실행할 명령어

즉, 위 Dockerfile은 다음 흐름이다.

JRE 21 환경 준비
-> build/libs/*.jar 파일을 app.jar로 복사
-> java -jar /app.jar 실행

3. JRE와 JDK 차이

Java 애플리케이션을 실행할 때 JRE와 JDK를 구분해야 한다.

구분	의미
JRE	Java 애플리케이션 실행 환경
JDK	JRE + 개발 도구

JRE는 이미 만들어진 .jar 파일을 실행하는 데 충분하다.
JDK는 Java 코드를 컴파일하고 개발할 때 필요하다.

이번 Dockerfile은 이미 빌드된 Spring Boot JAR를 실행하는 목적이므로 JDK가 아니라 JRE 이미지를 사용했다.

FROM eclipse-temurin:21-jre

정리하면 다음과 같다.

개발/빌드 필요 -> JDK
실행만 필요 -> JRE

4. Spring Boot 앱 Docker 이미지 만들기

Spring Boot 프로젝트는 먼저 JAR 파일로 빌드한다.

./gradlew build

그 다음 Dockerfile이 있는 위치에서 이미지를 만든다.

docker build -t namhyerhin/dockertest .

여기서 -t는 이미지 이름과 태그를 붙이는 옵션이다.

docker build -t 이미지이름 .

마지막의 .은 현재 디렉터리의 Dockerfile과 파일들을 build context로 사용한다는 뜻이다.

5. 이미지와 컨테이너

Docker에서 이미지는 실행을 위한 템플릿이고, 컨테이너는 이미지를 실제로 실행한 상태이다.

개념	의미
이미지	실행 환경, 코드, 라이브러리를 묶은 것
컨테이너	이미지를 실행한 프로세스

비유하면 다음과 같다.

이미지 = 설계도
컨테이너 = 설계도로 실행된 실제 프로그램

하나의 이미지로 여러 컨테이너를 만들 수 있다.

6. EC2 서버로 파일 전송

로컬에서 빌드한 JAR 파일이나 Dockerfile을 EC2 서버로 올릴 때 scp를 사용할 수 있다.

JAR 파일 전송:

scp -i "/System/Volumes/Data/Users/hyerhin/ubuntu-server.pem" -r /Users/hyerhin/Desktop/hyerhin/Study/lecture/13_AWS/dockerpro/build/libs/dockerpro-0.0.1-SNAPSHOT.jar ubuntu@13.125.208.6:~

Dockerfile 전송:

scp -i "/System/Volumes/Data/Users/hyerhin/ubuntu-server.pem" -r /Users/hyerhin/Desktop/hyerhin/Study/lecture/13_AWS/dockerpro/Dockerfile ubuntu@13.125.208.6:~

흐름은 다음과 같다.

로컬에서 JAR 빌드
-> scp로 EC2에 JAR와 Dockerfile 업로드
-> EC2에서 docker build
-> 컨테이너 실행
-> EC2 보안 그룹에서 포트 오픈

서버에서 애플리케이션을 띄웠더라도 EC2 방화벽, 즉 보안 그룹에서 해당 포트를 열지 않으면 외부에서 접속할 수 없다.

7. 포트 확인과 프로세스 종료

특정 포트를 어떤 프로세스가 사용 중인지 확인할 때 lsof를 사용할 수 있다.

lsof -i :8080

프로세스를 종료할 때는 PID를 확인한 뒤 종료한다.

kill [PID]

예를 들어 8080 포트를 이미 다른 프로세스가 사용 중이면 Spring Boot나 Docker 컨테이너가 같은 포트로 실행되지 않을 수 있다.

8. Docker Compose란?

Docker Compose는 여러 컨테이너를 한 번에 정의하고 실행하는 도구이다.

이번 예제에서는 Node.js 앱과 Redis를 함께 실행했다.

services:
  app:
    build: .
    ports:
      - "3000:3000"
    depends_on:
      - redis

  redis:
    image: redis:alpine

구조는 다음과 같다.

app 컨테이너
-> Node.js Express 서버

redis 컨테이너
-> Redis 저장소

depends_on은 app 컨테이너가 redis 컨테이너에 의존한다는 뜻이다.

9. Compose에서 컨테이너끼리 통신

Node.js 코드에서는 Redis에 다음 주소로 접속한다.

const client = redis.createClient({ url: 'redis://redis:6379' });

여기서 redis는 localhost가 아니라 Compose 서비스 이름이다.

redis:
  image: redis:alpine

Docker Compose 안에서는 같은 네트워크에 있는 서비스끼리 서비스 이름으로 접근할 수 있다.

app 컨테이너
-> redis:6379
-> redis 컨테이너

10. Docker Compose 명령어

자주 사용하는 명령어는 다음과 같다.

docker-compose up

서비스들을 실행한다.

docker-compose down

서비스를 중지하고 생성된 컨테이너와 네트워크를 정리한다.

docker-compose logs -f

실행 중인 로그를 계속 확인한다.

docker-compose config

Compose 설정 파일이 어떻게 해석되는지 확인한다.

docker-compose run [service]

특정 서비스 컨테이너를 일회성으로 실행한다.

11. Docker Network

Docker Network는 컨테이너들이 서로 통신할 수 있게 해주는 가상 네트워크이다.

네트워크 목록은 다음 명령어로 확인할 수 있다.

docker network ls

대표적인 네트워크 드라이버는 다음과 같다.

드라이버	설명
bridge	기본 네트워크. 같은 호스트 안의 컨테이너를 격리된 가상 LAN에 연결
host	컨테이너가 호스트 네트워크를 그대로 사용
overlay	여러 Docker 호스트 간 컨테이너 연결
macvlan	컨테이너에 별도 MAC 주소를 부여해 물리 네트워크에 직접 연결
none	네트워크 없이 컨테이너 실행

보통 단일 서버에서 Compose를 사용할 때는 기본적으로 bridge 계열 네트워크가 만들어진다.

12. Docker Volume

Docker Volume은 컨테이너가 삭제되어도 데이터를 유지하거나, 호스트와 컨테이너 사이에 데이터를 공유하기 위해 사용한다.

컨테이너 내부 파일은 컨테이너를 삭제하면 함께 사라질 수 있다.
하지만 Volume을 사용하면 데이터가 컨테이너 생명주기와 분리된다.

컨테이너 삭제
-> 컨테이너 내부 파일은 사라질 수 있음
-> Volume 데이터는 유지 가능

대표적인 방식은 다음과 같다.

방식	의미
Volume	Docker가 관리하는 저장 공간
Bind Mount	호스트의 특정 경로를 컨테이너에 직접 연결

개발 중에는 로컬 폴더를 바로 연결하는 Bind Mount가 편할 수 있고, 운영에서는 Docker Volume을 사용하는 경우가 많다.

13. 클라우드 서버란?

클라우드 서버는 물리 서버를 직접 구매하지 않고, 클라우드 제공자가 제공하는 가상 서버를 빌려 사용하는 방식이다.

장점은 다음과 같다.

초기 비용을 줄일 수 있다.
필요한 만큼 서버를 늘리거나 줄일 수 있다.
장애 대응과 인프라 관리 기능을 활용할 수 있다.
지역, 네트워크, 저장소 같은 자원을 쉽게 선택할 수 있다.

14. Hypervisor

Hypervisor는 가상 머신을 생성하고 실행해주는 기술이다.

VirtualBox도 Hypervisor의 한 종류로 볼 수 있다.

타입	설명
Type 1	하드웨어 위에서 직접 실행
Type 2	기존 운영체제 위에서 실행

VirtualBox는 일반적으로 내 OS 위에서 실행되므로 Type 2 방식에 가깝다.

15. IaaS, PaaS, SaaS

클라우드 서비스 모델은 보통 IaaS, PaaS, SaaS로 구분한다.

구분	의미	예시 느낌
IaaS	서버, 네트워크, 스토리지 같은 인프라 제공	EC2
PaaS	애플리케이션 실행 플랫폼 제공	앱 배포 플랫폼
SaaS	완성된 소프트웨어 제공	네이버 클라우드, Gmail 같은 서비스

정리하면 다음과 같다.

IaaS = 가상 서버를 빌림
PaaS = 실행 플랫폼을 빌림
SaaS = 완성된 서비스를 사용

16. AWS 주요 서비스

AWS에는 다양한 인프라 서비스가 있다.

서비스	역할
EC2	가상 서버 제공
S3	이미지, 문서, 동영상 같은 객체 스토리지
VPC	AWS 내부 네트워크 구성
IAM	사용자와 권한 관리
Route 53	DNS 서비스
ECS	Docker 컨테이너 실행 관리
EKS	Kubernetes 기반 컨테이너 실행 관리
SQS	메시지 큐 서비스
Lambda	서버 없이 함수 단위 코드 실행

이번 흐름에서는 EC2가 가장 직접적으로 연결된다.
EC2에 Ubuntu 서버를 만들고, 그 위에서 Docker를 설치해 애플리케이션 컨테이너를 실행할 수 있다.

17. IAM 계정

IAM은 AWS 리소스에 대한 접근 권한을 관리하는 서비스이다.

누가
어떤 리소스에
어떤 작업을 할 수 있는지
정하는 보안 시스템

예를 들어 어떤 사용자는 EC2 조회만 가능하고, 어떤 사용자는 S3 업로드까지 가능하게 권한을 나눌 수 있다.

실무에서는 루트 계정을 직접 쓰기보다 IAM 사용자나 역할을 만들어 권한을 제한해서 사용하는 것이 안전하다.

18. 핵심 정리

Dockerfile은 Docker 이미지를 만들기 위한 실행 환경과 순서를 적는 파일이다.
docker build -t 이미지명 .으로 현재 디렉터리의 Dockerfile을 기준으로 이미지를 만들 수 있다.
JRE는 Java 실행 환경이고, JDK는 JRE에 개발 도구까지 포함한 것이다.
이미 빌드된 Spring Boot JAR 실행만 필요하면 JRE 이미지로 충분하다.
이미지는 실행 템플릿이고, 컨테이너는 이미지를 실행한 상태이다.
scp를 사용하면 로컬 파일을 EC2 서버로 전송할 수 있다.
EC2에서 서버를 띄워도 보안 그룹에서 포트를 열어야 외부 접속이 가능하다.
lsof -i :8080으로 특정 포트를 사용하는 프로세스를 확인할 수 있다.
Docker Compose는 여러 컨테이너를 한 번에 정의하고 실행하는 도구이다.
Compose 안에서는 서비스 이름으로 컨테이너끼리 통신할 수 있다.
Docker Network는 컨테이너 간 통신을 위한 가상 네트워크이다.
Docker Volume은 컨테이너 삭제와 무관하게 데이터를 유지하거나 공유하기 위해 사용한다.
Cloud는 서버와 인프라 자원을 직접 소유하지 않고 빌려 쓰는 방식이다.
IaaS는 인프라, PaaS는 플랫폼, SaaS는 완성된 소프트웨어를 제공한다.
AWS EC2는 가상 서버, S3는 객체 저장소, IAM은 접근 권한 관리 서비스이다.

[TIL]Linux, Ubuntu, Vim, Docker 기초

namerong — Mon, 3 Aug 2026 15:51:46 +0900

1. 학습 주제

Linux와 Ubuntu의 기본 개념, 터미널 명령어, 에디터 사용법, Docker의 이미지와 컨테이너 개념을 학습했다.
서버 환경에서는 GUI보다 터미널을 많이 사용하기 때문에 기본 명령어와 파일 편집 도구에 익숙해지는 것이 중요하다.

핵심 내용은 다음과 같다.

Linux와 Ubuntu 개념
Shell과 터미널
Nano, vi, vim 차이
절대경로와 상대경로
기본 Linux 명령어
리디렉션과 grep
Docker 이미지와 컨테이너
Docker 컨테이너 실행, 접속, 중지, 삭제

2. Linux란?

Linux는 운영체제의 핵심인 Kernel을 기반으로 만들어진 운영체제 계열이다.
서버, 클라우드, Docker, 안드로이드 등 다양한 환경에서 많이 사용된다.

Linux 자체는 하나의 완성된 제품이라기보다, 여러 배포판의 기반이 된다.

대표적인 Linux 배포판은 다음과 같다.

배포판	특징
Ubuntu	입문자가 사용하기 좋고 자료가 많음
Debian	안정성을 중요하게 여김
CentOS / Rocky Linux	서버 환경에서 많이 사용
Fedora	최신 기술 반영이 빠름
Alpine	가볍고 Docker 이미지에서 자주 사용

수업에서는 Ubuntu를 중심으로 Linux 환경을 다뤘다.

3. Ubuntu와 VirtualBox

Ubuntu는 Linux 배포판 중 하나이다.
데스크톱이나 서버 환경에서 많이 사용되고, 패키지 설치 자료가 많아 학습용으로도 적합하다.

VirtualBox는 내 컴퓨터 안에 가상 컴퓨터를 만들어주는 프로그램이다.

내 컴퓨터
-> VirtualBox
-> Ubuntu 가상 머신

이렇게 하면 실제 컴퓨터 운영체제를 바꾸지 않고도 Ubuntu 환경을 실습할 수 있다.

4. Shell이란?

Shell은 사용자가 입력한 명령어를 운영체제에 전달하는 프로그램이다.

사용자 명령어
-> Shell
-> OS Kernel
-> 실행 결과

예를 들어 터미널에 다음 명령어를 입력하면:

ls

Shell이 이 명령을 해석해서 현재 디렉터리의 파일 목록을 출력한다.

자주 사용하는 Shell은 다음과 같다.

Shell	특징
sh	기본적인 Shell
bash	Linux에서 많이 사용
zsh	macOS 기본 Shell로 많이 사용

5. Nano, vi, vim 차이

터미널 환경에서는 파일을 수정할 때 터미널용 에디터를 사용한다.

에디터	특징
Nano	사용법이 단순하고 입문자에게 쉬움
vi	대부분의 Unix/Linux 서버에 기본 포함된 에디터
vim	vi의 확장판으로 기능이 더 많음

nano는 화면 아래에 단축키가 보여서 처음 쓰기 쉽다.
vi와 vim은 처음에는 어렵지만, 서버 환경에서 자주 만난다.

vim은 플러그인을 붙이면 IDE처럼 사용할 수도 있다.

자동완성
문법 강조
파일 탐색
검색
Git 연동

서버에서 설정 파일을 빠르게 고쳐야 할 때 vi 또는 vim을 사용할 일이 많다.

6. Apt

apt는 Ubuntu에서 패키지를 설치하고 관리하는 도구이다.

sudo apt update
sudo apt install vim

역할은 다음과 같다.

명령어	의미
apt update	설치 가능한 패키지 목록 갱신
apt install	패키지 설치
apt remove	패키지 삭제

Ubuntu에서 프로그램을 설치할 때 자주 사용한다.

7. 절대경로와 상대경로

경로는 파일이나 디렉터리의 위치를 나타낸다.

절대경로는 루트 디렉터리 /부터 시작하는 전체 경로이다.

/home/user/project/file.txt

상대경로는 현재 위치를 기준으로 한 경로이다.

./file.txt
../project/file.txt

자주 쓰는 기호는 다음과 같다.

기호	의미
/	루트 디렉터리
.	현재 디렉터리
..	상위 디렉터리
~	현재 사용자의 홈 디렉터리

8. 기본 Linux 명령어

자주 사용하는 명령어는 다음과 같다.

명령어	역할
pwd	현재 위치 출력
ls	파일 목록 출력
cd	디렉터리 이동
mkdir	디렉터리 생성
touch	빈 파일 생성
rm	파일 또는 디렉터리 삭제
cat	파일 내용 출력
cp	파일 복사
mv	파일 이동 또는 이름 변경
find	파일 검색
which	명령어 실행 위치 확인

예시:

mkdir test
cd test
touch memo.txt
cat memo.txt

9. rm 사용 주의

rm은 삭제 명령어이다.
휴지통으로 보내는 것이 아니라 바로 삭제되기 때문에 조심해야 한다.

rm file.txt
rm -r folder

특히 다음 명령은 매우 위험하다.

rm -rf /

삭제 명령어는 실행 전 경로를 꼭 확인해야 한다.

10. 리디렉션

리디렉션은 명령어의 출력 결과를 파일로 보내는 기능이다.

echo "hello" > memo.txt

>는 기존 내용을 덮어쓴다.

echo "world" >> memo.txt

>>는 기존 내용 뒤에 추가한다.

정리하면 다음과 같다.

기호	의미
>	출력 결과를 파일에 덮어쓰기
>>	출력 결과를 파일에 이어쓰기
<	파일 내용을 입력으로 사용

11. grep과 정규 표현식

grep은 파일 내용에서 특정 문자열을 찾는 명령어이다.

grep "error" app.log

정규 표현식을 함께 사용하면 더 복잡한 패턴도 찾을 수 있다.

grep "^Error" app.log

의미는 다음과 같다.

표현식	의미
^	줄의 시작
$	줄의 끝
.	임의의 한 글자
*	앞 패턴이 0번 이상 반복

로그 파일에서 에러를 찾거나 설정 파일에서 특정 값을 찾을 때 많이 사용한다.

12. Docker란?

Docker는 애플리케이션을 컨테이너라는 격리된 환경에서 실행하고 관리하는 도구이다.

간단히 말하면 다음과 같다.

프로그램 실행에 필요한 것들
+ 라이브러리
+ 설정
+ 실행 환경
= 이미지로 묶음

이미지를 실행한 상태
= 컨테이너

Docker를 사용하면 내 컴퓨터, 서버, AWS 등 어디서 실행하든 비슷한 환경을 만들 수 있다.

13. 이미지와 컨테이너

Docker에는 이미지와 컨테이너가 있다.

개념	의미
이미지	실행에 필요한 파일, 라이브러리, 설정을 묶은 템플릿
컨테이너	이미지를 실제로 실행한 상태

비유하면 다음과 같다.

이미지 = 실행 설계도
컨테이너 = 설계도로 실제 실행된 프로그램

하나의 이미지로 여러 컨테이너를 만들 수 있다.

14. Docker를 사용하는 이유

Docker를 사용하면 실행 환경을 맞추기 쉽다.

예를 들어 어떤 프로젝트가 특정 버전의 Ubuntu, Java, Python, 라이브러리를 필요로 한다면 이 환경을 이미지로 묶어둘 수 있다.

장점은 다음과 같다.

환경 차이로 인한 오류를 줄일 수 있다.
배포가 쉬워진다.
컨테이너 단위로 실행과 삭제가 가능하다.
서버에 여러 서비스를 격리해서 실행할 수 있다.
Docker Hub, GitHub, AWS 등과 연결해 배포하기 좋다.

15. Scale Up과 Scale Out

서비스 성능을 늘리는 방식에는 Scale Up과 Scale Out이 있다.

개념	의미
Scale Up	서버 한 대의 성능을 높이는 것
Scale Out	서버나 컨테이너 수를 늘리는 것

예를 들어 CPU와 RAM을 더 좋은 것으로 바꾸는 것은 Scale Up이다.
같은 서버를 여러 대로 늘리는 것은 Scale Out이다.

Docker는 컨테이너 단위로 서비스를 여러 개 띄우기 좋아서 Scale Out 구조와 잘 맞는다.

16. Docker 기본 명령어

실행 중인 컨테이너 목록을 확인한다.

docker ps

전체 컨테이너 목록을 확인한다.

docker ps -a

Docker 명령어 도움말을 확인한다.

docker --help

컨테이너를 시작한다.

docker start ubuntu_test2

컨테이너에 접속한다.

docker attach ubuntu_test2

컨테이너를 중지한다.

docker container stop ubuntu_test2

컨테이너를 강제로 삭제한다.

docker container rm -f ubuntu_test2

중지된 컨테이너를 한 번에 정리한다.

docker container prune

17. 컨테이너에서 빠져나오기

컨테이너에 접속한 상태에서 빠져나오는 방법은 두 가지가 있다.

Ctrl + P, Q

이 방식은 컨테이너를 계속 실행한 채로 빠져나온다.

Ctrl + D
exit

이 방식은 Shell을 종료하므로 컨테이너도 종료될 수 있다.

정리하면 다음과 같다.

방법	결과
Ctrl + P, Q	컨테이너 실행 유지 후 빠져나오기
Ctrl + D	Shell 종료
exit	Shell 종료

18. 핵심 정리

Linux는 서버와 클라우드 환경에서 많이 사용하는 운영체제 계열이다.
Ubuntu는 Linux 배포판 중 하나로 학습과 서버 환경에서 자주 사용된다.
VirtualBox를 사용하면 내 컴퓨터 안에서 Ubuntu 가상 머신을 실행할 수 있다.
Shell은 사용자의 명령어를 운영체제에 전달하는 프로그램이다.
Nano는 쉽고, vi는 기본 제공 가능성이 높고, vim은 확장성이 좋다.
apt는 Ubuntu의 패키지 설치 및 관리 도구이다.
절대경로는 /부터 시작하고, 상대경로는 현재 위치를 기준으로 한다.
ls, mkdir, touch, rm, cat, cp, mv, find, which는 기본 명령어로 익숙해져야 한다.
리디렉션은 명령어 출력 결과를 파일로 저장하거나 이어붙일 때 사용한다.
grep은 파일 내용에서 특정 문자열이나 패턴을 찾을 때 사용한다.
Docker는 애플리케이션을 컨테이너로 실행하고 관리하는 도구이다.
이미지는 실행 환경 템플릿이고, 컨테이너는 이미지를 실행한 상태이다.
Docker를 사용하면 환경 차이를 줄이고 배포를 쉽게 만들 수 있다.
docker ps는 실행 중인 컨테이너, docker ps -a는 전체 컨테이너를 보여준다.
Ctrl + P, Q는 컨테이너를 유지한 채 빠져나오는 방법이다.
docker container prune은 중지된 컨테이너를 정리할 때 사용한다.

[TIL]LangSmith로 Workflow 추적과 평가하기

namerong — Fri, 31 Jul 2026 14:29:43 +0900

1. 학습 주제

LangSmith를 사용해 AI Workflow 실행 과정을 추적하고, 실패 원인을 확인하며, 수정 전후 결과를 Dataset과 Experiment로 비교하는 흐름을 학습했다.

핵심 내용은 다음과 같다.

LangSmith 환경 설정 확인
@traceable을 사용한 실행 추적
Workflow 실행 Trace 기록
실패 Workflow 추적
baseline 버전과 fixed 버전 비교
Dataset 생성
Evaluator 작성
Experiment 실행과 비교

2. LangSmith란?

LangSmith는 LangChain, LangGraph 기반 애플리케이션의 실행 과정을 관찰하고 평가할 수 있게 도와주는 도구이다.

AI Workflow는 내부에서 여러 단계가 실행된다.

Planner
-> Executor
-> Task 실행
-> Validator
-> 결과 반환

이 흐름이 실패했을 때 단순히 “답이 이상하다”로는 원인을 찾기 어렵다.
LangSmith를 사용하면 각 단계가 어떤 입력을 받고, 어떤 출력을 만들었는지 Trace로 확인할 수 있다.

3. 환경 변수 설정

LangSmith에 Trace를 업로드하려면 환경 변수가 필요하다.

LANGSMITH_API_KEY
LANGSMITH_TRACING
LANGSMITH_PROJECT

설정 확인 함수에서는 누락된 값과 잘못된 값을 검사했다.

LANGSMITH_REQUIRED = (
    "LANGSMITH_API_KEY",
    "LANGSMITH_TRACING",
    "LANGSMITH_PROJECT",
)

LANGSMITH_TRACING은 true 계열 값이어야 한다.

if tracing and tracing not in {"true", "1", "yes", "on"}:
    errors.append("LANGSMITH_TRACING은 true여야 합니다.")

API Key는 그대로 출력하지 않고 일부만 마스킹해서 확인했다.
Key를 로그에 그대로 노출하지 않는 습관도 중요하다.

4. Trace

Trace는 실행 기록이다.
어떤 함수가 어떤 입력으로 실행되었고, 어떤 결과나 에러를 냈는지 남긴다.

이번 Workflow에서는 각 Task 함수를 @traceable로 감쌌다.

@traceable(name="task-destination", run_type="tool")
def traced_destination(request, context):
    execute_destination(request, context)
    return {
        "destinations": [
            place.model_dump() for place in context["destinations"]
        ]
    }

이렇게 하면 LangSmith에서 task-destination, task-budget, task-compose 같은 단계를 각각 확인할 수 있다.

5. Workflow Trace 구조

Workflow 전체도 @traceable로 감싸서 하나의 Chain 실행으로 기록했다.

@traceable(name="d-travel-workflow", run_type="chain")
def run_workflow(inputs: dict, version: PlanVersion = "fixed") -> dict:
    ...

실행 흐름은 다음과 같다.

run_workflow
-> build_workflow
-> planner
-> executor
-> task-requirements
-> task-weather
-> task-destination
-> task-budget
-> task-compose
-> validator

Trace를 보면 전체 흐름뿐 아니라 내부 Task별 실행 결과까지 볼 수 있다.
그래서 실패했을 때 어느 Task에서 문제가 생겼는지 확인하기 쉽다.

6. baseline과 fixed

이번 실습에서는 Workflow 버전을 나누어 실행했다.

PlanVersion = Literal["baseline", "fixed", "llm", "runtime_error"]

각 버전의 의미는 다음과 같다.

버전	의미
baseline	수정 전 Plan
fixed	수정 후 Plan
llm	실제 LLM이 생성한 Plan
runtime_error	오류 재현용 Plan

baseline은 destination Task가 빠진 Plan이었다.

requirements
-> weather
-> budget
-> compose

장소 후보를 검색하지 않고 예산 계산과 일정 작성을 진행하므로 검증 실패가 발생할 수 있다.

fixed는 장소 검색 Task까지 포함한다.

requirements
-> weather
-> destination
-> budget
-> compose

즉, 수정 전후의 차이를 LangSmith에 기록하고 비교할 수 있게 구성했다.

7. 실패 Trace 확인

실패를 일부러 재현하는 코드도 있었다.

version="runtime_error"

runtime_error 버전은 compose Task가 빠져 있어 최종 draft가 생성되지 않는다.

if draft is None:
    raise ValueError("실행 결과에 Draft가 없습니다. compose Task를 확인하세요.")

이런 실패를 LangSmith Trace로 남기면 어느 단계까지 실행됐고, 어떤 Task가 빠져서 예외가 발생했는지 확인할 수 있다.

실패 디버깅에서 중요한 점은 다음과 같다.

실패 결과만 보지 말고
실행 경로와 중간 결과를 같이 확인한다.

8. Validator 보완

Validator는 Workflow 결과가 요구사항을 만족하는지 판단한다.

이번에는 예산 조건 검증도 추가되었다.

if budget_options and not any(
    bool(option["within_budget"]) for option in budget_options
):
    cheapest = min(int(option["total"]) for option in budget_options)
    report = ValidationReport(
        passed=False,
        failed_conditions=[
            f"최저 예상 비용 {cheapest:,}원이 예산 {state['request'].budget:,}원을 초과합니다."
        ],
    )

단순히 Task가 실행됐는지만 보는 것이 아니라, 실제 결과가 사용자의 예산 조건을 만족하는지도 확인한다.

9. Dataset

Dataset은 평가에 사용할 입력과 기대 결과 모음이다.

EVALUATION_CASES = [
    {
        "inputs": {
            "goal": "비 오는 날 아이와 갈 송파 하루 일정을 만들어줘.",
            "weather": "rain",
            "people": 3,
            "budget": 200_000,
            "children": True,
        },
        "outputs": {"expected_pass": True},
    }
]

Dataset을 만들면 같은 테스트 케이스로 여러 버전의 Workflow를 반복 평가할 수 있다.

workflow-v1 Dataset
-> baseline Experiment
-> fixed Experiment

10. Evaluator

Evaluator는 실제 실행 결과와 기대 결과를 비교하는 함수이다.

def workflow_evaluator(outputs: dict, reference_outputs: dict) -> dict:
    ...

평가 기준은 다음과 같다.

실제 PASS/FAIL이 기대 결과와 같은가
PASS 케이스에서는 장소가 선택되었는가
FAIL 케이스에서는 기대한 실패 이유가 포함되었는가
Task 누락 때문에 우연히 실패한 것은 아닌가

결과는 점수와 코멘트로 반환한다.

return {
    "key": "workflow_requirement_match",
    "score": int(passed),
    "comment": "...",
}

Evaluator를 사용하면 단순히 실행만 해보는 것이 아니라, 결과 품질을 기준에 따라 판단할 수 있다.

11. Experiment

Experiment는 특정 버전의 Workflow를 Dataset에 대해 실행한 평가 기록이다.

client.evaluate(
    baseline_target,
    data=DATASET_NAME,
    evaluators=[workflow_evaluator],
    experiment_prefix="workflow-baseline",
)

수정 후 버전도 같은 Dataset으로 평가한다.

client.evaluate(
    fixed_target,
    data=DATASET_NAME,
    evaluators=[workflow_evaluator],
    experiment_prefix="workflow-fixed",
)

이렇게 하면 같은 입력에 대해 baseline과 fixed 결과를 비교할 수 있다.

같은 Dataset
-> baseline 실행 결과
-> fixed 실행 결과
-> 점수 비교

12. LangSmith를 쓰는 이유

AI Workflow는 일반 코드보다 디버깅이 어렵다.
LLM, Tool, Graph, Validator가 함께 동작하기 때문에 어디서 문제가 생겼는지 확인하기 어렵다.

LangSmith를 사용하면 다음을 확인할 수 있다.

어떤 입력이 들어왔는지
어떤 Plan이 만들어졌는지
어떤 Task가 실행되었는지
각 Task의 결과가 무엇인지
어느 단계에서 예외가 발생했는지
수정 전후 품질이 좋아졌는지

즉, LangSmith는 AI 기능의 로그, 디버깅, 평가를 위한 관찰 도구라고 이해할 수 있다.

13. 핵심 정리

LangSmith는 LangChain, LangGraph 실행 흐름을 추적하고 평가하는 도구이다.
Trace는 함수나 Workflow의 입력, 출력, 에러를 기록한다.
@traceable을 사용하면 특정 함수를 LangSmith 추적 대상으로 만들 수 있다.
run_type="tool"은 개별 Task 실행 추적에 사용했다.
run_type="chain"은 전체 Workflow 실행 추적에 사용했다.
환경 변수로 LANGSMITH_API_KEY, LANGSMITH_TRACING, LANGSMITH_PROJECT가 필요하다.
API Key는 로그에 그대로 출력하지 않고 마스킹해야 한다.
baseline과 fixed 버전을 나누면 수정 전후 결과를 비교할 수 있다.
실패 Trace를 보면 어떤 Task가 누락되었거나 어느 단계에서 예외가 발생했는지 확인할 수 있다.
Dataset은 평가에 사용할 입력과 기대 결과 모음이다.
Evaluator는 실제 결과가 기대 조건을 만족하는지 점수화한다.
Experiment는 Dataset을 대상으로 특정 버전을 실행한 평가 기록이다.
같은 Dataset으로 baseline과 fixed를 평가하면 개선 여부를 비교할 수 있다.
AI Workflow는 실행 결과뿐 아니라 중간 과정까지 관찰해야 디버깅할 수 있다.

[TIL]Agent Safety와 Plan-Execute-Replan Workflow

namerong — Thu, 30 Jul 2026 15:02:55 +0900

1. 학습 주제

Agent가 Tool을 사용할 때 필요한 안전 제어와, 복잡한 작업을 계획 -> 실행 -> 검증 -> 재계획 흐름으로 처리하는 Workflow 구조를 학습했다.

핵심 내용은 다음과 같다.

Agent Memory 보완
thread_id 기반 대화 기억 분리
Agent Safety
재시도, Fallback, Handoff 처리
Graph의 종료 조건과 recursion_limit
Planner
Executor
Validator
Replanner
Pydantic 기반 실행 계약 정의

2. Agent Memory 보완

Agent Memory는 이전 대화를 기억해 다음 요청에서 활용하는 구조이다.
이번 실습에서는 Checkpointer를 사용해 같은 thread_id의 대화 메시지를 이어가도록 구성했다.

checkpointer=InMemorySaver()

대화는 thread_id를 기준으로 분리된다.

config = {
    "configurable": {
        "thread_id": "student-1"
    }
}

같은 thread에서는 이전에 말한 이름, 동행인, 예산을 기억해 다음 Tool 호출 인자로 사용할 수 있다.

1. 내 이름은 수진이고 아이와 여행해. 전체 예산은 20만원이야.
2. 내 조건에 맞는 장소를 추천해줘.

두 번째 질문에는 이름, 동행인, 예산이 직접 들어있지 않지만, 같은 thread에 이전 대화가 저장되어 있다면 Agent가 그 정보를 찾아 Tool 인자를 만들 수 있다.

3. thread_id가 중요한 이유

Agent Memory에서 중요한 점은 사용자별 기억이 섞이면 안 된다는 것이다.

student-1
-> 수진, 아이 동반, 예산 정보 있음

student-2
-> 이전 정보 없음

student-1에서 장소 추천을 요청하면 이전 정보를 활용할 수 있다.
하지만 student-2에서 같은 질문을 하면 정보가 없으므로 Tool을 호출하지 않고 추가 질문을 해야 한다.

즉, thread_id는 “이 대화가 누구의 흐름인지” 구분하는 기준이다.

4. Agent Safety

Agent는 Tool을 사용할 수 있지만, 모든 판단을 모델에게만 맡기면 위험할 수 있다.
그래서 실패 결과에 따라 재시도할지, 중단할지, 담당자에게 넘길지 결정하는 안전 제어가 필요하다.

이번 실습에서는 Tool 결과를 다음 상태로 나누었다.

ResultCode	의미	처리
FOUND	검색 성공	성공 종료
NOT_FOUND	결과 없음	제한 횟수 안에서 재시도
TIMEOUT	일시적 실패	제한 횟수 안에서 재시도
AUTH_ERROR	권한 문제	재시도 없이 Handoff
NOT_RUN	아직 실행 안 함	초기 상태

5. Retry, Fallback, Handoff

실패라고 해서 모두 같은 방식으로 처리하면 안 된다.

NOT_FOUND / TIMEOUT
-> 다시 시도 가능

AUTH_ERROR
-> 다시 시도해도 해결되지 않음
-> 담당자 확인 필요

처리 흐름은 다음과 같다.

검색 실행
-> 결과 확인
-> FOUND면 성공 종료
-> NOT_FOUND 또는 TIMEOUT이면 재시도
-> 최대 횟수 초과 시 Fallback
-> AUTH_ERROR면 Handoff

Fallback은 자동 처리를 더 이상 하지 않고 사용자에게 조건 변경을 요청하는 흐름이다.

조건에 맞는 장소를 찾지 못했습니다.
실내, 무료, 산책 중 하나로 조건을 변경해 주세요.

Handoff는 자동 처리로 해결할 수 없는 상황을 담당자 확인으로 넘기는 흐름이다.

인증 문제로 자동 검색을 계속할 수 없습니다.
담당자 확인이 필요합니다.

6. 안전 규칙은 모델이 아니라 Graph가 강제

중요한 점은 재시도 여부와 최대 횟수를 모델의 판단에만 맡기지 않는다는 것이다.
모델은 답변을 만들고 Tool을 고를 수 있지만, 반복 제어와 종료 조건은 Graph State와 Edge에서 강제한다.

def route_after_guard(state):
    if result == "AUTH_ERROR":
        return "finalize_handoff"
    if result == "FOUND":
        return "agent"
    if result in RETRYABLE_RESULTS and state["attempts"] < state["max_attempts"]:
        return "agent"
    return "finalize_fallback"

즉, Agent가 계속 Tool을 호출하려 해도 Graph의 안전 규칙이 막을 수 있다.

7. recursion_limit

Graph에서 종료 조건을 잘못 만들면 무한 반복이 생길 수 있다.

search_destination
-> search_destination
-> search_destination
-> ...

이런 경우 recursion_limit가 마지막 안전장치 역할을 한다.

graph.invoke(state, config={"recursion_limit": 5})

하지만 recursion_limit는 최후의 방어선일 뿐이다.
정상적인 Graph라면 업무 조건으로 먼저 END에 도달해야 한다.

8. Plan-Execute-Replan Workflow

복잡한 작업은 한 번에 처리하기보다 단계별로 나누는 것이 좋다.

이번 실습에서는 여행 일정 생성을 다음 흐름으로 구성했다.

Planner
-> Executor
-> Validator
-> Replanner

각 단계의 역할은 다음과 같다.

단계	역할
Planner	목표를 실행 가능한 Task 목록으로 분해
Executor	Plan에 적힌 Task를 순서대로 실행
Validator	실행 결과가 완료 기준을 만족하는지 검증
Replanner	실패 원인을 보고 재시도할지 중단할지 판단

9. Plan

Plan은 Planner와 Executor가 공유하는 실행 계약이다.

class Plan(BaseModel):
    goal: str
    tasks: list[TaskName]
    success_criteria: list[str]

Task는 정해진 값만 사용할 수 있다.

TaskName = Literal[
    "requirements",
    "weather",
    "destination",
    "budget",
    "compose",
]

각 Task의 의미는 다음과 같다.

Task	역할
requirements	인원, 날씨, 아이 동반, 예산 조건 확인
weather	날씨를 실내외 장소 선택 정책으로 변환
destination	조건에 맞는 장소 후보 검색
budget	후보별 예상 비용 계산
compose	조사와 계산 결과로 일정 초안 작성

Plan에는 같은 Task가 중복되면 안 된다.

if len(tasks) != len(set(tasks)):
    raise ValueError("Plan에는 같은 Task를 중복할 수 없습니다.")

이렇게 하면 불필요한 반복 실행을 막을 수 있다.

10. Planner

Planner는 사용자의 목표를 보고 필요한 Task를 선택한다.

예를 들어 목표가 다음과 같다면:

아이와 비 오는 날 20만원 이내의 송파 하루 일정을 만들어줘.

필요한 Task는 다음처럼 구성될 수 있다.

requirements
-> weather
-> destination
-> budget
-> compose

반면 “예상 비용만 계산해줘” 같은 요청이라면 모든 Task가 필요하지 않을 수 있다.

즉, Planner는 목표를 작은 실행 단계로 분해하는 역할이다.

11. Executor

Executor는 Plan에 들어 있는 Task를 순서대로 실행한다.

for task in plan.tasks:
    TASK_HANDLERS[task](request, context)
    path.append(task)

TASK_HANDLERS는 Task 이름과 실제 실행 함수를 연결한다.

TASK_HANDLERS = {
    "requirements": execute_requirements,
    "weather": execute_weather,
    "destination": execute_destination,
    "budget": execute_budget,
    "compose": execute_compose,
}

Executor는 실행 중간 결과를 context에 저장한다.

requirements 결과
weather 결과
destinations 결과
budget_options 결과
draft 결과

12. Context

context는 Workflow 안에서 Task들이 공유하는 중간 결과 저장소이다.

예를 들어 destination Task는 장소 후보를 저장한다.

context["destinations"] = search_destinations(request)

budget Task는 앞에서 저장된 장소 후보를 읽어 비용을 계산한다.

places = context.get("destinations", [])
context["budget_options"] = calculate_budget_options(request, places)

즉, Task들은 독립적으로 실행되는 것이 아니라 이전 Task가 만든 context를 읽고 다음 결과를 만든다.

13. Validator

Validator는 실행 결과가 목표 조건을 만족하는지 확인한다.

검증 기준은 다음과 같다.

필요한 Task 결과가 context에 존재하는가
비 오는 날이면 실내 장소인가
아이 동반이면 아이 친화 장소인가
예상 비용이 예산을 넘지 않는가
일정 초안이 실제로 선택되었는가

if request.weather == "rain" and not draft.indoor:
    failures.append("비 오는 날에는 실내 장소가 필요합니다.")

검증 결과는 ValidationReport로 관리한다.

class ValidationReport(BaseModel):
    passed: bool
    failed_conditions: list[str]

성공하면 Workflow는 종료하고, 실패하면 Replanner로 넘어간다.

14. Replanner

Replanner는 검증 실패 원인을 보고 다시 실행할지 중단할지 판단한다.

class ReplanDecision(BaseModel):
    action: Literal["retry", "stop"]
    reason: str
    plan: Plan | None = None

중요한 규칙은 retry를 선택했다면 수정된 Plan이 반드시 있어야 한다는 점이다.

if self.action == "retry" and self.plan is None:
    raise ValueError("retry에는 수정 Plan이 필요합니다.")

실패가 누락된 Task 때문에 발생했다면 Plan을 수정해 다시 실행할 수 있다.
하지만 예산이 너무 낮아서 어떤 장소도 조건을 만족하지 못한다면 Plan을 바꿔도 해결되지 않을 수 있다. 이 경우 stop이 더 적절하다.

15. 전체 Workflow 흐름

전체 Graph 흐름은 다음과 같다.

START
-> planner
-> executor
-> validator
-> 검증 성공이면 END
-> 검증 실패이고 재시도 가능하면 replanner
-> retry면 executor
-> stop이면 END

이 구조의 장점은 문제 발생 지점을 분리해서 확인할 수 있다는 점이다.

Plan이 이상한가?
Task 실행 결과가 빠졌는가?
Draft가 조건을 만족하지 못했는가?
재계획으로 해결 가능한 문제인가?

16. Agent Safety와 Workflow의 차이

Agent Safety는 Tool 실행 중 실패를 안전하게 제어하는 데 집중한다.

Tool 실패
-> 재시도 가능 여부 판단
-> Fallback 또는 Handoff

Plan-Execute-Replan Workflow는 복잡한 목표를 단계별 작업으로 나누고, 결과를 검증한 뒤 필요하면 계획을 수정하는 데 집중한다.

목표
-> 계획
-> 실행
-> 검증
-> 재계획

정리하면 다음과 같다.

구분	목적
Agent Safety	Tool 실행 실패를 안전하게 제어
Workflow	복잡한 작업을 계획, 실행, 검증, 재계획으로 처리

17. 핵심 정리

Agent Memory는 같은 thread_id의 대화 메시지를 이어준다.
다른 thread_id끼리는 기억이 섞이면 안 된다.
Agent가 이전 대화를 바탕으로 Tool 인자를 만들 수 있다.
사용자가 정보를 수정하면 가장 최근 값을 기준으로 판단해야 한다.
Agent Safety는 실패 종류에 따라 재시도, Fallback, Handoff를 결정한다.
NOT_FOUND, TIMEOUT은 재시도 가능한 실패로 볼 수 있다.
AUTH_ERROR는 재시도하지 않고 Handoff하는 것이 적절하다.
재시도 횟수는 max_attempts로 제한해야 한다.
Graph의 반복은 반드시 종료 조건을 가져야 한다.
recursion_limit는 무한 반복을 막는 최후의 안전장치이다.
Planner는 목표를 실행 가능한 Task 목록으로 분해한다.
Executor는 Plan의 Task를 순서대로 실행한다.
Context는 Task 사이의 중간 결과를 저장한다.
Validator는 실행 결과가 조건을 만족하는지 검증한다.
Replanner는 실패 원인을 보고 retry 또는 stop을 결정한다.
Pydantic 모델을 사용하면 Planner, Executor, Validator 사이의 데이터 계약을 명확히 만들 수 있다.
복잡한 Agentic 작업은 “모델의 판단”과 “코드가 강제하는 규칙”을 분리해야 더 안전하게 운영할 수 있다.

[TIL]Agentic AI, Tool Calling, ReAct, Agent Memory

namerong — Wed, 29 Jul 2026 17:01:16 +0900

1. 학습 주제

Agentic AI의 기본 구조를 학습했다.
이전까지는 RAG, VectorStore, LangGraph처럼 정해진 흐름을 구성하는 데 집중했다면, 이번에는 모델이 상황에 따라 Tool을 선택하고 실행 결과를 보고 다음 행동을 결정하는 구조를 다뤘다.

핵심 내용은 다음과 같다.

Workflow와 Agent 차이
Tool Contract와 Schema
LangChain create_agent
Tool Calling 메시지 흐름
ReAct 구조
Action, Observation, Final Answer
Checkpointer 기반 Agent Memory
thread_id를 통한 대화 기억 분리

2. Workflow와 Agent 차이

Workflow는 개발자가 실행 순서를 미리 정해두는 방식이다.

질문 분석
-> 장소 검색이 필요하면 search_destination 실행
-> 예산 계산이 필요하면 estimate_day_budget 실행
-> 답변 작성

즉, 어떤 Tool을 언제 실행할지 개발자가 if문으로 결정한다.

if needs_destination:
    search_destination.invoke(...)

if needs_budget:
    estimate_day_budget.invoke(...)

반면 Agent는 모델이 질문과 Tool 설명을 보고 실행 중에 어떤 Tool을 사용할지 결정한다.

사용자 질문
-> 모델이 Tool Schema 확인
-> 필요한 Tool 선택
-> Tool 실행
-> 실행 결과를 보고 최종 답변

정리하면 다음과 같다.

구분결정 주체특징

Workflow	개발자	흐름이 명확하고 예측 가능
Agent	모델	질문에 따라 실행 중 Tool 선택

단순하고 고정된 흐름이면 Workflow가 더 안전하고 충분하다.
하지만 질문이 다양하고 어떤 Tool이 필요할지 매번 달라진다면 Agent 구조가 유용하다.

3. Tool Contract

Agent가 Tool을 사용하려면 단순 Python 함수만 있어서는 부족하다.
모델은 함수 내부 코드를 직접 이해하는 것이 아니라, Tool의 이름, 설명, 입력 Schema를 보고 사용 방법을 판단한다.

@tool(args_schema=BudgetInput)
def estimate_day_budget(
    travelers: int,
    ticket_price: int,
    meal_budget: int
) -> int:
    return travelers * (ticket_price + meal_budget)

Tool Contract의 핵심은 다음과 같다.

요소의미

Tool 이름	모델이 호출할 기능 이름
Tool 설명	언제 이 도구를 써야 하는지 알려주는 설명
입력 Schema	어떤 인자를 어떤 타입으로 받아야 하는지 정의

예를 들어 예산 계산 Tool은 다음 입력을 요구한다.

class BudgetInput(BaseModel):
    travelers: int
    ticket_price: int
    meal_budget: int

이 Schema가 있으면 모델이 Tool을 호출할 때 필요한 인자 구조를 맞출 수 있다.

4. Schema 검증과 업무 규칙 검증

Tool에는 두 종류의 검증이 필요하다.

첫 번째는 Schema 검증이다.
필수 필드가 빠졌거나 타입이 맞지 않으면 함수 실행 전에 막는다.

travelers 필수
ticket_price 필수
meal_budget 필수

두 번째는 업무 규칙 검증이다.
타입은 맞지만 값이 업무적으로 말이 안 되는 경우 함수 내부에서 확인한다.

if travelers < 1:
    raise ValueError("여행 인원은 1명 이상이어야 합니다.")

정리하면 다음과 같다.

구분처리 위치예시

Schema 검증	함수 실행 전	필수값 누락, 타입 오류
업무 규칙 검증	함수 내부	인원 0명, 음수 금액

검색 결과 없음은 입력 오류가 아니라 정상 실행 결과로 볼 수 있다.

검색 결과 없음

이 경우는 예외라기보다 “검색은 했지만 조건에 맞는 데이터가 없음”으로 처리한다.

5. create_agent

create_agent는 모델과 Tool을 연결해 Agent를 만드는 함수이다.

agent = create_agent(
    model=model,
    tools=[estimate_day_budget, search_destination],
    system_prompt="너는 여행 도우미다. 필요한 경우에만 Tool을 사용한다."
)

Agent는 사용자 질문을 보고 다음을 판단한다.

Tool이 필요한가?
어떤 Tool이 필요한가?
Tool 인자는 무엇인가?
Tool 결과를 어떻게 최종 답변에 반영할 것인가?

예를 들어 질문이 다음과 같다면:

3명이 입장료 35000원, 식비 20000원씩 쓰면 얼마야?

Agent는 estimate_day_budget Tool을 선택하고 다음 인자를 만들 수 있다.

{
  "travelers": 3,
  "ticket_price": 35000,
  "meal_budget": 20000
}

6. Tool Calling 메시지 흐름

Agent 실행 결과는 단순 문자열 하나가 아니라 여러 메시지 흐름으로 구성된다.

HumanMessage
-> AIMessage with tool_calls
-> ToolMessage
-> AIMessage final answer

각 메시지의 의미는 다음과 같다.

메시지의미

HumanMessage	사용자 질문
AIMessage with tool_calls	모델이 Tool 실행을 요청한 메시지
ToolMessage	Tool 실행 결과
AIMessage final	Tool 결과를 반영한 최종 답변

즉, Agent는 바로 답변하지 않고 중간에 Tool을 호출할 수 있다.

질문
-> Action: Tool 호출
-> Observation: Tool 결과
-> Final Answer: 최종 답변

7. ReAct 구조

ReAct는 Reasoning + Acting의 흐름을 가진 Agent 패턴이다.

실행 흐름은 다음과 같다.

Action 1
-> Observation 1
-> Action 2
-> Observation 2
-> Final Answer

예를 들어 장소 검색에서 처음에는 strict 모드로 정확히 검색한다.

Action 1: strict 검색
Observation 1: NOT_FOUND

검색 결과가 없으면 Tool 결과의 retry_hint를 보고 broad 모드로 다시 검색한다.

Action 2: broad 검색
Observation 2: FOUND

그리고 성공한 결과를 근거로 최종 답변한다.

Final Answer

ReAct의 핵심은 Tool 결과를 보고 다음 행동을 바꿀 수 있다는 점이다.
단순히 한 번 Tool을 호출하고 끝나는 구조보다 더 유연하다.

8. ToolNode와 tools_condition

LangGraph에서는 Agent와 Tool 실행을 Graph로 구성할 수 있다.

builder.add_node("agent", call_model)
builder.add_node("tools", ToolNode(tools))
builder.add_conditional_edges("agent", tools_condition)
builder.add_edge("tools", "agent")

흐름은 다음과 같다.

START
-> agent
-> tool_calls가 있으면 tools
-> Tool 실행 후 다시 agent
-> tool_calls가 없으면 END

tools_condition은 마지막 AIMessage에 Tool 호출이 있는지 확인한다.

Tool 호출이 있으면 tools 노드로 이동
Tool 호출이 없으면 종료

즉, Agent가 더 이상 Tool이 필요 없다고 판단할 때까지 agent -> tools -> agent 흐름을 반복할 수 있다.

9. 정보 부족 시 Tool 호출하지 않기

Agent가 항상 Tool을 호출하면 안 된다.
예산 계산에는 최소한 인원, 입장료, 식비가 필요하다.

3명 여행 예산을 계산해줘

이 질문에는 인원은 있지만 입장료와 식비가 없다.
이때 모델이 값을 추측해서 Tool을 호출하면 잘못된 결과가 나온다.

올바른 흐름은 다음과 같다.

정보 부족 확인
-> Tool 호출하지 않음
-> 사용자에게 필요한 값 질문

Agent를 만들 때 system prompt에 이런 규칙을 명확히 넣어야 한다.

인원, 입장료, 식비 중 하나라도 없으면 값을 추측하지 말고 사용자에게 질문한다.

10. Agent Memory

Agent Memory는 이전 대화를 기억해 다음 Tool 호출에 활용하는 구조이다.

이번 실습에서는 InMemorySaver를 checkpointer로 사용했다.

create_agent(
    model=ChatOpenAI(...),
    tools=[recommend_destination],
    checkpointer=InMemorySaver(),
)

그리고 thread_id로 대화 세션을 구분했다.

config = {
    "configurable": {
        "thread_id": "student-1"
    }
}

같은 thread_id로 대화를 이어가면 이전 메시지가 checkpoint에 저장되어 다음 요청에서 다시 사용된다.

1. 내 이름은 수진이고 아이와 여행해. 전체 예산은 20만원이야.
2. 내 조건에 맞는 장소를 추천해줘.

두 번째 질문에는 이름, 동행인, 예산이 직접 들어있지 않다.
하지만 같은 thread에 이전 대화가 저장되어 있으면 Agent가 그 정보를 찾아 Tool 인자로 만들 수 있다.

11. thread_id로 기억 분리

Memory에서 중요한 점은 사용자별 또는 세션별 기억이 섞이면 안 된다는 것이다.

student-1 thread
-> 수진, 아이, 예산 20만원

student-2 thread
-> 이전 정보 없음

student-1에서 장소 추천을 요청하면 이전 정보를 사용할 수 있다.
하지만 student-2에서 같은 질문을 하면 이전 정보가 없으므로 Tool을 호출하지 않고 추가 질문을 해야 한다.

즉, thread_id는 대화 기억을 분리하는 기준이다.

12. 수정된 정보는 최신 값 사용

사용자가 이전 정보를 바꿀 수도 있다.

전체 예산을 15만원으로 변경해줘

이후 추천을 요청하면 Agent는 예전 예산 20만원이 아니라 최신 예산 15만원을 사용해야 한다.

이전 값: 20만원
수정 값: 15만원
Tool 인자: max_budget = 150000

Agent Memory는 단순히 과거를 저장하는 것뿐만 아니라, 대화 안에서 가장 최근 정보를 기준으로 판단해야 한다.

13. 핵심 정리

Workflow는 개발자가 실행 순서를 정하는 구조이다.
Agent는 모델이 질문과 Tool Schema를 보고 필요한 Tool을 선택하는 구조이다.
Tool Contract는 Tool 이름, 설명, 입력 Schema로 구성된다.
일반 함수와 달리 LangChain Tool은 모델에게 사용 방법을 설명할 수 있다.
Schema 검증은 함수 실행 전 입력 구조를 확인한다.
업무 규칙 검증은 함수 내부에서 값의 의미를 확인한다.
create_agent는 모델과 Tool을 연결해 Agent를 만든다.
Tool Calling은 AIMessage -> ToolMessage -> Final Answer 흐름으로 진행된다.
ReAct는 Action과 Observation을 반복하며 다음 행동을 조정하는 구조이다.
Tool 결과가 NOT_FOUND이면 Agent는 다른 방식으로 재검색할 수 있다.
정보가 부족하면 Tool을 호출하지 않고 사용자에게 추가 질문해야 한다.
LangGraph의 ToolNode는 실제 Tool 실행을 담당한다.
tools_condition은 Tool 호출 여부에 따라 다음 노드를 결정한다.
Checkpointer는 같은 thread_id의 대화 메시지를 이어준다.
Agent Memory는 이전 대화를 바탕으로 Tool 인자를 생성할 수 있다.
다른 thread_id끼리는 기억이 섞이면 안 된다.
사용자가 정보를 수정하면 Agent는 가장 최근 값을 기준으로 판단해야 한다.

[TIL]FastAPI 파일 브릿지와 LangGraph 기초

namerong — Tue, 28 Jul 2026 15:47:50 +0900

1. 학습 주제

FastAPI와 Spring을 HTTP로 연결해 파일 업로드를 처리하는 구조와, LangGraph를 사용해 AI 작업 흐름을 Graph 형태로 구성하는 방법을 학습했다.

핵심 내용은 다음과 같다.

FastAPI 파일 업로드 API 구현
Spring에서 MultipartFile을 받아 FastAPI로 전달
RestClient를 사용한 서버 간 HTTP 통신
LangChain Chain과 LangGraph Graph 차이
LangGraph의 State, Node, Edge
Reducer를 사용한 State 병합
조건 분기 라우팅
RAG 흐름을 Graph로 구성
질문 의도에 따라 RAG 또는 일반 답변으로 분기

2. FastAPI 파일 업로드 API

FastAPI에서는 파일과 일반 값을 함께 받기 위해 multipart/form-data 형식을 사용한다.

@app.post("/api/v1/files", response_model=FileInfo, status_code=201)
async def upload_file(
    file: Annotated[UploadFile, File()],
    description: Annotated[str, Form(min_length=1, max_length=100)]
):

여기서 역할은 다음과 같다.

코드	의미
UploadFile	업로드된 파일 객체
File()	multipart 요청의 파일 part
Form()	multipart 요청의 일반 입력값
description	파일 설명

즉, 하나의 요청 안에 파일과 설명을 함께 담아 보낼 수 있다.

3. 파일 검증 흐름

파일 업로드에서는 아무 파일이나 저장하면 안 된다.
그래서 다음 조건을 검증했다.

허용된 Content-Type인지 확인
확장자와 Content-Type이 일치하는지 확인
파일 크기가 1MB 이하인지 확인
원본 파일명에서 경로 정보 제거
저장 파일명은 UUID로 생성

ALLOWED_TYPES = {
    "text/plain": ".txt",
    "application/pdf": ".pdf"
}

content = await file.read(MAX_FILE_SIZE + 1)

if len(content) > MAX_FILE_SIZE:
    raise HTTPException(status_code=413, detail="파일은 1MB 이하여야 합니다.")

파일명은 사용자가 보낸 이름을 그대로 쓰지 않고 UUID를 사용했다.

file_id = str(uuid4())
stored_name = f"{file_id}{suffix}"

이렇게 하면 파일명 충돌을 줄이고, 사용자가 보낸 파일명에 의존하지 않는 저장 구조를 만들 수 있다.

4. 파일 Metadata 저장

파일 자체는 .txt 또는 .pdf로 저장하고, 파일 정보는 별도의 .json 파일로 저장했다.

metadata_path(file_id).write_text(
    json.dumps(info.model_dump(), ensure_ascii=False, indent=2),
    encoding="utf-8"
)

저장되는 정보는 다음과 같다.

필드	의미
id	파일 고유 ID
original_name	사용자가 업로드한 원본 파일명
content_type	파일 MIME 타입
size	파일 크기
description	파일 설명
stored_name	서버에 저장된 파일명

파일과 metadata를 분리하면 나중에 목록 조회, 다운로드, 삭제 기능을 만들 때 관리하기 쉽다.

5. Spring과 FastAPI 파일 브릿지

Spring 서버는 클라이언트로부터 파일을 받고, 그 파일을 다시 FastAPI 서버로 전달한다.

흐름은 다음과 같다.

브라우저
-> Spring Controller
-> Spring RestClient
-> FastAPI 파일 업로드 API
-> FastAPI 저장
-> Spring 응답 반환

중요한 점은 Spring이 Python 함수를 직접 실행하는 것이 아니라, FastAPI 서버에 HTTP 요청을 보낸다는 것이다.

Spring Controller에서는 파일을 다음처럼 받는다.

@PostMapping(consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public ResponseEntity<?> upload(
        @RequestPart("file") MultipartFile file,
        @RequestParam("description") String description
)

그리고 FastApiFileClient에서 FastAPI로 다시 multipart 요청을 만든다.

MultiValueMap<String, Object> body = new LinkedMultiValueMap<>();
body.add("file", new HttpEntity<>(resource, fileHeaders));
body.add("description", description);

6. RestClient와 Multipart 전달

Spring에서 외부 API를 호출할 때 RestClient를 사용했다.

return restClient.post()
        .uri("/api/v1/files")
        .contentType(MediaType.MULTIPART_FORM_DATA)
        .body(body)
        .retrieve()
        .body(FileInfo.class);

MultipartFile은 그대로 외부 API에 넣을 수 없기 때문에 ByteArrayResource로 감싸서 전달했다.

ByteArrayResource resource = new ByteArrayResource(file.getBytes()) {
    @Override
    public String getFilename() {
        return file.getOriginalFilename();
    }
};

여기서 getFilename()을 오버라이드하는 이유는 FastAPI 쪽에서 원본 파일명을 인식할 수 있게 하기 위해서다.

7. 외부 API 예외 처리

FastAPI에서 파일 형식이 잘못되었거나 서버 연결이 실패할 수 있다.
Spring에서는 이 경우를 나누어 처리했다.

catch(RestClientResponseException e) {
    return ResponseEntity.status(e.getStatusCode())
            .body(Map.of(
                    "code", "FASTAPI_REJECTED",
                    "message", e.getResponseBodyAsString()
            ));
}

catch(IOException | RestClientException e) {
    return ResponseEntity.status(HttpStatus.BAD_GATEWAY)
            .body(Map.of(
                    "code", "UPLOAD_FAILED",
                    "message", "파일 전달에 실패했습니다."
            ));
}

정리하면 다음과 같다.

상황	응답
FastAPI가 파일을 거절	FastAPI의 상태 코드 전달
파일 읽기 실패 또는 통신 실패	502 Bad Gateway
FastAPI 서버 연결 불가	503 Service Unavailable

외부 서버와 연동할 때는 성공 흐름뿐 아니라 실패 흐름도 반드시 고려해야 한다.

8. LangChain Chain과 LangGraph Graph 차이

LangChain Chain은 작업 순서가 고정된 파이프라인에 적합하다.

retrieve -> generate

예를 들어 항상 검색 후 답변 생성만 한다면 Chain으로 충분하다.

하지만 질문에 따라 실행 경로가 달라지거나, 중간 상태를 여러 노드가 공유하거나, 분기와 반복이 필요하면 LangGraph가 더 적합하다.

START
-> classify
-> 조건에 따라 budget / destination / general
-> END

정리하면 다음과 같다.

구분	적합한 상황
Chain	순서가 고정된 단순 흐름
Graph	분기, 반복, 조건 처리, 상태 공유가 필요한 흐름

9. LangGraph의 State, Node, Edge

LangGraph는 작업 흐름을 State, Node, Edge로 구성한다.

개념	의미
State	여러 Node가 공유하는 데이터
Node	실제 작업을 수행하는 함수
Edge	Node 사이의 실행 순서
START	그래프 시작 지점
END	그래프 종료 지점

예시는 다음과 같다.

class TripState(TypedDict):
    place: str
    travelers: int
    ticket_price: int
    total_price: int
    message: str
    path: list[str]

Node는 State 전체를 반환하지 않아도 된다.
자신이 변경할 값만 dict로 반환하면 LangGraph가 기존 State에 합쳐준다.

def calculate_total(state: TripState) -> dict:
    total = state["travelers"] * state["ticket_price"]
    return {"total_price": total}

10. Reducer

기본적으로 같은 State 필드를 여러 번 업데이트하면 새 값으로 덮어써질 수 있다.
하지만 리스트처럼 계속 누적해야 하는 값은 덮어쓰기보다 합치기가 필요하다.

이때 사용하는 것이 Reducer이다.

class ResearchState(TypedDict):
    topic: str
    notes: Annotated[list[str], operator.add]

operator.add를 사용하면 여러 Node가 반환한 notes가 덮어써지지 않고 이어 붙는다.

destination note
+ budget note
+ meal note
+ transport note
= 최종 notes

Reducer는 여러 Node가 같은 State 필드를 업데이트할 때 “어떻게 합칠지” 정하는 규칙이다.

11. Conditional Routing

모든 질문에 같은 작업을 실행할 필요는 없다.
예산 질문이면 예산 노드로, 장소 질문이면 장소 노드로, 일반 질문이면 일반 노드로 보내는 것이 더 효율적이다.

먼저 질문을 분류하는 Router Node를 만든다.

def classify(state: RouteState) -> dict:
    if "입장료" in state["question"]:
        route = "budget"
    elif "장소" in state["question"]:
        route = "destination"
    else:
        route = "general"
    return {"route": route}

그리고 add_conditional_edges로 다음 노드를 선택한다.

builder.add_conditional_edges("classify", choose_route)

흐름은 다음과 같다.

START
-> classify
-> budget 또는 destination 또는 general
-> END

조건 분기를 사용하면 질문 의도에 맞는 작업만 실행할 수 있다.

12. RAG Graph

RAG도 LangGraph로 구성할 수 있다.

START
-> retrieve
-> generate
-> END

각 Node의 역할은 다음과 같다.

Node	역할
retrieve	VectorStore에서 질문과 관련 있는 문서 검색
generate	검색된 context를 근거로 LLM 답변 생성

def retrieve(state: RagState) -> dict:
    documents = store.similarity_search(state["question"], k=2)
    return {
        "context": [document.page_content for document in documents],
        "path": ["retrieve"]
    }

def generate(state: RagState) -> dict:
    prompt = (
        "아래 문서만 근거로 답하세요.\n"
        f"[문서]\n{context}\n[질문]\n{state['question']}"
    )
    answer = model.invoke(prompt).content
    return {"answer": answer}

이 구조의 장점은 RAG가 틀렸을 때 어느 단계가 문제인지 확인하기 쉽다는 점이다.

검색된 context가 이상함 -> Retrieval 문제
context는 맞는데 답변이 이상함 -> Generation 문제

13. Question Router

질문에 따라 RAG를 사용할지 일반 답변을 사용할지 나누는 구조도 학습했다.

START
-> classify
-> RAG 질문이면 retrieve -> rag_answer
-> 일반 질문이면 general
-> END

예를 들어 다음 질문은 RAG가 필요하다.

아쿠아리움 입장료는 얼마야?
무료 산책 장소는 어디야?

이 질문들은 수업용 문서에 있는 정보를 근거로 답해야 하므로 retrieve를 거친다.

반면 다음 질문은 일반 답변으로 처리할 수 있다.

여행 가방을 가볍게 싸는 방법은?
아이 여행 준비물은 무엇이야?

이런 질문은 특정 문서 검색이 꼭 필요하지 않으므로 general 노드로 보낸다.

이렇게 하면 불필요한 Embedding 검색 비용을 줄이고, 질문 성격에 맞는 처리 흐름을 만들 수 있다.

14. 핵심 정리

FastAPI는 UploadFile, File, Form으로 파일과 일반 값을 함께 받을 수 있다.
파일 업로드 요청은 multipart/form-data 형식을 사용한다.
파일 저장 전 Content-Type, 확장자, 크기 검증이 필요하다.
저장 파일명은 UUID를 사용하면 충돌을 줄일 수 있다.
Spring은 RestClient로 FastAPI API를 호출할 수 있다.
Spring이 Python 함수를 직접 실행하는 것이 아니라 HTTP 요청으로 FastAPI와 통신한다.
MultipartFile을 외부 API로 전달할 때는 ByteArrayResource와 MultiValueMap을 사용할 수 있다.
외부 API 연동에서는 RestClientResponseException, RestClientException 등 실패 상황을 나누어 처리해야 한다.
LangChain Chain은 고정된 순서의 작업에 적합하다.
LangGraph는 분기, 반복, 상태 공유가 필요한 작업 흐름에 적합하다.
State는 그래프 전체에서 공유되는 데이터이다.
Node는 State를 읽고 일부 값을 업데이트하는 작업 단위이다.
Edge는 Node 사이의 실행 순서를 정의한다.
Reducer는 같은 State 필드를 여러 Node가 업데이트할 때 병합 방식을 정한다.
Conditional Routing은 질문 의도에 따라 다음 실행 노드를 선택하는 방식이다.
RAG Graph는 검색 단계와 답변 생성 단계를 분리해 디버깅하기 쉽다.
Question Router를 사용하면 RAG가 필요한 질문과 일반 질문을 나누어 처리할 수 있다.

[TIL]FastAPI REST API, Router 분리, File Upload, Spring 연동

namerong — Mon, 27 Jul 2026 16:09:52 +0900

1. 학습 주제

FastAPI로 REST API를 구성하고, 기능별 Router 분리, 파일 입출력, 파일 업로드, Spring 서버와 FastAPI 서버를 HTTP로 연결하는 흐름을 학습했다.

핵심 내용은 다음과 같다.

REST CRUD API 구현
GET, PUT, PATCH 차이 이해
APIRouter로 기능별 API 분리
Pydantic Schema 재사용
Python Path를 활용한 파일 입출력
multipart/form-data 기반 파일 업로드
파일 확장자, Content-Type, 용량 검증
Spring RestClient로 FastAPI 호출
Spring 서버가 FastAPI 서버를 중간에서 연결하는 구조

2. REST CRUD API

REST API는 URL과 HTTP Method를 조합해서 자원을 다루는 방식이다.

이번 실습에서는 Task 자원을 기준으로 목록 조회, 단건 조회, 전체 수정, 부분 수정을 구현했다.

GET /api/v1/tasks
GET /api/v1/tasks/{task_id}
PUT /api/v1/tasks/{task_id}
PATCH /api/v1/tasks/{task_id}

각 Method의 역할은 다음과 같다.

Method	역할
GET	데이터 조회
POST	새 데이터 생성
PUT	기존 데이터를 전체 교체
PATCH	기존 데이터 일부 수정
DELETE	데이터 삭제

3. GET 목록 조회와 필터링

목록 조회에서는 Query Parameter를 사용해 조건 검색을 구현했다.

def list_tasks(
    completed: bool | None = None,
    priority: Literal["low", "normal", "high"] | None = None,
    keyword: Annotated[str | None, Query(min_length=2)] = None
):

요청 예시는 다음과 같다.

GET /api/v1/tasks?completed=true
GET /api/v1/tasks?priority=high
GET /api/v1/tasks?keyword=FastAPI

Query Parameter는 특정 자원 하나를 찾기보다는 목록에서 조건을 걸 때 자주 사용한다.

4. PUT과 PATCH 차이

PUT은 자원 전체를 교체하는 방식이다.

replaced = TaskResponse(id=task_id, **request.model_dump())
tasks[task_id] = replaced

즉, 클라이언트가 title, description, priority, completed를 모두 보내야 한다.
기존 값 중 일부만 유지하고 싶어도 전체 데이터를 다시 보내는 방식에 가깝다.

반면 PATCH는 일부 필드만 수정한다.

changed_fields = request.model_dump(exclude_unset=True)
updated = task.model_copy(update=changed_fields)

여기서 핵심은 exclude_unset=True이다.
클라이언트가 실제로 보낸 필드만 추려서 수정하기 때문에, 보내지 않은 필드는 기존 값이 유지된다.

PUT = 전체 교체
PATCH = 일부 수정

5. APIRouter로 API 분리

API가 많아지면 하나의 main.py에 모든 코드를 넣기 어렵다.
그래서 FastAPI에서는 APIRouter를 사용해 기능별로 API를 나눌 수 있다.

router = APIRouter(prefix="/students", tags=["students"])

그리고 메인 앱에서 router를 조립한다.

app.include_router(courses.router, prefix="/api/v1")
app.include_router(students.router, prefix="/api/v1")

이 구조를 사용하면 다음처럼 역할을 나눌 수 있다.

main.py
-> FastAPI 앱 생성
-> router 등록
-> 공통 설정 관리

students.py
-> 학생 API 담당

courses.py
-> 강좌 API 담당

schemas.py
-> 공통 요청/응답 모델 관리

Spring에서 Controller를 기능별로 나누는 것과 비슷한 느낌으로 이해할 수 있다.

6. Schema 분리

schemas.py에는 여러 router에서 함께 사용하는 Pydantic 모델을 분리했다.

class StudentCreate(BaseModel):
    name: str = Field(min_length=2, max_length=30)
    level: Level = "beginner"

class CourseResponse(BaseModel):
    id: int
    title: str
    level: Level
    hours: int

Schema를 분리하면 API 파일에서는 요청 처리 흐름에 집중할 수 있고, 데이터 구조는 한 곳에서 관리할 수 있다.

7. Python File I/O

파일 입출력에서는 pathlib.Path를 사용했다.

BASE_DIR = Path(__file__).resolve().parent
DATA_DIR = BASE_DIR / "data"

파일 읽기와 쓰기는 다음처럼 처리했다.

path.read_text(encoding="utf-8")
path.write_text(content, encoding="utf-8")

바이너리 파일은 read_bytes(), write_bytes()를 사용한다.

target.write_bytes(source.read_bytes())

텍스트 파일과 이미지, PDF 같은 바이너리 파일은 처리 방식이 다르다.

구분	사용 메서드
텍스트	read_text, write_text
바이너리	read_bytes, write_bytes

8. 안전한 파일 경로 처리

파일명을 그대로 조합하면 사용자가 ../ 같은 경로를 넣어 data 폴더 밖 파일에 접근할 위험이 있다.

그래서 resolve()를 사용해 실제 경로를 계산하고, 기준 폴더 안에 있는지 확인했다.

candidate = (DATA_DIR / filename).resolve()

if DATA_DIR.resolve() not in candidate.parents:
    raise ValueError("data폴더 밖의 경로는 사용할 수 없습니다.")

파일 API에서는 단순히 저장하고 읽는 것뿐 아니라, 허용된 폴더 밖으로 나가지 못하게 막는 것이 중요하다.

9. Form과 File Upload

파일 업로드는 일반 JSON 요청과 다르게 multipart/form-data 형식을 사용한다.

FastAPI에서는 파일은 File, 일반 폼 값은 Form으로 받는다.

async def upload_file(
    file: Annotated[UploadFile, File()],
    description: Annotated[str, Form(min_length=1, max_length=100)]
):

요청에는 다음 값이 함께 들어간다.

file = 업로드 파일
description = 파일 설명

즉, 파일과 일반 문자열 값을 하나의 요청으로 함께 보낼 수 있다.

10. UploadFile 검증

파일 업로드에서는 다음 검증을 처리했다.

허용된 Content-Type인지 확인
파일 확장자와 Content-Type이 일치하는지 확인
파일 크기가 1MB 이하인지 확인
원본 파일명에서 경로 정보를 제거
UUID로 저장 파일명 생성

content = await file.read(MAX_FILE_SIZE + 1)

if len(content) > MAX_FILE_SIZE:
    raise HTTPException(status_code=413, detail="파일은 1MB 이하여야 합니다.")

파일명은 사용자가 보낸 값을 그대로 저장하지 않고 UUID를 사용했다.

file_id = str(uuid4())
stored_name = f"{file_id}{suffix}"

이렇게 하면 같은 이름의 파일이 업로드되어도 충돌을 줄일 수 있고, 사용자가 보낸 파일명에 의존하지 않아도 된다.

11. 파일 Metadata 저장

파일 본문은 .txt 또는 .pdf로 저장하고, 파일 정보는 .json으로 따로 저장했다.

metadata_path(file_id).write_text(
    json.dumps(info.model_dump(), ensure_ascii=False, indent=2),
    encoding="utf-8"
)

저장되는 정보는 다음과 같다.

id
original_name
content_type
size
description
stored_name

파일 자체와 파일 설명 정보를 분리해서 저장하면, 나중에 목록 조회나 다운로드 기능을 만들 때 활용하기 쉽다.

12. Spring과 FastAPI 연동

Spring 서버에서 FastAPI 서버를 직접 호출하는 구조도 학습했다.

FastAPI 쪽에는 상태 확인 API가 있다.

@app.get("/health")
def health():
    return {"status": "ok", "service": "fastapi-file-service"}

Spring에서는 RestClient를 사용해 FastAPI 서버로 HTTP 요청을 보낸다.

return restClient.get()
        .uri("/health")
        .retrieve()
        .body(HealthResponse.class);

흐름은 다음과 같다.

클라이언트
-> Spring Controller
-> Spring Service 또는 Client
-> FastAPI 서버 HTTP 호출
-> FastAPI 응답
-> Spring 응답 반환

중요한 점은 Spring이 Python 함수를 직접 실행하는 것이 아니라, HTTP API로 FastAPI 서버를 호출한다는 것이다.

13. Spring에서 외부 API 장애 처리

FastAPI 서버가 꺼져 있거나 연결할 수 없는 경우를 대비해 예외 처리를 추가했다.

try {
    return ResponseEntity.ok(fastApiFileClient.checkHealth());
} catch (RestClientException e) {
    return unavailable("FastAPI서버에 연결할 수 없습니다.");
}

외부 서버 호출은 실패할 수 있기 때문에, 예외를 그대로 터뜨리지 않고 명확한 응답으로 바꿔주는 것이 좋다.

503 Service Unavailable
{
  "code": "FASTAPI_UNAVAILABLE",
  "message": "FastAPI서버에 연결할 수 없습니다."
}

14. 핵심 정리

REST API는 HTTP Method와 URL을 조합해 자원을 다룬다.
GET은 조회, PUT은 전체 교체, PATCH는 일부 수정에 사용한다.
PATCH에서는 exclude_unset=True를 사용하면 클라이언트가 보낸 필드만 수정할 수 있다.
API가 많아지면 APIRouter로 기능별 파일을 분리하는 것이 좋다.
공통 요청/응답 모델은 schemas.py처럼 따로 분리하면 재사용하기 쉽다.
파일 입출력에서는 Path를 사용하면 경로를 안전하고 명확하게 다룰 수 있다.
파일 API에서는 data 폴더 밖 접근을 막는 경로 검증이 필요하다.
파일 업로드는 multipart/form-data 형식으로 처리한다.
FastAPI에서는 UploadFile, File, Form을 사용해 파일과 일반 값을 함께 받을 수 있다.
업로드 파일은 Content-Type, 확장자, 크기를 검증해야 한다.
저장 파일명은 UUID를 사용하면 파일명 충돌을 줄일 수 있다.
Spring과 FastAPI는 직접 함수 호출이 아니라 HTTP 요청으로 연동한다.
Spring RestClient는 외부 API 호출을 담당할 수 있다.
외부 API 호출은 실패 가능성이 있으므로 예외 처리와 503 응답 같은 장애 처리가 필요하다.

이슈	작업 내용
#234	장보기 항목 중복 등록 방지
#235	AI 장보기 자동화 Agent API 명세 작성
#236	Agent 냉장고/장보기 조회 Tool API 구현
#237	Agent 장보기 추가 Tool API 구현
#238	AI 장보기 추천 MVP 구현