diff --git a/Lecture/FinalProject/Doc/최종프로젝트_API서버_백그라운드워커_구조.html b/Lecture/FinalProject/Doc/최종프로젝트_API서버_백그라운드워커_구조.html new file mode 100644 index 0000000..ec01b12 --- /dev/null +++ b/Lecture/FinalProject/Doc/최종프로젝트_API서버_백그라운드워커_구조.html @@ -0,0 +1,978 @@ + + + + + +API 서버 + 백그라운드 워커로 멀티에이전트 운영하기 + + + +
+ + +
+
최종 프로젝트 · 아키텍처 가이드
+

API 서버는 주문만 받고,
멀티에이전트는 워커가 돌린다

+

프런트엔드 · FastAPI · Celery 워커 · 외부 API · 오토힐링 · Docker
— 전체 구조, 예시 폴더 구조, 빌드·실행 구성

+
AI 애플리케이션 개발 과정 · 최종 프로젝트 공통 자료
+
+ + +
+
오늘의 목표
+

이 자료를 다 보고 나면 할 수 있어야 하는 것

+

멀티에이전트 + LLM + 외부 API가 섞인 서비스를 "요청 받는 곳"과 "일하는 곳"으로 나눠 설계한다.

+
+

① 왜 나누는지 설명한다

LLM 호출을 HTTP 요청 안에서 기다리면 무엇이 깨지는지 말할 수 있다.

+

② 전체 그림을 그린다

프런트 → API → 큐 → 워커 → LLM/외부 API, 그리고 결과가 돌아오는 길을 그릴 수 있다.

+

③ 폴더를 나눈다

backend/, agents/, shared/, docker/가 각각 무엇을 담고 어떤 이미지가 되는지 안다.

+

④ 오토힐링 위치를 안다

재시도·폴백·자동 재시작을 어느 계층에 넣어야 하는지 구분한다.

+
+
02
+
+ + +
+
문제 상황
+

LLM을 API 요청 안에서 그냥 호출하면?

+

멀티에이전트 한 번 = LLM 호출 여러 번 + 외부 API 여러 번 → 수십 초 ~ 수 분.

+
+
+
# ❌ 이렇게 만들면 안 됩니다
+@router.post("/analyze")
+async def analyze(body: Req):
+    result = await graph.ainvoke(body.dict())
+    #  ↑ Supervisor → 진단 → 복구 → 검증
+    #    LLM 6번 + 외부 API 4번 … 90초
+    return result
+

사용자는 90초 동안 로딩 스피너만 봅니다. 그 사이에 무슨 일이 생길까요?

+
+
+
    +
  • 타임아웃 — 로드밸런서·프록시(보통 30~60초)가 먼저 연결을 끊음 → 504
  • +
  • 새로고침 = 작업 증발 — 브라우저를 닫으면 결과를 받을 길이 없음
  • +
  • 서버 재시작 = 작업 유실 — 배포하는 순간 진행 중이던 작업이 사라짐
  • +
  • 재시도 불가 — 외부 API가 잠깐 죽었을 때 "나중에 다시"가 안 됨
  • +
  • 서버가 막힘 — 무거운 작업이 API 서버 자원을 잡아먹어 로그인·조회까지 느려짐
  • +
+
+
+
03
+
+ + +
+
한 장으로 이해하기
+

식당으로 비유하면

+

홀 직원이 직접 요리까지 하면 손님 응대가 멈춥니다. 그래서 주문 접수와 조리를 나눕니다.

+ + + + + + + + + +
식당우리 시스템하는 일
손님프런트엔드웹/앱 화면. 주문하고, 진행 상황을 봄
홀 직원 (카운터)FastAPI API 서버주문 확인(인증·입력 검증) 후 주문표를 걸고 바로 진동벨을 건넴
주문표Job (DB 한 행)무엇을 요청했고 지금 어떤 상태인지 기록
주문 레일큐 (Redis)주방이 처리할 순서대로 주문표가 대기하는 곳
주방 / 셰프 팀워커 / 멀티에이전트주문표를 하나 꺼내 Supervisor·전문 에이전트들이 협업해 처리
식자재 납품업체LLM · 외부 API가끔 늦거나 품절 → 재시도하거나 다른 업체로 (= 오토힐링)
진동벨job_id + SSE"지금 굽는 중", "완성!"을 손님에게 알려줌
+
04
+
+ + +
+
전체 구조
+

최종 프로젝트 표준 아키텍처

+ + + + + + + 프런트엔드 (fe) + Web (React 등) + 또는 App + + + FastAPI (be 컨테이너) + · 인증(JWT)·입력 검증 + · Job 생성 → 큐에 넣기 + · 상태 조회 API + · 진행 이벤트 SSE 중계 + 빠르게 응답만 (수 ms) + + + Redis 큐 + Celery 브로커 (작업 대기열) + + + DB (PostgreSQL) + Job 상태·결과·이력 + + + Redis Pub/Sub + 진행 이벤트 전달 + + + Celery 워커 (agents 컨테이너) + + LangGraph 멀티에이전트 + + Supervisor + + + + 진단 + 복구 + 검증 + 공유 State · 자기성찰 · 재시도 노드 + 에이전트 = 팀 주제에 맞게 교체 + + + LLM API + OpenAI·Claude 등 + + 외부 API + 공공·지도·기상 등 + + + ① POST /jobs + + ② 202 job_id + + ⑦ SSE 진행상황 + + send_task + + queued + + 구독 + + ③ 꺼내기 + + ⑥ 결과 + + ⑤ 진행 + + + ④ 호출 (재시도·폴백) + +
05
+
+ + +
+
구성요소
+

누가 무엇을 책임지나

+ + + + + + + + +
구성요소책임 (해야 할 일)하면 안 되는 일기술 예시
프런트엔드요청 보내기, job_id로 진행 상황 구독, 결과 표시, 에이전트 사고 과정 가시화LLM API 키 보관·직접 호출React/Next.js, Streamlit, Flutter
API 서버인증·권한, 입력 검증, Job 생성, 큐 투입, 상태 조회, SSE 중계LLM·에이전트를 요청 안에서 실행FastAPI, Pydantic, SQLAlchemy
큐 / 브로커작업을 안전하게 보관하고 워커에게 순서대로 전달결과를 영구 저장 (그건 DB)Redis (Celery 브로커)
워커Job 꺼내서 LangGraph 실행, 진행 이벤트 발행, 결과 저장, 실패 시 재시도HTTP 요청을 직접 받음Celery (+ Flower 모니터링)
DBJob 상태·결과·감사 로그의 "단일 진실 공급원"—PostgreSQL, Supabase
LLM·외부 API워커 안의 통합 계층(integrations)에서만 호출, 타임아웃·재시도·폴백 적용에이전트 코드 곳곳에서 날것으로 호출LiteLLM, httpx, tenacity
+
06
+
+ + +
+
흐름
+

요청 한 건의 일생 (9단계)

+

핵심: API는 ②에서 즉시 응답하고 빠진다. 무거운 일은 ④~⑧, 워커가 한다.

+
+
+

FE① 사용자가 "분석 요청" 클릭 → POST /api/v1/jobs

+

API② 검증 후 DB에 Job 저장 status=queued

+

API③ Celery로 send_task("agents.run_agent_job", [job_id]) → 202 + job_id 응답

+

FE④ GET /jobs/{id}/events (SSE) 구독 시작

+

Worker⑤ Celery 워커가 태스크 수신 → status=running

+
+
+

Worker⑥ LangGraph 실행. 노드가 끝날 때마다 {"type":"step","node":"diagnosis"} 발행

+

Ext⑦ 외부 API 실패 → 재시도 / 폴백 (오토힐링)

+

Worker⑧ 결과 DB 저장 status=succeeded + done 이벤트

+

FE⑨ done 수신 → GET /jobs/{id}로 최종 결과 표시

+
+
+
새로고침해도 괜찮습니다. job_id만 있으면 GET /jobs/{id}로 언제든 현재 상태·결과를 다시 볼 수 있어요.
+
07
+
+ + +
+
Job 상태
+

Job은 "상태 머신"으로 관리한다

+

DB의 jobs.status 한 컬럼이 화면·재시도·오토힐링·감사 로그의 기준이 됩니다.

+ + + queued + running + succeeded + retrying + waiting_approval + failed + 워커가 꺼냄 + 완료 + 일시 오류 + 잠시 후 다시 실행 + 위험 작업 + 운영자 승인 + 재시도 초과 + +

※ waiting_approval: 서비스 재시작처럼 위험한 복구는 사람 승인 후 진행 (가드레일·Human-in-the-loop). 팀 주제에 필요 없으면 생략 가능.

+
08
+
+ + +
+
실시간 표시
+

워커의 진행 상황을 화면에 보여주는 3가지 방법

+ + + + + +
방식동작장점단점
폴링프런트가 2초마다 GET /jobs/{id}가장 쉬움. 일단 이것부터지연·불필요한 요청
SSE ⭐ 권장서버 → 브라우저 한 방향 스트림. 이벤트가 생길 때마다 pushHTTP 그대로, 구현 간단, 자동 재연결단방향 (요청은 별도 POST)
WebSocket양방향 연결 유지채팅처럼 주고받기가 잦을 때연결 관리·인증·배포 설정이 더 복잡
+
+
추천 순서: ① 폴링으로 흐름을 먼저 완성 → ② SSE로 교체해 "에이전트 사고 과정 가시화" 구현
+
LLM 토큰 스트리밍도 같은 길로 흘려보내면 됩니다: 워커가 {"type":"token","text":"..."} 이벤트를 발행 → SSE로 전달.
+
+
09
+
+ + +
+
선택 기준
+

무엇을 워커로 보내고, 왜 Celery인가

+
+
+

워커로 보낼 작업

+
    +
  • 멀티에이전트 실행 (LLM 여러 번)
  • +
  • 외부 API 여러 개를 엮는 작업
  • +
  • 재시도·승인 대기가 필요한 작업
  • +
  • 주기 작업 (모니터링·이상 감지) → Celery Beat
  • +
+

API에서 바로 해도 되는 것

+
    +
  • DB 조회·저장, 로그인
  • +
  • 수 초 안에 끝나는 단일 LLM 응답 스트리밍
  • +
+
+
+ + + + + + + + +
Celery 용어뜻 (식당 비유)
Broker태스크 메시지가 대기하는 곳 = 주문 레일. 우리는 Redis
Task워커가 실행할 함수 = 레시피. @app.task로 등록
Worker태스크를 꺼내 실행하는 프로세스 = 주방. 컨테이너 여러 개로 확장
Queue태스크를 나누는 줄. 예: agents, monitor
Beat정해진 시각에 태스크를 넣는 스케줄러 = 알람
Flower워커·태스크 상태를 보는 웹 대시보드 (시연·모니터링용)
+

왜 Celery? 파이썬 백그라운드 작업의 사실상 표준 → 자료·예제가 가장 많고, 재시도·시간 제한·스케줄·모니터링이 모두 갖춰져 있음. (가벼운 대안: arq, Taskiq / 데모 전용: FastAPI BackgroundTasks)

+
+
+
10
+
+ + +
+
예시 폴더 구조 ①
+

저장소 최상위: 소스 폴더 = 이미지 단위

+
+
team-project/
+├── frontend/     # → {팀}-fe 이미지 (웹/앱)
+├── backend/      # → {팀}-be 이미지 (FastAPI)
+├── agents/       # → {팀}-agents 이미지
+│                 #   (Celery 워커 + LangGraph)
+├── shared/       # be·agents 공용 코드
+├── tests/
+├── docs/         # 산출물(설계서·결과서)
+├── docker/       # 빌드·실행 스크립트 (뒤에서)
+├── .env          # 실제 값 — 커밋 금지
+├── .env.example  # 키 이름만
+└── .gitignore
+
+

be와 agents를 왜 나누나?

be는 가볍고 빨라야 하고(요청 응답), agents는 무겁고 오래 걸립니다(LangGraph·LLM SDK). 이미지를 나누면 따로 빌드·배포·확장할 수 있고, 에이전트를 고쳐도 API 서버는 그대로 둘 수 있습니다.

+

shared/에는 무엇을?

양쪽이 똑같이 알아야 하는 것만: 설정(Settings), DB 연결, jobs 테이블 모델과 상태 상수. 빌드할 때 두 이미지에 모두 복사됩니다.

+
.env는 커밋 금지. LLM·외부 API 키는 be·agents 환경변수로만. 프런트 코드에 키가 들어가면 누구나 볼 수 있습니다.
+
+
+
11
+
+ + +
+
예시 폴더 구조 ②
+

backend / agents / shared 상세

+
+
backend/                   # {팀}-be
+├── app/
+│   ├── main.py            # 앱 생성·라우터 등록
+│   ├── core/
+│   │   ├── security.py    # JWT 검증·권한
+│   │   └── celery_client.py # 태스크 "보내기" 전용
+│   ├── api/v1/
+│   │   ├── jobs.py        # POST/GET /jobs, SSE
+│   │   ├── approvals.py   # 위험 작업 승인
+│   │   └── health.py      # /health
+│   ├── schemas/job.py     # Pydantic 요청·응답
+│   └── services/job_service.py
+└── requirements.txt       # fastapi, celery, redis
+
+shared/                    # 두 이미지 공용
+├── config.py              # Settings(환경변수)
+├── db.py                  # 엔진·세션
+└── models.py              # jobs 테이블·상태 상수
+
agents/                    # {팀}-agents
+├── worker/
+│   ├── celery_app.py      # Celery 앱·설정
+│   ├── tasks.py           # run_agent_job 태스크
+│   ├── job_store.py       # jobs 상태 변경
+│   └── events.py          # 진행 이벤트 발행
+├── graph/                 # LangGraph 멀티에이전트
+│   ├── build.py           # build_graph()
+│   ├── state.py           # 공유 State
+│   ├── supervisor.py
+│   ├── nodes/             # 팀 주제에 맞게
+│   │   └── diagnosis.py, recovery.py …
+│   └── prompts/
+├── integrations/          # 바깥 세상과의 경계
+│   ├── base.py            # 타임아웃·재시도 공통
+│   ├── llm.py             # LLM 게이트웨이
+│   └── public_api.py
+├── healing/               # 폴백·정책·주기 점검
+└── requirements.txt       # celery, langgraph, httpx
+
+
12
+
+ + +
+
가장 중요한 규칙
+

be는 agents 코드를 import하지 않는다

+ + + backend/{팀}-be + RedisCelery 브로커 + agents/worker{팀}-agents + agents/graph + integrations + + + + + 태스크 이름 + job_id만 + job_id로 DB에서 입력을 읽음 + healing 정책 적용 + shared/ (config · db · models) — be·agents 모두 import 가능 + +
+

✅ 이름으로 보내기

be는 send_task("agents.run_agent_job", ...)처럼 문자열 이름으로 보냅니다. 그래서 be 이미지에는 LangGraph·LLM 라이브러리가 없어도 됩니다.

+

✅ 인자에는 ID만

큰 입력(문서·대화 내용)은 DB에 저장하고 태스크 인자로는 job_id만. 재시도·감사 추적이 쉬워지고 브로커가 가벼워집니다.

+

❌ agents → backend

에이전트 노드에서 FastAPI·Request를 import하면 안 됩니다. 에이전트는 HTTP를 몰라야 단독으로 테스트할 수 있습니다.

+
+
13
+
+ + +
+
예시 코드 ① · API 서버 (be)
+

Job 만들고 Celery로 보낸 뒤 바로 202

+
+
+
backend/app/api/v1/jobs.py
+
from fastapi import APIRouter, Depends, status
+from app.core.celery_client import celery_client
+from app.core.security import current_user
+from app.schemas.job import JobCreate, JobAccepted, JobRead
+from app.services import job_service
+from shared.db import get_db
+
+router = APIRouter(prefix="/jobs", tags=["jobs"])
+
+@router.post("", status_code=status.HTTP_202_ACCEPTED,
+             response_model=JobAccepted)
+async def create_job(body: JobCreate, db=Depends(get_db),
+                     user=Depends(current_user)):
+    job = await job_service.create(db, user.id, body)  # ① DB: queued
+    celery_client.send_task("agents.run_agent_job",      # ② 이름으로 전송
+                            args=[job.id], queue="agents")
+    return JobAccepted(job_id=job.id, status="queued")  # ③ 즉시 응답
+
+@router.get("/{job_id}", response_model=JobRead)
+async def get_job(job_id: str, db=Depends(get_db)):
+    return await job_service.get(db, job_id)  # 상태·결과 조회
+
+
+
backend/app/core/celery_client.py
+
from celery import Celery
+from shared.config import settings
+
+# 보내기 전용 클라이언트
+# (태스크 함수는 여기 없음!)
+celery_client = Celery(
+    "be", broker=settings.redis_url)
+

포인트

+

· send_task는 브로커에 메시지만 넣고 즉시 돌아옵니다 (수 ms).
+ · 태스크 이름 "agents.run_agent_job"은 워커 쪽 @app.task(name=...)와 정확히 같아야 합니다.
+ · 결과는 Celery가 아니라 DB의 jobs 테이블에서 조회합니다.

+
+
+
14
+
+ + +
+
예시 코드 ② · Celery 워커 (agents)
+

워커: 태스크를 받아 LangGraph를 돌리고 진행 상황을 알린다

+
+
+
agents/worker/tasks.py
+
from agents.worker.celery_app import app
+from agents.worker import job_store as js
+from agents.worker.events import publish
+from agents.graph.build import build_graph
+from agents.integrations.base import TransientError
+graph = build_graph()                     # 워커 시작 시 한 번만 조립
+@app.task(name="agents.run_agent_job", bind=True, max_retries=3)
+def run_agent_job(self, job_id: str):
+    if not js.claim(job_id):              # queued→running 선점 실패면
+        return                            # 이미 처리 중 → 중복 실행 방지
+    try:
+        state = {}
+        for upd in graph.stream(js.get_input(job_id), stream_mode="updates"):
+            node, data = next(iter(upd.items()))
+            publish(job_id, {"type": "step", "node": node})
+            state.update(data or {})
+        js.succeed(job_id, state)
+        publish(job_id, {"type": "done"})
+    except TransientError as e:            # 잠깐의 장애 → 다시
+        if self.request.retries < self.max_retries:
+            js.mark_retrying(job_id)
+            raise self.retry(exc=e, countdown=10 * (self.request.retries + 1))
+        js.fail(job_id, e); raise       # 재시도 소진
+    except Exception as e:                 # 복구 불가 → 실패 기록
+        js.fail(job_id, e); raise       # status=failed + failed 이벤트
+
+
+
agents/worker/celery_app.py
+
from celery import Celery
+from shared.config import settings
+
+app = Celery("agents", broker=settings.redis_url,
+             include=["agents.worker.tasks"])
+app.conf.update(
+    task_default_queue="agents",
+    task_acks_late=True,      # 끝난 뒤 완료 처리
+    task_reject_on_worker_lost=True, # 워커가
+                     # 죽으면 다른 워커가 다시 받음
+    worker_prefetch_multiplier=1, # 하나씩
+    task_soft_time_limit=540,  # 9분: 예외로 경고
+    task_time_limit=600,       # 10분: 강제 종료
+    task_ignore_result=True,   # 결과는 DB에
+)
+
agents/worker/events.py
+
import json, redis
+r = redis.Redis.from_url(settings.redis_url)
+
+def publish(job_id, ev):
+    r.publish(f"job:{job_id}",
+              json.dumps(ev, ensure_ascii=False))
+
+
+
15
+
+ + +
+
Celery 실전 메모
+

중복 실행 막기와 워커 실행 방법

+
+
+
agents/worker/job_store.py — 상태 "선점(claim)"
+
from sqlalchemy import update
+from shared.db import SessionLocal
+from shared.models import Job
+
+def claim(job_id: str) -> bool:
+    """queued/retrying 인 Job만 running으로.
+    UPDATE 한 번이라 두 워커가 동시에 와도
+    한 명만 성공(rowcount == 1)."""
+    with SessionLocal() as s, s.begin():
+        res = s.execute(
+            update(Job)
+            .where(Job.id == job_id,
+                   Job.status.in_(["queued", "retrying"]))
+            .values(status="running"))
+    return res.rowcount == 1
+

acks_late를 켜면 같은 태스크가 두 번 올 수 있습니다 → 이 선점 로직이 "복구가 두 번 실행"을 막아 줍니다.

+
+
+

Celery 태스크는 동기 함수

+

워커 쪽 코드(graph.stream, httpx.Client, 동기 DB 세션)는 동기로 작성하는 것이 가장 단순합니다. async 코드를 꼭 써야 하면 태스크 안에서 asyncio.run(...)으로 감쌉니다.

+

로컬 개발 실행 (터미널 3개)

+
docker run -p 6379:6379 redis:7-alpine
+uvicorn app.main:app --reload            # backend/
+celery -A agents.worker.celery_app worker \
+       -Q agents -l INFO                 # 루트에서
+

Windows에서는 워커에 --pool=solo를 붙이세요.

+
Flower (localhost:5555)로 워커 수·대기 태스크·실패·재시도를 실시간으로 보여주면 오토힐링 시연에 좋습니다.
+
+
+
16
+
+ + +
+
예시 코드 ③ · 진행 상황 스트리밍
+

SSE: 워커 이벤트를 브라우저까지

+
+
+
backend/app/api/v1/jobs.py (이어서) — 워커가 Redis로 발행한 이벤트를 중계
+
import json
+from fastapi.responses import StreamingResponse
+
+@router.get("/{job_id}/events")
+async def job_events(job_id: str, request: Request):
+    async def stream():
+        ps = request.app.state.redis.pubsub()
+        await ps.subscribe(f"job:{job_id}")
+        try:
+            async for msg in ps.listen():
+                if msg["type"] != "message":
+                    continue
+                yield f"data: {msg['data']}\n\n"  # SSE 형식
+                if json.loads(msg["data"])["type"] in ("done", "failed"):
+                    break
+        finally:
+            await ps.unsubscribe()
+            await ps.aclose()
+    return StreamingResponse(stream(),
+                             media_type="text/event-stream")
+
+
+
frontend/src/hooks/useJob.ts
+
const res = await fetch("/api/v1/jobs", {
+  method: "POST", headers, body });
+const { job_id } = await res.json();
+
+const es = new EventSource(
+  `/api/v1/jobs/${job_id}/events`);
+es.onmessage = (e) => {
+  const ev = JSON.parse(e.data);
+  if (ev.type === "step") showStep(ev.node);
+  if (ev.type === "done" || ev.type === "failed") {
+    es.close();
+    loadResult(job_id); // GET /jobs/{id}
+  }
+};
+
주의 2가지
+ · Pub/Sub은 구독 전 이벤트를 저장하지 않음 → 화면 진입 시 GET /jobs/{id}로 현재 상태를 먼저 그리기
+ · EventSource는 Authorization 헤더를 못 붙임 → 쿠키 인증 또는 fetch 기반 SSE 라이브러리 사용
+
+
+
17
+
+ + +
+
오토힐링
+

오토힐링은 4개 계층에 나눠서 넣는다

+

"오토힐링 = 에이전트가 알아서 고친다"가 전부가 아닙니다. 아래 계층일수록 단순·확실하게.

+ + + + + + +
계층무엇이 고장나나자동 조치코드 위치
① 호출외부 API 타임아웃·5xx·429, LLM 과부하타임아웃 → 지수 백오프 재시도 → 폴백(백업 API·캐시·다른 모델)agents/integrations/
agents/healing/
② 에이전트LLM 출력 형식 오류, 근거 부족, 잘못된 판단스키마 검증 실패 → 재생성, 자기성찰 노드에서 재진단(최대 N회) → 사람 이관agents/graph/
③ 작업Job 처리 중 예외, 워커 강제 종료Celery self.retry(), acks_late로 워커가 죽어도 재전달, 상태 선점(claim)으로 중복 방지, 최종 실패는 failedagents/worker/tasks.py
celery_app.py
④ 인프라프로세스 다운, 메모리 초과헬스체크 실패 → 컨테이너 자동 재시작, 워커 여러 개 띄우기docker/compose/compose.yml
agents/healing/monitor.py
+
평가 포인트: 복구를 시연하려면 장애를 일부러 주입하고(예: 외부 API URL을 끊기) 감지 시각·복구 시각을 로그로 남겨야 합니다.
+
18
+
+ + +
+
예시 코드 ④ · 호출 계층 오토힐링
+

외부 API 래퍼: 타임아웃 → 재시도 → 폴백

+
+
+
agents/integrations/base.py · public_api.py
+
import httpx
+from tenacity import (retry, stop_after_attempt,
+    wait_exponential, retry_if_exception_type)
+
+class TransientError(Exception): ...  # "잠깐 기다리면 될 오류"
+
+@retry(stop=stop_after_attempt(3),
+       wait=wait_exponential(min=1, max=8),       # 1→2→4초
+       retry=retry_if_exception_type(TransientError), reraise=True)
+def get_json(client, url, params):
+    try:
+        r = client.get(url, params=params, timeout=5.0)
+    except (httpx.TimeoutException, httpx.NetworkError) as e:
+        raise TransientError(str(e)) from e
+    if r.status_code == 429 or r.status_code >= 500:
+        raise TransientError(f"HTTP {r.status_code}")
+    r.raise_for_status()           # 4xx = 내 잘못 → 재시도 X
+    return r.json()
+
+def get_crowd(area: str) -> dict:
+    with httpx.Client() as c:
+        try:
+            return get_json(c, PRIMARY_URL, {"area": area})
+        except TransientError:
+            if cached := cache.get(area):             # 폴백 ① 캐시
+                return {**cached, "stale": True}
+            return get_json(c, BACKUP_URL, {"area": area})  # ② 백업
+
+
+

오류를 두 종류로 나누기

+

일시적 (타임아웃·5xx·429) → 재시도할 가치 있음
영구적 (400·401·404) → 재시도해도 똑같음, 즉시 실패

+

재시도는 두 겹

+

① 여기(tenacity): 몇 초 안의 짧은 재시도
② 그래도 실패 → TransientError가 태스크까지 올라가 Celery self.retry()로 수십 초 뒤 전체 재실행

+

폴백 결과는 표시하기

+

"stale": true처럼 남겨 에이전트·화면이 "최신 아님"을 알게 합니다. LLM도 integrations/llm.py(LiteLLM 등)에 모아 모델 폴백을 한 곳에서.

+
+
+
19
+
+ + +
+
Docker ①
+

docker/ 폴더: 빌드와 실행을 한곳에

+
+
docker/
+├── build.sh             # 모든 이미지 빌드 + VERSION 갱신
+├── start.sh             # 컴포즈 시작
+├── stop.sh              # 컴포즈 종료
+├── restart.sh           # 재시작 (stop → start)
+├── compose/
+│   ├── compose.yml      # 서비스 정의
+│   └── .env             # 서비스 환경설정
+│                        #  (루트 .env 심볼릭 링크 가능)
+└── images/              # 우리 소스로 빌드하는 이미지
+    ├── {팀}-fe/          # 프런트엔드
+    │   ├── Dockerfile
+    │   └── VERSION      # 예: 261119-1650
+    ├── {팀}-be/          # 백엔드 API 서버
+    │   ├── Dockerfile
+    │   └── VERSION
+    ├── {팀}-agents/      # Celery 워커 + 에이전트
+    │   ├── Dockerfile
+    │   └── VERSION
+    └── …                # 필요 시 추가
+
+

폴더 이름 = 이미지 이름

images/bike-be/ → 이미지 bike-be:261119-1650. 팀 프리픽스로 다른 팀·프로젝트 이미지와 섞이지 않습니다.

+

images/에 없는 것

Redis·PostgreSQL·Flower처럼 공식 이미지를 그대로 쓰는 서비스는 빌드하지 않고 compose.yml에서 바로 가져옵니다.

+

VERSION = 빌드 시각

YYMMDD-hhmm 형식으로 build.sh가 자동 기록. 문제가 생기면 이전 시각 태그로 바로 되돌릴 수 있습니다.

+
.env 링크: ln -s ../../.env docker/compose/.env
compose는 compose.yml과 같은 폴더의 .env를 자동으로 읽습니다.
+
+
+
20
+
+ + +
+
Docker ②
+

build.sh와 Dockerfile

+
+
+
docker/build.sh
+
#!/usr/bin/env bash
+# 사용법: ./docker/build.sh            (전체)
+#        ./docker/build.sh bike-agents (일부만)
+set -euo pipefail
+cd "$(dirname "$0")/.."            # 프로젝트 루트로 이동
+
+VERSION=$(date +%y%m%d-%H%M)       # 예: 261119-1650
+TARGETS=("$@")
+if [ ${#TARGETS[@]} -eq 0 ]; then
+  TARGETS=($(ls docker/images))    # 인자 없으면 전부
+fi
+
+for name in "${TARGETS[@]}"; do
+  dir="docker/images/$name"
+  echo "▶ $name:$VERSION"
+  docker build -f "$dir/Dockerfile" \
+    -t "$name:$VERSION" -t "$name:latest" .   # 컨텍스트=루트
+  echo "$VERSION" > "$dir/VERSION"  # 성공했을 때만 기록
+done
+

빌드 컨텍스트가 프로젝트 루트라서 Dockerfile이 shared/, backend/, agents/를 모두 COPY할 수 있습니다.

+
+
+
docker/images/{팀}-be/Dockerfile
+
FROM python:3.12-slim
+WORKDIR /srv
+COPY backend/requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY shared/ ./shared/
+COPY backend/app/ ./app/
+ENV PYTHONPATH=/srv
+CMD ["uvicorn", "app.main:app", \
+     "--host", "0.0.0.0", "--port", "8000"]
+
docker/images/{팀}-agents/Dockerfile
+
FROM python:3.12-slim
+WORKDIR /srv
+COPY agents/requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY shared/ ./shared/
+COPY agents/ ./agents/
+ENV PYTHONPATH=/srv
+CMD ["celery", "-A", "agents.worker.celery_app", \
+     "worker", "-Q", "agents", "-l", "INFO"]
+

requirements를 먼저 COPY → 소스만 바뀌면 pip 단계는 캐시 재사용 (빌드 빨라짐).

+
+
+
21
+
+ + +
+
Docker ③
+

compose.yml: 서비스 조립

+
+
+
docker/compose/compose.yml
+
services:
+  fe:
+    image: ${TEAM}-fe:${FE_VERSION:-latest}
+    ports: ["80:80"]
+  be:
+    image: ${TEAM}-be:${BE_VERSION:-latest}
+    env_file: .env
+    ports: ["8000:8000"]
+    depends_on: [redis, db]
+    restart: unless-stopped
+  agents:
+    image: ${TEAM}-agents:${AGENTS_VERSION:-latest}
+    env_file: .env
+    depends_on: [redis, db]
+    restart: unless-stopped      # 죽으면 자동 재시작
+    deploy: { replicas: 2 }      # 워커 2개
+  agents-beat:                   # 주기 작업 (같은 이미지!)
+    image: ${TEAM}-agents:${AGENTS_VERSION:-latest}
+    env_file: .env
+    command: celery -A agents.worker.celery_app beat -l INFO
+  flower:                        # 모니터링 대시보드
+    image: mher/flower
+    command: celery --broker=redis://redis:6379/0 flower
+    ports: ["5555:5555"]
+  redis: { image: redis:7-alpine, restart: unless-stopped }
+  db:
+    image: postgres:16
+    env_file: .env
+    volumes: [pgdata:/var/lib/postgresql/data]
+volumes: { pgdata: {} }
+
+
+
docker/compose/.env (예시)
+
COMPOSE_PROJECT_NAME=bike
+TEAM=bike
+# 롤백할 때만 지정 (비우면 latest)
+# AGENTS_VERSION=261118-0930
+REDIS_URL=redis://redis:6379/0
+POSTGRES_PASSWORD=change-me
+DATABASE_URL=postgresql://postgres:change-me@db/app
+OPENAI_API_KEY=...
+
    +
  • 버전 고정·롤백: AGENTS_VERSION만 바꾸고 start → 그 시각 이미지로
  • +
  • 같은 이미지, 다른 command: agents와 agents-beat
  • +
  • 주의: 단독 Docker의 restart는 프로세스가 죽었을 때만 재시작합니다. 응답 없음(unhealthy) 감지·재시작은 healing/monitor가 맡도록 설계하세요.
  • +
+
+
+
22
+
+ + +
+
Docker ④
+

start · stop · restart 스크립트와 일상 작업 흐름

+
+
docker/start.sh
+
#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$0")/compose"
+docker compose up -d "$@"
+docker compose ps
+
docker/stop.sh
+
#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$0")/compose"
+docker compose down
+# DB 볼륨은 유지됨
+# (down -v 는 DB 삭제!)
+
docker/restart.sh
+
#!/usr/bin/env bash
+set -euo pipefail
+DIR="$(cd "$(dirname "$0")" && pwd)"
+"$DIR/stop.sh"
+"$DIR/start.sh"
+
+ + + + + + + +
상황명령
처음 띄우기./docker/build.sh && ./docker/start.sh
에이전트 코드만 고침./docker/build.sh bike-agents && ./docker/start.sh (바뀐 서비스만 새로 생성)
깨끗하게 다시 시작./docker/restart.sh
워커 로그 보기 / 워커 늘리기cd docker/compose && docker compose logs -f agents / docker compose up -d --scale agents=4
장애 주입 (오토힐링 시연)docker compose exec agents sh -c "kill 1" → 워커 자동 재시작·태스크 재전달 확인 (Flower로 시연)
+

처음 한 번 실행 권한 부여: chmod +x docker/*.sh

+
23
+
+ +
+
우리 팀에 대입하기
+

같은 구조, 다른 내용물

+

구조는 그대로 두고 Job · 에이전트 · 외부 API · 힐링 포인트만 팀 주제에 맞게 채웁니다. (아래는 예시)

+ + + + + + + +
묶음배달 오토힐링축제 다국어 안심 관광 비서자전거 안전 상담·코스 추천
Job 1건"이 배달 묶음에 이상 있음 → 진단·재배정""외국인 관광객 질문 1건 → 안전 답변 생성""출발지·조건 → 코스 추천 + 안전 상담"
에이전트감지 → 진단 → 재배정(복구) → 검증언어·의도 파악 → 혼잡도 조회 → 경로·대피 안내 → 응답 검증상담 → 코스 탐색 → 위험구간 결합 → 검증
외부 API지도·경로, 기상공공 혼잡도·관광 정보, 번역(LLM)자전거도로·사고다발 공공데이터, 기상
힐링 포인트지연·이탈 감지 시 재배정 / 경로 API 실패 시 거리 추정 폴백공공 API 1차 → 2차 → 캐시(stale 표시) 페일오버기상 API 장애 시 기본 안전 안내 + 재시도 / LLM 모델 폴백
주기 작업N분마다 진행 중 배달 점검N분마다 혼잡도 수집·캐시 갱신매일 공공데이터 갱신
+
24
+
+ + +
+
구현 순서
+

처음부터 LLM 붙이지 말고, 뼈대부터

+
+

1가짜 워커

Celery 태스크 안에서 time.sleep(3) 세 번 + 이벤트 발행만. POST → 202 → 폴링 → done이 돌면 성공.

+

2상태·DB

jobs 테이블과 상태 머신(queued/running/succeeded/failed) 완성. 새로고침해도 결과가 보여야 함.

+

3SSE 화면

폴링을 SSE로 교체. 노드 이름이 화면에 하나씩 찍히는 "사고 과정 타임라인".

+

4에이전트 연결

sleep 자리에 graph.stream(). 에이전트는 노트북/단위 테스트로 먼저 검증한 뒤 붙이기.

+

5외부 API·힐링

agents/integrations/ 래퍼에 재시도·폴백. 장애 주입 스위치(환경변수)를 만들어 둔다.

+

6측정·배포

docker/build.sh → start.sh로 배포. 장애 주입 → 감지·복구 시간 로그 → Auto-Healing 결과서.

+
+
1~3단계는 LLM 비용 0원으로 끝납니다. 구조가 먼저 돌아가야 에이전트 문제와 인프라 문제를 구분해서 디버깅할 수 있어요.
+
25
+
+ + +
+
점검
+

흔한 실수 체크리스트

+
+
+

☐ API 엔드포인트 안에서 graph.ainvoke()를 기다리고 있다

+

☐ BackgroundTasks로 멀티에이전트를 돌린다 (재시작 시 유실)

+

☐ Celery 태스크 인자로 대화 전문·파일 내용을 통째로 넘긴다 → ID만

+

☐ Job 상태를 DB에 안 남겨서 새로고침하면 결과가 사라진다

☐ docker compose down -v로 DB 볼륨까지 지운다

+

☐ 모든 오류를 무조건 재시도한다 (400·401도)

+
+
+

☐ 재시도 횟수·타임아웃 상한이 없다 → 무한 루프·비용 폭탄

+

☐ LLM·외부 API 키가 프런트 코드나 GitHub에 있다

+

☐ API 서버의 async def 안에서 requests·time.sleep 같은 동기 호출을 한다

+

☐ 같은 요청이 두 번 들어와 복구가 두 번 실행된다 → 멱등 키

+

☐ 이미지를 latest로만 관리해 이전 버전으로 되돌릴 수 없다

+
+
+
한 줄 요약: API는 주문만 받고(202), 워커가 요리하고(LangGraph), 진동벨로 알리고(SSE), 납품이 늦으면 다른 길로 간다(오토힐링).
+
26
+
+ +
+ +
+ 1 / 1 + +
+ + + + diff --git a/Lecture/FinalProject/Doc/최종프로젝트_API서버_백그라운드워커_구조.pdf b/Lecture/FinalProject/Doc/최종프로젝트_API서버_백그라운드워커_구조.pdf new file mode 100644 index 0000000..306abcd Binary files /dev/null and b/Lecture/FinalProject/Doc/최종프로젝트_API서버_백그라운드워커_구조.pdf differ