[feat] Instagram 이미지 OCR 장소 추출을 5장 단위 배치 및 부분 결과 저장 방식으로 개선

[KyungminPark-steck]

📖 배경

현재 Instagram post URL 처리 시 caption에서 장소가 추출되지 않는 경우 이미지 OCR fallback을 실행한다.

기존 구조에서는 최대 10장의 이미지를 한 번에 OCR한 뒤, 전체 OCR 결과를 합쳐 HF 장소 추출과 Kakao 검색을 한 번만 수행한다. 이 방식은 이미지 수가 많거나 추출 장소가 많은 게시물에서 사용자가 최종 결과를 보기까지 오래 기다려야 하는 문제가 있다.

또한 현재 설정상 이미지 수집은 10장, 장소 추출 후보는 12곳으로 제한되어 있어, 여러 장소를 소개하는 Instagram 게시물에서는 결과가 부족할 수 있다.

🎯 목표

Instagram 이미지 OCR fallback을 5장 단위로 처리하여, 장소 검색 결과가 일정 수 이상 확보되면 작업 완료 전에도 부분 결과를 조회할 수 있게 한다.

이미지 수집 한도는 20장, 장소 추출 후보 한도는 40곳으로 확대한다.

🛠️ 구현 내용

• Instagram 이미지 수집 기본 한도를 10장 → 20장으로 변경한다.
• Instagram carousel next click 기본 한도를 10회 → 20회로 변경한다.
• HF 장소 추출 후보 기본 한도를 12곳 → 40곳으로 변경한다.
• Instagram OCR fallback을 전체 이미지 일괄 처리에서 5장 단위 batch 처리로 변경한다.
• 각 batch마다 OCR -> HF 장소 추출 -> Kakao 장소 검색을 수행한다.
• batch 결과는 중복 제거하며 누적한다.
• 마지막 저장 이후 새로 확보된 resolved place가 5곳 이상이면 job_results에 partial result를 저장한다.
• 모든 batch 처리가 끝나면 남은 결과 수와 관계없이 최종 result를 저장하고 job을 성공 처리한다.
• /jobs/{jobId}/result는 job이 PROCESSING 상태여도 저장된 result가 있으면 200으로 결과를 반환한다.
• 후속 OCR batch에서 rate limit 등 오류가 발생하더라도 이미 누적된 장소 결과가 있으면 확보된 결과로 job을 성공 처리한다.

⚠️ 고려사항

• PROCESSING 상태에서도 result가 반환될 수 있으므로, 클라이언트는 응답의 status가 PROCESSING이면 partial result로 해석해야 한다.
• 별도의 cursor, hasMore, 더보기 API는 이번 범위에 포함하지 않는다. worker는 partial result 저장 후에도 남은 이미지 batch를 계속 처리한다.
• 후속 batch 실패 시 이미 확보한 결과가 있으면 성공 처리하므로, 일부 이미지가 처리되지 않았을 가능성이 있다. 이 정보는 OCR fallback metadata를 통해 image/ocr count로 확인한다.
• 기존 caption-only 추출 성공 경로는 유지하며, caption에서 장소가 추출되면 이미지 OCR fallback은 실행하지 않는다.

✅ 완료 조건

• Instagram caption에서 장소가 추출되지 않는 경우 이미지 OCR fallback이 5장 단위로 실행된다.
• 각 batch 이후 마지막 저장 시점 대비 신규 resolved place가 5곳 이상이면 partial result가 저장된다.
• PROCESSING 상태의 job도 저장된 result가 있으면 /jobs/{jobId}/result에서 200으로 조회된다.
• 이미지 수집 한도 20장, 장소 추출 후보 40곳 설정이 반영된다.
• 다음 시나리오 테스트가 통과한다.
  • 첫 batch에서 5곳 이상 추출되면 partial result가 저장된다.
  • 첫 batch가 5곳 미만이면 다음 batch 결과와 합산해 5곳 이상일 때 저장된다.
  • 이후 batch에서도 마지막 저장 이후 신규 5곳 이상 조건이 반복 적용된다.
  • 후속 OCR batch 실패 시 이미 누적된 결과가 있으면 확보된 결과로 성공 처리된다.
• 전체 자동 테스트가 통과한다.
• 실제 Instagram URL 기준 end-to-end 검증에서 result가 정상 저장된다.