Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,8 @@ OpenProxy를 경유하는 OpenSQL 3노드와 GCS 원본 저장소를 연결합
출력 Sanitization을 적용합니다.
- **RAGOps 운영 화면**: WebSocket으로 Job·Worker 상태를 갱신하고 실패 원인, Retry, Queue·동기화 상태를
관측하고 복구할 수 있습니다.
- **정합성 점검과 안전 복구**: 문서 원장과 Job·Chunk·Vector를 8가지 기준으로 비교해 Issue로 남기고, 기존 데이터를
지우거나 덮지 않는 Job·Vector 누락만 Outbox로 복구합니다. 관리자가 수동 실행하며 주기 점검은 기본으로 꺼져 있습니다.
- **환경별 저장소와 OpenSQL 연결**: Local Filesystem·GCS 저장소 Adapter와 OpenProxy A/B를 통한
OpenSQL 3노드 연결을 지원합니다. MinIO·AWS S3 Adapter도 코드에 남아 있어 선택해 쓸 수 있지만
현재 GCP 시험 저장소는 GCS입니다.
Expand Down Expand Up @@ -70,6 +72,7 @@ OpenProxy를 경유하는 OpenSQL 3노드와 GCS 원본 저장소를 연결합
|---|---|---|---|---|
| **하이브리드 검색 품질** | 짧은 용어·약어 질문을 벡터 검색만으로 찾지 못하는 문제 개선(예: `OM은 뭐야?` 정답 7위) | 로컬 백엔드 + BGE-M3, 문서 5개·청크 83개, topK 10, 질문 3세트 111문항, 증빙 커밋 2026-10-10 | 벡터 단독 → 하이브리드: 1위 정답 **82 → 92**. 사전에 기준을 고정한 세트 3(39문항) MRR@10 **0.784 → 0.868** | [검색 품질 측정](docs/test-results/kangcheolung-%23456-hybrid-search.md) |
| **DB·GCS 시점 복원** | DB가 보관한 문서 기록과 GCS 원본을 같은 시점으로 복원해 서로 맞는지 확인 | OpenSQL 기준 백업 + 연속 WAL을 격리 경로에서 지정 시점 T로 복원, GCS 독립 사본, 2026-10-15 | T 이전 쓰기 A 1건·이후 B 0건. 복원 DB가 참조하는 파일 91건 모두 사본에 존재, 복원 버킷 92객체 SHA-256 **92/92** 일치 | [시점 복원](docs/test-results/db-gcs-point-in-time-recovery-20261015/), [서비스 경로 후속 시험](docs/test-results/db-gcs-service-recovery-20261015/) |
| **정합성 점검·복구** | 검색 데이터가 원장과 어긋났을 때 점검기가 찾아내고, 안전한 경우만 복구해 검색이 돌아오는지 확인 | 로컬 격리 DB·BGE-M3, 시험 문서 4건(Chunk 20개), SQL과 Worker·Dispatcher 정지로 4종 주입, 수동 API·Backend 1대, 2026-10-16 | Vector 1행 누락·Job 누락 각 1건: 탐지 → 복구 Event 1건 → 새 Job → `INDEXED` → 재점검 종결, 검색 반환. 기존 Vector 4행 ID·해시 보존. 삭제 잔여·정체 버전은 보고만 함. 정상 삭제 문서에 남는 `MISSING_EMBEDDINGS` 오탐 1건 발견(수정: [#518](https://github.com/DocGrid/docgrid/issues/518)). 주기 점검·A/B·나머지 4개 유형은 미시험 | [격리 시험](docs/test-results/reconciler-repair-20261016/README.md), [설계](docs/design/gimin-%23517-reconciler-consistency-check.md) |
| **PDF·DOCX 인덱싱 E2E** | 실제 PDF·DOCX 여러 건을 함께 접수했을 때의 처리량과 데이터 완전성 측정 | 로컬 Apple Silicon 1대, PostgreSQL 17.8·MinIO·CPU BGE-M3, Worker Slot 2, 50·100문서 각 2회, 2026-08-11 | **31.046·32.063**문서/분. 합계 300문서·1,200 Vector에서 실패·재시도·미완료·중복 **0** | [최종 성능 리포트](docs/test-results/gimin-%23145-final-performance-report.md), [원본 측정](docs/test-results/gimin-%23143-pdf-docx-indexing-e2e-load-benchmark.md) |

검색 품질은 직접 작성한 질문과 작은 코퍼스, 성능은 로컬 개발 장비의 기준선입니다. 시점 복원은 RPO·RTO를
Expand Down
191 changes: 191 additions & 0 deletions docs/design/gimin-#517-reconciler-consistency-check.md

Large diffs are not rendered by default.

65 changes: 65 additions & 0 deletions docs/test-results/reconciler-repair-20261016/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# 정합성 점검기(Reconciler) 복구·보고 격리 시험

2026-10-16 KST에 develop `f238caf` JAR, 로컬 격리 PostgreSQL·Valkey·BGE-M3 컨테이너, 시험 문서 4건으로 Reconciler를 시험했다. 공개 서비스, GCP, 기존 로컬 DB와 사용자 데이터는 쓰지 않았다. 새 점검 로직이나 설정 변경 없이 기존 코드를 실행했다.

- 이슈: [#517](https://github.com/DocGrid/docgrid/issues/517)
- 설계: [정합성 점검기 설계](../../design/gimin-%23517-reconciler-consistency-check.md)

**복구 증명 2건(`MISSING_EMBEDDINGS`, `MISSING_JOB`)은 탐지부터 재점검 종결까지 통과했다. 보고 사례 2건(`DELETED_DOCUMENT_RESIDUE`, `STALLED_VERSION`)은 자동 복구 없이 보고만 했다. 단, 정상 삭제된 문서에 `MISSING_EMBEDDINGS`가 남는 기대와 다른 결과 1건을 발견했다. 이 시험에서는 코드를 고치지 않았고, 수정과 재시험은 [#518](https://github.com/DocGrid/docgrid/issues/518)에서 했다.**

## 실행 결과

| 실행 | 목적 | 주입 | 관측 | 판정 |
| --- | --- | --- | --- | --- |
| [run-baseline-01](run-baseline-01/README.md) | 깨끗한 상태 기준선 | 없음 | 버전 2개 점검, Issue 0건 | 통과 |
| [run-missing-embeddings-01](run-missing-embeddings-01/README.md) | Vector 누락 완결 복구 | ACTIVE Vector 1행 삭제 | 탐지 → Event 1 → 새 Job 1 → Worker → `RESOLVED`. 기존 Vector 4행 ID·해시 보존, 누락 1행만 같은 해시로 추가. 검색 1위가 복구 Vector | 통과 |
| [run-missing-job-01](run-missing-job-01/README.md) | Job 누락 완결 복구 | attempt 없는 `PENDING` Job 삭제 | Dispatcher가 재생성하지 않음 → 탐지 → Event 1 → 새 Job → Worker 켠 뒤 `INDEXED`. 검색 1·2위가 시험 문서 | 통과 |
| [run-deleted-residue-01](run-deleted-residue-01/README.md) | 삭제 문서 잔여 보고 | SQL 없음. Dispatcher 끈 채 정상 삭제 | `CRITICAL` 보고, `REPAIR` 0건, 단건 복구 409. 잔여 중 검색 0건. Outbox 처리 뒤 `RESOLVED` | **부분 통과**: 기대와 다른 `MISSING_EMBEDDINGS` 1건 |
| [run-stalled-version-01](run-stalled-version-01/README.md) | 정체 버전 보고와 동시 탐지 | `updated_at` 20분 과거로, 이어서 Job 삭제 | `STALLED_VERSION` `WARNING` → Job 삭제 뒤 `MISSING_JOB`과 동시 탐지, 정체는 `ERROR`로 상향. `REPAIR`는 `MISSING_JOB`만 예약 | 통과 |
| [run-final-check-01](run-final-check-01/README.md) | 최종 점검·무결성 | 없음 | OPEN 1건(위 기대와 다른 결과). Vector·Job 중복 0, 미처리 Outbox 0 | 기록 |

## 기대와 다른 결과

[run-deleted-residue-01](run-deleted-residue-01/README.md#기대와-다른-결과-정상-삭제-뒤-missing_embeddings-보고)에서 삭제 Event가 정상 처리되어 Vector가 모두 STALE이 된 뒤, 삭제된 문서의 현재 버전에 `MISSING_EMBEDDINGS`(`CRITICAL`, `repairable=false`)가 새로 열렸다. 이 Issue는 최종 점검까지 `OPEN`이었다.

코드상으로는 `SyncConsistencyInspector`의 Chunk·Vector 검사가 문서의 `DELETED` 상태를 제외하지 않는 것으로 보인다. 이 결과로 볼 때 정상 삭제된 문서마다 해소되지 않는 Issue가 하나씩 남을 수 있다. 자동 복구 Event는 만들지 않는다. 시험 지시에 따라 이 시험에서는 고치지 않았다. 원인 확인·수정·재시험은 [#518 검증 기록](../deleted-document-false-positive-20261016/README.md)에 있다.

## 환경

| 항목 | 값 |
| --- | --- |
| 실행 위치 | 로컬 macOS arm64, Temurin 17.0.18, Docker Desktop VM 7.75GiB |
| 앱 | develop `f238caf` bootJar, SHA-256 `f86e7da61fe9bfab5641a38a16935ba88468e9b86528e4797735f2c8a8d3057f` |
| DB | `pgvector/pgvector:0.8.1-pg17` 새 컨테이너. PostgreSQL 17.8, pgvector 0.8.1. 127.0.0.1 바인딩 |
| 기타 | Valkey 9.1 새 컨테이너, 저장소 `STORAGE_TYPE=local` 임시 디렉터리 |
| 임베딩 | 기존 `docgrid-embedding-server` 이미지의 새 컨테이너. 모델 캐시 volume을 읽기 전용으로 붙이고 오프라인 모드. BAAI/bge-m3 |
| RAG | `OLLAMA_SERVER_URL`을 닫힌 로컬 포트로 지정. 검색 뒤 RAG는 `FAILED`, 범위 밖 |
| Reconciler 설정 | 모두 기본값: 주기 점검 꺼짐, 배치 100, 정체 임계값 15분. 수동 API만 사용 |
| 계정 | Flyway `V28` 시드 ADMIN 계정(시험 DB 안에만 존재) |
| 문서 | [입력 생성기](inputs/generate_inputs.py)로 만든 가상 주제 TXT 4건, 각 Chunk 5개 |

Backend는 같은 JAR와 DB로 네 단계에 걸쳐 다시 띄웠다. 바꾼 것은 Worker·Dispatcher 켜짐 여부뿐이다.

| 단계 | Worker | Dispatcher | 사용한 실행 |
| --- | --- | --- | --- |
| 1 | 켬 | 켬 | 기준선, 증명 A, 문서 C 인덱싱 |
| 2 | 끔 | 끔 | 문서 C 삭제와 잔여 탐지 |
| 3 | 끔 | 켬 | 잔여 해소, 증명 B 주입·복구 예약, 정체 버전 |
| 4 | 켬 | 켬 | B·D 인덱싱 완료, 최종 점검 |

재현용 스크립트는 [scripts/](scripts/)에, 상태 조회 SQL은 [sql/](sql/)에, 단계별 Backend 핵심 로그는 [logs/](logs/)에 있다. DB 비밀번호와 JWT 비밀값은 실행마다 새로 만들었고 시험 뒤 삭제했다. 증거 파일에는 토큰을 남기지 않았다.

## 해석 범위

- 문서 4건과 Chunk 20개로 한 로컬 실행이다. 실제 운영 데이터, 대량 문서, 동시 부하, A/B 다중 Backend, 주기 점검 경로는 시험하지 않았다.
- 장애는 SQL과 Worker·Dispatcher 정지로 만든 제어된 상태다. 실제 장애 원인을 재현한 것은 아니다.
- `MISSING_CHUNKS`, `MODEL_MISMATCH`, `INVALID_CURRENT_VERSION`, `ORPHANED_DATA`는 이번에 주입하지 않았다.
- 관리 화면은 열지 않았다. 모든 호출은 관리자 REST API로 했다.
- 시간 값은 이 실행에서 관측한 값이며 처리 속도 기준으로 쓰지 않는다.

## 정리

- 단계마다 Backend를 SIGTERM으로 종료했다. Worker는 `graceful=true`로 종료됐다.
- 시험 컨테이너 3개(`docgrid-reconcile-pg/valkey/embedding-20261016`)를 `docker rm -f -v`로 익명 볼륨까지 삭제했고, 남은 컨테이너 0개를 확인했다.
- 임시 저장소 디렉터리, 비밀값 파일, 토큰, 질문 Vector 파일을 삭제했다.
- 기존 컨테이너(`docgrid-postgres17`, `docgrid-embedding` 등)와 다른 시험의 DB는 건드리지 않았다.
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
"""시험 전용 TXT 문서 4개를 결정적으로 생성한다. 실제 사용자 데이터가 아니다."""
import sys, pathlib
out = pathlib.Path(sys.argv[1])
docs = {
"rc517-a-harbor.txt": ("RC517A 가상 항만 야적장 운영 지침", [
"RC517A 야적장은 가상의 시험용 항만이며 실제 시설이 아니다.",
"컨테이너는 도착 순서가 아니라 선적 예정 시각 기준으로 블록에 배치한다.",
"냉동 컨테이너는 전원 소켓이 있는 R 구역에만 두고 두 시간마다 온도를 기록한다.",
"크레인 작업 반경 안에서는 보행자 통행을 막고 신호수가 무전으로 진입을 허가한다.",
"야간 반출은 게이트 예약 번호와 차량 번호가 모두 일치할 때만 승인한다.",
"위험물 컨테이너는 등급별 이격 거리를 지키고 소화 장비 위치를 교대 시 확인한다.",
]),
"rc517-b-observatory.txt": ("RC517B 가상 산악 천문대 관측 운영 기록", [
"RC517B 천문대는 가상의 시험용 관측소이며 실제 기관이 아니다.",
"관측 전에는 돔 내부와 외부의 온도 차를 줄이기 위해 한 시간 동안 환기한다.",
"구름 덮임이 사십 퍼센트를 넘으면 분광 관측을 멈추고 측광 관측으로 전환한다.",
"망원경 초점은 기온이 이 도 이상 변할 때마다 표준성으로 다시 맞춘다.",
"관측 자료는 원본과 보정본을 따로 저장하고 보정 단계마다 처리 시각을 남긴다.",
"달이 밝은 밤에는 장노출 촬영을 줄이고 밝은 변광성 위주로 일정을 바꾼다.",
]),
"rc517-c-apiary.txt": ("RC517C 가상 양봉장 계절 관리 기록", [
"RC517C 양봉장은 가상의 시험용 농장이며 실제 농가가 아니다.",
"봄철 첫 내검에서는 여왕벌 산란 상태와 저장 꿀의 양을 함께 확인한다.",
"분봉 징후가 보이면 왕대를 정리하고 빈 소비를 넣어 공간을 넓힌다.",
"장마 기간에는 벌통 받침을 높이고 출입구 주변의 물 고임을 막는다.",
"가을에는 월동 먹이를 충분히 남기고 응애 방제 기록을 통별로 정리한다.",
"겨울에는 벌통을 열지 않고 바깥 소리와 사체 수로 군세를 추정한다.",
]),
"rc517-d-bakery.txt": ("RC517D 가상 제빵 공정 표준서", [
"RC517D 제빵소는 가상의 시험용 공방이며 실제 사업장이 아니다.",
"반죽 온도는 이십육 도를 목표로 하고 물 온도로 계절 차이를 보정한다.",
"일차 발효는 부피가 두 배가 될 때까지 진행하고 손가락 자국으로 상태를 확인한다.",
"분할한 반죽은 무게 편차가 삼 그램을 넘지 않도록 다시 계량한다.",
"오븐은 굽기 삼십 분 전에 예열하고 첫 판은 온도계로 실제 온도를 확인한다.",
"구운 빵은 식힘 선반에서 중심 온도가 내려간 뒤에 포장한다.",
]),
}
for name, (title, sentences) in docs.items():
lines = [title, ""]
for section in range(1, 9):
lines.append(f"제{section}절. {title} 세부 항목 {section}")
for i, s in enumerate(sentences):
lines.append(f"{section}-{i+1}. {s} 이 항목은 {section}번째 점검 주기에 적용한다.")
lines.append("")
(out / name).write_text("\n".join(lines), encoding="utf-8")
print(name, len("\n".join(lines)))
Loading
Loading