[ Refactor ] - 소비 분류 병렬 처리 및 성능 계측 추가

[bigwaveBigwave]

관련 이슈

• Closes [ Refactor ] - 계좌 연동 후 소비 카테고리 분류 시간 단축 #231

배경

회원가입 후 계좌를 연동하면 사용자의 미분류 거래에 대해 소비 카테고리 분류를 실행합니다.

기존에는 FastAPI 분류 요청을 최대 100건씩 나눈 뒤 순차 호출해, 최초 계좌 연동 완료까지 약 4분이 소요됐습니다. 또한 단계별 처리 시간이 계측되지 않아 정확한 병목과 개선 전후 차이를
확인하기 어려웠습니다.

변경 사항

1. FastAPI 분류 배치 제한 병렬 처리

• 기존 100건 단위 요청 크기는 유지했습니다.
• 여러 FastAPI 배치를 전용 스레드 풀에서 병렬 실행하도록 변경했습니다.
• 기본 병렬도는 4이며 최대 8로 제한했습니다.
• 실행기 큐가 가득 차면 요청 스레드가 직접 처리하도록 CallerRunsPolicy를 적용했습니다.
• 병렬 실행 후에도 기존 요청 순서대로 결과를 합쳐 저장합니다.

2. 병렬도 외부 설정 지원

외부 fastapi.properties에서 병렬도를 조절할 수 있습니다.

fastapi.classification.parallelism=4

개선 전후 측정 시 같은 코드에서 설정만 변경합니다.

# 기존 순차 실행 재현
fastapi.classification.parallelism=1

# 제한 병렬 실행
fastapi.classification.parallelism=4

따라서 성능 측정을 위해 별도의 코드 변경이나 재배포를 반복할 필요가 없습니다. 설정 변경 후 서버 재시작만 필요합니다.

3. FastAPI timeout 설정

외부 API 지연으로 요청이 무기한 대기하지 않도록 timeout을 추가했습니다.

fastapi.connect-timeout-ms=5000
fastapi.read-timeout-ms=120000

• connect timeout 기본값: 5초
• read timeout 기본값: 120초
• 호출 실패 또는 timeout 발생 시 기존 ETC / VARIABLE fallback 정책을 유지합니다.

4. 소비 분류 성능 계측 로그 추가

사용자별 실행을 구분할 수 있도록 scope=userId를 포함했습니다.

수집 가능한 지표:

• 전체 처리 건수와 소비 분류 전체 시간
• DB 미분류 거래 조회 시간
• Java 규칙 분류 건수
• FastAPI 대상 거래 수와 배치 수
• FastAPI 배치별 요청 수와 응답 시간
• 정상 결과 및 fallback 건수
• DB 저장 시간

로그 예시:

[일간 소비 분류] FastAPI 배치 완료.
scope=userId=1, page=1, batch=1, requestCount=100,
validCount=100, fallbackCount=0, elapsedMs=...

[일간 소비 분류] 페이지 분류 완료.
scope=userId=1, page=1, targets=..., deterministic=...,
fastApiTargets=..., fastApiBatches=...

[일간 소비 분류] 페이지 저장 완료.
scope=userId=1, page=1, pageSize=..., totalProcessed=...,
dbReadMs=..., classificationMs=..., dbSaveMs=...

[일간 소비 분류] 실행 완료.
scope=userId=1, totalProcessed=..., pages=..., totalElapsedMs=...

기존 동작 유지

• FastAPI 요청 최대 크기 100건 유지
• Java 결정적 규칙 분류 유지
• FastAPI 응답 유효성 검증 유지
• 응답 누락·중복·오류 시 fallback 유지
• 원래 요청 순서대로 결과 저장
• TXN_ANALYSIS 저장 계약 유지
• 계좌 연동 API가 분류 완료까지 기다리는 기존 동기 흐름 유지

테스트

다음 테스트와 패키징을 실행했습니다.

.\gradlew.bat :services:ai-service:test :services:account-service:test --no-daemon
.\gradlew.bat :api:war --no-daemon

결과:

BUILD SUCCESSFUL

추가 및 보강한 테스트:

• FastAPI 요청이 최대 100건 단위로 분할되는지 검증
• 분할된 FastAPI 배치가 설정된 실행기에서 동시에 실행되는지 검증
• 기존 분류 및 fallback 결과 유지 검증
• connect/read timeout 기본값 검증
• timeout 설정값 로딩 검증

성능 측정 계획

한 번 배포한 뒤 외부 properties만 변경해 동일 조건에서 비교합니다.

개선 전

fastapi.classification.parallelism=1

개선 후

fastapi.classification.parallelism=4

측정 조건:

• 동일한 가상 사용자
• 동일한 은행 기관코드
• 동일한 DB 및 FastAPI 서버
• 워밍업 1회 후 최소 10회 측정
• 다른 배치 및 테스트 트래픽이 없는 시간에 실행

비교할 지표:

항목 개선 전 (parallelism=1) 개선 후 (parallelism=4)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━
분류 대상 거래 수 측정 예정 측정 예정
─────────────────────────────── ───────────────────────── ─────────────────────────
계좌 연동 전체 시간 p50 / p95 측정 예정 측정 예정
─────────────────────────────── ───────────────────────── ─────────────────────────
소비 분류 전체 시간 p50 / p95 측정 예정 측정 예정
─────────────────────────────── ───────────────────────── ─────────────────────────
처리량(건/초) 측정 예정 측정 예정
─────────────────────────────── ───────────────────────── ─────────────────────────
FastAPI 호출 횟수 측정 예정 측정 예정
─────────────────────────────── ───────────────────────── ─────────────────────────
FastAPI 요청 누적 시간 측정 예정 측정 예정
─────────────────────────────── ───────────────────────── ─────────────────────────
FastAPI wall time 측정 예정 측정 예정
─────────────────────────────── ───────────────────────── ─────────────────────────
fallback 건수 측정 예정 측정 예정
─────────────────────────────── ───────────────────────── ─────────────────────────
미분류 잔여 건수 측정 예정 측정 예정

성능 측정 결과는 배포 후 PR 댓글 또는 이슈 #231에 추가할 예정입니다.

운영 시 확인 사항

• FastAPI 서버가 동시 요청을 처리할 수 있는지 확인이 필요합니다.
• rate limit 또는 내부 직렬화가 확인되면 병렬도를 낮출 수 있습니다.
• 문제 발생 시 다음 설정으로 기존 순차 실행 방식으로 즉시 전환할 수 있습니다.

fastapi.classification.parallelism=1

• 설정 변경 후 서버 또는 컨테이너 재시작이 필요합니다.