Observability: LLM 애플리케이션 관찰·디버깅·평가

Observability: LLM 애플리케이션 관찰·디버깅·평가

RAG 시스템이나 에이전트 같은 LLM 애플리케이션을 제대로 개발하려면, 시스템 전체와 각 컴포넌트를 관찰·디버깅·평가할 수 있어야 해요. LlamaIndex는 원클릭 옵저버빌리티🔭 를 제공해 프로덕션 환경의 원칙 있는 LLM 애플리케이션 개발을 돕는데, 설정 변수 하나만 바꾸면 파트너가 제공하는 강력한 관찰·평가 도구와 매끄럽게 연결돼요.

출처: 공식문서

이 기능을 쓰면 다음과 같은 것들이 가능해져요.

• LLM/프롬프트 입력·출력 보기
• (LLM, 임베딩 같은) 각 컴포넌트의 출력이 기대대로 동작하는지 확인
• 인덱싱과 쿼리 모두의 호출 트레이스 보기

참고로 옵저버빌리티는 이제 instrumentation 모듈이 담당해요 (v0.10.20 이상). 이 페이지의 많은 도구·통합은 레거시 CallbackManager를 쓰거나 set_global_handler를 쓰지 않아요 — 그런 통합은 별도로 표시해 뒀어요.

사용 패턴

기본 사용법은 아주 간단해요. set_global_handler에 핸들러 이름을 넘기면 돼요.

from llama_index.core import set_global_handler

# general usage
set_global_handler("<handler_name>", **kwargs)

set_global_handler에 넘기는 모든 kwargs는 내부 콜백 핸들러로 전달돼요. 이게 전부예요! 실행이 자동으로 다운스트림 서비스로 이어지고, 애플리케이션의 실행 트레이스를 볼 수 있게 돼요.

주요 통합

OpenTelemetry

OpenTelemetry는 널리 쓰이는 오픈소스 트레이싱·옵저버빌리티 서비스로, Jaeger·Zipkin·Prometheus 같은 다양한 백엔드 통합을 지원해요. LlamaIndex 통합은 LLM, 에이전트, RAG 파이프라인 컴포넌트 등 코드에서 만들어지는 모든 이벤트를 트레이스해서 OpenTelemetry 형식으로 내보내요.

pip install llama-index-observability-otel

from llama_index.observability.otel import LlamaIndexOpenTelemetry
from llama_index.core import SimpleDirectoryReader, VectorStoreIndex
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.core import Settings

instrumentor = LlamaIndexOpenTelemetry()

if __name__ == "__main__":
    embed_model = OpenAIEmbedding(model_name="text-embedding-3-small")
    llm = OpenAI(model="gpt-4.1-mini")

    # start listening!
    instrumentor.start_registering()

    documents = SimpleDirectoryReader(
        input_dir="./data/paul_graham/"
    ).load_data()

    index = VectorStoreIndex.from_documents(documents, embed_model=embed_model)
    query_engine = index.as_query_engine(llm=llm)

    query_result_one = query_engine.query("Who is Paul?")
    query_result_two = query_engine.query("What did Paul do?")

더 복잡한 커스텀 구성(예: 커스텀 span exporter)도 지원해요. 에이전트 워크플로우를 트레이싱해 Postgres DB로 파이프하는 데모 저장소도 있어요.

LlamaTrace (호스팅 Arize Phoenix)

LlamaIndex 오픈소스 사용자와 네이티브로 동작하고 LlamaCloud 통합을 갖춘 호스팅 트레이싱·옵저버빌리티·평가 플랫폼이에요. 오픈소스 Phoenix 프로젝트 위에 만들어졌어요. Phoenix는 LLM 트레이스(애플리케이션 내부 실행·검색·도구 실행 문제 해결)와 LLM Eval(대형 언어 모델로 관련성·유해성 등 평가)을 제공해요.

pip install -U llama-index-callbacks-arize-phoenix

import llama_index.core
import os

PHOENIX_API_KEY = "<PHOENIX_API_KEY>"
os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = f"api_key={PHOENIX_API_KEY}"
llama_index.core.set_global_handler(
    "arize_phoenix", endpoint="https://llamatrace.com/v1/traces"
)

SigNoz

SigNoz는 OpenTelemetry 기반 오픈소스 옵저버빌리티 프레임워크예요. 트레이스·로그·메트릭을 한 화면에서 보여주고 자체 호스팅과 클라우드 배포 옵션을 둘 다 제공해요. LlamaIndex와 함께 쓰면 모든 RAG·에이전트 워크플로우의 상세 트레이스를 보면서 토큰 사용량·지연·오류율·LLM 모델 분포 같은 핵심 메트릭을 추적할 수 있어요.

pip install \
  opentelemetry-distro \
  opentelemetry-exporter-otlp \
  opentelemetry-instrumentation-httpx \
  opentelemetry-instrumentation-system-metrics \
  llama-index \
  openinference-instrumentation-llama-index

자동 계측을 추가하고(opentelemetry-bootstrap --action=install), 환경변수로 OTLP 엔드포인트·수집 키를 지정한 뒤 opentelemetry-instrument <your_run_command>로 애플리케이션을 실행하면 트레이스·로그·메트릭이 보여요.

W&B Weave

W&B Weave는 LLM 애플리케이션을 추적·실험·평가·배포·개선하는 프레임워크예요. LlamaIndex의 instrumentation 모듈을 활용해 span/이벤트를 Weave 호출로 등록해요. weave.init()를 부르면 자동으로 일반 LLM 라이브러리·프레임워크의 호출을 패치·추적해요.

import weave
from llama_index.llms.openai import OpenAI

# Initialize Weave with your project name
weave.init("llamaindex-demo")

llm = OpenAI(model="gpt-4o-mini")
response = llm.complete("William Shakespeare is ")
print(response)

{"openai": {"enabled": False}}같은autopatch_settings인자로 패칭 동작을 제어할 수도 있어요. 추적되지 않는 커스텀 함수는@weave.op()로 장식하면 돼요. weave.init()`가 호출되는 순간부터 추적이 시작되니 추가 설정이 필요 없어요.

MLflow

MLflow는 ML 프로젝트 전체 수명주기에 초점을 맞춘 오픈소스 MLOps/LLMOps 플랫폼이에요. MLflow Tracing은 OpenTelemetry 기반 트레이싱 기능으로, LlamaIndex 애플리케이션의 원클릭 계측을 지원해요. 오픈소스라서 계정 생성·API 키 설정 없이 바로 쓸 수 있어요.

import mlflow

mlflow.llama_index.autolog()  # Enable mlflow tracing

MLflow Tracing은 LlamaIndex 기능 전체를 지원하고, AgentWorkflow 같은 일부 신기능은 MLflow >= 2.18.0을 요구해요.

OpenLLMetry

OpenLLMetry는 OpenTelemetry 기반 오픈소스 LLM 애플리케이션 트레이싱·모니터링 프로젝트예요. 주요 옵저버빌리티 플랫폼에 연결되고 몇 분이면 설치돼요.

from traceloop.sdk import Traceloop

Traceloop.init()

Langfuse

Langfuse는 팀이 LLM 애플리케이션을 협업 디버깅·분석·반복하게 돕는 오픈소스 LLM 엔지니어링 플랫폼이에요. 인덱싱·쿼리 과정의 상세 트레이스를 캡처해 Langfuse UI에서 직접 검토할 수 있어요. 새 instrumentation 기반 통합을 추천하고, 레거시 langfuse 핸들러는 deprecated예요.

pip install llama-index langfuse openinference-instrumentation-llama-index

import os
os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..."
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..."
os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com"

from langfuse import get_client
langfuse = get_client()

from openinference.instrumentation.llama_index import LlamaIndexInstrumentor
LlamaIndexInstrumentor().instrument()

Literal AI, Comet Opik, Argilla, Agenta, Deepeval, Maxim AI

이 외에도 LLM 평가·옵저버빌리티 솔루션들이 다양하게 연결돼요.

• Literal AI: 프롬프트 엔지니어링·옵저버빌리티·평가·모니터링을 위한 협업 개발 사이클. set_global_handler("literalai")로 연결.
• Comet Opik: 오픈소스 종단간 LLM 평가 플랫폼. OPIK_API_KEY, OPIK_WORKSPACE 환경변수 + set_global_handler("opik").
• Argilla: AI 엔지니어·도메인 전문가를 위한 협업 도구. ArgillaHandler를 dispatcher에 추가.
• Agenta: 오픈소스 LLMOps 플랫폼. ag.init() + LlamaIndexInstrumentor().instrument().
• Deepeval (Confident AI): LLM 앱 평가 프레임워크. instrument_llama_index(instrument.get_dispatcher())로 트레이스 수집.
• Maxim AI: 에이전트 시뮬레이션·평가·옵저버빌리티. instrument_llamaindex(logger, debug=True).

대부분 Python 설치 명령과 간단한 초기화 코드면 연결이 끝나요.

레거시 원클릭 통합

CallbackManager 기반의 레거시 통합도 일부 남아 있어요 — OpenInference(set_global_handler("openinference")), TruEra TruLens, HoneyHive, PromptLayer, Langtrace, OpenLIT, AgentOps, 그리고 모든 LLM 입력/출력을 터미널에 출력하는 Simple(set_global_handler("simple")) 등이요. 이들은 새 instrumentation 모듈 기반이 아니라는 점을 유의하고, 가능하면 새 방식으로 대체하세요.

더 알아보기

• Callbacks Guide
• Instrumentation