TL;DR

  • SledTrace는 명시적 호출을 추가한 Python RAG 파이프라인에서 검색 결과와 모델 입력·응답의 불일치를 로컬에서 추적하는 디버거임.
  • 대시보드는 계정이나 API 키 없이 사용자 컴퓨터에서 실행되며, 데이터는 업로드되지 않고 SQLite에 저장됨.
  • 검색 실패, 중복·충돌 청크, 낮은 검색 점수, 수치 불일치, 근거가 약한 답변 등 7가지 경고를 결정론적 휴리스틱으로 탐지함.
  • 도구 호출, 최종 작업 결과, 소요 시간, LLM 토큰 사용량도 기록하며 알 수 없는 값은 0이 아닌 미확인으로 표시함.
  • Python 전용, 영어 텍스트 패턴 기반 경고, 단일 사용자 로컬 도구라는 한계가 있으며 자동 통합과 호스팅 기능은 제공하지 않음.

SledTrace 소개

  • SledTrace는 RAG 파이프라인용 로컬 디버거임. 앱이 오답을 내면 검색기가 반환한 내용, 모델에 제공된 입력, 모델 응답, 이들 사이의 불일치를 보여줌.
  • 모든 처리는 사용자 컴퓨터에서 실행되며 계정이나 API 키가 필요하지 않고 데이터도 외부로 업로드되지 않음.

빠른 시작

  • pip install sledtrace로 설치하고 sledtrace serve를 실행하면 브라우저에서 http://127.0.0.1:4319 대시보드가 열림.
  • 별도 터미널에서 sledtrace의 trace를 가져와 질문과 함께 추적을 시작하고, 검색 단계에는 청크 ID·텍스트·점수·메타데이터를 전달하며, LLM 단계에는 모델·프롬프트·응답을 기록하는 방식임.
  • 예시에서는 배송 후 반품 가능 기간을 묻는 질문에 대해 30일과 14일로 서로 충돌하는 정책 청크가 검색되고, 어느 쪽에도 근거가 없는 ‘45일’ 답변이 기록됨.
  • 대시보드에서 refund-question을 열면 검색된 두 정책의 충돌과 응답의 수치가 근거에 없다는 점을 확인할 수 있음.
  • 자체 앱에 적용하는 절차는 5분 빠른 시작 안내에 제시됨.

탐지 항목

  • no_retrieved_chunks: 검색기가 사용할 수 있는 청크를 반환하지 않음.
  • low_retrieval_score: 가장 높은 점수의 청크도 점수가 낮음.
  • duplicate_chunks: 같은 텍스트가 두 번 이상 검색됨.
  • weak_query_chunk_overlap: 상위 청크가 질문의 핵심 용어를 거의 언급하지 않음.
  • conflicting_chunks: 검색된 청크끼리 내용이 서로 다름.
  • numeric_mismatch: 답변의 숫자가 검색 문맥과 모순됨.
  • answer_not_grounded: 답변의 주장이 문맥으로 약하게 뒷받침됨.
  • 각 경고에는 근거와 다음 확인 항목이 표시됨. 규칙은 로컬에서 실행되는 결정론적 휴리스틱이며, 데이터 판단에 LLM을 사용하지 않음.
  • 경고별 작동 방식과 한계는 경고 규칙 안내에서 확인할 수 있음.
  • 도구 호출, 최종 작업 결과, 처리 시간, LLM 토큰 사용량도 기록함. 알 수 없는 값은 0이 아니라 미확인으로 표시됨.

작동 방식

  • Python 앱에 trace, retrieval, llm 호출을 요청 경로에 추가하는 구조임.
  • SDK가 완료된 추적 정보를 sledtrace serve가 시작한 로컬 수집기로 전송하고, 수집기가 경고 규칙을 실행한 뒤 ~/.sledtrace/sledtrace.db에 데이터를 저장함.
  • 구성은 Python 앱 → SledTrace SDK → 로컬 수집기 → SQLite이며, 대시보드는 브라우저에서 실행됨.

한계

  • Python 전용이며 명시적 호출이 필요함. 현재 자동 LangChain 또는 LlamaIndex 통합은 없음.
  • 경고는 영어 텍스트 패턴을 바탕으로 한 휴리스틱이며 정답 여부를 판정하지 않음.
  • 토큰 사용량은 sledtrace.openai.record_response 등을 통해 전달한 경우에만 기록되며, 비용 추정치는 참고용임.
  • 호스팅, 인증, 팀 기능이 없는 로컬 단일 사용자 도구임.
  • sledtrace serve 사전 빌드는 Windows, macOS, Linux의 x86-64 및 ARM64용으로 제공됨. 그 밖의 플랫폼에서는 소스에서 실행해야 함.

문서

  • 빠른 시작: 자체 RAG 앱 계측 안내.
  • Python SDK 가이드: 전체 API 참조.
  • 경고 규칙: 각 경고가 확인하는 내용.
  • 개발 환경 설정: 소스 실행, Docker, 데모, 구성 안내.
  • 기여 안내 및 릴리스 노트.
  • RAGLens에서 이름 변경: raglens 가져오기(import)도 계속 작동함.

SledTrace라는 이름

  • 이름은 허스키에서 유래함. RAG 파이프라인은 검색기, 재순위화기, LLM이 함께 끄는 썰매 팀과 같으며, 썰매가 경로를 벗어나면 눈 위의 흔적을 읽어 어느 개가 비틀거렸는지 찾는다는 비유임. SledTrace는 그 흔적을 보여줌.

라이선스

  • MIT