FitQuest AI 🌿 — 실제 퀘스트, 더 건강한 당신.

만약 피트니스 앱이 휴대폰 사용 시간이 적을 때 보상을 준다면 어떨까요?

FitQuest AI는 로컬 AI를 사용하여 야외 활동을 작은 퀘스트로 변환하고—사용자가 화면에서 벗어나 실제 세계를 즐기도록 장려합니다.

이것은 Hacktoberfest Open-Source AI Challenge — Week 1: Touch Grass 제출물입니다.

데모: 영상 데모 / 스크린샷 · 코드: GitHub 저장소

제가 만든 것 (What I Built)

_FitQuest AI_는 로컬 오픈 가중치(open-weight) AI 모델로 구동되는 개인 정보 보호에 중점을 둔 게임화된 야외 피트니스 앱입니다. 이 앱은 개발자 및 책상 근무자들이 모니터에서 벗어나 밖에 나가도록 돕기 위해 설계되었습니다.

FitQuest AI는 휴대폰의 끝없는 지표(metrics)에 집중하는 대신, 산책, 달리기, 하이킹, 사이클링 활동을 작은 RPG 스타일의 퀘스트로 변환합니다. 퀘스트를 생성하고 야외로 나간 다음, 돌아와 활동을 기록하고, 경험치(XP)를 얻고, 업적을 잠금 해제하며—'Touch Grass' 마일스톤을 포함하여—친구들과 진행 상황을 공유할 수 있습니다.

주요 기능 (Key Features)

• 🌿 AI 퀘스트 생성기 (AI Quest Generator): 피트니스 목표, 경험 수준 및 최근 활동에 맞춰 구조화된 야외 챌린지를 생성합니다.
• 💬 대화형 AI 코치 (Interactive AI Coach): 페이스 조절, 회복, 일관성 있는 습관 형성 등에 대한 대화식 가이드를 제공합니다.
• 🏆 게임화된 진행 (Gamified Progression): XP를 얻고, 레벨을 올리고, 스트릭(streaks)을 추적하며, 퀘스트를 완료하고, 마일스톤 업적을 잠금 해제합니다.
• 📸 트레일 사진 및 스토리 카드 (Trail Photos & Story Cards): 운동에 야외 사진을 추가하고 WhatsApp, Instagram, X와 같은 플랫폼에서 공유 가능한 스토리 카드를 만듭니다.
• 🔒 로컬 AI 추론 (Local AI Inference): 핵심 생성 워크플로우를 위해 호스팅되는 AI 추론 API에 의존하는 것을 피하며 Ollama와 qwen2.5:3b를 사용합니다.

FitQuest AI가 다른 점은 무엇인가?

대부분의 피트니스 앱은 사용자가 화면을 더 오래 보도록 장려합니다. FitQuest AI는 정반대의 접근 방식을 취합니다. 즉, AI를 사용하여 다음 야외 모험을 계획하고, 휴대폰을 치워 경험하러 나가는 것입니다.

• 목적 지향적인 AI: 일반적인 피트니스 조언 대신 구조화되고 실행 가능한 퀘스트를 생성합니다.
• 압박 없는 성장: XP(경험치), 레벨, 연속 기록(streaks), 그리고 업적(achievements)이 꾸준함을 보상으로 만듭니다.
• 설계 단계부터 사생활 보호 고려: 로컬 추론(Local inference)은 운동 상황 정보가 제3자 클라우드 AI 추론 서비스에 노출되는 것을 방지하는 데 도움이 됩니다.
• 탐험을 위해 구축됨: 걷기, 달리기, 사이클링, 하이킹이 할 일 목록의 또 다른 과제가 아니라 작은 모험이 됩니다.

시연(Demo)

• 비디오 시연 / 스크린샷: 시연 영상 보기
• 소스 코드: GitHub — FitQuest

팁: 대시보드 스크린샷과 예시 AI 생성 퀘스트를 여기에 추가하면 좋습니다. 독자들이 비디오를 보기 전에 경험을 빠르게 이해하는 데 도움이 됩니다.

기술 스택(Tech Stack)

구축 과정

1. 로컬 추론 엔진 (Local inference engine)

호스팅되는 AI 추론 API에 의존하기보다는, 백엔드가 Ollama를 통해 오픈 가중치 모델(qwen2.5:3b)에 연결됩니다. Pydantic은 생성된 구조화된 데이터가 애플리케이션에서 사용되기 전에 유효성을 검사하여 AI 출력을 예측 가능하게 유지하는 데 도움을 줍니다.

2. 상황 인식 코칭 (Context-aware coaching)

코치는 운동 상황, 탐험가 진행 상황(explorer progress), 그리고 인지된 노력(perceived-effort) 정보를 사용하여 응답을 더 관련성 있게 만들 수 있습니다. 채팅 기록은 SQLite에 저장되어 애플리케이션이 대화 맥락을 로컬에서 유지할 수 있도록 합니다.

3. 결정론적 게임화 (Deterministic gamification)

언어 모델은 퀘스트 콘텐츠를 생성하지만, 경험치(XP) 보상, 퀘스트 완료 여부, 레벨, 연속 기록(streaks), 업적과 같은 중요한 게임 규칙은 백엔드 로직이 처리합니다. 이렇게 함으로써 진행 상황을 모델에 결정하게 하는 대신 일관성을 유지할 수 있습니다.

4. 클라이언트 측 스토리 카드

도전 과제 및 배운 점 (Challenges & Learnings)

FitQuest AI를 구축하는 과정은 단순히 언어 모델을 피트니스 앱에 연결하는 것 이상이었습니다.

• 구조화된 AI 출력: LLM 응답은 일관성이 떨어질 수 있으므로, Pydantic 유효성 검사(validation)를 사용하여 생성된 퀘스트 데이터를 타입이 지정되고 예측 가능한 객체로 변환했습니다.
• AI 로컬 실행: Ollama와 경량 모델을 통합하여 전용 GPU 없이도 적절한 하드웨어에서 로컬 추론(inference)을 실용적으로 만들었지만, 성능은 기기에 따라 달라집니다.
• 신뢰할 수 있는 게이미피케이션: XP 보상과 퀘스트 진행 상황은 LLM에 맡기지 않고 결정론적 백엔드 로직이 처리합니다.
• 풀스택 통합: FastAPI 백엔드와 SQLite 데이터베이스를 React 프론트엔드에 연결하여 AI가 생성한 퀘스트와 피트니스 진행 상황을 하나의 애플리케이션으로 구현했습니다.

가장 큰 교훈은 AI 애플리케이션이 좋은 프롬프트 이상의 것이 필요하다는 것입니다. 즉, 유효성 검사(validation), 예측 가능한 비즈니스 로직, 그리고 AI를 진정으로 유용하게 만드는 사용자 경험이 필요합니다.

로컬에서 실행하기 (Run It Locally)

프로젝트는 로컬 Ollama 모델을 사용하므로, 첫 설정 단계에서 해당 모델을 다운로드해야 합니다. 아래 명령어들은 시작점이며, 최신 프로젝트별 설정 지침은 레포지토리를 확인해 주세요.

사전 준비 사항 (Prerequisites)

• Python 3.12 또는 호환되는 Python 버전
• Node.js 및 npm
• Ollama
• Git

1. 레포지토리 클론하기 (Clone the repository)

git clone https://github.com/neerajsbhandari27/FitQuest.git
cd FitQuest

2. AI 모델 다운로드하기 (Download the AI model)

olllama pull qwen2.5:3b

AI 기반 기능을 테스트하기 전에 Ollama가 실행 중인지 확인해 주세요.

3. 백엔드 시작하기 (Start the backend)

레포지토리의 백엔드 설정 지침을 따르세요. 일반적인 FastAPI 워크플로우는 다음과 같습니다:

cd backend
python -m venv .venv
source .venv/bin/activate
...

만약 레포지토리가 다른 의존성 파일이나 시작 명령어를 사용한다면, 현재의 지침을 따르세요.

4. 프론트엔드 시작하기 (Start the frontend)

두 번째 터미널에서, 레포지토리에 표시된 프론트엔드 디렉토리 이름을 사용하세요. Vite 앱의 경우, 일반적으로 다음과 같은 명령어를 사용합니다:

cd Frontend
npm install
npm run dev

Vite가 터미널에 출력하는 로컬 URL을 열어주세요. 정확한 API URL 구성 및 추가 설정은 레포지토리의 README를 확인해 주세요.

Open Innovation이 중요한 이유 (Why Does Open Innovation Matter?)

Open-source AI는 FitQuest AI에게 세 가지 이유로 중요합니다:

1. 개인 데이터 프라이버시: 운동 기록, 자각된 노력(perceived exertion), 활동 이력 등은 민감할 수 있습니다. 로컬 추론(Local inference)을 사용하면 이러한 컨텍스트가 제3자 클라우드 AI 서비스에 노출되는 것을 막을 수 있습니다.
2. 낮은 지속적인 추론 비용 (Lower ongoing inference costs): 로컬 모델을 실행하는 것은 요청당 호스팅된 AI 추론 요금(per-request hosted AI inference charges)을 피할 수 있게 합니다. 다만, 초기 다운로드를 위한 하드웨어, 전기, 인터넷 접속 비용은 여전히 발생할 수 있습니다.
3. 더 많은 제어권 (More control): 개발자는 자신의 장치에서 AI 워크플로우를 검사하고, 조정하며, 실행할 수 있습니다. 앱이 해당 워크플로우에 대해 외부 서비스에 의존하지 않는다면, 필요한 의존성과 모델 파일만 설치되어 있으면 인터넷 연결 없이도 핵심 로컬 기능이 작동할 수 있습니다.

오픈 혁신(Open innovation)은 AI가 우리가 디지털 피드에 갇히도록 만들 필요가 없다는 것을 증명합니다. 오히려 연결을 끊고 풀밭에 발을 디디는 데 도움을 주는 부드러운 자극제가 될 수 있습니다.

다음 계획 (What's Next)?

FitQuest AI는 지속적으로 발전하는 프로젝트입니다. 잠재적인 다음 단계에는 다음과 같은 것들이 포함됩니다:

• 더 스마트한 개인화: 활동 기록, 난이도 선호도, 그리고 시간에 따른 일관성을 사용하여 퀘스트를 조정합니다.
• 풍부해진 야외 모험: 테마별 퀘스트 체인, 탐험 마일스톤, 다일(multi-day) 챌린지를 추가합니다.
• 개선된 진행 상황 공유: 친구들과 성취를 축하할 수 있도록 사용자 정의 가능한 스토리 카드를 확장합니다.
• 커뮤니티 기여: 버그 보고서, 문서 개선, UI 향상, 새로운 기능 아이디어를 환영합니다.

기여 (Contributing)

팀: @mukesh_kumar_18d186c6e486와 협력하여 구축되었습니다.

FitQuest AI는 MIT 라이선스 하에 오픈 소스로 공개되어 있습니다. GitHub 저장소를 탐색하고, 로컬에서 사용해 보고, 피드백이나 아이디어를 공유해 주세요. 제출하기 전에 저장소의 기여 지침과 기존 이슈들을 확인하세요.

마지막 생각 (Final Thought)

기술은 우리가 더 잘 살도록 도와야 하며, 단지 온라인에 더 오래 머물게 하는 수단이 되어서는 안 됩니다. FitQuest AI는 약간의 AI 생성 동기 부여를 밖에 나가서 움직이고, 탐험하고, 풀밭에 발을 디딜 이유로 바꿉니다. 🌱