LlamaIndex

LlamaIndex

복잡한 데이터에서 지식 에이전트를 만들 때 LlamaIndex를 쓴다면, 몇 줄의 코드로 추적·평가를 시작할 수 있어요. Confident AI는 매 에이전트 실행, 검색, 도구 호출을 Observatory에 전체 계층으로 보여줘서, 에이전트가 무엇을 검색했고 어떤 도구를 골랐으며 각 모델 호출이 얼마나 들었는지 한눈에 볼 수 있게 해 줍니다.

출처: 문서

본문

개요

LlamaIndex는 복잡한 데이터에서 지식 에이전트를 쉽게 만들게 해 주는 LLM 프레임워크입니다. Confident AI는 몇 줄의 코드로 LlamaIndex 에이전트를 추적·평가할 수 있게 해 줘요 — 모든 에이전트 실행, 검색, 도구 호출이 Observatory에 전체 계층으로 나타나죠. 에이전트가 무엇을 검색했고, 어떤 도구를 골랐고, 각 모델 호출이 얼마나 들었는지 볼 수 있어요.

LlamaIndex 스팬은 실행의 구조 — 에이전트, 워크플로우, 단계, 검색, 도구 — 를 나타냅니다. 각 단계 안의 OpenAI(또는 Anthropic, Gemini, Bedrock) 호출은 여전히 LLM 스팬으로, 메시지·모델 이름·토큰 사용량과 함께 나타나요. 프로바이더 통합이 포착합니다. LlamaIndex 자체의 LLM 이벤트는 건너뛰어서 각 모델 호출이 정확히 한 번만 보여요.

Runtime Requirements Setup
Python Python 3.10+, llama-index-core 0.14.x (tested with 0.14.24) Call init() before running the agent or workflow
TypeScript Not supported —

자동 계측

EU 리전 사용자는 OTEL 엔드포인트를 EU 버전으로 설정하세요. 그렇지 않으면 트레이스가 우리 US 서버로 보내집니다.

export CONFIDENT_OTEL_ENDPOINT="https://eu.otel.confident-ai.com/v1/traces"

의존성 설치

confident-trace를 LlamaIndex 및 에이전트가 쓰는 모델 프로바이더 패키지와 함께 설치하세요(아래 예는 OpenAI를 사용).

pip install confident-trace llama-index-core llama-index-llms-openai

Confident AI 키 설정

Confident AI Project API key를 받아 환경 변수로 설정하거나, init()에 직접 전달하세요.

export CONFIDENT_API_KEY="<your-confident-api-key>"
export OPENAI_API_KEY="<your-openai-key>"

from confident_trace import init

init(api_key="<your-confident-api-key>")

LlamaIndex 계측

시작 시, 에이전트를 정의·실행하기 전에 init()을 한 번 호출하세요. 그 뒤의 모든 LlamaIndex 호출이 자동으로 추적되어 Confident AI로 보내져요 — 평소의 agent.run 호출은 그대로 두면 됩니다.

import asyncio

from confident_trace import init, shutdown
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.core.tools import FunctionTool
from llama_index.llms.openai import OpenAI


def multiply(a: float, b: float) -> float:
    """Useful for multiplying two numbers."""
    return a * b


async def main():
    init()
    try:
        agent = FunctionAgent(
            name="assistant",
            llm=OpenAI(model="gpt-4o-mini"),
            tools=[FunctionTool.from_defaults(multiply)],
            system_prompt="You are a helpful assistant that can perform calculations.",
        )
        print(await agent.run("What is 3 * 12?"))
    finally:
        shutdown()


if __name__ == "__main__":
    asyncio.run(main())

init()은 명시적 스팬 ID와 부모를 보고하는 LlamaIndex의 계측 디스패처를 구독합니다. 그 순간부터 모든 LlamaIndex 스팬·이벤트가 계층까지 보존된 채 자동으로 포착됩니다 — 다른 코드 변경은 필요 없어요.

한 번 초기화하고, 한 번 종료하세요. 장기 실행 서버에서는 시작 시 init()을, 정상 종료 시 활성 에이전트 작업이 끝난 뒤 shutdown()을 호출하세요 — 요청마다 하지 마세요. 한 번 초기화를 참고하세요.

LlamaIndex 실행

스크립트를 실행해 에이전트를 돌려 보세요.

python main.py

완료 ✅. Confident AI 프로젝트에서 Observatory를 열어 트레이스와 자식 스팬을 확인하세요.

트레이스가 안 보이면, 거의 항상 프로그램이 트레이스를 보낼 기회가 생기기 전에 종료됐기 때문이에요. 종료 전에 반드시 shutdown()(장기 실행 프로세스에선 flush())을 호출하세요 — 트러블슈팅 페이지를 참고하세요.

무엇이 포착되나

LlamaIndex 에이전트·워크플로우 실행은 계층이 그대로 보존된 채 내보내져서, 진입점에서 시작해 단계·검색·모델 호출·도구를 따라갈 수 있어요.

  • 에이전트·워크플로우 실행 — 작업 이름, 타이밍, 상태, 단계 사이의 부모-자식 관계
  • 모델 호출 — 메시지, 모델 상세, 도구 요청, 완료 사유, 토큰 사용량
  • 도구 호출 — 도구 이름과 그 입출력
  • 검색·워크플로우 단계 — LlamaIndex가 요청 처리 중 보고하는 중간 작업
  • 커스텀 스팬 — 작업 안에서 만든 커스텀 애플리케이션 스팬이 그 아래에 중첩되어 유지

포착되는 입력, 출력, 메시지, 검색된 콘텐츠는 콘텐츠 정책을 따릅니다.

모델 스팬은 에이전트의 LLM이 지원되는 프로바이더 SDK를 거칠 때만 나타나요. 그 SDK를 우회하는 커스텀·로컬 모델 래퍼는 에이전트 구조만 보여주고 LLM 스팬은 없습니다 — 지원되는 프로바이더를 쓰거나, 그 호출을 명시적으로 계측하세요. 임베딩 호출은 추적되지 않아요.

트레이스 스팬 속성 설정

호출이 시작되기 전에 아는 속성을 추가하려면 트레이스 컨텍스트를 사용하세요. 추가 스팬은 만들지 않아요. agent.run()이 시작한 트레이스가 태그, 메타데이터, 사용자 ID, 고객 ID를 상속받습니다.

from confident_trace import init, trace_context

init()

async with trace_context(
    tags=["support"],
    metadata={"release": "2026-09"},
    user_id="user-42",
    customer_id="customer-7",
):
    result = await agent.run("Explain OpenTelemetry in one sentence.")

각 ID와 함께 선택적 표시 이름을 설정하려면 사용자와 고객을, 지원되는 모든 트레이스 속성과 갱신 동작은 트레이스 컨텍스트를 참고하세요.

다중 턴 계측

LlamaIndex 엔트리포인트 호출 하나가 이미 하나의 대화 턴일 때는 turn()이 필요 없어요 — 통합이 그 턴의 트레이스를 자동으로 만들어 주거든요. 경계를 직접 정의하고 싶을 때, 예를 들어 두 번의 연속 LlamaIndex 호출을 하나의 턴으로 묶고 싶을 때 turn()을 사용하세요. 이후 턴에서 같은 스레드 ID를 재사용해 하나의 대화로 묶으면 돼요.

from confident_trace import init, turn

init()

async with turn("support-turn", thread_id="chat-42"):
    context = await agent.run("Find the relevant account details.")
    answer = await agent.run(f"Summarize these details: {context}")

스레드 입출력, 턴 ID, 사용자 ID는 스레드를 참고하세요.

LlamaIndex 계측 비활성화

특정 통합만 활성화하려면 init()에 통합 식별자 목록을 전달하세요. LlamaIndex의 식별자는 Python에서 "llamaindex"이고, 이를 빼면 이 통합이 비활성화돼요. 빈 목록은 모든 자동 계측을 비활성화합니다.

from confident_trace import init
init(instrumentations=())
# Use ("llamaindex",) to opt in; omit "llamaindex" to disable it.

이렇게 하면 Confident AI의 자동 계측이 꺼지고, 초기화 이후의 호출은 이 통합으로 계측되지 않아요.

다음 단계

에이전트를 추적했으니, 더 깊이 들어가 볼까요.

Online Evals

트레이스와 스팬이 Confident AI로 수집되는 실시간으로 평가를 돌려 에이전트 품질을 모니터링하세요.

Threads

같은 대화의 에이전트 실행을 스레드로 묶고, 전체 대화를 하나의 단위로 평가하세요.

더 알아보기

  • OpenAI — 공식 OpenAI 클라이언트 추적
  • OpenInference — OpenInference 계측기로 스팬 만들기
  • Online Evals — 실시간 트레이스·스팬 평가