快速开始：几分钟跑起评测

几分钟上手 Ragas。只需几条命令，就能创建一个完整的评测项目。

第 1 步：创建项目

任选一种方式：

无需预先安装。uvx 会自动下载并运行 ragas：

uvx ragas quickstart rag_eval
cd rag_eval

先安装 ragas，再创建项目：

pip install ragas
ragas quickstart rag_eval
cd rag_eval

第 2 步：安装依赖

安装项目依赖：

uv sync

或者你更喜欢 pip：

pip install -e .

第 3 步：设置 API Key

默认情况下，quickstart 示例使用 OpenAI。设置 API key 即可开始。你也可以稍作修改后使用其他提供商：

export OPENAI_API_KEY="your-openai-key"

quickstart 项目已经配置为使用 OpenAI。可以直接开始！

设置 Anthropic API key：

export ANTHROPIC_API_KEY="your-anthropic-key"

然后更新 evals.py 中的 LLM 初始化：

from anthropic import Anthropic
from ragas.llms import llm_factory

client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))
llm = llm_factory("claude-3-5-sonnet-20241022", provider="anthropic", client=client)

设置 Google 凭证：

export GOOGLE_API_KEY="your-google-api-key"

然后更新 evals.py 中的 LLM 初始化：

选项 1：使用 Google 官方库（推荐）

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

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)
# Adapter is auto-detected as "litellm" for google provider

更多 Gemini 选项与详细设置，见 Google Gemini 集成指南。

在本地安装并运行 Ollama，然后更新 evals.py 中的 LLM 初始化：

from openai import OpenAI
from ragas.llms import llm_factory

# Create an OpenAI-compatible client for Ollama
client = OpenAI(
    api_key="ollama",  # Ollama doesn't require a real key
    base_url="http://localhost:11434/v1"
)
llm = llm_factory("mistral", provider="openai", client=client)

对于任何 OpenAI 兼容 API 的 LLM：

from openai import OpenAI
from ragas.llms import llm_factory

client = OpenAI(
    api_key="your-api-key",
    base_url="https://your-api-endpoint"
)
llm = llm_factory("model-name", provider="openai", client=client)

更多细节，见 LLM 集成。

项目结构

生成的项目包含：

rag_eval/
├── README.md              # Project documentation
├── pyproject.toml         # Project configuration
├── rag.py                 # Your RAG application
├── evals.py               # Evaluation workflow
├── __init__.py            # Makes this a Python package
└── evals/
    ├── datasets/          # Test data files
    ├── experiments/       # Evaluation results
    └── logs/              # Execution logs

第 4 步：运行评测

运行评测脚本：

uv run python evals.py

如果用 pip 安装：

python evals.py

评测会：

从 evals.py 的 load_dataset() 函数加载测试数据
用测试问题查询你的 RAG 应用
评测响应
在控制台显示结果
把结果保存为 evals/experiments/ 目录下的 CSV

恭喜！你已经有一套完整可运行的评测环境。🎉

定制你的评测

增加更多测试用例

编辑 evals.py 中的 load_dataset()，增加更多测试问题：

from ragas import Dataset

def load_dataset():
    """Load test dataset for evaluation."""
    dataset = Dataset(
        name="test_dataset",
        backend="local/csv",
        root_dir=".",
    )

    data_samples = [
        {
            "question": "What is Ragas?",
            "grading_notes": "Ragas is an evaluation framework for LLM applications",
        },
        {
            "question": "How do metrics work?",
            "grading_notes": "Metrics evaluate the quality and performance of LLM responses",
        },
        # Add more test cases here
    ]

    for sample in data_samples:
        dataset.append(sample)

    dataset.save()
    return dataset

定制评测指标

模板包含一个用于自定义评测逻辑的 DiscreteMetric。你可以通过以下方式定制评测：

修改指标 prompt — 更改评测标准
调整允许值 — 更新合法输出类别
增加更多指标 — 为不同方面创建额外指标

修改指标的示例：

from ragas.metrics import DiscreteMetric
from ragas.llms import llm_factory

my_metric = DiscreteMetric(
    name="custom_evaluation",
    prompt="Evaluate this response: {response} based on: {context}. Return 'excellent', 'good', or 'poor'.",
    allowed_values=["excellent", "good", "poor"],
)

接下来做什么？

学习概念：阅读评测一个简单的 LLM 应用，加深理解
自定义指标：用简单装饰器创建自己的指标
接入生产：把评测集成进 CI/CD 流水线
RAG 评测：用专用指标评测 RAG 系统
Agent 评测：探索 AI agent 评测
测试数据生成：为评测生成合成测试数据集