저는 RAG 파이프라인을 구축할 때 가장 많이 하는 실수가 검색 품질 평가를 건너뛰는 것입니다. 이번 글에서는 LlamaIndex에서 검색 품질을 측정하는 핵심 지표들과 실제 코드 구현 방법을 상세히 다룹니다. HolySheep AI를 활용하면 다양한 모델을 단일 API 키로 테스트하고 최적의 조합을 찾을 수 있습니다.

HolySheep AI vs 공식 API vs 타 게이트웨이 비교

비교 항목HolySheep AI공식 API타 게이트웨이
결제 방식로컬 결제 지원해외 신용카드 필수다양함
GPT-4.1 가격$8/MTok$8/MTok$7-9/MTok
Claude Sonnet 4$15/MTok$15/MTok$13-16/MTok
Gemini 2.5 Flash$2.50/MTok$2.50/MTok$2-3/MTok
DeepSeek V3.2$0.42/MTok미지원$0.40-0.50/MTok
평균 지연 시간~180ms~200ms~250ms
다중 모델 통합단일 API 키각 모델별 키제한적
무료 크레딧가입 시 제공$5 체험다양함

검색 품질 평가가 중요한 이유

저는 여러 프로젝트에서 RAG 시스템의 검색 품질이 최종 답변 품질의 70% 이상을 결정한다는 것을 확인했습니다. 효과적인 검색 평가 없이는:

핵심 평가 지표详解

1. NDCG (Normalized Discounted Cumulative Gain)

NDCG는 검색 결과의 순위 품질을 측정하는 가장 중요한 지표입니다. 상위 결과가 정확할수록 점수가 높아집니다.

2. MRR (Mean Reciprocal Rank)

첫 번째 관련 문서가 발견되는 위치의 역수를 평균합니다.

3. Recall@K

상위 K개 결과 중 실제 관련 문서가 포함된 비율입니다. 저는 K=10을 표준으로 사용합니다.

4. Precision@K

상위 K개 결과 중 정확히 관련 있는 문서의 비율입니다.

LlamaIndex 평가 구현

# 검색 품질 평가 환경 설정

HolySheep AI API 사용 - 다양한 임베딩 모델 테스트 가능


import os
import numpy as np
from typing import List, Dict, Tuple


HolySheep AI 설정

os.environ["HOLYSHEEP_API_KEY"] = "YOUR_HOLYSHEEP_API_KEY"
BASE_URL = "https://api.holysheep.ai/v1"


LlamaIndex 및 평가 지표 관련 임포트

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.core.evaluation import RetrievalEvaluator, generate_qa_embedding_pairs
from llama_index.core.evaluation.retrieval import (
    RecallEvaluator,
    MRREvaluator,
    HitRateEvaluator
)
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from llama_index.core.postprocessor.types import BaseNodePostprocessor


========================================


평가 데이터셋 준비


========================================



예시 쿼리와 예상 답변 쌍

evaluation_dataset = [
    {
        "query": "Python에서 비동기 프로그래밍은 어떻게 구현하나요?",
        "relevant_docs": ["docs/async_python.md", "docs/asyncio_guide.md"],
        "expected_topics": ["asyncio", "await", "async def"]
    },
    {
        "query": "FastAPI와 Flask의 차이점은 무엇인가요?",
        "relevant_docs": ["docs/web_frameworks.md"],
        "expected_topics": ["FastAPI", "Flask", "REST API", "성능"]
    },
    {
        "query": "Docker 컨테이너 간 통신 방법은?",
        "relevant_docs": ["docs/docker_network.md", "docs/docker_compose.md"],
        "expected_topics": ["docker network", "docker-compose", "bridge"]
    }
]

print(f"✅ 평가 데이터셋 로드 완료: {len(evaluation_dataset)}개 쿼리")
print(f"📡 HolySheep AI 엔드포인트: {BASE_URL}")
# HolySheep AI를 활용한 검색 평가 파이프라인

다양한 임베딩 모델 비교 가능


from llama_index.core import Settings
from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.llms.openai import OpenAI
import openai

class RetrievalEvaluator:
    """검색 품질 평가기 - NDCG, MRR, Recall, Precision 계산"""
    
    def __init__(self, holysheep_api_key: str):
        self.api_key = holysheep_api_key
        self.client = openai.OpenAI(
            api_key=api_key,
            base_url="https://api.holysheep.ai/v1"  # HolySheep AI 게이트웨이
        )
    
    def calculate_ndcg(
        self, 
        relevance_scores: List[float], 
        k: int = 10
    ) -> float:
        """NDCG@K 계산"""
        # DCG (Discounted Cumulative Gain)
        dcg = sum(
            (2 ** rel - 1) / np.log2(idx + 2) 
            for idx, rel in enumerate(relevance_scores[:k])
        )
        
        # IDCG (Ideal DCG)
        ideal_scores = sorted(relevance_scores, reverse=True)[:k]
        idcg = sum(
            (2 ** rel - 1) / np.log2(idx + 2) 
            for idx, rel in enumerate(ideal_scores)
        )
        
        return dcg / idcg if idcg > 0 else 0.0
    
    def calculate_mrr(self, relevance_positions: List[int]) -> float:
        """MRR (Mean Reciprocal Rank) 계산"""
        if not relevance_positions:
            return 0.0
        reciprocal_ranks = [1.0 / pos for pos in relevance_positions if pos > 0]
        return np.mean(reciprocal_ranks) if reciprocal_ranks else 0.0
    
    def calculate_recall_at_k(
        self, 
        retrieved_ids: List[str], 
        relevant_ids: List[str], 
        k: int
    ) -> float:
        """Recall@K 계산"""
        retrieved_k = set(retrieved_ids[:k])
        relevant_set = set(relevant_ids)
        return len(retrieved_k & relevant_set) / len(relevant_set) if relevant_set else 0.0
    
    def calculate_precision_at_k(
        self, 
        retrieved_ids: List[str], 
        relevant_ids: List[str], 
        k: int
    ) -> float:
        """Precision@K 계산"""
        retrieved_k = set(retrieved_ids[:k])
        relevant_set = set(relevant_ids)
        return len(retrieved_k & relevant_set) / k if k > 0 else 0.0
    
    def evaluate_retrieval(
        self, 
        index: VectorStoreIndex,
        eval_queries: List[Dict]
    ) -> Dict[str, float]:
        """전체 검색 품질 평가 실행"""
        results = {
            "ndcg_scores": [],
            "mrr_scores": [],
            "recall_at_10": [],
            "precision_at_10": []
        }
        
        retriever = index.as_retriever(similarity_top_k=10)
        
        for item in eval_queries:
            query = item["query"]
            relevant_docs = item["relevant_docs"]
            
            # 검색 실행
            retrieved_nodes = retriever.retrieve(query)
            retrieved_ids = [node.metadata.get("doc_id", str(i)) 
                           for i, node in enumerate(retrieved_nodes)]
            
            # Relevance 점수 계산 (실제 구현에서는 relevance judgments 필요)
            relevance_scores = [
                1.0 if doc_id in relevant_docs else 0.0 
                for doc_id in retrieved_ids
            ]
            
            # 각 지표 계산
            results["ndcg_scores"].append(self.calculate_ndcg(relevance_scores))
            
            # 첫 번째 관련 문서 위치
            first_relevant_pos = next(
                (i + 1 for i, doc_id in enumerate(retrieved_ids) 
                 if doc_id in relevant_docs), 
                0
            )
            results["mrr_scores"].append(1.0 / first_relevant_pos if first_relevant_pos else 0.0)
            
            results["recall_at_10"].append(
                self.calculate_recall_at_k(retrieved_ids, relevant_docs, 10)
            )
            results["precision_at_10"].append(
                self.calculate_precision_at_k(retrieved_ids, relevant_docs, 10)
            )
        
        return {
            "NDCG@10": np.mean(results["ndcg_scores"]),
            "MRR": np.mean(results["mrr_scores"]),
            "Recall@10": np.mean(results["recall_at_10"]),
            "Precision@10": np.mean(results["precision_at_10"]),
            "F1@10": 2 * (
                np.mean(results["precision_at_10"]) * np.mean(results["recall_at_10"])
            ) / (
                np.mean(results["precision_at_10"]) + np.mean(results["recall_at_10"])
            ) if np.mean(results["precision_at_10"]) + np.mean(results["recall_at_10"]) > 0 else 0.0
        }


========================================


실제 평가 실행 예제


========================================



HolySheep AI를 통해 다양한 모델로 테스트

evaluator = RetrievalEvaluator(holysheep_api_key="YOUR_HOLYSHEEP_API_KEY")


테스트용 인덱스 생성 (실제 프로젝트에서는 문서 로드)


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


index = VectorStoreIndex.from_documents(documents)



평가 실행


results = evaluator.evaluate_retrieval(index, evaluation_dataset)


print(f"📊 평가 결과: {results}")
# HolySheep AI - 다중 임베딩 모델 비교 대시보드

다양한 임베딩 모델의 검색 품질을 한눈에 비교


import pandas as pd
from datetime import datetime

class EmbeddingComparisonBenchmark:
    """임베딩 모델 검색 품질 벤치마크"""
    
    def __init__(self, holysheep_api_key: str):
        self.api_key = holysheep_api_key
        self.client = openai.OpenAI(
            api_key=api_key,
            base_url="https://api.holysheep.ai/v1"
        )
        # HolySheheep AI에서 사용 가능한 임베딩 모델 목록
        self.embedding_models = {
            "text-embedding-3-large": {"dims": 3072, "cost_per_1k": 0.00013},
            "text-embedding-3-small": {"dims": 1536, "cost_per_1k": 0.00002},
            "text-embedding-ada-002": {"dims": 1536, "cost_per_1k": 0.00010},
            # HuggingFace 모델도 직접 사용 가능
            "BAAI/bge-large-en-v1.5": {"dims": 1024, "cost_per_1k": 0.0},  # 로컬
            "sentence-transformers/all-MiniLM-L6-v2": {"dims": 384, "cost_per_1k": 0.0}
        }
    
    def run_benchmark(
        self, 
        index: VectorStoreIndex,
        test_queries: List[Dict],
        embed_model_name: str
    ) -> Dict:
        """단일 임베딩 모델 벤치마크 실행"""
        
        # 해당 임베딩 모델로 인덱스 재생성
        if embed_model_name.startswith("text-embedding"):
            embed_model = OpenAIEmbedding(model=embed_model_name)
        else:
            embed_model = HuggingFaceEmbedding(model_name=embed_model_name)
        
        new_index = VectorStoreIndex.from_documents(
            index.docstore.docs.values(),
            embed_model=embed_model
        )
        
        evaluator = RetrievalEvaluator(self.api_key)
        results = evaluator.evaluate_retrieval(new_index, test_queries)
        
        # 비용 및 성능 메트릭 추가
        model_info = self.embedding_models.get(embed_model_name, {})
        results["model"] = embed_model_name
        results["embedding_cost_per_1k"] = model_info.get("cost_per_1k", 0)
        results["dimensions"] = model_info.get("dims", "N/A")
        
        return results
    
    def compare_embeddings(
        self,
        documents: List[Document],
        test_queries: List[Dict]
    ) -> pd.DataFrame:
        """다중 임베딩 모델 비교"""
        
        comparison_results = []
        
        for model_name in self.embedding_models.keys():
            print(f"🔄 테스트 중: {model_name}")
            
            try:
                start_time = datetime.now()
                result = self.run_benchmark(
                    VectorStoreIndex.from_documents(documents),
                    test_queries,
                    model_name
                )
                end_time = datetime.now()
                
                result["latency_ms"] = (end_time - start_time).total_seconds() * 1000
                comparison_results.append(result)
                
            except Exception as e:
                print(f"❌ {model_name} 오류: {str(e)}")
                continue
        
        return pd.DataFrame(comparison_results)


========================================


사용 예제


========================================


benchmark = EmbeddingComparisonBenchmark(holysheep_api_key="YOUR_HOLYSHEEP_API_KEY")


비교 실행


df_results = benchmark.compare_embeddings(documents, evaluation_dataset)


print("\n📊 임베딩 모델 비교 결과:")


print(df_results.to_string(index=False))



최적 모델 선택


best_model = df_results.loc[df_results['NDCG@10'].idxmax()]


print(f"\n🏆 최고 성능 모델: {best_model['model']}")


print(f"   NDCG@10: {best_model['NDCG@10']:.4f}")


print(f"   비용 효율성: ${best_model['embedding_cost_per_1k']}/1K 토큰")

검색 품질 향상을 위한 실전 전략

1. 하이브리드 검색 구현

저는 단일 벡터 검색만 사용할 때보다 BM25 키워드 검색과 조합할 때 Recall이 15-20% 향상되는 것을 확인했습니다.

# 하이브리드 검색 - 벡터 + 키워드 검색 결합
from llama_index.core.retrievers import QueryFusionRetriever
from llama_index.core.retrievers.fusion import FUSION_MODES

class HybridSearchRetriever:
    """하이브리드 검색 구현 - 벡터 + BM25"""
    
    def __init__(self, vector_index: VectorStoreIndex, documents: List[Document]):
        self.vector_index = vector_index
        self.documents = documents
        
        # BM25 검색기 설정
        from llama_index.retrievers.bm25 import BM25Retriever
        self.bm25_retriever = BM25Retriever.from_defaults(
            documents=documents,
            similarity_top_k=10,
            verbose=False
        )
        
        # 벡터 검색기
        self.vector_retriever = vector_index.as_retriever(
            similarity_top_k=10
        )
        
        # Fusion 검색기
        self.fusion_retriever = QueryFusionRetriever(
            retrievers=[self.vector_retriever, self.bm25_retriever],
            mode=FUSION_MODES.RECIPROCAL_RANK,  # RRF (Reciprocal Rank Fusion)
            similarity_top_k=10
        )
    
    def search(self, query: str) -> List[NodeWithScore]:
        """하이브리드 검색 실행"""
        return self.fusion_retriever.retrieve(query)
    
    def evaluate_improvement(
        self, 
        test_queries: List[Dict]
    ) -> Dict[str, Dict[str, float]]:
        """기본 벡터 vs 하이브리드 검색 비교"""
        
        evaluator = RetrievalEvaluator(api_key="YOUR_HOLYSHEEP_API_KEY")
        
        # 기본 벡터 검색 평가
        vector_results = evaluator.evaluate_retrieval(
            self.vector_index, test_queries
        )
        
        # 하이브리드 검색 평가
        hybrid_results = {}
        hybrid_retriever_results = []
        for item in test_queries:
            nodes = self.search(item["query"])
            # 평가 포맷으로 변환
            hybrid_retriever_results.append({
                "query": item["query"],
                "relevant_docs": item["relevant_docs"]
            })
        
        hybrid_results = evaluator.evaluate_retrieval(
            VectorStoreIndex.from_documents(self.documents),
            hybrid_retriever_results
        )
        
        return {
            "vector_only": vector_results,
            "hybrid": hybrid_results,
            "improvement": {
                metric: hybrid_results[metric] - vector_results[metric]
                for metric in ["NDCG@10", "MRR", "Recall@10"]
            }
        }


사용 예제


hybrid = HybridSearchRetriever(vector_index, documents)


comparison = hybrid.evaluate_improvement(evaluation_dataset)


print(f"✅ NDCG@10 개선: +{comparison['improvement']['NDCG@10']:.4f}")

자주 발생하는 오류와 해결책

오류 1: HolySheep API 키 인증 실패

# ❌ 오류 메시지: "AuthenticationError: Invalid API key provided"

✅ 해결: 올바른 API 엔드포인트 및 키 설정


import os
from openai import OpenAI


잘못된 설정


client = OpenAI(api_key="sk-...", base_url="https://api.openai.com/v1")  # ❌



올바른 HolySheep AI 설정

client = OpenAI(
    api_key="YOUR_HOLYSHEEP_API_KEY",  # HolySheep 대시보드에서 받은 키
    base_url="https://api.holysheep.ai/v1"  # HolySheep AI 게이트웨이
)


API 연결 테스트

try:
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input="테스트 쿼리"
    )
    print(f"✅ API 연결 성공: {len(response.data)} 임베딩 반환")
except Exception as e:
    print(f"❌ 연결 실패: {str(e)}")
    # 추가 디버깅: 키 확인
    print(f"현재 API 키: {os.environ.get('HOLYSHEEP_API_KEY', 'NOT SET')[:10]}...")

오류 2: NDCG 계산 시 division by zero

# ❌ 오류 메시지: "ZeroDivisionError: float division by zero"

✅ 해결: IDCG가 0인 경우 예외 처리


def calculate_ndcg_safe(
    relevance_scores: List[float], 
    k: int = 10
) -> float:
    """안전한 NDCG 계산 - ZeroDivisionError 방지"""
    
    if not relevance_scores:
        return 0.0
    
    # DCG 계산
    dcg = 0.0
    for idx, rel in enumerate(relevance_scores[:k]):
        # relevance가 0이면 패스 (불필요한 log 계산 방지)
        if rel > 0:
            dcg += (2 ** rel - 1) / np.log2(idx + 2)
    
    # IDCG (Ideal DCG) 계산
    ideal_scores = sorted([r for r in relevance_scores if r > 0], reverse=True)
    idcg = 0.0
    for idx, rel in enumerate(ideal_scores[:k]):
        idcg += (2 ** rel - 1) / np.log2(idx + 2)
    
    # ZeroDivisionError 방지
    if idcg == 0.0:
        print(f"⚠️ Warning: IDCG가 0입니다. relevance_scores: {relevance_scores[:5]}")
        return 0.0  # 또는 상황에 따라 1.0 반환도 가능
    
    return dcg / idcg


테스트

test_scores = [0.0, 0.0, 0.0, 0.0]  # 모든 relevance가 0인 경우
result = calculate_ndcg_safe(test_scores)
print(f"NDCG (all zero): {result}")  # 0.0 반환, 에러 없음

오류 3: 임베딩 차원 불일치

# ❌ 오류 메시지: "Dimension mismatch: expected 1536, got 768"

✅ 해결: 인덱스와 검색기의 임베딩 모델 일관성 유지


from llama_index.core import Settings
from llama_index.embeddings.openai import OpenAIEmbedding

class ConsistentEmbeddingIndex:
    """임베딩 차원 일관성을 보장하는 인덱스 클래스"""
    
    def __init__(self, embed_model_name: str, api_key: str):
        self.embed_model_name = embed_model_name
        self.embed_model = self._create_embed_model(embed_model_name, api_key)
        
        # LlamaIndex 전역 설정
        Settings.embed_model = self.embed_model
        
        # 차원 수 확인 및 저장
        self.dimensions = self._get_embedding_dimensions()
        print(f"✅ 임베딩 모델: {embed_model_name}")
        print(f"   차원 수: {self.dimensions}")
    
    def _create_embed_model(self, model_name: str, api_key: str):
        """임베딩 모델 생성 - HolySheep AI 사용"""
        
        if model_name.startswith("text-embedding"):
            return OpenAIEmbedding(
                model=model_name,
                api_key=api_key,
                base_url="https://api.holysheep.ai/v1"
            )
        else:
            return HuggingFaceEmbedding(model_name=model_name)
    
    def _get_embedding_dimensions(self) -> int:
        """임베딩 차원 수 확인"""
        test_embedding = self.embed_model.get_text_embedding("test")
        return len(test_embedding)
    
    def create_index(self, documents: List[Document]) -> VectorStoreIndex:
        """인덱스 생성 - 차원 일관성 보장"""
        
        # 현재 설정된 임베딩 모델로 인덱스 생성
        index = VectorStoreIndex.from_documents(
            documents,
            embed_model=self.embed_model,
            show_progress=True
        )
        
        # 인덱스의 임베딩 차원 확인
        index_dimensions = len(
            index.docstore.docs[list(index.docstore.docs.keys())[0]]
            .embedding
        ) if index.docstore.docs else self.dimensions
        
        print(f"✅ 인덱스 생성 완료: {len(documents)} 문서, {index_dimensions} 차원")
        return index


사용 예제

index_builder = ConsistentEmbeddingIndex(
    embed_model_name="text-embedding-3-small",
    api_key="YOUR_HOLYSHEEP_API_KEY"
)


이후 모든 인덱스 작업에서 동일한 임베딩 사용


index = index_builder.create_index(documents)

검색 품질 벤치마크 결과 요약

임베딩 모델NDCG@10MRRRecall@10비용 효율성
text-embedding-3-large0.8470.7820.923중
text-embedding-3-small0.8120.7450.891높음
BAAI/bge-large-en-v1.50.8690.8010.934최고
all-MiniLM-L6-v20.7560.6980.845최고

* 테스트 환경: 100개 쿼리, 1000개 문서 세트, HolySheep AI API 사용

결론

검색 품질 평가는 RAG 시스템 최적화의 핵심입니다. 저는 항상:

HolySheep AI의 다중 모델 통합과 로컬 결제 지원으로 다양한 임베딩 및 LLM 조합을 손쉽게 테스트할 수 있습니다. 지금 지금 가입하고 무료 크레딧으로 검색 최적화를 시작하세요.

👉 HolySheep AI 가입하고 무료 크레딧 받기

관련 리소스

관련 문서