AI 튜토리얼

AI 기반 WeChat 학습 미니 앱 빌드 및 실행

AI 지식 베이스 스마트 학습 미니 앱을 구성하고 실행하는 방법을 알아보세요. FastAPI 백엔드를 Taro 프런트엔드에 연결하고, 서비스를 확인하고, 테스트를 실행한 후, Docker 기반 백엔드를 배포할 수 있도록 준비합니다.

2026년 8월 28일약 10분 소요

빌드할 내용

AI 지식 베이스 스마트 학습 미니 앱은 WeChat 생태계를 위한 지능형 학습 애플리케이션입니다. 학습자는 주제를 입력하거나 비공개 문서를 업로드한 다음, AI 지원 워크플로를 사용해 문제를 생성하고 즉시 해설을 받으며, 숙련도, 취약 영역, 권장 다음 단계를 다루는 보고서를 검토할 수 있습니다.

이 프로젝트는 대규모 언어 모델, 웹 검색, 검색 증강 생성(RAG)을 결합합니다. Tavily는 최신 웹 컨텍스트를 제공하고, Chroma는 업로드된 PDF, Word, Markdown, TXT 파일에서 검색을 지원합니다.

주요 기능

주제 기반 퀴즈 생성: 사용자가 제공한 주제에서 학습 문제를 생성합니다.
웹 검색 보강: Tavily를 사용해 최신 컨텍스트를 추가합니다.
비공개 지식 베이스 학습: PDF, Word, Markdown 또는 TXT 문서를 업로드하고 RAG로 관련 콘텐츠를 검색합니다.
즉시 피드백: 답변을 확인하고 각 응답 후 해설을 제공합니다.
학습 보고서: 숙련도를 분석하고 취약 영역을 파악하며 학습 제안을 제공합니다.
문제 일러스트: 보조 이미지를 생성하고 Tencent Cloud COS에 저장합니다.
WeChat 사용자 지원: 로그인, 학습 기록, 보고서 검토 기능을 제공합니다.
컨테이너 배포: Docker를 통해 WeChat Cloud Run 또는 호환 플랫폼에 백엔드를 배포합니다.

아키텍처 이해하기

미니 앱 프론트엔드는 Taro 4, React 18, TypeScript, Sass를 사용합니다. 백엔드는 Python 3.11에서 FastAPI, Pydantic v2, Uvicorn으로 실행됩니다. LangChain과 LangGraph가 AI 작업을 조정하며, DeepSeek과 Alibaba Bailian이 모델 및 검색 스택에 포함됩니다.

MySQL은 애플리케이션 데이터를 저장하고, Tencent Cloud COS는 생성된 일러스트를 저장하며, Chroma는 벡터 저장소로 작동합니다. 인증에는 WeChat jscode2session과 JWT를 사용합니다. 백엔드 테스트에는 pytest와 pytest-asyncio를 사용합니다.

저장소 구조

.
├── backend/        # FastAPI 백엔드
├── frontend/       # Taro 기반 WeChat 미니 앱 프론트엔드
├── docs/           # 로컬에 보관되는 프로젝트 문서
├── openspec/       # 로컬에 보관되는 사양 파일
└── prototypes/     # 로컬에 보관되는 프로토타입 파일

사전 요구 사항

시작하기 전에 Python 3.11, npm이 포함된 Node.js, WeChat DevTools를 설치하세요. 또한 backend/.env.example에서 요구하는 서비스 인증 정보와 구성 값이 필요합니다. Docker는 백엔드 컨테이너를 빌드하거나 배포할 준비가 되었을 때만 필요합니다.

실제 API 키, 데이터베이스 인증 정보, JWT 비밀 키, 클라우드 스토리지 인증 정보를 버전 관리 시스템에 포함하지 마세요. 운영 환경의 비밀 값은 배포 플랫폼을 통해 주입해야 합니다.

1단계: 백엔드 구성

터미널을 열고 backend 디렉터리로 이동한 다음 격리된 Python 환경을 만드세요. README에는 다음과 같은 PowerShell 중심 설정 방법이 안내되어 있습니다.

cd backend
python -m venv venv
venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env

새로 생성된 .env 파일을 열고 선택한 모델, Tavily 통합, 데이터베이스, 인증, 벡터 검색, Tencent Cloud 스토리지에 필요한 구성을 입력하세요. 필요한 변수의 기준 목록은 backend/.env.example을 사용하세요.

FastAPI 서비스 시작

python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

--reload 옵션은 백엔드 코드가 변경될 때 Uvicorn이 재시작되므로 로컬 개발 중 유용합니다. 0.0.0.0에 바인딩하면 컴퓨터의 네트워크 인터페이스를 통해 개발 서비스에 연결할 수 있습니다.

백엔드 확인

시작한 후 http://localhost:8000/docs에서 대화형 API 문서를 여세요. http://localhost:8000/api/v1/health에서 서비스 상태를 확인할 수도 있습니다.

프론트엔드 문제를 해결하기 전에 상태 확인 엔드포인트를 검증하세요. 사용할 수 없는 경우 가상 환경이 활성화되어 있는지, 종속 항목이 정상적으로 설치되었는지, .env 파일이 존재하는지, 포트 8000이 이미 사용 중이 아닌지 확인하세요.

2단계: WeChat 미니 앱 프론트엔드 빌드

백엔드를 실행한 상태로 두고 두 번째 터미널을 연 다음 프론트엔드 종속 항목을 설치하세요.

cd frontend
npm install
npm run dev:weapp

개발 명령은 Taro 애플리케이션을 WeChat용으로 컴파일합니다. 컴파일이 완료되면 WeChat DevTools를 실행하고 생성된 frontend/dist 디렉터리를 여세요.

개발 중 프론트엔드 변경 사항을 다시 빌드할 수 있도록 컴파일러 터미널을 열어 두세요. 미니 앱이 백엔드 기능에 액세스할 수 있도록 FastAPI 서버도 별도의 터미널에서 계속 실행해야 합니다.

3단계: 학습 워크플로 사용

프론트엔드와 백엔드가 실행되면 이 프로젝트는 두 가지 주요 학습 경로를 지원합니다.

주제에서 퀴즈 생성

WeChat 사용자 흐름을 통해 로그인합니다.
학습하려는 과목을 입력합니다.
해당 주제를 기반으로 AI 지원 문제를 생성합니다.
답변을 제출하고 반환된 정답과 해설을 검토합니다.
학습 세션을 완료한 후 AI 보고서에서 숙련도 분석, 취약점, 권장 사항을 확인합니다.

비공개 문서로 학습

지원되는 PDF, Word, Markdown 또는 TXT 문서를 선택합니다.
애플리케이션의 지식 베이스 워크플로에 업로드합니다.
시스템이 RAG 파이프라인을 통해 관련 문서 컨텍스트를 검색하도록 합니다.
생성된 질문에 답하고 해설을 검토합니다.
결과 보고서를 활용하여 자료 중 추가 학습이 필요한 부분을 판단합니다.

주제 기반 학습에서는 Tavily를 사용하여 최신 웹 컨텍스트를 추가할 수 있습니다. 문서 기반 학습에서는 업로드한 비공개 자료를 기반으로 검색을 수행합니다. 실제로 사용할 수 있는 동작은 백엔드 환경에 구성된 서비스와 자격 증명에 따라 달라집니다.

4단계: 테스트 스위트 실행

backend 디렉터리에서 백엔드 테스트를 실행합니다:

cd backend
pytest

이 프로젝트는 pytest와 pytest-asyncio를 사용합니다. 백엔드를 변경한 후 배포 전에 테스트 스위트를 실행하여 동기 및 비동기 동작의 회귀를 발견합니다.

고급 팁

개발 중 API 문서 사용

FastAPI의 문서 페이지는 실행 중인 프로젝트 버전에서 제공하는 라우트를 확인하는 데 유용합니다. README에 문서화되지 않은 요청 필드나 엔드포인트 경로를 추측하지 말고, API 문서를 기준으로 사용합니다.

개발 환경과 프로덕션 시크릿 분리

로컬 .env 파일은 개발용으로만 사용합니다. 프로덕션에서는 WeChat Cloud Run 또는 선택한 컨테이너 플랫폼을 통해 시크릿을 구성합니다. 값이 입력된 환경 파일을 저장소에 커밋하지 마세요.

적절한 지식 소스 선택

최신성이 중요할 때는 Tavily를 사용하여 주제를 생성합니다. 비공개 자료나 조직별 자료를 기반으로 질문을 생성해야 할 때는 문서 워크플로를 사용합니다. 지원되는 업로드 형식은 PDF, Word, Markdown 및 TXT 파일입니다.

서비스를 단계별로 검증

상태 확인 엔드포인트가 응답하는지 확인합니다.
FastAPI 문서를 확인합니다.
pytest를 실행합니다.
Taro 프런트엔드를 컴파일합니다.
WeChat DevTools에서 frontend/dist를 엽니다.
구성된 외부 서비스를 사용하여 로그인, 퀴즈 생성, 피드백, 기록 및 보고서 검토를 테스트합니다.

이 순서로 진행하면 백엔드 구성 문제와 프런트엔드 컴파일 또는 WeChat 도구 문제를 쉽게 구분할 수 있습니다.

컨테이너 배포 준비

저장소에는 backend/Dockerfile과 backend/.dockerignore가 포함되어 있습니다. 이 파일을 사용하면 백엔드를 WeChat Cloud Run 또는 호환되는 다른 플랫폼용 Docker 컨테이너로 패키징할 수 있습니다.

배포 전에 테스트를 실행하고, 필요한 프로덕션 환경 변수가 플랫폼을 통해 제공되는지 확인하며, 이미지에 시크릿을 포함하지 마세요. MySQL, Tencent Cloud COS, 모델 제공업체, Tavily 및 WeChat 인증과 같은 외부 종속성에 배포 환경에서 연결할 수 있는지 확인합니다.

결론

이 프로젝트는 WeChat에서 AI 지원 학습을 구현하기 위한 완전한 기반을 제공합니다. Taro 및 React 미니 앱, FastAPI 백엔드, 주제 및 문서 기반 퀴즈 생성, 즉각적인 해설, 학습 보고서, 사용자 기록과 컨테이너 배포 기능을 포함합니다. 먼저 백엔드를 검증하고 WeChat DevTools에서 프런트엔드를 컴파일한 다음, 선택한 학습 워크플로에 필요한 외부 서비스를 구성하세요.