AX Flow SDK 명세서 v2.0 · 통합 파트너 검토용 — 정식 스키마는 /docs Swagger UI를 단일 기준으로 사용합니다.
Operations
데이터 인입

14.1 인입 가능 포맷 / 검증 정책

형식처리비고
PDF자체 구조 추출 파서텍스트·표·이미지 추출
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 — 동기 완료 (참고)

입력

파라미터타입기본값설명
filenamestr?null인입 대상 파일명. 미지정 시 디렉토리 전체 스캔
engine_slugstr"default"RAG 엔진 식별자
force_reindexboolFalse콘텐츠 해시 변경 없어도 강제 재인입

응답 — 동기

필드타입의미
processedint인입 완료 건수
skippedint스킵 건수 (이미 인입됨 + force_reindex=False)
errorslist인입 실패 항목 (파일명·사유)

14.3.2 index_data_files — 배치 인입 트리거

입력

파라미터타입기본값설명
data_uuidstr?null데이터 테이블의 FILE 항목 ID. 미지정 시 미처리 전체 인입
engine_slugstr"default"RAG 엔진 식별자
force_reindexboolFalse강제 재인입

응답

필드타입의미
processedint인입 완료 건수
skippedint스킵 건수
errorslist인입 실패 항목

14.3.3 get_rag_status — 진행 상태 조회

입력

파라미터타입기본값설명
data_uuidstr(필수)조회 대상 데이터 ID
engine_slugstr?"default"RAG 엔진 식별자

응답

필드타입의미
statusstrdone / failed / in_progress / pending (운영 환경 확인)
progressfloat?진행률 (0.0~1.0). 도구가 노출 시에만 채워짐
errorstr?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% 여유
  • status enum의 정확한 값은 운영 환경 확인. 본 예시는 done / failed 단순 분기 패턴

14.4 인입 실패 케이스 트라이아지

증상원인 후보대응
검증 오류 (포맷)매직바이트 불일치사용자에게 파일 재확인 요청
검증 오류 (size)200MB 초과분할 인입 권장
status=failed (파싱 단계)손상 PDF / 비표준 폼사용자에게 재출력본 요청
status=failed (그래프 추출)LLM 응답 형식 오류자동 재시도 1회. 반복 시 운영 알람