Google Gemini 통합 가이드

이 가이드는 Google의 Gemini 모델을 Ragas와 함께 설정하고 평가에 사용하는 방법을 다뤄요. Ragas는 자동 어댑터 선택과 함께 Google Gemini 모델을 지원해요. 프레임워크는 새로운 google-genai SDK(권장)와 레거시 google-generativeai SDK 모두에서 동작해요.

출처: 문서

본문

설정

사전 요구사항

Gemini API 접근이 가능한 Google API 키
Python 3.8+
Ragas 설치됨

설치

필요한 의존성을 설치해요.

# Recommended: New Google GenAI SDK
pip install ragas google-genai

# Legacy (deprecated, support ends Aug 2025)
pip install ragas google-generativeai

구성

옵션 1: 새 Google GenAI SDK 사용(권장)

새 google-genai SDK가 권장 방식이에요.

import os
from google import genai
from ragas.llms import llm_factory

# Create client with API key
client = genai.Client(api_key=os.environ.get("GOOGLE_API_KEY"))

# Create LLM - adapter is auto-detected for google provider
llm = llm_factory(
    "gemini-2.0-flash",
    provider="google",
    client=client
)

옵션 2: 레거시 SDK 사용(폐기됨)

옛 google-generativeai SDK는 여전히 동작하지만 폐기됐어요(지원은 2025년 8월 종료).

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

# Configure with your API key
genai.configure(api_key=os.environ.get("GOOGLE_API_KEY"))

# Create client
client = genai.GenerativeModel("gemini-2.0-flash")

# Create LLM
llm = llm_factory(
    "gemini-2.0-flash",
    provider="google",
    client=client
)

옵션 3: LiteLLM 프록시 사용(고급)

LiteLLM의 프록시 기능이 필요한 고급 사용 사례라면, 먼저 LiteLLM 프록시 서버를 설정한 뒤 다음과 같이 사용해요.

import os
from openai import OpenAI
from ragas.llms import llm_factory

# Requires running: litellm --model gemini-2.0-flash
client = OpenAI(
    api_key="anything",
    base_url="http://0.0.0.0:4000"  # LiteLLM proxy endpoint
)

# Create LLM with explicit adapter selection
llm = llm_factory("gemini-2.0-flash", client=client, adapter="litellm")

지원 모델

Ragas는 모든 Gemini 모델과 함께 동작해요.

최신 : gemini-2.0-flash (권장)
1.5 시리즈 : gemini-1.5-pro, gemini-1.5-flash
1.0 시리즈 : gemini-1.0-pro

최신 모델과 가격은 Google AI Studio 에서 확인하세요.

임베딩 구성

Ragas 메트릭은 두 범주로 나뉘어요.

LLM 전용 메트릭(임베딩 불필요):
- ContextPrecision
- ContextRecall
- Faithfulness
- AspectCritic
임베딩 의존 메트릭(임베딩 필요):
- AnswerCorrectness
- AnswerRelevancy
- AnswerSimilarity
- SemanticSimilarity
- ContextEntityRecall

자동 프로바이더 매칭

Ragas를 Gemini와 함께 사용하면 임베딩 프로바이더가 LLM 프로바이더에 자동으로 매칭돼요. Gemini LLM을 제공하면 Ragas는 기본적으로 Google 임베딩을 사용해요. OpenAI API 키가 필요 없어요.

옵션 1: 기본 임베딩(권장)

LLM에 기반해 Ragas가 올바른 임베딩을 자동 선택하게 하세요.

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

# Initialize Gemini client (new SDK)
client = genai.Client(api_key=os.environ.get("GOOGLE_API_KEY"))
llm = llm_factory("gemini-2.0-flash", provider="google", client=client)

# Create sample evaluation data
data = {
    "question": ["What is the capital of France?"],
    "answer": ["Paris is the capital of France."],
    "contexts": [["France is a country in Western Europe. Paris is its capital."]],
    "ground_truth": ["Paris"]
}

dataset = Dataset.from_dict(data)

# Define metrics - embeddings are auto-configured for Google
metrics = [
    ContextPrecision(llm=llm),
    ContextRecall(llm=llm),
    Faithfulness(llm=llm),
    AnswerCorrectness(llm=llm)  # Uses Google embeddings automatically
]

# Run evaluation
results = evaluate(dataset, metrics=metrics)
print(results)

옵션 2: 명시적 임베딩

임베딩을 명시적으로 제어하려면 별도로 만들 수 있어요. Google 임베딩은 여러 구성 옵션과 함께 동작해요.

import os
from google import genai
from ragas.llms import llm_factory
from ragas.embeddings import GoogleEmbeddings
from ragas.embeddings.base import embedding_factory
from datasets import Dataset
from ragas import evaluate
from ragas.metrics import AnswerCorrectness, ContextPrecision, ContextRecall, Faithfulness

# Initialize Gemini client (new SDK)
client = genai.Client(api_key=os.environ.get("GOOGLE_API_KEY"))
llm = llm_factory("gemini-2.0-flash", provider="google", client=client)

# Initialize Google embeddings (multiple options):

# Option A: Using the same client (recommended for new SDK)
embeddings = GoogleEmbeddings(client=client, model="gemini-embedding-001")

# Option B: Using embedding factory
embeddings = embedding_factory("google", model="gemini-embedding-001")

# Option C: Auto-import (creates client automatically)
embeddings = GoogleEmbeddings(model="gemini-embedding-001")

# Create sample evaluation data
data = {
    "question": ["What is the capital of France?"],
    "answer": ["Paris is the capital of France."],
    "contexts": [["France is a country in Western Europe. Paris is its capital."]],
    "ground_truth": ["Paris"]
}

dataset = Dataset.from_dict(data)

# Define metrics with explicit embeddings
metrics = [
    ContextPrecision(llm=llm),
    ContextRecall(llm=llm),
    Faithfulness(llm=llm),
    AnswerCorrectness(llm=llm, embeddings=embeddings)
]

# Run evaluation
results = evaluate(dataset, metrics=metrics)
print(results)

예시: 완전한 평가

Gemini로 RAG 애플리케이션을 평가하는 완전한 예시(자동 임베딩 프로바이더 매칭 사용)예요.

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

# Initialize Gemini client (new SDK)
client = genai.Client(api_key=os.environ.get("GOOGLE_API_KEY"))
llm = llm_factory("gemini-2.0-flash", provider="google", client=client)

# Create sample evaluation data
data = {
    "question": ["What is the capital of France?"],
    "answer": ["Paris is the capital of France."],
    "contexts": [["France is a country in Western Europe. Paris is its capital."]],
    "ground_truth": ["Paris"]
}

dataset = Dataset.from_dict(data)

# Define metrics - embeddings automatically use Google provider
metrics = [
    ContextPrecision(llm=llm),
    ContextRecall(llm=llm),
    Faithfulness(llm=llm),
    AnswerCorrectness(llm=llm)
]

# Run evaluation
results = evaluate(dataset, metrics=metrics)
print(results)

성능 고려사항

모델 선택

gemini-2.0-flash : 속도와 효율에 가장 좋아요
gemini-1.5-pro : 복잡한 평가에 더 나은 추론
gemini-1.5-flash : 속도와 비용의 좋은 균형

비용 최적화

Gemini 모델은 비용 효율적이에요. 대규모 평가를 위해서는:

대부분의 메트릭에 gemini-2.0-flash 사용
여러 평가에 대해 배치 처리 고려
가능하면 프롬프트 캐시(Gemini는 프롬프트 캐싱 지원)

비동기 지원

높은 처리량 평가를 위해서는 비동기 작업을 사용하세요.

import os
from google import genai
from ragas.llms import llm_factory

# Create client (new SDK)
client = genai.Client(api_key=os.environ.get("GOOGLE_API_KEY"))
llm = llm_factory("gemini-2.0-flash", provider="google", client=client)

# Use in async evaluation
# response = await llm.agenerate(prompt, ResponseModel)

어댑터 선택

Ragas는 설정에 따라 적절한 어댑터를 자동 선택해요.

# Auto-detection happens automatically
# For Gemini: uses LiteLLM adapter
# For other providers: uses Instructor adapter

# Explicit selection (if needed)
llm = llm_factory(
    "gemini-2.0-flash",
    client=client,
    adapter="litellm"  # Explicit adapter selection
)

# Check auto-detected adapter
from ragas.llms.adapters import auto_detect_adapter
adapter_name = auto_detect_adapter(client, "google")
print(f"Using adapter: {adapter_name}")  # Output: Using adapter: litellm

문제 해결

API 키 문제

# Make sure your API key is set
import os
if not os.environ.get("GOOGLE_API_KEY"):
    raise ValueError("GOOGLE_API_KEY environment variable not set")

알려진 이슈: Instructor 안전 설정(새 SDK)

새 google-genai SDK를 사용할 때 instructor 라이브러리가 Gemini API에 잘못된 안전 설정을 보내는 알려진 업스트림 이슈가 있어요. 다음과 같은 오류가 발생할 수 있어요.

Invalid value at 'safety_settings[5].category'... "HARM_CATEGORY_JAILBREAK"

우회 방법:

OpenAI 호환 엔드포인트 사용(지금은 권장):

from openai import OpenAI
client = OpenAI(
    api_key=os.environ.get("GOOGLE_API_KEY"),
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)
llm = llm_factory("gemini-2.0-flash", provider="openai", client=client)

업스트림 이슈 추적: instructor#1658

Note: 임베딩은 새로운 SDK에서 올바르게 동작해요—이 이슈는 LLM 생성에만 영향을 미쳐요.

Rate Limit

Gemini에는 rate limit이 있어요. 프로덕션 사용 시 LLM 어댑터가 재시도와 타임아웃을 자동으로 처리해요. 세밀한 제어가 필요하다면 HTTP 클라이언트 수준에서 적절한 타임아웃으로 클라이언트를 구성해야 해요.

모델 가용성

모델을 사용할 수 없으면:

Google Cloud Console에서 지역/할당량 확인
지원 목록에서 다른 모델 시도
API 키가 Generative AI API에 접근 권한이 있는지 확인

다른 프로바이더에서 마이그레이션

OpenAI에서

# Before: OpenAI-only
from openai import OpenAI
client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
llm = llm_factory("gpt-4o", client=client)

# After: Gemini with new SDK
from google import genai
client = genai.Client(api_key=os.environ.get("GOOGLE_API_KEY"))
llm = llm_factory("gemini-2.0-flash", provider="google", client=client)

Anthropic에서

# Before: Anthropic
from anthropic import Anthropic
client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))
llm = llm_factory("claude-3-sonnet", provider="anthropic", client=client)

# After: Gemini with new SDK
from google import genai
client = genai.Client(api_key=os.environ.get("GOOGLE_API_KEY"))
llm = llm_factory("gemini-2.0-flash", provider="google", client=client)

레거시 google-generativeai SDK에서

# Before: Legacy SDK (deprecated)
import google.generativeai as genai
genai.configure(api_key=os.environ.get("GOOGLE_API_KEY"))
client = genai.GenerativeModel("gemini-2.0-flash")
llm = llm_factory("gemini-2.0-flash", provider="google", client=client)

# After: New SDK (recommended)
from google import genai
client = genai.Client(api_key=os.environ.get("GOOGLE_API_KEY"))
llm = llm_factory("gemini-2.0-flash", provider="google", client=client)

메트릭 컬렉션과 함께 사용(최신 방식)

최신 메트릭 컬렉션 API를 위해 LLM과 임베딩을 모두 명시적으로 만들어야 해요.

import os
from google import genai
from ragas.llms import llm_factory
from ragas.embeddings import GoogleEmbeddings
from ragas.metrics.collections import AnswerCorrectness, ContextPrecision

# Create client (new SDK)
client = genai.Client(api_key=os.environ.get("GOOGLE_API_KEY"))

# Create LLM
llm = llm_factory("gemini-2.0-flash", provider="google", client=client)

# Create embeddings using the same client
embeddings = GoogleEmbeddings(client=client, model="gemini-embedding-001")

# Create metrics with explicit LLM and embeddings
metrics = [
    ContextPrecision(llm=llm),  # LLM-only metric
    AnswerCorrectness(llm=llm, embeddings=embeddings),  # Needs both
]

# Use metrics with your evaluation workflow
result = await metrics[1].ascore(
    user_input="What is the capital of France?",
    response="Paris",
    reference="Paris is the capital of France."
)

레거시 방식과의 핵심 차이:

레거시 evaluate() : LLM 프로바이더에서 임베딩을 자동 생성
최신 컬렉션 : 각 메트릭에 임베딩을 명시적으로 전달

이렇게 하면 더 많은 제어가 가능하고 Gemini와 매끄럽게 동작해요!

지원 메트릭

모든 Ragas 메트릭이 Gemini와 동작해요.

Answer Correctness
Answer Relevancy
Answer Similarity
Aspect Critique
Context Precision
Context Recall
Context Entities Recall
NLI Eval
Response Relevancy

자세한 내용은 Metrics Reference를 참고하세요.

고급: 커스텀 모델 파라미터

Gemini에 커스텀 파라미터를 전달해요.

llm = llm_factory(
    "gemini-2.0-flash",
    client=client,
    temperature=0.5,
    max_tokens=2048,
    top_p=0.9,
    top_k=40,
)

리소스

Google GenAI SDK 문서
Google Gemini API 문서
Ragas 메트릭 문서
Ragas LLM Factory 가이드

더 알아보기 (Learn more)

통합 목록