ragas官方文档中文版（五十八）

yongche_shi

12人浏览 · 2026-07-08 08:15:00

yongche_shi · 2026-07-08 08:15:00 发布

操作指南

本节中的每个指南都针对您作为有经验的用户在使用 Ragas 时可能遇到的实际问题提供了专注的解决方案。这些指南设计得简洁直接，为您的问题提供快速解决方案。我们假设您对 Ragas 的概念有基本了解且能够熟练使用。如果不是，请先浏览快速入门（Get Started）部分。

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：默认嵌入（推荐）

让 Ragas 根据您的 LLM 自动选择合适的嵌入：

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）

instructor 库存在一个已知的上游问题，当使用新的 google-genai SDK 时，它会向 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

注意：嵌入在新 SDK 中正常工作——此问题仅影响 LLM 生成。

速率限制

Gemini 有速率限制。对于生产用途，LLM 适配器会自动处理重试和超时。如果需要细粒度控制，请确保您的客户端在 HTTP 客户端级别正确配置了适当的超时设置。

模型可用性

如果模型不可用：

在 Google Cloud Console 中检查您的区域/配额
尝试支持列表中的其他模型
验证您的 API 密钥是否有权访问生成式 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（上下文实体召回率）
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,
)

资源

Google GenAI SDK 文档
Google Gemini API 文档
Ragas 指标文档
Ragas LLM 工厂指南

2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

关于gpt与文心使用的对比分析

期间登录openai官网访问gpt咨询问题：Gemini API（免费额度较大） Groq 免费接口、OpenRouter 免费模型哪个模型好。gpt:给出Gemini、OpenRouter、Groq，为了防止出错，又开了新聊天问同样的问题，回答顺序依然没有改变。文心承认一半真一半假，数据全是编的，并反驳gpt的发言也是编的。这时文心给出的推荐排序是第三方应用平台(调用的是openai官网的gp

2048 AI社区

如何让Kimi生成excel ？AI 导出鸭一键搞定。

2048 AI社区

从循环开始：理解 Claude Code 的 Loop 机制

循环（Loop）是指智能体重复执行工作，直到满足停止条件。循环可按触发方式、停止条件以及所使用的 Claude Code 原语（命令/能力）来分类。并非所有任务都需要循环——从简单开始。选择合适的交互模式—— 简单任务用 Turn-based，复杂任务用 Goal-based 或 Proactive设计高效的自动化工作流—— 通过组合 /schedule、/goal、/loop 实现复杂场景优化