[Quiz][Refactor] 제미나이 SDK 타임아웃 및 재시도 설정

[sunwon12]

개요

Gemini API 연동의 안정성과 비용 관리 효율성을 높이기 위해 타임아웃 및 재시도 전략을 전면적으로 수정했습니다.
특히, 무료 티어의 엄격한 Quota(RPM/RPD) 관리를 위해 "정확한 집계"를 "재시도 편의성"보다 우선시하는 Fail-Fast 전략을 채택했습니다.

---

변경 사항

1. Request-Level Timeout 도입

• Before: GeminiClientManager 등에서 전역 설정 불가 (SDK 기본값 의존) 또는 모든 요청에 동일 타임아웃 적용.
• After: GeminiRequest DTO에 timeout 필드 추가 (기본값: 60,000ms).
  • 이점: '간단한 채팅'은 짧게(10s), '긴 퀴즈 생성'은 길게(120s) 설정하여 스레드 점유 최적화.

2. Explicit Retry Policy (명시적 재시도 정책) 정의

GeminiSdkClient에 HttpRetryOptions를 명시적으로 설정했습니다.

• 설정값:
  • attempts: 5회 (총 6회 시도)
  • initialDelay: 1초 (Exponential Backoff, multiplier=2.0)
  • maxDelay: 60초

3. Fail-Fast Strategy for 408 & 429

다음 에러 코드는 SDK 자동 재시도 대상에서 제외했습니다.

Status Code	Description	Reason for Exclusion (제외 사유)	Application Handling
429	Too Many Requests	Rate Limit 도달 시 즉시 멈추고 롤백 취소 등 대응 필요.	GeminiRateLimiterService가 재고 차감 유지.
408	Request Timeout	"숨겨진 요청" 방지. 재시도 시 요청 횟수(RPM)가 중복 집계되지 않아 Quota 관리 정확도 하락.	집계 정확성(Accounting) 우선 정책에 따라 즉시 실패 처리.

재시도 대상: 500, 502, 503, 504 (서버 측의 명백한 에러)

---

📚 Documentation (문서화)

상세한 의사결정 과정과 트레이드오프 분석은 다음 문서에 정리했습니다.

• docs/feature_description/GEMINI_TIMEOUT_AND_RETRY_STRATEGY.md

[gemini-code-assist]

Summary of Changes

Hello @sunwon12, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

이 PR은 Gemini SDK 연동의 안정성과 비용 관리 효율성을 향상시키기 위해 타임아웃 및 재시도 전략을 전면적으로 개선합니다. 요청별로 유연하게 타임아웃을 설정할 수 있게 되었으며, 특히 무료 티어의 엄격한 Quota 관리를 위해 408 및 429 에러에 대해서는 'Fail-Fast' 전략을 적용하여 정확한 집계를 우선시합니다. 이를 통해 시스템의 예측 가능성을 높이고 불필요한 자원 소모를 줄이는 것을 목표로 합니다.

Highlights

• 요청별 타임아웃 도입: GeminiRequest DTO에 timeout 필드(기본값 60,000ms)를 추가하여 각 Gemini API 요청에 대해 동적으로 타임아웃을 설정할 수 있도록 변경했습니다. 이는 기존의 전역 설정이나 SDK 기본값 의존 방식에서 벗어나 요청의 특성(예: 간단한 채팅 vs. 긴 퀴즈 생성)에 따라 스레드 점유를 최적화합니다.
• 명시적 재시도 정책 설정: GeminiSdkClient에 HttpRetryOptions를 명시적으로 설정하여 재시도 정책을 정의했습니다. 총 5회 재시도(총 6회 시도), 1초의 초기 지연(지수 백오프), 최대 60초의 지연 시간을 갖도록 구성되었습니다.
• 408 및 429 에러에 대한 Fail-Fast 전략: HTTP 상태 코드 408 (Request Timeout)과 429 (Too Many Requests)는 SDK의 자동 재시도 대상에서 제외되었습니다. 이는 Rate Limit 도달 시 즉각적인 대응과 정확한 Quota 관리를 위한 'Fail-Fast' 전략을 채택한 것으로, '숨겨진 요청'으로 인한 Quota 집계 오류를 방지합니다. 500, 502, 503, 504와 같은 서버 측 에러만 재시도됩니다.
• 상세 의사결정 문서 추가: 타임아웃 및 재시도 전략에 대한 의사결정 과정, 대안 검토, 최종 구현 상세 및 트레이드오프 분석을 담은 docs/feature_description/GEMINI_TIMEOUT_AND_RETRY_STRATEGY.md 문서를 새로 추가했습니다.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

전반적으로 Gemini API 연동의 안정성과 비용 효율성을 높이기 위한 타임아웃 및 재시도 전략 리팩토링이 매우 인상적입니다. 특히, 요청별 타임아웃을 유연하게 설정하고, 무료 티어의 엄격한 Quota 관리를 위해 Fail-Fast 전략을 채택한 점이 돋보입니다. 의사결정 과정을 상세히 기술한 GEMINI_TIMEOUT_AND_RETRY_STRATEGY.md 문서 덕분에 변경 사항의 의도를 명확히 파악할 수 있었습니다.

다만, GeminiSdkClient 클래스에서 GenerateContentConfig를 생성하는 로직이 중복되고, 불필요한 메서드 호출이 발견되어 이 부분을 개선하면 코드의 유지보수성이 더욱 향상될 것입니다. 자세한 내용은 아래의 개별 리뷰 코멘트를 참고해 주세요.

[gemini-code-assist]

문서의 재시도 설정 구조 표에서 exp_base라는 파라미터를 사용하고 있으나, 실제 적용된 Java SDK에서는 multiplier를 사용합니다. 문서와 코드의 일관성을 위해 multiplier로 수정하는 것이 좋겠습니다.

Suggested change

	| `exp_base` | 2 | 지수 백오프(Exponential Backoff) 승수 |
	| `multiplier` | 2 | 지수 백오프(Exponential Backoff) 승수 |

[github-actions]

🌻 테스트 커버리지 리포트

Overall Project	52.04%	🍏
Files changed	100%	🍏

File	Coverage
GeminiRequestFactory.java	100%	🍏
GeminiClientManager.java	80.7%	🍏
GeminiSdkClient.java	73.18%	🍏