본문으로 건너뛰기

파싱 노드(builtin.parse) 설정 QA 가이드

이 문서는 Pipeline Studio의 파싱 노드(builtin.parse, #2399)에 노출된 설정을 QA가 화면에서 단계별로 검증할 수 있도록 정리한 것입니다. 스크린샷은 커밋된 E2E 스펙 ui/tests/ps-parse-node-config-e2e.spec.ts가 QA_CAPTURE=1로 캡처한 것과 동일한 화면입니다.

개요​

파싱은 업로드된 파일(파일 바이트)을 텍스트 + 메타데이터로 추출하는 변환 노드입니다. 이전에는 노드를 선택해도 "이 노드는 설정이 없습니다"만 표시됐지만, 이제 백엔드 파서가 이미 수행하던 기능이 노드 설정으로 노출됩니다.

필드위치기본값적용 대상 / 동작
processor기본자동(외부 등록 시 우선)로컬 선택 시 외부 파싱 API 레지스트리를 건너뛰고 내장 파서(PyMuPDF/Tesseract)만 사용
page_range고급(전체)PDF. 1-20 또는 5 (1-based, inclusive). 무효값·미입력이면 전체 페이지
extract_images고급추출PDF 임베디드 이미지 추출 on/off
ocr_lang고급kor+eng이미지 OCR tesseract 언어 코드 (예: kor+eng, eng, jpn)
vlm_caption고급끔이미지 VLM 의미 캡션 생성. 켜면 캡션이 OCR 텍스트 앞에 prepend, 실패 시 OCR only 폴백

범위: 이 노드의 설정 패널은 100% 클라이언트측이라 백엔드 배포 없이도 UI 계약을 검증할 수 있습니다. 파싱이 설정을 실제로 소비하는지(런타임)는 파서 이미지(gend-api) + Dagster 코드서버 재빌드 후의 실행 또는 단위테스트(test_parsers.py / test_ps_handlers.py)로 검증합니다.

1. 파싱 노드 선택 → 기본 설정​

Pipeline Studio 빌더에서 좌측 팔레트의 파싱을 캔버스로 끌어다 놓고 노드를 클릭하면, 우측 설정 패널에 파서(processor) 기본 필드와 고급 설정 (4) 접이식이 나타납니다. 더 이상 "설정 없음" 문구는 없습니다.

파싱 노드 기본 설정 — 파서 선택

  • 파서: 기본 자동(외부 등록 시 우선). 드롭다운에 로컬(PyMuPDF/Tesseract) 선택지.
  • 힌트: "local = 외부 파싱 API 레지스트리를 건너뛰고 내장 파서만 사용".

2. 고급 설정 펼치기​

고급 설정 (4) 를 펼치면 4개 필드가 나타납니다.

파싱 노드 고급 설정 — page_range / extract_images / ocr_lang / vlm_caption

  • 페이지 범위 (PDF): 예: 1-20 또는 5 (1-based, 미입력 시 전체).
  • 임베디드 이미지 추출 (PDF): 기본 추출.
  • OCR 언어 (이미지): 기본 kor+eng — tesseract 언어 코드. 예: kor+eng, eng, jpn.
  • VLM 캡션 (이미지): 기본 끔 — 이미지 의미 캡션 생성(가용 provider 필요). 실패 시 OCR only 로 폴백.

3. 값 편집​

필드를 편집하면 노드 config에 반영됩니다. 예: 파서를 로컬, 페이지 범위를 1-20으로 지정.

파싱 노드 설정 값 편집

시나리오 시드​

세 가지 시연 시나리오는 make seed-parse-demo (또는 scripts/seed_parse_demo.py)로 시드할 수 있습니다. 각 시나리오는 실제 샘플 파일(scripts/sample-docs/parse_sample_report.pdf, parse_sample_scan.png)을 S3에 올리고 s3_op → builtin.parse(config) → chunk → embed → vector 그래프를 생성합니다(멱등):

파이프라인파싱 config시연 포인트
zz-parse-demo-pdf-page-range{processor: local, page_range: "1-2", extract_images: off}PDF 일부 페이지만 파싱
zz-parse-demo-pdf-full{processor: auto, extract_images: on}PDF 전체 + 이미지 추출
zz-parse-demo-image-ocr-kor{processor: local, ocr_lang: "kor+eng"}이미지 한국어 OCR

실제 PDF에 대한 동작은 검증됨: page_range=1-1이면 1페이지 텍스트만, 2-3이면 2·3페이지만 추출되고, extract_images=off이면 image_count=0입니다.

E2E 회귀 가드 / 캡처​

커밋된 스펙: ui/tests/ps-parse-node-config-e2e.spec.ts — 파싱 노드를 드롭 → 설정 패널에 기본/고급 필드가 렌더되는지 검증합니다. 위 스크린샷 갱신:

cd ui && QA_CAPTURE=1 E2E_USERNAME=admin E2E_PASSWORD=admin \
  pnpm exec playwright test ps-parse-node-config
# → docs-site/static/img/qa/parse-node/01-config-basic.png, 02-advanced-expanded.png, 03-configured.png

QA_CAPTURE 없이 실행하면 스크린샷 없이 순수 회귀 어서션으로 동작합니다.