Zohue/dq-copilot-ai-data-quality
GitHub: Zohue/dq-copilot-ai-data-quality
一款基于 RAG 和多智能体架构的 AI 数据质量平台，通过自然语言生成规则、根因分析和规则生命周期管理实现数据质量治理的自动化闭环。
Stars: 24 | Forks: 0
# DQ Copilot
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](#roadmap)
## 为什么选择 DQ Copilot
大多数开源数据质量工具（Great Expectations、Soda Core、dbt tests、Elementary）都**擅长执行规则** —— 但数据质量中最困难的部分是规则*之外*的所有事情：
- **新规则从何而来？** 分析师一次只能手动编写一条 YAML 或 SQL 规则。
- **为什么这一行会校验失败？** 你只能查看日志并在 Slack 上提问。
- **哪些规则仍然有用？** 没人知道；规则集只会无限膨胀。
- **`customer_status` 的业务定义在哪里？** 在某个人的 Confluence 文档里。
DQ Copilot 将**一个基于 RAG 的 AI Copilot 构建在规则执行层之上**，从而形成闭环：
```
business definition (NL) ──▶ Rule Proposer Agent ──▶ Rule Reviewer Agent ──▶ Production
│
finding ◀──────── Detectors (SQL / Source-Diff / Stats / Drift) ◀──────┘
│
└─▶ Root Cause Agent (RAG: history + lineage + similar cases)
│
└─▶ Fix suggestion → knowledge replay → Rule Evolver Agent
│
└─▶ retire / merge / blind spots
```
## 功能对比
| 功能 | Great Expectations | Soda Core | dbt tests | Elementary | DataHub | **DQ Copilot** |
| -------------------------- | ------------------ | --------- | --------- | ---------- | ------- | -------------- |
| 规则执行 | ✅ | ✅ | ✅ | ➖ | ❌ | ✅ |
| 字段级数据目录 | ➖ | ➖ | ➖ | ➖ | ✅ | ✅ |
| 从自然语言生成 AI 规则 | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| 基于历史的根因分析 | ❌ | ❌ | ❌ | 部分 | ❌ | ✅ |
| 规则生命周期（淘汰/合并） | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| 跨源对比 | ➖ | ➖ | ❌ | ❌ | ❌ | ✅ |
| LLM-as-judge 软规则 | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| 厂商中立的 LLM | n/a | n/a | n/a | n/a | n/a | ✅ (Azure/OpenAI/Ollama/DeepSeek) |
| MCP 原生 | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| 许可证 | Apache | Apache | Apache | Apache | Apache | MIT |
DQ Copilot **并不**取代你的数据仓库、BI 工具或核心数据目录。它是连接它们的 AI 层，使规则管理能够自我维持。
## 5 分钟快速开始
### 推荐的默认 AI 设置
DQ Copilot 现在默认使用这种对本地友好的 AI 配置：
- LLM: `deepseek / deepseek-v4-flash`
- Embeddings: `ollama / nomic-embed-text`，地址为 `http://127.0.0.1:11434`
- 向量数据库: 本地 ChromaDB
- 隐私: 默认设置为 `allow_egress: false`
请勿提交 API 密钥。对于 DeepSeek，请在设置前导出 `DEEPSEEK_API_KEY`，或者稍后在仪表板的 Settings（设置）页面中添加密钥。`config/settings.local.yaml` 已被 Git 忽略，是存放本地密钥的正确位置。
### 在 macOS / MacBook 上一键进行项目设置
```
git clone https://github.com/zhy13040291896-blip/dq-copilot-ai-data-quality.git
cd dq-copilot-ai-data-quality
python3 -m venv .venv
source .venv/bin/activate
export DEEPSEEK_API_KEY="" # optional; can also be filled in the UI later
python scripts/install.py
```
`scripts/install.py` 会安装 Python 包，写入本地默认配置，在可能的情况下启动/拉取 Ollama，注入演示数据，并打印仪表板启动命令。在 macOS 上，如果缺少 `ollama` 且有可用的 Homebrew，安装程序将尝试运行 `brew install ollama`；否则请手动安装：
```
brew install ollama
ollama serve
ollama pull nomic-embed-text
```
启动仪表板：
```
dq-copilot dashboard
# 或
python scripts/start_dashboard.py --host localhost --port 8501
```
打开 `http://localhost:8501`。
### 手动安装
```
git clone https://github.com/zhy13040291896-blip/dq-copilot-ai-data-quality.git
cd dq-copilot-ai-data-quality
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,ai,documents]"
python scripts/install.py --no-seed --skip-ollama
```
然后在仪表板的 **Settings**（设置）页面配置提供商。该页面会写入 `config/settings.local.yaml`；请避免手动编辑或提交密钥。
DQ Copilot 也可以在没有任何 LLM 密钥的情况下以仅检测模式运行。一旦配置了提供商，规则生成、聊天和根因分析等 AI 功能就会自动激活。
## 一张图看懂架构
```
┌────────────────────────────────────────────────────────────────────┐
│ Surface MCP Server │ CLI │ Python SDK │ Dashboard │
├────────────────────────────────────────────────────────────────────┤
│ Copilot Rule Proposer │ Root Causer │ Rule Evolver │
│ (RAG + LLM Agents) │ Rule Reviewer (adversarial gate) │
├────────────────────────────────────────────────────────────────────┤
│ Detector Plane SQL │ SourceDiff │ Stats │ SchemaDrift │ LLM │
│ (pluggable) + community detectors via entry-points │
├────────────────────────────────────────────────────────────────────┤
│ Catalog Asset / Field / Owner / SLA / lineage │
│ (field is first-class) Built-in SQLite ⇄ DataHub / OpenMetadata │
├────────────────────────────────────────────────────────────────────┤
│ Connectors SQLAlchemy (Postgres/MySQL/Snowflake/DuckDB) │
│ fsspec (S3/GCS/local CSV/Parquet) │
└────────────────────────────────────────────────────────────────────┘
```
详情请参阅 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) 和开发规范 [`DEV_SPEC.md`](DEV_SPEC.md)。
## 功能
### 数据目录：字段作为一等公民
- 基于 YAML / SQLite 的资产和字段元数据
- 业务定义、所有者、SLA、敏感度、血缘存根
- 用于从 DataHub / OpenMetadata 导入的适配器接口，避免重复维护事实来源
### 检测平面：一个接口，多种 runtime
- **SqlDetector** — 针对任何可以通过“违反规则的行 ⇒ 失败”表示的规则，面向 SQLAlchemy URL 执行
- **SourceDiffDetector** — 两个数据源（例如操作型数据库与数据仓库）之间的字段级比对
- **StatsDetector** — 分布 / 异常值 / 时间序列异常
- **SchemaDriftDetector** — 针对基线的列增加/删除/类型更改检测
- **LLMJudgeDetector** — 难以用硬 SQL 实现的软约束检查（例如“这个产品描述是否符合其类别？”）
- 自定义检测器通过 Python entry-points 注册：`dq_copilot.detectors`
### Copilot：闭环的四个 Agent
| Agent | 输入 | 输出 |
| ----- | ----- | ------ |
| **Rule Proposer（规则提议者）** | 自然语言业务定义 / 字段 | Detector + 参数 + 规则 YAML |
| **Root Causer（根因分析）** | 一条检查结果 | 疑似原因 + 历史相似案例 + 修复路径 |
| **Rule Evolver（规则演进）** | 所有规则 + 最近的检查结果 | 盲区、重复项、长期失效规则 |
| **Rule Reviewer（规则审查者）** | AI 生成的规则 | 对抗性裁决 → 阻止产生幻觉的规则进入生产环境 |
### 知识库：将你的 DQ 世界进行 RAG 摄取
- 现有的规则 YAML、SQL 文件、检查结果历史、runbook、业务定义
- 混合搜索（BM25 + 稠密 embedding）+ 交叉编码器重排
- 为每个 Copilot agent 提供支持
### 可观测性：基于资产的健康状况，而非基于服务的告警
- 按表 → 字段统计的健康分数，而不是根据哪个检测器触发了告警
- 完整的规则生命周期追踪：草稿 → 审查 → 激活 → 淘汰
- Streamlit 仪表板，无需额外部署
### 设计上的厂商中立
- LLM 提供商：Azure OpenAI、OpenAI、Ollama（本地）、DeepSeek
- Embedding 提供商：Azure OpenAI、OpenAI、Ollama
- 向量数据库：Chroma（为 Qdrant/Pinecone 提供直接替换接口）
- 通过一个配置标志控制数据是否离开你的网络
## 项目结构
```
config/ # Settings, rule YAMLs, prompt templates
docs/
ARCHITECTURE.md # Single-page architecture overview
DQ_COPILOT_USAGE.md # End-user walkthrough
examples/
quickstart/ # DuckDB demo invoked by `dq-copilot quickstart`
src/
dq_core/
catalog/ # Asset / Field metadata layer
detectors/ # BaseDetector + builtin implementations
findings/ # Finding data class + persistence
lifecycle/ # Rule lifecycle state machine
ai_services/
agents/ # Rule Proposer / Root Causer / Evolver / Reviewer
ingestion/ # RAG ingestion (knowledge base)
core/ # RAG retrieval engine
libs/ # Pluggable LLM / Embedding / Evaluator providers
mcp_server/ # MCP tools surface
observability/dashboard/ # Streamlit UI
cli/ # `dq-copilot` CLI
tests/
```
## 路线图
### v0.1 — 基础构建 *(进行中)*
- [ ] 包含默认 SQLite 的数据目录层
- [ ] 检测器抽象 + SqlDetector / SchemaDriftDetector
- [ ] Rule Proposer + Rule Reviewer agent
- [ ] DuckDB 快速开始
- [ ] 刷新 MCP 工具
### v0.2 — 形成闭环
- [ ] Root Causer + Rule Evolver agent
- [ ] SourceDiffDetector 和 StatsDetector
- [ ] 检查结果历史持久化 + 历史记录的 RAG 摄取
- [ ] DataHub 适配器（数据目录导入）
### v0.3 — 面向生产环境
- [ ] 调度器（Airflow / Prefect / cron）
- [ ] Slack / webhook 通知展示面
- [ ] Detector 插件 SDK + 社区插件示例
- [ ] 公开基准测试：在公开数据集上对比 AI 生成的规则与手动编写的规则
### 未来规划
- [ ] OpenMetadata 适配器
- [ ] 具有结构化输出验证的 LLMJudgeDetector
- [ ] 感知血缘的影响分析
- [ ] 多租户部署指南
## 许可证
MIT — 请参阅 [`LICENSE`](LICENSE)。
## 鸣谢
DQ Copilot 建立在 Great Expectations、Soda Core、dbt、Elementary、DataHub 以及更广泛的开源数据质量社区的工作基础之上。其 RAG 引擎借鉴了 LlamaIndex 和 LangChain 的工程模式，但并不依赖于它们中的任何一个。
标签：AI风险缓解, Kubernetes, Python, RAG, 人工智能, 异常检测, 数据治理, 数据质量, 无后门, 根因分析, 用户模式Hook绕过, 逆向工具