콘텐츠로 이동

번역되지 않은 페이지는 영어로 열리며 영어로 표시됩니다.

이 페이지는 영어 원문을 기계 번역한 것이며, 영어 원문이 기준입니다. Machine-translated from the English page, which is authoritative.

문서 추출

업로드된 원본은 추출기 서비스가 추출 아티팩트라는 하나의 형태로 파싱합니다. 추출기 서비스는 자체 의존성을 가진 별도의 프로세스이며, Loom 서버가 아닙니다. 서버는 원본의 바이트를 해당 형식이 라우팅된 서비스로 보내고, 아티팩트를 신뢰할 수 없는 입력으로 간주하여 읽어 들인 뒤, 아티팩트의 블록에서 구조적 청크를 잘라냅니다. 따라서 SQL 구문, TOML 키, Markdown 섹션은 모두 원본을 가리키는 로케이터로 인용됩니다. Loom은 Markdown, HTML, 일반 텍스트, SQL, TOML, CSV, PDF, DOCX, PPTX, XLSX를 처리하는 참조 추출기(extractor/loom_extractor/)를 제공하며, pyarrow가 설치되어 있으면 Parquet도 처리합니다. 운영자는 동일한 와이어 계약을 따르는 다른 추출기를 실행할 수도 있습니다. knowledge.ingest는 업로드된 원본을 이 방식으로 추출하며(수집), 문서 소스 동기화는 등록된 폴더에 있는 PDF, .pptx, .docx 파일에 대해 이 추출기를 호출합니다(소스 동기화). knowledge.add는 호출자가 직접 추출한 텍스트를 받습니다.

서비스 경계

측면 담당 내용
Loom 서버 계약(server/knowledge/domain/extract/), 추출기가 반환한 결과에 대한 검사, 형식 라우팅, 구조 청커, 클라이언트(server/knowledge/app/extractors.py)
추출기 서비스 형식 감지, 엄격한 디코딩, 모든 파서. Loom 토큰, 데이터베이스 자격 증명, 버킷 접근 권한이 없습니다. 바이트를 받아 JSON을 반환합니다

파일을 파싱하는 일은 업로더가 제어하는 입력에 파서를 실행하는 일입니다. 이를 서버 프로세스 밖에 두면 파서 결함, 병리적인 입력, 파서의 의존성이 ClickHouse 자격 증명, 서명 키, 테넌트 데이터를 가진 프로세스에 닿지 않으며, 운영자가 특정 형식에 자신의 유틸리티를 대신 연결할 수 있습니다. tests/unit/test_package_contracts.py는 어떤 서버 모듈도 추출기, sqlglot, pypdf를 임포트하지 않으며, 지식 플레인이 파서 라이브러리를 임포트하지 않는지 검사합니다.

라우팅. 서버는 호출자가 알려 준 내용(선언된 형식, 없으면 파일 확장자, 없으면 미디어 유형, 없으면 text)으로 형식을 정하며 바이트는 읽지 않습니다. 그런 다음 원본을 LOOM_DOCUMENT_EXTRACTORS_JSON이 해당 형식에 지정한 서비스로 보냅니다. 미디어 유형이 그 형식을 가리키면 그 미디어 유형에 지정한 서비스로 보내고, 그렇지 않으면 LOOM_DOCUMENT_EXTRACTOR_URL로 보냅니다. 형식은 해당 서비스의 /v1/capabilities가 선언한 경우에만 추출됩니다. 선언은 1분 뒤에 다시 읽습니다. .doc, .xls, .ppt 이름은 어떤 호출보다 먼저 거부됩니다. 라우트 키는 형식 이름이거나 형식을 가리키는 미디어 유형이며, 매개변수와 대소문자를 무시하고 비교합니다. 그 밖의 키는 설정을 로드할 때 거부됩니다. 배포가 제공한다고 알리는 형식은 이 선언들이 말하는 내용입니다. knowledge.formats는 해당 형식의 파일이 갈 수 있는 서비스가 선언하면 그 형식을 사용 가능으로 보고하고, 그 서비스를 읽을 수 없는 동안에는 알 수 없음으로 보고합니다(미디어 유형의 라우트로만 제공되는 형식은 업로드가 그 미디어 유형을 담고 있을 때 읽습니다). 서비스들은 함께 5초 안에 읽습니다. 5초 안에 읽지 못한 서비스의 형식은 capabilities 읽기가 성공할 때까지 최대 1분 동안 알 수 없음으로 처리됩니다.

실패 시 차단. 설정된 서비스가 없는 형식, 그 형식을 선언하지 않은 서비스, 연결할 수 없는 서비스, 한 번의 호출 전체가 LOOM_DOCUMENT_EXTRACTOR_TIMEOUT_S보다 오래 걸리는 서비스, 서버의 토큰을 거부하는 서비스(401, 403, 407), 408, 429, format_unavailable, 5xx 또는 200도 4xx도 아닌 응답(리디렉션, 204)을 보내는 서비스는 ExtractorUnavailable을 발생시키며, 해당 소스는 다시 시도할 수 있습니다. 서비스가 거부한 소스는 계약의 코드(format_mismatch, encoding, too_large, timeout, resource_limit, ...)와 함께 ExtractionFailed를 발생시키며, 계약을 위반한 응답(invalid_artifact)도 마찬가지입니다. 프로세스 내 대체 경로는 없습니다. 추출기를 설정하지 않으면 어떤 원본도 추출되지 않습니다.

토큰. 서버는 각 서비스에 LOOM_DOCUMENT_EXTRACTOR_TOKENS_JSON이 그 URL에 대해 가진 토큰을 보내고, 없으면 LOOM_DOCUMENT_EXTRACTOR_TOKEN을 보냅니다. 따라서 운영자의 자체 서비스가 참조 추출기가 받아들이는 토큰을 가질 필요가 없습니다.

신뢰할 수 없는 출력. 서버는 압축하지 않은 응답을 요청하고(Accept-Encoding: identity), 압축된 응답은 서비스를 사용할 수 없는 것으로 취급하며, LOOM_DOCUMENT_EXTRACTOR_MAX_ARTIFACT_BYTES까지 아티팩트를 읽고 그보다 긴 것은 resource_limit으로 거부합니다. 그런 다음 청크 분할, 임베딩, 게시에 앞서 parse_artifact가 다음을 검사합니다. 스키마 버전, 요청한 형식, 각 블록의 유형, 고유한 id와 앞선 블록인 부모, 블록당 최대 1,024자의 키 10,000개와 500자의 섹션 경로 항목 64개(긴 블록에서 잘라 낸 청크가 그 블록의 키를 공유하므로 청크당 작업량이 선형으로 유지됩니다), 범위인 로케이터 스팬, 전체 이내인 커버리지 수, 유효한 유니코드인 문자열, JSON인 숫자(NaN이나 Infinity 없음, 부호 있는 64비트 정수(-2^63 ~ 2^63-1), 그 밖의 숫자는 double 범위 이내), 각 테이블의 형태(고유한 id, 500자 이내 이름의 형식 있는 열 최대 16,384개, 열 수와 같은 길이이며 스칼라 또는 셀 오류로 이루어진 행, 로케이터인 시트와 행), attrs와 options의 중첩 깊이(16, 참조 TOML 파서는 8보다 깊게 중첩된 값의 attrs.value를 생략하며 그 텍스트는 블록이 유지합니다). complete는 개수, 실패, 손실로부터 다시 계산되며, 플래그가 일치하지 않는 아티팩트는 거부됩니다. 계약에 명시되지 않은 필드는 버려집니다. 서버는 서비스가 보낸 바이트가 아니라 자신이 직렬화한 결과의 SHA-256으로 아티팩트를 지정합니다.

참조 추출기의 격리. 모든 /v1 호출은 Authorization: Bearer <token>을 포함해야 하며, 서비스는 16자 이상의 토큰이 없으면 시작을 거부합니다. 각 추출은 자식 프로세스에서 실행되며, 자식이 소스를 읽기 전에 다음이 적용됩니다.

자식 프로세스 방법
환경 변수가 없습니다 PYTHONPATH, PATH, LC_ALL만 지정해 시작하므로 토큰이 들어 있지 않습니다
서비스나 다른 자식을 읽을 수 없습니다 서비스와 모든 자식이 덤프 불가(PR_SET_DUMPABLE) 상태이므로, 같은 사용자의 프로세스가 /proc이나 ptrace로 그들의 환경, 메모리, 열린 파일을 읽을 수 없습니다
리소스가 제한됩니다 주소 공간(LOOM_EXTRACTOR_MEMORY_MB), CPU 초, 파일 크기 0(빈 파일은 만들 수 있지만 쓸 수는 없음), 코어 덤프 없음
프로세스를 시작하지 않습니다 RLIMIT_NPROC 0이므로 파서가 시작한 것은 추출보다 오래 살아남지 못합니다. 타임아웃, 연결 끊김, 취소 시점에 아직 실행 중인 자식은 슬롯이 해제되기 전에 프로세스 그룹과 함께 종료됩니다
소켓을 열지 않습니다 no-new-privileges 이후에 설정된 seccomp 필터가 socket, socketpair, io_uring_setup을 EPERM으로 실패시키며, ptrace, process_vm_readv, process_vm_writev, pidfd_getfd도 마찬가지입니다(x86_64와 aarch64이며, 다른 아키텍처에서는 서비스가 시작을 거부합니다). 따라서 네트워크상의 Loom 서버를 포함해 어떤 주소에도 도달하지 못합니다. 동시에 실행 중인 형제 프로세스는 덤프 불가가 되기 전까지 /proc/<pid>/mem을 통해 쓰기가 가능하므로, LOOM_EXTRACTOR_CONCURRENCY가 1보다 크면 장악된 자식이 스스로 필터를 적용하기 전에 형제를 변조할 수 있습니다
exec로 권한을 얻지 못합니다 서비스와 각 자식에 PR_SET_NO_NEW_PRIVS가 적용되므로 setuid 바이너리나 파일 capability로 권한을 올릴 수 없습니다
패키지만 로드합니다 -P와 함께 /에서 실행되므로 현재 디렉터리나 스크립트 디렉터리가 sys.path에 없습니다. 패키지와 그 의존성은 서비스 사용자에게 읽기 전용으로 설치되는데, sys.path에 있는 자체 파일이 이후 모든 자식이 임포트하는 내용을 바꿀 수 있기 때문입니다
요청을 보여 주지 않습니다 명령줄에는 제한값만 들어 있고, 파일 이름과 옵션은 stdin으로 전달됩니다

서비스는 실제 경과 시간 타임아웃에 도달했을 때, 호출자의 연결이 끊어졌을 때, 출력이 아티팩트 한도를 넘었을 때 자식을 종료합니다. 그리고 LOOM_EXTRACTOR_CONCURRENCY 슬롯 중 하나가 비어 있을 때만 소스를 읽으므로, 이 한도는 메모리에 보관되는 원본도 포함합니다. 슬롯은 기본적으로 1개입니다. 자식은 시작부터 스스로 덤프 불가로 만들 때까지 같은 사용자의 다른 프로세스가 읽을 수 있으므로, 악의적인 소스에 장악된 자식이 그 순간에 동시에 실행 중인 자식의 소스를 열 수 있습니다. 슬롯이 아니라 서비스 레플리카로 확장하십시오. 커널은 root나 CAP_SYS_RESOURCE 또는 CAP_SYS_ADMIN을 가진 프로세스에는 프로세스 한도를 적용하지 않으므로, 서비스는 root로 시작하거나 두 capability 중 하나가 허용된 상태로 시작하는 것을 거부합니다. 자식은 자신의 프로세스에서 파일 시스템 읽기가 거부되지 않으며, 이를 막는 것은 자식이 실행되는 컨테이너입니다. 서비스는 소켓 필터가 다루지 않는 아키텍처에서는 시작을 거부합니다. 설정은 extractor/README.md에 있습니다.

아티팩트

구성 요소 담는 내용
blocks 소스의 구조를 순서대로 담습니다: heading, paragraph, list, code, sql_statement, toml_table, toml_key, ...; 각 블록은 텍스트, 로케이터, 섹션 경로, 부모를 가집니다
tables 소스가 담고 있는 테이블: 각각 이름, 타입이 지정된 열, 값의 행, 헤더 행 수, 로케이터를 가집니다 (CSV, XLSX, PDF, Parquet)
coverage 포맷을 구성하는 단위(lines, statements, keys, chars, pages, paragraphs, slides, rows), 그 단위의 전체 개수, 추출된 개수, 실패한 각 단위와 그 사유, 손실된 각 기능
warnings 모호한 SQL 방언처럼 독자가 알아야 할 사실
options 파싱 시 적용된 재정의 값(SQL 전용 sql_dialect, 코덱 이름으로 지정하는 encoding)
attrs 포맷 관련 사실(dialect, dialect_source, dialect_candidates; HTML 페이지 또는 PDF의 title; PDF의 pages와 furniture, 프레젠테이션의 slides, 통합 문서의 sheets; images_unread, 그림, 차트, 다이어그램 또는 포함된 개체를 읽지 않은 텍스트 PDF 페이지 또는 PPTX 슬라이드)

블록의 id는 b<ordinal>이며, 해당 아티팩트 안에서 안정적입니다. keys는 독자가 블록을 찾아볼 수 있는 정확한 이름입니다: SQL 문이 생성하고, 쓰고, 읽는 개체와 그 열(sqlglot이 파싱하지 못하는 문은 토큰에 담긴 모든 이름), 한정된 이름은 마지막 부분만으로도(analytics.events의 경우 events), 따옴표 없이(db.`my.table`의 경우 my.table; 따옴표로 묶인 부분은 점을 유지합니다); TOML 테이블 또는 키의 전체 경로와 인덱스를 뺀 형태입니다.

로케이터는 해당하는 필드만 설정합니다: 모든 텍스트 포맷에는 line_start/line_end(1부터 시작), Markdown, 일반 텍스트, SQL, 유효하지 않은 TOML 파일의 텍스트 블록에는 char_start/char_end(디코딩된 텍스트에서의 오프셋), TOML에는 key_path, PDF의 페이지와 PPTX 프레젠테이션의 슬라이드에는 page_start/page_end(1부터 시작), 통합 문서의 시트와 CSV 파일의 행, 그리고 페이지가 있는 PDF 테이블의 행에는 sheet와 row_start/row_end(헤더 포함)를 사용합니다. DOCX에는 자체 페이지가 없으므로(페이지 나누기는 렌더러가 결정합니다) 블록에 로케이터가 없으며, 인용은 섹션 경로를 지칭합니다. Markdown 제목의 범위는 마크업을 포함한 소스 행 전체를 포괄하지만 텍스트는 정리된 제목이므로, 긴 제목의 윈도는 제목 전체 범위를 인용합니다. 여러 블록에서 잘라낸 청크는 그 블록들의 행, 문자, 페이지, 행 범위를 포괄하며, 모든 블록이 같은 시트를 가리키면 그 시트를 유지합니다.

아티팩트는 정렬된 간결한 JSON으로 직렬화되어 schema_version을 갖고, 그 바이트의 SHA-256으로 주소가 지정됩니다. 파서나 옵션이 바뀌면 같은 소스 리비전에 대해 새 아티팩트가 만들어지며, 아티팩트는 수정되지 않습니다. 리더는 알지 못하는 schema_version을 거부합니다. parser_version은 파싱이 의존하는 대상을 나타냅니다: SQL은 sqlglot의 버전, PDF는 pypdf의 버전(OCR이 페이지나 슬라이드를 읽은 경우 Tesseract의 버전 포함), HTML, TOML, CSV, XLSX는 Python 버전이며, 이 파서들은 Python과 함께 제공됩니다(csv와 그 sniffer, 텍스트로 쓰인 XLSX 날짜에는 datetime.fromisoformat).

참조 추출기의 형식

PDF, DOCX, PPTX 리더가 문서의 텍스트, 제목, 표, 페이지를 얼마나 잘 보존하는지는 레이아웃 모델 기준선과 비교하여 문서 파싱 결과에서 측정합니다.

detect_format은 파일 이름보다 바이트를 먼저 읽습니다. PDF, DOCX·PPTX·XLSX 컨테이너(zip 안의 파트로 판별), Parquet 파일은 내용으로 인식합니다. 바이트와 다른 형식을 주장하는 이름은 거부되며(format_mismatch), 구형 바이너리 Office 파일도 거부됩니다(unsupported_format). 형식을 선언하지 않은 .doc, .xls, .ppt 이름도 마찬가지입니다. 텍스트는 엄격하게 디코딩합니다. 바이트 순서 표시(BOM)에 따라 UTF-8, UTF-16, UTF-32로 읽거나 선언된 인코딩으로 읽으며, 텍스트가 UTF-8이면 선언 여부와 관계없이 UTF-8 BOM은 제거하고, 선언된 바이트 순서 코덱(utf-16-le)의 표시도 제거합니다. 디코딩할 수 없는 바이트는 그 오프셋을 알려 주는 encoding 실패이며, 선언되지 않은 UTF-8 텍스트(BOM 뒤든 아니든)의 NUL 바이트는 바이너리로 취급합니다. 어느 쪽도 치환하여 색인하지 않습니다.

형식 파서 블록
Markdown CommonMark의 제목, 펜스, HTML 블록 규칙을 따르는 블록 파서 제목, 문단, 목록, 펜스 코드, 프런트 매터
일반 텍스트 문단 분리기 빈 줄이 아닌 줄의 연속마다 문단 하나(# 줄은 제목이 아니라 텍스트)
HTML 표준 라이브러리의 파서 제목, 문단, 목록 항목, 표, 인용, 정의, pre
SQL sqlglot, 실행하지 않음 문장마다 블록 하나
TOML tomllib와 줄 스캐너 테이블 헤더마다, 키마다 블록 하나
PDF pypdf: 텍스트 런의 위치와 그려진 선, OCR 페이지별: 제목, 문단, 목록, 코드, 표. 페이지 장식 요소는 제외
DOCX 표준 라이브러리의 zip 및 XML 리더 제목, 문단, 목록, 표, 각주와 미주
PPTX 표준 라이브러리의 zip 및 XML 리더 슬라이드별: 제목은 제목 블록, 각 텍스트 도형, 표, 발표자 노트
CSV 표준 라이브러리의 csv 표 하나. 행은 최대 20행 단위 블록
XLSX 표준 라이브러리의 zip 및 XML 리더 시트별: 표, 이름은 제목, 행은 최대 20행 단위 블록
Parquet pyarrow, 메모리의 바이트에서 읽음 표 하나. 행은 최대 20행 단위 블록

Markdown. 제목은 ATX, setext, 한 줄짜리 <hN>입니다. setext 밑줄(최대 세 칸 들여쓰기) 위의 문단은 제목 하나이며, 목록 항목, 인용, --- 위의 주제 구분선은 제목이 아닙니다. 펜스 블록은 펜스를 제외한 본문 줄을 유지합니다. 펜스는 같은 문자가 같거나 더 길게 단독으로 나오면 닫히고, 언어는 정보 문자열의 첫 단어이며 나머지는 info로 유지합니다(빈 블록도 유지). 문단 안에서는 글머리 기호나 1로 번호가 매겨진 항목만 목록을 시작하므로, 2019.로 시작하는 줄바꿈된 줄은 본문으로 남습니다. 주제 구분선(***, - - -)은 마크업이며 위의 문단이나 목록을 끝내고 어떤 블록의 텍스트도 되지 않습니다. HTML 블록은 작성된 그대로 문단 블록 하나이며 제목의 제목이 되지 않습니다(CommonMark의 시작 조건). 주석, <?, <![CDATA[, <!(<!DOCTYPE html>), 원시 텍스트 태그(<pre>, <script>, <style>, <textarea>)로 시작한 블록은 끝 표시(-->, </pre>)가 있는 줄에서 끝나므로 그다음 줄이 setext 제목이 될 수 있습니다. 블록 수준 태그(<p align="center">, <div>)나 태그만 있는 줄(</div>)로 시작한 블록은 빈 줄에서 끝납니다. 태그만 있는 줄을 제외한 각 블록은 위의 문단을 끝내며, 문단 안의 태그만 있는 줄은 그 문단의 텍스트입니다. 빈 ATX 제목(# #)은 위의 문단을 끝내는 마크업이고, 제목이 정리하면 아무것도 남지 않는 경우(# <img src="logo.svg">)는 문단으로 남습니다. 맨 앞의 YAML 프런트 매터(--- 표시 사이의 key: 줄이며, 줄 시작의 # 뒤에 공백이 있으면 주석이 아니라 제목)는 블록 하나입니다. 블록은 줄 범위와 문자 범위를 가지며, 커버리지는 비어 있지 않은 줄을 셉니다. 이 줄은 모두 어떤 블록에 속하거나, 펜스·프런트 매터 구분자, 주제 구분선, 빈 ATX 제목 중 하나입니다(블록의 범위로부터 계산하며, 파서 변경으로 줄이 누락되는 것을 막는 장치입니다).

이 규칙은 추출기 자체의 규칙입니다(extractor/loom_extractor/markdown.py). 호출자가 추출한 텍스트를 섹션으로 나누는 knowledge.add 제목 분리기는 별도의 규칙을 유지하므로 같은 문서를 다르게 나눌 수 있습니다.

제목의 제목 텍스트는 그 아래 섹션 경로에 처음 500자까지만 들어가며, 잘린 부분은 아래 계약 한도에서 설명하는 대로 표시됩니다. 제목 블록은 전체를 유지하며 청크보다 긴 다른 블록처럼 윈도우로 나뉩니다.

HTML. blockquote, dd, dt는 문단이며, 목록 항목을 여는 <p>와 그 뒤의 <p>들은 그 항목의 텍스트입니다. 끝 태그가 생략된 블록은 다음 블록, 컨테이너의 끝, 문서의 끝에서 닫힙니다(블록 안의 컨테이너는 그것을 열어 둔 채로 두며, br, hr, 컨테이너의 시작은 단어를 구분합니다). 닫히지 않은 head는 첫 body 요소나 텍스트에서 닫힙니다. 블록의 줄 범위는 첫 텍스트 줄부터 마지막 줄까지입니다. script, style, template, noscript, svg, title, head는 블록에서 제외됩니다(<title> 텍스트는 아티팩트의 attrs.title). 커버리지는 그 바깥의 눈에 보이는 문자 수와 블록이 담은 문자 수를 셉니다(표의 셀을 잇는 파이프는 제외하며, 같은 종류의 안전장치입니다). 블록이 내부에서 잃는 것, 예를 들어 제거된 인라인 태그는 어느 쪽에서도 세지 않습니다. 열린 채 남은 숨김 요소는 문서의 나머지를 숨기며, 그 안의 텍스트는 읽지 않은 것으로 집계되고 열린 요소를 알려 주는 실패가 함께 보고됩니다.

HTML 표. <table>은 블록 하나이며, 행마다 한 줄이고 셀은 파이프로 이어지며 attrs.table에 rows와 columns가 들어갑니다. DOCX 표와 같지만 텍스트가 없는 행은 제외됩니다. 행이 끝난 뒤의 셀은 다음 행을 시작하고, 행 그룹의 시작이나 끝(thead, tbody, tfoot)은 열려 있는 행을 끝냅니다. 캡션(그 안의 제목이나 목록 포함)과 어느 셀에도 속하지 않는 텍스트(행 사이)는 브라우저가 표와 따로 보여 주듯이 표 앞에 순서대로 문단으로 놓입니다. 캡션 안의 표는 그곳의 제목이나 목록처럼 캡션의 텍스트로 읽습니다.

셀은 HTML이 배치하는 방식대로 열에 놓입니다. 스팬(colspan, rowspan)은 HTML이 음이 아닌 정수를 읽는 방식으로 읽으며, rowspan으로 아래로 이어지는 셀은 행 그룹이 끝날 때까지 아래 행에서 빈 셀로서 자기 열을 차지합니다. 빈 셀과 여러 열에 걸친 셀로만 채워진 열은 간격용 열이므로 제외되지만, 텍스트가 있는 셀이 그 열로 이어져 내려오면 제외되지 않습니다. 배치는 각 행의 셀과 그 행으로 이어져 내려온 셀을 셉니다. 그 수가 백만을 넘는 표도 모든 셀을 유지합니다. 열이 하나만 남은 표에는 격자가 없습니다. 그 행들은 attrs.table 없이 문단 하나가 되며, 표로 감싼 페이지(이메일)도 이렇게 됩니다.

셀에 제목, 목록, pre, 표, 두 번째 문단이 들어 있는 표는 대신 페이지를 배치하는 표입니다(이메일, 표의 셀로 구성된 페이지). 그 셀, 캡션, 어느 셀에도 속하지 않는 텍스트는 담고 있는 블록으로 순서대로 읽히며, 그 안의 표는 표로 읽힙니다. 어느 셀에도 속하지 않는 제목, 목록, 목록 항목, 정의, pre, 표는 </table>이 생략되었든 아니든 표를 끝내고, 그 뒤의 행은 문단으로 읽히므로 열린 채 남은 표가 페이지의 나머지를 삼키지 않습니다. 표가 들어 있는 요소의 끝은 표의 끝이 아닙니다. HTML은 표를 독립된 스코프로 취급하므로, 셀에 속하지 않고 뒤따르는 것은 브라우저가 보여 주듯이 표 앞에 표시되며, 열린 채 남은 캡션이 그것을 담습니다. 셀에 속하지 않는 각 문단이나 컨테이너의 텍스트는 각각 별개입니다.

SQL 문장. 문장은 방언의 토큰을 기준으로 나뉘므로 문자열이나 주석 안의 ;는 문장을 끝내지 않습니다. 클라이언트 고유의 명령 줄(GO, 단독 /, DELIMITER ;;, 백슬래시 명령)은 SQL이 아닙니다. 이를 포함한 스크립트도 ; 토큰 기준으로 똑같이 나뉘며, 명령 줄이 이어 붙인 문장은 커버리지가 실패로 기록하는 UNKNOWN 블록이 됩니다. 클라이언트가 통째로 보내는 본문(프로시저의 BEGIN … END)은 내부의 ;에서 잘립니다. 머리부는 CREATE와 그 이름을 유지하고, 본문의 각 문장은 자체 읽기·쓰기를 가진 독립된 블록이 되며, 닫는 조각(END)은 UNKNOWN입니다. BEGIN … END가 없는 T-SQL 본문은 완결된 것으로 읽힐 수 있습니다. 클라이언트 고유의 규칙에 따른 분할은 하지 않으므로 방언을 선언하고, 그런 스크립트는 sql_structure 손실이 보고될 것으로 예상하십시오. 블록은 종류(CREATE MATERIALIZED VIEW는 CREATE VIEW와 구분), 생성된 객체, 쓰이는 객체(뷰의 TO 테이블, 인덱스가 만들어지는 테이블, DROP이나 TRUNCATE가 제거하는 대상, MERGE 대상), 읽는 테이블(CTE는 해당하지 않음), 열, 주석(줄의 ; 뒤에 오는 주석은 그 문장에 속함)을 담습니다. 커버리지는 주석만 있는 블록이 아니라 문장을 세며, 실패한 문장은 블록 id로 알려 줍니다.

SQL 방언. 선언된 방언은 이름만으로 그대로 사용되며, 알 수 없는 방언이나 쉼표 뒤에 sqlglot 설정이 붙은 방언은 invalid_option입니다. 선언이 없으면 모든 후보 방언이 스크립트의 한 윈도우를 읽습니다. 스크립트가 50,000자 이하이면 전체를, 그보다 길면 처음 50,000자 안의 50번째 ;까지의 앞부분을 읽으며, 토크나이저가 거부하면 더 짧은 앞부분을 씁니다(잘린 위치가 따옴표로 묶인 본문 안에 놓일 수 있음). 더 긴 윈도우를 토큰화하는 방언이 먼저 순위에 오르므로, 스크립트를 거부하는 방언이 더 짧게 잘라 읽어서 이길 수는 없습니다. 그다음 처음 50개 문장의 텍스트 중 구문 트리로 바뀐 비율이 큰 방언이 이기며(비율이므로 따옴표로 묶인 본문을 작은 문장 여러 개로 쪼개는 방언은 이기지 못합니다), 동점이면 고정된 순서(ClickHouse가 첫째)의 첫 방언이 이깁니다. 무엇이든 파싱하는 방언들 사이의 동점은 동점 후보와 함께 sql_dialect_ambiguous로 보고되며, 스크립트는 그중 토크나이저가 전체를 읽는 첫 방언으로 분할됩니다. 스크립트의 가장 많은 부분을 읽은 방언 가운데 아무것도 파싱하지 못하면 그중 첫 방언을 dialect_source = "default"로 쓰고 후보는 없습니다. 감지는 윈도우당 최대 50,000자, 방언당 최대 약 일곱 개의 윈도우만 읽으므로, 첫 문장이 더 길거나 첫 따옴표 본문이 모든 절단 지점을 넘어서는 스크립트는 잘못 감지될 수 있으니 방언을 선언하십시오. 선택된 방언이 구문 트리로 만들지 못하는 문장은 종류가 UNKNOWN인 검색 가능한 블록으로 남고, coverage.failed에 나열되며 coverage.lost = ["sql_structure"]를 설정합니다. 토크나이저가 나누지 못하는 스크립트는 그런 블록 하나가 됩니다.

TOML. 유효성, 타입, 값은 tomllib가 결정하고, 옆의 스캐너는 줄, 주석, 원래의 값 텍스트(여러 줄에 걸친 값, 즉 여러 줄 문자열, 배열, 인라인 테이블 포함)를 찾습니다. 키 블록의 텍스트는 <full path> = <value text>에 주석을 더한 형태로, 단독으로 읽히도록 작성되며 줄 범위는 원본을 가리킵니다. 테이블이나 키 위의 주석은 그 텍스트와 줄 범위에 들어가고, 뒤따르는 테이블이나 키가 없는 주석 묶음은 별도의 문단이며, 여러 줄 배열 안의 주석은 그 키의 텍스트에 남습니다. 유효하지 않은 파일(부호 있는 64비트를 벗어난 정수가 있는 경우 포함)은 문단 블록으로 유지되며 coverage.lost = ["toml_types"]와 이유가 붙고, 가능하면 이유에 줄이나 키 경로가 명시됩니다. 키의 attrs.value는 JSON 값이지만, 날짜나 시간은 ISO 텍스트이고 무한대나 NaN 부동소수점은 value_type에 관계없이 그 텍스트(inf, nan)입니다.

PDF. 페이지는 배치된 모습대로 읽으며, pypdf가 보고하는 각 텍스트 런의 위치와 그려진 선을 사용합니다(extractor/loom_extractor/pdflayout.py). 런의 너비는 글꼴의 너비(/Widths, 또는 CID 글꼴의 /W를 ToUnicode 맵으로 연결한 것, 또는 표준 글꼴의 메트릭)에서 얻으며 텍스트 상태의 문자 간격, 단어 간격, 가로 비율은 반영하지 않습니다. 한 텍스트 연산자의 조각(다른 글꼴의 합자처럼 글꼴이 바뀌는 곳에서 잘림)은 앞 조각의 끝에서 이어집니다. 같은 기준선의 런은 한 줄이 되며 글꼴 크기보다 넓은 간격에서 세그먼트로 잘립니다. 기하학적으로 붙어 있는 두 런은, 합쳐서 만들어질 단어가 페이지의 텍스트 레이어에 없고 두 부분이 각각 있을 때 분리됩니다. 같은 자리에 두 번 그려진 런(가짜 굵게, 그림자)은 한 번만 읽습니다. 페이지는 대부분의 텍스트 런이 진행하는 방향이 왼쪽에서 오른쪽이 되도록 회전하므로, 옆으로 표시되는 페이지(/Rotate, 또는 회전되어 그려진 콘텐츠)도 다른 페이지처럼 읽힙니다. 다른 방향의 텍스트는 별도의 줄로 유지되어 페이지 본문 뒤에 문단 하나씩으로 붙습니다(attrs.orientation). 그다음 순서대로 다음을 적용합니다.

  • 페이지 가운데에 줄의 20분의 1 이하만 가로지르는 거터가 있고 양쪽에 열을 채우는 텍스트가 있으면 페이지를 두 열로 나누어, 전체 너비 줄 사이에서 왼쪽, 오른쪽 순으로 읽습니다.
  • 만나는 가로선과 세로선의 격자(획으로 그린 선이나 얇게 채운 상자, 폼 XObject 포함)는 괘선이 있는 표이며, 셀은 각 상자 안의 텍스트이고 빈 행과 열은 제외됩니다. 텍스트를 둘러싼 상자 하나는 표가 아닙니다.
  • 페이지의 두 개 이상 밴드에 놓인 세그먼트로 잘린 줄의 연속은 괘선 없는 표입니다. 첫 밴드에 텍스트가 있는 줄은 행을 열고, 없는 줄은 위 행의 셀에 이어 붙습니다(줄바꿈된 셀). 항목 텍스트와 떨어져 놓인 목록 표시(•, 1., 심볼 글꼴의 글머리 기호)는 열이 아닙니다.
  • 페이지 장식 요소란 표에 행으로 속하지 않는 줄 중 페이지의 위나 아래 10분의 1에 있고, 글자를 포함하며, 숫자를 제외한 텍스트가 최소 두 페이지와 전체의 5분의 2 이상에서 반복되는 것, 또는 페이지 번호만 있는 줄이며 블록에서 제외됩니다(괘선 없는 표의 양 끝에 있는 후보는, 페이지 번호만 있는 경우가 아니라면, 각 페이지 위에서 반복되는 표 자체의 헤더처럼 모든 열을 채울 때, 또는 표의 행 간격의 1.5배 안에서 행을 열거나 맨 위에서 첫 열을 제외한 모든 열을 채울 때(행 이름 열 위의 헤더)에만 그 표의 행입니다. 따라서 위의 러닝 헤더, 아래의 페이지 번호, 두 열에 걸친 셀이 있는 반복 헤더는 해당하지 않습니다). 아티팩트는 각 종류를 첫 텍스트와 그것이 나타나는 페이지 수와 함께 기록하고(페이지 번호가 바뀌는 푸터는 한 항목, attrs.furniture, 처음 200종류) 그렇게 했다는 경고를 남깁니다.
  • 나머지는 문단(한 스타일의 줄들로, 해당 크기에서 문서에서 가장 흔한 줄 간격을 30% 넘게 초과하는 간격에서 나뉨), 목록 항목(표시가 먼저 오는 것), 코드(고정폭 글꼴, 들여쓰기 유지), 제목입니다. 제목은 최대 세 줄 스무 단어의 문단(목록 항목으로 읽히는 번호 매김 문단은 한 줄)으로, 본문 텍스트(가장 많은 문자가 쓰는 크기)보다 최소 12% 크게 설정되었거나 그 크기의 95% 이상에서 굵고, 번호가 매겨지지 않았다면 문장처럼 끝나지 않는 것입니다. 더 큰 크기가 더 높은 순위이며, 같은 스타일 안에서는 번호 매김(2.1)이 수준을 정합니다.

PDF에 개요(북마크)가 있으면 그 항목이 대신 제목이 됩니다. 각 항목은 개요 순서대로, 앞 제목 다음의 줄 중 그 제목을 담은 첫 줄(또는 텍스트가 그 제목인 문단)을 취하고 그 문단은 그 둘레에서 나뉘며, 그런 줄이 없으면 앞 제목 바로 뒤에 놓입니다. 개요에 있는 모든 항목보다 크게 설정된 제목(개요에서 빠진 문서 제목)은 그 위에 남고, 개요의 수준은 모든 페이지에서 그 아래에 놓입니다. 다음 페이지 맨 위에서 같은 열로 행이 이어지는 표는 이어지는 페이지 수만큼 하나의 표이며, 다음 페이지에서 반복되는 헤더 행은 제외됩니다.

표는 표 형식 소스의 표와 같습니다(아래 표). tables의 타입이 지정된 표이며 첫 행이 헤더이고 위치는 페이지와 행(헤더는 1행)이고, 행은 담고 있는 페이지와 행으로 인용되는 column: value 줄의 블록이므로, 검색 결과는 그 행을 인용하고 데이터셋은 그 값을 담습니다. 셀은 값이 페이지에 보이는 그대로 다시 읽힐 때만 CSV 필드처럼 타입이 지정되므로 1.50과 버전 1.10은 텍스트로 남습니다. 배치된 읽기 결과가 텍스트 레이어의 글자와 숫자(간격과 대소문자를 제외하고 센 것)의 99.8% 미만을 담거나, 5,000줄을 넘거나, 배치를 읽을 수 없는 경우에는 페이지를 텍스트 레이어로 읽습니다(텍스트는 빈 줄에서 나뉘고, 개요의 제목은 그 제목을 담은 줄에서 나뉨). 이때 해당 페이지와 이유를 알리는 경고가 붙으므로, 레이아웃을 잘못 읽어도 텍스트가 사라지지 않습니다. 텍스트는 없고 이미지를 그리는 페이지(이미지 객체, 또는 폼 안의 것)는 추출기에 OCR(아래)이 있으면 OCR로 읽고, 없으면 실패한 단위입니다. 그 텍스트에는 OCR이 필요하므로 그런 페이지가 있는 PDF는 완전하지 않으며 allow_partial로만 게시됩니다. 인라인으로 그려진 이미지(페이지 콘텐츠나 폼 안)는 읽지 않으며, 그런 페이지는 그 사실을 알리는 실패한 단위입니다(텍스트가 있는 페이지에서 인라인 그림이 그 5분의 1을 덮고 자체 텍스트가 그것을 채우지 않으면 부분적이고, 텍스트가 없는 페이지에서 인라인 이미지가 OCR이 읽는 그림 옆에 있으면 부분적입니다. 너비 1포인트 미만의 인라인 이미지는 없는 것으로 봅니다). 텍스트가 있는 페이지에서 그리기나 레이아웃을 읽을 수 없거나, 파일에 없는 이미지 객체를 지명하거나, 다른 폼 네 개 안에 중첩된(리더가 따라가는 깊이보다 깊은) 폼을 그리는 경우, 그림을 그릴 수 있다면 부분적이며, 같은 상태의 텍스트 없는 페이지는 파일이 아니라 그 페이지만 실패한 단위입니다. 페이지의 리소스에 있지만 그려지지 않는 이미지는 없는 것으로 봅니다. 텍스트가 있고 페이지의 5분의 1 이상을 덮는 그림(스크린샷, 화이트보드 사진)을 그리는 페이지는 그 그림을 OCR로 읽어 각 줄을 페이지 텍스트 뒤에 별도의 문단 블록으로 두며(attrs.ocr) 표나 제목은 되지 않습니다. OCR이 없으면 완전하지 않으며, 페이지는 읽히고 실패한 단위가 그림의 텍스트에는 OCR이 필요하다고 알립니다. 페이지 자체의 텍스트가 이미 10분의 1을 채우는 그림(이미지 위에 그려진 스캔의 텍스트 레이어)은 다시 읽지 않습니다. 텍스트가 있고 OCR이 건너뛰는 더 작은 그림(너비나 높이 1포인트 미만이거나 페이지 자체 텍스트가 채우는 것은 없는 것)을 그리는 페이지는 텍스트만 읽히고 attrs.images_unread(그 페이지 번호)와 파일 전체에 대한 경고 하나로 알려집니다. 이 값은 읽지 않은 그림, 페이지, 슬라이드의 수가 아니라 해당 페이지를 페이지 번호로 식별합니다. 이런 이미지 안에만 그려진 텍스트는 추출되지 않습니다. 그림 때문에 부분적인 페이지는 대신 멈춘 원인을 알리는 이유로 지명되며, 가진 그림 전체를 나열하지는 않습니다. pypdf가 읽을 수 없는 페이지는 파일이 아니라 그 페이지만 실패한 단위이며, 실패한 페이지의 개요 제목도 섹션을 엽니다. 글꼴의 맵이 유니코드 문자를 주지 않는 문자(단독 서로게이트)는 U+FFFD로 읽히고 해당 페이지를 알리는 경고가 붙습니다. 비밀번호가 있어야만 열리는 PDF는 unsupported_format입니다.

OCR. 추출기 이미지는 Tesseract와 Leptonica의 라이브러리와 Tesseract의 영어 모델을 설치합니다(LOOM_EXTRACTOR_OCR_LANGUAGES는 이미지에 들어 있는 다른 언어를 지정하며, 하나라도 없으면 서비스가 시작을 거부하고, 라이브러리가 설치되어 있지 않으면 한 번 알립니다). 추출 자식 프로세스는 프로그램을 시작할 수 없으므로 ctypes를 통해 자신의 프로세스에서 이를 로드하며(extractor/loom_extractor/ocr.py), OpenMP는 스레드 하나로 제한하고 첫 그림을 읽을 때 로드합니다. OCR=off로 빌드하거나 LOOM_EXTRACTOR_OCR=off를 설정하면 이미지를 읽지 않으며, 그때 무엇이 완전하지 않은지는 위의 규칙이 설명합니다. PDF 이미지는 담고 있는 파일 그대로(JPEG, JPEG 2000, CCITT 팩스이며 pypdf가 TIFF로 감쌈) 또는 원시 샘플(회색조, RGB, 검정으로 표현된 CMYK, 또는 회색조나 RGB의 인덱스, 1비트나 8비트)을 PNM으로 읽습니다. 별도 프로그램만 디코딩할 수 있는 JBIG2는 읽지 않으며 그렇게 알립니다. 이미지는 디코딩되었든 스케일되었든 최대 40 M 픽셀이며, 크기는 디코딩 전에 자체 헤더에서 읽습니다(GIF는 화면과 모든 프레임을 위해 블록을 따라가 읽으며, 각 프레임은 자체 크기로 디코딩되기 때문). 너비 1포인트 미만으로 표시되는 PDF 이미지(스페이서, 추적 픽셀)는 텍스트가 없으므로 읽지 않으며, 인치당 200픽셀 미만으로 표시되는 이미지는 먼저 약 300으로 스케일됩니다. 이미지는 회색조로 읽고 Tesseract가 자체 임계값을 정하며, 대부분 어두운 이미지(어두운 화면의 밝은 텍스트)는 밝게 반전하여 읽습니다. 단어를 읽기 전에 가로 0.5인치 또는 세로 3분의 1인치보다 긴 획(괘선 표의 격자이며, 인치당 600픽셀 기준 가로 최대 300픽셀, 세로 210픽셀이라, 그보다 큰 글자(인치당 300픽셀에서 약 36포인트, 1,200에서 18포인트)는 그 획과 함께 세로 줄기를 잃고, 인치의 10분의 1보다 두꺼운 어두운 영역(제목의 배경 등)은 획이 아니며, 그 영역과 같은 두께 이내로 붙은 획(어두운 헤더 행에 닿은 괘선)이나 그 안에 있는 밝은 글자 사이의 틈도 획이 아님)은 이미지에서 지워지며(크기는 인치당 최대 600픽셀 기준이므로 고해상도로 표시된 스크린샷은 자체 크기로 읽고 정리 비용도 낮게 유지됨) 괘선 있는 표의 규칙선이 됩니다. Tesseract는 괘선 있는 표의 셀을 그림으로 읽기 때문입니다. 그런 규칙선 옆의 단어는 가장자리에 남은 획을 잃고([Owner, rota-8|), 세로 막대만으로 된 단어는 버려지며(찾지 못한 너무 옅은 격자선), 그 밖의 단어는 있는 그대로 읽힙니다(timeout = 30, __init__). 각 단어는 이미지가 그려진 페이지에 놓이며, 포인트 크기는 Tesseract가 줄의 x-높이에서 읽은 값입니다. 이 값은 Tesseract가 읽는 인치당 300픽셀 기준으로 주어지며 이미지가 표시되는 크기로 환산됩니다(제목은 여기서 얻어지며, OCR이 정수 포인트를 읽으므로 12%가 아닌 8% 단위이고, 고해상도 이미지에서 OCR 크기가 변환되는 6포인트 미만의 크기는 반 포인트가 아니라 10분의 1포인트 단위로 비교함). 그래서 위의 레이아웃 읽기가 스캔 페이지의 문단, 제목, 표를 만들고 그 블록에는 attrs.ocr가 표시됩니다. 한 파일은 최대 LOOM_EXTRACTOR_OCR_MAX_IMAGES개(30)의 이미지를 읽으며, 각 이미지는 여러 페이지나 슬라이드에 나타나도 한 번만 읽고, OCR로 읽는 그림 중 한 페이지에서는 최대 50개, 이미지 한 장의 인식은 최대 20초입니다. 이 중 하나라도 넘는 이미지가 있거나, 그리기가 너무 커서 모든 그림을 수집할 수 없거나, OCR이 읽을 수 없는 페이지는 이유와 함께 부분적이며(자체 텍스트가 없으면 실패한 단위), 아티팩트는 OCR로 읽은 페이지를 나열하고(attrs.ocr_pages, 슬라이드 덱은 attrs.ocr_slides), parser_version은 OCR로 읽은 경우 Tesseract의 버전을 명시합니다. OCR 엔진은 이미지에 약 44 MB(압축 시 12.5 MB)를 더합니다. OCR은 이미지가 텍스트로 보여 주는 것을 읽으며 차트나 다이어그램의 구조는 읽지 않습니다.

DOCX와 PPTX. 둘 다 XML 파트의 zip이며 표준 라이브러리로 읽으므로, 악의적인 파일에 대해 서드파티 XML이나 이미지 라이브러리가 실행되지 않습니다. 파트는 저장(stored)되었거나 deflate 압축(OOXML이 쓰는 방식)이어야 하고 압축 해제 시 최대 256 MiB여야 하며, 패키지의 파트는 합쳐서 최대 512 MiB입니다. 파트는 선언된 크기까지만 압축 해제하므로 zip 폭탄은 거기서 멈춥니다. DOCTYPE을 선언한 파트(어떤 인코딩이든)는 거부되어 엔티티가 확장되지 않습니다. 읽을 수 없는 파트(손상, 한도 초과, XML이 아님, XML 파서가 읽지 못하는 인코딩)는 그 파트가 속한 단위(슬라이드, 슬라이드의 노트, 스타일, 각주)를 실패시키며, 문서 파트 자체가 읽히지 않으면 파일이 corrupt로 실패합니다. DOCX 제목은 Heading N 또는 Title 스타일의 문단이거나, 자체 개요 수준을 가졌거나 스타일의 basedOn 체인을 따라 개요 수준을 가진 문단이며, 가장 가까운 설정이 결정합니다(수준 9는 본문이며 스타일에 관계없이 제목이 아님). Title 문단이 제목으로 읽힌 뒤에는 그것이 깊이 1(개요 수준과 무관)이고 그 뒤의 다른 모든 제목은 자기 수준보다 한 단계 아래(Heading 1은 깊이 2)가 되므로 섹션이 제목 아래에 놓이며, 이후의 제목은 다시 깊이 1입니다. 번호가 매겨진 문단이나 List 스타일은 목록 항목이고, 그 연속은 목록 블록 하나입니다. 삽입된 텍스트는 읽고, 추적된 삭제(그 런, 행, 셀)와 이동된 텍스트의 원래 위치는 읽지 않습니다. 콘텐츠 컨트롤이나 사용자 지정 XML 요소의 텍스트는 본문, 표의 행과 셀에서 제자리에서 읽고, 대체 콘텐츠 선택지는 한 번만 읽습니다. 머리글, 바닥글, 주석은 본문이 아니므로 읽지 않으며, 각주와 미주는 본문 뒤에 이어집니다(attrs.note). 포함된 문서(altChunk)는 실패한 단위이며, 그림, 차트, 다이어그램, 포함된 객체로만 이루어지고 텍스트가 없는 문서도 같습니다. 텍스트 문서가 본문, 표, 노트에서 그림이 보여 주지만 리더가 읽지 않는 것을 담고 있으면 경고합니다. 대상은 이미지(그림, 그룹, 도형 채우기 안의 것, VML 도형의 그림 채우기, 또는 대체 콘텐츠의 폴백이며, 3D 모델처럼 리더가 모르는 그림은 폴백 그림을 유지하고 거기 그려진 텍스트는 선택지의 것으로 읽음), 그려진 텍스트(WordArt, 잠긴 캔버스의 것), 차트, 다이어그램, 포함된 객체이며, 페이지 배경은 읽지도 알리지도 않습니다. 추적된 삭제는 제외되고, 텍스트 상자(그 텍스트는 읽음), 선, 일반 도형은 경고하지 않습니다. PPTX 슬라이드 덱은 슬라이드 순서대로 읽으며(프레젠테이션의 슬라이드 목록이 기준이고 파트 이름은 아님), 슬라이드의 제목은 그 슬라이드의 다른 블록이 속하는 제목이고, 각 텍스트 도형(그룹화된 것은 제자리에서, 대체 콘텐츠의 도형은 첫 선택지를 통해)은 블록이며, 발표자 노트는 attrs.notes가 표시된 블록입니다. 숨겨진 슬라이드(show가 false)는 읽히고 attrs.hidden이 표시됩니다. 슬라이드의 5분의 1 이상을 덮는 그림은 OCR로 읽어 슬라이드 도형 뒤에 attrs.ocr가 표시된 문단 블록으로 두며(여러 슬라이드가 보여 주는 이미지는 한 번만 읽고, 그림은 패키지 파트와 별도의 자체 한도 안에서 압축 해제됨), OCR이 없거나 파일에 들어 있지 않고 링크된 그림이면 그 슬라이드는 이유를 알리는 실패한 단위입니다. 그림의 크기는 자체 크기에 자신이 속한 각 그룹의 배율을 곱한 것이며, 그것이 없으면 슬라이드 레이아웃의 자리표시자(인덱스, 그다음 타입 순)의 크기, 그다음 마스터의 크기를 따릅니다. 어디에도 명시되지 않으면 슬라이드의 크기를 쓰며, 슬라이드 크기를 지명하지 않는 덱은 기본값 10 × 7.5인치입니다. 텍스트 없이 그림, 차트, 다이어그램, 포함된 객체가 보여 주는 내용 전부를 전달하는 슬라이드는, OCR이 그림을 읽은 경우가 아니면 실패한 단위입니다. OCR이 읽은 텍스트만 있는 슬라이드도 차트, 다이어그램, 포함된 객체를 담고 있으면 실패한 단위입니다. 관계가 슬라이드 파트를 지명하지 않는 슬라이드 id, 리더가 따라가는 깊이보다 깊게 중첩된 슬라이드, 관계를 읽을 수 없는 슬라이드, 그림이 읽을 수 없는 레이아웃이나 마스터의 자리표시자에서 크기를 가져오는 슬라이드도 마찬가지입니다(그 텍스트는 여전히 읽힘). OCR이 읽지 않는 그림(슬라이드의 5분의 1 미만, 그림으로 채운 도형, 그룹, 표 셀, 슬라이드 자체의 배경 그림, 또는 잉크처럼 리더가 모르는 그림이나 수식의 폴백 그림이며 수식의 수학은 읽지 않음, 레이아웃, 마스터, 테마가 주는 배경은 읽지 않음), 차트, 다이어그램, 포함된 객체가 있는 텍스트 슬라이드는 텍스트만 읽히고 attrs.images_unread(그 슬라이드 번호)와 파일 전체에 대한 경고 하나로 알려지지만, 슬라이드가 보여 주는 것 때문에 실패한 경우는 예외이며 그때의 실패는 가진 것 전부가 아니라 멈춘 원인을 알립니다. 이 값은 읽지 않은 그림, 페이지, 슬라이드의 수가 아니라 해당 슬라이드를 슬라이드 번호로 식별합니다. 두 형식 모두 표는 블록 하나이며 행마다 한 줄이고 셀은 파이프로 이어지며 attrs.table에 rows와 columns가 들어갑니다.

표(CSV, XLSX, Parquet). 표 형식 소스는 아티팩트의 tables입니다. 각 표는 헤더(값이 있는 첫 행, XLSX는 아래에 설명하듯 두 행일 수 있음, Parquet 파일은 스키마), 담고 있는 모든 값으로 타입이 정해지는 열(string, number, bool, date, datetime, time, duration, 또는 mixed이며 빈 셀과 오류는 세지 않고, 날짜와 날짜-시간으로 된 열은 datetime), 값의 행으로 이루어집니다. 같은 행들은 20행 단위 블록이자 최대 1,000자이며(더 긴 행은 청크의 기본값 1,500자 아래에서 단독 블록이 되므로 청크는 담고 있는 행을 인용함), 각 행은 column: value 쌍의 한 줄이고 시트와 행으로 인용되므로 어휘 검색과 벡터 검색 경로가 다른 문단처럼 검색합니다. 아래에 텍스트가 있는 행이 없는 헤더(행이 없거나 Parquet 파일의 모든 값이 제외된 경우)는 열 이름이 있으면 별도의 블록이 되며, 블록은 텍스트가 있는 행에서 시작하고 끝납니다. 열의 이름은 헤더 셀의 최대 500자이며(그보다 짧게 잘린 것은 실패한 단위, <table> header), 부동소수점 값의 행 텍스트는 시트가 보여 주는 대로 유효숫자 15자리까지이고(0.1+0.2는 0.3으로 읽힘) 표는 정확한 값을 유지합니다. CSV와 XLSX에서 JSON 숫자가 아닌 숫자(부호 있는 64비트를 넘는 정수, 무한대, NaN)는 부동소수점이나 텍스트로 읽고, 다른 규칙이 읽지 못하는 값(5,000자리의 스타일 인덱스, 9999년을 넘어 반올림되는 날짜)은 숫자나 텍스트로 읽히며 파일을 실패시키지 않습니다. Parquet은 각각을 열의 타입(아래)에 따라 읽습니다.

CSV. .tsv 이름이면 구분자는 탭이며 따옴표 처리는 없습니다. 그렇지 않으면 쉼표, 세미콜론, 탭, 파이프 중 하나이며(그런 이름 없이 보낸 탭 구분 파일은 스니핑하므로 CSV처럼 따옴표를 읽음), 파일의 처음 4 KiB의 완전한 줄에 있는 따옴표 필드로 추정하고, 없으면 처음 64 KiB의 완전한 줄에서 구분자 수로 추정합니다(각 표본은 첫 줄이 표본을 넘는 경우에만 줄 중간에서 잘림). 필드는 스니퍼가 추정한 것에 관계없이 "로 인용되고 따옴표는 두 번 쓰며, 값은 일반 숫자, ISO 날짜, ISO 날짜와 시간(시간대 유지)으로 쓰인 경우가 아니면 텍스트입니다. 행은 비어 있지 않은 필드만 담습니다. 1메가바이트가 넘는 필드, 8 MiB가 넘는 레코드, 리더가 닫을 수 없는 따옴표는 그 지점부터의 행을 실패시킵니다.

XLSX. 워크북, 스타일, 공유 문자열, 워크시트는 압축 해제되는 대로 읽으며 트리로 보관하지 않습니다. 워크북의 관계는 최대 4 MiB의 파트에서 전체를 읽으며(그것을 넘거나 XML이 아니면 파일은 corrupt로 거부됨, 관계 없이는 시트를 찾을 수 없기 때문), 공유 문자열과 스타일을 지명합니다. 워크북에 없는 공유 문자열을 지명하는 셀은 빈 값으로 읽히고 아티팩트는 shared_strings를 잃습니다. 시트 이름은 최대 500자이며(그보다 짧게 잘린 것은 실패한 단위, sheet names), 워크시트는 워크북의 순서대로 읽습니다(차트 시트나 대화 상자 시트에는 셀이 없고, 매크로 시트나 다른 종류의 시트는 읽지 않으며 단독으로 실패함). 각각은 표 하나이고, Strict Open XML 워크북은 unsupported_format으로 거부되며, 관계가 파트를 지명하지 않는 시트는 단독으로 실패합니다. 셀은 워크북이 담은 대로 읽습니다. 공유 문자열이나 인라인 문자열(발음 표기는 제외하고, 공백만 있는 것은 CSV 필드처럼 비어 있음), 숫자, 불리언, 오류({"error": "#DIV/0!"}), 또는 숫자 서식이 날짜일 때의 날짜(내장 서식 14-17과 22, 동아시아 Excel의 27-31, 36, 50-58, 또는 날짜 문자가 있고 Excel 자체의 한도인 255자 이하의 사용자 지정 코드)이며, 1900 체계(Excel의 1900-02-29는 텍스트로 읽음) 또는 1904 체계에서 가장 가까운 초로 읽습니다. 시각 서식은 time으로, [h]:mm 같은 경과 시간 서식은 duration으로 읽습니다. 수식은 캐시된 값으로 읽으며, 캐시가 없으면 빈 값으로 읽고 아티팩트는 formula_values를 잃습니다. 인라인이든 공유든 1메가바이트가 넘는 값과 16,384열을 넘는 값은 제외되고 집계되며, 같은 위치에 두 번 쓰인 셀도 마찬가지입니다(앞의 값은 사라짐). 병합된 범위의 첫 값은 그 모든 셀을 채우므로, 여러 열에 병합된 헤더는 각 열의 이름을 정합니다. 두 행에 걸친 헤더, 즉 첫 행의 열 병합 범위가 둘째 행의 텍스트 셀을 묶는 경우(2025 아래의 H1과 H2)에는 두 행에서 각 열의 이름을 정하고(2025 / H1, 위에 아무것도 없으면 둘째 행의 이름), header_rows는 2이며, 둘째 헤더 행은 표가 담는 행 수에 포함됩니다. 그 둘째 행에서 첫 행으로부터 아래로 병합되지 않은 다른 셀은 텍스트든 아니든 둘째 행을 데이터로 만듭니다. 셀 예산 때문에 펼쳐지지 않은 범위는 아무것도 묶지 않으며, 범위 아래의 숫자나 날짜(숫자로 쓴 2024 | 2025)도 데이터로 읽힙니다. 첫 행 전체에 병합된 제목도 이 규칙에 해당하며 모든 이름의 앞에 붙습니다(Sales 2025 / Region). 채우는 모든 열을 덮는 병합 아래에 있는 모두 텍스트인 첫 데이터 행(Alice | Smith 위의 Name)도 마찬가지입니다. 그룹 아래의 이름과 구별할 방법이 없으므로 둘째 헤더 행으로 읽히며, 시트가 바뀔 때까지 열은 그 이름을 유지합니다. 병합은 담긴 마지막 행 너머의 행을 채우지 않으며, 표가 담는 행 너머로 행을 더하려는 병합은 거기서 멈추고 실패한 단위가 됩니다. 위치를 지명하지 않는 행이나 셀은 앞의 것 다음 위치를 취합니다. 숨겨진 시트는 읽히고 attrs.hidden이 표시되며, 손상된 시트나 루트가 워크시트가 아닌 시트(다른 네임스페이스)는 단독으로 실패합니다. 끝까지 읽을 수 없는 공유 문자열이나 스타일은 읽은 데까지 유지되고, 아티팩트는 shared_strings 또는 number_formats를 잃습니다.

Parquet. pyarrow는 파일 시스템, 스레드 없이 시스템 메모리 풀로 메모리의 바이트에서 파일을 읽습니다. 열은 스키마에서(처음 16,384개이며 이름이 반복될 수 있으므로 위치로 유지하고 나머지는 실패한 단위, <name> columns) 가져오고, 행은 행 그룹 단위로 최대 1,024행의 배치로, 셀 예산이 허용하는 값의 수를 넘지 않게 읽으며 리프 열 기준으로 셉니다(구조체의 필드는 각각 하나). 이름은 파일의 행이 아니므로 표에는 헤더 행이 없고(header_rows 0) 행은 1부터 셉니다. 열을 읽는 방식은 타입으로 한 번 결정되므로 열의 모든 배치가 같게 읽힙니다. 정수는 숫자이며 소수와 부호 있는 64비트를 넘는 정수(uint64)도 그렇고, 각각 정확한 자릿수로 쓰입니다. JSON 숫자는 double로 다시 읽히기 때문입니다(아티팩트와 그 문단은 모든 자릿수를 유지하며, 데이터셋의 처음 24개 숫자 또는 기간 열은 소수점 아래 아홉 자리를 담으므로 decimal(38,18)은 거기서 반올림되고 나머지는 double입니다, 데이터셋). 부동소수점은 숫자이며, 최상위 float32나 float16 열의 값은 자체 타입에서 가장 짧은 십진수이고, NaN은 값이 아니며(부동소수점 열이 누락된 숫자를 표시하는 방식) null도 마찬가지입니다. 불리언, 날짜, 타임스탬프(시간대를 유지하며 열에 없으면 없음), 시각, 기간은 다른 리더가 쓰는 대로 읽고, 나노초 단위는 마이크로초로 변환합니다(리스트, 구조체, 맵 안에서도 같으며, Arrow가 다른 요소 타입으로 변환하지 않는 리스트 뷰는 제외). 텍스트는 텍스트이고 UUID는 그 텍스트이며, 리스트, 구조체, 맵은 JSON입니다(그 안의 바이트는 base64). 다른 확장 타입은 저장하는 타입으로 읽으며 bool8은 불리언입니다. 바이트는 텍스트가 아니며, 바이트, 무한대(부동소수점 열이 숫자로 남도록), 1,048,576자를 넘는 값, Python이 담을 수 없는 값(9999년 이후의 날짜)은 제외되고 집계됩니다(<name> values이며 각 원인이 읽은 행에 대해 명시됨). Python이 담을 수 없는 값이 있는 배치는 각 부분이 변환될 때까지 절반으로 나뉘어 그 하나만 제외되며, 한 열에서(파일 전체에서) 그런 값이 16개를 넘으면 열의 나머지는 읽지 않고 제외되며 그렇게 집계됩니다. null, NaN, 빈 텍스트로만 된 행은 행이 아닙니다. 스키마에 열이 없는 파일은 빈 행만 있으며 메타데이터에서 집계되고, 행이 없는 행 그룹은 건너뜁니다. 푸터가 선언한 0 미만의 행 수는 없는 것으로 보며, 행 그룹이 선언한 행이 2^63 이상인 푸터는 corrupt로 거부됩니다. 페이지는 한 번에 하나씩 디코딩되므로 행 그룹의 크기가 보유량을 정하지 않습니다. 표 예산을 넘는 행은 읽지 않으며, 그것은 예산이 바닥난 배치 이후의 행, 그리고 400만 값, 디코딩된 256 MiB, 읽은 100,000개의 행 그룹을 넘은 행이고, 이는 배치를 Python으로 읽기 전에 부과됩니다(최소한 행마다 값 하나, 리스트, 구조체, 맵의 모든 요소를 리프까지, 딕셔너리 항목은 그것을 지명하는 값마다 한 번, 뷰의 값은 뷰마다 한 번이며, 이 둘은 Python으로 읽는 열에서이고 바이트 열은 복사되지 않음). 그래서 빈 행, 긴 리스트, 긴 값으로 된 파일도 한도가 적용되고, 그 지점 이후의 행은 별도의 실패한 단위(past what one file decodes)이며 메타데이터에서 집계되고 디코딩되지 않습니다. 페이지가 디코딩되지 않거나 푸터가 선언한 것보다 많거나 적은 행을 가진 행 그룹(행 번호와 개수는 푸터가 기준)은 그 지점부터의 행을 실패시킵니다(<name> rows N-). 자식의 한도는 디코딩 한 번을 제한하며(시간 제한을 넘으면 파일이 timeout으로 거부되고 자식이 충돌하면 resource_limit), 그 환경은 네이티브 라이브러리를 스레드 하나와, 주소 공간 제한이 허용하는 시스템 할당자로 제한합니다. pyarrow가 없는 빌드는 Parquet을 선언하지 않습니다.

한도. 하나의 예산이 아티팩트의 모든 표를 제한하며 세 부분으로 이루어집니다. 소스가 담는 것, 표가 쓰는 바이트, 표가 색인하는 텍스트입니다. 소스는 병합된 셀을 포함하여 비어 있지 않은 셀을 전체 1,000,000개까지, 그 텍스트는 문자당 4바이트로 센 256 MiB까지, 표당 100,000행까지 담습니다. 남은 셀에 비해 너무 큰 병합은 건너뛰고 셀을 나머지에 남겨 두며, 워크북은 병합된 범위를 최대 1,000,000개까지 읽습니다(병합에 걸리는 시간에 대한 한도이며, 그것을 넘으면 각각 펼쳐지지 않은 것으로 집계되고 읽지 않음). 행을 배치하는 데는 아티팩트의 JSON이 쓰는 방식으로 센 최대 40 MiB를 쓰며, 각 행의 값(null 포함), 열 이름과 이스케이프를 포함한 블록 줄, 각 블록의 필드와 시트 이름, 실패한 단위가 해당합니다. 표 블록이 담는 텍스트는 최대 12 M자이고 각 블록에 760이 추가로 부과됩니다. 블록은 최대 청크 하나로 색인되고(한 제목 아래의 블록은 더 적은 청크로 묶임) 청크보다 긴 블록은 스트라이드마다 하나로 색인되므로, 아티팩트의 표는 최대 15,800개의 청크로 색인되며 이는 소스가 기본으로 게시하는 20,000개 미만입니다. 표가 들어가지 않는 시트는 제목도 남기지 않습니다. 이 예산은 기본값을 전제로 합니다. 추출기의 64 MiB 입력 한도를 높인 배포(CSV는 크기에 비례하는 시간에 읽히며, 빈 줄 64 MiB는 34초이고 자식의 한도는 120초)에서는 큰 CSV가 CPU 시간을 소진할 수 있고, 추출기의 응답 한도를 약 41 MiB 아래로 낮추거나 서버의 청크 크기, 청크 스트라이드(760자 미만), 청크 상한을 낮춘 배포는 큰 표를 자르지 않고 거부합니다(resource_limit, too_large). 그 어느 것이든 넘는 행은 집계되는 실패한 단위가 되며, 그 셀은 값이 있는지만 확인하고 배치하지 않습니다. 바이트를 넘는 헤더는 그 표를 실패시키고, 예산(셀, 바이트, 텍스트)이 바닥나면 그 뒤의 시트는 읽지 않는 하나의 실패한 단위가 되며, 남은 셀은 절단이 일어난 시트의 병합을 여전히 펼치므로 병합된 헤더가 열 이름을 정합니다. 워크북의 파트는 DOCX와 마찬가지로 합쳐서 최대 512 MiB로 압축 해제되며(스트리밍되는 파트는 선언한 크기와 상관없이 그 합계까지 읽고 거기서 잘리며, 그 전에 읽은 행은 남음), 속성을 포함해 16 MiB를 넘는 태그, 64를 넘는 중첩 깊이, 4,096개를 넘는 고유 요소 및 속성 이름, 1,024자를 넘는 이름도 같은 방식으로 그 파트만 자르며, 전체 요소는 최대 25 M개로 읽는 시간을 제한하고, 한도에 걸린 시트는 그 전에 읽은 행을 유지합니다. 워크북은 처음 10,000개의 시트(나머지는 실패한 단위 하나)와 65,536개의 스타일 및 숫자 서식(그것을 넘으면 아티팩트가 number_formats를 잃음)까지 읽으며, 공유 문자열은 문자당 4바이트와 객체가 차지하는 크기로 센 최대 256 MiB를 담습니다(넘으면 lost: shared_strings). 100,000 × 20개 숫자의 시트(압축 해제 62 MB, zip 4 MB)는 자식의 제한 아래에서 약 9초에 추출됩니다.

계약 한도. 참조 추출기는 응답하기 전에 모든 블록을 계약의 한도에 맞춥니다. 1,024자를 넘는 키는 제외하고 처음 10,000개를 유지하며, 섹션 경로는 처음 64개 항목을 유지하고 각 항목은 500자로 자릅니다. 잘린 블록에는 표시가 붙고(attrs.keys_truncated, attrs.section_truncated), 아티팩트의 coverage.lost가 잃은 것을 명시하며(exact_keys, section_path), 블록의 텍스트와 위치는 여전히 전체를 담고 있습니다.

적격성 검증

참조 추출기는 아래 하한을 통과한 형식만 지원한다고 선언한다. 평균이 좋아도 실패한 항목이 가려지지 않도록 형식과 슬라이스마다 따로 측정한다. tests/unit/test_extraction_gates.py는 이 표를 읽어 레이블이 달린 픽스처로 참조 추출기의 점수를 매기고, 하한에 못 미치는 슬라이스가 있으면 실패 처리한다. 또한 참조 추출기의 capabilities가 이 표에 행이 없는 형식을 선언하거나 형식과 그 옵션을 넘어서는 것을 주장해도 실패한다. PDF, DOCX, PPTX는 파싱 벤치의 코퍼스(bench/docparse/corpus, 그 정답 레이블, bench/docparse/score.py)로 점수를 매기고, 나머지 형식은 테스트 안에서 만든 레이블 픽스처로 점수를 매긴다.

형식 슬라이스 지표 하한
pdf 텍스트 레이어, 모든 슬라이스 텍스트 재현율 0.97
pdf 텍스트 레이어, 모든 슬라이스 읽기 순서 0.95
pdf 텍스트 레이어, 모든 슬라이스 제목 F1 0.95
pdf 텍스트 레이어, 모든 슬라이스 제목 레벨 0.95
pdf 텍스트 레이어, 모든 슬라이스 표 셀 F1 0.95
pdf 텍스트 레이어, 모든 슬라이스 로케이터 0.90
pdf 스캔 실패 단위 1.00
pdf 모든 슬라이스 손실 공지 1.00
docx 문서 텍스트 재현율 0.98
docx 문서 제목 F1 0.98
docx 문서 제목 레벨 0.98
docx 문서 표 셀 F1 0.98
pptx 덱 텍스트 재현율 0.95
pptx 덱 제목 F1 0.98
pptx 덱 로케이터 0.90
pptx 덱 노트 1.00
pptx 덱 손실 공지 1.00
markdown 픽스처 텍스트 재현율 1.00
markdown 픽스처 텍스트 정밀도 1.00
markdown 픽스처 제목 F1 1.00
markdown 픽스처 제목 레벨 1.00
markdown 픽스처 로케이터 1.00
html 픽스처 텍스트 재현율 1.00
html 픽스처 텍스트 정밀도 1.00
html 픽스처 제목 F1 1.00
html 픽스처 제목 레벨 1.00
html 픽스처 표 행 1.00
text 픽스처 텍스트 재현율 1.00
text 픽스처 텍스트 정밀도 1.00
text 픽스처 로케이터 1.00
sql 픽스처 구문 1.00
sql 픽스처 로케이터 1.00
sql 픽스처 이름 1.00
toml 픽스처 키 경로 1.00
toml 픽스처 로케이터 1.00
csv 픽스처 타입 셀 1.00
csv 픽스처 헤더 1.00
xlsx 픽스처 타입 셀 1.00
xlsx 픽스처 헤더 1.00
parquet 픽스처 타입 셀 1.00
parquet 픽스처 헤더 1.00

지표는 다음과 같다.

  • 텍스트 재현율, 텍스트 정밀도, 읽기 순서, 제목 F1, 제목 레벨, 표 셀 F1, 로케이터는 벤치 채점기의 지표다. 각각 정답의 단어 중 파싱 결과가 담고 있는 비율, 파싱 결과의 단어 중 정답이 담고 있는 비율, 정답의 블록 중 순서가 맞는 비율, 텍스트로 대응시킨 제목에 대한 F1, 대응된 제목 중 (순위 기준으로) 레벨이 맞는 비율, 표 셀에 대한 F1, 정답의 블록 중 해당 페이지나 슬라이드로 인용된 비율이다. 덱에서는 코퍼스의 모든 슬라이드 제목이 한 레벨이므로 제목 레벨을 게이트로 두지 않는다. Markdown, HTML, text, SQL에서 로케이터는 정답 블록이나 구문 중 줄 범위가 정확히 일치하게 찾아낸 비율이고, TOML에서는 키가 속한 블록의 범위가 그 키의 줄을 포함하는 비율이다.
  • 실패 단위: 스캔 파일의 페이지 중 아티팩트가 OCR로 읽었거나(attrs.ocr_pages) 실패로 보고한 비율이다. 빈 페이지로 읽어서는 안 된다. OCR이 꺼져 있으면 모든 페이지가 실패 단위다.
  • 손실 공지: 벤치 카테고리별로, 이미지 안에 그려진 정답 텍스트 중 해당 페이지나 슬라이드를 아티팩트가 OCR로 읽었거나 coverage.failed 또는 attrs.images_unread에서 읽지 않았다고 명시한 비율이다.
  • 노트: 발표자 노트 중 해당 슬라이드의 노트로 담긴 비율이다.
  • 표 행: HTML 표의 행 중 셀 순서를 유지한 하나의 행으로 담긴 비율이다.
  • 구문, 이름, 키 경로: 각각 SQL 구문 중 온전하게 찾아낸 비율, 구문이 정의하거나 읽는 객체 중 키 사이에서 찾아낸 비율, TOML 키 경로 중 키로 찾아낸 비율이다.
  • 타입 셀과 헤더: 표의 셀 중 값과 타입을 함께 읽어낸 비율, 열 중 이름을 함께 읽어낸 비율이다. 분모는 정답의 개수와 추출 결과의 개수 중 큰 쪽이므로, 추가된 행, 열, 표는 누락으로 센다.

게이트는 OCR을 끈 상태로 실행하므로, OCR 엔진이 설치되어 있든 아니든 결과가 같다.

검증하지 않으므로 참조 추출기가 지원한다고 주장하지 않는 것은 다음과 같다. OCR이 읽는 단어(추출기 이미지에 엔진이 포함되어 있으면 스캔 페이지와 큰 그림을 읽지만, 스캔 게이트와 손실 공지 게이트는 읽은 페이지를 읽은 것으로 셀 뿐 그 텍스트를 재는 하한은 아직 없다), 더 작은 이미지 안의 텍스트, 차트와 다이어그램(attrs.images_unread와 아티팩트의 경고에 이름이 올라가며 읽지는 않는다), 그리고 타입이 있는 표로서의 Markdown 파이프 표(행은 작성된 그대로 하나의 문단으로 남는다)가 해당한다.

검색 하한선

이 하한선은 참조 추출기가 선언하는 내용이 아니라, 추출된 문서에 대한 knowledge.search의 결과를 기준으로 합니다. tests/integration/test_knowledge_retrieval_floors.py는 Markdown 런북, SQL 스키마, TOML 파일, CSV 표, HTML 표, PDF를 텍스트 쓰기와 함께 수집한 뒤, 레이블이 붙은 쿼리를 세 가지 구간으로 나누어 실행합니다. 각 쿼리의 대상은 첫 번째 결과여야 합니다(첫 결과로 찾음).

  • 정확한 식별자: 오류 코드, 테이블, 뷰, 키 경로, 양식 번호.
  • 표 질문: 여러 블록으로 나뉠 만큼 긴 CSV 표의 각 블록에 있는 행, 같은 열을 가진 다른 CSV의 행, 같은 열을 가진 두 HTML 표 각각의 행.
  • 필터 적용 재현율: 경쟁 문서를 각각 남기는 formats, block_types, tags 필터. 모든 결과가 필터 안에 있어야 합니다(필터 내 유지).

결과가 예상한 출처에서 나왔고, 그 구절 또는 구절이 속한 제목에 예상한 텍스트가 나타나면 적중으로 계산합니다(오류 코드는 흔히 해당 섹션의 제목입니다). 하한선은 통합 테스트가 실행하는 가짜 n-gram 임베더로 측정하고 검증하며, 청크와 쿼리를 같은 모델로 임베딩하므로 실행마다 순위가 달라지지 않습니다. 다른 임베더를 사용하면 테스트는 건너뜁니다. M-41 같은 코드는 어휘 검색 경로에도(구성 요소가 최소 용어 길이에 못 미침) 정확한 키 경로에도 해당하지 않으므로, 가짜 임베더에서는 섹션 제목에 대한 벡터 경로를 통해 찾습니다.

구간 지표 하한선
정확한 식별자 첫 결과로 찾음 1.00
표 질문 첫 결과로 찾음 1.00
필터 적용 재현율 첫 결과로 찾음 1.00
필터 적용 재현율 필터 내 유지 1.00

구조 기반 청크

chunk_artifact는 평탄화한 텍스트 위에 고정 크기 윈도우를 씌우는 대신 블록 단위로 청크를 자릅니다.

  • 하나의 부모 아래에 있는 연속된 블록(헤딩의 섹션, 키를 포함한 TOML 테이블)은 청크 크기까지 하나의 청크로 묶입니다.
  • SQL 문 하나는 그 자체로 하나의 청크이므로, 검색 결과 하나가 문 하나를 인용합니다.
  • 청크 크기보다 긴 블록은 윈도우로 나뉘며, 각 윈도우는 자신의 섹션을 유지하고, 문자 오프셋이 있는 블록이라면 자신만의 줄 범위와 문자 범위도 유지합니다(HTML 윈도우나 유효한 TOML 파일의 윈도우는 해당 블록의 줄을 인용합니다).
  • 헤딩 텍스트는 청크 텍스트에 반복되지 않으며, 섹션 경로가 청크와 함께 전달됩니다. 텍스트가 없고 그 아래에 하위 섹션도 없는 헤딩은 그 자체로 하나의 청크가 됩니다.

각 청크는 자신을 만든 블록의 id, 블록의 타입(서로 다르면 mixed), 블록 범위를 병합한 locator(key_path 같은 필드는 모든 블록이 일치할 때만 유지됨), 블록 키의 합집합을 가지며, 기록될 당시의 문서 리비전과 포맷도 함께 기록합니다.

수집

knowledge.ingest는 POST /v1/knowledge.upload가 저장한 원본에 대해 작업(server/knowledge/app/ingest_run.py, 워커 knowledge_ingest)을 실행합니다. 업로드는 파일 이름과 미디어 타입으로 형식을 정할 뿐 바이트를 읽지 않습니다. 작업은 원본을 읽어 위의 클라이언트를 통해 추출기에 보내고, 산출물을 검사한 뒤 그것을 별도의 원본으로 (콘텐츠 주소 방식으로) 저장합니다. 이어서 각 청크의 컨텍스트(chunk_context: 제목, 설명, 섹션 경로)와 함께 구조 기반 청크를 만들고, 임베딩합니다. 이때 이 네임스페이스가 같은 모델로 이미 임베딩한 입력은 그 벡터를 재사용합니다. 그런 다음 소스의 다음 리비전을 게시합니다. 리비전을 정하고(기대하는 리비전이 있으면 확인하고), 그 리비전으로 기록된 청크를 삽입한 뒤, 소스의 클레임 아래에서 리비전을 정한 이후 소스가 바뀌었으면 게시를 거부하고, 문서 행을 쓰고, 이전 버전의 청크를 폐기합니다. 클레임은 청크 삽입이 아니라 이 몇 개의 문장만 포함하므로, 어떤 크기의 소스에서도 시간 제한이 유지됩니다. 추출기가 거부한 소스는 해당 코드와 함께 작업을 실패시키고, 설정된 어떤 추출기도 받지 않는 형식은 format_unavailable로, 계약을 어기는 산출물은 invalid_artifact로 실패시킵니다. 추출기에 연결할 수 없거나, 시간이 초과되거나, 결과도 거부도 아닌 상태로 응답하면 작업은 점점 늘어나는 지연(최대 한 시간)과 함께 LOOM_KNOWLEDGE_INGEST_MAX_ATTEMPTS까지 다시 대기열로 돌아갑니다. 느린 단계가 모두 끝나기 전에는 아무것도 게시되지 않으므로, 실패하거나 취소된 작업은 이전 리비전이 계속 서비스되게 둡니다. 작업 행은 게시가 문서 행을 쓰기 전에 삽입하는 청크 버전을 기록합니다. 실행이 그 둘 사이에서 멈추면, 재시도, 실패 또는 다음 실행이 그 청크를 폐기합니다. 문서 행에는 그것을 쓴 작업이 기록되고(ingestion_id, 메타데이터 편집과 삭제에서도 유지됨), 재실행은 그것을 가리키는 소스의 어떤 버전 행이든 찾기 때문에 이후의 텍스트 쓰기가 그것을 가리지 않습니다. 게시 도중 멈춘 실행(게시 단계에서 여전히 processing이며 청크 버전과 함께 저장됨)은, 이후 소스에 대한 쓰기(텍스트 쓰기, 메타데이터 편집, 삭제)가 이미 반영되었는데 작업의 행을 찾을 수 없으면(병합으로 사라졌을 수 있음) 더 오래된 파일로 그 쓰기를 덮어쓸 위험을 피하기 위해 revision_conflict로 실패합니다. 재시도로 pending에 되돌려진 작업은 이렇게 판단하지 않습니다. 일시적으로 실패한 문서 삽입(자체 타임아웃, 또는 소스 클레임의 데드라인에 의한 중단)은 그래도 반영될 수 있으므로, 실행은 크래시처럼 거기서 멈추고 작업은 게시 단계의 processing 상태로 남으며 청크는 활성 상태입니다. 실행은 작업의 리스를 해제하지 않고 만료되도록 두므로, 서버 시계 기준으로 리스의 TTL이 지날 때까지, 곧 삽입 자체의 한계(전달된 전송의 시작 구간, 클레임된 문장의 서버 측 제한, 커밋 여유)를 넘길 때까지 어떤 워커도 그 작업을 가져가지 않습니다. 그때에는 삽입이 반영되었거나 중단된 상태이며, 다음 실행은 행이 반영되었으면 게시된 것으로 마무리하거나(그 뒤에 쓴 것은 유지됨: 삭제나 텍스트 쓰기), 위와 같이 추월된 것으로 실패시키거나, 청크를 폐기합니다. 게시를 마친 작업의 재실행은 다시 게시하거나 게시한 청크를 폐기하지 않고 끝납니다. 취소는 별도의 행(loom.knowledge_ingest_cancels)이며 작업의 버전이 아닙니다. 작업의 버전은 작업의 리스를 가진 워커만 씁니다. 워커는 게시 전과 작업을 가져올 때 취소를 읽고, 자체 게시가 확인된 작업은 이후에 어떤 취소가 오든 게시된 상태로 끝납니다. 한 번의 패스는 LOOM_KNOWLEDGE_INGEST_MAX_PASS_SECONDS 안에서 작업 하나를 실행하며, 한 소스의 작업은 요청된 순서대로 한 번에 하나씩(소스당 가장 오래된 열린 작업만 제공되며, 오래된 작업이 이후 작업보다 먼저) 처리하고, 네임스페이스는 차례로(가장 오래전에 서비스된 것부터) 처리합니다. 그 데드라인에서, 또는 중지된 프로세스로 인해 끊긴 실행은 작업의 시도 횟수에 포함됩니다.

장애

아래 각 장애는 이미 제공 중인 소스의 다음 리비전에서 발생합니다. 작업은 표시된 상태로 끝나고, error_code와 error_message가 그 이유를 알려 주며, 이전 리비전의 문서 행과 청크가 계속 제공됩니다. 일시적 장애는 LOOM_KNOWLEDGE_INGEST_MAX_ATTEMPTS를 모두 소진할 때까지 작업을 retrying과 함께 pending으로 되돌리고, 소진하면 retries_exhausted로 실패 처리합니다. 이 경우들은 tests/unit/test_knowledge_ingest.py::test_a_fault_on_the_next_revision_fails_typed_and_the_earlier_one_keeps_serving에 있습니다.

장애 작업 종료 상태
추출기에 연결할 수 없음 재시도 후 failed retries_exhausted
추출기가 LOOM_DOCUMENT_EXTRACTOR_TIMEOUT_S보다 느림 재시도 후 failed retries_exhausted
추출기가 압축된 응답을 반환함 (모든 Content-Encoding) 재시도 후 failed retries_exhausted
추출기가 자체 시간 제한을 넘겨 소스를 거부함 failed timeout
설정된 추출기가 없거나 서비스에 해당 파서가 없음 failed format_unavailable
아티팩트가 LOOM_DOCUMENT_EXTRACTOR_MAX_ARTIFACT_BYTES를 초과함 failed resource_limit
아티팩트가 JSON이 아니거나, 규약을 벗어나거나, 블록의 부모가 없거나, 로케이터가 원본을 벗어남 failed invalid_artifact
오브젝트 스토어가 원본 읽기 또는 아티팩트 쓰기에 실패함 재시도 후 failed retries_exhausted
임베더가 중단되었거나 기한을 초과함 재시도 후 failed retries_exhausted
임베더 결함 (그 밖의 모든 오류) failed internal
스토어가 청크 이후의 문서 행을 거부함 failed internal

스토어에서 원본이 사라지면 original_gone으로 실패합니다 (같은 파일에 있음). tests/integration/test_knowledge_ingest_faults_live.py는 추출기 중단, 부모가 없는 블록, 오브젝트 스토어의 읽기 실패, 임베더 중단, 청크 이후 문서 행 거부를 서버와 해당 ClickHouse를 대상으로 실행하며, 이전 리비전을 knowledge.get과 knowledge.search로 다시 읽어 확인합니다.

서비스 수준

혼합 부하에서 배포 환경이 지식 op에 요구하는 수준입니다. 대화형 읽기의 p95와 p99, 그리고 knowledge.ingest부터 작은 문서의 작업이 ready 상태로 끝날 때까지의 시간이 여기에 해당합니다. 각 op의 p99가 곧 지연 시간 예산(server/settings/catalog.py의 OP_BUDGETS_P99_MS)이며, 이 값은 단위 테스트로 검증합니다.

측정 항목 p95 (밀리초) p99 (밀리초)
knowledge.search 150 250
knowledge.query 1,000 1,500
knowledge.ingest 40 60
작은 문서 ingest 20,000 30,000

bench/knowledge_load.py는 서버에 혼합 부하를 걸고 그 결과를 이 표와 대조합니다. 작은 문서 ingest, 큰 PDF 한 건, CSV 가져오기를 동시에 실행하고, 게시된 내용에 대해 검색과 구조화된 쿼리를 수행하며, 네임스페이스의 열린 작업을 샘플링해 큐 깊이를 측정합니다. 호출은 이전 호출의 응답 여부와 관계없이 정해진 속도로 들어옵니다. 네임스페이스의 속도 제한(server/core/ratelimit.py)이 테넌트 하나가 보낼 수 있는 양을 제한하므로, --tenants는 여러 org에서 동시에 부하를 실행합니다. 결과로 op별 p50, p95, p99와 오류, 거부된 호출(429, 503)을 보고하며, 어느 측정 항목이든 기준을 넘으면 0이 아닌 코드로 종료합니다.

ingest는 배포 환경 전체에 대해 처리량이 제한됩니다. ingest 워커를 실행하는 프로세스는 하나뿐이며(LOOM_BACKGROUND_WORKERS=auto에서 워커의 lease를 보유하는 supervisor), 이 프로세스는 한 번에 작업 하나만 실행합니다. 따라서 replica가 몇 개이든 배포 환경은 작업을 차례로 실행하는 속도보다 빠르게 끝낼 수 없고, 큰 파일 뒤에 대기 중인 작업은 그 파일이 끝나기를 기다려야 합니다. 작업을 실행한 패스 다음에는 LOOM_KNOWLEDGE_INGEST_INTERVAL_SECONDS(0이면 즉시) 뒤에 다음 패스가 시작됩니다. 작업을 찾지 못한 패스는 LOOM_KNOWLEDGE_INGEST_IDLE_INTERVAL_SECONDS(15초)만큼 기다리므로, 한가한 배포 환경에서는 문서의 작업이 시작되기까지 최대 그 시간만큼 기다립니다. 작은 문서 기준은 이 대기 시간을 감안한 값이며, 작은 문서가 워커가 처리하는 속도보다 느리게 들어올 때만 유지됩니다.

데이터셋

아티팩트의 표(시트, CSV 또는 Parquet 파일, PDF의 표)는 타입이 있는 데이터셋(server/knowledge/app/datasets.py)이 되기도 하므로, 그 값을 구절이 아니라 값으로 읽을 수 있습니다. 파일의 형태와 상관없이 모든 데이터셋은 두 개의 테이블에 저장되므로, 업로드가 테이블을 만들지 않습니다.

  • loom.datasets, 카탈로그: (소스, 데이터셋, 문서 버전)마다 ReplacingMergeTree 행 하나를 두며 FINAL로 읽습니다. 스키마, 상태(inferred, needs_clarification, approved), 답변이 필요한 항목, 저장된 행과 거부된 행, 추출이 표의 모든 값을 유지했는지 여부, 그리고 이를 제공하는 스냅샷이 들어 있습니다.
  • loom.dataset_rows, 행: 컬럼의 값은 스키마가 정해 주는 타입별 슬롯에 들어가며, 슬롯은 모두 72개입니다. 텍스트와 시간은 s1..s24(Nullable(String)), 숫자와 기간(초 단위)은 n1..n24(Nullable(Decimal128(9)))에 들어가고, 그 슬롯을 넘는 숫자 컬럼은 f1..f8(Nullable(Float64))에 들어갑니다. 날짜와 날짜-시간은 t1..t8(Nullable(DateTime64(6, 'UTC'))), 불리언은 b1..b8에 들어갑니다. 해당 종류의 슬롯을 넘는 컬럼은 저장되지 않으며 그 사실이 표시됩니다(past_capacity). 키는 (org, namespace, dataset_id, snapshot_id, row_id)입니다.

컬럼은 추출기가 정한 타입을 따르며, mixed 컬럼은 텍스트로 보관됩니다. 셀 오류가 있는 행이나 컬럼의 타입이 담을 수 없는 값이 있는 행은 통째로 거부되어 개수가 집계되고, 처음 20개는 사유와 함께 기록됩니다. 따라서 데이터셋의 값은 모두 타입이 있습니다. 거부 대상은 n 슬롯에서 (소수 아홉 자리로 반올림한 뒤) 10^29 이상인 숫자, f 슬롯에서 double이 담을 수 없는 숫자, 1900-2299년 범위(DateTime64가 담는 범위) 밖의 시각입니다(시간대는 UTC로 변환됩니다). 데이터셋은 추출이 표의 모든 값을 유지했을 때만 complete입니다. 즉 행, 병합, 값, 셀 중 어느 것도 실패한 단위가 아니고, 손실된 공유 문자열이 없으며, 아티팩트가 값이 의존하는 기능(수식 값, 공유 문자열, 숫자 서식)을 하나도 잃지 않아야 합니다. 스키마는 다음 경우에 답변을 요청합니다(needs_clarification). mixed 컬럼, 생성된 이름(빈 헤더 셀), 중복된 이름(참조 추출기가 아닌 추출기가 보낼 수 있으며, 컬럼은 이름으로 지정되므로 참조 추출기처럼 데이터셋이 <name> (2)로 이름을 붙입니다), 모든 이름이 숫자나 날짜로 읽히는 헤더(첫 행이 데이터일 수 있음. Parquet 파일의 스키마처럼 이름이 소스의 행이 아닌, header_rows가 0인 표에는 묻지 않음), 그리고 어떤 슬롯에도 담기지 않는 컬럼(타입마다 답변 하나, 그중 첫 컬럼을 지목함)입니다. 개별 컬럼에 대한 질문은 100개에서 멈추며, 그 이후는 컬럼의 inferred 타입이 나머지를 알려 줍니다. 표의 너비가 16,384개 컬럼에 이를 수 있으므로 추론은 이벤트 루프 밖에서 실행됩니다. 데이터셋의 id는 소스의 모든 리비전에서 동일합니다. 시트는 이름으로, CSV나 Parquet 파일의 표와 PDF의 표는 각자의 id로 정해지며(PDF는 페이지에 나타난 순서대로이므로, 다른 표보다 앞에 표가 추가되면 뒤의 표는 새 데이터셋이 됩니다), 추출기가 둘 이상의 표로 나눈 시트는 이름과 표의 id로 정해집니다.

수집 작업은 각 데이터셋을 청크 뒤, 소스의 클레임 앞에 기록합니다. 먼저 빈 카탈로그 행을 써서 중간에 멈춘 실행이 자신이 쓴 행을 찾을 수 있게 하고, 이어서 새 스냅샷 아래 5,000개 단위 배치로 행을 씁니다(타입 변환은 이벤트 루프 밖에서 하며, 각 배치 전에 작업을 다시 읽으므로 작업을 삭제한 삭제 요청이 있으면 나머지 기록이 멈춥니다). 그다음 작업의 행이 가지는 문서 버전과 함께 카탈로그 행을 씁니다. 그 행이 기록되기 전에는 아무것도 이를 읽지 않습니다. 데이터셋은 소스의 라이브 문서 행이 게시 당시의 버전을 가지고 있는 동안 제공되므로, 문서 행은 청크와 데이터셋 모두에 대한 스위치이며, 소스의 텍스트 쓰기나 삭제는 제공을 즉시 중단시킵니다. 메타데이터 편집(knowledge.update_metadata)은 이를 유지합니다. 소스의 클레임 아래에서 각 카탈로그 행을 같은 스냅샷으로 새 버전에 맞춰 문서 행보다 먼저 씁니다. 그 행이 기록되면 소스의 이전 버전 스냅샷은 삭제되며, 그 전에 멈춘 실행은 자신의 스냅샷을 삭제합니다. 라이브 데이터셋이 승인된 소스의 리비전은 컬럼의 이름과 순서가 같으면 승인된 타입을 유지합니다. 게시가 라이브 데이터셋을 읽은 뒤에 기록된 승인(승인이 먼저 클레임을 잡음)은 작업을 즉시 다시 실행하도록 되돌리며 시도 횟수에는 포함되지 않으므로, 승인은 누락되지 않고 이월됩니다.

knowledge.dataset_approve는 데이터셋의 스키마를 승인하며, 지정한 컬럼의 타입을 다시 정합니다. 타입을 다시 정하면 저장된 아티팩트에서 새 스냅샷 아래로 행을 다시 타입 지정하며, 이는 소스의 클레임을 잡기 전에(수집의 게시가 잡는 것과 같은 클레임) 기록됩니다. 클레임 아래에서 승인은 문서가 자신이 읽은 문서이고 스냅샷이 호출자가 검토한 스냅샷인지 확인한 뒤, 새 스냅샷으로 전환하는 카탈로그 행을 쓰고(버전은 그 자리에서, 대체하는 행보다 뒤로 찍힘) 대체된 스냅샷의 행을 삭제합니다. 다른 쓰기가 소스를 옮겼음을 발견한 승인, 클레임을 잡을 수 없는 승인, 카탈로그 행이 전송되기 전에 실패한 승인은 카탈로그 행을 쓰지 않고 자신의 행을 삭제합니다. 카탈로그 insert가 전송된 뒤에 실패한 승인은 행이 기록되었을 수 있으므로 자신의 행을 유지합니다. 카탈로그 행은 승인자의 기록입니다. actor와 approved_by는 승인자를 가리키고 source_class는 asserted입니다. 행은 계속 업로더의 것으로 남으며(user_id와 행 자체의 source_class), 사용자 삭제 요청이 이를 찾을 수 있습니다.

스냅샷은 lightweight_deletes_sync = 0으로 경량 DELETE FROM을 통해 삭제됩니다. 어떤 카탈로그 행도 제공하지 않는 스냅샷은 아무것도 읽지 않으므로 어떤 요청도 이를 기다리지 않습니다. knowledge.delete는 자신이 읽은 버전까지, 폐기하는 문서 버전들의 데이터셋을 삭제합니다. 그동안 실행 중인 수집이 더 나중 버전을 쓰면, 삭제는 이를 그 수집에 온전히 맡깁니다(삭제는 클레임을 잡지 않으므로 수집의 배치 사이에 끼어들 수 있습니다). 이월된 스냅샷의 행은 기록된 당시의 버전을 유지하므로, 삭제는 경계를 넘는 카탈로그 행이 아직 제공하는 모든 스냅샷의 행을 남깁니다. 이월이 삭제가 카탈로그를 읽은 뒤에 기록되는 편집은, 그 버전이 더 나중이면 삭제를 넘어 문서를 되살릴 수 있습니다. 이 경우 청크는 툼스톤 처리되고 데이터셋은 행이 삭제된 채로 제공되며, 이는 클레임 없는 삭제가 편집과 경합할 때 남는 상태와 같고, 소스를 다시 삭제하면 둘 다 정리됩니다. 이미 삭제된 소스를 다시 삭제하면 폐기된 버전에 남은 것을 다시 삭제합니다(첫 삭제가 실행되는 동안 기록된 승인의 스냅샷이나 빌드 N-1이 남긴 스냅샷). 수집된 소스 위에 텍스트를 쓰면 그 스냅샷은 소스의 다음 수집이나 삭제 때까지 제공되지 않습니다. 삭제 요청(erasure)은 문서와 함께 해당 범위의 두 테이블 행을 삭제합니다(documents.tombstone).

쿼리

knowledge.query(server/knowledge/app/query.py)는 타입이 있는 플랜으로 데이터셋을 대상으로 계산합니다. 플랜은 호출자의 네임스페이스에 속한 최대 네 개의 데이터셋(각각 별칭 하나), 컬럼에 대한 필터(모두 성립해야 함), 첫 번째 이후의 각 데이터셋을 그 앞의 데이터셋에 연결하는 내부 등가 조인, 그룹(날짜나 날짜-시간은 UTC 기준 일, 월, 연 단위), 그리고 집계(count, count_distinct, sum, avg, min, max) 또는 행 id가 붙은 행 자체로 구성됩니다. 플랜은 데이터셋의 스키마에 대해 검증됩니다(server/knowledge/domain/query.py). 플랜이 지정하는 모든 컬럼은 스키마가 저장하는 컬럼이어야 하고, 모든 필터 값은 해당 컬럼의 타입으로 읽히며(행의 값과 같은 방식이지만 소수 아홉 자리를 넘는 decimal은 반올림하지 않고 거부함, double로 보관된 숫자 컬럼은 double로 비교됨), 모든 비교, 조인, 그룹, 집계는 컬럼의 타입이 허용하는 것이어야 합니다. decimal과 double은 공통 타입이 없으므로 조인 키는 같은 종류의 슬롯에 있어야 합니다. 플랜은 슬롯 이름, 결과 이름 c0, c1, ... 그리고 타입이 있는 파라미터만으로 만들어진 loom.dataset_rows 대상의 읽기 전용 문장 하나로 컴파일되므로(server/knowledge/store/dataset_query.py), 호출자가 쓴 어떤 것도 SQL이 되지 않습니다. 각 데이터셋은 조인 전에 자신의 필터와 함께 자신의 스냅샷 및 호출자의 org와 네임스페이스로 한정된 서브쿼리이므로, 다른 테넌트나 스냅샷의 행은 집계에 도달하지 않습니다. decimal 컬럼의 합은 어떤 데이터셋의 행으로도 오버플로하지 않는 Decimal256으로 계산하고, 평균은 그 합을 개수로 나누되 18자리로 나눈 뒤 아홉 자리로 반올림합니다(ClickHouse의 decimal avg는 double이고 decimal 나눗셈은 절사함). 데이터셋의 처음 24개 숫자 또는 기간 컬럼을 넘는 숫자 컬럼은 double로 보관되므로 double로 합산되고 평균이 계산됩니다.

각 데이터셋은 소스의 라이브 문서가 제공하는 스냅샷에서 읽습니다. 스키마가 답변을 필요로 하는(needs_clarification) 데이터셋은 승인될 때까지 거부됩니다. 문장은 LOOM_CH_READER_USER가 설정된 경우 읽기 전용 reader 사용자로, 호출자 기준 한도 아래에서 실행되므로(ch.caller_shaped), 배포 환경이 한 요청에 허용하는 행, 시간, 메모리를 넘는 플랜은 집계의 일부만 반환하지 않고 실패합니다(422). 행이 반환되기 전에 각 데이터셋은 여전히 읽은 스냅샷이 제공하고 있어야 합니다(게시나 타입 재지정 승인은 다른 스냅샷을 제공하게 하고 읽은 행을 기다리지 않고 삭제함, 삭제 요청은 아무것도 제공하지 않음, 메타데이터 편집은 유지함). 문장이 실행되는 동안 교체되거나 삭제된 경우, 그리고 쿼리가 데이터셋을 조회하는 동안 게시가 기록된 경우에는 409 PRECONDITION_FAILED로 응답하며 다시 실행해야 합니다. 결과는 영수증에 읽은 각 스냅샷을 이름으로 적고, 검증된 플랜, 문장과 그 파라미터를 함께 담으며, 데이터셋의 추출이 표의 일부를 빠뜨렸거나 행을 거부한 경우에는 이유와 함께 complete: false입니다. 아무것도 저장되지 않으며, 영수증이 곧 응답입니다.

datasets를 지정한 knowledge.synthesize(server/knowledge/app/synthesize.py, 프롬프트와 응답 해석은 server/knowledge/domain/answer_plan.py)는 작업과 각 데이터셋의 별칭, 이름, 행 수, 저장된 컬럼을 바탕으로 모델에게 한 번 knowledge.query 플랜을 요청하거나, 모델이 물어야 할 질문(ambiguous)을 요청합니다. 데이터셋은 호출자의 것이며, 플랜 자체의 datasets, org, namespace는 버려집니다. 플랜은 knowledge.query 입력으로 검증되고 그 핸들러가 실행하므로, 모든 쿼리와 마찬가지로 스키마에 대해 검증되고, 고정되고, 제한되고, 다시 검증됩니다. 둘 중 하나에서 거부된 플랜은 사유와 함께 한 번 더 제안되며, 그래도 거부되면 답변은 보류됩니다(invalid_plan). 결과의 컬럼과 처음 50개 행은 포함하지 못할 수 있는 내용과 함께 reduce를 위한 노트 하나로 추가되며, [knowledge.query#1]로 인용되고 청크 인용과 같이 근거 검사를 거치므로(ground_citations), 실행되지 않은 계산에 대한 인용은 제거됩니다. 컬럼 이름, 데이터셋 이름, 작업은 플랜에 대해 신뢰할 수 없는 입력이며 어떤 권한도 부여하지 않습니다. 쿼리는 호출자의 범위 안에서, reader 사용자가 설정된 경우 그 사용자로 실행됩니다.

의존성

참조 extractor의 파서는 SQL에 sqlglot, PDF에 pypdf(AES로 암호화된 PDF에는 cryptography도 필요), Parquet에 pyarrow가 필요하며, 그 밖의 경우에는 표준 라이브러리를 사용합니다. 이들은 서비스와 함께 설치되고(extractor/pyproject.toml), 개발 환경에서는 extractor extra로 설치됩니다. 서버 이미지에는 이 중 어느 것도 들어 있지 않습니다. extractor 이미지(extractor/Dockerfile, ghcr.io/clickhouse/loom-extractor)는 패키지와 잠금된 의존성(extractor/uv.lock)을 root가 소유한 venv에 설치하고, 그 안의 어떤 것도 소유하지 않는 사용자로 서비스를 실행하므로 자식 프로세스의 sys.path에 있는 어떤 파일도 자식 프로세스가 쓸 수 없습니다. compose 스택과 Helm 차트는 이 서비스를 서버와 분리하여 실행합니다. Compose에서는 서버만 공유하는 내부 네트워크에서 실행하고, 차트에서는 Loom의 파드만 허용하고 egress를 허용하지 않는 NetworkPolicy 뒤에서 실행하며, 토큰 외의 자격 증명은 없습니다. 두 방식 모두 추출이 단독으로 실행되는 동안(LOOM_EXTRACTOR_CONCURRENCY 1, 기본값) 소켓을 만들지 않습니다 (배포, Kubernetes).

불변 조건

  • 텍스트 형식의 내용은 블록으로 들어갑니다. 파서가 구조화하지 못한 부분은 조용히 버려지지 않고 coverage(실패한 단위, 잃어버린 기능)에 기록됩니다. 위에 나열된 HTML 요소만 의도적으로 제외됩니다.
  • 블록의 로케이터는 해당 블록이 나온 원본 텍스트를 가리킵니다.
  • 아티팩트는 바이트의 SHA-256으로 주소가 지정되며 수정되지 않습니다. 파서가 변경되면 해당 파서의 PARSER_VERSION이 올라가므로, 그 출력은 새로운 아티팩트가 됩니다.
  • 추출은 파싱하는 대상을 실행하지 않습니다.
  • 서버는 원본을 파싱하지 않습니다. 모든 형식은 추출기 서비스로 전달되며, 추출기가 반환한 결과는 parse_artifact가 수락하기 전에는 사용되지 않습니다.

소스 진입점

항목 위치
아티팩트 server/knowledge/domain/extract/artifact.py (Artifact, Block, Locator, Coverage)
응답 검사 server/knowledge/domain/extract/validate.py (parse_artifact)
포맷 라우팅 server/core/document_formats.py (format_of)
추출기 호출 server/knowledge/app/extractors.py (extract, available_formats)
구조 기반 청크 server/knowledge/domain/extract/structural.py (chunk_artifact)
데이터셋 스키마와 타입 지정 server/knowledge/domain/datasets.py (infer, typed_rows)
데이터셋 게시, 승인 server/knowledge/app/datasets.py, 행은 server/knowledge/store/datasets.py
데이터셋 쿼리 server/knowledge/app/query.py, 계획은 domain/query.py, SQL은 store/dataset_query.py
참조 서비스 extractor/loom_extractor/service.py, 추출 한 건당 child.py 프로세스 하나
포맷 감지, 디코딩 extractor/loom_extractor/source.py (detect_format, decode, extract)
SQL extractor/loom_extractor/sql.py (extract_sql, detect_dialect)
TOML extractor/loom_extractor/tomlfile.py
Markdown, 일반 텍스트, HTML extractor/loom_extractor/text.py, 제목 규칙은 markdown.py