操作指南

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

LLM 适配器：使用多种结构化输出后端

Ragas 通过适配器模式支持多种结构化输出后端。本指南说明如何为不同的 LLM 服务商使用不同的适配器。

概述

Ragas 使用适配器处理来自不同 LLM 服务商的结构化输出：

• Instructor 适配器 ：适用于 OpenAI、Anthropic、Azure、Groq、Mistral、Cohere 以及其他许多服务商
• LiteLLM 适配器 ：适用于所有 100+ 个受 LiteLLM 支持的服务商（Gemini、Ollama、vLLM、Bedrock 等）

框架会自动为您的服务商选择最佳适配器，但您也可以显式选择。

快速开始

自动适配器选择（推荐）**

让 Ragas 自动检测最佳适配器：

from ragas.llms import llm_factory
from openai import OpenAI

# For OpenAI - automatically uses Instructor adapter
client = OpenAI(api_key="...")
llm = llm_factory("gpt-4o-mini", client=client)

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

# For Gemini - automatically uses LiteLLM adapter
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

# Force using Instructor adapter
llm = llm_factory("gpt-4o", client=client, adapter="instructor")

# Force using LiteLLM adapter
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

# See which adapter will be used
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)
# Uses Instructor adapter automatically

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)
# Uses Instructor adapter automatically

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)
# Uses LiteLLM adapter automatically for google provider

Google Gemini（使用 LiteLLM Proxy - 高级）

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
)
llm = llm_factory("gemini-2.0-flash", client=client, adapter="litellm")
# Uses LiteLLM adapter explicitly

本地模型（Ollama）

from openai import OpenAI
from ragas.llms import llm_factory

# Ollama exposes OpenAI-compatible API
client = OpenAI(
    api_key="ollama",
    base_url="http://localhost:11434/v1"
)
llm = llm_factory("mistral", provider="openai", client=client)
# Uses Instructor adapter

AWS Bedrock

from openai import OpenAI
from ragas.llms import llm_factory

# Use LiteLLM proxy for Bedrock
# Note: Set up LiteLLM with Bedrock credentials first
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)
# Uses Instructor adapter automatically

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)
# Uses Instructor adapter automatically

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)
# Uses Instructor adapter automatically

适配器选择指南

根据您的需求选择适配器：

使用 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")

# Create LLM using adapter directly
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)

# Async generation
response = await llm.agenerate(prompt, ResponseModel)

使用 LiteLLM 的自定义服务商

LiteLLM 支持许多 Instructor 未覆盖的服务商。使用 LiteLLM proxy 方法：

from openai import OpenAI
from ragas.llms import llm_factory

# Set up LiteLLM proxy first:
# 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,
)

# Initialize LLM with your provider
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)

# Create evaluation dataset
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)

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

# Evaluate
results = evaluate(dataset, metrics=metrics)
print(results)

故障排除

“Unknown adapter: xyz”（未知适配器：xyz）**

确保您使用的是有效的适配器名称：

# Valid: "instructor" or "litellm"
llm = llm_factory("model", client=client, adapter="instructor")

# Invalid: "dspy" (not yet implemented)
# llm = llm_factory("model", client=client, adapter="dspy")  # Error!

“Failed to initialize provider client”（初始化服务商客户端失败）

确保：

1. 您的客户端已正确初始化
2. 您的 API 密钥有效
3. 该服务商被适配器支持

# Check if adapter can handle your provider
from ragas.llms.adapters import auto_detect_adapter
adapter = auto_detect_adapter(client, "my-provider")
print(f"Will use: {adapter}")

适配器不匹配

自动检测可以处理大多数情况，但显式选择会更有帮助：

# If auto-detection picks the wrong adapter:
llm = llm_factory(
    "model",
    provider="provider-name",
    client=client,
    adapter="litellm"  # Explicit override
)

迁移指南

从纯文本到结构化输出

如果您正在从纯文本 LLM 使用方式升级：

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

# After (new way)
from ragas.llms import llm_factory
llm = llm_factory("gpt-4o", client=client)

切换服务商

要从 OpenAI 切换到 Gemini：

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

# After: Gemini (similar code pattern!)
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)
# Adapter automatically switches to LiteLLM for google provider

另请参阅

• Gemini 集成指南 - 详细的 Gemini 设置
• LLM Factory 参考 - 完整的 API 参考
• 指标文档 - 使用 LLM 的指标