minaz-rong 님의 블로그

Django와 FastAPI를 활용한 MSA 기반 멀티모달 AI 챗봇 구축기

minaz-rong — Fri, 22 May 2026 20:39:49 +0900

1. 프로젝트 개요

이번 프로젝트의 목표는 단순한 API 호출을 넘어, 사용자의 입력(텍스트, 음성, 이미지)을 안전하게 검증하고 처리하는 풀스택 AI 서비스를 구축하는 것이었다. 이를 위해 프론트엔드(Vanilla JS)부터 API 게이트웨이(Django), AI 연동 전담 모델 서버(FastAPI)까지 역할이 명확히 분리된 MSA(마이크로서비스 아키텍처)를 설계했다.

주요 기능

Guardrail (안전망): 사용자의 부적절한 요청(선정성, 폭력성 등)을 AI가 사전 차단.
멀티모달 처리: 텍스트 대화뿐만 아니라 이미지 생성(~그려줘), TTS 음성 변환 지원.
답변 품질 평가: LLM의 답변이 사용자의 질문과 얼마나 적합한지 자체 채점(Scoring)하여 UX 신뢰도 향상.

️ 2. 아키텍처 설계: 왜 Django와 FastAPI를 같이 썼을까?

초기 설계 단계에서 가장 많이 고민했던 부분이다. "그냥 서버 하나로 다 만들면 안 되나?"라는 의문이 들 수 있지만, 시스템의 확장성과 유지보수, 그리고 각 프레임워크의 장점을 극대화하기 위해 두 서버를 분리했다.

1) Django: 든든한 문지기 (API Gateway & Proxy)

역할: 클라이언트의 요청을 가장 먼저 맞이하는 게이트웨이이자, HTML 화면을 서빙(Serving)하는 역할.
선택 이유: Django는 무겁지만 체계적이다. Serializers를 통해 들어오는 데이터의 형식을 엄격하게 검증하고, 잘못된 요청은 모델 서버로 가기 전에 즉시 400 Bad Request로 차단한다. 향후 회원가입, 로그인, 결제, 대화 기록 저장(DB) 등의 비즈니스 로직이 추가될 때 진가를 발휘한다.

2) FastAPI: 날렵한 AI 스페셜리스트 (Model Server)

역할: AI 모델(OpenAI/GMS)과 직접 통신하며 텍스트, 이미지, 음성을 생성하는 핵심 두뇌 역할.
선택 이유: 이름 그대로 빠르고 가볍다. 비동기 처리(Async)에 특화되어 있어 응답 시간이 길어질 수 있는 AI 모델 API 호출을 병목 없이 처리하는 데 최적화되어 있다.

핵심 인사이트 (관심사의 분리): Django는 복잡한 '서비스/회원 로직'을, FastAPI는 무거운 'AI 추론 연산'을 담당한다. 만약 AI 트래픽이 몰리면 FastAPI 서버만 여러 대 늘리면(Scale-out) 되므로 인프라 자원을 매우 경제적이고 효율적으로 운영할 수 있다.

️ 3. Trouble Shooting (이슈 및 해결 과정)

개발 과정에서 겪었던 주요 블로커(Blocker)들과 해결 과정을 기록한다.

Issue 1: TemplateDoesNotExist - 장고가 화면을 찾지 못하는 현상

증상: 장고 서버 구동 후 localhost:8000에 접속했으나 index.html을 렌더링하지 못함.
원인: 장고의 BASE_DIR 기준점과 실제 templates 폴더의 위치가 어긋나 있었다. 폴더가 proxy_server 안쪽 깊숙이 들어가 있었던 것.
해결: templates 폴더를 manage.py와 같은 레벨(최상위)로 꺼내고, settings.py의 TEMPLATES 경로가 [BASE_DIR / 'templates']를 정확히 바라보도록 디렉토리 구조를 재정렬했다.

[에러 로그]

TemplateDoesNotExist at /
index.html
Exception Location: /.../django/template/loader.py

[원인 및 해결]

# settings.py 수정 내용
TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [BASE_DIR / 'templates'], #   장고에게 폴더 위치를 정확히 명시!
        ...
    }
]

Issue 2: 데이터 규격 불일치로 인한 404 Not Found & 422 Unprocessable Entity

증상: 프론트엔드에서 장고를 거쳐 FastAPI로 데이터가 넘어갈 때 에러 발생.
원인: Django(게이트웨이)와 FastAPI(모델 서버) 간의 API 명세(Contract) 불일치
404 에러: Django는 /chat/completions 주소로 데이터를 쐈지만, FastAPI는 /chat이라는 이름표를 달고 있었다.
422 에러: 데이터 포맷이 달랐다. Django는 데이터를 messages라는 이름(Key)으로 보냈는데, FastAPI의 Pydantic 모델은 prompt라는 이름을 기다리고 있어서 처리를 거부(Unprocessable)한 것이다.
해결: 장고의 통신 전담 파일인 services.py를 리팩토링했다. 하드코딩된 변수들을 FastAPI의 Pydantic 모델(ChatRequest) 규격에 맞춰 prompt로 통일하고 엔드포인트를 수정하여 두 서버 간의 언어를 일치시켰다.

[에러 로그]

[서비스 에러 발생] 404 Client Error: Not Found for url: http://127.0.0.1:8001/api/v1/chat/completions
[서비스 에러 발생] 422 Client Error: Unprocessable Entity for url: http://127.0.0.1:8001/api/v1/chat/score

[원인 및 해결]

# Django: proxy_server/api/services.py

def get_chat_response(chat_request):
    """FastAPI 모델 서버로 채팅 요청 전송"""
    # 수정 1: 'messages' -> 'prompt'로 Key 통일
    payload_data = {"prompt": chat_request.get("prompt")}
    try:
        # 수정 2: '/chat/completions' -> '/chat'으로 URI 통일
        response = requests.post(
            f"{MODEL_SERVER_URL}/chat", json=payload_data
        )
        response.raise_for_status()
        return response.json()
    except Exception as e:
        print(f"[에러] {e}")
        return None

Issue 3: TTS 오디오 데이터 전송 포맷 문제 (Base64)

증상: TTS API 호출 시 바이너리(이진) 형태의 mp3 데이터가 HTTP JSON 응답으로 제대로 전달되지 않음.
원인: JSON 포맷은 텍스트만 담을 수 있기 때문에, 오디오 파일을 그대로 쑤셔 넣으면 데이터가 깨지거나 에러가 난다.
해결: FastAPI에서 오디오 데이터를 base64.b64encode()를 이용해 안전한 텍스트 형태로 인코딩(암호화)하여 전송했다. 프론트엔드에서는 이를 다시 디코딩하여 <audio> 태그의 소스로 활용해 브라우저에서 즉시 재생되도록 구현했다.

[해결]

# FastAPI: model_server/model_main.py

@app.post("/api/v1/audio/speech")
def generate_speech(req: TTSRequest):
    # (중략) 외부 API로 음성 생성 요청 ...
    res.raise_for_status()
    
    #   핵심: 넘어온 이진(Binary) mp3 데이터를 웹에서 읽을 수 있게 Base64로 인코딩!
    audio_data = base64.b64encode(res.content).decode("utf-8")
    return {"audio_data": audio_data}

이후 프론트엔드(Vanilla JS)에서는 받아온 Base64 텍스트를 다시 오디오 소스로 변환해 브라우저에서 즉시 재생(new Audio().play())하도록 구현했다.

4. Retrospective (회고)

단순히 "기능이 동작한다"를 넘어, 실제 프로덕트 레벨에서 시스템이 어떻게 맞물려 돌아가야 하는지 뼈저리게 배운 하루였다.

특히 views.py에 있던 외부 통신 로직을 services.py로 분리하면서 코드를 어떻게 짜야 나중에 서비스 기획이나 스펙이 변경될 때 유연하게 대처할 수 있는지 아키텍처 설계의 중요성을 깨달았다. 프론트엔드(UI/UX), 프록시, AI 연동이라는 전체 데이터의 흐름을 통제해 본 경험은 향후 AI 서비스를 기획하고 리드하는 데 있어 엄청난 자산이 될 것 같다.

Jira + GitHub 협업 규칙

minaz-rong — Thu, 14 May 2026 17:02:25 +0900

1. 개념 이해하기

용어	의미
Jira Task	해야 할 일 카드
Branch	해당 작업을 위한 개인 작업 공간
Commit Message	작업 내용을 저장하면서 남기는 기록
Pull Request (PR)	내 작업을 main 브랜치에 합쳐달라고 요청하는 것

2. 작업 예시

Jira에 다음 작업이 있다고 가정한다.

KAN-27 AI 해설 생성 API 구현

3. 브랜치명 규칙

형식: feature/KAN-번호-작업명
예시:
- feature/KAN-27-ai-api
- feature/KAN-35-result-page
- feature/KAN-16-public-api-test

브랜치 생성 명령어

Bash

git checkout main
git pull origin main
git checkout -b feature/KAN-27-ai-api

git checkout main: 현재 브랜치를 main으로 이동 (팀의 기준 코드가 있는 곳).
git pull origin main: GitHub에 있는 최신 코드를 내 컴퓨터로 다운로드.
git checkout -b feature/KAN-27-ai-api: 새로운 브랜치를 만들고 이동 (KAN-27 전용 공간).

세 줄 요약: main 브랜치로 이동 → 최신 코드 받기 → 내 작업용 브랜치 생성

4. 커밋 메시지 규칙

형식: KAN-번호 작업 내용
예시:
- KAN-27 AI 해설 생성 API 구현
- KAN-35 결과 페이지 UI 구현

커밋 명령어

Bash

git add .
git commit -m "KAN-27 AI 해설 생성 API 구현"

git add .: 수정한 파일들을 커밋 대상으로 등록.
git commit -m "...": 작업 내용을 저장하고 기록을 남김.

5. GitHub에 Push

Bash

git push origin feature/KAN-27-ai-api

의미: 내 브랜치를 GitHub에 업로드한다.

6. Pull Request(PR) 제목 규칙

형식: KAN-번호 작업 내용
예시: KAN-27 AI 해설 생성 API 구현
의미: KAN-27 작업이 끝났으니 main에 합쳐달라는 요청.

7. Jira 상태 변경 규칙

To Do → In Progress → In Review → Done

상황	Jira 상태
작업 시작	In Progress
PR 생성	In Review
PR Merge 완료	Done

8. 전체 작업 흐름

Jira에서 작업 확인: KAN-27 AI 해설 생성 API 구현
브랜치 생성: git checkout main → git pull → git checkout -b ...
코드 작성
커밋: git add . → git commit -m "KAN-27 ..."
GitHub에 Push: git push origin ...
Pull Request 생성: 제목에 Jira 번호 포함
리뷰 후 Merge
Jira 상태 변경: Done으로 완료 처리

9. 역할별 실제 예시

AI 담당자
- Task: KAN-23 프롬프트 설계
- Branch: feature/KAN-23-prompt-design
- PR: KAN-23 프롬프트 설계
Backend 담당자
- Task: KAN-27 AI 해설 생성 API 구현
- Branch: feature/KAN-27-ai-api
- PR: KAN-27 AI 해설 생성 API 구현
Frontend 담당자
- Task: KAN-35 결과 페이지 구현
- Branch: feature/KAN-35-result-page
- PR: KAN-35 결과 페이지 구현

10. 핵심 규칙 한 줄 요약

브랜치명, 커밋 메시지, PR 제목에 반드시 Jira 번호(KAN-xx)를 포함한다.

11. 팀원 체크리스트

[ ] 작업 시작 전: Jira 번호 확인 및 상태를 'In Progress'로 변경. 최신 코드 pull 후 브랜치 생성.
[ ] 작업 중: 코드 작성 및 수시로 커밋.
[ ] 작업 완료 후: Push 후 PR 생성. 제목에 번호 포함. Jira 상태를 'In Review'로 변경.
[ ] 리뷰 완료 후: Merge 확인 후 Jira 상태를 'Done'으로 변경.

요약: 번호 확인 → 브랜치 생성 → 작업 → 커밋 → Push → PR → 리뷰 → Merge → Done

12. Jira 사용법 요약

Epic (큰 기능 단위)

기획 및 자료조사 / 데이터 수집 / AI 해설 생성 / 백엔드 / 프론트엔드 / 배포 / 발표 준비

Task (실제 세부 작업)

사용자 페르소나 정의 / 공공 API 조사 / 프롬프트 설계 / 결과 페이지 구현

Priority (우선순위)

Highest: 지금 당장 해야 함
High: 매우 중요
Medium: 일반
Low: 여유 있을 때

2026 정보처리기사 필기 시험 소개 및 일정 정리

minaz-rong — Wed, 6 May 2026 11:01:44 +0900

정보처리기사란?

정보처리기사는 IT 전반의 기초 지식과 실무 능력을 평가하는 국가기술자격증
소프트웨어 개발, 데이터베이스, 시스템 운영 등 IT 직무 전반에서 기본 자격증처럼 취급된다

주관: 한국산업인력공단
시행: 연 3회 (보통)

왜 따는가?

IT 취업 시 기본 스펙
공기업 / 공공기관 가산점
개발자, 데이터 직무 준비 시 기초 정리용

특히 비전공자도 많이 도전하는 시험

시험 구성

✔ 필기시험

객관식 4지선다
총 100문제 (과목당 20문제)

과목 구성:

소프트웨어 설계
소프트웨어 개발
데이터베이스 구축
프로그래밍 언어 활용
정보시스템 구축관리

✔ 합격 기준

과목별 40점 이상
전체 평균 60점 이상

한 과목이라도 과락이면 탈락

2026년 정보처리기사 시험 일정 (예시)

※ 정확한 일정은 큐넷에서 확인 필요

접수 및 확인: 큐넷(https://www.q-net.or.kr/crf005.do?id=crf00503&jmCd=1320)

✔ 1회차

접수: 1월 12일 ~ 1월 15일
필기시험: 3월

✔ 2회차

접수: 4월 20일 ~ 4월 23일
필기시험: 5월

✔ 3회차

접수: 7월 20일 ~ 7월 23일
필기시험: 9월

⏱ 시험 시간

총 150분 (2시간 30분)
과목 구분 없이 한 번에 진행

난이도 & 특징

암기 + 이해 혼합형 시험
기출 문제 반복 비중 높음
실무보다는 “이론 중심”

느낌:
“얕고 넓게 많이 아는 사람이 유리한 시험”

합격률 (참고)

필기: 약 50~60%
실기: 약 20~30%

실기가 훨씬 어려움

이런 사람에게 추천

개발자 취업 준비생
IT 기초를 정리하고 싶은 사람
공기업 준비생

협업을 위한 폴더 구조와 네이밍 규칙 총정리

minaz-rong — Wed, 29 Apr 2026 17:05:10 +0900

팀 프로젝트를 하다 보면 이런 상황을 자주 겪습니다.

“이 코드 어디에 있어?”
“파일 이름 왜 이렇게 지었지?”
“같은 기능인데 파일이 여기저기 흩어져 있네…”

이런 문제의 원인은 대부분 폴더 구조와 네이밍이 통일되지 않았기 때문입니다.

1. 잘못된 폴더 구조 vs 좋은 폴더 구조

❌ 잘못된 예 (사람 기준 구조)

mina/
koo/
boo/

문제점

기능이 사람 기준으로 흩어짐
코드 찾기 어려움
협업이 아닌 개인 작업처럼 변함

❌ 또 다른 나쁜 예 (섞여있는 구조)

utils/
api/
components/
pages/
stock/
chat/
data/

기준이 섞여 있음 (기능 + 역할 혼합)

✅ 좋은 예 (기능 기준 구조)

backend/
  user/
  order/
  payment/

frontend/
  user/
  order/
  payment/

장점

기능 단위로 코드가 모여 있음
유지보수 쉬움
협업 시 역할 분리 명확

2. 네이밍 컨벤션, 왜 중요한가?

코드는 결국 “읽는 것”이 더 많습니다.
이름이 곧 문서입니다.

❌ 나쁜 네이밍 예

data1
temp
abc
getD

문제:

의미를 알 수 없음
협업 시 해석 필요 → 시간 낭비

✅ 좋은 네이밍 예

userList
getUserData
fetchOrderHistory
calculateTotalPrice

이름만 보고 역할이 바로 이해됨

3. 네이밍 규칙 정리

변수 / 함수 → camelCase

userName
getUserProfile
calculateDiscountPrice

클래스 / 컴포넌트 → PascalCase

UserService
OrderController
PaymentCard

파일명 → kebab-case (추천)

user-service.js
order-controller.js
payment-utils.js

DB 컬럼 → snake_case

user_id
created_at
order_price

API 경로 → 소문자 + kebab-case

/api/user-profile
/api/order-history
/api/payment-status

4. 흔히 하는 실수

camelCase / snake_case 섞어 쓰기
파일명 규칙 사람마다 다르게 쓰기
의미 없는 이름 사용
축약어 남발 (usr, dt 등)

결국 코드 이해도가 떨어짐

5. 좋은 구조와 네이밍의 효과

코드 찾는 시간 감소
협업 효율 증가
유지보수 쉬움
코드 리뷰 속도 향상

한 줄 정리

“폴더는 기능 기준으로, 이름은 일관되게” 이 두 가지만 지켜도 프로젝트 퀄리티가 달라진다

팀 프로젝트 시작 전, 반드시 정해야 할 협업 규칙2 (폴더구조, 네이밍 컨벤션)

minaz-rong — Wed, 29 Apr 2026 17:04:32 +0900

프로젝트 진행 시 아래 기준으로 반드시 통일합니다.

1. 폴더 구조 (기능 기준)

✅ 구조

backend/
  stock/        # 주식
  crypto/       # 크립토
  consumption/  # 소비 분석
  ai/           # 공통 AI

frontend/
  chatbot/      # 챗봇 UI
  dashboard/    # 소비/데이터 시각화
  stock/        # 주식 화면

규칙

각자 담당 기능 폴더 중심으로 작업
다른 폴더 수정 시 팀원과 공유
공통 폴더(ai)는 역할 나눠서 작업

2. 네이밍 컨벤션

변수 / 함수

camelCase

userName
getUserData
fetchStockPrice

클래스 / 컴포넌트

PascalCase

UserCard
LoginPage
StockChart

파일명

kebab-case

user-profile.js
stock-chart.vue
chatbot-service.py

DB 컬럼

snake_case

user_id
created_at
stock_price

API 경로

소문자 + kebab-case

/api/stock-price
/api/crypto-buzz
/api/user-data

⚠️ 필수 규칙

네이밍 방식 혼용 금지
의미 없는 이름 금지 (data1, temp ❌)
축약어 남발 금지

Git PR(Pull Request) 개념부터 실전까지 한 번에 정리

minaz-rong — Wed, 29 Apr 2026 16:45:04 +0900

우리 팀 PR (Pull Request) 규칙

팀 프로젝트에서 PR은
코드를 합치기 전 반드시 거치는 “검토 과정”입니다.
아래 규칙을 반드시 지킵니다.

언제 사용하나요?

feature 브랜치에서 작업 완료 후
develop 브랜치에 반영할 때 사용

어디서 작성하나요?

GitHub 웹사이트에서 작성

경로:

Repository 접속
Pull requests 클릭
New pull request 버튼 클릭

1. 기본 원칙

PR 없이 merge 금지 ❌
모든 코드는 PR을 통해서만 develop에 반영 ⭕
PR = “내 코드 리뷰 요청”

2. PR 방향 (중요 ⭐)

feature/* → develop

예:

feature/mina-chatbot → develop
feature/boo-stock-analysis → develop

3. PR 작성 규칙

템플릿 (필수 사용)

## 작업 내용
## 변경 사항
## 리뷰 포인트
## 관련 이슈

작성 기준

작업 내용을 한눈에 이해 가능하게 작성
변경 사항은 핵심만 정리
리뷰 포인트는 꼭 확인받고 싶은 부분 작성

진행 흐름

feature 브랜치에서 작업
commit & push
PR 생성 (→ develop)
코드 리뷰
승인 후 merge

4. 리뷰 & Merge 규칙

최소 1명 이상 승인 후 Merge
승인 없이 merge 금지
리뷰 요청 시 팀원 태그 필수

Merge 방식: Squash Merge 사용(권장)

5. PR 크기 규칙 (중요)

기능 단위로 PR 생성
너무 큰 PR 금지
하루 작업 단위로 PR 권장

❌ 나쁜 예

기능 여러 개를 한 번에 PR

✅ 좋은 예

로그인 기능 PR
회원가입 기능 PR

6. 작업 흐름

feature 브랜치 생성
기능 개발
commit & push
PR 생성 (→ develop)
코드 리뷰
승인 후 merge

7. 금지 사항

main 브랜치로 PR 금지
develop에서 직접 작업 후 merge 금지
리뷰 없이 merge 금지
의미 없는 PR 생성 금지

8. 권장 사항

하루 1회 이상 PR
오래된 브랜치 방치 금지
충돌 발생 시 직접 해결 후 PR

9. 작성예시

예시 1. 챗봇 기능

## 작업 내용
크립토 챗봇 기본 기능 구현

## 변경 사항
- 뉴스 요약 기능 추가
- 감정 분석 결과 반환
- 챗봇 API 연결

## 리뷰 포인트
- 응답 속도 괜찮은지 확인 부탁드립니다
- 감정 분석 결과 정확도 체크해주세요

## 관련 이슈
- PROJ-12

예시 2. 주식 분석 기능

## 작업 내용
주식 데이터 수집 및 기본 분석 기능 구현

## 변경 사항
- 주가 API 연동
- 데이터 전처리 로직 추가
- 매수/매도 감정 계산 로직 구현

## 리뷰 포인트
- 감정 분류 기준이 적절한지 확인 부탁드립니다

## 관련 이슈
- PROJ-18

예시 3. 소비 분석 기능

## 작업 내용
소비 데이터 시각화 기능 구현

## 변경 사항
- 카테고리별 소비 그래프 추가
- 월별 소비 통계 계산 로직 구현

## 리뷰 포인트
- 그래프 UI/UX 자연스러운지 확인 부탁드립니다

## 관련 이슈
- PROJ-25

한 줄 정리

“작게 만들고, 자주 올리고, 리뷰 받고 합친다”

PR = “내 코드 합쳐도 되는지 팀에게 묻는 과정”

팀 프로젝트 시작 전, 반드시 정해야 할 협업 규칙1 (Git)

minaz-rong — Wed, 29 Apr 2026 16:35:59 +0900

1. 깃(Git) 브랜치 전략

최종 브랜치 전략

main                 # 배포용 (직접 수정 금지) 
develop              # 통합 개발 브랜치 
feature/이름-기능    # 기능 개발 브랜치

브랜치 네이밍 (기능 기준 + 사람)

Boo (공병우 - 주식 & 일부 데이터)

feature/boo-stock-data
feature/boo-stock-prediction
feature/boo-stock-news-analysis
feature/boo-stock-sentiment

Min (정민아 - 크립토 + 챗봇 핵심)

feature/min-crypto-price
feature/min-crypto-buzz
feature/min-chatbot-core
feature/min-chatbot-summary
feature/min-chatbot-sentiment

Koo (구도연 - 소비 + 데이터)

feature/koo-consumption-analysis
feature/koo-consumption-visualization
feature/koo-consumption-prediction
feature/koo-recommendation

공통 AI 기능 (중요) - 미정

여기 충돌 많이 남 → 명확히 나눠야 함

feature/ai-common-qa
feature/ai-common-summary

대신 내부 역할 분리

min: 챗봇 UX + 인터페이스
Boo: 주식 데이터 연결
Koo: 소비 데이터 연결

2. 커밋 메시지 컨벤션 (필수 규칙 정리)

팀 프로젝트에서는
커밋 메시지만 보고도 “누가, 무엇을, 왜 했는지” 알 수 있어야 합니다.

1. 기본 구조

type: Subject

type: 작업 종류
Subject: 작업 내용 (간결하게)

2. 예시

feat: 로그인 기능 구현
fix: 회원가입 에러 수정
refactor: 인증 로직 구조 개선

3. 타입 (Type) 정의

feat: 새로운 기능 추가
fix: 버그 수정
docs: 문서 수정 (README 등)
style: 코드 스타일 변경 (기능 영향 없음)
refactor: 코드 구조 개선 (기능 변화 없음)
test: 테스트 코드 추가
chore: 설정, 빌드 등 기타 작업

4. 작성 규칙

한 줄로 간결하게 작성
50자 이내 권장
동사로 시작 (구현, 수정, 추가 등)
불필요한 설명 ❌ (상세 내용은 PR에 작성)

5. 좋은 vs 나쁜 예시

❌ 나쁜 예시

수정
로그인 고침
코드 변경

무엇을 했는지 알 수 없음

✅ 좋은 예시

feat: JWT 기반 로그인 기능 구현
fix: 로그인 시 토큰 만료 오류 수정

작업 내용이 명확함

6. 팀 규칙

커밋 메시지 형식 통일 (반드시 준수)
의미 없는 커밋 메시지 금지
하나의 커밋 = 하나의 작업

2-1. PR 규칙 (초간단 요약)

기본

PR 없이 merge 금지
모든 코드는 PR → develop

방향

feature/* → develop

작성

## 작업 내용
## 변경 사항
## 리뷰 포인트
## 관련 이슈

규칙

팀장 승인 후 merge
PR은 작게 (기능 단위)
하루 1회 이상 PR 권장

금지

main으로 PR ❌
리뷰 없이 merge ❌

PR 작성 내용 (템플릿)

## 작업 내용
챗봇 기본 기능 구현

## 변경 사항
- 뉴스 요약 기능 추가
- 감정 분석 연결

## 리뷰 포인트
- 응답 속도 확인 부탁드립니다

## 관련 이슈
- PROJ-12

빅데이터 분석기사 준비

minaz-rong — Mon, 23 Mar 2026 16:24:44 +0900

빅데이터분석기사 필기 완벽 정리 (시험일 4/4)

✅ 빅데이터분석기사란?

빅데이터분석기사(빅분기)는
데이터를 수집하고, 분석하고, 인사이트를 도출하는 능력을 평가하는 국가기술자격증이다.

쉽게 말하면

“데이터를 활용해서 의미 있는 결과를 만들어내는 능력”을 보는 시험

✅ 시험 구성

✔ 필기 과목 (4과목)

빅데이터 분석 기획
빅데이터 탐색
빅데이터 모델링
빅데이터 결과 해석

객관식 시험
과목당 과락 있음 (40점 미만 탈락)
평균 60점 이상 합격

시험 일정

시험일: 4월 4일 (D-14)

지금 시점 기준
“개념 정리보다 기출 반복이 훨씬 중요”

과목별 핵심 요약

1️⃣ 빅데이터 분석 기획

✔ 빅데이터 특징 (3V)

Volume (데이터 양)
Velocity (속도)
Variety (다양성)

추가 개념

Veracity (정확성)
Value (가치)

✔ 분석 절차 (중요)

문제 정의
데이터 수집
전처리
분석
결과 해석

순서 문제 자주 출제됨

2️⃣ 빅데이터 탐색

✔ 데이터 전처리 (시험 핵심)

결측치 처리 (삭제 / 평균 대체)
이상치 처리
정규화 vs 표준화

차이

정규화: 0~1
표준화: 평균 0, 표준편차 1

✔ EDA (탐색적 분석)

데이터 분포 확인
변수 간 관계 분석
이상치 탐색

3️⃣ 빅데이터 모델링

✔ 지도학습 vs 비지도학습

지도학습: 정답 있음
비지도학습: 정답 없음

✔ 핵심 개념

회귀: 연속값 예측
분류: 범주 예측

✔ 자주 나오는 알고리즘

KNN
의사결정트리
로지스틱 회귀

✔ 과적합 / 언더피팅

과적합: 학습 데이터에만 맞음
언더피팅: 너무 단순

해결 방법

데이터 증가
규제
교차검증

4️⃣ 결과 해석 (모델 평가)

✔ 분류 평가 지표 (⭐ 핵심)

정확도
정밀도
재현율

차이

정밀도: 예측 중 맞은 것
재현율: 실제 중 맞춘 것

✔ F1 Score

정밀도 + 재현율 균형 지표

✔ 회귀 평가 지표

MSE
RMSE
MAE

값이 작을수록 좋음

시험 대비 핵심 전략

✔ 반드시 기억

전처리 = 무조건 나온다
평가 지표 = 무조건 나온다
회귀 vs 분류 = 필수
과적합 = 단골

✔ 공부 방법 (2주 남았을 때)

이게 진짜 중요

기출 3회독
틀린 문제 반복
오답노트 정리

한줄 요약

“빅분기는 기출 반복으로 합격하는 시험이다.”

AI 가구 이미지 생성기 개발기: FastAPI와 Stability AI, S3 연동!

minaz-rong — Fri, 11 Jul 2025 16:22:17 +0900

안녕하세요! 오늘은 Stability AI의 Stable Image Core 모델을 활용하여 가구 이미지를 생성하고, 이를 S3 버킷에 저장하며, 클라이언트가 이미지를 바로 다운로드할 수 있는 FastAPI 기반의 API를 개발한 과정을 공유하려고 합니다. 간단한 이미지 생성 API에서 시작하여 점차 기능을 확장하는 흥미로운 작업이었습니다!

1단계: Stability AI 이미지 생성 기본 API 구축 (초기 코드)

가장 먼저 Stability AI의 text-to-image 기능을 활용하여 프롬프트를 입력하면 이미지를 생성해주는 기본 API를 만들었습니다. FastAPI를 사용하여 엔드포인트를 정의하고, requests 라이브러리로 Stability AI API에 요청을 보냈습니다.

주요 코드 및 설명:

Python

import os
import requests
from dotenv import load_dotenv
from fastapi import FastAPI, Query, HTTPException, Response
from io import BytesIO
from PIL import Image # (현재 코드에서는 직접 사용되지 않지만, 이미지 처리에 유용)

# .env 파일 로드 (API 키 등 민감 정보 관리)
load_dotenv()

# Stability AI API 키 가져오기 및 유효성 검사
STABILITY_KEY = os.getenv("STABILITY_KEY")
if not STABILITY_KEY:
    raise ValueError("STABILITY_KEY not found in .env file. Please set it.")

# FastAPI 애플리케이션 초기화
app = FastAPI(
    title="Furniture Image Generator with Stability AI",
    description="API to generate furniture images using Stability AI's Stable Image Core model.",
    version="1.0.0"
)

# Stability AI에 이미지 생성 요청을 보내는 핵심 함수
def send_generation_request(host: str, params: dict) -> bytes:
    headers = {
        "Accept": "image/*", # 이미지 반환을 기대
        "Authorization": f"Bearer {STABILITY_KEY}" # API 인증
    }
    files = {"none": ''} # Stability AI API의 특정 요구사항
    print(f"Sending REST request to {host} with params: {params}")
    try:
        response = requests.post(host, headers=headers, files=files, data=params)
        response.raise_for_status() # HTTP 오류 발생 시 예외 처리
    except requests.exceptions.RequestException as e:
        raise HTTPException(status_code=500, detail=f"Failed to connect to Stability AI API: {e}")

    output_image = response.content # 생성된 이미지 바이트
    finish_reason = response.headers.get("finish-reason") # 생성 완료 이유 (컨텐츠 필터링 등)

    if finish_reason == 'CONTENT_FILTERED':
        raise HTTPException(status_code=400, detail="Generation failed due to content filter.")

    print(f"Image generated with seed: {response.headers.get('seed')}")
    return output_image

# 가구 이미지 생성을 위한 FastAPI 엔드포인트
@app.post("/generate-furniture", summary="Generate a furniture image", response_description="The generated image")
async def generate_furniture(
    prompt: str = Query(..., description="The prompt for generating the furniture image."),
    negative_prompt: str = Query("", description="Optional: Negative prompt to guide the generation away from certain things."),
    aspect_ratio: str = Query("1:1", description="Aspect ratio of the generated image.",
                               enum=["21:9", "16:9", "3:2", "5:4", "1:1", "4:5", "2:3", "9:16", "9:21"]),
    style_preset: str = Query("None", description="Optional: Style preset to apply to the generation.",
                               enum=["None", "3d-model", "analog-film", "anime", "cinematic", "comic-book", "digital-art", "enhance", "fantasy-art", "isometric", "line-art", "low-poly", "modeling-compound", "neon-punk", "origami", "photographic", "pixel-art", "tile-texture"]),
    seed: int = Query(0, description="Optional: Seed for reproducible generations. Use 0 for random."),
    output_format: str = Query("jpeg", description="Output format of the image.",
                                enum=["webp", "jpeg", "png"])
):
    host = "https://api.stability.ai/v2beta/stable-image/generate/core"
    params = {
        "prompt": prompt,
        "negative_prompt": negative_prompt,
        "aspect_ratio": aspect_ratio,
        "seed": seed,
        "output_format": output_format,
        "mode": "text-to-image"
    }
    if style_preset != "None":
        params["style_preset"] = style_preset

    try:
        image_bytes = send_generation_request(host, params)
        media_type = f"image/{output_format}" # 반환할 이미지의 MIME 타입 결정
        return Response(content=image_bytes, media_type=media_type) # 이미지 바이트 직접 반환
    except HTTPException as e:
        raise e
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"An unexpected error occurred: {e}")

설명:

.env 파일에서 STABILITY_KEY를 로드하여 API 키를 안전하게 관리합니다.
send_generation_request 함수는 Stability AI API에 HTTP POST 요청을 보내고, 생성된 이미지 데이터를 바이트 형태로 반환합니다. 오류 처리 및 콘텐츠 필터링 감지 로직이 포함되어 있습니다.
generate_furniture 엔드포인트는 prompt, negative_prompt, aspect_ratio, style_preset, seed, output_format 등의 파라미터를 받아 Stability AI에 전달하고, 생성된 이미지를 클라이언트에게 직접 반환합니다.

2단계: 생성된 이미지 S3 저장 기능 추가

생성된 이미지를 단순히 반환하는 것을 넘어, AWS S3 버킷에 자동으로 저장하도록 기능을 확장했습니다. 이를 위해 boto3 라이브러리를 추가하고 S3 클라이언트를 설정하는 로직을 통합했습니다.

주요 코드 및 설명 (1단계 코드에서 추가된 부분):

Python

import boto3 # S3 연동을 위한 라이브러리 추가
import uuid # 고유한 파일명 생성을 위한 라이브러리 추가

# ... (기존 코드 유지) ...

# AWS S3 관련 환경 변수 추가
AWS_ACCESS_KEY_ID = os.getenv("AWS_ACCESS_KEY_ID")
AWS_SECRET_ACCESS_KEY = os.getenv("AWS_SECRET_ACCESS_KEY")
S3_BUCKET_NAME = "버킷이름" # 직접 버킷 이름을 하드코딩하거나 .env에서 가져오기

# AWS S3 자격 증명 확인 및 S3 클라이언트 초기화
if not AWS_ACCESS_KEY_ID:
    raise ValueError(".env 파일에 AWS_ACCESS_KEY_ID가 없습니다. 설정해주세요.")
if not AWS_SECRET_ACCESS_KEY:
    raise ValueError(".env 파일에 AWS_SECRET_ACCESS_KEY가 없습니다. 설정해주세요.")
if not S3_BUCKET_NAME:
    raise ValueError(".env 파일에 S3_BUCKET_NAME이 없습니다. 설정해주세요.")

s3_client = boto3.client(
    "s3",
    aws_access_key_id=AWS_ACCESS_KEY_ID,
    aws_secret_access_key=AWS_SECRET_ACCESS_KEY
)

# ... (기존 send_generation_request 함수 유지) ...

# S3에 이미지 업로드하는 비동기 함수 추가
async def upload_image_to_s3(image_bytes: bytes, file_name: str, content_type: str):
    try:
        s3_client.put_object(
            Bucket=S3_BUCKET_NAME,
            Key=file_name, # S3에 저장될 파일명 (경로 포함 가능)
            Body=image_bytes, # 업로드할 이미지 데이터
            ContentType=content_type # 이미지의 MIME 타입
        )
        print(f"S3://{S3_BUCKET_NAME}/{file_name}에 이미지가 성공적으로 업로드되었습니다.")
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"S3에 이미지 업로드에 실패했습니다: {e}")

# generate_furniture 엔드포인트 수정 (S3 업로드 로직 추가)
@app.post("/generate-furniture", summary="가구 이미지를 생성하고 S3에 저장 및 다운로드 제공", response_description="생성된 이미지 및 S3 URL")
async def generate_furniture(
    # ... (기존 파라미터 유지) ...
):
    # ... (기존 host 및 params 설정 유지) ...

    try:
        image_bytes = send_generation_request(host, params)
        media_type = f"image/{output_format}"
        
        folder_name = "furniture" # S3 버킷 내의 폴더명 (선택 사항)
        file_name = f"{folder_name}/furniture_image_{uuid.uuid4()}.{output_format}" # 고유한 파일명 생성

        await upload_image_to_s3(image_bytes, file_name, media_type) # S3에 이미지 업로드

        s3_url = f"https://{S3_BUCKET_NAME}.s3.amazonaws.com/{file_name}" # S3 이미지 URL 생성
        
        # ... (다음 단계에서 추가될 Content-Disposition 헤더 부분은 잠시 생략) ...

        return Response(content=image_bytes, media_type=media_type) # 이미지와 함께 S3 URL을 헤더로 반환하는 것은 아직 안함
    except HTTPException as e:
        raise e
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"예상치 못한 오류가 발생했습니다: {e}")

설명:

boto3 라이브러리를 사용하여 AWS S3와 상호작용합니다.
.env 파일에서 AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, S3_BUCKET_NAME을 가져와 S3 클라이언트를 설정합니다. (코드 예시에서는 S3_BUCKET_NAME이 직접 하드코딩되어 있으니 .env 파일에서 가져오도록 수정하는 것이 좋습니다.)
upload_image_to_s3 비동기 함수는 생성된 이미지 바이트를 지정된 S3 버킷의 특정 경로에 업로드합니다. uuid를 사용하여 파일명 충돌을 방지합니다.
generate_furniture 엔드포인트에서 이미지 생성 후 upload_image_to_s3 함수를 호출하여 이미지를 S3에 저장합니다.

3단계: 다운로드 기능 및 S3 URL 정보 추가

클라이언트가 생성된 이미지를 바로 다운로드할 수 있도록 하고, S3에 저장된 이미지의 URL도 함께 제공하도록 Response 헤더를 수정했습니다.

주요 코드 및 설명 (2단계 코드에서 추가된 부분):

Python

# ... (기존 코드 유지) ...

@app.post("/generate-furniture", summary="가구 이미지를 생성하고 S3에 저장 및 다운로드 제공", response_description="생성된 이미지 및 S3 URL")
async def generate_furniture(
    # ... (기존 파라미터 유지) ...
):
    # ... (기존 host 및 params 설정 유지) ...

    try:
        image_bytes = send_generation_request(host, params)
        media_type = f"image/{output_format}"
        
        folder_name = "furniture" 
        file_name = f"{folder_name}/furniture_image_{uuid.uuid4()}.{output_format}"
        
        await upload_image_to_s3(image_bytes, file_name, media_type)

        s3_url = f"https://{S3_BUCKET_NAME}.s3.amazonaws.com/{file_name}" # S3 이미지 URL 생성
        
        headers = {
            "X-S3-URL": s3_url, # 커스텀 헤더로 S3 URL 정보 제공
            "Content-Disposition": f"attachment; filename=\"{file_name.split('/')[-1]}\"" # 다운로드 파일명 제안
        }
        
        return Response(content=image_bytes, media_type=media_type, headers=headers) # 헤더와 함께 응답
    except HTTPException as e:
        raise e
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"예상치 못한 오류가 발생했습니다: {e}")

설명:

응답 헤더에 X-S3-URL을 추가하여 클라이언트에게 S3에 저장된 이미지의 직접적인 URL을 제공합니다.
Content-Disposition: attachment; filename="..." 헤더를 추가하여 웹 브라우저가 이 응답을 다운로드 가능한 파일로 인식하고, 제안된 파일명으로 저장하도록 유도합니다. file_name.split('/')[-1]을 사용하여 폴더명 없이 실제 파일명만 filename에 넣도록 개선했습니다.

.env 파일 설정 가이드

API를 실행하기 전에 프로젝트 루트 디렉터리에 .env 파일을 생성하고 다음 정보를 입력해야 합니다.

코드 스니펫

STABILITY_KEY="YOUR_STABILITY_AI_API_KEY"
AWS_ACCESS_KEY_ID="YOUR_AWS_ACCESS_KEY_ID"
AWS_SECRET_ACCESS_KEY="YOUR_AWS_SECRET_ACCESS_KEY"
S3_BUCKET_NAME="버킷이름" # 여러분의 S3 버킷 이름

YOUR_STABILITY_AI_API_KEY: Stability AI에서 발급받은 API 키
YOUR_AWS_ACCESS_KEY_ID: AWS Access Key ID
YOUR_AWS_SECRET_ACCESS_KEY: AWS Secret Access Key
S3_BUCKET_NAME: 사용할 S3 버킷의 이름 (코드에 하드코딩되어 있으나, .env에 정의하는 것이 더 권장됩니다.)

️ 애플리케이션 실행 방법

필수 라이브러리 설치:

Bash

uv pip install fastapi uvicorn python-dotenv requests pillow boto3

파이썬 파일 저장: 위의 모든 코드를 main.py와 같은 이름으로 저장합니다.
애플리케이션 실행: 터미널에서 다음 명령어를 실행합니다.(--reload 옵션은 코드 변경 시 자동으로 서버를 재시작해 개발에 편리합니다.)

Bash

uvicorn main:app --host 0.0.0.0 --port 3002

사용 예시 (API 요청)

FastAPI 서버가 실행되면, http://localhost:3002/docs로 접속하여 Swagger UI를 통해 API를 테스트할 수 있습니다. generate-furniture 엔드포인트에 POST 요청을 보낼 때 다음과 같은 JSON 본문을 사용할 수 있습니다.

JSON

{
  "prompt": "Single wooden style chair, top-down view, 2D, empty surface, transparent background, clean lines, clear details, studio lighting, size 70x70mm",
  "negative_prompt": "realistic, blurry, distorted, old, dark, ugly, complex background, busy background, shadows, textures, multiple objects, cropped, cut off, low resolution, 3d render, photographic, realistic shading, harsh lines, text, watermark",
  "aspect_ratio": "1:1",
  "style_preset": "None",
  "seed": 0,
  "output_format": "png"
}

(참고: size 1000x800mm과 같은 구체적인 픽셀 크기는 AI 모델이 직접적으로 제어하기 어렵고, aspect_ratio가 주된 비율 제어 수단입니다. 하지만 프롬프트에 포함하여 모델이 참고하도록 할 수는 있습니다.)

이미지 생성 매개변수 설명

"prompt": "Single wooden style chair, top-down view, 2D, empty surface, transparent background, clean lines, clear details, studio lighting, size 70x70mm"
- 이것은 **생성하고자 하는 이미지에 대한 긍정적인 지시(Positive Prompt)**입니다. AI에게 어떤 이미지를 만들지 구체적으로 설명하는 부분이죠.
- 여기서는 "단일 목재 스타일 의자", "위에서 본 모습(탑다운 뷰)", "2D", "빈 표면", "투명한 배경", "깔끔한 선", "선명한 디테일", "스튜디오 조명", "70x70mm 크기"를 포함하라는 지시가 담겨 있습니다. 즉, 쇼핑몰 상세 페이지나 디자인 작업에 활용할 법한 깔끔한 목재 의자 이미지를 요청하고 있다고 볼 수 있습니다.
"negative_prompt": "realistic, blurry, distorted, old, dark, ugly, complex background, busy background, shadows, textures, multiple objects, cropped, cut off, low resolution, 3d render, photographic, realistic shading, harsh lines, text, watermark"
- 이것은 **생성하지 않기를 바라는 이미지 특징에 대한 지시(Negative Prompt)**입니다. AI가 프롬프트 내용에 집중하도록 방해 요소를 제거하는 역할을 합니다.
- "사실적인(realistic)", "흐릿한(blurry)", "왜곡된(distorted)", "오래된(old)", "어두운(dark)", "못생긴(ugly)", "복잡한 배경(complex background)", "바쁜 배경(busy background)", "그림자(shadows)", "텍스처(textures)", "여러 객체(multiple objects)", "잘린(cropped), "잘려나간(cut off)", "저해상도(low resolution)", "3D 렌더(3d render)", "사진 같은(photographic)", "사실적인 음영(realistic shading)", "거친 선(harsh lines)", "텍스트(text)", "워터마크(watermark)" 등, 원치 않는 결과물 요소를 명확히 지정하여 깔끔하고 특정 스타일에 맞는 이미지가 나오도록 유도합니다.
"aspect_ratio": "1:1"
- 생성될 이미지의 가로세로 비율을 나타냅니다. "1:1"은 정사각형 이미지를 의미합니다. 다른 옵션으로는 "16:9", "4:3" 등이 있을 수 있습니다.
"style_preset": "None"
- 이미지 생성에 적용할 사전 설정 스타일을 의미합니다. "None"은 특별한 스타일 프리셋을 적용하지 않고, 프롬프트 지시에 따라 이미지를 생성하겠다는 뜻입니다. 일반적으로 "photographic", "anime", "digital-art" 등 다양한 스타일 옵션이 있습니다.
"seed": 0
- 이미지 생성의 재현성을 위한 시드(Seed) 값입니다. AI 모델이 이미지를 생성할 때 초기 노이즈 패턴을 결정하는 숫자입니다.
- 0으로 설정하면 매번 다른 무작위 이미지를 생성합니다. 만약 특정 시드 값을 사용하면, 동일한 프롬프트로 이미지를 다시 생성했을 때 거의 동일한 결과물을 얻을 수 있습니다. 이는 특정 이미지를 기반으로 미세 조정하거나 여러 번 시도할 때 유용합니다.
"output_format": "png"
- 생성될 이미지의 파일 형식을 나타냅니다. 여기서는 "png"로 설정되어 있으며, 이는 투명한 배경을 지원하는 형식이기 때문에 "transparent background" 프롬프트와 잘 어울립니다. 다른 옵션으로는 "jpeg", "webp" 등이 있을 수 있습니다.

가구 이미지 생성 시 발생하는 이슈 및 프롬프트 개선 방안

Stability AI를 통해 가구 이미지를 생성할 때 발생할 수 있는 일반적인 문제점과 이를 프롬프트 수정을 통해 어떻게 해결했는지 상세히 설명해 드릴게요.

발생했던 주요 문제점

초기에 가구 이미지를 생성했을 때 다음과 같은 원치 않는 결과물이 나왔습니다.

사람이 추가됨: 가구 이미지에 사람이 함께 생성되어 가구 자체에 집중하기 어려웠습니다.
가구 위에 다른 물건이 올라가 있음: 의자 위에 책이나 다른 장식품 등이 놓여 있어 가구의 순수한 형태를 확인하기 어려웠습니다.
여러가구가 같이 추출: 가구 하나가 아닌 방의 이미지가 추출되어, 용도에 맞지 않는 사진이 계속해서 추출되었습니다.
가구 여러 개가 같이 붙어있거나 이미지가 이상하게 추출됨: 단일 가구를 원했지만, 여러 개의 가구가 붙어있거나 형태가 왜곡되어 생성되는 경우가 있었습니다. 이는 제품 이미지로 활용하기에 부적합했습니다.

잘못추출된 가구들

프롬프트 개선을 통한 해결 방안

이러한 문제들을 해결하기 위해 다음과 같이 **prompt (긍정 프롬프트)**와 **negative_prompt (부정 프롬프트)**를 상세하게 조정했습니다.

1. prompt (긍정 프롬프트) 수정

목표: 순수한 가구 이미지, 특정 뷰, 깨끗한 배경 등 원하는 요소를 명확히 지시하여 AI가 정확히 그릴 수 있도록 유도했습니다.

수정 내용:

"Single wooden style chair": "단일(Single)"이라는 단어를 추가하여 여러 개의 가구가 아닌 하나만 생성되도록 명확히 했습니다.
"top-down view, 2D": 가구의 특정 시점(위에서 내려다본 시점)과 그림 스타일(2D)을 지정하여 예측 가능하고 균일한 결과물을 얻도록 했습니다.
"empty surface": 가구 위에 아무것도 없는 깨끗한 상태를 명시하여 불필요한 물건이 올라가지 않도록 지시했습니다.
"transparent background": 배경을 투명하게 요청하여 가구 자체를 깔끔하게 분리하고, 추후 편집 용이성을 높였습니다.
"clean lines, clear details, studio lighting": 이미지의 품질과 스타일을 높이기 위해 깔끔한 선, 선명한 디테일, 전문적인 스튜디오 조명을 요구했습니다.
"size 70x70mm": 특정 크기를 명시하여 제품 이미지 규격에 맞는 출력을 유도했습니다 (물론 AI가 물리적 크기를 정확히 맞추기보다는 그 비율과 느낌을 참고합니다).

개선된 prompt: "Single wooden style chair, top-down view, 2D, empty surface, transparent background, clean lines, clear details, studio lighting, size 70x70mm"

2. negative_prompt (부정 프롬프트) 수정

목표: 원치 않는 요소(사람, 추가 물건, 복잡한 배경, 왜곡 등)를 명시적으로 제거하여 AI가 생성 과정에서 해당 요소를 회피하도록 지시했습니다.

수정 내용:

"realistic, photographic, 3d render, realistic shading": 불필요한 현실감이나 사진 같은 느낌, 3D 렌더링 효과를 제외하여 2D 스타일에 집중하도록 했습니다.
"complex background, busy background, shadows, textures": 깔끔하고 투명한 배경을 위해 복잡하거나 방해되는 배경, 불필요한 그림자나 텍스처를 배제했습니다.
"multiple objects, text, watermark": 여러 개의 객체(가구 또는 기타 물건)가 생성되는 것을 방지하고, 이미지에 텍스트나 워터마크가 포함되지 않도록 했습니다.
"blurry, distorted, old, dark, ugly, cropped, cut off, low resolution, harsh lines": 이미지 품질을 저하시키는 흐릿함, 왜곡, 저해상도, 거친 선 등을 사전에 차단했습니다.

개선된 negative_prompt: "realistic, blurry, distorted, old, dark, ugly, complex background, busy background, shadows, textures, multiple objects, cropped, cut off, low resolution, 3d render, photographic, realistic shading, harsh lines, text, watermark"

이번 작업을 통해 AI 이미지 생성 API를 구축하고, AWS S3와의 연동, 그리고 사용자 친화적인 파일 다운로드 기능을 구현하는 전반적인 과정을 경험할 수 있었습니다. 특히, 프롬프트 엔지니어링을 통해 '아기자기한 일러스트'와 '탑 뷰', '배경 제거'와 같은 특정 요구사항을 이미지에 반영하는 과정이 흥미로웠습니다.

다음에는 생성된 이미지를 웹 서비스에 바로 활용하거나, 더 복잡한 이미지 처리 기능을 추가하는 방향으로 확장해볼 예정입니다. 긴 글 읽어주셔서 감사합니다!

공공데이터포털에서 아파트 평면도 이미지 불러오기: 파이썬으로 자동화하기

minaz-rong — Thu, 10 Jul 2025 21:32:56 +0900

안녕하세요! 이번 포스팅에서는 공공데이터포털에서 제공하는 아파트 평면도 이미지를 파이썬을 이용해 자동으로 불러오고 PNG 파일로 변환하는 방법에 대해 알아보겠습니다. 부동산 관련 데이터를 분석하거나, 건축/인테리어 분야에서 평면도 이미지가 필요한 경우 유용하게 활용할 수 있는 팁입니다.

1. 공공데이터포털이란?

공공데이터포털은 정부 및 공공기관이 보유한 다양한 공공데이터를 한곳에 모아 국민에게 개방하는 서비스입니다. 이곳에서 제공하는 데이터는 누구나 자유롭게 이용할 수 있으며, API 형태로 제공되는 경우도 많아 개발자들이 프로그램으로 쉽게 접근할 수 있습니다.

2. 왜 아파트 평면도 이미지를 불러와야 할까요?

데이터베이스 구축: 자체적인 평면도 이미지 데이터베이스를 구축하여 다양한 서비스에 활용할 수 있습니다. 특히 전 가구를 배치하는 용도로 평면도를 이용하려 하였습니다

3. 공공데이터포털에서 사용된 데이터 개요

이번 포스팅에서 사용된 데이터는 공공데이터포털의 "한국토지주택공사 주택 평면도 현황" 데이터셋입니다. 이 데이터셋은 한국토지주택공사(LH)가 관리하는 주택(공공분양, 공공임대 등)의 평면도 정보를 JSON(이미지 파일 변환) 형태로 제공합니다.

데이터셋 명칭: 한국토지주택공사 주택 평면도 현황
제공 기관: 한국토지주택공사
데이터 유형: JSON (내부에 Base64 인코딩된 이미지 포함)
설명: 평면도는 집의 구조적 모습을 보기 위해 수평으로 나타내어진 그림입니다.
최신 업데이트: 2024년 12월 18일 (수정일 기준)
누적 다운로드: 13953회 (주간 다운로드 3872회)
이용 허락 범위: 공공누리 제1유형 (출처표시)

이 데이터셋은 연도별, 지역별로 구분되어 있으며, 각 폴더 내에 개별 평면도에 대한 JSON 파일이 포함되어 있습니다. 각 JSON 파일은 평면도 이미지를 Base64 문자열 형태로 담고 있어, 이를 파이썬 코드로 추출하고 변환하는 과정이 필요합니다.

4. 파이썬 코드로 평면도 이미지 불러오기 및 변환하기

공공데이터포털의 API를 통해 평면도 데이터를 요청하면, 이미지 데이터가 Base64 문자열 형태로 JSON 응답에 포함되어 있는 경우가 많습니다. 이 Base64 문자열을 디코딩하여 실제 이미지 파일(PNG)로 저장하는 과정이 필요합니다.

아래 코드는 이러한 과정을 자동화하는 예시입니다. 이 코드는 특정 JSON 파일에 Base64 인코딩된 이미지 데이터가 포함되어 있다고 가정하고, 해당 데이터를 추출하여 PNG 파일로 저장합니다. 공공데이터포털에서 직접 API를 호출하여 JSON 응답을 받는 부분은 API마다 구조가 다르므로, 해당 API의 문서를 참고하여 requests 라이브러리로 호출하는 코드를 추가해야 합니다.
json 파일의 형태에 따라 추출하는 방식이 달라 코드를 두가지 사용하여 png 파일로 변환하였습니다

특정 JSON 구조 (예: 59A.json 형태) 추출 코드 설명

단일 JSON 파일, 예를 들어 59A.json과 같은 파일에서 Base64 인코딩된 이미지 데이터를 추출하여 PNG로 변환하는 데 사용될 수 있습니다. 이 코드는 특히 JSON 파일 내에서 Base64 문자열이 어떤 키에 포함되어 있는지에 대한 여러 시나리오를 처리하도록 설계되었습니다.

import json
import base64
import os
# re 모듈은 이 특정 코드 스니펫에는 사용되지 않았지만,
# 일반적으로 Base64 데이터 URI 접두사를 처리하는 데 유용합니다.
# 이 코드 스니펫에서는 'base64,' 문자열을 기준으로 직접 분할합니다.

# 59A.json 파일 경로 지정
# 현재 작업 디렉토리(os.getcwd()) 아래 'floorplan_json' 폴더에 '59A.json' 파일이 있다고 가정합니다.
json_path = os.path.join(os.getcwd(), 'floorplan_json', '59A.json')

# 저장할 폴더 및 파일 경로 지정
# 현재 작업 디렉토리 아래 'floorplan_image' 폴더에 '59A.png'로 저장할 경로를 정의합니다.
output_dir = os.path.join(os.getcwd(), 'floorplan_image') 
output_png = os.path.join(output_dir, '59A.png')

# 폴더가 없으면 생성
# 이미지를 저장할 'floorplan_image' 폴더가 존재하지 않으면 새로 생성합니다.
os.makedirs(output_dir, exist_ok=True)

# JSON 파일 열기
# 지정된 경로의 JSON 파일을 읽기 모드('r')로 열고, UTF-8 인코딩을 사용합니다.
# 'with' 문을 사용하여 파일이 자동으로 닫히도록 합니다.
with open(json_path, 'r', encoding='utf-8') as f:
    # json.load(f)를 사용하여 파일 객체 f에서 JSON 데이터를 로드하여 파이썬 딕셔너리 'data'에 저장합니다.
    data = json.load(f)

# base64 문자열 추출 (구조에 따라 경로 수정 필요)
# JSON 'data' 딕셔너리에서 Base64 문자열을 찾습니다.
if 'data' in data:
    # 만약 'data' 키가 최상위에 직접 존재하면 그 값을 Base64 문자열로 사용합니다.
    base64_str = data['data']
elif 'image' in data and '@attributes' in data['image'] and 'xlink:href' in data['image']['@attributes']:
    # 만약 'image' -> '@attributes' -> 'xlink:href' 경로에 Base64 문자열이 있다면 그 값을 사용합니다.
    # 이는 SVG 이미지 데이터에서 흔히 볼 수 있는 구조입니다.
    base64_str = data['image']['@attributes']['xlink:href']
else:
    # 위의 두 가지 일반적인 경로에서 Base64 문자열을 찾지 못했을 경우,
    # 딕셔너리의 모든 최상위 값들을 순회하며 'base64,' 문자열을 포함하는 첫 번째 문자열을 찾습니다.
    base64_str = None
    for value in data.values():
        if isinstance(value, str) and 'base64,' in value:
            base64_str = value
            break # 찾으면 루프를 종료합니다.
    if base64_str is None:
        # Base64 문자열을 끝까지 찾지 못하면 ValueError를 발생시킵니다.
        raise ValueError('Base64 문자열을 찾을 수 없습니다.')

# 'base64,' 이후 부분만 추출
# Base64 문자열에 'base64,' 접두사가 포함되어 있다면, 이 접두사를 제거하고 실제 Base64 데이터만 추출합니다.
if 'base64,' in base64_str:
    base64_data = base64_str.split('base64,')[1]
else:
    # 접두사가 없다면 Base64 문자열 전체를 사용합니다.
    base64_data = base64_str

# 디코딩 및 PNG 파일로 저장
# Base64 데이터를 바이너리 형식으로 디코딩합니다.
# 디코딩된 데이터를 'output_png' 경로에 바이너리 쓰기 모드('wb')로 PNG 파일로 저장합니다.
with open(output_png, 'wb') as img_file:
    img_file.write(base64.b64decode(base64_data))

# 이미지 저장 완료 메시지 출력
print(f'이미지 저장 완료: {output_png}')

특정 JSON 구조 (예: 84C.json 형태) 추출 코드 설명

공공데이터포털에서 제공하는 일부 JSON 파일은 이미지 데이터가 {"image": {"mime": "image/png", "data": "..."}}와 같은 특정 구조로 포함되어 있습니다. 특히 data 키의 값이 Base64 인코딩된 이미지 문자열인 경우, 이를 직접 추출하여 PNG 파일로 변환할 수 있습니다. 아래 코드는 이러한 형태의 JSON 파일을 처리하는 데 사용됩니다.

import json # JSON 데이터 처리를 위한 모듈
import base64 # Base64 인코딩/디코딩을 위한 모듈
import re # 정규 표현식 사용을 위한 모듈
import os # 파일 시스템 경로 조작을 위한 모듈

# 84C.json 파일 경로 지정
# 현재 작업 디렉토리(os.getcwd()) 아래 'floorplan_json' 폴더에 '84C.json' 파일이 있다고 가정합니다.
json_path = os.path.join(os.getcwd(), 'floorplan_json', '84C.json')

# 저장할 폴더 및 파일 경로 지정
# 현재 작업 디렉토리 아래 'floorplan_image' 폴더에 '84C.png'로 저장할 경로를 정의합니다.
output_dir = os.path.join(os.getcwd(), 'floorplan_image') 
output_png = os.path.join(output_dir, '84C.png')

# 폴더가 없으면 생성
# 이미지를 저장할 'floorplan_image' 폴더가 존재하지 않으면 새로 생성합니다.
os.makedirs(output_dir, exist_ok=True)

# JSON 파일 열기 및 전체 텍스트 읽기
# 지정된 경로의 JSON 파일을 읽기 모드('r')로 열고, UTF-8 인코딩을 사용합니다.
# 'with' 문을 사용하여 파일이 자동으로 닫히도록 합니다.
with open(json_path, 'r', encoding='utf-8') as f:
    # f.read()를 사용하여 파일의 전체 내용을 문자열로 읽어와 'json_text' 변수에 저장합니다.
    # 이는 JSON 파싱 전에 특정 패턴을 검색하기 위함입니다.
    json_text = f.read()

# "data":" 다음부터 마지막 따옴표(") 또는 작은따옴표(') 전까지 추출 (줄바꿈 포함)
# re.search()를 사용하여 'json_text'에서 특정 정규 표현식 패턴을 검색합니다.
# r'"data"\s*:\s*["\']([^"\']+)["\']' 패턴 설명:
#   - '"data"\s*:\s*': "data" 문자열, 콜론(:), 그리고 그 사이에 있을 수 있는 공백(\s*)을 찾습니다.
#   - '["\']': 큰따옴표(") 또는 작은따옴표(') 중 하나를 찾습니다.
#   - '([^"\']+)': 이 부분이 핵심입니다. 큰따옴표나 작은따옴표를 제외한 모든 문자(.)가 하나 이상(+) 반복되는 것을 캡처 그룹으로 지정합니다.
#     이는 Base64 데이터가 포함된 부분입니다. 줄바꿈 문자도 포함될 수 있습니다.
#   - '["\']': 닫는 큰따옴표(") 또는 작은따옴표(')를 찾습니다.
match = re.search(r'"data"\s*:\s*["\']([^"\']+)["\']', json_text)
if not match:
    # 만약 패턴을 찾지 못했다면, Base64 문자열을 찾을 수 없다는 ValueError를 발생시킵니다.
    raise ValueError('"data":" 다음에 base64 문자열을 찾을 수 없습니다.')

# match.group(1)은 정규 표현식의 첫 번째 캡처 그룹(즉, Base64 데이터 부분)을 반환합니다.
base64_data = match.group(1)

# base64 디코딩 및 이미지 파일로 저장
# base64.b64decode()를 사용하여 Base64 데이터를 바이너리 형식으로 디코딩합니다.
# 디코딩된 데이터를 'output_png' 경로에 바이너리 쓰기 모드('wb')로 PNG 파일로 저장합니다.
with open(output_png, 'wb') as img_file:
    img_file.write(base64.b64decode(base64_data))

# 이미지 저장 완료 메시지 출력
print(f'이미지 저장 완료: {output_png}')

위 코드를 이용하여 아파트 평면도를 추출하였습니다.