FastAPI, Next.js, RAG를 활용한 AI 기반 Python 학습 플랫폼 구축

AI 기반 애플리케이션을 만드는 것은 LLM API에 연결된 채팅 인터페이스만 있으면 비교적 쉽습니다.

하지만 그러한 AI를 중심으로 완전한 학습 플랫폼을 구축하는 것은 또 다른 도전 과제입니다.

저는 구조화된 커리큘럼, 실습 프로그래밍 연습, 개인 맞춤형 학습, 그리고 AI 튜터를 하나의 풀스택 시스템으로 결합하는 방법을 탐구하고 싶었습니다.

이것이 바로 AI Python Mentor가 시작된 계기입니다.

본 글에서는 프로젝트의 아키텍처, 기술 선택, AI 통합 방식, 그리고 엔지니어링 과정에서 겪었던 몇 가지 어려움에 대해 설명하겠습니다.

GitHub: https://github.com/coffee1337/ai-python-mentor

아이디어

AI Python Mentor는 사용자가 Python과 백엔드 개발을 학습할 수 있도록 설계된 풀스택 플랫폼입니다.

단순히 AI가 생성한 설명만 제공하는 것이 아니라, 이 애플리케이션은 여러 가지 학습 메커니즘을 결합합니다:

• Python 및 백엔드 개념을 다루는 구조화된 커리큘럼
• 프로그래밍 연습 및 지식 점검
• 강의 맥락에 접근할 수 있는 AI 튜터
• 개인 맞춤형 학습 로드맵
• 진도 추적 및 간격 반복(spaced repetition)
• 경력 중심 기술 격차 분석
• 실용적인 포트폴리오 프로젝트

목표는 AI가 구조화된 학습을 대체하는 것이 아니라 지원하는 환경을 구축하는 것입니다.

기술 스택

이 애플리케이션은 다음 기술들을 사용합니다:

백엔드

• Python 3.12
• FastAPI
• PostgreSQL
• SQLAlchemy 및 Alembic
• Pydantic
• AsyncIO

프론트엔드

• Next.js 15
• React 19
• TypeScript

AI

• LLM Gateway
• 검색 증강 생성(Retrieval-Augmented Generation, RAG)
• 강의 기반 지식 인덱싱
• 토큰 사용량 및 비용 회계

인프라스트럭처

• Docker 및 Docker Compose
• GitHub Actions
• 백그라운드 워커
• 데이터베이스 마이그레이션

저는 FastAPI가 비동기 API 개발, 명시적 유효성 검사(validation), 모듈식 백엔드 설계를 위한 견고한 기반을 제공하기 때문에 이를 선택했습니다.

PostgreSQL은 관계형 데이터를 처리하며, SQLAlchemy와 Alembic은 데이터베이스 접근 및 스키마 변경을 관리합니다.

시스템 아키텍처

이 애플리케이션은 모듈식 모놀리스(modular monolith) 방식을 따릅니다.

핵심 API는 인증, 학습 진행 상황, 레슨, 연습 문제, 통합 기능을 담당합니다.

특정 작업들은 별도의 프로세스가 처리할 수 있습니다.

                    Browser
                       |
                       v
...

저의 아키텍처 목표 중 하나는 핵심 학습 기능이 외부 AI 서비스의 가용성에 의존하지 않도록 유지하는 것이었습니다.

예를 들어, AI Gateway가 사용 불가능하더라도 사용자는 여전히 레슨 및 기타 비(非)AI 기능을 이용할 수 있어야 합니다.

이러한 분리는 애플리케이션을 유지보수하고 발전시키기 더 쉽게 만듭니다.

RAG를 활용한 AI 튜터 구축

범용 LLM은 Python 개념을 설명할 수 있지만, 학생이 현재 어떤 레슨을 공부하고 있는지 또는 자료의 어느 버전이 게시되었는지 자동으로 알지 못합니다.

여기서 검색 증강 생성(Retrieval-Augmented Generation, RAG)이 유용해집니다.

AI Python Mentor는 게시된 레슨 콘텐츠의 불변 스냅샷으로 구축된 로컬 지식 인덱스를 사용합니다.

기본 흐름은 다음과 같습니다:

Student asks a question
          |
          v
...

학습 자료에서 컨텍스트를 검색함으로써, AI 튜터는 학생이 실제로 공부하고 있는 콘텐츠에 근거하여 설명을 할 수 있습니다.

이는 기술적으로 정확한 답변이라 하더라도 학습자의 현재 수준에는 부적절할 수 있는 교육용 애플리케이션의 경우 특히 중요합니다.

플랫폼은 또한 AI 사용량과 비용을 추적합니다.

유료 LLM API에 의존하는 제품을 구축할 때 중요한 고려 사항입니다.

Python 코드 실행 처리

또 다른 과제는 실습 프로그래밍 연습 문제를 지원하는 것입니다.

사용자는 간단한 계약(contract)을 따라 Python 솔루션을 제출합니다:

def solve(payload):
    # User implementation
    ...

연습 문제는 공개 예제와 숨겨진 테스트를 정의할 수 있으며, 플랫폼은 제출물과 시도 기록을 저장합니다.

하지만, 신뢰할 수 없는 Python 코드를 메인 API 내부에서 직접 실행하는 것은 심각한 보안 위험을 초래합니다.

이러한 이유로 시스템은 실행 디스패칭(execution dispatching)을 주 애플리케이션과 분리하고 전용 Python Runner 아키텍처를 정의했습니다.

프로덕션 실행 모델은 컨테이너 또는 샌드박스 경계를 포함하여 격리와 리소스 제한을 중심으로 설계되었습니다.

중요: 신뢰할 수 없는 코드 실행은 기본적으로 비활성화되어 있습니다. 프로덕션 Runner는 여전히 적절한 격리 배포 및 보안 구성이 필요합니다.

핵심 설계 결정은 간단합니다: 메인 웹 API가 임의 사용자 코드를 위한 실행 환경이 되어서는 안 됩니다.

인증 및 보안 (Authentication and Security)

백엔드에는 여러 계정 보안 기능이 포함되어 있습니다:

• 쿠키 기반 세션(Cookie-based sessions)
• Argon2 비밀번호 해싱(password hashing)
• CSRF 보호(protection)
• 이메일 확인 및 비밀번호 복구
• 세션 취소(Session revocation)
• 계정 내보내기 및 삭제(Account export and deletion)
• 관리자 감사 로깅(Administrative audit logging)

이러한 기능들은 실제 애플리케이션이 작동하는 로그인 엔드포인트 이상의 것을 필요로 하기 때문에 중요합니다.

프로덕션 배포의 경우, 안전한 쿠키와 HTTPS도 필수적입니다.

백그라운드 처리 (Background Processing)

모든 작업이 HTTP 요청 내부에서 직접 실행될 필요는 없습니다.

아키텍처에는 알림 및 실행 디스패칭과 같은 워크로드를 위한 백그라운드 처리가 포함되어 있습니다.

이러한 워크로드들을 분리하는 것은 요청 처리의 응답성을 유지하는 데 도움이 되며, 더 오래 실행되는 작업을 관리하기 쉽게 만듭니다.

테스트 및 CI (Testing and CI)

저장소에는 백엔드 기능, 데이터베이스 마이그레이션(database migrations), 프론트엔드 빌드, 워커 로직, 브라우저 흐름에 대한 자동화된 검사가 포함되어 있습니다.

GitHub Actions는 이러한 영역 전반에 걸쳐 변경 사항을 검증하는 데 도움을 줍니다.

또한 모든 로컬 워크플로우에 Docker가 필요하지 않은 네이티브 Windows 개발 지원도 추가했습니다.

이는 개발 환경의 접근성을 높이는 동시에 Docker 기반 배포 옵션을 유지할 수 있게 했기 때문에 유용했습니다.

현재 상태 (Current Status)

AI Python Mentor는 현재 활발하게 개발 중입니다.

핵심 학습 플랫폼, 백엔드, AI 통합, 데이터베이스 계층, CI 인프라가 구현되었습니다.

현재 작업은 제품 다듬기(polish), 학습 콘텐츠 품질 개선, AI 평가, 그리고 프로덕션 배포에 초점을 맞추고 있습니다.

이 점에 대해 투명하게 말씀드리자면, 프로덕션 지향적인 아키텍처를 갖췄다고 해서 계획된 모든 프로덕션 구성 요소가 이미 배포되었다는 의미는 아닙니다.

제가 배운 것들

이 프로젝트를 통해 여러 엔지니어링 교훈을 얻었습니다:

1. AI는 전체 아키텍처가 아닌, 하나의 구성 요소여야 합니다.

유용한 AI 제품은 여전히 신뢰할 수 있는 인증(authentication), 데이터 모델, 애플리케이션 로직, 그리고 운영 안전장치(operational safeguards)를 필요로 합니다.

2. 구조화된 컨텍스트가 중요합니다.

RAG는 답변이 특정하고 버전 관리되는 학습 자료를 반영해야 할 때 특히 유용합니다.

3. 보안 경계는 초기에 설계되어야 합니다.

특히 애플리케이션이 사용자로부터 실행 가능한 코드를 수락하는 경우에 중요합니다.

4. 운영상의 고려 사항은 제품 기능입니다.

사용량 할당(Usage quotas), 비용 추적, 백그라운드 작업(background jobs), 그리고 테스트 모두 AI 애플리케이션의 장기적인 생존 가능성에 기여합니다.

다음 계획은 무엇인가요?

저의 다음 우선순위에는 AI 평가 개선, 사용자 경험 다듬기, 교육 콘텐츠 정제, 그리고 프로덕션 배포를 위한 인프라 준비가 포함됩니다.

코드와 아키텍처는 여기서 확인하실 수 있습니다:

GitHub: https://github.com/coffee1337/ai-python-mentor

포트폴리오: https://coffee1337.github.io

또한 Python 백엔드, FastAPI, AI/LLM 통합, RAG 시스템, 그리고 SaaS MVP 개발과 관련된 프리랜서 및 계약 프로젝트에도 열려 있습니다.

비슷한 것을 구축하고 계시다면 언제든지 연락 주십시오!

태그: #python #ai #fastapi #webdev