[Feat] Chunk Embedding 생성 및 Vector 저장

[Gimini-3]

Summary

• 외부 /embed 호출을 EmbeddingClient로 분리해 Query와 문서 Embedding 흐름이 같은 전송 경계를 사용하도록 했습니다.
• Job 고정 Model과 정렬된 Chunk Snapshot을 사용하는 준비 Transaction → 외부 단건 순차 호출 → 완료 Transaction 흐름을 구현했습니다.
• Vector 차원·유한 값·SHA-256 Hash를 생성 직후와 저장 직전에 검증하고, Version·Model 단위 전체 Embedding Set만 원자 저장합니다.
• 관리자 Endpoint POST /admin/indexing-jobs/{jobId}/attempts/{attemptId}/embeddings를 추가했습니다.
• 최초 저장은 201 Created, 전체 결과 멱등 재생은 200 OK를 반환합니다.

Transaction / state contract

• 준비와 완료 단계 모두 EmbeddingJob → DocumentVersion 순서로 행을 잠급니다.
• 두 단계에서 현재 Worker, Claim Token, Lease와 STARTED Attempt를 검증합니다.
• 외부 HTTP 호출 중에는 DB Transaction과 행 잠금을 유지하지 않습니다.
• 최초 요청만 CHUNKED → EMBEDDING 전이와 EMBEDDING_STARTED 이벤트를 기록합니다.
• Vector 저장 후에도 Version은 EMBEDDING을 유지하며, Job·Attempt·Document 완료 처리는 후속 인덱싱 완료 기능에 남깁니다.
• 같은 실행의 동시 요청은 전체 Set을 먼저 저장한 한 요청과 기존 결과를 재생한 한 요청으로 수렴합니다.

Data contract

• EmbeddingJob.embeddingModel의 ID와 Dimension을 사용합니다.
• Chunk ID·Index·Text·Content Hash를 준비/완료 사이에 다시 비교합니다.
• Vector는 Model Dimension과 일치하고 모든 값이 유한해야 합니다.
• Vector Hash는 big-endian IEEE 754 float byte 배열의 SHA-256 소문자 Hex입니다.
• (chunk_id, embedding_model_id) Unique 제약과 Version 행 잠금을 중복 저장의 최종 방어선으로 사용합니다.

Verification

• ./gradlew clean build: 성공
• 전체 392 tests, 0 failures
• 실제 OpenSQL/pgvector 통합 검증:
  • vector(1024) 전체 Set 저장 및 재생
  • 두 번째 Chunk 외부 호출 실패 시 Embedding 0행 유지
  • 동시 요청 2건이 생성 1건 + 재생 1건, 단일 Embedding Set과 시작 이벤트 1건으로 수렴

Documentation

• docs/design/Gimini-3-#82-chunk-embedding-vector-storage.md

Closes #82

Summary by CodeRabbit

• 새 기능

  • 문서 Chunk의 Embedding을 생성하고 저장하는 API가 추가되었습니다.
  • 작업 소유권과 상태를 검증하며, 처리 결과를 안전하게 저장하고 재요청 시 기존 결과를 재생합니다.
  • Embedding 모델 및 Chunk별 결과 집계 정보를 응답으로 제공합니다.

• 버그 수정

  • 잘못된 상태, Vector 차원 및 유효하지 않은 값으로 인한 저장을 방지합니다.
  • 외부 Embedding 서버 장애나 동시 요청 시 부분 저장을 방지합니다.

• 문서

  • Embedding 생성 및 Vector 저장 설계 문서가 추가되었습니다.

[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: 37cab2a5-d21b-44d9-ae5b-3c818fc3f996

📥 Commits

Reviewing files that changed from the base of the PR and between 41014da and 55b8514.

📒 Files selected for processing (25)

• docs/design/Gimini-3-#82-chunk-embedding-vector-storage.md
• src/main/java/com/opensource/docgrid/domain/document/entity/DocumentVersion.java
• src/main/java/com/opensource/docgrid/domain/document/repository/DocumentChunkRepository.java
• src/main/java/com/opensource/docgrid/domain/embedding/client/EmbeddingClient.java
• src/main/java/com/opensource/docgrid/domain/embedding/controller/IndexingJobAdminController.java
• src/main/java/com/opensource/docgrid/domain/embedding/dto/request/CreateDocumentEmbeddingsRequest.java
• src/main/java/com/opensource/docgrid/domain/embedding/dto/response/DocumentEmbeddingsResponse.java
• src/main/java/com/opensource/docgrid/domain/embedding/entity/Embedding.java
• src/main/java/com/opensource/docgrid/domain/embedding/repository/EmbeddingRepository.java
• src/main/java/com/opensource/docgrid/domain/embedding/service/DocumentEmbeddingDraft.java
• src/main/java/com/opensource/docgrid/domain/embedding/service/DocumentEmbeddingGenerator.java
• src/main/java/com/opensource/docgrid/domain/embedding/service/DocumentEmbeddingService.java
• src/main/java/com/opensource/docgrid/domain/embedding/service/EmbeddingVectorSupport.java
• src/main/java/com/opensource/docgrid/domain/embedding/service/command/DocumentEmbeddingTransactionService.java
• src/main/java/com/opensource/docgrid/domain/embedding/service/query/QueryEmbeddingService.java
• src/main/java/com/opensource/docgrid/global/exception/ErrorCode.java
• src/test/java/com/opensource/docgrid/domain/document/entity/DocumentVersionTest.java
• src/test/java/com/opensource/docgrid/domain/embedding/client/EmbeddingClientTest.java
• src/test/java/com/opensource/docgrid/domain/embedding/controller/IndexingJobAdminControllerTest.java
• src/test/java/com/opensource/docgrid/domain/embedding/entity/EmbeddingTest.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
• src/test/java/com/opensource/docgrid/domain/embedding/service/query/QueryEmbeddingServiceTest.java

---

📝 Walkthrough

Walkthrough

문서 Chunk Embedding 생성 기능을 추가했다. Job 고정 모델과 Attempt 소유권을 검증하고, 외부 Vector를 순차 생성한다. Vector와 Chunk Snapshot을 재검증한 뒤 전체 Embedding을 원자 저장한다. 최초 생성, 재생, 실패, 동시 요청을 테스트한다.

Changes

문서 Embedding 생성 흐름

Layer / File(s)	Summary
계약·Client·Vector 기반 docs/design/..., src/main/java/com/opensource/docgrid/domain/document/..., src/main/java/com/opensource/docgrid/domain/embedding/client/..., src/main/java/com/opensource/docgrid/domain/embedding/dto/..., src/main/java/com/opensource/docgrid/domain/embedding/entity/..., src/main/java/com/opensource/docgrid/domain/embedding/repository/..., src/main/java/com/opensource/docgrid/domain/embedding/service/EmbeddingVectorSupport.java, src/main/java/com/opensource/docgrid/global/exception/ErrorCode.java, src/test/java/com/opensource/docgrid/domain/{document,embedding}/...	Embedding 요청·응답 DTO, 외부 EmbeddingClient, 정렬된 Chunk 조회, Vector 방어적 복사, 차원·유한성·SHA-256 검증을 추가했다. DocumentVersion의 CHUNKED → EMBEDDING 전이를 제한했다.
준비·생성·완료 Transaction src/main/java/com/opensource/docgrid/domain/embedding/service/{DocumentEmbeddingDraft,DocumentEmbeddingGenerator}.java, src/main/java/com/opensource/docgrid/domain/embedding/service/command/..., src/test/java/com/opensource/docgrid/domain/embedding/service/{DocumentEmbeddingGeneratorTest.java,command/...}	준비 단계에서 Job·Attempt·Version·Model·Chunk를 검증하고 Snapshot을 만든다. 외부 호출 결과를 Draft로 전달한다. 완료 단계에서 Snapshot과 Vector Hash를 재검증하고 전체 Embedding을 저장한다.
Service orchestration·관리 API src/main/java/com/opensource/docgrid/domain/embedding/service/DocumentEmbeddingService.java, src/main/java/com/opensource/docgrid/domain/embedding/controller/..., src/main/java/com/opensource/docgrid/domain/embedding/service/query/..., src/test/java/com/opensource/docgrid/domain/embedding/{controller,integration,service}/...	준비 Transaction, 외부 Embedding 생성, 완료 Transaction을 순서대로 실행한다. 관리 API는 최초 생성에 201, 완료 결과 재생에 200을 반환한다. Controller 계약, 원자성, 재호출, 동시 요청을 검증한다.

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

Sequence Diagram(s)

sequenceDiagram
  participant Admin as 관리자 API
  participant Service as DocumentEmbeddingService
  participant Tx as DocumentEmbeddingTransactionService
  participant Client as EmbeddingClient
  participant DB as Embedding 저장소

  Admin->>Service: Embedding 생성 요청
  Service->>Tx: 준비 Transaction 실행
  Tx-->>Service: Chunk Snapshot 반환
  Service->>Client: Chunk별 /embed 호출
  Client-->>Service: Vector 반환
  Service->>Tx: 완료 Transaction과 Draft 전달
  Tx->>DB: 전체 Embedding 원자 저장
  DB-->>Tx: 저장 결과 반환
  Tx-->>Service: 생성 또는 재생 결과 반환
  Service-->>Admin: 201 또는 200 응답

Loading

Possibly related PRs

• DocGrid/backend#38: EmbeddingClient가 호출하는 Embedding 서버와 /embed 계약을 도입했다.
• DocGrid/backend#49: Job Claim, Lease, Claim Token 소유권 검증 흐름을 제공한다.
• DocGrid/backend#76: Embedding 대상인 DocumentChunk와 정렬된 Chunk 처리 흐름을 제공한다.

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/82

---

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