ragking

LlamaIndex 기반 한국어(법령·규정) RAG 라이브러리. 파일을 계층적으로 청킹·임베딩해 저장하고, auto-merging 검색 + 리랭크 + LLM으로 답한다.

앱이 아니라 라이브러리다 — 서버 진입점이 없고, 호스트 앱(FastAPI 등)에 임포트해서 쓴다.

인제스트:  File ──▶ Converter ──▶ Processor ──▶ connector.upload ──▶ (벡터 스토어 + docstore)
                  bytes→markdown    청킹(parent/leaf)   Small-to-Big 저장

조회:      RAGRetriever ──▶ AutoMergingRetriever ──▶ (리랭커) ──▶ LLM
                            leaf 검색→부모로 병합

특징

• 한국어 법령 문서용 파서 — 장/절/조/부칙 헤더 트리를 세워 조문 단위로 청킹하고 section_path·page_start/page_end를 메타데이터로 남긴다(인용 앵커).
• Small-to-Big 저장 — leaf만 임베딩해 벡터 스토어에, 부모는 docstore에. 검색은 좁은 leaf로 하고 답변 컨텍스트는 부모로 넓힌다.
• 레지스트리 한 번 초기화 — rag_registry.initialize(config) 이후 컴포넌트 배선이 없다.
• 내부망 전제 — 임베딩·LLM 모두 OpenAI 호환 엔드포인트(vLLM, TEI 등)를 가리키고, PDF 변환은 내부 Marker API에 위임한다.
• 하이브리드 검색(opt-in) — dense + BM25 sparse로 조문 번호·법령명 정확 매칭을 살린다.
• FastAPI/Celery 연동 제공 — lifespan, 요청 의존성, /health 라우터, 인제스트 태스크.

설치

pip install ragking
# 또는 저장소에서 직접
pip install git+https://github.com/JunseoKR/ragking.git

Python 3.10+ (CI는 3.10/3.11/3.12). 설치 한 번으로 전부 들어온다 — celery(비동기 인제스트), redis docstore, pymupdf(2-up PDF 분리)까지 기본 의존성이며 기능별 extra는 없다. 하이브리드 검색(fastembed)만 예외로 별도 설치가 필요하다. 폐쇄망 설치는 offline-install 참고.

필요한 외부 서비스: 임베딩 서버·LLM 서버(OpenAI 호환)·Qdrant는 필수, MinIO·Marker API· 리랭크 서버는 용도에 따라 선택이다. 자세한 표는 getting-started 참고.

30초 사용법

from ragking.fastapi.registry import rag_registry
from ragking.tasks import run_ingest
from ragking.retrievers.retriever import RAGRetriever

rag_registry.initialize()                                             # env/.env → 설정 로드
run_ingest(bucket="docs", object_name="법령.pdf", file_type="legal")   # 인제스트
print(RAGRetriever().query("제12조의 내용은?"))                        # 조회

FastAPI 호스트 앱에 붙일 때:

from fastapi import FastAPI, Depends
from ragking.fastapi import ragking_lifespan, get_retriever, health_router

app = FastAPI(lifespan=ragking_lifespan(settings))
app.include_router(health_router)


@app.post("/query")
async def query(q: str, retriever=Depends(get_retriever)):
    return {"answer": await retriever.aquery(q)}

문서

전체 문서는 docs/에 있다.

개발

python3 -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
pytest tests/unit      # 단위 테스트(외부 서비스 불필요)
ruff check .

tests/integration/은 벡터 스토어 등 외부 서비스를 전제한다. 기여 규약과 저장소 관례는 AGENTS.md와 .agents/ 참고.

라이선스

MIT