Google Gemini 集成指南

本指南介绍如何设置并在 Ragas 评测中使用 Google 的 Gemini 模型。

概述

Ragas 支持 Google Gemini 模型，并自动选择 adapter。该框架同时适用于新的 google-genai SDK（推荐）和旧的 google-generativeai SDK。

设置

前置条件

具备 Gemini API 访问权限的 Google API Key
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 Proxy（高级）

对于需要 LiteLLM proxy 能力的高级用例，先搭建 LiteLLM proxy 服务器，然后使用：

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。

Embeddings 配置

Ragas 指标分为两类：

仅 LLM 的指标（不需要 embeddings）：
ContextPrecision
ContextRecall
Faithfulness
AspectCritic
依赖 embedding 的指标（需要 embeddings）：
AnswerCorrectness
AnswerRelevancy
AnswerSimilarity
SemanticSimilarity
ContextEntityRecall

自动匹配 Provider

将 Ragas 与 Gemini 一起使用时，embedding provider 会自动匹配 到你的 LLM provider。如果你提供的是 Gemini LLM，Ragas 默认会使用 Google embeddings。不需要 OpenAI API key。

选项 1：默认 Embeddings（推荐）

让 Ragas 根据你的 LLM 自动选择合适的 embeddings：

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：显式 Embeddings

要显式控制 embeddings，可以单独创建它们。Google embeddings 支持多种配置选项：

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 应用的完整示例（使用自动 embedding provider 匹配）：

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
考虑对多次评测使用批处理
尽可能缓存 prompts（Gemini 支持 prompt caching）

异步支持

对于高吞吐评测，使用异步操作：

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)

Adapter 选择

Ragas 会根据你的设置自动选择合适的 adapter：

# 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 Key 问题

# 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 Safety Settings（新 SDK）

instructor 库存在一个已知的上游问题：使用新的 google-genai SDK 时，它会向 Gemini API 发送无效的 safety settings。这可能导致如下错误：

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

变通方法：

使用 OpenAI 兼容 endpoint（目前推荐）：

python 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

注意：Embeddings 与新 SDK 配合正常——该问题只影响 LLM 生成。

速率限制

Gemini 有速率限制。生产使用时，LLM adapter 会自动处理重试和超时。如果需要细粒度控制，请确保在 HTTP 客户端层面为 client 配置合适的超时。

模型可用性

如果某个模型不可用：

在 Google Cloud Console 检查你的区域/配额
尝试支持列表中的其他模型
确认你的 API key 有权访问 Generative AI API

从其他 Provider 迁移

从 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)

与 Metrics Collections 一起使用（现代方法）

对于现代 metrics collections API，你需要显式创建 LLM 和 embeddings：

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 provider 自动创建 embeddings
现代 collections：你需要显式把 embeddings 传给每个指标

这能给你更多控制权，并能与 Gemini 无缝配合！

支持的指标

所有 Ragas 指标都可与 Gemini 一起使用：

Answer Correctness
Answer Relevancy
Answer Similarity
Aspect Critique
Context Precision
Context Recall
Context Entities Recall
Faithfulness
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,
)