본문으로 건너뛰기

Pipeline Studio QA 가이드 — 재실행 · 스케줄 · 실행 가드

이 문서는 Pipeline Studio 후속 기능을 QA가 화면에서 직접 따라 검증할 수 있도록 단계별 스크린샷과 함께 정리한 것입니다. 모든 화면은 실제 GenD 환경의 데모 워크스페이스에서 캡처했습니다.

대상 기능:

  • 1-click 재실행 — 종료된(성공/실패) 실행을 한 번에 다시 실행 (#2049)
  • 스케줄(cron) 정기 실행 — 파이프라인을 주기적으로 자동 실행 (#2053)
  • 실행 가드 — 비활성 파이프라인 실행 차단 / 실행 중 run 재실행 차단 (#2059)

사전 준비: 파이프라인 스튜디오에서 노드 그래프를 작성·배포해 둔 파이프라인이 1개 이상 있어야 합니다. 작성·배포 방법은 Pipeline Studio GUI 빌더를 참고하세요.

1. 스케줄(cron) 정기 실행​

파이프라인을 주기적으로 자동 실행하도록 설정합니다. 평가는 UTC 기준입니다(예: daily = 02:00 UTC = KST 11:00).

1-1. 스케줄 메뉴 열기​

목록 페이지에서 파이프라인 행 끝의 ⋯ 메뉴 → 스케줄을 선택합니다.

파이프라인 목록 ⋯ 메뉴 → 스케줄

1-2. 스케줄 다이얼로그​

프리셋(5분마다 / 15분마다 / 매시 / 6시간 / 12시간 / 매일 02:00) 또는 직접 입력(5-필드 cron) 중 선택합니다. 수동(스케줄 없음)을 고르면 스케줄이 해제됩니다.

스케줄 다이얼로그

1-3. ✅ 엣지: 잘못된 cron 식 거부 (422)​

직접 입력에 형식에 맞지 않는 값(예: nonsense-cron)을 넣고 저장하면 검증 에러 토스트가 뜨고 다이얼로그가 닫히지 않습니다. 올바른 값으로 다시 입력해야 합니다.

잘못된 cron 입력 검증 실패(422) — 다이얼로그 유지

1-4. 프리셋 저장 → 배지 확인​

5분마다를 선택하고 저장하면 "스케줄을 저장했습니다" 토스트와 함께 목록 행에 ⏱ 스케줄 배지가 표시됩니다.

스케줄 배지

1-5. ✅ 엣지: 재오픈 시 현재 값 프리필​

다이얼로그를 다시 열면 현재 설정된 프리셋이 선택된 상태로 표시됩니다.

재오픈 프리필

1-6. 스케줄 해제​

수동(스케줄 없음)을 선택하고 저장하면 배지가 사라집니다.

스케줄 해제됨

확인 포인트(QA): 스케줄을 설정하면 Dagster pipeline_studio_cron_sensor가 60초마다 평가하여 만기 시 자동으로 run을 트리거합니다. 실행 탭에서 created_by가 비어 있는(=시스템 트리거) run이 주기적으로 생기는지 확인하세요. (소스 노드 s3_op의 uri가 그래프에 설정되어 있어야 자동 실행이 성공합니다.)

폴더 감시(다중 파일 배치, s3_op 전용): 이 스케줄 다이얼로그 안의 "폴더 감시 (선택)" 섹션에서 S3 폴더를 지정하면, tick마다 신규 파일별로 run이 fan-out됩니다 — 사용법은 셀프서비스 튜토리얼의 "폴더 감시" 절을 참고하세요.

2. 1-click 재실행​

종료된 실행을 다시 실행합니다. 원본 실행의 입력값(파일 경로/파일명/seed)을 그대로 사용하되, 현재 배포된 리비전에서 실행합니다 — 따라서 "실패 → 설정 수정 → 재배포 → 재실행" 흐름에 적합합니다.

2-1. 실행 탭 열기​

빌더 우측 패널 실행 탭에서 실행 이력을 봅니다. 종료된(성공/실패) run에만 재실행 버튼이 보입니다(실행 중인 run에는 없음).

실행 탭 — 이력

2-2. 실패한 실행 + 인라인 에러​

실패한 run 카드에는 실패 노드의 에러 메시지가 인라인으로 표시되고, 우측에 재실행 버튼이 있습니다.

실패 run — 에러 + 재실행 버튼

2-3. 재실행 → 새 실행 생성​

재실행을 누르면 "재실행을 시작했습니다" 토스트와 함께 새 run이 목록 맨 위에 추가되고 폴링이 시작됩니다.

재실행 클릭

2-4. 재실행 성공​

(설정을 고친 뒤라면) 새 run이 성공으로 종료됩니다.

재실행 성공

확인 포인트(QA): ① 실행 중인 run에는 재실행 버튼이 없는지, ② 재실행 버튼을 빠르게 두 번 눌러도 run이 1개만 생기는지(진행 중 비활성화) 확인하세요.

3. 실행 가드 (엣지 케이스)​

소프트-disable 및 동시 실행을 막는 서버측 가드입니다.

3-1. ✅ 비활성 파이프라인 실행 차단 (409)​

파이프라인이 비활성(· 비활성) 상태면 실행할 수 없습니다. 빌더에서 실행을 시도하면 비활성 파이프라인은 실행할 수 없습니다. 먼저 활성화하세요 에러가 표시됩니다. 먼저 ⋯ 메뉴 등으로 활성화해야 합니다.

비활성 파이프라인 빌더 비활성 실행 차단 토스트(409)

Dagster cron 센서도 비활성 파이프라인은 자동으로 건너뜁니다 — 수동/자동 양쪽에서 일관되게 차단됩니다.

3-2. ✅ 실행 중 run 재실행 차단 (409)​

아직 실행 중(종료되지 않은) run은 재실행할 수 없습니다. 실행 탭에서 실행 중 run에는 재실행 버튼 자체가 노출되지 않으며, API로 직접 호출 시 아직 실행 중인 run 은 재실행할 수 없습니다 409가 반환됩니다. run이 종료된 뒤 재실행하세요.

4. 적재 결과 확인 (#2438)​

적재가 끝난 뒤 "이 실행이 무엇을 적재했는지"를 실행 탭 안에서 바로 볼 수 있습니다. 벡터 인덱스·AI 문서 메뉴로 이동할 필요가 없습니다.

4-1. 실행 펼치기 → 적재 결과​

실행 탭에서 성공한 run의 로그 디스클로저를 펼치면, 노드 로그 아래에 "적재 결과" 카드가 표시됩니다.

  • 요약: N개 청크 · <컬렉션> · <차원>차원 (예: 1개 청크 · DocumentChunks · 1024차원)
  • 소스: 적재된 파일명 (예: ps-test-report.pdf)
  • 청크 발췌: #인덱스 + 청크 본문 앞부분

실행 탭 적재 결과

동작 원리: 적재 결과는 벡터 노드가 청크에 저장한 소스(파일명) 로 벡터 백엔드(Weaviate)를 조회합니다. 따라서 "이 파일의 현재 인덱스 청크"를 보여줍니다(멱등 재적재라 최신 성공 실행 결과와 일치). 임베딩 벡터 원본과 접속 키는 응답·화면 어디에도 노출되지 않으며, 차원(길이) 만 표기됩니다.

적재가 없는 실행: 벡터 적재(sink) 노드가 없거나, 소스 파일명을 확인할 수 없거나, 비-Weaviate 백엔드이거나, 백엔드에 연결할 수 없으면 요약 대신 사유가 표시됩니다(무회귀 graceful).

4-2. 문서 프리뷰 열기 (#2444)​

적재 결과 카드의 "문서 프리뷰 열기" 링크를 누르면, 그 문서의 전체 프리뷰 다이얼로그가 열립니다 — 청크 내용·메타데이터, PDF 는 위치 하이라이트(좌표)까지. 실행 탭에서 곧바로 상세를 확인할 수 있어 벡터 인덱스·문서 메뉴로 이동할 필요가 없습니다.

적재 결과 + 문서 프리뷰 열기 링크 문서 프리뷰 다이얼로그

동작 원리(#2444): 벡터 적재 노드는 Weaviate upsert 후, 표준 수집 경로와 동일하게 문서를 Postgres 레지스트리에 등록합니다(IngestedFile + DocumentMetadata + DocumentChunkRecord). 따라서 PS 로 적재한 문서도 프리뷰가 정상 동작하고, 청크 오프셋(전 포맷)과 PDF 좌표 rects 로 위치 하이라이트가 표시됩니다. 등록은 best-effort — 실패해도 Weaviate 적재(실행)는 성공으로 유지됩니다.

4-3. 수집>문서 리스트에 등장 (#2444)​

PS 로 적재한 문서는 수집(Ingestion) > 문서 리스트에도 등장합니다(source = pipeline-studio). 업로드로 넣은 문서와 동일하게 클릭하면 프리뷰가 열립니다.

수집 문서 리스트 — PS 적재 문서(ps-test-report.pdf) 포함

재실행 멱등: 같은 문서를 재적재하면 동일 document_id(내용 해시 기반 UUID5)로 레코드가 갱신됩니다(중복 생성 없음).

QA 체크리스트 요약​

#시나리오기대 결과
1스케줄 프리셋 저장토스트 + 목록 배지
2잘못된 cron 직접 입력 → 저장422 에러 토스트 + 다이얼로그 유지
3스케줄 다이얼로그 재오픈현재 값 프리필
4수동 선택 → 저장배지 사라짐(해제)
5cron 만기 (UTC)센서가 자동 run 트리거(created_by 빈 값)
6실패 run 재실행새 run 생성 → (수정 후) 성공
7실행 중 run재실행 버튼 미노출
8재실행 더블클릭run 1개만 생성
9비활성 파이프라인 실행409 차단 토스트
10실행 중 run 재실행(API)409 차단
11성공 run 펼치기"적재 결과" 카드(요약·소스·청크 발췌) 표시
12적재 결과 응답벡터 원본/키 미노출, 차원만 표기
13"문서 프리뷰 열기" 클릭 (#2444)문서 프리뷰 다이얼로그(청크·메타·PDF 하이라이트) 오픈
14PS 적재 후 수집>문서 (#2444)문서가 리스트에 등장(source=pipeline-studio)
15동일 문서 재적재 (#2444)동일 document_id 레코드 갱신(중복 없음), 등록 실패해도 실행 성공