14.1 인입 가능 포맷 / 검증 정책
| 형식 | 처리 | 비고 |
|---|---|---|
| 자체 구조 추출 파서 | 텍스트·표·이미지 추출 | |
| DOCX / XLSX | 자체 구조 추출 파서 | 오피스 변환 의존성 필요 |
| HWP / HWPX | 자체 파서 | 한컴오피스 OLE2 / ZIP-XML |
| CSV | 자체 파서 | UTF-8 / CP949 자동 감지, 500행 청킹 |
| 스캔 PDF / 필기 메모 | 별도 OCR 도구 | PoC 단계에서 도메인별 평가 후 결정 |
파일 검증 — 사전 거부 케이스:
- 빈 파일 / 200MB 초과
- 매직바이트 ↔ 확장자 불일치
- 손상 PDF / 암호 PDF
- 인코딩 감지 실패 (CSV) 거부 시 검증 오류 응답 — 사유 코드와 함께 호스트에 전달.
14.2 인입 우선순위 권장
1) SOP · 매뉴얼 · 표준 ← Triple-GraphRAG 강점 최대
2) 계약 · 규제 · 정책 ← 다중홉 + 출처 정밀 필요
3) 운영 DB (MES / ERP / LIMS) 커넥터 ← 문서 × 운영 데이터 통합
4) 외부 드라이브 (Google Drive 등, 옵트인) ← 사용자 동의 토글 후
5) 웹 자료 (4단계 폴백 크롤링) ← 옵션14.3 인입 진행 상태 폴링 패턴 — index_data_files 배치 컨텍스트
index_local_files는 동기 완료({ processed, skipped, errors })이므로 별도 폴링 불필요. 데이터 테이블 기반 배치 인입(index_data_files)의 data_uuid 단위 진행 상태 추적이 필요한 경우만 아래 패턴 사용.
14.3.1 index_local_files — 동기 완료 (참고)
입력
| 파라미터 | 타입 | 기본값 | 설명 |
|---|---|---|---|
filename | str? | null | 인입 대상 파일명. 미지정 시 디렉토리 전체 스캔 |
engine_slug | str | "default" | RAG 엔진 식별자 |
force_reindex | bool | False | 콘텐츠 해시 변경 없어도 강제 재인입 |
응답 — 동기
| 필드 | 타입 | 의미 |
|---|---|---|
processed | int | 인입 완료 건수 |
skipped | int | 스킵 건수 (이미 인입됨 + force_reindex=False) |
errors | list | 인입 실패 항목 (파일명·사유) |
14.3.2 index_data_files — 배치 인입 트리거
입력
| 파라미터 | 타입 | 기본값 | 설명 |
|---|---|---|---|
data_uuid | str? | null | 데이터 테이블의 FILE 항목 ID. 미지정 시 미처리 전체 인입 |
engine_slug | str | "default" | RAG 엔진 식별자 |
force_reindex | bool | False | 강제 재인입 |
응답
| 필드 | 타입 | 의미 |
|---|---|---|
processed | int | 인입 완료 건수 |
skipped | int | 스킵 건수 |
errors | list | 인입 실패 항목 |
14.3.3 get_rag_status — 진행 상태 조회
입력
| 파라미터 | 타입 | 기본값 | 설명 |
|---|---|---|---|
data_uuid | str | (필수) | 조회 대상 데이터 ID |
engine_slug | str? | "default" | RAG 엔진 식별자 |
응답
| 필드 | 타입 | 의미 |
|---|---|---|
status | str | done / failed / in_progress / pending (운영 환경 확인) |
progress | float? | 진행률 (0.0~1.0). 도구가 노출 시에만 채워짐 |
error | str? | status="failed" 시 사유 |
14.3.4 폴링 패턴 (호출 예시)
# 1) 배치 인입 트리거
batch = client.call_tool("index_data_files",
data_uuid="batch_2026Q1",
engine_slug="default",
)
# 응답: { "processed": 12, "skipped": 0, "errors": [] }
# 2) 진행 상태 폴링 — 응답 키는 14.3.3 정의 그대로
def wait_indexed(client, data_uuid, timeout_sec=300):
deadline = time.time() + timeout_sec
while time.time() < deadline:
s = client.call_tool("get_rag_status", data_uuid=data_uuid)
if s["status"] == "done":
return s
if s["status"] == "failed":
raise RuntimeError(s.get("error"))
time.sleep(2)
raise TimeoutError(f"indexing timeout: {data_uuid}")
wait_indexed(client, "batch_2026Q1")- 권장 타임아웃 — 단일 PDF 50MB 기준 5분. 표·이미지 풍부 문서는 +50% 여유
statusenum의 정확한 값은 운영 환경 확인. 본 예시는done/failed단순 분기 패턴
14.4 인입 실패 케이스 트라이아지
| 증상 | 원인 후보 | 대응 |
|---|---|---|
| 검증 오류 (포맷) | 매직바이트 불일치 | 사용자에게 파일 재확인 요청 |
| 검증 오류 (size) | 200MB 초과 | 분할 인입 권장 |
status=failed (파싱 단계) | 손상 PDF / 비표준 폼 | 사용자에게 재출력본 요청 |
status=failed (그래프 추출) | LLM 응답 형식 오류 | 자동 재시도 1회. 반복 시 운영 알람 |