[Feat] BGE-M3 배치 문서 임베딩 연동 지원 추가 구현

[Gimini-3]

작업 내용

• 기존 /embed 단건 계약을 유지하면서 문서 Chunk 전용 /embed/batch API를 추가했습니다.
• 문서 Embedding Batch 크기를 embedding.document.batch-size로 설정하고 1~64 범위를 검증합니다.
• Java Client와 Generator가 Chunk를 순서대로 Batch 처리하고 모델·개수·Index·차원·NaN·Infinity를 저장 전에 검증합니다.
• 모든 Batch가 성공한 경우에만 전체 Vector Set을 기존 완료 Transaction에서 원자 저장합니다.
• 중간 Batch 전송·검증 실패 시 완료 Transaction을 호출하지 않아 부분 저장을 방지합니다.

Closes #101

상세 설명

문서 Chunk 수만큼 반복되던 HTTP 및 BGE-M3 호출을 설정 가능한 Batch 단위로 줄였습니다. EmbeddingWork에 Model Name을 고정해 준비와 완료 Transaction 사이의 모델 변경도 차단합니다.

Query Embedding의 기존 단건 API와 응답 형식은 변경하지 않으며, Provider 전송 장애는 기존 Worker 자동 Retry 정책을 사용합니다.

검증

• Python Batch API 계약 테스트: 9 passed
• PostgreSQL 17 + pgvector 문서 Embedding 통합 테스트: passed
• 전체 Gradle 테스트: 588 tests, 0 failed
• 실제 BAAI/bge-m3 Batch Smoke
  • Vector 3개 모두 1024차원·유한 값
  • 관련 문장 Cosine: 0.849536
  • 무관 문장 Cosine: 0.350154

문서

• docs/design/Gimini-3-#101-bge-m3-batch-document-embedding.md
• docs/test-results/Gimini-3-#101-bge-m3-batch-document-embedding.md

추후 작업

• PDF·DOCX Parsing
• 업로드부터 실제 BGE-M3와 Vector 저장까지 전체 관통 E2E
• 공식 OpenSQL 17.8 원격 호환성 검증

Summary by CodeRabbit

• 새 기능

  • 문서 임베딩 생성이 배치 처리로 전환되어 대량 문서 처리 효율이 향상되었습니다.
  • 입력 순서와 임베딩 결과의 대응 관계를 보장합니다.
  • 배치 크기를 설정할 수 있으며 기본값은 16입니다.

• 버그 수정

  • 모델 불일치, 결과 개수·순서 오류, 잘못된 벡터 응답을 감지합니다.
  • 배치 처리 중 오류가 발생하면 일부 결과만 저장되지 않도록 처리됩니다.

• 문서화

  • 배치 임베딩 API 설계와 검증 결과를 문서화했습니다.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: e38e1f09-a345-481f-a733-bb31936b9951

📥 Commits

Reviewing files that changed from the base of the PR and between 6e6cfc3 and 739a2dc.

📒 Files selected for processing (20)

• .gitignore
• docs/design/Gimini-3-#101-bge-m3-batch-document-embedding.md
• docs/test-results/Gimini-3-#101-bge-m3-batch-document-embedding.md
• embedding-server/main.py
• embedding-server/requirements-test.txt
• embedding-server/test_main.py
• src/main/java/com/opensource/docgrid/domain/embedding/client/EmbeddingClient.java
• src/main/java/com/opensource/docgrid/domain/embedding/config/EmbeddingBatchProperties.java
• src/main/java/com/opensource/docgrid/domain/embedding/dto/request/EmbedBatchRequest.java
• src/main/java/com/opensource/docgrid/domain/embedding/dto/response/EmbedBatchItemResponse.java
• src/main/java/com/opensource/docgrid/domain/embedding/dto/response/EmbedBatchServerResponse.java
• src/main/java/com/opensource/docgrid/domain/embedding/service/DocumentEmbeddingGenerator.java
• src/main/java/com/opensource/docgrid/domain/embedding/service/command/DocumentEmbeddingTransactionService.java
• src/main/resources/application.yml
• src/test/java/com/opensource/docgrid/domain/embedding/client/EmbeddingClientTest.java
• src/test/java/com/opensource/docgrid/domain/embedding/config/EmbeddingBatchPropertiesTest.java
• src/test/java/com/opensource/docgrid/domain/embedding/integration/DocumentEmbeddingIntegrationTest.java
• src/test/java/com/opensource/docgrid/domain/embedding/service/DocumentEmbeddingGeneratorTest.java
• src/test/java/com/opensource/docgrid/domain/embedding/service/DocumentEmbeddingServiceTest.java
• src/test/java/com/opensource/docgrid/domain/embedding/service/command/DocumentEmbeddingTransactionServiceTest.java

---

📝 Walkthrough

Walkthrough

Python Embedding Server에 /embed/batch를 추가했다. Java 문서 임베딩 흐름은 설정 가능한 배치 호출과 응답 검증을 사용한다. 모델명, 벡터 차원, 유한값을 저장 전에 검증하며 배치 실패 시 완료 처리를 중단한다.

Changes

BGE-M3 배치 문서 임베딩

Layer / File(s)	Summary
Python 배치 API 계약 .gitignore, embedding-server/*, docs/design/...	POST /embed/batch가 입력을 검증하고 encode 결과를 입력 순서와 인덱스에 맞춰 반환한다. 기존 /embed 계약은 유지한다.
Java 배치 계약과 클라이언트 src/main/java/.../embedding/client/*, src/main/java/.../embedding/config/*, src/main/java/.../embedding/dto/*, src/main/resources/application.yml, src/test/java/.../embedding/client/*, src/test/java/.../embedding/config/*	배치 요청·응답 Record와 배치 크기 설정을 추가했다. EmbeddingClient는 HTTP 오류, null 응답, 모델·개수·인덱스 불일치를 오류 코드로 변환한다.
문서 임베딩 배치 생성과 모델 일치 검증 src/main/java/.../embedding/service/*, src/test/java/.../embedding/service/*	청크를 설정된 크기로 나누고 배치별 벡터를 검증한다. EmbeddingWork에 모델명을 저장하며 준비 시점과 완료 시점의 모델명을 비교한다.
통합 검증과 실행 기록 src/test/java/.../embedding/integration/*, docs/test-results/*, docs/design/*	배치 호출 횟수, 순서 보존, 중간 실패, 동시성 동작과 검증 범위를 기록하고 테스트한다.

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

Sequence Diagram(s)

sequenceDiagram
  participant DocumentEmbeddingGenerator
  participant EmbeddingClient
  participant EmbeddingServer
  DocumentEmbeddingGenerator->>EmbeddingClient: embedBatch(chunks, batchSize)
  EmbeddingClient->>EmbeddingServer: POST /embed/batch
  EmbeddingServer-->>EmbeddingClient: model, indexed vectors
  EmbeddingClient-->>DocumentEmbeddingGenerator: validated batch response
  DocumentEmbeddingGenerator-->>DocumentEmbeddingGenerator: validate vectors and create drafts

Loading

Possibly related PRs

• DocGrid/backend#45: EmbeddingClient와 Python /embed 연동 계약을 확장하는 공통 기반과 관련된다.
• DocGrid/backend#60: 동일한 BGE-M3 Embedding Server와 응답 계약을 사용한다.
• DocGrid/backend#83: EmbeddingClient와 DocumentEmbeddingGenerator 흐름을 배치 호출로 확장한다.

Suggested labels: ✨ Feature

✨ 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/101

---

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.}