操作指南

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

OCI Gen AI 集成指南

本指南介绍如何使用 Oracle Cloud Infrastructure (OCI) 生成式 AI 模型与 Ragas 进行评估。

安装

首先，安装 OCI 依赖：

pip install ragas[oci]

设置

1. 配置 OCI 认证

使用以下方法之一设置 OCI 配置：

选项 A：OCI CLI 配置

oci setup config

选项 B：环境变量

export OCI_CONFIG_FILE=~/.oci/config
export OCI_PROFILE=DEFAULT

选项 C：手动配置

config = {
    "user": "ocid1.user.oc1..example",
    "key_file": "~/.oci/private_key.pem",
    "fingerprint": "your_fingerprint",
    "tenancy": "ocid1.tenancy.oc1..example",
    "region": "us-ashburn-1"
}

2. 获取必需的 ID

您需要：

• 模型 ID ：OCI 模型 ID（例如 cohere.command 、 meta.llama-3-8b ）
• Compartment ID ：您的 OCI 租户 OCID
• 端点 ID（可选） ：如果使用自定义端点

使用

基本用法

from ragas.llms import oci_genai_factory
from ragas import evaluate
from datasets import Dataset

# Initialize OCI Gen AI LLM
llm = oci_genai_factory(
    model_id="cohere.command",
    compartment_id="ocid1.compartment.oc1..example"
)

# Your dataset
dataset = Dataset.from_dict({
    "question": ["What is the capital of France?"],
    "answer": ["Paris"],
    "contexts": [["France is a country in Europe. Its capital is Paris."]],
    "ground_truth": ["Paris"]
})

# Evaluate with OCI Gen AI
result = evaluate(
    dataset,
    llm=llm,
    embeddings=None  # You can use any embedding model
)

高级配置

from ragas.llms import oci_genai_factory
from ragas.run_config import RunConfig

# Custom OCI configuration
config = {
    "user": "ocid1.user.oc1..example",
    "key_file": "~/.oci/private_key.pem",
    "fingerprint": "your_fingerprint",
    "tenancy": "ocid1.tenancy.oc1..example",
    "region": "us-ashburn-1"
}

# Custom run configuration
run_config = RunConfig(
    timeout=60,
    max_retries=3
)

# Initialize with custom config and endpoint
llm = oci_genai_factory(
    model_id="cohere.command",
    compartment_id="ocid1.compartment.oc1..example",
    config=config,
    endpoint_id="ocid1.endpoint.oc1..example",  # Optional
    run_config=run_config
)

使用不同模型

# Cohere Command model
llm_cohere = oci_genai_factory(
    model_id="cohere.command",
    compartment_id="ocid1.compartment.oc1..example"
)

# Meta Llama model
llm_llama = oci_genai_factory(
    model_id="meta.llama-3-8b",
    compartment_id="ocid1.compartment.oc1..example"
)

# Using with different endpoints
llm_endpoint = oci_genai_factory(
    model_id="cohere.command",
    compartment_id="ocid1.compartment.oc1..example",
    endpoint_id="ocid1.endpoint.oc1..example"
)

支持的模型

OCI Gen AI 支持多种模型，包括：

• Cohere ： cohere.command 、 cohere.command-light
• Meta ： meta.llama-3-8b 、 meta.llama-3-70b
• Mistral ： mistral.mistral-7b-instruct
• 更多 ：请查阅 OCI 文档获取最新可用模型

错误处理

OCI Gen AI 封装器包含全面的错误处理：

try:
    result = evaluate(dataset, llm=llm)
except Exception as e:
    print(f"Evaluation failed: {e}")

性能考量

1. 速率限制 ：OCI Gen AI 有速率限制。使用适当的重试配置。
2. 超时 ：根据您的用例设置适当的超时时间。
3. 批处理 ：封装器支持多个补全的批处理。

故障排除

常见问题

1. 认证错误

Error: OCI SDK authentication failed

解决方案 ：验证您的 OCI 配置和凭证。

2. 模型未找到

Error: Model not found in compartment

解决方案 ：检查模型 ID 是否存在于您的 compartment 中。

3. 权限错误

Error: Insufficient permissions

解决方案 ：确保您的用户拥有生成式 AI 所需的 IAM 策略。

调试模式

启用调试日志以排查问题：

import logging
logging.basicConfig(level=logging.DEBUG)

# Your OCI Gen AI code here

示例

完整评估示例

from ragas import evaluate
from ragas.llms import oci_genai_factory
from ragas.metrics import faithfulness, answer_relevancy, context_precision
from datasets import Dataset

# Initialize OCI Gen AI
llm = oci_genai_factory(
    model_id="cohere.command",
    compartment_id="ocid1.compartment.oc1..example"
)

# Create dataset
dataset = Dataset.from_dict({
    "question": [
        "What is the capital of France?",
        "Who wrote Romeo and Juliet?"
    ],
    "answer": [
        "Paris is the capital of France.",
        "William Shakespeare wrote Romeo and Juliet."
    ],
    "contexts": [
        ["France is a country in Europe. Its capital is Paris."],
        ["Romeo and Juliet is a play by William Shakespeare."]
    ],
    "ground_truth": [
        "Paris",
        "William Shakespeare"
    ]
})

# Evaluate
result = evaluate(
    dataset,
    metrics=[faithfulness, answer_relevancy, context_precision],
    llm=llm
)

print(result)

使用 OCI Gen AI 的自定义指标

from ragas.metrics import MetricWithLLM

# Create custom metric using OCI Gen AI
class CustomMetric(MetricWithLLM):
    def __init__(self):
        super().__init__()
        self.llm = oci_genai_factory(
            model_id="cohere.command",
            compartment_id="ocid1.compartment.oc1..example"
        )

# Use in evaluation
result = evaluate(
    dataset,
    metrics=[CustomMetric()],
    llm=llm
)

最佳实践

1. 使用适当的模型 ：根据评估需求选择模型。
2. 监控成本 ：OCI Gen AI 使用会产生费用。监控您的使用情况。
3. 处理错误 ：为生产使用实施适当的错误处理。
4. 使用缓存 ：为重复评估启用缓存。
5. 批处理操作 ：尽可能使用批处理操作以提高效率。

支持

对于 OCI Gen AI 集成相关的问题：

• 查看 OCI 文档： https://docs.oracle.com/en-us/iaas/Content/generative-ai/
• OCI Python SDK： https://docs.oracle.com/en-us/iaas/tools/python/2.160.1/api/generative_ai.html
• Ragas GitHub 问题： https://github.com/vibrantlabsai/ragas/issues