AI_PARSE_DOCUMENT

AI_PARSE_DOCUMENT

AI_PARSE_DOCUMENT() 함수는 Snowflake 스테이지의 문서에서 추출한 내용을 JSON 형식 문자열로 반환해요. 이 함수는 OCR(광학 문자 인식)과 레이아웃의 두 가지 추출 방식을 지원해요. 자세한 내용은 AI_PARSE_DOCUMENT로 문서 파싱하기 문서를 참고하세요.

지역 가용성: 특정 지역의 계정에는 기본적으로 사용 가능하고, 모든 지역의 계정에는 크로스 리전 추론(cross-region inference)으로 사용 가능해요.

출처: Snowflake SQL Reference

본문

문법

AI_PARSE_DOCUMENT( <file_object> [, <options> ] [, <return_error_details> ] )

인자

file_object (필수) — Snowflake 스테이지에 저장된, 파싱할 문서를 지정하는 FILE 객체예요. 파일 객체 생성에 대한 정보는 TO_FILE을 참고하세요.

options (선택) — 문서 파싱 옵션을 담은 OBJECT 값이에요. 지원되는 키는 아래와 같고 모두 선택 사항이에요.

  • 'extract_images': TRUE로 설정하면 함수가 문서에 포함된 이미지를 추출해요. LAYOUT 모드가 필요해요.
  • 'mode': 파싱 모드를 지정해요. 지원되는 모드는 다음과 같아요.
    • 'OCR': 함수가 텍스트만 추출해요. 기본 모드예요.
    • 'LAYOUT': 함수가 테이블 같은 구조적 콘텐츠를 포함해 레이아웃과 텍스트를 모두 추출해요.
  • 'page_split': TRUE로 설정하면 함수가 문서를 페이지로 나누고 각 페이지를 개별적으로 처리해요. 이 기능은 PDF, PowerPoint (.pptx), Word (.docx) 문서만 지원해요. 다른 형식의 문서는 오류를 반환해요. 기본값은 FALSE.

팁: AI_PARSE_DOCUMENT의 토큰 한도를 초과하는 긴 문서를 처리하려면 이 옵션을 TRUE로 설정하세요.

  • 'page_filter': 처리할 다중 페이지 문서의 페이지 범위를 지정하는 배열이에요. 각 범위는 범위의 첫 번째(포함)와 마지막(제외) 페이지를 지정하는 start와 end 필드를 가진 객체예요. 페이지 인덱스는 0부터 시작해요. 예를 들어 {'start': 0, 'end': 1}은 문서의 첫 페이지를 지정해요.

참고: page_filter를 지정하면 page_split이 암시돼요. 페이지 범위를 지정하면 page_split도 설정할 필요가 없어요.

return_error_details (선택) — 오류 발생 시 오류 세부 정보를 반환할지 나타내는 BOOLEAN 플래그예요. TRUE로 설정하면 함수는 value, error, metadata 필드를 담은 OBJECT를 반환해요. value 필드는 파싱된 문서 데이터를, error 필드는 오류 메시지(성공 시 NULL)를, metadata는 파싱된 출력의 하위 필드가 아니라 최상위 필드예요. 자세한 내용은 Error behavior 참고.

반환

추출된 데이터와 관련 메타데이터를 담은 JSON 객체(문자열로)를 반환해요. options 인자가 반환 객체의 구조를 결정해요.

팁: SQL에서 출력을 사용하려면 PARSE_JSON 함수로 OBJECT 값으로 변환하세요.

'page_split' 옵션이 설정되면 출력은 다음 구조를 가져요.

  • "pages": 문서에서 추출한 텍스트를 각각 담은 JSON 객체 배열. 문서에 페이지가 하나뿐이어도 출력에 여전히 "pages" 배열(단일 객체를 포함)이 있어요. 각 페이지는 다음 필드를 가져요.
    • "content": (OCR 모드의) 일반 텍스트 또는 (LAYOUT 모드의) Markdown 형식 텍스트.
    • "index": 0부터 시작하는 파일의 페이지 인덱스. 문서에 지정된 페이지 번호와 형식은 무시돼요.

'page_split'이 FALSE이거나 없으면 출력은 다음 구조를 가져요.

  • "content": (OCR 모드의) 일반 텍스트 또는 (LAYOUT 모드의) Markdown 형식 텍스트.

참고: pageCount 같은 문서 메타데이터는 위 출력 구조에 포함되지 않아요. 메타데이터를 반환하려면 return_error_details 인자로 TRUE를 전달하세요. 그러면 함수가 최상위 value, error, metadata 필드를 담은 OBJECT를 반환하며, metadata에는 pageCount 같은 필드가 들어 있어요.

"extract_images" 옵션이 TRUE로 설정되면 출력에 추가 필드가 포함돼요.

  • "images": 추출된 이미지를 각각 나타내는 JSON 객체 배열. 각 이미지 객체는 다음 필드를 가져요.
    • "id": 이미지의 고유 식별자.
    • "top_left_x", "top_left_y", "bottom_right_x", "bottom_right_y": 페이지에서 이미지의 경계 상자(bounding box) 좌표.
    • "image_base64": base64 문자열로 인코딩된 추출된 이미지 데이터.

오류 동작 (Error behavior)

기본적으로 AI_PARSE_DOCUMENT가 입력을 처리할 수 없으면 함수는 NULL을 반환해요. 쿼리가 여러 행을 처리하면 오류가 있는 행은 NULL을 반환하고 쿼리가 완료되는 것을 막지 않아요.

오류 시 반환 값은 return_error_details 인자에 따라 달라져요. 다음 표는 return_error_details 인자에 따른 반환 값을 보여줘요.

return_error_details 반환 값 설명
FALSE / 전달 안 함 NULL
TRUE value, error, metadata 필드를 가진 OBJECT value: 파싱된 문서 데이터를 담은 OBJECT, 오류가 발생했으면 NULL. error: 오류가 발생했으면 오류 메시지를 담은 VARCHAR, 함수가 성공하면 NULL. value 안의 error 필드(errorInformation에서 이름 변경)는 있을 때 문서별 오류 세부 정보를 담음. metadata: 페이지 수 같은 문서 메타데이터를 담은 OBJECT. 이 필드는 파싱된 출력 안이 아니라 최상위에 있음.

AI 함수의 오류 처리에 대한 자세한 내용은 Snowflake Cortex AI Function: Multirow error handling improvements 문서를 참고하세요.

예제

예제는 AI_PARSE_DOCUMENT 예제 문서를 참고하세요.

참고: AI_PARSE_DOCUMENT는 PARSE_DOCUMENT의 갱신된 버전이에요. 최신 기능을 사용하려면 AI_PARSE_DOCUMENT를 사용하세요.

법적 고지

법적 고지는 Snowflake AI and ML을 참고하세요.

더 알아보기 (Learn more)