번역되지 않은 페이지는 영어로 열리며 영어로 표시됩니다.
이 페이지는 영어 원문을 기계 번역한 것이며, 영어 원문이 기준입니다. Machine-translated from the English page, which is authoritative.
추출기 계약
추출기는 Loom 서버가 원본 파일을 보내면 추출 아티팩트를 돌려주는 HTTP 서비스입니다.
이 페이지는 서버와 추출기 사이의 계약 버전 1입니다. Loom의 참조 추출기(extractor/loom_extractor/)이든 운영자가 직접 만든 추출기이든, 서비스가 반드시 제공해야 하는 내용을 설명합니다. 파싱을 서버 밖에서 실행하는 이유와 서버가 응답을 읽는 방식은 문서 추출에서 다룹니다.
서버 설정
| 설정 | 의미 |
|---|---|
LOOM_DOCUMENT_EXTRACTOR_URL |
어떤 경로도 지정하지 않은 형식이 향하는 기본 URL |
LOOM_DOCUMENT_EXTRACTORS_JSON |
{format or media type: base URL}. 형식의 키가 미디어 타입의 키보다 우선하며(미디어 타입의 키는 해당 미디어 타입의 형식에만 적용됨), 둘 다 위의 URL보다 우선합니다. 어떤 형식도 가리키지 않는 키나 같은 미디어 타입을 두 번 표기한 키는 로드 시 거부됩니다 |
LOOM_DOCUMENT_EXTRACTOR_TOKEN |
아래에 자체 토큰이 없는 서비스로 보내는 bearer 토큰 |
LOOM_DOCUMENT_EXTRACTOR_TOKENS_JSON |
{base URL: token}. 서비스별 자체 토큰이므로 어떤 서비스도 다른 서비스가 받아들이는 토큰을 가지지 않습니다. 각 URL은 위의 두 설정 중 하나에 있는 URL이어야 합니다 |
LOOM_DOCUMENT_EXTRACTOR_TIMEOUT_S |
한 번의 호출 전체에 허용되는 시간(초). 기능 정보를 읽는 시간, 또는 원본을 보내고 응답을 읽는 시간입니다 |
LOOM_DOCUMENT_EXTRACTOR_MAX_ARTIFACT_BYTES |
서버가 읽는 응답의 최대 크기. 이보다 긴 응답은 resource_limit로 거부됩니다 |
형식 이름은 markdown, html, text, sql, toml, pdf, docx, pptx, xlsx, csv, parquet입니다. 예를 들어 PDF는 운영자가 직접 운영하는 서비스로 보내고 나머지는 모두 참조 추출기로 보내려면 다음과 같이 설정합니다.
LOOM_DOCUMENT_EXTRACTOR_URL=http://extractor:8790
LOOM_DOCUMENT_EXTRACTORS_JSON='{"pdf": "http://pdf-extractor:8080"}'
엔드포인트
모든 호출에는 Authorization: Bearer <token>이 포함됩니다. 서비스는 토큰이 없거나 잘못된 경우 401로 응답합니다.
GET /v1/capabilities
서비스가 추출하는 대상을 알려 줍니다. 서버는 라우팅된 서비스가 여기에 나열한 포맷만 추출하며, 1분 후에 이 정보를 다시 읽습니다.
{
"contract_version": 1,
"extractor": { "name": "loom-reference", "version": "1" },
"max_bytes": 67108864,
"formats": [
{ "format": "markdown", "options": ["encoding"] },
{ "format": "sql", "options": ["encoding", "sql_dialect"] }
]
}
| 필드 | 의미 |
|---|---|
contract_version |
1입니다. 서버는 다른 버전의 서비스를 사용할 수 없는 것으로 처리합니다 |
max_bytes |
서비스가 받는 원본의 최대 크기입니다. 서버는 이보다 큰 원본을 보내지 않습니다 |
formats |
서비스가 추출하는 각 포맷과 그 포맷이 받는 옵션입니다 |
POST /v1/extract
원본의 바이트가 본문입니다(Content-Type: application/octet-stream). 쿼리는 서버가 요청하는 내용을 지정합니다.
| 매개변수 | 의미 |
|---|---|
format |
서버가 파일에 대해 라우팅한 포맷 |
name |
파일 이름이며, 비어 있을 수 있습니다 |
encoding |
선택 사항: 자체적으로 인코딩을 밝히지 못하는 텍스트 파일의 코덱 이름 |
sql_dialect |
선택 사항, SQL 전용: 파싱에 사용할 방언 |
서비스는 받지 않는 옵션을 거부합니다(invalid_option). 또한 내용을 format과 대조하여, 다른 포맷의 파일이면 요청된 포맷으로 읽지 않고 거부합니다(format_mismatch).
200은 아티팩트 JSON을 담습니다. 서버는 Accept-Encoding: identity를 보내며, 서비스는 응답을 압축해서는 안 됩니다. 서버는 상태와 관계없이 압축된 응답을 서비스를 사용할 수 없는 것으로 처리합니다. 서비스가 추출할 수 없는 소스는 오류 본문과 함께 422로 응답합니다.
{ "error": { "code": "format_mismatch", "message": "the file is pdf, not markdown" } }
| 코드 | 의미 |
|---|---|
unsupported_format |
어떤 추출기도 지원하지 않는 포맷의 파일입니다 |
format_unavailable |
이 서비스는 해당 포맷을 추출하지 않습니다 |
format_mismatch |
내용이 요청된 포맷과 다른 포맷입니다 |
encoding |
텍스트를 디코딩할 수 없습니다 |
corrupt |
파일이 손상되었거나 파서가 처리하지 못합니다 |
invalid_option |
옵션을 알 수 없거나 서비스가 거부하는 값을 가졌습니다 |
too_large |
원본이 서비스의 max_bytes를 초과합니다 |
timeout |
추출이 서비스가 허용하는 시간보다 오래 걸렸습니다 |
resource_limit |
추출이 메모리 또는 출력 한도를 넘었습니다 |
서버는 소문자와 _로 이루어진 최대 40자의 코드를 실패 코드로 보존하며, 그 외의 코드나 64 KiB를 넘는 오류 본문은 refused로 읽습니다. 서버는 401, 403, 407, 408, 429, 모든 5xx, 200이나 4xx가 아닌 그 밖의 응답(리다이렉트, 204), format_unavailable, 그리고 타임아웃을 넘긴 호출을 서비스를 사용할 수 없는 것으로 처리하므로 소스를 나중에 다시 시도할 수 있습니다. 그 밖의 4xx는 소스가 거부된 것으로 처리합니다. 아래 규칙을 어기는 아티팩트를 담은 200은 invalid_artifact로 거부됩니다.
아티팩트
{
"schema_version": 1,
"format": "toml",
"parser": "loom-toml",
"parser_version": "1+python3.12.13",
"options": {},
"attrs": {},
"warnings": [],
"coverage": {
"unit": "keys",
"total": 1,
"extracted": 1,
"failed": [],
"lost": [],
"complete": true
},
"blocks": [
{
"id": "b0",
"type": "toml_table",
"text": "[server]",
"section_path": ["server"],
"locator": { "line_start": 1, "line_end": 1, "key_path": "server" },
"keys": ["server"]
},
{
"id": "b1",
"type": "toml_key",
"text": "server.port = 7777",
"parent": "b0",
"section_path": ["server"],
"locator": { "line_start": 2, "line_end": 2, "key_path": "server.port" },
"keys": ["server.port"],
"attrs": { "value": 7777, "value_type": "integer" }
}
]
}
| 필드 | 타입 | 규칙 |
|---|---|---|
schema_version |
정수 | 1 |
format |
문자열 | 요청한 format |
parser, parser_version |
비어 있지 않은 문자열 | 아티팩트를 만든 주체. 파서가 바뀌면 새 버전이 된다 |
options, attrs |
객체 | 중첩은 최대 16단계 |
warnings |
문자열 목록 | |
coverage.unit |
비어 있지 않은 문자열 | 형식을 이루는 단위: lines, statements, keys, chars, pages, paragraphs, slides, rows, ... |
coverage.total, coverage.extracted |
정수 | 0 <= extracted <= total |
coverage.failed |
{unit, reason} 목록 |
추출되지 않은 각 단위 |
coverage.lost |
문자열 목록 | 아티팩트가 제공할 수 없는 기능 (예: sql_structure) |
coverage.complete |
불리언, 선택 | 보내는 경우 extracted == total이면서 실패와 손실이 없는 것과 같아야 한다 |
blocks |
목록 | 읽는 순서대로 |
blocks[].id |
비어 있지 않은 문자열 | 아티팩트 내에서 고유 |
blocks[].type |
문자열 | heading, paragraph, list, code, sql_statement, toml_table 또는 toml_key |
blocks[].text |
문자열 | |
blocks[].parent |
문자열, 선택 | 이 블록을 감싸는 앞선 블록의 id |
blocks[].depth |
정수, 선택 | 0 이상. 제목의 수준 |
blocks[].section_path |
문자열 목록 | 블록 위에 있는 제목들. 최대 64개, 각각 최대 500자 |
blocks[].keys |
문자열 목록 | 블록을 조회할 때 쓰는 정확한 이름. 최대 10,000개, 각각 최대 1,024자 |
blocks[].attrs |
객체 | 형식별 정보 (행 블록의 table_id: 행이 속한 표의 id. DOCX, PPTX, HTML 표 블록의 table: 해당 표의 rows와 columns. 페이지와 다른 방향으로 흐르는 텍스트의 PDF 블록의 orientation. 이미지에서 읽은 블록의 ocr) |
blocks[].locator |
객체 | line_start/line_end (1부터 시작, 둘 다 0 또는 1 <= start <= end), char_start/char_end (디코딩된 텍스트에서의 오프셋, 둘 다 -1 또는 0 <= start <= end), key_path, page_start/page_end (PDF의 페이지 또는 덱의 슬라이드, 1부터 시작, 둘 다 0 또는 1 <= start <= end), sheet (워크북의 시트 이름, 최대 500자), row_start/row_end (시트나 CSV 파일의 행으로 헤더를 포함해 센다. Parquet 파일의 행은 1부터, PDF 표의 행은 헤더 행을 1로 센다. 1부터 시작, 둘 다 0 또는 1 <= start <= end) |
표 형식 소스(CSV 파일, 워크북의 시트, Parquet 파일)와 표가 들어 있는 PDF는 검색에 쓰이는 행 블록과 함께 tables도 포함한다:
| 필드 | 타입 | 규칙 |
|---|---|---|
tables |
목록, 선택 | 소스의 각 표 |
tables[].id, tables[].name |
문자열 | id는 고유하며 비어 있지 않아야 한다. name은 시트 이름, 파일 이름, 또는 PDF 표의 페이지와 위치(page 3 table 1) |
tables[].columns |
{name, type} 목록 |
최대 16,384개. name은 최대 500자. type은 string, number, bool, date, datetime, time, duration 또는 mixed (담고 있는 모든 값의 종류이며, 날짜와 날짜-시간이 함께 있으면 datetime) |
tables[].rows |
목록의 목록 | 각각 columns와 길이가 같다. 각 값은 문자열, 숫자, 불리언, null, 또는 셀 오류 {"error": "#DIV/0!"}. 날짜와 시간은 ISO 텍스트, 기간은 하루를 넘는 시간을 허용하는 H:MM:SS(36:00:00), 소수, 또는 부호 있는 64비트를 넘는 정수이며, number 열에서는 정확한 자릿수 문자열("12.345")이다 |
tables[].header_rows |
integer, 선택 사항 | 0 이상이며, 생략하면 1: 열 이름을 이루는 값 위에 있는 행. 이름이 소스의 행이 아닌 소스(Parquet 스키마)에는 0이며, 이 경우 행은 1부터 센다 |
tables[].locator |
object | 블록의 locator와 같음: 표가 걸쳐 있는 시트(또는 PDF의 페이지)와 행 |
tables[].attrs |
object | 형식별 정보(숨겨진 시트에는 hidden) |
tables를 모르는 서버는 계약에 명시되지 않은 다른 필드와 마찬가지로 이 필드를 버리고, 행 블록은 그대로 게시합니다.
모든 문자열은 유효한 Unicode여야 하며, 모든 숫자는 JSON 숫자여야 합니다(NaN이나 Infinity 불가). 정수는 부호 있는 64비트(-2^63에서 2^63-1까지이므로 그 범위를 넘는 UInt64는 불가)이고, 그 밖의 숫자는 double 범위 안에 있어야 합니다(1e999 불가). 서버는 규칙을 하나라도 어기는 아티팩트를 거부하며, 계약에 명시되지 않은 필드는 버리므로 서비스는 버전을 바꾸지 않고도 그런 필드를 보낼 수 있습니다. 이전 서버가 읽을 수 없는 변경은 schema_version을 올립니다. 블록의 키와 섹션 경로는 그 블록에서 잘라낸 모든 청크와 함께 전달되므로, 아티팩트의 크기뿐 아니라 개수와 길이에도 제한이 있습니다. 참조 추출기는 더 긴 키를 제외하고, 처음 10,000개의 키와 처음 64개의 섹션 항목(각각 500자로 자름)만 유지합니다. 그리고 해당 블록에 attrs.keys_truncated 또는 attrs.section_truncated를, 아티팩트의 coverage.lost에 (exact_keys, section_path)를 표시하여 스스로를 완전하다고 보고하지 않게 합니다. 여기와 char_start/char_end에서 문자는 디코딩된 텍스트의 Unicode 코드 포인트입니다(UTF-16 단위나 바이트가 아님). 줄 또는 문자 범위는 원본 안에 있어야 합니다. 서버는 char_end가 원본의 바이트 크기를 넘거나 line_end가 그 크기에 1을 더한 값을 넘는 아티팩트를 거부하며, 이 한계는 어떤 인코딩에서도 성립합니다.