[2026.02.07]

주제: 시스템 아키텍처(DFD) 설계 및 배포 환경 트러블슈팅

1. 이원화된 시스템 아키텍처 수립

팀장님의 SDXL 파이프라인과 본인의 FLUX 파이프라인을 통합한 전체 시스템의 데이터 흐름도(Data Flow Diagram)를 설계하였다.

특히 FLUX 트랙에서는 물리 RAM의 한계를 극복하기 위해 Swap Memory(NVMe SSD)를 활용한 OOM 방지 메커니즘과 Bfloat16 정밀도 최적화 과정을 명시적으로 시각화하여 기술적 차별성을 강조하였다.

설계의 핵심:
- Track A (High Quality): SDXL + ControlNet 기반
- Track B (Fast Inference): FLUX.2-klein-4B 기반 (본인 담당, Swap I/O 기술 적용)

flowchart TD
    %% 1. 사용자 및 입력 단계
    User((사용자))
    
    subgraph Frontend ["프론트엔드 (Client)"]
        UI_Input[1. 이미지/텍스트/스타일 입력]
        UI_Mode[2. 생성 모드 선택]
        UI_Logic[3. API 요청 생성]
    end

    %% 2. 백엔드 처리 단계
    subgraph Backend ["FastAPI 백엔드 (Server)"]
        Router{"4. 모델 라우팅 (Mode)"}
        
        %% [Data Store 1] 팀장님 DB
        DB[(D1: 스타일/프롬프트 DB)]
        
        %% [Data Store 2] Swap Memory (핵심 인프라)
        Swap[(D2: Swap Memory<br/>NVMe SSD 32GB)]
        
        %% [Track A] SDXL 파이프라인 (High Quality)
        subgraph Track_SDXL ["🅰️ SDXL 파이프라인 (Detail)"]
            Preprocess["5-1. 전처리 (Resize/Canny)"]
            PromptMgr["5-2. 프롬프트 매니징"]
            SDXL_Engine["5-3. SDXL + ControlNet 엔진"]
        end
        
        %% [Track B] Flux 파이프라인 (Efficiency)
        subgraph Track_Flux ["🅱️ Flux 파이프라인 (System)"]
            %% 트러블슈팅: Config/Tokenizer 복구 및 Bfloat16 최적화
            Flux_Pre["5-1. 리소스 로드 & 최적화<br/>(Config/Tokenizer/BF16)"]
            
            %% 핵심 추론 엔진
            Flux_Core["5-2. Flux.2 DiT 추론<br/>(4-Step Fast Inference)"]
            
            %% 후처리
            Flux_Post["5-3. VAE 디코딩<br/>(Latent to Pixel)"]
        end
    end

    %% 3. 출력 단계
    Output[("6. 최종 광고 이미지")]

    %% 흐름 연결
    User --> UI_Input
    UI_Input --> UI_Mode
    UI_Mode --> UI_Logic
    UI_Logic -->|"POST /generate/..."| Router
    
    %% 라우팅 분기
    Router -->|"Mode: Quality (SDXL)"| Preprocess
    Router -->|"Mode: Simple (Flux)"| Flux_Pre
    
    %% [Track A] 흐름
    DB -.->|"스타일 조회"| PromptMgr
    Preprocess --> PromptMgr
    PromptMgr --> SDXL_Engine
    SDXL_Engine --> Output
    
    %% [Track B] 흐름 (Swap I/O 강조)
    Flux_Pre --> Flux_Core
    Flux_Core <-->|"Swap I/O<br/>(OOM 방지)"| Swap
    Flux_Core --> Flux_Post
    Flux_Post --> Output
    
    Output --> User

2. [Troubleshooting] 배포 환경의 모듈 경로 충돌 및 해결

Windows(Local)에서 Linux(GCP)로 코드를 이관하는 과정에서 파이썬 모듈 인식 실패(ModuleNotFoundError: No module named 'flux2') 에러가 발생하여 서비스 구동이 중단됨.

원인 분석:
- 로컬 개발 환경과 달리, 리눅스 쉘 환경에서는 flux2 모듈이 위치한 src 디렉토리를 파이썬 인터프리터가 자동으로 인식하지 못함.
- 또한, 모델 가중치 경로를 명시하지 않을 경우 HuggingFace에서 대용량 파일을 재다운로드하려는 시도가 발생하여 스토리지 낭비 우려.

기술적 해결:

소스 코드(server.py)를 수정하여 경로를 하드코딩하는 대신, 환경변수 주입을 통해 런타임 환경을 제어함.
PYTHONPATH를 확장하여 모듈 인식 문제를 해결하고, 로컬 모델 경로를 환경변수로 강제 지정하여 외부 네트워크 요청을 차단함.

Deployment Configuration Script (Bash)

GCP 인스턴스에서 서버 구동 전 필수 실행 스크립트

# 1. 모듈 경로 인식 해결 (src 폴더를 파이썬 경로에 추가)
export PYTHONPATH=$PYTHONPATH:$(pwd)/src

# 2. 로컬 모델 가중치 강제 사용 (인터넷 다운로드 차단)
# 설명: $(pwd)는 현재 폴더 위치를 자동으로 채워주는 명령어입니다.
export FLUX_MODEL_PATH=$(pwd)/models/flux-2-klein-4b.safetensors
export AE_MODEL_PATH=$(pwd)/models/ae.safetensors
export TE_MODEL_PATH=$(pwd)/models/hub/models--Qwen--Qwen3-4B-FP8

3. 서비스 배포 결과

포트 개방: GCP 방화벽 인바운드 규칙(TCP:8000) 적용 확인.
접속 테스트: 공인 IP(35.226.245.91:8000/docs)를 통해 Swagger UI 접근 성공.
성과: 외부망에서 T2I/I2I 기능이 정상 동작함을 확인하였으며, 이를 통해 팀 내 프론트엔드 연동 준비를 완료함.

[2026.02.07]

1. 이원화된 시스템 아키텍처 수립

2. [Troubleshooting] 배포 환경의 모듈 경로 충돌 및 해결

3. 서비스 배포 결과

[2026.02.09]