강아지 관련 AI 기능을 제공하는 통합 FastAPI 서버입니다. 강아지 품종 분류, 임베딩 생성, 유사도 계산 등의 기능을 제공합니다.
- 🐕 강아지 품종 분류: YOLO + EfficientNet을 사용한 120개 품종 분류
- 🔍 임베딩 생성: CLIP + YOLO를 사용한 이미지/텍스트 임베딩 생성
- 📊 유사도 계산: 두 임베딩 간의 유사도 계산 (유실견/발견견 매칭용)
- 🌏 한글 지원: 한국어 견종명 매핑
Gangajikimi-FastAPI-Server/
├── app/
│ ├── main.py # FastAPI 앱 진입점
│ ├── domain/ # 도메인별 기능 모듈
│ │ ├── config.py # 공통 설정 (LLM, YOLO, CLIP 등)
│ │ ├── dogbreed/ # 강아지 품종 분류 도메인
│ │ │ ├── router.py # API 라우터
│ │ │ ├── schema.py # Pydantic 모델들
│ │ │ ├── service.py # 비즈니스 로직
│ │ │ ├── assets/ # AI 모델 가중치
│ │ │ └── models/ # AI 모델 코드들
│ │ ├── embed/ # 임베딩 생성 도메인
│ │ │ ├── router.py # API 라우터
│ │ │ ├── schema.py # Pydantic 모델들
│ │ │ ├── pipeline_embed.py # 메인 임베딩 파이프라인
│ │ │ ├── llm_client.py # LLM 텍스트 정제
│ │ │ ├── yolo_crop.py # YOLO 이미지 크롭
│ │ │ └── clipper.py # CLIP 임베딩
│ │ └── similarity/ # 유사도 계산 도메인
│ │ ├── router.py # API 라우터
│ │ ├── schema.py # Pydantic 모델들
│ │ ├── pipeline_similarity.py # 메인 유사도 파이프라인
│ │ └── similarity.py # 유사도 계산 함수들
│ └── response/ # 응답 유틸리티
├── requirements/ # 의존성 관리
│ ├── requirements-base.txt # 기본 패키지
│ ├── requirements-cpu.txt # CPU 버전 PyTorch
│ └── requirements-gpu-cu128.txt # GPU 버전 PyTorch
├── Dockerfile # Docker 컨테이너 설정
└── yolov8s.pt # YOLO 모델 가중치
- Python 3.8 이상
- 최소 4GB RAM (모델 로딩용)
- 디스크 공간 2GB 이상
# 프로젝트 디렉토리로 이동
cd Gangajikimi-FastAPI-Server
# 가상환경 생성
python -m venv fastapi_env
# 가상환경 활성화
source fastapi_env/bin/activate # Linux/Mac
# 또는
fastapi_env\Scripts\activate # Windows# 기본 패키지 설치
pip install -r requirements/requirements-base.txt
# PyTorch 설치 (CPU 버전)
pip install -r requirements/requirements-cpu.txt
# 또는 GPU 버전 (CUDA 12.8)
pip install -r requirements/requirements-gpu-cu128.txt로컬 개발 환경:
# config.py.example을 복사하여 config.py 생성
cp app/domain/config.py.example app/domain/config.py
# config.py를 열어서 GEMINI_API_KEY 수정
# GEMINI_API_KEY = "YOUR_ACTUAL_API_KEY_HERE"Gemini API 키 발급 방법:
- Google AI Studio에 접속
- "Create API Key" 클릭하여 API 키 생성
app/domain/config.py파일에서GEMINI_API_KEY값을 수정
주의사항:
⚠️ config.py는.gitignore에 포함되어 있어 GitHub에 업로드되지 않습니다- 운영/배포 환경에서는 GitHub Actions가 환경변수로 자동 생성합니다
- 환경변수로도 설정 가능:
export GEMINI_API_KEY="your_key"
# 개발 모드 실행
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
# 프로덕션 모드 실행
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4서버 실행 후 다음 URL에서 API 문서를 확인할 수 있습니다:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
엔드포인트: POST /api/v1/dogbreed/
요청:
- Content-Type:
multipart/form-data - image: 강아지 이미지 파일 (JPG, PNG 등)
요청 예시:
curl -X POST "http://localhost:8000/api/v1/dogbreed/" \
-H "accept: application/json" \
-F "image=@/path/to/dog_image.jpg"응답:
{
"result": "골든 리트리버"
}엔드포인트: POST /api/v1/embed/normalize
요청:
{
"breed": "골든 리트리버",
"colors": "골드, 흰색",
"features": "큰 귀, 긴 털"
}응답:
{
"sentences": [
"골든 리트리버 견종입니다.",
"골드와 흰색 색상의 강아지입니다.",
"큰 귀와 긴 털이 특징입니다."
]
}엔드포인트: POST /api/v1/embed/embed
요청:
- Content-Type:
multipart/form-data - image: 강아지 이미지 파일
- breed: 품종 (선택사항)
- colors: 색상 (선택사항)
- features: 특징 (선택사항)
요청 예시:
curl -X POST "http://localhost:8000/api/v1/embed/embed" \
-H "accept: application/json" \
-F "image=@/path/to/dog_image.jpg" \
-F "breed=골든 리트리버" \
-F "colors=골드, 흰색" \
-F "features=큰 귀, 긴 털"응답:
{
"sentences": [
"골든 리트리버 견종입니다.",
"골드와 흰색 색상의 강아지입니다.",
"큰 귀와 긴 털이 특징입니다."
],
"image": [0.1, -0.2, 0.3, ...], // 512차원 이미지 임베딩
"text": [0.2, -0.1, 0.4, ...] // 512차원 텍스트 임베딩
}엔드포인트: POST /api/v1/similarity/score
요청:
{
"emb_a_image": [0.1, -0.2, 0.3, ...], // 게시물 A의 이미지 임베딩
"emb_a_text": [0.2, -0.1, 0.4, ...], // 게시물 A의 텍스트 임베딩
"emb_b_image": [0.3, -0.3, 0.2, ...], // 게시물 B의 이미지 임베딩
"emb_b_text": [0.1, -0.2, 0.3, ...], // 게시물 B의 텍스트 임베딩
"weights": [0.2, 0.0, 0.0, 0.8] // 가중치 (선택사항)
}응답:
{
"s_ii": 0.85, // 이미지-이미지 유사도
"s_it": 0.72, // 이미지-텍스트 유사도
"s_ti": 0.68, // 텍스트-이미지 유사도
"s_tt": 0.91, // 텍스트-텍스트 유사도
"score": 0.88, // 최종 가중 평균 유사도
"threshold": 0.35, // 임계값
"pass": true // 임계값 기준 매칭 여부
}다음 환경 변수를 설정할 수 있습니다:
# Gemini API 설정 (LLM 텍스트 정제용)
GEMINI_API_URL=https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent
GEMINI_API_KEY=your_gemini_api_key_here # Gemini API 키를 여기에 입력
GEMINI_TEMPERATURE=0.1
LLM_TIMEOUT=20
LLM_MAX_RETRIES=3
# YOLO 설정
YOLO_WEIGHTS=yolov8s.pt
YOLO_CONF=0.30
YOLO_MARGIN=0.18
YOLO_IMGSZ=512
DOG_CLASS_ID=16
# CLIP 설정
CLIP_MODEL=ViT-B-32
CLIP_PRETRAINED=laion2b_s34b_b79k
TEXT_POOLING=avg
# 유사도 가중치
W_II=0.20 # 이미지-이미지 가중치
W_IT=0.00 # 이미지-텍스트 가중치
W_TI=0.00 # 텍스트-이미지 가중치
W_TT=0.80 # 텍스트-텍스트 가중치
# 유사도 임계값
SIM_THRESHOLD=0.35# Docker 이미지 빌드
docker build -t gangajikimi-api .
# Docker 컨테이너 실행 (환경변수 포함)
docker run -p 8000:8000 \
-e GEMINI_API_KEY="your_gemini_api_key_here" \
gangajikimi-api
# 또는 백그라운드 실행
docker run -d -p 8000:8000 \
-e GEMINI_API_KEY="your_gemini_api_key_here" \
--name gangajikimi-server \
gangajikimi-api모델 캐시를 재사용하려면 볼륨을 마운트할 수 있습니다:
docker run -d -p 8000:8000 \
-e GEMINI_API_KEY="your_gemini_api_key_here" \
-v $(pwd)/.cache:/app/.cache \
--name gangajikimi-server \
gangajikimi-api참고:
- Hugging Face 모델은
/app/.cache/huggingface에 다운로드됩니다 - 비루트 사용자(
appuser, UID 10001)로 실행되므로 권한 문제가 없습니다
이 프로젝트는 GitHub Actions를 통해 GCP VM에 자동으로 배포할 수 있습니다.
-
Docker Hub 계정 준비: Docker Hub 계정 및 Access Token 생성
-
GCP VM 생성: GCP Compute Engine에서 VM 인스턴스 생성
-
SSH 키 설정: VM 접속용 SSH 키 생성 및 등록
-
GitHub Secrets 추가: Repository Settings에서 필요한 secrets 추가
DOCKERHUB_USERNAME: Docker Hub 사용자 이름DOCKERHUB_TOKEN: Docker Hub Access TokenSSH_PRIVATE_KEY: VM 접속용 SSH Private 키VM_HOST: VM의 외부 IP 주소VM_USER: VM 사용자 이름 (예:ubuntu)GEMINI_API_KEY: Gemini API 키CONFIG_PY:app/domain/config.py파일의 전체 내용
-
자동 배포:
develop브랜치에 push하면 자동으로 배포
자세한 설정 방법은 GCP 배포 가이드를 참고하세요.
config.py파일 생성 (GitHub Secret에서)- Docker 이미지 빌드
- Docker Hub에 푸시
- SSH 키 설정
- VM에 SSH 접속하여 컨테이너 재시작
-
유실견 게시물 처리:
# 유실견 이미지와 설명으로 임베딩 생성 curl -X POST "http://localhost:8000/api/v1/embed/embed" \ -F "image=@lost_dog.jpg" \ -F "breed=골든 리트리버" \ -F "colors=골드, 흰색" \ -F "features=큰 귀, 긴 털"
-
발견견 게시물 처리:
# 발견견 이미지와 설명으로 임베딩 생성 curl -X POST "http://localhost:8000/api/v1/embed/embed" \ -F "image=@found_dog.jpg" \ -F "breed=골든 리트리버" \ -F "colors=골드, 흰색" \ -F "features=큰 귀, 긴 털"
-
유사도 계산:
# 두 게시물 간의 유사도 계산 curl -X POST "http://localhost:8000/api/v1/similarity/score" \ -H "Content-Type: application/json" \ -d '{ "emb_a_image": [...], "emb_a_text": [...], "emb_b_image": [...], "emb_b_text": [...] }'
이 프로젝트는 MIT 라이선스 하에 배포됩니다.
버그 리포트나 기능 제안은 이슈를 통해 알려주세요.
Gangajikimi AI - 강아지와 함께하는 더 나은 세상을 만들어갑니다. 🐕✨