Skip to content

[Perf] 인덱싱·Vector 검색 최종 통합 성능 리포트 및 그래프 추가 - #146

Merged
Gimini-3 merged 5 commits into
developfrom
feature/145
Aug 11, 2026
Merged

[Perf] 인덱싱·Vector 검색 최종 통합 성능 리포트 및 그래프 추가#146
Gimini-3 merged 5 commits into
developfrom
feature/145

Conversation

@Gimini-3

@Gimini-3 Gimini-3 commented Aug 11, 2026

Copy link
Copy Markdown
Contributor

변경 내용

  • 기존 성능 결과 8개의 핵심 수치와 출처를 정규화 JSON으로 통합했습니다.
  • Claim, 실제 BGE-M3, Exact·HNSW, Worker 수평 확장, Queue Backpressure, PDF·DOCX E2E 그래프 6개를 추가했습니다.
  • Python 표준 라이브러리 기반 SVG 생성기와 데이터 계약·재현성 검사 모드를 추가했습니다.
  • 최종 리포트에 비교표, 병목 이동, 현재 환경의 권장 기준점과 남은 공식 OpenSQL 검증을 정리했습니다.
  • 서로 다른 문서 크기·환경의 절대 성능은 직접 비교하지 않도록 해석 경계를 명시했습니다.

핵심 결론

  • OpenSQL 17.8 Claim은 Worker 5에서 748.45 TPS, p99 13.187ms로 균형이 가장 좋았습니다.
  • 실제 BGE-M3 Batch 32는 최대 처리량의 98.27%이며 Batch 64보다 p95가 46.89% 낮았습니다.
  • HNSW는 5만 Vector에서 Exact보다 p95가 99.09배 빨랐지만 평균 Recall@10은 0.22여서 실제 Corpus 튜닝이 필요합니다.
  • Worker 실행 Slot은 2개 이후 약 21.6문서/분으로 포화됐습니다.
  • PDF·DOCX 본 측정 300문서에서 1,200개 Vector를 저장했고 실패·Retry·미완료·중복은 0건이었습니다.

검증

  • python3 -m unittest scripts/performance/test_generate_final_performance_report.py
    • 4 tests passed
  • python3 scripts/performance/generate_final_performance_report.py --check
    • SVG 6개 일치
  • ./gradlew test
    • 728 tests passed
  • git diff --check

제외 및 후속

  • 기존 Benchmark는 재실행하지 않았습니다.
  • 현재 수치를 운영 SLO로 확정하지 않습니다.
  • 공급사 지원 Rocky Linux 9.7 x86-64 원격 OpenSQL 환경의 최종 검증은 별도 후속입니다.
  • 실제 Corpus에서 HNSW ef_search별 지연·Recall Pareto 측정이 필요합니다.

Closes #145

Summary by CodeRabbit

  • 새로운 기능

    • 주요 처리량, 검색, 확장성, 백프레셔 및 문서 처리 성능을 종합한 최종 성능 리포트를 추가했습니다.
    • 성능 데이터를 기반으로 접근성을 지원하는 SVG 차트를 자동 생성하고, 결과 일치 여부를 점검할 수 있습니다.
    • 재현 명령, 기준 환경, 운영 판단, 제한 사항 및 후속 과제를 리포트에 포함했습니다.
  • 테스트

    • 성능 데이터 검증, 차트 생성, 잘못된 데이터 거부 및 결과 변조 감지 테스트를 추가했습니다.

@coderabbitai

coderabbitai Bot commented Aug 11, 2026

Copy link
Copy Markdown

Review Change Stack

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: 9b41e510-e26c-4bf9-b1c8-f0ead5ef661c

📥 Commits

Reviewing files that changed from the base of the PR and between efed944 and b8d0e7d.

📒 Files selected for processing (3)
  • docs/test-results/gimin-#145-final-performance-report.md
  • scripts/performance/generate_final_performance_report.py
  • scripts/performance/test_generate_final_performance_report.py
📝 Walkthrough

Walkthrough

정규화된 성능 데이터와 출처를 추가했다. 데이터 계약 검증기와 결정적 SVG 생성기를 구현했다. --check 모드와 회귀 테스트를 추가했다. 6개 성능 영역의 최종 리포트와 설계 문서를 작성했다.

Changes

최종 통합 성능 리포트

Layer / File(s) Summary
성능 데이터 계약과 실측 데이터
docs/design/gimin-#145-final-performance-report.md, docs/test-results/gimin-#145-final-performance-report-data.json
성능 데이터 구조, 출처, 비교 경계와 6개 benchmark 및 supporting baseline을 정의했다.
데이터 검증과 SVG 렌더링
scripts/performance/generate_final_performance_report.py
JSON 계약과 출처를 검증하고, 선형·로그 축 및 접근성 메타데이터를 포함한 결정적 SVG를 생성한다.
재생성 검사와 회귀 검증
scripts/performance/generate_final_performance_report.py, scripts/performance/test_generate_final_performance_report.py
CLI의 생성 및 --check 흐름을 추가했다. 계약 오류, SVG 구조, 시리즈 길이와 출력 변조를 테스트한다.
최종 성능 리포트
docs/test-results/gimin-#145-final-performance-report.md
Job Claim, BGE-M3 batch, Exact/HNSW, Worker 확장, Queue backpressure, PDF·DOCX E2E 결과와 기준점을 문서화했다.

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

Sequence Diagram(s)

sequenceDiagram
  participant PerformanceData
  participant validate_data
  participant render_all
  participant SVGFiles
  PerformanceData->>validate_data: JSON 계약과 출처 검증
  validate_data->>render_all: 유효한 benchmark 전달
  render_all->>SVGFiles: 결정적 SVG 생성
Loading

Possibly related PRs

  • DocGrid/backend#62: OpenSQL Job Claim 처리량 benchmark 결과를 최종 리포트에 포함한다.
  • DocGrid/backend#130: BGE-M3 batch-size benchmark 결과와 Batch 32 기준점을 포함한다.
  • DocGrid/backend#135: Worker indexing 처리량 benchmark 결과를 검증된 차트 데이터로 정리한다.

Suggested labels: 📃 Docs

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name Status Explanation Resolution
Linked Issues check ❓ Inconclusive 대부분의 요구사항은 충족하지만, 6개 SVG 산출물은 !**/*.svg 필터로 제외되어 실제 파일과 재생성 일치를 확인할 수 없습니다. 제외된 6개 SVG 파일의 존재와 생성 결과 일치를 별도 검토하거나, SVG 파일을 검토 대상에 포함해 확인하세요.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed 제목은 인덱싱·Vector 검색 성능 리포트와 그래프 추가라는 주요 변경 내용을 명확하게 요약합니다.
Description check ✅ Passed 설명은 변경 내용, 핵심 결론, 검증 결과, 제외 범위와 후속 계획, 연결 이슈를 포함하여 요구 정보를 대부분 제공합니다.
Out of Scope Changes check ✅ Passed 변경 사항은 정규화 데이터, 성능 리포트, SVG 생성기와 테스트로 구성되며 연결 이슈의 범위를 벗어난 코드 변경은 확인되지 않습니다.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feature/145

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

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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🧹 Nitpick comments (2)
scripts/performance/generate_final_performance_report.py (1)

242-245: 🩺 Stability & Availability | 🔵 Trivial | 💤 Low value

Series가 6개 이상이면 PALETTE 색인이 범위를 벗어납니다.

PALETTE는 색상 5개를 가집니다. ordered_series 길이가 6 이상이면 IndexError가 발생합니다. 현재 데이터는 최대 3개라 재현되지 않습니다. 데이터 계약이 Series 수를 제한하지 않으므로 순환 색인이나 검증 추가를 고려하세요.

♻️ 제안 리팩터링
     colors = {
-        series_id: PALETTE[index]
+        series_id: PALETTE[index % len(PALETTE)]
         for index, series_id in enumerate(ordered_series)
     }
🤖 Prompt for 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.

In `@scripts/performance/generate_final_performance_report.py` around lines 242 -
245, Update the colors mapping in the ordered_series flow so any number of
series can be handled without indexing beyond PALETTE; cycle through PALETTE
using modulo or an equivalent reusable-color approach while preserving the
existing series ordering.
scripts/performance/test_generate_final_performance_report.py (1)

53-66: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Commit된 SVG와 정규화 데이터의 일치 테스트를 추가하세요.

현재 테스트는 임시 디렉터리에 생성한 파일만 비교합니다. DEFAULT_OUTPUT_DIRECTORY의 Commit된 SVG를 검사하지 않으므로 데이터 변경 후 SVG 재생성을 누락한 Drift를 검출하지 못합니다. GENERATOR.check_outputs(rendered, GENERATOR.DEFAULT_OUTPUT_DIRECTORY)를 호출하는 회귀 테스트를 추가하세요.

🤖 Prompt for 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.

In `@scripts/performance/test_generate_final_performance_report.py` around lines
53 - 66, Extend test_check_detects_a_tampered_svg to call
GENERATOR.check_outputs(rendered, GENERATOR.DEFAULT_OUTPUT_DIRECTORY) after
validating and rendering, so the committed SVG outputs are compared against the
normalized data. Keep the existing temporary-directory tampering assertion
unchanged.
🤖 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-`#145-final-performance-report.md:
- Around line 159-161: Update the report’s conclusion around the 100-document
validation statement to accurately reflect the 300-document result described in
the performance measurement. Distinguish 50- and 100-document throughput
measurements from the separate 300-document vector consistency validation, or
revise the overall E2E scope to 300 documents if that workload covered the full
path; ensure the conclusion no longer implies validation ended at 100 documents.
- Around line 202-221: Update the “재현성과 원본 출처” section to record actual
automated verification outcomes alongside the commands, including
50·100-document measurements, 300-document completeness validation, and the full
regression test count. Add the Swagger manual verification scenario,
environment, and result, or explicitly state why it was not run; do not mark
unexecuted checks as PASS. In the final conclusions, distinguish the
50·100-document load profile from the separate 300-document completeness
validation.

In `@scripts/performance/generate_final_performance_report.py`:
- Around line 517-532: Update write_outputs to force LF line endings when
writing rendered SVGs, and update check_outputs to compare exact file bytes
without newline translation. Use explicit newline handling via open(...,
newline="") or read_bytes() while preserving UTF-8 behavior and the existing
mismatch reporting.

---

Nitpick comments:
In `@scripts/performance/generate_final_performance_report.py`:
- Around line 242-245: Update the colors mapping in the ordered_series flow so
any number of series can be handled without indexing beyond PALETTE; cycle
through PALETTE using modulo or an equivalent reusable-color approach while
preserving the existing series ordering.

In `@scripts/performance/test_generate_final_performance_report.py`:
- Around line 53-66: Extend test_check_detects_a_tampered_svg to call
GENERATOR.check_outputs(rendered, GENERATOR.DEFAULT_OUTPUT_DIRECTORY) after
validating and rendering, so the committed SVG outputs are compared against the
normalized data. Keep the existing temporary-directory tampering assertion
unchanged.
🪄 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: e0f7cdd4-723d-4422-93df-a383c2458f65

📥 Commits

Reviewing files that changed from the base of the PR and between 168f831 and efed944.

⛔ Files ignored due to path filters (6)
  • docs/test-results/assets/final-performance-report/bge-batch-throughput-latency.svg is excluded by !**/*.svg
  • docs/test-results/assets/final-performance-report/claim-throughput-tail-latency.svg is excluded by !**/*.svg
  • docs/test-results/assets/final-performance-report/pdf-docx-e2e-load.svg is excluded by !**/*.svg
  • docs/test-results/assets/final-performance-report/queue-backpressure.svg is excluded by !**/*.svg
  • docs/test-results/assets/final-performance-report/vector-exact-hnsw-latency-recall.svg is excluded by !**/*.svg
  • docs/test-results/assets/final-performance-report/worker-horizontal-scaling.svg is excluded by !**/*.svg
📒 Files selected for processing (5)
  • docs/design/gimin-#145-final-performance-report.md
  • docs/test-results/gimin-#145-final-performance-report-data.json
  • docs/test-results/gimin-#145-final-performance-report.md
  • scripts/performance/generate_final_performance_report.py
  • scripts/performance/test_generate_final_performance_report.py

Comment thread docs/test-results/gimin-#145-final-performance-report.md Outdated
Comment thread docs/test-results/gimin-#145-final-performance-report.md
Comment thread scripts/performance/generate_final_performance_report.py Outdated
@Gimini-3
Gimini-3 merged commit 93a96cb into develop Aug 11, 2026
1 check passed
@Gimini-3 Gimini-3 self-assigned this Aug 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

인덱싱·Vector 검색 최종 통합 성능 리포트 및 그래프 지원 추가 구현

1 participant