chunk_count 정합성 확인 QA 가이드 (#1804)
이 문서는 적재(Ingestion) 파일 목록의 chunk_count 정합성 확인 기능을 QA가 화면에서 직접 따라 검증할 수 있도록 단계별 스크린샷과 함께 정리한 것입니다. 모든 화면은 실제 GenD prod 환경의 데모 워크스페이스에서 캡처했습니다.
개요
파일을 적재하면 GenD 는 문서를 청크로 쪼개고, 그 개수를 chunk_count 로 기록(Postgres 부기)합니다. 이 숫자는 실제 저장소 — Postgres 청크 레코드와 Weaviate 벡터 — 와 항상 일치해야 합니다. 하지만 적재가 중간에 끊기거나 일부 스토어에만 기록되면, 기록된 chunk_count 가 실제 저장량과 어긋날 수 있습니다.
특히 위험한 경우가 유령(phantom) 입니다 — 목록에는 chunk_count = 12 로 보이지만 실제 청크/벡터는 0개라, RAG·미리보기가 소리 없이 빈 결과를 내놓습니다. #1804 는 이 어긋남을 사용자가 on-demand 로 즉시 확인할 수 있는 affordance 를 파일 목록에 추가했습니다.
판정 상태
- 정합 (ok) — 기록 = PG = 벡터. 모두 일치.
- 불일치 (degraded) — 일부만 어긋남(기록 N / PG M / 벡터 K).
- 유령 (phantom) — 기록 > 0 인데 실제 저장 0. 재업로드 필요.
설계 노트(성능): 정합성 확인은 목록 로드 시 자동 발사하지 않습니다(행마다 Postgres count + Weaviate 조회 = N+1 + 벡터 비용). 사용자가 행의 정합성 확인 버튼을 클릭할 때만 호출됩니다(on-demand 전용). 한 번 받은 판정은 컴포넌트 상태에 보관돼 재렌더(목록 갱신 등)에는 다시 조회하지 않고 그대로 유지되며, 재적재로
chunk_count/updated_at이 바뀌면 이 캐시는 비워집니다. 단, 같은 버튼을 다시 클릭하면 최신 상태를 다시 확인하기 위해 새로 조회합니다(안정적인 파일이면 같은 판정이 다시 나옵니다).
사전 준비 / seed
- 별도 seed 가 필요하지 않습니다. 워크스페이스에 적재된 파일이 1건 이상 있으면 됩니다. 정상 워크스페이스의 파일은 보통 정합(ok) 으로 판정됩니다.
불일치(degraded)/유령(phantom)상태는 prod 에 자연 발생 파일이 거의 없고, 인위적으로 만들기(예:chunk_count > 0+ PG 청크 0행)가 공유 prod 에서 깔끔하게 되돌려지지 않습니다. 따라서 이 두 상태의 엔드포인트 판정 로직은apps/api/tests/test_chunk_count_consistency.py로, 셀의 배지 렌더링(불일치/유령 표시)은ui/src/components/ingestion/IngestionFilesTab.test.tsx(mock 판정값) 로 단위 검증합니다. 본 화면 가이드는 prod 가 실제로 돌려주는 판정(대개 정합)을 검증합니다.
1. 파일 목록 — 행마다 "정합성 확인" 버튼
좌측 메뉴에서 적재(레거시) 화면(/ingestion/legacy, Files 탭)으로 이동합니다. 각 파일 행의 청크(chunks) 열에 기록된 청크 수와 함께 방패 모양의 정합성 확인 버튼(aria-label="정합성 확인")이 있습니다.
확인 포인트(QA): 모든 파일 행에 정합성 확인 버튼이 하나씩 있는지, 그리고 화면 로드 시점에 자동으로 호출되지 않는지(버튼을 누르기 전에는 판정 배지가 없음) 확인하세요.
2. 정합성 확인 클릭 → 판정 배지 인라인 표시
확인 전에는 청크 수 옆에 숫자만 보입니다.
행의 정합성 확인 버튼을 클릭하면 GET /api/v1/ingestion/files/{id}/consistency-check 가 호출되고, 결과가 청크 수 바로 옆에 인라인 배지로 렌더됩니다. 정상 파일이면 초록색 정합 배지가 나타납니다(어긋나면 노란색 불일치, 빨간색 유령).
확인 포인트(QA): 클릭 후 셀 텍스트가 바뀌고 세 판정(정합 / 불일치 / 유령) 중 하나가 표시되는지 확인하세요. 정합 배지에 마우스를 올리면
기록 N / PG M / 벡터 K상세가 툴팁으로 보입니다. (벡터 스토어가 비활성/조회 불가면 벡터 값은-로 표시됩니다.)
3. 재확인은 멱등 — 판정 유지, on-demand 전용
목록을 처음 열었을 때는 정합성 확인이 자동으로 호출되지 않습니다(판정 배지 없음, on-demand 전용). 같은 행의 정합성 확인 버튼을 다시 클릭하면 최신 상태를 확인하기 위해 다시 조회하지만, 파일이 안정적이면 같은 판정(예: 정합)이 그대로 나오므로 결과는 멱등합니다.
확인 포인트(QA): 브라우저 개발자도구 Network 탭을 열고, 목록 로드 직후에는
…/consistency-check요청이 0건(자동 호출 없음)인지 확인하세요. 버튼을 누르면 1건이 찍히고 판정 배지가 나타납니다. 다시 누르면 새로 1건이 더 찍히지만 판정은 동일하게 유지됩니다. (재적재로 청크 수가 바뀌면 보관된 판정은 비워지고, 다음 확인 시 새로 조회합니다.)
4. API 직접 검증 (선택)
UI 없이 엔드포인트만 확인하려면 인증 토큰으로 다음을 호출합니다.
curl -H "Authorization: Bearer $TOKEN" \
https://gend.example.com/api/v1/ingestion/files/<FILE_ID>/consistency-check
응답(#1804 계약):
{
"file_id": "…",
"recorded_chunk_count": 12,
"postgres_chunk_records": 12,
"weaviate_vectors": 12,
"is_consistent": true,
"status": "ok"
}
status는 항상ok/degraded/phantom중 하나입니다.is_consistent는기록 == PG이고(벡터 == null 또는 벡터 == PG)일 때만true입니다.weaviate_vectors는 벡터 스토어 비활성/조회 불가 시null입니다(이 경우는 정합 판정에서 관대하게 처리).- 다른 워크스페이스(또는 존재하지 않는) 파일 id 로 호출하면 목록 엔드포인트와 동일한 워크스페이스 펜스가 적용돼 404 가 반환됩니다(절대 노출되지 않음).
QA 체크리스트 요약
| # | 시나리오 | 기대 결과 |
|---|---|---|
| 1 | 파일 목록 진입 | 행마다 정합성 확인 버튼 1개, 자동 호출 없음 |
| 2 | 정합성 확인 클릭 | 청크 수 옆에 정합/불일치/유령 인라인 배지 |
| 3 | 정상 파일 확인 | 정합(초록), 툴팁에 기록/PG/벡터 |
| 4 | 같은 행 재확인 | 로드 시 자동 호출 없음(0건), 클릭마다 재조회하되 판정은 동일(멱등) |
| 5 | API: 정상 id | 200 + 문서화된 6개 키, status ∈ {ok,degraded,phantom} |
| 6 | API: 타 워크스페이스/미지 id | 404 (워크스페이스 펜스) |
| 7 | 불일치/유령 렌더링 | API/단위 테스트로 검증(아래 참고) |
#7(불일치/유령 화면)은 prod 에 자연 발생 파일이 없어 본 가이드에서 화면 캡처 대신 엔드포인트 판정(
test_chunk_count_consistency.py)과 셀 배지 렌더(IngestionFilesTab.test.tsx, mock 판정값)로 검증합니다.
알아두기
- on-demand 전용: 목록 로드 시 자동 호출하지 않습니다(N+1 + Weaviate 비용 회피). 행 버튼 클릭 시에만 호출합니다. 받은 판정은 재렌더에도 유지되며, 버튼을 다시 누르면 최신 상태를 다시 조회합니다(안정 파일이면 같은 판정).
- 캐시 무효화: 재적재 등으로
chunk_count또는updated_at이 바뀌면 보관된 판정은 비워져 stale 판정을 보여주지 않습니다. - 유령(phantom) = 재업로드 신호: 기록은 있는데 실제 저장 0 이면 RAG/미리보기가 빈 결과를 내므로 해당 파일은 재업로드해야 합니다.
- 읽기 전용: 정합성 확인은 어떤 데이터도 변경하지 않습니다(read-only). 권한은 목록 조회와 동일한 viewer 권한입니다.