서비스 아키텍쳐 모듈화

app/
├── main.py
├── api/
│   └── v1/
│       ├── endpoints/
│       │   ├── album_embedding_router.py   # [앨범 임베딩 요청]
│       │   ├── album_tagging_router.py     # [태깅 분리 요청]
│       │   ├── album_duplicate_router.py     # 중복 판별
│       │   ├── album_clustering_router.py    # 인물 클러스터링
│       │   └── style_router.py             # [스타일 변환 요청]
│       └── controllers/
│           ├── album_embedding_controller.py
│           ├── album_tagging_controller.py
│           ├── album_duplicate_controller.py
│           ├── album_clustering_controller.py
│           └── style_controller.py
├── services/
│   ├── album/
│   │   ├── embedding_service.py        # 이미지 임베딩 추출
│   │   ├── person_clustering.py        # 사람 분류 (군집화)
│   │   ├── duplicate_detection.py      # 중복 사진 판별
│   │   └── tagging_service.py          # 태깅 처리 (ex. beach, food)
│   └── style/
│       ├── gemini_service.py           # 제미나이 호출 (스타일 프롬프트 생성)
│       ├── gpu_server_service.py       # GPU 서버 스타일 변환 요청
├── schemas/
│   ├── album_schema.py                 # Pydantic: 앨범 생성 요청/응답
│   └── style_schema.py                 # Pydantic: 스타일 변환 요청/응답
└──  utils/
    └──  image_converter.py              # base64 <-> PIL 변환 등

흐름 요약 (분리된 API 기준)

1. 이미지 임베딩 요청 (POST /api/v1/albums/embeddings)

• album_embedding_router.py → album_embedding_controller.py

  → embedding_service.py

• 임베딩해서 캐시에 저장

• 클라이언트에 임베딩 성공했음을 알림. 임베딩 성공 후, 태깅&중복 판별&인물 클러스터링이 비동기로 진행됨.

---

2. 태깅 요청 (POST /api/v1/albums/tags)

• album_tagging_router.py → album_tagging_controller.py

  → tagging_service.py

• 이미지에 대해 음식, 해변 등 콘텐츠 기반 태그 추출

📦 응답 예시:

{
  "tags": {
    "food": ["http://server:8000/img1.jpg", "http://server:8000/img5.jpg"],
    "beach": ["http://server:8000/img2.jpg", "http://server:8000/img6.jpg"]
  }
}

---

3. 중복 이미지 판별 요청 (POST /api/v1/albums/duplicates)

• album_duplicate_router.py → album_duplicate_controller.py

  → duplicate_detection.py

• 유사도 기반으로 중복 이미지 그룹화

📦 응답 예시:

{
  "duplicates": {
    "duplicate_group_1": ["http://server:8000/img4.jpg", "http://server:8000/img7.jpg"]
  }
}

---

4. 인물 클러스터링 요청 (POST /api/v1/albums/clusters)

• album_clustering_router.py → album_clustering_controller.py

  → person_clustering.py

• 동일 인물 기준으로 이미지 그룹화

📦 응답 예시:

{
  "people_clusters": {
    "person1": ["http://server:8000/img1.jpg", "http://server:8000/img3.jpg"],
    "person2": ["http://server:8000/img2.jpg"]
  }
}

---

5. 스타일 변환 요청 (POST /api/v1/style)

• style_router.py → style_controller.py

  → image_downloader.py (이미지 다운로드)

  → gemini_service.py (이미지 기반 프롬프트 생성)

  → image_converter.py (PIL → base64 변환)

  → gpu_server_service.py (base64 + 프롬프트 전달)

  → s3_uploader.py (결과 이미지 S3 업로드 후 URL 반환)

---

📦 흐름 요약

1. 클라이언트(백엔드 서버)가 S3 이미지 URL과 스타일명을 요청에 담아 전송

2. image_downloader.py가 해당 URL에서 이미지를 다운로드 (PIL 이미지로 변환)

3. gemini_service.py가 다운로드된 이미지를 Gemini에 입력하여

   → 이미지 설명 기반 스타일 프롬프트 생성

4. image_converter.py에서 해당 이미지를 base64로 인코딩

5. gpu_server_service.py가 base64 이미지 + 스타일 프롬프트를 GPU 서버에 전송

6. GPU 서버가 스타일 이미지 생성 후 반환된 base64 이미지를 다시 디코딩

7. 결과 이미지를 s3_uploader.py가 S3에 저장

8. 클라이언트에게 S3 URL을 응답으로 반환

---

📝 요청 예시

{
  "image_url": "https://your-bucket.s3.amazonaws.com/originals/img123.jpg",
  "style_name": "watercolor"

---

📝 응답 예시

{
  "image_url": "https://your-bucket.s3.amazonaws.com/converted/img123_watercolor.jpg"
}

---

🧩 전체 모듈 흐름

모듈	역할
image_downloader.py	이미지 URL에서 파일 다운로드 → PIL 이미지 반환
gemini_service.py	다운로드된 이미지를 기반으로 스타일 프롬프트 생성
image_converter.py	PIL 이미지를 base64 문자열로 인코딩
gpu_server_service.py	base64 이미지 + 프롬프트 → GPU 서버로 전송
s3_uploader.py	결과 이미지를 S3에 업로드하고 URL 반환

---

예시: GPU 서버로 보내는 데이터 포맷

{
  "prompt": "ghibli style, 1girl, smiling, close-up, soft lighting, warm color tones, ((masterpiece)), ((best quality)), <lora:ghibli_style_offset:1.1>",
  "negative_prompt": "(worst quality, low quality:1.4), bad anatomy, blurry, jpeg artifacts, watermark, text",
  "seed": 1178811602,
  "steps": 20,
  "width": 512,
  "height": 768,
  "cfg_scale": 8,
  "sampler_name": "Euler a",
  "denoising_strength": 0.5,
  "init_images": ["<base64로 인코딩된 원본 이미지>"],
  "restore_faces": true,
  "enable_hr": false,
  "override_settings": {
    "sd_model_checkpoint": "anyloraCheckpoint_bakedvaeBlessedFp16",
    "CLIP_stop_at_last_layers": 2
  },
  "alwayson_scripts": {
    "ControlNet": {
      "args": [
        {
          "enabled": true,
          "module": "mediapipe_face",
          "model": "control_v2p_sd15_mediapipe_face [0653d983]",
          "control_mode": "ControlNet is more important",
          "resize_mode": "Crop and Resize",
          "image": {
            "image": "<face_img_base64>",
            "mask": null
          }
        },
        {
          "enabled": true,
          "module": "depth_midas",
          "model": "diffusers_xl_depth_mid [39c49e13]",
          "control_mode": "My prompt is more important",
          "resize_mode": "Crop and Resize",
          "image": {
            "image": "<depth_img_base64>",
            "mask": null
          }
        },
        {
          "enabled": true,
          "module": "softedge_hed",
          "model": "control_v11p_sd15_softedge [a8575a2a]",
          "control_mode": "My prompt is more important",
          "resize_mode": "Crop and Resize",
          "image": {
            "image": "<softedge_img_base64>",
            "mask": null
          }
        },
        {
          "enabled": true,
          "module": "canny",
          "model": "diffusers_xl_canny_mid [112a778d]",
          "control_mode": "My prompt is more important",
          "resize_mode": "Crop and Resize",
          "threshold_a": 100,
          "threshold_b": 200,
          "image": {
            "image": "<canny_img_base64>",
            "mask": null
          }
        }
      ]
    }
  }
}