API Reference

기준 버전: Evidence-Chunker 0.1.2. 설치 및 가장 짧은 예제는 README를 참고하세요.

EvidenceChunker

from evidence_chunker import EvidenceChunker

chunker = EvidenceChunker(
    parser=None,
    artifacts_path=None,
    bbox_threshold=300.0,
    sim_threshold=0.0,
)

인자	타입	기본값	설명
parser	PdfParser | None	None	parse(path) -> ParsedDoc를 구현한 파서. chunk()에만 적용
artifacts_path	str | None	None	기본 Docling 파서의 모델 아티팩트 경로
bbox_threshold	float	300.0	표 주변 설명 문단 탐색 거리(pt)
sim_threshold	float	0.0	> 0이면 캡션과 문단 간 임베딩 유사도 필터 활성화

chunk(pdf_path, doc_id=None)

표 중심 EvidenceUnit 목록을 반환합니다. 큰 단위에는 분할 정책을 적용합니다. doc_id 기본값은 PDF 파일명의 확장자를 뺀 문자열입니다.

units = chunker.chunk("paper.pdf", doc_id="paper")

반환: list[EvidenceUnit] (표가 없는 PDF는 빈 리스트 가능)

build_corpus(pdf_path, doc_id=None)

표 기반 EvidenceUnit과 일반 본문 TextChunk가 섞인 리스트를 반환합니다. 일반 본문은 Docling HybridChunker를 사용합니다.

corpus = chunker.build_corpus("paper.pdf")

반환: list[EvidenceUnit | TextChunk]

제약: EvidenceChunker(parser=custom_parser)로 생성한 경우 NotImplementedError를 발생시킵니다. 커스텀 파서로 표 기반 근거만 생성할 때는 chunk()를 사용하세요.

build_evidence_units(parsed, ...)

이미 파싱된 ParsedDoc을 입력받아 분할 이전의 EvidenceUnit을 만드는 하위 수준 함수입니다.

from evidence_chunker.chunker import build_evidence_units

units = build_evidence_units(parsed, bbox_threshold=300.0, sim_threshold=0.0, doc_id="paper")

EvidenceUnit

from evidence_chunker import EvidenceUnit

주요 데이터 필드:

필드	의미
eu_id, doc_id, page_no, table_index	ID 및 원본 위치 정보
page_span	해당 단위에 포함된 관련 페이지
caption_text, caption_confidence	캡션, 연결 방식 (direct/inferred/none)
section_header, footnote_text	섹션 제목, 각주
context_before, context_after	표 위·아래에서 선택한 문단 목록
table_html, flattened_rows, table_abstract	표 HTML, 행별 검색 문장, 표 요약
bbox	BOTTOMLEFT 기반 정규화 좌표 (x1, y1, x2, y2)
is_split, split_index, total_splits	분할 관련 정보

계산되는 프로퍼티:

프로퍼티	반환값	목적
text	str	표 HTML을 포함한 전체 근거 텍스트
retrieval_text	str	표 HTML을 제외한 검색 텍스트
retrieval_units	list[str]	행·문단 등의 세부 검색 표현
safe_caption	str | None	그림 캡션 오인식 방지 처리 후 캡션
chunk_id	str	eu_id의 별칭
metadata	dict	페이지·캡션·표 인덱스 등 검색용 메타데이터
is_atomic	bool	EvidenceUnit은 False

for unit in chunker.chunk("paper.pdf"):
    print(unit.retrieval_units[:2])
    print(unit.metadata["chunk_id"])
    print(unit.text)

retrieval_units의 캡션 반복 prefix를 끄는 공식 API 옵션은 v0.1.2에 없습니다. 해당 변형은 Experiments에 기록돼 있습니다.

LangChain export

추가 설치:

pip install -e '.[langchain]'

from evidence_chunker.export.langchain import (
    to_langchain,
    to_langchain_units,
    dedupe_by_chunk_id,
    EvidenceRetriever,
)

API	반환/동작
to_langchain(chunks)	청크당 Document 하나, page_content=chunk.text
to_langchain_units(chunks)	EU의 retrieval_units별 Document; 일반 본문은 하나로 유지
dedupe_by_chunk_id(results, k=None, key="chunk_id")	이미 정렬된 결과에서 부모 ID 중복 제거
EvidenceRetriever(vectorstore, k=5, fetch_k=None, dedupe=True)	similarity_search_with_score 지원 VectorStore를 감싸는 후처리 래퍼

to_langchain_units()는 EU의 세부 검색 문서에 전체 부모 근거를 metadata["parent_text"]로 넣습니다. EvidenceRetriever.invoke(query)는 **검색 유닛 Document**를 반환하며, parent_text로 자동 치환하지 않습니다.

search_docs = to_langchain_units(chunker.build_corpus("paper.pdf"))
for doc in search_docs[:3]:
    display_text = doc.metadata.get("parent_text", doc.page_content)
    print(display_text[:100])

EvidenceRetriever는 LangChain의 BaseRetriever 하위 클래스가 아닌 별도 래퍼입니다. 기본 fetch_k는 max(k * 4, 20)이며, 전체 인덱스가 아니라 가져온 후보 안에서 중복을 제거합니다.

LlamaIndex export

pip install -e '.[llamaindex]'

from evidence_chunker.export.llamaindex import (
    to_llamaindex,
    to_llamaindex_units,
    dedupe_by_chunk_id,
    EvidenceRetriever,
)

API	반환/동작
to_llamaindex(chunks)	청크당 TextNode 하나
to_llamaindex_units(chunks)	EU의 검색 유닛별 TextNode 생성, metadata["parent_text"] 포함
dedupe_by_chunk_id(results, k=None, key="chunk_id")	NodeWithScore 또는 TextNode 목록 중복 제거
EvidenceRetriever(base_retriever, k=5, dedupe=True)	.retrieve(query) 결과를 중복 제거하는 래퍼

LlamaIndex의 EvidenceRetriever를 사용할 때 기본 retriever의 similarity_top_k를 최종 k보다 넉넉히 설정하세요.

Custom parser

PdfParser는 다음 계약을 만족합니다.

class PdfParser(Protocol):
    def parse(self, path: str) -> ParsedDoc: ...

ParsedDoc은 texts, tables, picture_caption_refs, page_sizes를 포함합니다. 내부 BBox는 TOPLEFT 좌표계입니다. 기본 파서 구현은 evidence_chunker.parser.docling.DoclingParser입니다.

커스텀 파서 구현 예제와 데이터 계약은 Examples 및 parser/base.py를 참고하세요.