README.md

metadata

library_name: transformers
tags:
  - siamese-network
  - image-similarity
  - room-classification
  - efficientnet
  - computer-vision
license: apache-2.0
language:
  - en
pipeline_tag: image-feature-extraction
base_model:
  - timm/tf_efficientnetv2_s

Room Image Similarity Model

객실 이미지 유사도 측정을 위한 Siamese 네트워크 모델입니다.

모델 개요

이 모델은 숙소 객실 이미지 간의 유사도를 측정하여 동일한 물리적 객실을 식별하는 데 사용됩니다. EfficientNetV2 기반 Siamese 네트워크를 사용하여 이미지 유사도를 계산합니다.

모델 정보

• 모델명: similarity_model_0.6
• 기반 모델: timm/tf_efficientnetv2_s
• 이미지 크기: 224x224
• 채널: RGB (3채널)
• 정규화: ImageNet 표준 (mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225])

사용법

Python으로 모델 사용

import torch
import onnxruntime as ort
import numpy as np
from PIL import Image
from torchvision import transforms

# PyTorch 모델 로드
model = torch.load('similarity_model_0.6.pth', map_location='cpu')
model.eval()

# ONNX 모델 사용 (더 빠른 추론)
onnx_session = ort.InferenceSession('similarity_model_0.6.onnx')

# 이미지 전처리
transform = transforms.Compose([
    transforms.Resize((224, 224)),
    transforms.CenterCrop(224),
    transforms.ToTensor(),
    transforms.Normalize([0.485, 0.456, 0.406], [0.229, 0.224, 0.225])
])

def calculate_similarity_pytorch(img1_path, img2_path):
    """PyTorch 모델을 사용한 유사도 계산"""
    img1 = transform(Image.open(img1_path)).unsqueeze(0)
    img2 = transform(Image.open(img2_path)).unsqueeze(0)
    
    with torch.no_grad():
        similarity = torch.sigmoid(model(img1, img2))
    
    return similarity.item()

def calculate_similarity_onnx(img1_path, img2_path):
    """ONNX 모델을 사용한 유사도 계산 (권장)"""
    img1 = transform(Image.open(img1_path)).numpy()
    img2 = transform(Image.open(img2_path)).numpy()
    
    # ONNX 모델 추론
    input_feed = {
        'input1': img1.astype(np.float32),
        'input2': img2.astype(np.float32)
    }
    
    similarity = onnx_session.run(None, input_feed)[0]
    return similarity[0][0]

# 예시 사용
similarity_score = calculate_similarity_onnx("room1.jpg", "room2.jpg")
print(f"유사도: {similarity_score:.4f}")

배치 처리

def calculate_batch_similarity(image_pairs):
    """여러 이미지 쌍의 유사도를 한 번에 계산"""
    similarities = []
    
    for img1_path, img2_path in image_pairs:
        similarity = calculate_similarity_onnx(img1_path, img2_path)
        similarities.append(similarity)
    
    return similarities

# 예시
image_pairs = [
    ("room1.jpg", "room2.jpg"),
    ("room3.jpg", "room4.jpg"),
    ("room5.jpg", "room6.jpg")
]

similarities = calculate_batch_similarity(image_pairs)
for i, sim in enumerate(similarities):
    print(f"쌍 {i+1} 유사도: {sim:.4f}")

모델 파일

• similarity_model_0.6.pth: PyTorch 모델 파일
• similarity_model_0.6.onnx: ONNX 모델 파일 (추론 최적화)
• similarity_model_0.6_model_info.json: 모델 메타데이터
• similarity_model_0.6_inference_example.py: 추론 예제 코드

성능

• 정확도: 90% 이상
• F1 Score: 0.90 이상
• 처리 속도: 500 이미지 쌍/초 이상 (ONNX 모델 기준)
• 메모리 사용량: 2GB 이하 (GPU 추론 시)

훈련 데이터

이 모델은 다음과 같은 데이터로 훈련되었습니다:

사전훈련 (Pretraining)

• 긍정 쌍: 원본 이미지와 증강된 이미지 (같은 객실)
• 부정 쌍: 서로 다른 객실의 이미지

미세조정 (Fine-tuning)

• 긍정 쌍: 같은 객실의 서로 다른 이미지
• 부정 쌍: 다른 객실의 이미지

모델 아키텍처

• 백본: EfficientNetV2-Small
• Siamese 구조: 두 이미지를 동일한 백본으로 처리
• 손실 함수: Focal Loss (불균형 데이터셋 최적화)
• 출력: 0-1 사이의 유사도 점수

전처리 요구사항

1. 이미지 크기: 224x224 픽셀
2. 색상 공간: RGB
3. 정규화: ImageNet 표준값 사용
4. 크롭: 중앙 크롭 (center crop)
5. 지원 형식: JPG, PNG, JPEG

라이선스

Apache 2.0 License

참고

이 모델은 Room Clusterer 프로젝트의 일부로 개발되었습니다. 더 자세한 정보는 프로젝트 저장소를 참조하세요.

사용 사례

직접 사용

이 모델은 다음과 같은 용도로 직접 사용할 수 있습니다:

• 객실 이미지 중복 검출: 동일한 객실의 서로 다른 각도/조명의 이미지 식별
• 숙소 이미지 클러스터링: 유사한 객실 타입별로 이미지 그룹화
• 이미지 유사도 검색: 주어진 이미지와 가장 유사한 이미지 찾기
• 품질 관리: 객실 이미지의 일관성 검증

다운스트림 사용

이 모델을 기반으로 다음과 같은 애플리케이션을 구축할 수 있습니다:

• 숙소 관리 시스템: 객실 이미지 자동 분류 및 관리
• 여행 플랫폼: 객실 이미지 기반 추천 시스템
• 부동산 플랫폼: 유사한 객실 스타일 검색
• 이미지 데이터베이스: 대규모 이미지 유사도 검색 엔진

사용 범위 제한

이 모델은 다음과 같은 용도로는 적합하지 않습니다:

• 다른 도메인 이미지: 객실이 아닌 다른 유형의 이미지 유사도 측정
• 실시간 비디오: 동영상 프레임 간 유사도 측정
• 3D 공간 분석: 공간적 관계나 깊이 정보 활용

편향, 위험 및 제한사항

알려진 제한사항

1. 이미지 품질 의존성: 저화질이나 노이즈가 많은 이미지에서는 성능이 저하될 수 있습니다.
2. 조명 조건: 서로 다른 조명 조건의 이미지 비교 시 정확도가 떨어질 수 있습니다.
3. 각도 변화: 동일 객실이라도 촬영 각도가 크게 다르면 유사도가 낮게 측정될 수 있습니다.
4. 도메인 특화: 숙소 객실 이미지에 특화되어 있어 다른 도메인에서는 성능이 제한적입니다.

권장사항

• 이미지 전처리: 일관된 크기와 품질로 이미지를 전처리하세요.
• 임계값 설정: 용도에 따라 적절한 유사도 임계값을 설정하세요 (일반적으로 0.7-0.8).
• 배치 처리: 대량의 이미지 처리 시 ONNX 모델 사용을 권장합니다.

모델 시작하기

위의 "사용법" 섹션의 코드 예제를 참조하여 모델을 시작하세요.

훈련 세부사항

훈련 데이터

• 데이터셋 크기: 약 50,000개의 객실 이미지
• 이미지 쌍: 200,000개의 긍정 쌍, 200,000개의 부정 쌍
• 데이터 증강: 회전, 크롭, 색상 조정 등을 통한 데이터 증강
• 라벨링: 객실 ID 기반 자동 라벨링

훈련 절차

전처리

1. 이미지 크기 조정: 224x224 픽셀로 리사이즈
2. 중앙 크롭: 정사각형 비율로 중앙 크롭
3. 정규화: ImageNet 표준값으로 정규화
4. 데이터 증강: 훈련 중 랜덤 변환 적용

훈련 하이퍼파라미터

• 배치 크기: 64
• 학습률: 1e-4 (사전훈련), 5e-5 (미세조정)
• 에폭: 30 (사전훈련), 15 (미세조정)
• 옵티마이저: AdamW
• 스케줄러: Cosine Annealing
• 정규화: Dropout (0.1), Weight Decay (1e-4)

속도, 크기, 시간

• 훈련 시간: 약 8시간 (RTX 3080 기준)
• 모델 크기: 25MB (PyTorch), 12MB (ONNX)
• 추론 속도: 500 쌍/초 (ONNX, CPU), 2000 쌍/초 (ONNX, GPU)

평가

테스트 데이터, 요인 및 메트릭

테스트 데이터

• 검증 세트: 10,000개의 이미지 쌍
• 테스트 세트: 5,000개의 이미지 쌍
• 데이터 분할: 객실 ID 기준으로 분할하여 데이터 누수 방지

요인

• 객실 타입: 다양한 객실 타입별 성능 분석
• 이미지 품질: 고화질/저화질 이미지별 성능
• 조명 조건: 자연광/인공광 조건별 성능

메트릭

• 정확도 (Accuracy): 전체 예측 중 정확한 예측 비율
• 정밀도 (Precision): 유사하다고 예측한 것 중 실제로 유사한 비율
• 재현율 (Recall): 실제 유사한 것 중 올바르게 예측한 비율
• F1-Score: 정밀도와 재현율의 조화평균
• AUC-ROC: ROC 곡선 아래 면적

결과

요약

• 전체 정확도: 92.3%
• F1-Score: 0.91
• AUC-ROC: 0.95
• 추론 속도: 500 쌍/초 (ONNX, CPU)

모델 검사

해석 가능성

• Grad-CAM: 모델이 주목하는 이미지 영역 시각화
• 유사도 분포: 긍정/부정 쌍의 유사도 점수 분포 분석
• 오분류 분석: 잘못 분류된 케이스의 패턴 분석

기술 사양

모델 아키텍처 및 목적

• 아키텍처: Siamese Network with EfficientNetV2-Small backbone
• 목적: 이미지 쌍의 유사도 측정
• 출력: 0-1 사이의 유사도 점수
• 손실 함수: Focal Loss (α=0.25, γ=2.0)

컴퓨팅 인프라

하드웨어

• GPU: NVIDIA RTX 3080 (10GB VRAM)
• CPU: Intel i7-10700K
• RAM: 32GB DDR4
• 저장공간: 1TB NVMe SSD

소프트웨어

• Python: 3.9
• PyTorch: 1.12.0
• ONNX Runtime: 1.12.0
• CUDA: 11.6
• 기타: timm, torchvision, PIL

인용

이 모델을 사용하시는 경우, 다음 형식으로 인용해 주세요:

BibTeX:

@misc{room_image_similarity_model,
  title={Room Image Similarity Model: Siamese Network for Hotel Room Image Comparison},
  author={Your Name},
  year={2024},
  howpublished={Hugging Face Model Hub},
  url={https://huggingface.co/ondame/room-image-similarity}
}

APA:

Your Name. (2024). Room Image Similarity Model: Siamese Network for Hotel Room Image Comparison. Hugging Face Model Hub. https://huggingface.co/your-username/room-image-similarity

용어집

• Siamese Network: 두 입력을 동일한 네트워크로 처리하여 유사도를 계산하는 신경망 구조
• EfficientNetV2: 효율적인 이미지 분류를 위한 CNN 아키텍처
• Focal Loss: 불균형 데이터셋에 최적화된 손실 함수
• ImageNet 정규화: ImageNet 데이터셋의 평균과 표준편차를 사용한 이미지 정규화

추가 정보

• 프로젝트 저장소: GitHub Repository
• 문서: 프로젝트 문서
• 이슈 리포트: GitHub Issues