操作指南

本节中的每个指南都针对您作为有经验的用户在使用 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 的指标
# python # AI
Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

创业团队省钱秘籍：如何利用库拉（ssooai.cn）一站式解决文案与代码需求？

avatar DeepSeek技术社区
cover

速览：chatgpt亡羊补牢，给大家补偿一个月的Pro/plus了！

avatar DeepSeek技术社区

2026深度实测：Claude Code平替对比与vibe coding实战

vibe coding 的核心不是“让 AI 写代码”，而是“让 AI 帮你做架构设计与规范落地”。Claude Code 适合纯终端英文开发，但成本高、迭代低效；TRAE 凭借免费基础版、中文友好、零门槛上手、全链路工程化能力，成为 Claude Code 的最优平替。作为维护祖传代码的老员工，我已全面切换至 TRAE，它不仅帮我修复了 CMS-Pro 的历史问题，更让我在新需求开发中效率提升

avatar DeepSeek技术社区