소속팀: Developer팀 작성자: 유수영
🤖 상담사에게는 하나의 흐름이지만, 서비스의 책임은 나누어야 합니다.
이벤트를 찾고, 선택한 자료로 질문하고, 다시 볼 내용을 저장합니다. 이 글은 FastAPI와 서비스 컨테이너, 공통 Agent 구성요소로 그 흐름을 연결하는 설계 사례입니다. 검색·답변·기록을 나누면 바꿀 곳과 실패한 곳을 찾기 쉬워집니다.
기존 설계의 앱 기동, 지연 초기화, API와 서비스 분리, 이력 재사용을 중심으로 정리했습니다. 코드는 구조를 확인하기 위한 축약 예제입니다. 실제 서비스의 인증·검색·모델·DB 구현을 그대로 옮긴 것은 아닙니다.
| 궁금한 점 | 이 글에서 살펴볼 내용 |
|---|---|
| 검색과 상세 질문은 왜 나눌까? | 상담 흐름과 기능별 의존성 |
| 연결은 언제 만들고 닫을까? | 앱 수명과 서비스 컨테이너 |
| 라우터에는 어떤 코드를 둘까? | HTTP 계약과 업무 규칙의 경계 |
| 기록은 어떻게 다시 사용할까? | 검색 이력, 즐겨찾기, 최근 본 이벤트 |
| 한 기능이 실패하면 어떻게 할까? | 부분 실패와 운영 관측 |
1. 개요: 상담사가 다음 화면으로 넘어갈 수 있도록
상담사가 “온라인 쇼핑 할인 이벤트를 찾아줘”라고 요청합니다. 결과에서 이벤트 하나를 고르고, 적용 조건을 다시 묻습니다. 다음 상담에도 참고하려고 즐겨찾기에 저장할 수 있습니다. 사용자에게는 이 과정이 끊기지 않는 것이 중요합니다.
서비스에서는 서로 다른 작업이 이어집니다. 검색기는 관련 자료를 찾고, 모델은 선택한 자료를 설명합니다. 저장 계층은 사용자별 기록을 남깁니다. 모든 기능을 하나의 처리 함수에 넣으면 변경의 영향도 함께 커집니다.
이 사례는 검색 중심 API와 선택 문서 기반 질의 API를 나눴습니다. 검색에는 후보 이벤트를 빠르게 찾는 책임을 줍니다. 상세 질문에는 선택한 문서를 근거로 답하는 책임을 줍니다. 사용자 기록은 별도 저장 계층에서 관리합니다.
그림 1. 검색, 상세 질문, 다시 보기를 하나의 상담 흐름으로 연결합니다. AI 생성 일러스트입니다.
먼저 나누는 두 가지 경로
검색 응답의 answer는 검색 건수 안내일 수 있습니다. 상세 질의의 answer는 모델이 생성한 상담 답변입니다. 같은 필드 이름을 쓰더라도 화면과 평가에서 의미를 구분해야 합니다.
| 구분 | 이벤트 검색 | 선택 이벤트 상세 질문 |
|---|---|---|
| 입력 | 질문, 기간, 접근 범위 | 질문, 선택한 묶음 ID, 세션 |
| 핵심 작업 | 대표·첨부 문서 검색 | 묶음 문서 조회 후 답변 생성 |
| 모델 의존성 | 기본 검색 경로에서는 불필요 | 답변 생성에 필요 |
| 기록 | 검색 이력 | 대화와 답변 상태 |
여기서 묶음은 같은 이벤트의 대표 문서와 첨부 문서를 뜻합니다. 코드에서는 bundle_id로 구분합니다. 검색 때 접근할 수 있었다고 상세 질문에서도 권한 검사를 생략하지는 않습니다.
2. 상세내용: 역할과 수명을 기준으로 서비스 나누기
2.1 전체 구조는 계층보다 책임으로 이해하기
기존 서비스는 앱 구성, 설정, API, 업무 서비스, 프롬프트, 평가로 나뉩니다. 공통 Agent 계층은 모델과 검색기 연결을 지원합니다. 서비스는 이를 이용해 상담 업무의 순서를 구성합니다.

그림 2. 검색 경로와 답변 경로가 필요한 구성요소를 구분한 흐름도입니다.
| 영역 | 책임 | 다른 영역에 넘길 일 |
|---|---|---|
| 앱 구성 | 설정, 미들웨어, 라우터, 시작·종료 | 상담 업무 판단 |
| API | 입력 검증, 인증 주체 전달, 응답 형식 | 검색 전략과 문서 조합 |
| 업무 서비스 | 검색·답변·기록의 순서와 실패 정책 | SDK별 호출 형식 |
| 검색 서비스 | 필터, 대표·첨부 조회, 근거 구성 | 사용자 응답 문구 |
| 저장 계층 | 이력·즐겨찾기 조회와 저장 | HTTP 상태 코드 결정 |
| 공통 어댑터 | 모델·검색·DB 연결 차이 처리 | 업무별 정답 기준 |
| 평가 | 근거와 답변의 품질 비교 | 운영 요청 자체의 처리 |
💡 계층을 많이 만든다고 구조가 좋아지는 것은 아닙니다. 변경 이유와 자원 수명이 다른 부분을 나누는 것이 기준입니다. 같은 책임을 컨테이너와 라우터 양쪽에 중복해서 두지 않습니다.
2.2 앱 생성: 무엇을 준비하고 무엇을 정리할까?
FastAPI 앱을 만들 때는 라우터만 연결하는 것으로 끝나지 않습니다. 요청을 받기 전에 필요한 연결을 준비하고, 종료할 때 자원을 반환해야 합니다. 이 범위를 앱의 lifespan으로 묶을 수 있습니다.
| 기동 단계의 책임 | 확인할 항목 |
|---|---|
| 설정 읽기 | 필수 값, 서비스 버전, 허용된 실행 옵션 |
| 컨테이너 준비 | 생성 함수와 자원 소유권 |
| 필수 자원 초기화 | 요청을 받기 위한 최소 준비 상태 |
| 미들웨어 등록 | CORS, 요청 추적, 인증·이력 정책 |
| 라우터 등록 | 상태 확인, 검색, 질의, 사용자 기록 |
| 종료 처리 | 진행 중 요청 정리 후 소유한 자원 해제 |
모든 자원을 기동 시 만들 필요는 없습니다. 기본 검색에 필요한 연결은 미리 확인하고, 선택 기능은 첫 사용 때 준비할 수 있습니다. 어느 기능을 지연 초기화할지는 서비스의 가용성 정책과 함께 정합니다.
2.3 컨테이너: 공유할 객체와 요청별 상태를 구분하기
컨테이너는 필요한 서비스를 만들고 보관하는 역할입니다. 기존 설계는 Agent, DB, 대화 이력 관리자를 필요할 때 준비합니다. 생성 비용이 큰 연결을 요청마다 다시 만들지 않으려는 목적입니다. 테스트에서는 생성 함수를 바꿔 외부 연결을 대체할 수 있습니다.
반면 사용자 ID나 현재 질문은 요청별 정보입니다. 공유 서비스 객체에 “현재 사용자”를 저장하면 다른 요청과 섞일 수 있습니다. 사용자와 세션 정보는 호출 인자로 전달합니다. 객체를 공유해도 대화 상태까지 함께 공유하는 것은 아닙니다.
첫 요청이 동시에 들어오는 경우도 생각해야 합니다. 서비스가 아직 없다는 이유로 여러 연결을 함께 만들 수 있습니다. 초기화 구간을 보호하고, 성공한 객체만 캐시에 넣습니다. 실패한 객체를 준비 완료 상태로 남기지 않는 것도 중요합니다.
그림 3. 컨테이너는 연결의 생성과 수명을 관리합니다. AI 생성 일러스트입니다.
다음은 비동기 서비스 하나를 지연 초기화하는 예제입니다. 생성 함수는 자원을 정리할 수 있는 비동기 컨텍스트 매니저를 반환합니다. 컨테이너는 자신이 소유한 자원만 종료한다고 가정합니다.
|
import asyncio |
|---|
이 잠금과 캐시는 한 프로세스 안에서만 동작합니다. 여러 워커를 실행하면 각 워커가 별도의 연결 풀을 가질 수 있습니다. DB 연결 한도는 워커 수까지 고려해 정합니다.
생성 함수가 자원을 일부 만든 뒤 실패하면 그 함수가 정리해야 합니다. 컨테이너에 등록되기 전의 자원은 자동으로 회수된다고 가정할 수 없습니다. 앱 종료 전에는 새 요청을 막고 진행 중 작업을 정리하는 순서도 필요합니다.
2.4 lifespan으로 컨테이너와 앱의 수명 연결하기
아래 예제는 Python 3.10 이상, FastAPI, Pydantic 2를 기준으로 작성했습니다. router는 다음 절에서 정의하며, create_app() 호출 전에 준비합니다. eager=True이면 시작할 때 서비스를 준비하고, 아니면 첫 요청까지 미룹니다.
|
from fastapi import FastAPI |
|---|
앱마다 컨테이너를 따로 두면 테스트 사이의 공유 상태도 줄일 수 있습니다. 실제 자원의 준비·종료 시점은 FastAPI lifespan 문서를 참고할 수 있습니다. 기동 성공과 모든 선택 기능의 사용 가능 여부는 별도로 구분합니다.
2.5 Router: HTTP 계약과 업무 실행의 경계
라우터는 입력을 검증하고, 인증된 요청 주체를 서비스에 전달합니다. 서비스는 검색 조건과 업무 순서를 처리합니다. 권한 관련 값은 본문의 사용자 ID를 그대로 믿고 사용하지 않습니다.
| 요청 정보 | 사용하는 위치 | 확인할 기준 |
|---|---|---|
| 인증된 사용자 | 검색·기록·대화 전반 | 검증된 로그인 주체인가? |
| 그룹·업무 범위 | 검색과 문서 조회 | 서버에서 확인한 접근 범위인가? |
| 세션 ID | 상세 질문과 대화 저장 | 사용자 범위 안에서 연결되는가? |
| 묶음 ID | 선택 문서 조회 | 현재 조회 권한이 있는가? |
| 기간·검색 개수 | 검색 서비스 | 허용된 형식과 상한인가? |
기존의 X-User-ID, X-Group-ID 헤더도 인증 경계에서 검증된 값이어야 합니다. X-Session-ID는 대화를 연결하는 값이며 접근 권한 자체를 증명하지는 않습니다.
다음 예제는 인증이 없으면 401을 반환합니다. 실제 인증 구현은 별도이며, 테스트에서는 이 의존성만 대체합니다. 인증 이후의 문서 접근 제어는 검색·조회 단계에서도 적용해야 합니다.
from dataclasses import dataclass
from typing import Annotated, Literal
from fastapi import APIRouter, Depends, HTTPException, Request
from pydantic import BaseModel, Field, StringConstraints
Text = Annotated[str, StringConstraints(strip_whitespace=True, min_length=1)]
@dataclass(frozen=True)
class Principal:
user_id: str
group_ids: tuple[str, …]
async def require_principal():
raise HTTPException(401, detail=”인증이 필요합니다.”)
class SearchRequest(BaseModel):
query: Text
top_k: int = Field(default=5, ge=1, le=20, strict=True)
class DocumentInfo(BaseModel):
chunk_id: str
content: str
metadata: dict = Field(default_factory=dict)
score: float | None = None
documents_by_attach: list[“DocumentInfo”] = Field(default_factory=list)
class QueryResponse(BaseModel):
mode: Literal[“search”, “answer”]
answer: str
query: str
documents: list[DocumentInfo] = Field(default_factory=list)
session_id: str | None = None
metadata: dict = Field(default_factory=dict)
router = APIRouter()
@router.post(“/events/search”, response_model=QueryResponse)
async def search_event(body: SearchRequest, request: Request,
principal: Annotated[Principal, Depends(require_principal)]):
service = await request.app.state.container.get_service()
return await service.search(
query=body.query, top_k=body.top_k, principal=principal
)
응답의 mode는 검색 안내와 생성 답변을 구분하기 위해 추가한 예시 필드입니다. 실제 계약에 도입할 때는 화면과 기존 클라이언트의 호환성을 확인합니다. 목록과 사전의 기본값은 객체별로 생성되도록 의도를 드러냈습니다. 기본값 구성은 Pydantic 필드 문서를 참고할 수 있습니다.
2.6 미들웨어에는 모든 업무를 넣지 않기
기존 설계에는 CORS, 대화 이력, 요청·응답 로깅 미들웨어가 있습니다. 대화 이력은 상세 질의에 적용하고, 검색 이력은 별도로 저장합니다. 두 기록은 목적과 실패 처리 기준이 다릅니다.
| 미들웨어 역할 | 적용할 일 | 주의할 일 |
|---|---|---|
| CORS | 허용한 브라우저 출처와 호출 조건 | 인증이나 문서 권한을 대신하지 않음 |
| 요청 추적 | 요청 ID, 소요 시간, 종료 상태 | 본문과 인증 정보를 무조건 기록하지 않음 |
| 대화 기록 | 대상 질의의 대화 결과 기록 | 부분 응답과 완료 답변 구분 |
경로에 특정 문자열이 포함됐는지만 보고 기록 대상을 고르면 범위가 넓어질 수 있습니다. 명확한 라우트나 등록된 기능 단위를 기준으로 대상을 정합니다. 응답 본문을 다시 읽는 구현은 스트리밍을 방해하지 않는지도 확인합니다.
미들웨어의 공통 상태에 요청별 사용자 정보를 보관하지 않습니다. 적용 순서와 상태 관리 원칙은 Starlette 미들웨어 문서를 참고할 수 있습니다. 성공 여부가 업무 실행 결과에 달린 기록은 서비스 계층에서 명시적으로 남기는 방법도 있습니다.
2.7 Agent 서비스와 검색 서비스의 역할 나누기
Agent 서비스는 상담 업무의 순서를 조합합니다. 검색 서비스는 필요한 문서를 가져오는 방법에 집중합니다. 공통 프레임워크는 모델·검색기·DB 연결을 제공하고, 업무 규칙을 대신 결정하지 않습니다.
| 기능 | Agent 서비스 | 검색 서비스 |
|---|---|---|
| 이벤트 검색 | 요청 조건 전달, 응답·기록 정책 | 대표 문서 검색과 첨부 연결 |
| 상세 질문 | 근거 확인, 모델 호출, 답변 상태 | 선택 묶음의 전체 문서 조회 |
| 검색 튜닝 | 업무별 허용 옵션 선택 | 기본값과 요청 옵션 병합 |
| 기간 처리 | 기준 날짜와 업무 의도 전달 | 겹치는 기간 조건 적용 |
| 근거 부족 | 추가 질문·응답 보류 판단 | 빈 결과와 조회 실패 구분 |
검색과 상세 질문은 같은 검색 서비스를 재사용할 수 있습니다. 다만 상세 질문은 선택한 묶음을 ID로 조회하므로 벡터 검색이 필요하지 않을 수 있습니다. ID 조회에서도 권한과 문서 개정은 다시 확인합니다.
비동기 라우터 안에서 동기 DB·모델 호출을 직접 오래 실행하면 다른 요청이 지연될 수 있습니다. 비동기 클라이언트를 사용하거나, 동기 작업을 별도 실행 경계로 분리합니다. 아래 대역은 구조를 설명하려고 비동기 인터페이스를 사용합니다.
2.8 외부 연결 없이 요청 흐름 확인하기
다음 대역은 검색 결과 하나를 반환합니다. 실제 검색이나 DB 저장을 수행하지 않으며, 이력 미저장 상태도 명시합니다. 앞의 앱·라우터 정의와 같은 실행 문맥에서 사용합니다.
|
class FakeContactService: |
|---|
🧪 대역은 HTTP 입력, 서비스 전달, 자원 정리를 확인하는 도구입니다. 검색 품질이나 실제 저장 성공을 검증한 것으로 해석하지 않습니다. 실제 연결 검증은 별도의 시험 환경에서 진행합니다.
2.9 검색 이력과 대화 이력을 따로 저장하는 이유
검색 이력은 어떤 조건으로 어떤 이벤트를 찾았는지 남깁니다. 대화 이력은 선택한 자료로 무엇을 묻고 답했는지 남깁니다. 둘을 연결할 수는 있지만, 같은 저장 규칙을 사용할 필요는 없습니다.
| 저장 대상 | 주요 식별 기준 | 다시 사용할 목적 |
|---|---|---|
| 검색 이력 | 사용자, 검색 ID, 질문·조건 | 검색 결과 스냅샷 확인 |
| 즐겨찾기 | 사용자, 묶음 ID | 관심 이벤트 다시 보기 |
| 최근 본 이벤트 | 사용자, 묶음 ID, 조회 시각 | 최근 상담 자료로 돌아가기 |
| 대화 이력 | 사용자, 세션, 요청 ID | 질문과 답변의 흐름 재구성 |
아래 SQL은 검색 이력 저장과 소유자 범위 조회를 설명하는 샘플입니다. %s는 DB 클라이언트에서 별도의 값으로 바인딩하는 자리입니다. 실제 테이블과 트랜잭션이 준비되어 있다고 가정합니다.
|
INSERT INTO search_history |
|---|
이력 ID는 저장 트랜잭션이 완료된 뒤 응답에 연결합니다. RETURNING으로 ID를 받았다는 사실만으로 커밋이 완료된 것은 아닙니다. 저장 문법과 반환값은 PostgreSQL INSERT 문서를 참고할 수 있습니다.
검색이 성공했지만 이력 저장이 실패할 수 있습니다. 부분 성공을 허용한다면 화면에 저장 상태를 구분해 전달합니다. 필수 감사 기록이라면 저장 실패를 요청 실패로 볼지 별도 정책이 필요합니다.
2.10 즐겨찾기 메타데이터는 소유권 확인 후 보완하기
기존 설계는 검색 이력에서 같은 묶음의 정보를 찾아 저장 요청을 보완합니다. 클라이언트가 모든 문서 정보를 다시 보내지 않아도 되는 장점이 있습니다. 다만 이력 ID를 안다는 이유만으로 다른 사용자의 자료를 가져오면 안 됩니다.

그림 4. 이력의 소유권 확인과 현재 문서 접근 권한 확인은 모두 필요합니다.
기존 병합 순서는 클라이언트 값, 지정 검색 이력, 최근 검색 이력 순입니다. 이 우선순위는 표시용 정보에 한정하는 편이 좋습니다. 문서 ID, 소유자, 접근 범위, 원문 개정은 서버가 확인한 값을 유지합니다.
| 조건 | 보완할 정보 | 반드시 확인할 범위 |
|---|---|---|
| 검색 이력 ID 있음 | 해당 이력의 묶음 스냅샷 | 같은 사용자와 요청 묶음 |
| 이력 ID 없음 | 사용자의 최근 이력에서 찾은 스냅샷 | 조회 개수·기간·현재 권한 |
| 이력에서 찾지 못함 | 현재 문서 조회 또는 명시적 오류 | 오래된 값으로 임의 복원하지 않음 |
| 클라이언트 표시값 있음 | 허용한 제목·메모 같은 필드 | 문서 식별·권한 필드 덮어쓰기 금지 |
다음은 현재 문서 접근 권한을 확인한 뒤 호출하는 병합 예제입니다. 허용한 표시용 필드만 받으며, 이력 소유자와 묶음을 다시 검사합니다. 이 함수만으로 전체 접근 제어가 구현되는 것은 아닙니다.
|
from copy import deepcopy |
|---|
이 예제는 이력에 묶음당 대표 항목 하나가 있다고 가정합니다. 청크별 결과라면 먼저 묶음 단위로 정리해야 합니다. 외부 응답에는 허용된 필드만 포함하고, 내부 설정이나 디버깅 정보는 제외합니다.
즐겨찾기의 중복 방지는 사용자·묶음 조합의 고유 제약으로 뒷받침합니다. 최근 본 기록은 재조회 시 시각을 갱신할지, 새 기록을 만들지 정합니다. 동시 요청과 재시도에서도 같은 정책이 유지되는지 실제 DB에서 확인합니다.
2.11 설정과 프롬프트: 이름보다 의미를 고정하기
Agent 팩터리는 허용한 이름을 서비스 설정에 연결합니다. 공백·대소문자·별칭을 정규화하더라도 알 수 없는 이름을 임의 서비스로 보내지는 않습니다. 설정 누락과 사용자가 요청한 자원 없음도 구분해야 합니다.
기존 설계는 프롬프트 누락을 404로 변환합니다. 운영에서는 잘못된 Agent 이름과 배포 구성 누락을 서로 다른 원인으로 기록하는 편이 좋습니다. 필수 프롬프트는 시작 단계에서 검증하고, 배포 구성 오류가 요청 시점까지 늦춰지지 않도록 합니다.
다음은 업무와 연결 설정을 나눈 샘플입니다. 옵션 이름은 설명용이며 실제 제공자의 지원 범위에 맞게 변환해야 합니다.
|
{ |
|---|
검색 요청에서 변경할 수 있는 옵션도 제한합니다. 검색 개수와 후보 수에는 상한을 두고, 문서 접근 범위를 요청값으로 덮어쓰지 않습니다. 인덱스·저장소 연결은 환경 설정으로 관리하며 변경 이력을 남깁니다.
2.12 장애를 기능별로 바라보기
모델 연결이 실패해도 검색은 계속 제공하고 싶을 수 있습니다. 그러려면 검색 서비스를 만들 때 모델 초기화를 강제하지 않아야 합니다. API만 분리하고 의존성을 함께 초기화하면 장애 영향은 그대로 남습니다. 구조상의 분리와 실제 연결의 분리를 함께 확인해야 합니다.
저장소도 같은 관점으로 봅니다. 이력 저장과 문서 검색이 같은 DB를 사용한다면 장애가 함께 영향을 줄 수 있습니다. 논리적으로 계층을 나눴다고 물리적 장애까지 격리되는 것은 아닙니다. 공유 자원과 필수 의존성을 운영 문서에 명확히 남깁니다.
상태 확인은 프로세스 생존과 요청 처리 준비를 구분합니다. 검색·질의·기록 중 어느 기능을 제공할 수 있는지 확인합니다. 선택 기능이 꺼져 있는데 전체 서비스가 완전한 상태인 것처럼 표시하지 않습니다. 사용자에게 제공할 수 있는 범위를 기준으로 상태를 정합니다.
그림 5. 앱 기동 여부와 기능별 준비 상태를 나누어 봅니다. AI 생성 일러스트입니다.
| 실패 지점 | 예상 영향 | 확인할 정책 |
|---|---|---|
| 모델 초기화·호출 | 상세 답변 불가 | 검색 경로의 독립성 |
| 검색 저장소 | 검색·묶음 조회 제한 | 준비 상태와 오류 안내 |
| 이력 저장 | 다시 보기·대화 보관 제한 | 부분 성공 또는 전체 실패 |
| 선택 기능 미등록 | 해당 기능 사용 불가 | 명시적 비활성 상태 |
| 필수 설정·프롬프트 누락 | 관련 서비스 준비 실패 | 기동 차단과 배포 검증 |
2.13 요청 하나의 실행과 기록을 연결하기
검색, 묶음 조회, 모델 호출, 이력 저장에 같은 요청 ID를 전달합니다. 단계별 시간과 상태를 남기면 어디에서 지연됐는지 확인할 수 있습니다. 사용자 ID나 세션 ID를 로그에 남길 때도 필요한 범위와 보존 정책을 정합니다.
| 관측 항목 | 운영에서 확인할 내용 |
|---|---|
| 요청·추적 ID | API부터 하위 호출까지 연결 |
| 검색·묶음 조회 시간 | 후보 탐색과 첨부 조회의 병목 |
| 모델 시간·종료 상태 | 생성 지연, 제한, 중단 구분 |
| 저장 결과·이력 ID | 검색 성공과 저장 성공 구분 |
| 초기화·연결 풀 상태 | 첫 요청 지연과 자원 부족 |
OpenTelemetry의 트레이스 개념은 단계별 실행을 연결하는 데 참고할 수 있습니다. 추적 기록만으로 감사 체계가 완성되지는 않습니다. 감사 이벤트의 보존·열람·변경 통제는 별도로 설계합니다.
2.14 테스트로 의존성 경계 확인하기
아래 테스트는 앞의 예제를 사용합니다. TestClient, HTTPX, pytest가 필요하며 실제 인증·모델·DB는 호출하지 않습니다. 인증된 주체의 전달과 앱 종료 시 정리를 확인합니다.
|
from fastapi.testclient import TestClient |
|---|
의존성 대체 방식은 FastAPI 테스트 문서를 참고할 수 있습니다. 여기에 초기화 동시 요청, 생성 실패, 다른 사용자의 이력 접근 테스트를 추가합니다. 실제 DB의 트랜잭션과 문서 권한은 통합 테스트로 확인합니다.
3. 결론: 상담 흐름은 연결하고, 변경 이유는 나누기
고객 컨택 Agent는 검색, 답변, 사용자 기록이 함께 움직이는 서비스입니다. 기능을 나누는 목적은 계층 이름을 늘리는 데 있지 않습니다. 사용자 흐름을 유지하면서 변경과 실패의 영향을 파악하기 위해서입니다.
✅ 앱은 자원의 수명을, API는 요청 계약을, 서비스는 업무 순서를 책임집니다. 검색과 저장 계층은 문서·사용자 범위를 지키며 필요한 데이터를 제공합니다. 이 경계가 분명하면 대역 테스트와 실제 연결 검증도 나누기 쉬워집니다.
처음에는 검색부터 즐겨찾기 재조회까지 하나의 흐름을 확인해 볼 수 있습니다. 정상 경로뿐 아니라 권한 변화, 기록 실패, 초기화 오류도 함께 살펴봅니다. 상담사가 다음 행동을 이어갈 수 있는지 확인하는 것이 아키텍처를 검증하는 좋은 기준입니다.
4. 참조 출처
아래 공식 문서를 참고해 앱 수명, 데이터 계약, 저장과 관측의 설명을 보완했습니다. 예제 식별자와 응답은 설명용이며 실제 고객 정보나 운영 측정값이 아닙니다.
- FastAPI — Lifespan Events: 시작·종료 단계와 자원 수명.
- FastAPI — Testing Dependencies: 테스트에서 의존성 대체.
- Starlette — Middleware: 미들웨어 구성과 요청별 상태 관리.
- PostgreSQL — INSERT: 데이터 저장과 반환값.
- Pydantic — Fields: 필드 검증과 기본값 구성.
- OpenTelemetry — Traces: 분산 호출의 실행 추적.
일러스트 세 장은 시리즈의 기존 AI 생성 이미지를 활용했습니다. 흐름도 두 개는 직접 작성했으며 편집 가능한 draw.io 원본을 함께 보관합니다. 실제 상담 화면이나 운영 결과를 촬영한 이미지는 아닙니다.
5. 태그
#상담AI #AIAgent #ServiceArchitecture #FastAPI #RAG #DependencyInjection #ConversationHistory #PostgreSQL #EventHistory #서비스컨테이너 #운영관측