콜백으로 내부 동작 추적하기
콜백으로 내부 동작 추적하기 (Callbacks)
라이브러리 내부에서 무슨 일이 일어나는지 디버깅하고, 추적하고, 로그를 남기고 싶다면 콜백(Callback)이 정답이에요. LlamaIndex는 콜백 매니저를 통해 필요한 만큼 콜백을 추가할 수 있게 해주고, 이벤트 관련 데이터 로깅은 물론 각 이벤트의 지속 시간과 발생 횟수까지 추적하게 해줘요. 여기에 더해 이벤트의 추적 맵(trace map) 도 기록되기 때문에 콜백이 이 데이터를 자유롭게 활용할 수 있어요. 예를 들어 LlamaDebugHandler는 대부분의 작업 후 이벤트 추적을 기본으로 출력해줘요.
출처: 공식문서
개념 — 추적 가능한 이벤트 타입
각 콜백이 모든 이벤트 타입을 활용하진 않지만, 추적할 수 있는 이벤트는 다음과 같아요.
CHUNKING— 텍스트 분할 전후 로깅NODE_PARSING— 문서와 그 문서가 파싱되어 만들어진 노드들 로깅EMBEDDING— 임베딩된 텍스트 수 로깅LLM— LLM 호출의 템플릿과 응답 로깅QUERY— 각 쿼리의 시작과 끝 추적RETRIEVE— 쿼리에 대해 검색(retrieve)된 노드들 로깅SYNTHESIZE— 합성(synthesize) 호출 결과 로깅TREE— 생성된 요약물과 요약 레벨 로깅SUB_QUESTION— 생성된 하위 질문·답변 로깅
이 이벤트들을 추적하도록 직접 콜백을 구현할 수도 있고, 기존 콜백을 사용할 수도 있어요.
제공되는 콜백 모듈
현재 지원되는 콜백은 다음과 같아요.
- TokenCountingHandler — 프롬프트·완성·임베딩 토큰 사용량의 유연한 카운팅. 마이그레이션 상세 참고
- LlamaDebugHandler — 이벤트의 기본 추적·트레이싱
- WandbCallbackHandler — Wandb Prompts 프론트엔드로 이벤트와 트레이스를 추적. Wandb 참고
- AimCallback — LLM 입력·출력 추적
- OpenInferenceCallbackHandler — AI 모델 추론(inference) 추적
- OpenAIFineTuningHandler — 모든 LLM 입력·출력을 기록한 뒤, OpenAI 파인튜닝에 적합한 형식으로 저장하는
save_finetuning_events()함수 제공