LLM 어댑터: 여러 구조화 출력 백엔드 사용하기

LLM 어댑터: 여러 구조화 출력 백엔드 사용하기 (LLM Adapters: Using Multiple Structured Output Backends)

Ragas는 어댑터 패턴을 통해 여러 구조화 출력 백엔드를 지원해요. 이 가이드는 LLM 프로바이더마다 다른 어댑터를 사용하는 방법을 설명해요. 프로바이더에 맞는 어댑터를 자동으로 골라주기 때문에 대부분은 별도 설정 없이 바로 사용할 수 있어요.

출처: 문서

본문

Ragas는 여러 LLM 프로바이더의 구조화 출력을 처리하기 위해 어댑터를 사용해요.

• Instructor 어댑터: OpenAI, Anthropic, Azure, Groq, Mistral, Cohere 등 많은 프로바이더와 함께 작동해요
• LiteLLM 어댑터: LiteLLM이 지원하는 100개 이상의 모든 프로바이더(Gemini, Ollama, vLLM, Bedrock 등)와 작동해요

프레임워크가 프로바이더에 가장 적합한 어댑터를 자동으로 선택하지만, 직접 명시적으로 선택할 수도 있어요.

퀵 스타트

자동 어댑터 선택 (권장)

Ragas가 최적의 어댑터를 자동 감지하도록 해요.

from ragas.llms import llm_factory
from openai import OpenAI

# OpenAI용 - 자동으로 Instructor 어댑터 사용
client = OpenAI(api_key="...")
llm = llm_factory("gpt-4o-mini", client=client)

from ragas.llms import llm_factory
import google.generativeai as genai

# Gemini용 - 자동으로 LiteLLM 어댑터 사용
genai.configure(api_key="...")
client = genai.GenerativeModel("gemini-2.0-flash")
llm = llm_factory("gemini-2.0-flash", provider="google", client=client)

명시적 어댑터 선택

더 많은 제어가 필요하다면 특정 어댑터를 선택해요.

from ragas.llms import llm_factory

# Instructor 어댑터 강제 사용
llm = llm_factory("gpt-4o", client=client, adapter="instructor")

# LiteLLM 어댑터 강제 사용
llm = llm_factory("gemini-2.0-flash", client=client, adapter="litellm")

자동 감지 로직

adapter="auto"(기본값)일 때 Ragas는 이 로직을 사용해요.

1. 클라이언트 유형 확인: 클라이언트가 litellm 모듈에서 온 것이면 → LiteLLM 어댑터 사용
2. 프로바이더 확인: 프로바이더가 google 또는 gemini이면 → LiteLLM 어댑터 사용
3. 기본값: 그 외의 모든 경우 Instructor 어댑터 사용

from ragas.llms.adapters import auto_detect_adapter

# 어떤 어댑터가 사용될지 확인
adapter_name = auto_detect_adapter(client, "google")
print(adapter_name)  # Output: "litellm"

adapter_name = auto_detect_adapter(client, "openai")
print(adapter_name)  # Output: "instructor"

프로바이더별 예제

OpenAI

from openai import OpenAI
from ragas.llms import llm_factory

client = OpenAI(api_key="your-key")
llm = llm_factory("gpt-4o", client=client)
# 자동으로 Instructor 어댑터 사용

Anthropic Claude

from anthropic import Anthropic
from ragas.llms import llm_factory

client = Anthropic(api_key="your-key")
llm = llm_factory("claude-3-sonnet", provider="anthropic", client=client)
# 자동으로 Instructor 어댑터 사용

Google Gemini (google-generativeai 사용 - 권장)

import google.generativeai as genai
from ragas.llms import llm_factory

genai.configure(api_key="your-key")
client = genai.GenerativeModel("gemini-2.0-flash")
llm = llm_factory("gemini-2.0-flash", provider="google", client=client)
# google 프로바이더는 자동으로 LiteLLM 어댑터 사용

Google Gemini (LiteLLM Proxy 사용 - 고급)

from openai import OpenAI
from ragas.llms import llm_factory

# 다음 실행 필요: litellm --model gemini-2.0-flash
client = OpenAI(
    api_key="anything",
    base_url="http://0.0.0.0:4000"  # LiteLLM proxy endpoint
)
llm = llm_factory("gemini-2.0-flash", client=client, adapter="litellm")
# 명시적으로 LiteLLM 어댑터 사용

로컬 모델 (Ollama)

from openai import OpenAI
from ragas.llms import llm_factory

# Ollama는 OpenAI 호환 API를 노출해요
client = OpenAI(
    api_key="ollama",
    base_url="http://localhost:11434/v1"
)
llm = llm_factory("mistral", provider="openai", client=client)
# Instructor 어댑터 사용

AWS Bedrock

from openai import OpenAI
from ragas.llms import llm_factory

# Bedrock에는 LiteLLM proxy 사용
# 참고: 먼저 Bedrock 자격 증명으로 LiteLLM을 설정해요
client = OpenAI(
    api_key="",  # Bedrock uses IAM auth
    base_url="http://0.0.0.0:4000"  # LiteLLM proxy endpoint
)
llm = llm_factory("claude-3-sonnet", client=client, adapter="litellm")

Groq

from groq import Groq
from ragas.llms import llm_factory

client = Groq(api_key="your-key")
llm = llm_factory("mixtral-8x7b", provider="groq", client=client)
# 자동으로 Instructor 어댑터 사용

Mistral

from mistralai import Mistral
from ragas.llms import llm_factory

client = Mistral(api_key="your-key")
llm = llm_factory("mistral-large", provider="mistral", client=client)
# 자동으로 Instructor 어댑터 사용

Cohere

from cohere import Cohere
from ragas.llms import llm_factory

client = Cohere(api_key="your-key")
llm = llm_factory("command-r-plus", provider="cohere", client=client)
# 자동으로 Instructor 어댑터 사용

어댑터 선택 가이드

필요에 따라 어댑터를 선택해요.

다음과 같은 경우 Instructor 어댑터 사용:

• OpenAI, Anthropic, Azure, Groq, Mistral, Cohere 사용 중
• 프로바이더가 Instructor를 네이티브로 지원
• 가장 안정적이고 검증된 옵션을 원함
• 프로바이더가 특별한 처리를 요구하지 않음

다음과 같은 경우 LiteLLM 어댑터 사용:

• Google Gemini 사용 중
• 로컬 모델(Ollama, vLLM 등) 사용 중
• 100개 이상의 옵션이 있는 프로바이더(Bedrock 등) 사용 중
• 최대한의 프로바이더 호환성이 필요함
• 자동 감지가 프로바이더에 대해 이 어댑터를 선택

어댑터 직접 사용하기

사용 가능한 어댑터 확인

from ragas.llms.adapters import ADAPTERS

print(ADAPTERS)
# Output: {
#     "instructor": InstructorAdapter(),
#     "litellm": LiteLLMAdapter()
# }

특정 어댑터 가져오기

from ragas.llms.adapters import get_adapter

instructor = get_adapter("instructor")
litellm = get_adapter("litellm")

# 어댑터를 직접 사용해 LLM 생성
llm = instructor.create_llm(client, "gpt-4o", "openai")

고급 사용법

모델 인자

모든 어댑터는 동일한 모델 인자를 지원해요.

llm = llm_factory(
    "gpt-4o",
    client=client,
    temperature=0.7,
    max_tokens=2048,
    top_p=0.9,
)

시스템 프롬프트

두 어댑터 모두 특정 지침이 필요한 모델을 위한 시스템 프롬프트를 지원해요.

llm = llm_factory(
    "gpt-4o",
    client=client,
    system_prompt="You are a helpful assistant that evaluates RAG systems."
)

시스템 프롬프트는 다음과 같은 경우 유용해요:

• LLM에 특정 동작 지침이 필요한 경우
• 커스텀 시스템 프롬프트가 있는 파인튜닝 모델을 사용하는 경우
• 모든 메트릭에서 평가 스타일을 일관되게 유지하려는 경우

시스템 프롬프트는 모든 LLM 호출에 시스템 메시지로 앞에 붙어서 전달돼요.

비동기 지원

두 어댑터 모두 비동기 연산을 지원해요.

from openai import AsyncOpenAI
from ragas.llms import llm_factory

async_client = AsyncOpenAI(api_key="...")
llm = llm_factory("gpt-4o", client=async_client)

# 비동기 생성
response = await llm.agenerate(prompt, ResponseModel)

LiteLLM으로 커스텀 프로바이더 사용

LiteLLM은 Instructor가 다루는 것 이상의 많은 프로바이더를 지원해요. LiteLLM proxy 방식을 사용해요.

from openai import OpenAI
from ragas.llms import llm_factory

# 먼저 LiteLLM proxy 설정:
# litellm --model grok-1  (for xAI)
# litellm --model deepseek-chat  (for DeepSeek)
# etc.

client = OpenAI(
    api_key="your-provider-api-key",
    base_url="http://0.0.0.0:4000"  # LiteLLM proxy endpoint
)

# xAI Grok
llm = llm_factory("grok-1", client=client, adapter="litellm")

# DeepSeek
llm = llm_factory("deepseek-chat", client=client, adapter="litellm")

# Together AI
llm = llm_factory("mistral-7b", client=client, adapter="litellm")

완전한 평가 예제

from datasets import Dataset
from ragas import evaluate
from ragas.llms import llm_factory
from ragas.metrics import (
    ContextPrecision,
    ContextRecall,
    Faithfulness,
    AnswerCorrectness,
)

# 프로바이더로 LLM 초기화
import google.generativeai as genai
genai.configure(api_key="...")
client = genai.GenerativeModel("gemini-2.0-flash")
llm = llm_factory("gemini-2.0-flash", provider="google", client=client)

# 평가 데이터셋 생성
data = {
    "question": ["What is the capital of France?"],
    "answer": ["Paris"],
    "contexts": [["France is in Europe. Paris is its capital."]],
    "ground_truth": ["Paris"]
}
dataset = Dataset.from_dict(data)

# 메트릭 정의
metrics = [
    ContextPrecision(llm=llm),
    ContextRecall(llm=llm),
    Faithfulness(llm=llm),
    AnswerCorrectness(llm=llm),
]

# 평가
results = evaluate(dataset, metrics=metrics)
print(results)

문제 해결 (Troubleshooting)

"Unknown adapter: xyz"

유효한 어댑터 이름을 사용하고 있는지 확인해요.

# 유효: "instructor" 또는 "litellm"
llm = llm_factory("model", client=client, adapter="instructor")

# 무효: "dspy" (아직 구현되지 않음)
# llm = llm_factory("model", client=client, adapter="dspy")  # Error!

"Failed to initialize provider client"

다음을 확인해요:

1. 클라이언트가 제대로 초기화되었는지
2. API 키가 유효한지
3. 프로바이더가 어댑터에서 지원되는지

# 어댑터가 프로바이더를 처리할 수 있는지 확인
from ragas.llms.adapters import auto_detect_adapter
adapter = auto_detect_adapter(client, "my-provider")
print(f"Will use: {adapter}")

어댑터 불일치

자동 감지가 대부분의 경우를 처리하지만, 명시적 선택이 도움이 될 수 있어요.

# 자동 감지가 잘못된 어댑터를 선택하면:
llm = llm_factory(
    "model",
    provider="provider-name",
    client=client,
    adapter="litellm"  # 명시적 재정의
)

마이그레이션 가이드

텍스트 전용에서 구조화 출력으로

텍스트 전용 LLM 사용에서 업그레이드한다면:

# 이전 (deprecated)
# from ragas.llms import LangchainLLMWrapper
# llm = LangchainLLMWrapper(langchain_llm)

# 이후 (새 방식)
from ragas.llms import llm_factory
llm = llm_factory("gpt-4o", client=client)

프로바이더 전환

OpenAI에서 Gemini로 전환하려면:

# 이전: OpenAI
from openai import OpenAI
client = OpenAI(api_key="...")
llm = llm_factory("gpt-4o", client=client)

# 이후: Gemini (비슷한 코드 패턴!)
import google.generativeai as genai
genai.configure(api_key="...")
client = genai.GenerativeModel("gemini-2.0-flash")
llm = llm_factory("gemini-2.0-flash", provider="google", client=client)
# google 프로바이더에서는 자동으로 LiteLLM 어댑터로 전환

더 알아보기 (Learn more)

• Gemini 통합 가이드 - 상세 Gemini 설정
• LLM Factory 레퍼런스 - 완전한 API 레퍼런스
• 메트릭 문서 - LLM과 함께 메트릭 사용