Cách sửa lỗi Ragas ValueError: Dataset does not contain required column ['contexts']

Lỗi thường gặpKhi chạy các chỉ số đánh giá trong Ragas (Retrieval Augmented Generation Assessment), bạn có thể gặp lỗi crash trong quá trình gọi hàm evaluate(). Truy vết lỗi (traceback) thường trông như sau:

ValueError: Dataset does not contain required column ['contexts']

Điều này xảy ra ngay cả khi bạn cảm thấy tập dữ liệu của mình đã đầy đủ. Thư viện Ragas rất khắt khe về cấu trúc đầu vào (schema). Nếu thiếu hoặc viết sai tên một cột bắt buộc, quá trình đánh giá sẽ dừng lại ngay lập tức.

Nguyên nhân gốc rễCác chỉ số của Ragas yêu cầu tên cột cụ thể trong đối tượng Hugging Face Dataset để thực hiện tính toán. Tùy thuộc vào các chỉ số bạn chọn (như context_precision hoặc context_recall), thư viện sẽ mong đợi một cột có tên chính xác là contexts.

Các nguyên nhân phổ biến gây ra lỗi này bao gồm:

• Sai lệch tên gọi: Tập dữ liệu của bạn sử dụng context (số ít), source_documents, hoặc retrieved_chunks thay vì contexts.- Vấn đề kiểu dữ liệu: Cột contexts phải là một danh sách các chuỗi (List[str]), không phải là một chuỗi đơn lẻ hay một danh sách các đối tượng.- Thiếu khóa trong từ điển: Khi chuyển đổi một từ điển Python sang Hugging Face Dataset, khóa cho các tài liệu đã truy xuất không khớp với những gì Ragas mong đợi.## Các bước khắc phục### Cách 1: Đổi tên cột trong Hugging Face DatasetNếu bạn đã có một đối tượng dataset nhưng tên cột bị sai, hãy sử dụng phương thức rename_column. Đây là cách hiệu quả nhất để sửa lỗi mà không cần xử lý lại dữ liệu.

from datasets import Dataset

# Dữ liệu mẫu với tên cột bị 'sai'
data = {
    "question": ["What is Ragas?"],
    "answer": ["Ragas is an evaluation framework."],
    "source": [["Ragas helps evaluate RAG pipelines."]], # Cột này lẽ ra phải là 'contexts'
    "ground_truth": ["Ragas is a framework for RAG evaluation."]
}

ds = Dataset.from_dict(data)

# Sửa lỗi: Đổi tên 'source' thành 'contexts'
if "contexts" not in ds.column_names:
    ds = ds.rename_column("source", "contexts")

print(ds.column_names)
# Output: ['question', 'answer', 'contexts', 'ground_truth']

Cách 2: Định dạng Contexts chính xácRagas yêu cầu contexts phải là một danh sách các chuỗi cho mỗi hàng. Nếu pipeline RAG của bạn trả về một chuỗi đơn lẻ, bạn phải bao bọc nó trong một danh sách. Nếu nó trả về các đối tượng LangChain Document, bạn phải trích xuất page_content.

# Định dạng sai (sẽ gây lỗi ngay cả khi tên cột đúng)
# contexts: "This is a single string"

# Định dạng đúng
# contexts: ["Chunk 1 text", "Chunk 2 text"]

# Ví dụ về việc trích xuất từ các tài liệu LangChain
retrieved_docs = retriever.get_relevant_documents(query)
context_strings = [doc.page_content for doc in retrieved_docs]

# Thêm vào từ điển dữ liệu của bạn
eval_data = {
    "question": [query],
    "answer": [result_from_llm],
    "contexts": [context_strings], # Lưu ý danh sách lồng nhau
    "ground_truth": [actual_answer]
}

Cách 3: Sử dụng lớp EvaluationDataset (Ragas 0.2+)Các phiên bản mới hơn của Ragas cung cấp một cách có cấu trúc hơn để xử lý dữ liệu. Thay vì truyền vào một dataset thô, bạn có thể sử dụng các lớp EvaluationDataset hoặc SingleTurnSample để giúp xác thực schema trước khi chạy logic đánh giá nặng nề.

from ragas import EvaluationDataset

# Lệnh này sẽ đưa ra lỗi xác thực rõ ràng sớm nếu thiếu 'contexts'
eval_ds = EvaluationDataset.from_dict({
    "question": [...],
    "answer": [...],
    "contexts": [[...]], 
    "ground_truth": [...]
})

Xác minhĐể xác nhận việc khắc phục, hãy chạy một đánh giá tối giản với chỉ một chỉ số. Điều này giúp tiết kiệm chi phí API trong khi vẫn xác minh được schema.

from ragas import evaluate
from ragas.metrics import context_precision

# Nếu lệnh này chạy mà không có ValueError, schema của bạn đã chính xác
result = evaluate(
    dataset=ds,
    metrics=[context_precision]
)

print("Evaluation successful:", result)

Cách phòng ngừaĐể tránh lỗi này trong các dự án tương lai, hãy triển khai một hàm ánh xạ (mapping) đơn giản cho đầu ra RAG của bạn. Vì các framework khác nhau (LangChain, LlamaIndex, Haystack) sử dụng các quy ước đặt tên khác nhau cho các node được truy xuất, một hàm mapper sẽ đảm bảo tính nhất quán.

def prepare_ragas_dataset(rag_results):
    """
    Chuẩn hóa đầu ra RAG sang định dạng Ragas.
    rag_results: Danh sách các từ điển chứa 'query', 'result', 'source_documents'
    """
    formatted_data = {
        "question": [],
        "answer": [],
        "contexts": [],
        "ground_truth": []
    }
    
    for item in rag_results:
        formatted_data["question"].append(item["query"])
        formatted_data["answer"].append(item["result"])
        # Đảm bảo contexts là một danh sách các chuỗi
        formatted_data["contexts"].append([doc.page_content for doc in item["source_documents"]])
        formatted_data["ground_truth"].append(item["expected_answer"])
        
    return Dataset.from_dict(formatted_data)

Bằng cách áp dụng schema này tại lớp nạp dữ liệu (data ingestion), bạn sẽ ngăn chặn lỗi ValueError tiếp cận công cụ đánh giá của Ragas.