🌍 ESG 공급망 리스크 모니터링 플랫폼

글로벌 알루미늄 업스트림 공급망(추출~성형)의 ESG 리스크를 실시간으로 모니터링하고, 하이브리드 RAG 기반 AI 추론으로 협력사별 리스크를 등급 분류·시각화하는 플랫폼입니다.

---

🏗️ 시스템 아키텍처

레이어	구성	핵심 역할
Frontend	React, Vite, Recharts, Tailwind CSS (nginx 서빙)	공급망 맵 동적 렌더링, 토큰 기반 인증, 실시간 알림 피드
Backend (통합 FastAPI)	FastAPI(Python 3.12), Pydantic, WebSocket, Google Vision API	회원/협력사/공급망 API, 세션 관리(Redis), 파일 업로드·OCR, 2차 보안 인증 + AI 파이프라인 내장
Message Broker	Kafka, Gmail API	이벤트 큐 처리, 협력사 초대 및 2차 보안 인증 메일 발송
Data & AI Pipeline	FastAPI(BackgroundTasks), Ollama(Gemma), HuggingFace, BGE-M3, Cross-Encoder	룰 기반 1차 스크리닝, 하이브리드 RAG 추론 — Airflow 없이 백엔드 안에서 직접 실행 (동시 실행 락·단계별 런 상태 추적)
Data Store	PostgreSQL(pgvector), MariaDB, Redis	ESG 규제 벡터 DB, 세션 캐시/인증 코드, 31개 테이블 구성
DevOps & Platform	GitHub, GitHub Actions, AWS(EC2), Docker Compose	CI/CD 파이프라인, 단일 compose 로 전체 스택 기동

🙋‍♂️ 본인 담당 영역 통합 백엔드(FastAPI) 설계 및 개발, 하이브리드 검색(BM25+벡터) 및 Cross-Encoder 재랭킹 기반 RAG 아키텍처 설계, Airflow DAG(XCom 기반) 오케스트레이션 구축 및 FastAPI 단독 파이프라인으로의 마이그레이션(실행 락 설계·정량 검증), PostgreSQL/MariaDB 연동 설계

---

📅 프로젝트 정보

항목	내용
기간	2026.05 ~ 2026.06 (5주)
인원	3명 (Backend 2 / AI 1 / PM 1 등 팀 구성 기입)
본인 역할	AI 아키텍처 설계, Airflow 파이프라인 구축 → FastAPI 단독 마이그레이션, DB 연동 및 백엔드 개발
프로젝트 유형	팀 프로젝트 (삼정KPMG AX Academy 공급망 프로젝트 )

---

✨ 주요 기능

• 공급망 리스크 실시간 대시보드 및 지도 시각화
• 정밀 키워드 파싱 기반 1차 가드레일 룰베이스 엔진
• 하이브리드 검색(BM25 + 벡터) + RRF + Cross-Encoder 재랭킹 기반 RAG 추론
• FastAPI 단독 파이프라인 (동시 실행 락 + 단계별 런 상태 추적 — Airflow DAG 에서 마이그레이션)
• 협력사 초대 및 2차 보안 인증(이메일 기반) 플로우

---

🚀 실행 방법 (Quick Start)

# 1. 레포 클론
git clone https://github.com/mpsddd-commits/Triple_Values_ESG_Project_Files.git
cd Triple_Values_ESG_Project_Files

# 2. 환경 변수 (기본값으로도 동작 — 메일/OCR 은 실계정 키 입력 시 활성화)
cp .env.example .env

# 3. 프론트엔드 빌드 + 백엔드 베이스 이미지 (최초 1회)
(cd frontend && npm install && npm run build)
docker build -t uv:1 -f backend/uv.Dockerfile backend

# 4. 전체 스택 실행 (frontend·backend·MariaDB·pgvector·Redis·Kafka — 스키마 자동 초기화)
docker compose up -d

# 5. 테스트 데이터 + ESG 가이드라인 벡터 시드
docker exec tval-backend uv run python seed.py

# 6. 접속 확인
# Frontend:            http://localhost
# API Docs (Swagger):  http://localhost:8000/docs
# 파이프라인 트리거:    POST /pipeline/run  →  GET /pipeline/runs/{runId} 로 단계별 상태 확인

사전 준비: Docker, Node.js, 호스트 Ollama(.env 의 AI_MODEL·EMBED_MODEL 모델 설치, 외부 접근 허용 OLLAMA_HOST=0.0.0.0). 파이프라인은 Airflow 없이 백엔드 안에서 직접 실행됩니다 (apache/ 폴더는 마이그레이션 전 원본 DAG 참고용).

---

📊 주요 성과

1) AI 파이프라인 아키텍처 진화 — Airflow 우회에서 FastAPI 단독 근본 해결까지

Problem (초기) FastAPI 단일 애플리케이션이 API 요청 처리와 고부하 LLM/RAG 추론을 동기 처리하면서, 파이프라인 실행 중 동기 API 전체가 응답 불능이 되고 서버 재시작이 반복됐습니다.

1차 해결 — Airflow 분리 (추론 시간 77.7% 절감) FastAPI 는 API 요청 처리로 경량화하고, 룰 엔진과 RAG 추론을 Apache Airflow 로 분리·이관하는 디커플링을 적용해 추론 소요를 10분 → 2분 14초로 줄였습니다. 다만 이 방식은 상시 컨테이너 7개(스케줄러·워커·메타DB·브로커 등)와 태스크당 스케줄링 오버헤드라는 운영 비용을 대가로 치렀습니다.

근본 원인 규명 — 락 도입 (실측 기반) 응답 불능의 실제 원인이 프레임워크가 아니라 ① AnyIO 스레드풀(40개) 고갈, ② 동시 런 간 데이터 경쟁(낙관적 잠금 충돌로 런 성공률 2.5~10%)임을 부하 실측으로 규명하고, 동시 실행 락으로 해결했습니다. 락 전/후 3단계 부하(10/40/60발) 정량 비교는 docs/troubleshooting-pipeline-run-lock.md 참고 (성공률 100% 회복, 완료 소요 최대 12.2배 단축, 동기 API 응답 불능 제거 — 전체 플랫폼 통합 후 재측정에서도 동일 재현, 문서 8장).

2차 해결 — FastAPI 단독 회귀 (Airflow 제거) 근본 원인이 해결되자 Airflow 는 오버헤드만 남게 되어, 파이프라인을 FastAPI BackgroundTasks + 실행 락 + 런 상태 추적으로 재구현하고 Airflow 를 제거했습니다.

Result — 동일 워크로드(알럿 3건: 임베딩 3회 + 리랭킹 + LLM 추론 3회) 실측 비교 (통합 플랫폼 기준 — 양쪽 모두 CrossEncoder 리랭킹 포함)

지표	Airflow 기반	FastAPI 통합 백엔드 (실행 락)	개선
파이프라인 전체 사이클	288.7초	40.3초	86.0% ↓ (7.2배) ¹
LLM 추론 (순수 실작업)	40.4초	39.3초	동등 — 차이는 전부 오버헤드
오케스트레이션 오버헤드	약 204초 (15개 태스크 × 평균 ~7초 + 콜드스타트)	~0.1초	사실상 제거
Airflow 전용 상시 컨테이너	7개 (apiserver·scheduler·dag-processor·triggerer·worker·메타DB·브로커)	0개 (플랫폼 백엔드에 내장)	인프라 제거
이미지·디스크	약 3.9GB (airflow 3.12GB + postgres + redis) + 컨테이너별 pip 패키지	—	약 4GB+ 절감

¹ Airflow 측은 워커 콜드스타트(~100초) 포함, FastAPI 측은 웜 프로세스(모델 캐시 상태) 실측. 콜드스타트를 보정해도 약 75% 단축입니다. 단독 파이프라인 앱 시절(리랭커 폴백) 측정은 70.0초였으며, 상세 태스크별 실측치는 트러블슈팅 문서 7·8장 참고.

---

🛠️ 기술 스택

Backend: Python 3.12, FastAPI(통합 API + 파이프라인), WebSocket, Pydantic, uv AI & LLM: Ollama(Gemma), HuggingFace(CrossEncoder), rank_bm25, BGE-M3 — 하이브리드 RAG Database: PostgreSQL(pgvector), MariaDB, Redis DevOps & Infra: Docker Compose, AWS(EC2), Apache Kafka, GitHub Actions _{※ Apache Airflow 는 초기 버전에서 사용 후 FastAPI 단독 파이프라인으로 대체 (주요 성과 1 참고)} Frontend: React, Vite, Recharts, Tailwind CSS (nginx)

---

📂 폴더 구조

Triple_Values_ESG_Project_Files/
├── README.md
├── compose.yml              # 전체 스택 (frontend·backend·MariaDB·pgvector·Redis·Kafka)
├── .env.example
├── database/                # DB 스키마·초기화 SQL (31개 테이블, 컨테이너가 자동 적재)
│   ├── mariadb/
│   └── pgvector/
├── frontend/                # React + Vite (빌드 산출물을 nginx 로 서빙)
├── backend/                 # 통합 FastAPI 백엔드
│   ├── main.py
│   ├── src/apis/            # auth · company · supplychain · workflow · ws · pipeline 등 11개 라우터
│   ├── src/models/          # 비즈니스 로직
│   ├── src/utils/           # settings · db · kafka · ocr · token 등 공용 계층
│   ├── src/pipeline/        # AI 파이프라인 (ruleengine · aiengine · runner) — 구 Airflow DAG
│   ├── seed.py / bench.py   # 시드 · 부하 측정 도구
│   ├── uv.Dockerfile        # 백엔드 베이스 이미지 (uv:1)
│   └── data/                # RAG DB 덤프, 샘플 파일
├── apache/                  # (참고용) 마이그레이션 전 원본 Airflow DAG — 실행에 미사용
└── docs/
    ├── architecture.png
    ├── troubleshooting-pipeline-run-lock.md   # 실행 락 전/후 정량 비교 실측 (10/40/60발 + 통합 재측정)
    └── pipeline-migration.md                  # Airflow 태스크 → 함수 매핑 문서

---

🎬 데모

• 데모 영상 링크: https://youtu.be/7Hf3IbZv_wg

---

💭 회고

• 잘한 점

  • 단일 애플리케이션 병목 현상의 진단 → 우회 → 근본 해결로 이어진 아키텍처 진화
    • FastAPI 단일 애플리케이션이 API 서빙과 고부하 LLM/RAG 추론을 동시 처리하면서 발생하는 병목(Bottleneck) 문제를 진단하고, 1차로 Apache Airflow 분리(디커플링)를 통해 추론 시간을 77.7% 단축.
    • 이후 부하 실측으로 응답 불능의 근본 원인(AnyIO 스레드풀 고갈, 동시 런 데이터 경쟁)을 규명하고, 동시 실행 락 기반의 FastAPI 단독 파이프라인으로 회귀 — Airflow 대비 전체 사이클 86% 단축과 상시 인프라 7컨테이너 제거를 정량 실측으로 입증.
    • "우회책과 근본 해결을 구분하고, 아키텍처 결정을 측정으로 검증한다"는 원칙을 실제로 경험함.

• 아쉬운 점 / 개선하고 싶은 점

  • RDB 기반 공급망 모델링의 한계와 지식그래프(Knowledge Graph) 도입 필요성
    • 현재 MariaDB와 PostgreSQL을 활용해 30여 개의 테이블로 공급망 데이터를 관리하고 있으나, 원청사와 N차 협력사 간의 복잡한 다대다($N:M$) 관계 및 순환 구조를 RDB의 조인(Join) 연산만으로 추적하는 데 확장성 한계를 느낌.
    • 향후 Neo4j와 같은 그래프 데이터베이스(Graph DB)나 지식그래프를 도입하여 계층 구조에 얽매이지 않는 유연한 공급망 네트워크를 확립하고, 특정 협력사의 ESG 리스크가 전체 공급망 체인에 미치는 전이 효과(Traceability)를 직관적으로 추적·분석해보고 싶음.