Évaluation RAG sur disque (corpus/ + train.json)

Objectif

Guider les agents à travers les benchmarks filesystem de NVIDIA RAG Blueprint : préparer corpus/ et train.json, exécuter scripts/eval/evaluate_rag.py, ajuster les flags de retrieval et de génération pour les comparaisons de qualité, interpréter les sorties JSON RAGAS, et diagnostiquer les défaillances (erreurs HTTP/stream, contextes vides, collection non correspondante, API judge).

Pour les tests de latence, débit et charge, utilisez la skill rag-perf (scripts/rag-perf, docs/performance-benchmarking.md) — pas cette skill.

Quand ne pas utiliser

N'utilisez pas cette skill pour : déployer ou réparer des services (utilisez rag-blueprint) ; évaluer des APIs sans le layout corpus/ + train.json ; expériences ML générales sans lien avec cet évaluateur ; monitoring/alerting en production ; ou benchmarking de latence/débit (utilisez rag-perf).

Prérequis

• Repo cloné ; exécutez les commandes depuis la racine du repo (les imports et chemins supposent cela).
• Python 3.11+ et uv ; dépendances eval : uv sync --project scripts/eval.
• Serveur RAG et ingestor accessibles (par défaut souvent localhost:8081 / 8082).
• NVIDIA_API_KEY pour RAGAS (voir hygiène des credentials) ; RAG_EVAL_JUDGE_MODEL optionnel.
• Les racines de dataset passées à --dataset-paths contiennent chacune corpus/ et train.json.

Instructions

1. Préparer les données — Assurez-vous que chaque répertoire de dataset correspond au layout et aux règles de train.json dans references/dataset-and-conversion.md. Quand les sources arrivent sous forme de liens publics (sites ou pages dataset), matérialisez les documents sous corpus/ — préférez PDF pour le contenu multimodal afin que les images restent intégrées ; convertissez CSV/JSONL/etc. en utilisant les patterns là-bas.
2. Exécuter eval — uv run --project scripts/eval python scripts/eval/evaluate_rag.py avec --dataset-paths, --host, et --port. Voir references/benchmark-execution.md pour les exemples de commande, sorties et erreurs. Utilisez references/evaluate-rag-cli.md pour les détails au niveau des flags.
3. Ajuster la qualité — Modifiez --top_k / --vdb_top_k, les toggles de reranking et query-rewriting, et les overrides de génération (--temperature, --top-p, --max-tokens) comme documenté dans references/benchmark-execution.md quand vous comparez les configs de retrieval/génération pour les scores RAGAS.
4. Analyser les résultats — Utilisez references/result-analysis.md pour les scripts ; examinez rag_*_evaluation_summary.json pour les métriques RAGAS principales.
5. Diagnostiquer les erreurs — Utilisez le tableau de signaux d'erreur et la section Dépannage ci-dessous.

Exemples

Définir la clé API sans mettre les secrets dans l'historique shell (patterns préférés) : charger depuis un fichier env ignoré par git ou un gestionnaire de secrets ; évitez de commiter .env ; renouvelez les clés si exposées. Détails : references/benchmark-execution.md#credential-hygiene-nvidia_api_key.

Eval minimal (clé déjà dans l'environnement) :

uv sync --project scripts/eval
uv run --project scripts/eval python scripts/eval/evaluate_rag.py \
  --dataset-paths /path/to/my_dataset \
  --host localhost \
  --port 8081

Afficher le JSON du résumé en beau format :

python3 -m json.tool results/my_dataset/rag_my_dataset_evaluation_summary.json

Plus d'exemples (ignorer l'ingestion, balayage qualité) : references/benchmark-execution.md.

Limitations

• Le comportement de l'évaluateur est fixe au contrat filesystem et à evaluate_rag.py ; il ne se substitue pas aux judges offline personnalisés ou aux benchmarks non-RAG.
• Les choix de Vector DB / embedding suivent l'ingestor déployé et l'environnement RAG — non surpassés par ce CLI seul.
• Les scores dépendent de la qualité du retrieval, la disponibilité du judge model, et NVIDIA_API_KEY ; les contextes vides donnent des métriques RAGAS partielles (voir références).
• Les détails procéduraux larges vivent sous references/ pour garder le routage concis ; lisez ces fichiers quand l'utilisateur a besoin d'une conversion pas-à-pas, des flags complets, ou de tables d'erreurs.

Dépannage

Table de signaux complète : references/benchmark-execution.md#common-error-cases-and-signals.

Pièges

• Exécuter depuis la racine du repo : les chemins et imports dans scripts/eval/evaluate_rag.py supposent cela ; un mauvais répertoire casse silencieusement les imports.
• --ingestor_server_url : passez http://host:port sans /v1 — le code ajoute /v1/ automatiquement. Inclure /v1 cause des 404s sur les appels ingestor.
• Paramètres Vector DB / embedding : non définis par ce CLI ; configurez via l'ingestor déployé et les vars env du serveur RAG (p.ex. APP_VECTORSTORE_URL, embedding model).
• --model / --llm_endpoint : transmis verbatim uniquement quand explicitement définis ; omettez pour garder le LLM configuré du serveur.
• Collections obsolètes : les données ingérées d'une précédente exécution persistent sauf si vous utilisez --force_ingestion. Utilisez --collection avec un nom unique quand vous comparez la qualité entre exécutions isolées.
• Métriques de contexte vide : si tous les generated_contexts sont vides, les scores RAGAS ne calculent que nv_accuracy et laissent les deux autres métriques blanches — ce n'est pas un succès silencieux.

Source de vérité

Playbook agent

1. Exécuter eval — uv sync --project scripts/eval puis uv run --project scripts/eval python scripts/eval/evaluate_rag.py avec les --dataset-paths, --host, et --port requis (et env NVIDIA_API_KEY). L'argument --ingestor_server_url est optionnel (par défaut http://localhost:8082) ; ne le passez que quand vous surpassez l'endpoint ingestor.
2. Ajustement qualité — Voir references/benchmark-execution.md : --top_k/--vdb_top_k, toggles de reranker et query-rewriting, --temperature, --top-p, --max-tokens.
3. Conversion de données — Suivez references/dataset-and-conversion.md.
4. Analyser les résultats — references/result-analysis.md ; scan rapide : python3 -m json.tool results/<dataset>/rag_<dataset>_evaluation_summary.json.
5. Diagnostic d'erreurs — references/benchmark-execution.md#common-error-cases-and-signals.