Skip to content

SETUP_GUIDE.md

Latest commit

 

History

History
398 lines (299 loc) · 8 KB

SETUP_GUIDE.md

File metadata and controls

398 lines (299 loc) · 8 KB

Vision Contact - 설치 및 실행 가이드

시각장애인을 위한 AI 기반 보행 보조 시스템

목차

  1. 사전 준비사항
  2. 백엔드 설정
  3. 프론트엔드 설정
  4. 실행 방법
  5. 문제 해결

사전 준비사항

필수 설치 프로그램

1. Python 3.11 이상

# macOS (Homebrew 사용)
brew install python@3.11

# Windows
# https://www.python.org/downloads/ 에서 다운로드

# 설치 확인
python3 --version

2. Node.js 20.19.0 이상 또는 22.12.0 이상

# macOS (Homebrew 사용)
brew install node

# Windows
# https://nodejs.org/ 에서 LTS 버전 다운로드

# 설치 확인
node --version
npm --version

백엔드 설정

1. 프로젝트 디렉토리로 이동

cd version_2/backend

2. Python 가상환경 생성 및 활성화

# 가상환경 생성
python3 -m venv venv

# 가상환경 활성화
# macOS/Linux
source venv/bin/activate

# Windows (PowerShell)
.\venv\Scripts\Activate.ps1

# Windows (CMD)
.\venv\Scripts\activate.bat

가상환경이 활성화되면 터미널 프롬프트에 (venv)가 표시됩니다.

3. 의존성 패키지 설치

pip install --upgrade pip
pip install -r requirements.txt

설치되는 주요 패키지:

  • FastAPI: 웹 API 프레임워크
  • OpenAI: GPT-4o, Whisper, TTS API
  • Ultralytics: YOLOv8 객체 탐지
  • OpenCV: 이미지 처리
  • SQLAlchemy: 데이터베이스 ORM

4. 환경변수 설정

.env 파일이 이미 존재하지만, 새로 만들려면:

# .env 파일 생성
touch .env

.env 파일 내용 (API 키는 본인의 키로 교체):

# OpenAI API Key (필수)
OPENAI_API_KEY=your_openai_api_key_here

# Database
DATABASE_URL=sqlite+aiosqlite:///./vision_contact.db

# Kakao API Key (선택)
KAKAO_REST_API_KEY=your_kakao_key_here

# T map API (SK Open API) (선택)
TMAP_APP_KEY=your_tmap_key_here

# Naver News API (선택)
NAVER_CLIENT_ID=your_naver_client_id
NAVER_CLIENT_SECRET=your_naver_client_secret

# OpenWeather API (선택)
OPENWEATHER_API_KEY=your_openweather_key_here

API 키 발급 :

5. YOLO 모델 파일 확인

# YOLO 모델 파일 위치 확인
ls ../../instructions/YOLO_model/model_file/yolov8n.pt

모델 파일이 없으면 자동으로 다운로드됩니다.

프론트엔드 설정

1. 프론트엔드 디렉토리로 이동

cd ../frontend/vision-contact-app

2. 의존성 패키지 설치

npm install

설치되는 주요 패키지:

  • Vue 3: 프론트엔드 프레임워크
  • Vite: 빌드 도구
  • TypeScript: 타입 안정성
  • Axios: HTTP 클라이언트
  • Pinia: 상태 관리

실행 방법

방법 1: 터미널 2개 사용 (권장)

터미널 1 - 백엔드 실행

cd version_2/backend

# 가상환경 활성화
source venv/bin/activate  # macOS/Linux
# 또는
.\venv\Scripts\Activate.ps1  # Windows

# 서버 실행
python run.py

백엔드 실행 확인:

터미널 2 - 프론트엔드 실행

cd version_2/frontend/vision-contact-app

# 개발 서버 실행
npm run dev

프론트엔드 실행 확인:

  • 개발 서버 주소: http://localhost:5173 (또는 터미널에 표시된 주소)
  • 브라우저에서 자동으로 열림

방법 2: 백그라운드 실행

macOS/Linux

# 백엔드 백그라운드 실행
cd version_2/backend
source venv/bin/activate
nohup python run.py > backend.log 2>&1 &

# 프론트엔드 실행
cd ../frontend/vision-contact-app
npm run dev

Windows (PowerShell)

# 백엔드 백그라운드 실행
cd version_2\backend
.\venv\Scripts\Activate.ps1
Start-Process python -ArgumentList "run.py" -NoNewWindow

# 프론트엔드 실행
cd ..\frontend\vision-contact-app
npm run dev

접속 및 테스트

1. 브라우저 접속

http://localhost:5173

2. API 테스트 (선택)

FastAPI Swagger UI를 통해 API를 직접 테스트할 수 있습니다:

http://localhost:8000/docs

3. 기능 확인

  • 홈 화면: 모드 선택 (어린이, 시각장애, 차량)
  • 안전모드: 실시간 객체 탐지 및 표지판 분석
  • 음성 명령: 마이크 버튼으로 경로 안내, 날씨, 뉴스 조회
  • 번역 모드: 실시간 음성 번역
  • 레포트: 사용 기록 조회

문제 해결

백엔드 문제

1. ModuleNotFoundError 에러

# 가상환경이 활성화되었는지 확인
which python  # macOS/Linux
where python  # Windows

# 의존성 재설치
pip install -r requirements.txt

2. OPENAI_API_KEY 에러

# .env 파일 확인
cat .env  # macOS/Linux
type .env  # Windows

# API 키가 올바르게 설정되었는지 확인

3. 포트 8000이 이미 사용 중

# macOS/Linux
lsof -ti:8000 | xargs kill -9

# Windows (PowerShell)
Get-Process -Id (Get-NetTCPConnection -LocalPort 8000).OwningProcess | Stop-Process

4. YOLO 모델 로드 실패

# ultralytics 재설치
pip uninstall ultralytics
pip install ultralytics>=8.0.0

# 모델 수동 다운로드
python -c "from ultralytics import YOLO; YOLO('yolov8n.pt')"

프론트엔드 문제

1. npm install 실패

# npm 캐시 삭제
npm cache clean --force

# node_modules 삭제 후 재설치
rm -rf node_modules package-lock.json  # macOS/Linux
rmdir /s node_modules & del package-lock.json  # Windows
npm install

2. Node.js 버전 문제

# Node.js 버전 확인 (20.19.0 이상 또는 22.12.0 이상 필요)
node --version

# nvm으로 버전 변경 (nvm이 설치되어 있다면)
nvm install 20
nvm use 20

3. 포트 5173이 이미 사용 중

# macOS/Linux
lsof -ti:5173 | xargs kill -9

# Windows (PowerShell)
Get-Process -Id (Get-NetTCPConnection -LocalPort 5173).OwningProcess | Stop-Process

4. CORS 에러

백엔드 서버가 실행 중인지 확인:

curl http://localhost:8000/docs

공통 문제

1. 카메라 접근 거부

  • 브라우저 설정에서 카메라 권한 허용
  • Chrome: 설정 > 개인정보 및 보안 > 사이트 설정 > 카메라
  • Safari: 환경설정 > 웹사이트 > 카메라

2. 마이크 접근 거부

  • 브라우저 설정에서 마이크 권한 허용
  • Chrome: 설정 > 개인정보 및 보안 > 사이트 설정 > 마이크

개발 환경 종료

백엔드 종료

# 터미널에서 Ctrl + C

# 가상환경 비활성화
deactivate

프론트엔드 종료

# 터미널에서 Ctrl + C

프로덕션 빌드 (선택)

프론트엔드 빌드

cd version_2/frontend/vision-contact-app
npm run build

# 빌드 결과물은 dist/ 폴더에 생성됨

프로덕션 서버 실행

# 백엔드
cd version_2/backend
source venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8000

# 프론트엔드 (빌드된 파일 서빙)
cd version_2/frontend/vision-contact-app
npm run preview

기술 스택

백엔드

  • Python 3.11+
  • FastAPI
  • OpenAI API (GPT-4o, GPT-4o-mini, Whisper, TTS)
  • YOLOv8 (객체 탐지)
  • OpenCV (이미지 처리)
  • SQLite (데이터베이스)

프론트엔드

  • Vue 3 (Composition API)
  • TypeScript
  • Vite
  • Pinia (상태 관리)
  • Axios (HTTP 클라이언트)

라이선스 및 API 사용 안내

본 프로젝트는 다음 외부 API를 사용합니다:

  • OpenAI API: 유료 (사용량 기반 과금)
  • Kakao API: 무료 (일일 할당량 제한)
  • TMAP API: 무료 (일일 할당량 제한)
  • Naver API: 무료 (일일 할당량 제한)
  • OpenWeather API: 무료 (일일 할당량 제한)