AI 서비스 초기 구성

[VitoJeong]

개요

AI 서비스의 기반이 되는 외부 LLM 연동(Gemini/GPT) 환경과 공통 예외 체계를 구축했습니다.

구현 항목

작업내용 상세 문서는 on-seoul-agent/docs/ai-service-implementation.md를 참고해주세요.

프로젝트 초기 구성 및 인프라

• FastAPI 기반 앱 엔진: 비동기 핸들러 및 SSE 스트리밍 응답 구조 준비
• 설정 관리: pydantic-settings 기반 환경 변수 관리
• DB 연동: SQLAlchemy async 엔진 및 세션 팩토리 구성
• 로깅: 서비스 레이어 및 에이전트 실행 추적을 위한 정형 로깅 설정

데이터 스키마 및 DB 설계 (Phase 2)

• 메시지 중심 설계: room_id/message_id 기반 요청/응답 모델 정의
• 상태 관리: LangGraph 노드 간 문맥 공유를 위한 AgentState 정의(LangChain에서는 미사용)
• 에이전트 트레이스: 실행 메타데이터 저장을 위한 chat_agent_traces JSONB 모델링
• DDL 작성: on_ai DB 전용 테이블(service_embeddings, chat_agent_traces) 및 pgvector 확장 적용

LLM 클라이언트 및 유틸리티 (Phase 3)

• LLM 연동 추상화: llm_provider 설정에 따라 Gemini(Google)와 GPT(OpenAI)를 동적으로 전환하는 get_chat_model 구현
• 임베딩 최적화: Google Generative AI 기반 1536차원 벡터 생성
• 공통 예외 체계:
  • LLMException: API 호출 및 쿼터 제한 오류 처리
  • DatabaseException: DB 세션 및 쿼리 오류 처리
  • ConfigurationException: 설정 누락 및 공급자 미지원 오류 처리

테스트 및 검증

• 외부 API 연동 테스트: pytest 를 사용하여 실제 LLM API 호출 검증
• Mock 테스트: 단위 테스트를 통한 Generator 및 Embedder 로직 검증 완료

[f-lab-ted]

docs, on-seoul-agent (python) 파트에 대한 리뷰입니다.

[f-lab-ted]

[Major] architecture.md에서 SecurityConfig.java를 "Spring Security 설정 (세션 기반)"으로, SessionAuthFilter.java를 "요청마다 세션 검증"으로 기술하고 있으나, docs/schemas/auth-design.md에서는 JWT 기반 인증(Access Token은 클라이언트 저장, 서버 상태 없음)으로 설계되어 있습니다.

두 문서의 인증 전략이 상충합니다:

• architecture.md → 세션 기반
• auth-design.md → JWT 기반 (Stateless Access Token + Redis Refresh Token)

JWT 설계를 채택한 것이라면 architecture.md의 SessionAuthFilter → JwtAuthFilter, "세션 기반" → "JWT 기반"으로 업데이트가 필요합니다. 설계 문서 간 불일치는 이후 구현 시 혼란을 야기할 수 있습니다.

[VitoJeong]

해당 피드백은 인증 관련 브랜치에서 처리해두었습니다.
커밋 링크

[f-lab-ted]

[Major] datetime.now()는 timezone-naive한 datetime을 생성하지만, DDL(ddl_chat_entities.sql)에서 created_at을 TIMESTAMPTZ(timezone-aware)로 정의하고 있습니다. timezone 불일치는 시간 기반 조회/정렬에서 예측 불가능한 결과를 초래할 수 있습니다.

datetime.now(tz=timezone.utc) 또는 datetime.now(tz=UTC)를 사용하세요:

from datetime import datetime, timezone

created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))

[VitoJeong]

해당 피드백 반영해두었습니다.
별개로 API 서비스에서는 TIMESTAMP 타입을 사용하여, 타입이 혼재된 상태로 있어 통일하는 작업해두겠습니다!

[f-lab-ted]

[Minor] logging.basicConfig는 root logger를 직접 설정하므로, uvicorn·SQLAlchemy·httpx 등 서드파티 라이브러리의 로그 레벨까지 함께 변경됩니다. PR 설명에서 언급한 "정형 로깅"과도 거리가 있습니다.

서비스 전용 logger를 설정하는 것이 더 적합합니다:

def setup_logging() -> None:
    logger = logging.getLogger("on_seoul_agent")
    logger.setLevel(getattr(logging, settings.log_level.upper(), logging.INFO))
    handler = logging.StreamHandler()
    handler.setFormatter(
        logging.Formatter("%(asctime)s %(levelname)s %(name)s %(message)s")
    )
    logger.addHandler(handler)

[VitoJeong]

해당 피드백 반영하였습니다.

[f-lab-ted]

[Minor] from typing import Any, Optional 후 Optional[Any]를 사용하고 있으나, 같은 프로젝트의 다른 파일들(config.py, state.py, chat.py 등)은 모두 str | None 형태의 modern union syntax를 사용합니다. 코드베이스 일관성을 위해 Optional[Any] → Any | None으로 통일하세요.

def __init__(self, message: str, detail: Any | None = None):

[VitoJeong]

해당 피드백 반영하였습니다!

[f-lab-ted]

[Suggestion] google_api_key와 openai_api_key가 None이어도 앱이 정상 기동되지만, 실제 LLM 호출 시(get_chat_model)에 None이 그대로 API 클라이언트에 전달되어 모호한 에러가 발생합니다.

get_chat_model() 내부에서 선택된 provider의 키가 없으면 ConfigurationException을 명시적으로 발생시키는 가드를 추가하면 디버깅이 수월해집니다:

if selected_provider in ("gemini", "google"):
    if not settings.google_api_key:
        raise ConfigurationException("GOOGLE_API_KEY is required for Gemini provider")
    ...

[VitoJeong]

해당 피드백 반영하였습니다. 그 외 다른 설정값 누락에도 적용하여 테스트코드 추가하였습니다.

[f-lab-ted]

on-seoul-api 리뷰 입니다.

[f-lab-ted]

[Bug] @Builder 생성자에 apiServicePath 파라미터가 누락되어 있습니다.

apiServicePath는 @Column(nullable = false)로 선언되어 있으므로, Builder를 통해 엔티티를 생성하면 해당 필드가 null인 채로 persist되어 DB 제약조건 위반(NOT NULL constraint)이 발생합니다.

@Builder
public ApiSourceCatalog(String datasetId, String datasetName, String datasetUrl,
                        String apiServicePath, boolean active, String tags) {
    this.datasetId = datasetId;
    this.datasetName = datasetName;
    this.datasetUrl = datasetUrl;
    this.apiServicePath = apiServicePath;
    this.active = active;
    this.tags = tags;
}

[f-lab-ted]

[Operational] key 필드에 유효성 검증이 없습니다.

API 키가 설정되지 않으면(null) WebClient가 경로에 null을 포함한 요청을 보내게 되어, 의미 없는 4xx 응답과 함께 디버깅이 어려운 오류가 발생합니다.

@jakarta.validation.constraints.NotBlank 어노테이션을 추가하고, @Validated와 함께 사용하면 애플리케이션 기동 시점에 설정 누락을 조기 감지할 수 있습니다.

@NotBlank(message = "seoul.api.key 설정이 필요합니다")
private String key;

[VitoJeong]

아래 커밋에 피드백 반영했습니다.
커밋 링크

[f-lab-ted]

[Suggestion] fetchAll() 내부에서 result가 불필요하게 두 번 생성됩니다.

List<PublicServiceRow> result = new ArrayList<>();  // 첫 번째 생성

if (totalCount == 0 || firstPage.getRows().isEmpty()) {
    return result;
}

result = new ArrayList<>(totalCount);  // 두 번째 생성 (첫 번째는 즉시 GC 대상)

result 선언을 early return 이후로 옮기면 불필요한 객체 생성을 피할 수 있습니다.

if (totalCount == 0 || firstPage.getRows().isEmpty()) {
    return List.of();
}

List<PublicServiceRow> result = new ArrayList<>(totalCount);
result.addAll(firstPage.getRows());

[VitoJeong]

아래 커밋에 피드백 반영했습니다.
커밋 링크