diff --git a/README.md b/README.md index 7278c699..f9dbeb76 100644 --- a/README.md +++ b/README.md @@ -55,9 +55,25 @@

-# Introduction of Dingo +# Introduction -Dingo is a data quality evaluation tool that helps you automatically detect data quality issues in your datasets. Dingo provides a variety of built-in rules and model evaluation methods, and also supports custom evaluation methods. Dingo supports commonly used text datasets and multimodal datasets, including pre-training datasets, fine-tuning datasets, and evaluation datasets. In addition, Dingo supports multiple usage methods, including local CLI and SDK, making it easy to integrate into various evaluation platforms, such as [OpenCompass](https://github.com/open-compass/opencompass). +**Dingo is A Comprehensive AI Data, Model and Application Quality Evaluation Tool**, designed for ML practitioners, data engineers, and AI researchers. It helps you systematically assess and improve the quality of training data, fine-tuning datasets, and production AI systems. + +## Why Dingo? + +🎯 **Production-Grade Quality Checks** - From pre-training datasets to RAG systems, ensure your AI gets high-quality data + +🗄️ **Multi-Source Data Integration** - Seamlessly connect to Local files, SQL databases (PostgreSQL/MySQL/SQLite), HuggingFace datasets, and S3 storage + +🔍 **Multi-Field Evaluation** - Apply different quality rules to different fields in parallel (e.g., ISBN validation for `isbn`, text quality for `title`) + +🤖 **RAG System Assessment** - Comprehensive evaluation of retrieval and generation quality with 5 academic-backed metrics + +🧠 **LLM & Rule Hybrid** - Combine fast heuristic rules (30+ built-in) with LLM-based deep assessment + +🚀 **Flexible Execution** - Run locally for rapid iteration or scale with Spark for billion-scale datasets + +📊 **Rich Reporting** - Detailed quality reports with GUI visualization and field-level insights ## Architecture Diagram @@ -197,26 +213,87 @@ https://github.com/user-attachments/assets/aca26f4c-3f2e-445e-9ef9-9331c4d7a37b This video demonstrates step-by-step how to use Dingo MCP server with Cursor. -# Data Quality Metrics +# 🎓 Key Concepts for Practitioners -Dingo provides comprehensive data quality assessment through both rule-based and prompt-based evaluation metrics. These metrics cover multiple quality dimensions including effectiveness, completeness, similarity, security, and more. +## What Makes Dingo Production-Ready? -📊 **[View Complete Metrics Documentation →](docs/metrics.md)** +### 1. **Multi-Field Evaluation Pipeline** +Apply different quality checks to different fields in a single pass: +```python +"evaluator": [ + {"fields": {"content": "isbn"}, "evals": [{"name": "RuleIsbn"}]}, + {"fields": {"content": "title"}, "evals": [{"name": "RuleAbnormalChar"}]}, + {"fields": {"content": "description"}, "evals": [{"name": "LLMTextQualityV5"}]} +] +``` +**Why It Matters**: Evaluate structured data (like database tables) without writing separate scripts for each field. + +### 2. **Stream Processing for Large Datasets** +SQL datasources use SQLAlchemy's server-side cursors: +```python +# Handles billions of rows without OOM +for data in dataset.get_data(): # Yields one row at a time + result = evaluator.eval(data) +``` +**Why It Matters**: Process production databases without exporting to intermediate files. + +### 3. **Field Isolation in Memory** +RAG evaluations prevent context bleeding across different field combinations: +``` +outputs/ +├── user_input,response,retrieved_contexts/ # Faithfulness group +└── user_input,response/ # Answer Relevancy group +``` +**Why It Matters**: Accurate metric calculations when evaluating multiple field combinations. + +### 4. **Hybrid Rule-LLM Strategy** +Combine fast rules (100% coverage) with sampled LLM checks (10% coverage): +```python +"evals": [ + {"name": "RuleAbnormalChar"}, # Fast, runs on all data + {"name": "LLMTextQualityV5"} # Expensive, sample if needed +] +``` +**Why It Matters**: Balance cost and coverage for production-scale evaluation. + +### 5. **Extensibility Through Registration** +Clean plugin architecture for custom rules, prompts, and models: +```python +@Model.rule_register('QUALITY_BAD_CUSTOM', ['default']) +class MyCustomRule(BaseRule): + @classmethod + def eval(cls, input_data: Data) -> EvalDetail: + # Your logic here + return EvalDetail(status=False, label=['QUALITY_GOOD']) +``` +**Why It Matters**: Adapt to domain-specific requirements without forking the codebase. + +--- -Our evaluation system includes: -- **Pretrain Text Quality Assessment Metrics**: Pre-training data quality evaluation using DataMan methodology and enhanced multi-dimensional assessment -- **SFT Data Assessment Metrics**: Honest, Helpful, Harmless evaluation for supervised fine-tuning data -- **Classification Metrics**: Topic categorization and content classification -- **Multimodality Assessment Metrics**: Image classification and relevance evaluation -- **Rule-Based Quality Metrics**: Automated quality checks using heuristic rules for effectiveness and similarity detection -- **Factuality Assessment Metrics**: Two-stage factuality evaluation based on GPT-5 System Card -- etc +# 📚 Data Quality Metrics -Most metrics are backed by academic sources to ensure objectivity and scientific rigor. +Dingo provides **70+ evaluation metrics** across multiple dimensions, combining rule-based speed with LLM-based depth. -### Using LLM Assessment in Evaluation +## Metric Categories -To use these assessment prompts in your evaluations, specify them in your configuration: +| Category | Examples | Use Case | +|----------|----------|----------| +| **Pretrain Text Quality** | Completeness, Effectiveness, Similarity, Security | LLM pre-training data filtering | +| **SFT Data Quality** | Honest, Helpful, Harmless (3H) | Instruction fine-tuning data | +| **RAG Evaluation** | Faithfulness, Context Precision, Answer Relevancy | RAG system assessment | +| **Hallucination Detection** | HHEM-2.1-Open, Factuality Check | Production AI reliability | +| **Classification** | Topic categorization, Content labeling | Data organization | +| **Multimodal** | Image-text relevance, VLM quality | Vision-language data | +| **Security** | PII detection, Perspective API toxicity | Privacy and safety | + +📊 **[View Complete Metrics Documentation →](docs/metrics.md)** +📖 **[RAG Evaluation Guide →](docs/rag_evaluation_metrics_zh.md)** +🔍 **[Hallucination Detection Guide →](docs/hallucination_guide.md)** +✅ **[Factuality Assessment Guide →](docs/factcheck_guide.md)** + +Most metrics are backed by academic research to ensure scientific rigor. + +## Quick Metric Usage ```python llm_config = { @@ -224,115 +301,188 @@ llm_config = { "key": "YOUR_API_KEY", "api_url": "https://api.openai.com/v1/chat/completions" } + input_data = { - # Other parameters... "evaluator": [ { "fields": {"content": "content"}, "evals": [ - {"name": "LLMTextRepeat", "config": llm_config} - ], + {"name": "RuleAbnormalChar"}, # Rule-based (fast) + {"name": "LLMTextQualityV5", "config": llm_config} # LLM-based (deep) + ] } ] } ``` -You can customize these prompts to focus on specific quality dimensions or to adapt to particular domain requirements. When combined with appropriate LLM models, these prompts enable comprehensive evaluation of data quality across multiple dimensions. +**Customization**: All prompts are defined in `dingo/model/llm/` directory (organized by category: `text_quality/`, `rag/`, `hhh/`, etc.). Extend or modify them for domain-specific requirements. + + +# 🌟 Feature Highlights + +## 📊 Multi-Source Data Integration -### Hallucination Detection & RAG System Evaluation +**Diverse Data Sources** - Connect to where your data lives +✅ **Local Files**: JSONL, CSV, TXT, Parquet +✅ **SQL Databases**: PostgreSQL, MySQL, SQLite, Oracle, SQL Server (with stream processing) +✅ **Cloud Storage**: S3 and S3-compatible storage +✅ **ML Platforms**: Direct HuggingFace datasets integration -For detailed guidance on using Dingo's hallucination detection capabilities, including HHEM-2.1-Open local inference and LLM-based evaluation: +**Enterprise-Ready SQL Support** - Production database integration +✅ Memory-efficient streaming for billion-scale datasets +✅ Connection pooling and automatic resource cleanup +✅ Complex SQL queries (JOIN, WHERE, aggregations) +✅ Multiple dialect support with SQLAlchemy -📖 **[View Hallucination Detection Guide →](docs/hallucination_guide.md)** +**Multi-Field Quality Checks** - Different rules for different fields +✅ Parallel evaluation pipelines (e.g., ISBN validation + text quality simultaneously) +✅ Field aliasing and nested field extraction (`user.profile.name`) +✅ Independent result reports per field +✅ ETL pipeline architecture for flexible data transformation -For comprehensive guidance on RAG evaluation metrics including Faithfulness, Context Precision, Answer Relevancy, Context Recall, and Context Relevancy: +--- -📖 **[View RAG Evaluation Metrics Guide →](docs/rag_evaluation_metrics_zh.md)** +## 🤖 RAG System Evaluation -### Factuality Assessment +**5 Academic-Backed Metrics** - Based on RAGAS, DeepEval, TruLens research +✅ **Faithfulness**: Answer-context consistency (hallucination detection) +✅ **Answer Relevancy**: Answer-query alignment +✅ **Context Precision**: Retrieval precision +✅ **Context Recall**: Retrieval recall +✅ **Context Relevancy**: Context-query relevance -For comprehensive guidance on using Dingo's two-stage factuality evaluation system: +**Comprehensive Reporting** - Auto-aggregated statistics +✅ Average, min, max, standard deviation for each metric +✅ Field-grouped results +✅ Batch and single evaluation modes -📖 **[View Factuality Assessment Guide →](docs/factcheck_guide.md)** +📖 **[View RAG Evaluation Guide →](docs/rag_evaluation_metrics_zh.md)** +--- -# Feature Highlights +## 🧠 Hybrid Evaluation System -## Multi-source & Multi-modal Support +**Rule-Based** - Fast, deterministic, cost-effective +✅ 30+ built-in rules (text quality, format, PII detection) +✅ Regex, heuristics, statistical checks +✅ Custom rule registration -- **Data Sources**: Local files, Hugging Face datasets, S3 storage -- **Data Types**: Pre-training, fine-tuning, and evaluation datasets -- **Data Modalities**: Text and image +**LLM-Based** - Deep semantic understanding +✅ OpenAI (GPT-4o, GPT-3.5), DeepSeek, Kimi +✅ Local models (Llama3, Qwen) +✅ Vision-Language Models (InternVL, Gemini) +✅ Custom prompt registration -## Rule-based & Model-based Evaluation +**Extensible Architecture** +✅ Plugin-based rule/prompt/model registration +✅ Clean separation of concerns (agents, tools, orchestration) +✅ Domain-specific customization -- **Built-in Rules**: 20+ general heuristic evaluation rules -- **LLM Integration**: OpenAI, Kimi, and local models (e.g., Llama3) -- **Hallucination Detection**: HHEM-2.1-Open local model and GPT-based evaluation -- **RAG System Evaluation**: Response consistency and context alignment assessment -- **Custom Rules**: Easily extend with your own rules and models -- **Security Evaluation**: Perspective API integration +--- -## Flexible Usage +## 🚀 Flexible Execution & Integration -- **Interfaces**: CLI and SDK options -- **Integration**: Easy integration with other platforms -- **Execution Engines**: Local and Spark +**Multiple Interfaces** +✅ CLI for quick checks +✅ Python SDK for integration +✅ MCP (Model Context Protocol) server for IDEs (Cursor, etc.) -## Comprehensive Reporting +**Scalable Execution** +✅ Local executor for rapid iteration +✅ Spark executor for distributed processing +✅ Configurable concurrency and batching -- **Quality Metrics**: 7-dimensional quality assessment -- **Traceability**: Detailed reports for anomaly tracking +**Data Sources** +✅ **Local Files**: JSONL, CSV, TXT, Parquet formats +✅ **Hugging Face**: Direct integration with HF datasets hub +✅ **S3 Storage**: AWS S3 and S3-compatible storage +✅ **SQL Databases**: PostgreSQL, MySQL, SQLite, Oracle, SQL Server (stream processing for large-scale data) -# User Guide +**Modalities** +✅ Text (chat, documents, code) +✅ Images (with VLM support) +✅ Multimodal (text + image consistency) -## Custom Rules, Prompts, and Models +--- -If the built-in rules don't meet your requirements, you can create custom ones: +## 📈 Rich Reporting & Visualization -### Custom Rule Example +**Multi-Level Reports** +✅ Summary JSON with overall scores +✅ Field-level breakdown +✅ Per-rule violation details +✅ Type and name distribution + +**GUI Visualization** +✅ Built-in web interface +✅ Interactive data exploration +✅ Anomaly tracking + +**Metric Aggregation** +✅ Automatic statistics (avg, min, max, std_dev) +✅ Field-grouped metrics +✅ Overall quality score + +--- + +# 📖 User Guide + +## 🔧 Extensibility + +Dingo uses a clean plugin architecture for domain-specific customization: + +### Custom Rule Registration ```python from dingo.model import Model from dingo.model.rule.base import BaseRule -from dingo.config.input_args import EvaluatorRuleArgs from dingo.io import Data from dingo.io.output.eval_detail import EvalDetail - -@Model.rule_register('QUALITY_BAD_RELEVANCE', ['default']) -class MyCustomRule(BaseRule): - """Check for custom pattern in text""" - - dynamic_config = EvaluatorRuleArgs(pattern=r'your_pattern_here') +@Model.rule_register('QUALITY_BAD_CUSTOM', ['default']) +class DomainSpecificRule(BaseRule): + """Check domain-specific patterns""" @classmethod def eval(cls, input_data: Data) -> EvalDetail: - res = EvalDetail() - # Your rule implementation here - return res + text = input_data.content + + # Your custom logic + is_valid = your_validation_logic(text) + + return EvalDetail( + status=not is_valid, # False = good, True = bad + label=['QUALITY_GOOD' if is_valid else 'QUALITY_BAD_CUSTOM'], + reason=["Validation details..."] + ) ``` -### Custom LLM Integration +### Custom LLM/Prompt Registration ```python from dingo.model import Model from dingo.model.llm.base_openai import BaseOpenAI -@Model.llm_register('my_custom_model') -class MyCustomModel(BaseOpenAI): - # Custom implementation here - pass +@Model.llm_register('custom_evaluator') +class CustomEvaluator(BaseOpenAI): + """Custom LLM evaluator with specialized prompts""" + + _metric_info = { + "metric_name": "CustomEvaluator", + "metric_type": "LLM-Based Quality", + "category": "Custom Category" + } + + prompt = """Your custom prompt here...""" ``` -See more examples in: -- [Register Rules](examples/register/sdk_register_rule.py) -- [Register Prompts](examples/register/sdk_register_prompt.py) -- [Register Models](examples/register/sdk_register_llm.py) +**Examples:** +- [Custom Rules](examples/register/sdk_register_rule.py) +- [Custom Models](examples/register/sdk_register_llm.py) -## Execution Engines +## ⚙️ Execution Modes -### Local Execution +### Local Executor (Development & Small-Scale) ```python from dingo.config import InputArgs @@ -342,42 +492,33 @@ input_args = InputArgs(**input_data) executor = Executor.exec_map["local"](input_args) result = executor.execute() -# Get results -summary = executor.get_summary() # Overall evaluation summary -bad_data = executor.get_bad_info_list() # List of problematic data -good_data = executor.get_good_info_list() # List of high-quality data +# Access results +summary = executor.get_summary() # Overall metrics +bad_data = executor.get_bad_info_list() # Quality issues +good_data = executor.get_good_info_list() # High-quality data ``` -### Spark Execution +**Best For**: Rapid iteration, debugging, datasets < 100K rows + +### Spark Executor (Production & Large-Scale) ```python -from dingo.config import InputArgs -from dingo.exec import Executor from pyspark.sql import SparkSession +from dingo.exec import Executor -# Initialize Spark spark = SparkSession.builder.appName("Dingo").getOrCreate() -spark_rdd = spark.sparkContext.parallelize([...]) # Your data as Data objects +spark_rdd = spark.sparkContext.parallelize(your_data) -input_data = { - "executor": { - "result_save": {"bad": True} - }, - "evaluator": [ - { - "fields": {"content": "content"}, - "evals": [ - {"name": "RuleColonEnd"}, - {"name": "RuleSpecialCharacter"} - ] - } - ] -} -input_args = InputArgs(**input_data) -executor = Executor.exec_map["spark"](input_args, spark_session=spark, spark_rdd=spark_rdd) +executor = Executor.exec_map["spark"]( + input_args, + spark_session=spark, + spark_rdd=spark_rdd +) result = executor.execute() ``` +**Best For**: Production pipelines, distributed processing, datasets > 1M rows + ## Evaluation Reports After evaluation, Dingo generates: @@ -388,7 +529,6 @@ After evaluation, Dingo generates: Report Description: 1. **score**: `num_good` / `total` 2. **type_ratio**: The count of type / total, such as: `QUALITY_BAD_COMPLETENESS` / `total` -3. **name_ratio**: The count of name / total, such as: `QUALITY_BAD_COMPLETENESS-RuleColonEnd` / `total` Example summary: ```json @@ -412,16 +552,19 @@ Example summary: } ``` -# Future Plans +# 🚀 Roadmap & Contributions + +## Future Plans -- [ ] Richer graphic and text evaluation indicators -- [ ] Audio and video data modality evaluation -- [ ] Small model evaluation (fasttext, Qurating) -- [ ] Data diversity evaluation +- [ ] **Agent-as-a-Judge** - Multi-agent debate patterns for bias reduction and complex reasoning +- [ ] **SaaS Platform** - Hosted evaluation service with API access and dashboard +- [ ] **Audio & Video Modalities** - Extend beyond text/image +- [ ] **Diversity Metrics** - Statistical diversity assessment +- [ ] **Real-time Monitoring** - Continuous quality checks in production pipelines -# Limitations +## Limitations -The current built-in detection rules and model methods focus on common data quality problems. For specialized evaluation needs, we recommend customizing detection rules. +The current built-in detection rules and model methods primarily focus on common data quality issues. For special evaluation needs, we recommend customizing detection rules. # Acknowledgments diff --git a/README_ja.md b/README_ja.md index 5727140f..7b7c001e 100644 --- a/README_ja.md +++ b/README_ja.md @@ -56,7 +56,23 @@ # はじめに -Dingoは、データセット内のデータ品質問題を自動的に検出するデータ品質評価ツールです。Dingoは様々な組み込みルールとモデル評価手法を提供し、カスタム評価手法もサポートしています。Dingoは一般的に使用されるテキストデータセットとマルチモーダルデータセット(事前学習データセット、ファインチューニングデータセット、評価データセットを含む)をサポートしています。さらに、DingoはローカルCLIやSDKなど複数の使用方法をサポートし、[OpenCompass](https://github.com/open-compass/opencompass)などの様々な評価プラットフォームに簡単に統合できます。 +**Dingo は包括的な AI データ、モデル、アプリケーション品質評価ツール**であり、機械学習エンジニア、データエンジニア、AI 研究者向けに設計されています。トレーニングデータ、ファインチューニングデータセット、本番 AI システムの品質を体系的に評価・改善するのを支援します。 + +## なぜ Dingo を選ぶのか? + +🎯 **本番グレードの品質チェック** - 事前学習データセットから RAG システムまで、AI に高品質なデータを提供 + +🗄️ **マルチソースデータ統合** - ローカルファイル、SQL データベース(PostgreSQL/MySQL/SQLite)、HuggingFace データセット、S3 ストレージへのシームレスな接続 + +🔍 **マルチフィールド評価** - 異なるフィールドに並行して異なる品質ルールを適用(例:`isbn` フィールドには ISBN 検証、`title` フィールドにはテキスト品質チェック) + +🤖 **RAG システム評価** - 5つの学術的裏付けのある指標で検索と生成品質を包括的に評価 + +🧠 **LLM とルールのハイブリッド** - 高速ヒューリスティックルール(30以上の組み込みルール)と LLM ベースの深度評価を組み合わせ + +🚀 **柔軟な実行** - ローカルで実行して迅速に反復、または Spark で数十億規模のデータセットにスケール + +📊 **豊富なレポート** - GUI 可視化とフィールドレベルの洞察を備えた詳細な品質レポート ## アーキテクチャ図 @@ -194,26 +210,87 @@ https://github.com/user-attachments/assets/aca26f4c-3f2e-445e-9ef9-9331c4d7a37b このビデオでは、Dingo MCPサーバーをCursorと一緒に使用する方法をステップバイステップで説明しています。 -# データ品質メトリクス +# 🎓 実務者のための重要概念 -Dingoはルールベースおよびプロンプトベースの評価メトリクスを通じて包括的なデータ品質評価を提供します。これらのメトリクスは、効果性、完全性、類似性、セキュリティなどの複数の品質次元をカバーしています。 +## Dingo を本番環境で使用できる理由 -📊 **[完全なメトリクス文書を表示 →](docs/metrics.md)** +### 1. **マルチフィールド評価パイプライン** +1回の実行で異なるフィールドに異なる品質チェックを適用: +```python +"evaluator": [ + {"fields": {"content": "isbn"}, "evals": [{"name": "RuleIsbn"}]}, + {"fields": {"content": "title"}, "evals": [{"name": "RuleAbnormalChar"}]}, + {"fields": {"content": "description"}, "evals": [{"name": "LLMTextQualityV5"}]} +] +``` +**重要性**:各フィールドごとに別々のスクリプトを書かずに構造化データ(データベーステーブルなど)を評価できます。 -評価システムには以下が含まれます: -- **テキスト品質評価メトリクス**: DataMan手法と拡張された多次元評価を使用した事前学習データの品質評価 -- **SFTデータ評価メトリクス**: 教師ありファインチューニングデータの正直、有用、無害評価 -- **分類メトリクス**: トピック分類とコンテンツ分類 -- **マルチモーダル評価メトリクス**: 画像分類と関連性評価 -- **ルールベース品質メトリクス**: ヒューリスティックルールによる効果性と類似性検出を用いた自動品質チェック -- **事実性評価メトリクス**: GPT-5 System Cardに基づく二段階事実性評価 -- など +### 2. **大規模データセットのストリーミング処理** +SQL データソースは SQLAlchemy のサーバーサイドカーソルを使用: +```python +# メモリオーバーフローなしで数十億行を処理 +for data in dataset.get_data(): # 1行ずつyield + result = evaluator.eval(data) +``` +**重要性**:中間ファイルにエクスポートすることなく本番データベースを処理できます。 + +### 3. **メモリ内フィールド分離** +RAG 評価は異なるフィールド組み合わせ間のコンテキストリークを防止: +``` +outputs/ +├── user_input,response,retrieved_contexts/ # Faithfulness グループ +└── user_input,response/ # Answer Relevancy グループ +``` +**重要性**:複数のフィールド組み合わせを評価する際のメトリクス計算の正確性を保証。 -大部分のメトリクスは学術的なソースによって支持されており、客観性と科学的厳密性を保証しています。 +### 4. **ルール-LLM ハイブリッド戦略** +高速ルール(100% カバレッジ)とサンプリング LLM チェック(10% カバレッジ)を組み合わせ: +```python +"evals": [ + {"name": "RuleAbnormalChar"}, # 高速、全データで実行 + {"name": "LLMTextQualityV5"} # コスト高、必要に応じてサンプリング +] +``` +**重要性**:本番規模の評価でコストとカバレッジのバランスを取る。 -### 評価でのLLM評価の使用 +### 5. **登録による拡張性** +カスタムルール、プロンプト、モデルのための明確なプラグインアーキテクチャ: +```python +@Model.rule_register('QUALITY_BAD_CUSTOM', ['default']) +class MyCustomRule(BaseRule): + @classmethod + def eval(cls, input_data: Data) -> EvalDetail: + # あなたのロジック + return EvalDetail(status=False, label=['QUALITY_GOOD']) +``` +**重要性**:コードベースをフォークせずにドメイン固有のニーズに適応。 -これらの評価プロンプトを評価で使用するには、設定で指定します: +--- + +# 📚 データ品質メトリクス + +Dingo は **70以上の評価メトリクス**を提供し、複数の次元にわたってルールベースの速度と LLM ベースの深度を組み合わせます。 + +## メトリクスカテゴリ + +| カテゴリ | 例 | 使用例 | +|----------|----------|----------| +| **事前学習テキスト品質** | 完全性、有効性、類似性、セキュリティ | LLM 事前学習データフィルタリング | +| **SFT データ品質** | 正直、有用、無害 (3H) | 指示ファインチューニングデータ | +| **RAG 評価** | 忠実度、コンテキスト精度、答え関連性 | RAG システム評価 | +| **幻覚検出** | HHEM-2.1-Open、事実性チェック | 本番 AI 信頼性 | +| **分類** | トピック分類、コンテンツラベリング | データ整理 | +| **マルチモーダル** | 画像テキスト関連性、VLM 品質 | ビジュアル言語データ | +| **セキュリティ** | PII 検出、Perspective API 毒性 | プライバシーと安全性 | + +📊 **[完全なメトリクス文書を表示 →](docs/metrics.md)** +📖 **[RAG 評価ガイド →](docs/rag_evaluation_metrics_zh.md)** +🔍 **[幻覚検出ガイド →](docs/hallucination_guide.md)** +✅ **[事実性評価ガイド →](docs/factcheck_guide.md)** + +大部分のメトリクスは学術研究に裏付けられており、科学的厳密性を確保しています。 + +## メトリクスの迅速な使用 ```python llm_config = { @@ -221,67 +298,137 @@ llm_config = { "key": "YOUR_API_KEY", "api_url": "https://api.openai.com/v1/chat/completions" } + input_data = { - # Other parameters... "evaluator": [ { "fields": {"content": "content"}, "evals": [ - {"name": "LLMTextRepeat", "config": llm_config} - ], + {"name": "RuleAbnormalChar"}, # ルールベース(高速) + {"name": "LLMTextQualityV5", "config": llm_config} # LLMベース(深度) + ] } ] } ``` -これらのプロンプトは、特定の品質次元に焦点を当てたり、特定のドメイン要件に適応させるためにカスタマイズできます。適切なLLMモデルと組み合わせることで、これらのプロンプトは複数の次元にわたる包括的なデータ品質評価を可能にします。 +**カスタマイズ**:すべてのプロンプトは `dingo/model/llm/` ディレクトリに定義されています(カテゴリ別に整理:`text_quality/`、`rag/`、`hhh/` など)。ドメイン固有のニーズに合わせて拡張または変更できます。 + -### 幻覚検出とRAGシステム評価 +# 🌟 機能ハイライト -HHEM-2.1-Openローカル推論とLLMベース評価を含む、Dingoの幻覚検出機能の使用に関する詳細なガイダンス: +## 📊 マルチソースデータ統合 -📖 **[幻覚検出ガイドを見る →](docs/hallucination_guide.md)** +**多様なデータソース** - データがある場所に接続 +✅ **ローカルファイル**:JSONL、CSV、TXT、Parquet +✅ **SQL データベース**:PostgreSQL、MySQL、SQLite、Oracle、SQL Server(ストリーミング処理対応) +✅ **クラウドストレージ**:S3 および S3 互換ストレージ +✅ **ML プラットフォーム**:HuggingFace データセットの直接統合 -### 事実性評価 +**エンタープライズ対応 SQL サポート** - 本番データベース統合 +✅ 数十億規模のデータセットのメモリ効率的なストリーミング +✅ 接続プールと自動リソースクリーンアップ +✅ 複雑な SQL クエリ(JOIN、WHERE、集計) +✅ SQLAlchemy による複数の方言サポート -Dingoの二段階事実性評価システムの使用に関する詳細なガイダンス: +**マルチフィールド品質チェック** - 異なるフィールドに異なるルール +✅ 並列評価パイプライン(例:ISBN 検証 + テキスト品質を同時実行) +✅ フィールドエイリアスとネストされたフィールド抽出(`user.profile.name`) +✅ フィールドごとに独立した結果レポート +✅ 柔軟なデータ変換のための ETL パイプラインアーキテクチャ -📖 **[事実性評価ガイドを見る →](docs/factcheck_guide.md)** +--- +## 🤖 RAG システム評価 -# 機能ハイライト +**5つの学術的裏付けのある指標** - RAGAS、DeepEval、TruLens 研究に基づく +✅ **忠実度(Faithfulness)**:答え-コンテキストの一貫性(幻覚検出) +✅ **答え関連性(Answer Relevancy)**:答え-クエリの整合性 +✅ **コンテキスト精度(Context Precision)**:検索精度 +✅ **コンテキスト再現率(Context Recall)**:検索再現率 +✅ **コンテキスト関連性(Context Relevancy)**:コンテキスト-クエリ関連性 -## マルチソース・マルチモーダルサポート +**包括的なレポート** - 自動集計統計 +✅ 各メトリクスの平均、最小、最大、標準偏差 +✅ フィールド別にグループ化された結果 +✅ バッチおよび単一評価モード -- **データソース**: ローカルファイル、Hugging Faceデータセット、S3ストレージ -- **データタイプ**: 事前学習、ファインチューニング、評価データセット -- **データモダリティ**: テキストと画像 +📖 **[RAG 評価ガイドを見る →](docs/rag_evaluation_metrics_zh.md)** -## ルールベース・モデルベース評価 +--- -- **内蔵ルール**: 20以上の一般的なヒューリスティック評価ルール -- **LLM統合**: OpenAI、Kimi、ローカルモデル(例:Llama3) -- **幻覚検出**: HHEM-2.1-OpenローカルモデルとGPTベースの評価 -- **RAGシステム評価**: 応答一貫性とコンテキスト整合性評価 -- **カスタムルール**: 独自のルールとモデルで簡単に拡張 -- **セキュリティ評価**: Perspective API統合 +## 🧠 ハイブリッド評価システム -## 柔軟な使用方法 +**ルールベース** - 高速、決定論的、コスト効率 +✅ 30以上の組み込みルール(テキスト品質、フォーマット、PII 検出) +✅ 正規表現、ヒューリスティック、統計チェック +✅ カスタムルール登録 -- **インターフェース**: CLIとSDKオプション -- **統合**: 他のプラットフォームとの簡単な統合 -- **実行エンジン**: ローカルとSpark +**LLM ベース** - 深い意味理解 +✅ OpenAI(GPT-4o、GPT-3.5)、DeepSeek、Kimi +✅ ローカルモデル(Llama3、Qwen) +✅ ビジョン言語モデル(InternVL、Gemini) +✅ カスタムプロンプト登録 -## 包括的なレポート +**拡張可能なアーキテクチャ** +✅ プラグインベースのルール/プロンプト/モデル登録 +✅ 明確な関心の分離(エージェント、ツール、オーケストレーション) +✅ ドメイン固有のカスタマイズ -- **品質メトリクス**: 7次元品質評価 -- **トレーサビリティ**: 異常追跡のための詳細レポート +--- -# ユーザーガイド +## 🚀 柔軟な実行と統合 + +**複数のインターフェース** +✅ 迅速なチェックのための CLI +✅ 統合のための Python SDK +✅ IDE 用 MCP(モデルコンテキストプロトコル)サーバー(Cursor など) + +**スケーラブルな実行** +✅ 迅速な反復のためのローカル実行 +✅ 分散処理のための Spark 実行 +✅ 設定可能な並行性とバッチ処理 + +**データソース** +✅ **ローカルファイル**:JSONL、CSV、TXT、Parquet フォーマット +✅ **Hugging Face**:HF データセットハブとの直接統合 +✅ **S3 ストレージ**:AWS S3 および S3 互換ストレージ +✅ **SQL データベース**:PostgreSQL、MySQL、SQLite、Oracle、SQL Server(大規模データのストリーミング処理) + +**モダリティ** +✅ テキスト(チャット、ドキュメント、コード) +✅ 画像(VLM サポート) +✅ マルチモーダル(テキスト+画像の一貫性) + +--- + +## 📈 豊富なレポートと可視化 + +**多層レポート** +✅ 全体スコア付き Summary JSON +✅ フィールドレベルの内訳 +✅ ルール違反ごとの詳細情報 +✅ タイプと名前の分布 + +**GUI 可視化** +✅ 組み込み Web インターフェース +✅ インタラクティブなデータ探索 +✅ 異常追跡 + +**メトリクス集計** +✅ 自動統計(avg、min、max、std_dev) +✅ フィールド別にグループ化されたメトリクス +✅ 全体品質スコア + +# 📖 ユーザーガイド ## カスタムルール、プロンプト、モデル -組み込みルールが要件を満たさない場合、カスタムルールを作成できます: +Dingo はドメイン固有のニーズに対応する柔軟な拡張メカニズムを提供します。 + +**例:** +- [カスタムルール](examples/register/sdk_register_rule.py) +- [カスタムモデル](examples/register/sdk_register_llm.py) ### カスタムルール例 @@ -320,7 +467,6 @@ class MyCustomModel(BaseOpenAI): 詳細な例については以下をご覧ください: - [ルール登録](examples/register/sdk_register_rule.py) -- [プロンプト登録](examples/register/sdk_register_prompt.py) - [モデル登録](examples/register/sdk_register_llm.py) ## 実行エンジン @@ -381,7 +527,6 @@ result = executor.execute() レポートの説明: 1. **score**: `num_good` / `total` 2. **type_ratio**: タイプの数 / 総数, 例: `QUALITY_BAD_COMPLETENESS` / `total` -3. **name_ratio**: 名前の数 / 総数, 例: `QUALITY_BAD_COMPLETENESS-RuleColonEnd` / `total` サマリー例: ```json @@ -405,14 +550,16 @@ result = executor.execute() } ``` -# 今後の計画 +# 🔮 今後の計画 -- [ ] より豊富なグラフィックとテキスト評価指標 -- [ ] 音声・動画データモダリティ評価 -- [ ] 小規模モデル評価(fasttext、Qurating) -- [ ] データ多様性評価 +**近日公開予定の機能**: +- [ ] **Agent-as-a-Judge** - 多ラウンド反復評価 +- [ ] **SaaS プラットフォーム** - API アクセスとダッシュボードを備えたホスト型評価サービス +- [ ] **音声・動画モダリティ** - テキスト/画像を超えた拡張 +- [ ] **多様性メトリクス** - 統計的多様性評価 +- [ ] **リアルタイム監視** - 本番パイプラインでの継続的品質チェック -# 制限事項 +## 制限事項 現在の組み込み検出ルールとモデル手法は、一般的なデータ品質問題に焦点を当てています。専門的な評価ニーズについては、検出ルールのカスタマイズを推奨します。 diff --git a/README_zh-CN.md b/README_zh-CN.md index ebf7a2bc..6b567bfe 100644 --- a/README_zh-CN.md +++ b/README_zh-CN.md @@ -56,7 +56,23 @@ # Dingo 介绍 -Dingo是一款数据质量评估工具,帮助你自动化检测数据集中的数据质量问题。Dingo提供了多种内置的规则和模型评估方法,同时也支持自定义评估方法。Dingo支持常用的文本数据集和多模态数据集,包括预训练数据集、微调数据集和评测数据集。此外,Dingo支持多种使用方式,包括本地CLI和SDK,便于集成到各种评测平台,如[OpenCompass](https://github.com/open-compass/opencompass)等。 +**Dingo 是一款全面的 AI 数据、模型和应用质量评估工具**,专为机器学习工程师、数据工程师和 AI 研究人员设计。它帮助你系统化地评估和改进训练数据、微调数据集和生产AI系统的质量。 + +## 为什么选择 Dingo? + +🎯 **生产级质量检查** - 从预训练数据集到 RAG 系统,确保你的 AI 获得高质量数据 + +🗄️ **多数据源集成** - 无缝连接本地文件、SQL 数据库(PostgreSQL/MySQL/SQLite)、HuggingFace 数据集和 S3 存储 + +🔍 **多字段评估** - 对不同字段并行应用不同的质量规则(例如:对 `isbn` 字段进行 ISBN 验证,对 `title` 字段进行文本质量检查) + +🤖 **RAG 系统评估** - 使用 5 个学术支持的指标全面评估检索和生成质量 + +🧠 **LLM 与规则混合** - 结合快速启发式规则(30+ 内置规则)和基于 LLM 的深度评估 + +🚀 **灵活执行** - 本地运行快速迭代,或使用 Spark 扩展到数十亿级数据集 + +📊 **丰富报告** - 详细的质量报告,带有 GUI 可视化和字段级洞察 ## 架构图 @@ -196,26 +212,87 @@ https://github.com/user-attachments/assets/aca26f4c-3f2e-445e-9ef9-9331c4d7a37b 此视频展示了关于 Dingo MCP 服务端与 Cursor 一起使用的分步演示。 -# 数据质量指标 +# 🎓 实践者关键概念 -Dingo通过基于规则和基于提示的评估指标提供全面的数据质量评估。这些指标涵盖多个质量维度,包括有效性、完整性、相似性、安全性等。 +## 让 Dingo 适用于生产环境的原因? -📊 **[查看完整指标文档 →](docs/metrics.md)** +### 1. **多字段评估流水线** +在单次运行中对不同字段应用不同的质量检查: +```python +"evaluator": [ + {"fields": {"content": "isbn"}, "evals": [{"name": "RuleIsbn"}]}, + {"fields": {"content": "title"}, "evals": [{"name": "RuleAbnormalChar"}]}, + {"fields": {"content": "description"}, "evals": [{"name": "LLMTextQualityV5"}]} +] +``` +**为什么重要**:无需为每个字段编写单独的脚本即可评估结构化数据(如数据库表)。 -我们的评估系统包括: -- **文本质量评估指标**:使用DataMan方法论和增强的多维评估进行预训练数据质量评估 -- **SFT数据评估指标**:针对监督微调数据的诚实、有帮助、无害评估 -- **分类指标**:主题分类和内容分类 -- **多模态评估指标**:图像分类和相关性评估 -- **基于规则的质量指标**:使用启发式规则进行效果性和相似性检测的自动化质量检查 -- **事实性评估指标**:基于 GPT-5 System Card 的两阶段事实性评估 -- 等等 +### 2. **大数据集流式处理** +SQL 数据源使用 SQLAlchemy 的服务器端游标: +```python +# 处理数十亿行数据而不会内存溢出 +for data in dataset.get_data(): # 每次yield一行 + result = evaluator.eval(data) +``` +**为什么重要**:无需导出到中间文件即可处理生产数据库。 -大部分指标都由学术来源支持,以确保客观性和科学严谨性。 +### 3. **内存中的字段隔离** +RAG 评估防止不同字段组合之间的上下文泄漏: +``` +outputs/ +├── user_input,response,retrieved_contexts/ # Faithfulness 组 +└── user_input,response/ # Answer Relevancy 组 +``` +**为什么重要**:评估多个字段组合时保证指标计算准确。 -### 在评估中使用LLM评估 +### 4. **混合规则-LLM 策略** +结合快速规则(100% 覆盖)和采样 LLM 检查(10% 覆盖): +```python +"evals": [ + {"name": "RuleAbnormalChar"}, # 快速,在所有数据上运行 + {"name": "LLMTextQualityV5"} # 昂贵,按需采样 +] +``` +**为什么重要**:平衡生产规模评估的成本和覆盖率。 -要在评估中使用这些评估prompt,请在配置中指定它们: +### 5. **通过注册实现可扩展性** +清晰的插件架构用于自定义规则、prompt 和模型: +```python +@Model.rule_register('QUALITY_BAD_CUSTOM', ['default']) +class MyCustomRule(BaseRule): + @classmethod + def eval(cls, input_data: Data) -> EvalDetail: + # 你的逻辑 + return EvalDetail(status=False, label=['QUALITY_GOOD']) +``` +**为什么重要**:适应特定领域需求而无需分叉代码库。 + +--- + +# 📚 数据质量指标 + +Dingo 提供 **70+ 评估指标**,跨多个维度,结合基于规则的速度和基于 LLM 的深度。 + +## 指标类别 + +| 类别 | 示例 | 使用场景 | +|----------|----------|----------| +| **预训练文本质量** | 完整性、有效性、相似性、安全性 | LLM 预训练数据过滤 | +| **SFT 数据质量** | 诚实、有帮助、无害 (3H) | 指令微调数据 | +| **RAG 评估** | 忠实度、上下文精度、答案相关性 | RAG 系统评估 | +| **幻觉检测** | HHEM-2.1-Open、事实性检查 | 生产 AI 可靠性 | +| **分类** | 主题分类、内容标注 | 数据组织 | +| **多模态** | 图文相关性、VLM 质量 | 视觉语言数据 | +| **安全性** | PII 检测、Perspective API 毒性 | 隐私和安全 | + +📊 **[查看完整指标文档 →](docs/metrics.md)** +📖 **[RAG 评估指南 →](docs/rag_evaluation_metrics_zh.md)** +🔍 **[幻觉检测指南 →](docs/hallucination_guide.md)** +✅ **[事实性评估指南 →](docs/factcheck_guide.md)** + +大部分指标都有学术研究支持,以确保科学严谨性。 + +## 快速使用指标 ```python llm_config = { @@ -223,71 +300,137 @@ llm_config = { "key": "YOUR_API_KEY", "api_url": "https://api.openai.com/v1/chat/completions" } + input_data = { - # Other parameters... "evaluator": [ { "fields": {"content": "content"}, "evals": [ - {"name": "LLMTextRepeat", "config": llm_config} - ], + {"name": "RuleAbnormalChar"}, # 基于规则(快速) + {"name": "LLMTextQualityV5", "config": llm_config} # 基于LLM(深度) + ] } ] } ``` -您可以自定义这些prompt,以关注特定的质量维度或适应特定的领域需求。当与适当的LLM模型结合时,这些prompt能够在多个维度上对数据质量进行全面评估。 +**自定义**:所有 prompts 都定义在 `dingo/model/llm/` 目录中(按类别组织:`text_quality/`、`rag/`、`hhh/` 等)。可针对特定领域需求进行扩展或修改。 + + +# 🌟 功能亮点 + +## 📊 多源数据集成 + +**多样化数据源** - 连接到你的数据所在之处 +✅ **本地文件**:JSONL、CSV、TXT、Parquet +✅ **SQL 数据库**:PostgreSQL、MySQL、SQLite、Oracle、SQL Server(支持流式处理) +✅ **云存储**:S3 和 S3 兼容存储 +✅ **ML 平台**:直接集成 HuggingFace 数据集 + +**企业级 SQL 支持** - 生产数据库集成 +✅ 数十亿级数据集的内存高效流式处理 +✅ 连接池和自动资源清理 +✅ 复杂 SQL 查询(JOIN、WHERE、聚合) +✅ 通过 SQLAlchemy 支持多种方言 + +**多字段质量检查** - 不同字段使用不同规则 +✅ 并行评估流水线(例如:ISBN 验证 + 文本质量同时进行) +✅ 字段别名和嵌套字段提取(`user.profile.name`) +✅ 每个字段独立结果报告 +✅ 灵活数据转换的 ETL 流水线架构 + +--- + +## 🤖 RAG 系统评估 + +**5 个学术支持的指标** - 基于 RAGAS、DeepEval、TruLens 研究 +✅ **忠实度(Faithfulness)**:答案-上下文一致性(幻觉检测) +✅ **答案相关性(Answer Relevancy)**:答案-查询对齐 +✅ **上下文精度(Context Precision)**:检索精度 +✅ **上下文召回(Context Recall)**:检索召回 +✅ **上下文相关性(Context Relevancy)**:上下文-查询相关性 + +**全面报告** - 自动聚合统计 +✅ 每个指标的平均值、最小值、最大值、标准差 +✅ 按字段分组的结果 +✅ 批量和单次评估模式 -### 幻觉检测和RAG系统评估 +📖 **[查看 RAG 评估指南 →](docs/rag_evaluation_metrics_zh.md)** -有关使用Dingo幻觉检测功能的详细指导,包括HHEM-2.1-Open本地推理和基于LLM的评估: +--- -📖 **[查看幻觉检测指南 →](docs/hallucination_guide.md)** +## 🧠 混合评估系统 -有关RAG评估指标的完整指导,包括忠实度、上下文精度、答案相关性、上下文召回和上下文相关性: +**基于规则** - 快速、确定性、成本效益高 +✅ 30+ 内置规则(文本质量、格式、PII 检测) +✅ 正则表达式、启发式、统计检查 +✅ 自定义规则注册 -📖 **[查看RAG评估指标指南 →](docs/rag_evaluation_metrics_zh.md)** +**基于 LLM** - 深度语义理解 +✅ OpenAI(GPT-4o、GPT-3.5)、DeepSeek、Kimi +✅ 本地模型(Llama3、Qwen) +✅ 视觉语言模型(InternVL、Gemini) +✅ 自定义 prompt 注册 -### 事实性评估 +**可扩展架构** +✅ 基于插件的规则/prompt/模型注册 +✅ 清晰的关注点分离(agents、tools、orchestration) +✅ 特定领域定制 -有关使用Dingo两阶段事实性评估系统的详细指导: +--- -📖 **[查看事实性评估指南 →](docs/factcheck_guide.md)** +## 🚀 灵活执行与集成 +**多种接口** +✅ CLI 用于快速检查 +✅ Python SDK 用于集成 +✅ MCP(模型上下文协议)服务器用于 IDE(Cursor 等) -# 功能亮点 +**可扩展执行** +✅ 本地执行器用于快速迭代 +✅ Spark 执行器用于分布式处理 +✅ 可配置并发和批处理 -## 多源和多模态支持 +**数据源** +✅ **本地文件**:JSONL、CSV、TXT、Parquet 格式 +✅ **Hugging Face**:直接与 HF 数据集中心集成 +✅ **S3 存储**:AWS S3 和 S3 兼容存储 +✅ **SQL 数据库**:PostgreSQL、MySQL、SQLite、Oracle、SQL Server(大规模数据流式处理) -- **数据源**:本地文件、Hugging Face数据集、S3存储 -- **数据类型**:预训练、微调和评估数据集 -- **数据模态**:文本和图像 +**模态** +✅ 文本(聊天、文档、代码) +✅ 图像(支持 VLM) +✅ 多模态(文本+图像一致性) -## 基于规则和模型的评估 +--- -- **内置规则**:20多种通用启发式评估规则 -- **LLM集成**:OpenAI、Kimi和本地模型(如Llama3) -- **幻觉检测**:HHEM-2.1-Open本地模型和基于GPT的评估 -- **RAG系统评估**:响应一致性和上下文对齐评估 -- **自定义规则**:轻松扩展自己的规则和模型 -- **安全评估**:Perspective API集成 +## 📈 丰富的报告和可视化 -## 灵活的使用方式 +**多层级报告** +✅ 带有总体评分的 Summary JSON +✅ 字段级分解 +✅ 每条规则违规的详细信息 +✅ 类型和名称分布 -- **接口**:CLI和SDK选项 -- **集成**:易于与其他平台集成 -- **执行引擎**:本地和Spark +**GUI 可视化** +✅ 内置 Web 界面 +✅ 交互式数据探索 +✅ 异常追踪 -## 全面报告 +**指标聚合** +✅ 自动统计(avg、min、max、std_dev) +✅ 按字段分组的指标 +✅ 总体质量评分 -- **质量指标**:7维质量评估 -- **可追溯性**:异常追踪的详细报告 +# 📖 用户指南 -# 使用指南 +## 自定义规则、Prompt 和模型 -## 自定义规则、Prompt和模型 +Dingo 提供灵活的扩展机制来满足特定领域需求。 -如果内置规则不满足您的需求,您可以创建自定义规则: +**示例:** +- [自定义规则](examples/register/sdk_register_rule.py) +- [自定义模型](examples/register/sdk_register_llm.py) ### 自定义规则示例 @@ -326,7 +469,6 @@ class MyCustomModel(BaseOpenAI): 查看更多示例: - [注册规则](examples/register/sdk_register_rule.py) -- [注册Prompts](examples/register/sdk_register_prompt.py) - [注册模型](examples/register/sdk_register_llm.py) ## 执行引擎 @@ -387,7 +529,6 @@ result = executor.execute() 报告说明: 1. **score**: `num_good` / `total` 2. **type_ratio**: 类型的数量 / 总数, 例如: `QUALITY_BAD_COMPLETENESS` / `total` -3. **name_ratio**: 名称的数量 / 总数, 例如: `QUALITY_BAD_COMPLETENESS-RuleColonEnd` / `total` 概要示例: ```json @@ -411,14 +552,16 @@ result = executor.execute() } ``` -# 未来计划 +# 🔮 未来计划 -- [ ] 更丰富的图文评测指标 -- [ ] 音频和视频数据模态评测 -- [ ] 小模型评测(如fasttext、Qurating) -- [ ] 数据多样性评测 +**即将推出的功能**: +- [ ] **Agent-as-a-Judge** - 多轮迭代评估 +- [ ] **SaaS 平台** - 托管评估服务,提供 API 访问和仪表板 +- [ ] **音频和视频模态** - 扩展到文本/图像之外 +- [ ] **多样性指标** - 统计多样性评估 +- [ ] **实时监控** - 生产流水线中的持续质量检查 -# 局限性 +## 局限性 当前内置的检测规则和模型方法主要关注常见的数据质量问题。对于特殊评估需求,我们建议定制化检测规则。