ㄹㅎ
좋습니다 YG님,
말씀하신 두 가지 포인트를 반영하여 아래와 같이 문서를 완전 보완 버전으로 재구성했습니다:
보완사항 반영:
1. 전체 처리 플로우도 마크다운 플로우로 시각화
2. A안/B안에 대한 장단점을 개발 단계와 운영 단계로 나누어 명확히 정리
3. 기존 메시지 스키마, 샘플 메시지, 이미지 처리 흐름도 포함
⸻
[Kafka 기반 이미지 메타데이터 처리 시스템 - 아키텍처 및 메시지 정의 문서]
⸻
1. 문서 목적
• Kafka 기반 이미지/메타데이터 처리 구조 정의
• FastAPI 및 FastStream 기반 아키텍처 구성안 제시
• Kafka 메시지 구조 표준화
• 이미지 저장 방식 및 처리 위치 설계 기준 마련
⸻
2. 전체 처리 플로우
[사용자 or Airflow]
↓
[HTTP 요청 or DAG 실행]
↓
[POST 서버 또는 ETL 노드]
└─ 이미지 저장 or presigned URL 발급
↓
[Kafka 메시지 발행]
↓
[Kafka 브로커]
↓
[Kafka Consumer (FastStream)]
├─ 이미지 저장 (MinIO)
└─ 메타데이터 색인 (OpenSearch)
⸻
3. 아키텍처 구성안 비교
✅ A안 – 단일 서버 구조 (FastAPI + FastStream 통합)
• 모든 기능이 하나의 앱 내에서 동작
• 요청 수신, Kafka 송신, 메시지 처리 및 저장까지 단일 프로세스 처리
장점 및 단점
항목 장점 단점
개발 단계 - 구조 단순, 빠른 MVP 구현 가능- 디버깅/테스트 일관성 높음 - 관심사 분리 미약- 기능 확장 시 구조 혼잡 가능
운영 단계 - 배포 단순- 장애 시 전체 로직 함께 추적 가능 - 장애 발생 시 전체 서비스 중단 위험- 수평 확장 어려움
⸻
✅ B안 – 분리 서버 구조 (POST 서버 + Kafka Processor)
• 요청 수신과 메시지 처리를 마이크로서비스 형태로 분리
• Kafka를 경계로 역할 분리
장점 및 단점
항목 장점 단점
개발 단계 - 역할별 책임 명확- 팀 간 분업에 적합 - 통신 포맷 설계 필요- 로컬 테스트/모킹 복잡
운영 단계 - 장애 격리 용이- 서비스 단위로 스케일링 가능 - 모니터링/트레이싱 복잡- 배포 환경 복잡도 증가
⸻
4. Kafka 메시지 스키마 표준안
필드 정의
필드명 타입 필수 설명
filename string ✅ 이미지 파일명
image_path string ⭕ 저장된 경로 (Base64 미사용 시)
image_base64 string ⭕ 이미지 내용 (Base64 인코딩)
content_type string ✅ MIME 타입 (예: image/png)
uploaded_at ISO datetime ✅ 업로드 시간
tags array[string] ⭕ 태그 정보
source string ✅ 생성 주체 (예: api, airflow)
checksum string ⭕ 무결성 확인용
user_id string ⭕ 사용자 ID
request_id string ⭕ 요청 추적용 UUID
ocr_status string ⭕ OCR 처리 상태 (예: pending)
schema_version int ✅ 스키마 버전 (예: 1)
⸻
샘플 메시지 (Base64 포함)
{
"filename": "img_20250415.png",
"image_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
"content_type": "image/png",
"uploaded_at": "2025-04-15T11:00:00Z",
"tags": ["invoice", "ocr"],
"source": "airflow",
"checksum": "c284fd0934af...",
"user_id": "u12345",
"request_id": "req_98d21",
"schema_version": 1
}
⸻
샘플 메시지 (파일 경로 기반)
{
"filename": "img_20250415.png",
"image_path": "/mnt/images/img_20250415.png",
"content_type": "image/png",
"uploaded_at": "2025-04-15T11:00:00Z",
"tags": ["invoice", "ocr"],
"source": "airflow",
"checksum": "c284fd0934af...",
"user_id": "u12345",
"request_id": "req_98d21",
"schema_version": 1
}
⸻
5. 이미지 저장 방식별 흐름 정의
A안: Kafka에 이미지(base64) 직접 포함
사용자
↓
POST API 요청 (base64 포함)
↓
Kafka 메시지 발행
↓
Consumer에서 base64 디코딩
↓
MinIO에 업로드
⸻
B안: Kafka에 이미지 경로만 포함
Airflow/POST 서버 → 이미지 저장
↓
Kafka 메시지에 경로 포함
↓
Consumer가 파일 읽어 MinIO에 업로드
⸻
C안: Presigned URL 방식
POST 서버 → presigned URL 발급
↓
사용자 → MinIO 직접 업로드
↓
Kafka 메시지에 URL 포함
↓
Consumer가 URL 통해 다운로드 (선택)
⸻
6. 의사결정이 필요한 항목
항목 질문 결정 포인트
Kafka에 이미지 포함 여부 base64로 보낼지? 경로만 전달할지? 메시지 크기, 브로커 부담
이미지 저장 위치 Kafka 미포함 시 어디에 사전 저장할지? POST 서버 / ETL / MinIO
메시지 구조 확정 확장 필드(유저, 추적 ID 등) 포함 여부 멀티 테넌시 및 디버깅 전략
구조 선택 A안 vs B안 무엇을 우선 적용할지 초기 운영 전략 기반 결정
⸻
7. 회의 목표 요약
• 아키텍처 A안 vs B안 구조 확정 또는 단계적 도입 결정
• Kafka 메시지 구조 및 스키마 표준안 공유
• 이미지 저장 방식 및 처리 위치 협의
• 시스템 초기 운영 설계 방향 논의
⸻
Note:
본 문서는 입력 방식 및 처리 방식이 유동적인 상황에서
확장성과 운영성을 고려한 아키텍처 선택과 메시지 표준을 정의하기 위한 협의 문서입니다.
⸻
필요하시면 .md, .docx, 또는 HTML 포맷으로도 변환해드릴 수 있습니다.
또 Mermaid 시각화도 필요하시면 병행해드릴게요.
이 문서로 회의 준비는 완성된 상태예요. 혹시 추가하고 싶은 항목 있으실까요?