문서 인덱싱 실행과 상태 확인

이 페이지에서는 실제 문서를 인덱싱하고, 실행 완료 여부를 확인하며, 중단되거나 실패한 작업을 다시 실행하는 방법을 설명합니다.

샘플 문서로 전체 시스템을 처음 실행하려면 먼저 설치와 첫 실행을 진행합니다. 파싱, 청킹, NER, KG 구축 등 각 단계의 동작을 이해하려면 문서 인덱싱 파이프라인을 참고합니다.

문서 한 건 실행하기

전체 문서를 실행하기 전에 문서 한 건으로 파이프라인과 외부 서비스가 정상적으로 동작하는지 확인하는 것을 권장합니다.

먼저 Temporal을 시작하고 서버 상태를 점검합니다. struct4search-preflight가 정상 종료된 뒤 인덱싱을 실행합니다.

docker compose -f deploy/temporal-compose.yaml up -d
struct4search-preflight

struct4search-ingest \
  --config configs/production.yaml \
  --services configs/services/cold-services.yaml \
  --output <출력_디렉터리> \
  --document-id d002343_6b6d39ebe6

인자	설명
`--output`	단계별 산출물과 완료 기록을 저장할 디렉터리. 필수
`--config`	인덱싱 설정이 정의된 실행 프로파일
`--services`	파서, NER, LLM 등 실행에 필요한 서비스 정의
`--document-id`	처리할 문서 ID. 여러 번 지정할 수 있음
`--stack`	로컬 실행용 통합 설정. `--config`, `--services`와 함께 사용할 수 없음

실행기는 설정에 정의된 서비스를 확인한 뒤 해당 문서의 인덱싱 파이프라인을 실행합니다. 필요한 서비스와 주소는 외부 의존에서 확인합니다.

실행 결과 확인하기

인덱싱이 끝나면 <출력_디렉터리>/documents/<문서_ID>/complete.json을 확인합니다. 이 파일에는 run_id, document_id, indexed_units와 각 단계의 결과가 저장됩니다. 전체 실행 결과는 <출력_디렉터리>/FINAL_REPORT.json에서 확인합니다.

complete.json이 없으면 같은 위치의 failure.json과 실행 로그에서 실패한 단계를 확인합니다.

단계별 산출물이 저장되는 위치는 저장소와 보존에서 확인합니다. ID 연결은 용어 사전, 각 산출물의 주요 필드는 단계 문서의 입력과 출력에서 확인합니다.

여러 문서 실행하기

여러 문서를 처리하려면 --document-id를 반복해서 지정합니다.

struct4search-ingest \
  --config configs/production.yaml \
  --services configs/services/cold-services.yaml \
  --output <출력_디렉터리> \
  --document-id <문서_ID_1> \
  --document-id <문서_ID_2>

프로파일에 포함된 전체 문서를 처리하려면 --document-id를 생략합니다.

struct4search-ingest \
  --config configs/production.yaml \
  --services configs/services/cold-services.yaml \
  --output <출력_디렉터리>

전체 문서를 실행하기 전에는 문서 한 건으로 다음 항목을 먼저 확인합니다.

파서, NER, LLM, OpenSearch 서비스가 정상적으로 연결되는지
단계별 산출물이 생성되는지
최종 검색 단위가 OpenSearch에 저장되는지
완료 기록이 생성되는지

중단된 실행 이어서 시작하기

실행 프로세스가 종료되어도 완료된 작업은 <출력_디렉터리>/orchestration.sqlite3에 기록되고 단계별 산출물도 남습니다.

처음 실행할 때 사용한 설정, 출력 디렉터리와 --document-id 전체를 그대로 넣어 다시 실행합니다. 실행 기록에 완료된 것으로 남은 문서는 건너뛰고, 끝나지 않은 문서부터 이어서 처리합니다.

struct4search-ingest \
  --config configs/production.yaml \
  --services configs/services/cold-services.yaml \
  --output <기존_출력_디렉터리> \
  --document-id <기존_문서_ID>

따라서 단순히 실행이 중단된 경우에는 기존 산출물을 삭제하거나 새로운 출력 디렉터리를 만들지 않습니다.

다른 인덱싱 작업이 같은 실행 자원을 사용하고 있으면 중복 실행을 방지하기 위해 새 실행이 거부될 수 있습니다. 이 경우 오류 메시지에 표시된 실행 ID를 확인하고, 기존 작업이 실제로 실행 중인지 먼저 확인합니다.

실패한 문서 다시 실행하기

일부 문서만 실패했더라도 처음 실행한 문서 선택을 바꾸지 않습니다. 처음 실행과 같은 명령을 사용하면 완료된 문서는 실행 기록에서 확인해 건너뛰고 실패한 문서만 다시 처리합니다.

struct4search-ingest \
  --config configs/production.yaml \
  --services configs/services/cold-services.yaml \
  --output <기존_출력_디렉터리> \
  --document-id <처음_실행한_문서_ID_1> \
  --document-id <처음_실행한_문서_ID_2>

처음에 --document-id를 생략해 전체 문서를 실행했다면 다시 실행할 때도 생략합니다. 실패한 ID만 골라 같은 출력 디렉터리에 지정하면 최초 실행 기록과 달라져 실행이 거부됩니다. 기존 실행이 종료된 상태에서 다시 시작해야 합니다.

모델이나 설정을 변경한 경우

실행 중단과 설정 변경은 다르게 처리해야 합니다.

중단된 작업은 기존 산출물을 그대로 사용해 이어서 실행할 수 있지만, 다음 항목을 변경한 경우에는 기존 산출물이나 인덱스가 새 설정과 호환되지 않을 수 있습니다.

파서 또는 페이지 판정 방식
청킹 크기, 오버랩 또는 토크나이저
NER 모델 또는 라벨
Metadata 프롬프트 또는 출력 필드
KG 구성 방식
검색표현 생성 방식
임베딩 모델 또는 벡터 차원
OpenSearch 인덱스 매핑

이 경우 기존 출력 디렉터리를 재사용하지 않고 새 출력 디렉터리에서 실행합니다. 변경 항목별 재생성 범위에서 다음 사항도 확인합니다.

어느 단계부터 다시 생성해야 하는지
기존 출력 디렉터리를 재사용할 수 있는지
새 OpenSearch 인덱스가 필요한지
기존 문서의 검색 단위를 교체해야 하는지

특히 임베딩 모델, 벡터 차원 또는 인덱스 매핑을 변경한 경우에는 기존 인덱스에 섞지 않고 새 인덱스를 생성해야 합니다.

문제 해결

문제가 발생하면 실행 로그에서 마지막으로 성공한 단계를 먼저 확인한 뒤, 해당 단계가 사용하는 서비스를 점검합니다.

증상	먼저 확인할 것
다른 실행이 진행 중이라는 메시지와 함께 시작되지 않음	오류 메시지에 표시된 실행 ID와 기존 프로세스
스캔 문서의 파싱 단계에서 실패함	MinerU 서비스 상태와 주소
Metadata, KG 또는 검색표현이 생성되지 않음	LLM 서비스 상태, 모델 설정과 인증 정보
NER 단계에서 실패함	NER 서비스 상태와 모델 로드 여부
인덱싱 단계에서 실패함	OpenSearch 주소, 인덱스 존재 여부와 매핑
`403 index_create_block_exception` 오류가 발생함	서버의 디스크 여유 공간과 OpenSearch의 `cluster.blocks.create_index` 설정
실행은 끝났지만 완료 기록이 없음	마지막 단계의 오류와 누락된 산출물
일부 문서만 반복해서 실패함	해당 문서의 마지막 성공 단계와 입력 파일

서비스 주소와 실행 조건은 외부 의존에서 확인합니다.

확인할 내용	파일·심볼
실행 진입점	`backend/struct4search/entrypoints/cli/ingest.py` · `main`
중단된 실행 이어가기 및 중복 실행 방지	`backend/struct4search/entrypoints/cli/ingest.py` · `refuse_if_another_run_is_live`
실행 상태 기록과 재개 검증	`backend/struct4search/adapters/orchestration/back_pipeline.py` · `SqliteRunLedgerAdapter`
문서 실행과 완료 판정	`backend/struct4search/ingest/back.py` · `CompleteIngestExecutor`
SQLite 실행 기록	`backend/struct4search/orchestration/state_store.py` · `SqliteStateStore`
실행 프로파일	`configs/production.yaml`
서비스 정의	`configs/services/cold-services.yaml`

문서 한 건 실행하기​

실행 결과 확인하기​

여러 문서 실행하기​

중단된 실행 이어서 시작하기​

실패한 문서 다시 실행하기​

모델이나 설정을 변경한 경우​

문제 해결​

관련 코드​