[Perf] 실제 BGE-M3 Batch Size 최적화 및 기본값 조정

[Gimini-3]

🔍️ 작업 내용

• Closes 실제 BGE-M3 Batch Size별 성능 비교 및 최적 기본값 검증 #128
• 실제 BAAI/bge-m3의 Batch Size 1, 4, 8, 16, 32, 64를 동일한 한국어 입력으로 비교하는 Benchmark를 추가했습니다.
• Warm-up 분리, Round별 실행 순서 회전, 처리량·p50·p95·p99·Text당 시간·오류율·Container RSS 수집을 구현했습니다.
• Model·응답 순서·개수·1024차원·NaN·Infinity 계약을 요청마다 검증합니다.
• 실제 측정 결과를 근거로 문서 임베딩 기본 Batch Size를 16에서 32로 변경했습니다.
• 설계 문서와 재현 가능한 테스트 결과 문서를 추가했습니다.

✨ 상세 설명

기존 Batch Size 기본값은 실제 BGE-M3 처리량과 꼬리 지연, 메모리 사용량을 함께 비교한 근거가 없었습니다. 최고 처리량만 선택하지 않고 운영 안정성과 처리량의 균형을 확인할 수 있도록 반복 가능한 측정 도구와 결과를 추가했습니다.

측정 결과

• 전체: 1,140 HTTP 요청, 4,608 Vector, 실패 0
• Batch 32: 17.08 texts/s, p95 1,975.70ms
• Batch 64: 17.38 texts/s, p95 3,719.82ms
• Batch 32는 최고 처리량의 98.27%를 유지
• Batch 64의 측정 최고 RSS는 Batch 32보다 약 83.05MiB 높음

처리량 차이는 1.76%인 반면 Batch 64의 p95가 Batch 32의 1.88배여서 기본값으로 Batch 32를 선택했습니다.

영향

• 문서 임베딩 처리량이 기존 Batch 16 대비 약 12.74% 증가합니다.
• Query Embedding 단건 API와 Batch Size 허용 범위 1~64는 변경하지 않습니다.
• Benchmark는 일반 테스트와 분리되어 실제 Embedding Server가 있을 때만 명시적으로 실행합니다.

검증

• Python 계약·회귀 테스트: 27 passed
• Java 전체 회귀: 709 tests, failures 0, errors 0
• 실제 BGE-M3 확장 측정: 6개 Profile, 실패 및 Vector 계약 오류 0
• git diff --check 통과

🛠️ 추후 리팩토링 및 고도화 계획

• GPU 및 공급사 운영 서버에서 동일 Benchmark 재측정
• 다중 Worker 동시 요청과 Queue Backpressure 별도 검증
• 실제 운영 문서 Token 길이 분포 기반 추가 비교

💬 리뷰 요구사항

• Batch 32 기본값 선택 기준이 처리량과 꼬리 지연의 균형 관점에서 적절한지 확인 부탁드립니다.
• Benchmark가 일반 테스트와 분리된 경계가 유지되는지 확인 부탁드립니다.

Summary by CodeRabbit

• 새로운 기능

  • BGE-M3 임베딩 배치 크기별 성능을 측정하고 결과를 JSON·콘솔 요약으로 확인할 수 있습니다.
  • 배치 크기 성능 검증을 위한 실행 명령과 설정 예시가 추가되었습니다.

• 변경 사항

  • 문서 임베딩 기본 배치 크기가 16에서 32로 변경되었습니다.
  • CPU 벤치마크 결과와 설정 기준이 문서화되었습니다.

• 테스트

  • 배치 크기 파싱, 응답 검증, 성능 집계 및 설정 유효성 검증 테스트가 추가되었습니다.

[coderabbitai]

Warning

Review limit reached

@Gimini-3, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 51 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 468b895c-a65d-4abe-8c4a-061ad00f9067

📥 Commits

Reviewing files that changed from the base of the PR and between 016b22f and 002c67d.

📒 Files selected for processing (3)

• docs/test-results/gimin-#128-bge-m3-batch-size-performance.md
• embedding-server/benchmark_batch_size.py
• embedding-server/test_benchmark_batch_size.py

📝 Walkthrough

Walkthrough

실제 BGE-M3 /embed/batch 성능 benchmark CLI와 Gradle 실행 태스크를 추가했습니다. 측정 결과를 문서화하고 문서 임베딩 기본 배치 크기를 16에서 32로 변경했습니다. 관련 설정 예시와 Java 회귀 테스트도 갱신했습니다.

Changes

BGE-M3 배치 크기 benchmark

Layer / File(s)	Summary
Benchmark 계약과 입력 검증 docs/design/..., embedding-server/benchmark_batch_size.py, embedding-server/test_benchmark_batch_size.py	Batch 설정, 재현 가능한 Corpus, 응답 Vector 계약, Percentile 및 설정 검증을 추가했습니다. 관련 pytest 테스트를 추가했습니다.
Benchmark 실행과 결과 집계 embedding-server/benchmark_batch_size.py, build.gradle	Health 확인, Warm-up, Batch별 순차 측정, Docker RSS 수집, 성능 집계, 추천 계산 및 JSON 출력을 구현했습니다. Gradle 실행 태스크를 추가했습니다.
측정 결과와 문서 임베딩 기본값 docs/test-results/..., .env.example, src/main/java/..., src/main/resources/application.yml, src/test/java/...	Batch 32를 기본값으로 선정한 결과를 기록했습니다. 설정 기본값과 테스트 기대값을 32로 변경했습니다. Query Embedding 단건 API 설정은 유지했습니다.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Developer
  participant Gradle
  participant BenchmarkCLI
  participant EmbeddingServer
  participant Docker
  participant ResultJSON
  Developer->>Gradle: bgeBatchPerformanceTest 실행
  Gradle->>BenchmarkCLI: benchmark_batch_size.py 실행
  BenchmarkCLI->>EmbeddingServer: /health 확인
  BenchmarkCLI->>EmbeddingServer: Batch별 /embed/batch 요청
  BenchmarkCLI->>Docker: 컨테이너 RSS 조회
  BenchmarkCLI->>ResultJSON: 지표와 추천 결과 저장

Loading

Possibly related PRs

• DocGrid/backend#102: 동일한 문서 임베딩 Batch 크기 설정을 도입했으며, 이번 PR이 해당 설정을 benchmark하고 변경합니다.
• DocGrid/backend#60: 공유 BGE-M3 embedding-server와 Vector 응답 차원 검증 경로를 수정했습니다.
• DocGrid/backend#45: 공유 embedding-server 통합과 Vector 응답 검증을 다룹니다.

Suggested labels: ✨ Feature, 📃 Docs

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	제목은 실제 BGE-M3 배치 크기 성능 측정과 기본값 조정이라는 주요 변경을 명확하게 요약합니다.
Description check	✅ Passed	작업 내용, 상세 설명, 후속 계획, 리뷰 요구사항을 포함하며 템플릿의 필수 정보를 대부분 충족합니다.
Linked Issues check	✅ Passed	실제 BGE-M3 벤치마크, 응답 계약 검증, RSS 측정, 결과 문서화, 기본값 조정을 직접 연결된 이슈의 요구사항에 맞게 구현했습니다.
Out of Scope Changes check	✅ Passed	변경 사항은 벤치마크 구현, 테스트, 문서화 및 문서 임베딩 기본값 조정 범위에 포함되며 관련 없는 변경은 확인되지 않습니다.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/128

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/test-results/gimin-`#128-bge-m3-batch-size-performance.md:
- Around line 119-122: 프로젝트 루트에서 실행해도 테스트 파일을 찾도록 pytest 명령을 수정하세요.
`test_benchmark_batch_size.py`와 `test_main.py` 경로에 `embedding-server/` 접두사를
추가하거나 명령 실행 전에 `cd embedding-server`를 포함하고, 두 테스트가 동일하게 실행되도록 유지하세요.

In `@embedding-server/benchmark_batch_size.py`:
- Line 24: 제품 기본값과 일치하도록 embedding-server/benchmark_batch_size.py 24-24의
CURRENT_DEFAULT_BATCH_SIZE를 32로 변경하세요. 해당 변경에 맞춰
embedding-server/test_benchmark_batch_size.py 115-125의 현재 기본값 Fixture를 Batch 32로
업데이트하고, 5% 정책 검증을 위해 Batch 32는 96.0, Batch 64는 100.0으로 설정하세요.
- Around line 252-263: Update the exception handling around the response
decoding in the benchmark request flow to include UnicodeDecodeError alongside
the existing exceptions caught by the handler after validate_batch_response.
Ensure invalid UTF-8 responses are recorded as failed request samples so the
benchmark continues and previously completed profile results can still be saved.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: c99878cf-2022-4582-aecb-572d6b285685

📥 Commits

Reviewing files that changed from the base of the PR and between 2562f31 and 016b22f.

📒 Files selected for processing (9)

• .env.example
• build.gradle
• docs/design/gimin-#128-bge-m3-batch-size-performance.md
• docs/test-results/gimin-#128-bge-m3-batch-size-performance.md
• embedding-server/benchmark_batch_size.py
• embedding-server/test_benchmark_batch_size.py
• src/main/java/com/opensource/docgrid/domain/embedding/config/EmbeddingBatchProperties.java
• src/main/resources/application.yml
• src/test/java/com/opensource/docgrid/domain/embedding/config/EmbeddingBatchPropertiesTest.java