# YXAI

**Repository Path**: hezoo/yxai

## Basic Information

- **Project Name**: YXAI
- **Description**: 用于AI竞赛数据质量智能诊断 Agent 
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-21
- **Last Updated**: 2026-04-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Data Quality Agent

> 亚信黑客马拉松初赛 · 赛题 3：数据质量智能诊断 Agent

## 项目简介

输入 CSV/Parquet 文件，LLM 驱动的 Agent 自动完成数据质量诊断，输出结构化报告（JSON + HTML）。

## 功能特性

- ✅ 字段类型推断与校验（LLM + 规则双轨）
- ✅ 缺失、重复、异常值检测（IQR / Z-score / DBSCAN）
- ✅ 逻辑一致性检查（日期先后、金额正负等）
- ✅ 分布漂移检测（PSI）
- ✅ 可执行修复建议（SQL / Python 片段）
- ✅ 结构化报告（JSON + HTML，含交互图表）
- ✅ 大文件采样诊断（≥100MB 自动采样）
- ✅ Web UI 交互（文件上传 / 进度查看 / 报告展示）

## 技术栈

| 模块 | 技术 |
|------|------|
| 后端框架 | FastAPI ≥ 0.110 |
| 数据处理 | pandas ≥ 2.0, polars, PyArrow |
| 异常检测 | scikit-learn |
| 报告生成 | Jinja2, Plotly |
| 前端 | Vue3, Element Plus |
| 容器化 | Docker, Docker Compose |
| LLM | 统一网关（组委会提供） |

## 快速启动

### 前置依赖

- Python ≥ 3.10
- Node.js ≥ 18
- Docker & Docker Compose

### 一键启动

```bash
make run
```

或手动启动：

```bash
# 后端
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

# 前端
cd frontend
npm install
npm run dev
```

访问 http://localhost:5173

### API 文档

启动后访问 http://localhost:8000/docs

## 项目结构

```
data-quality-agent/
├── SPEC.md                  # 项目规格说明书
├── README.md                # 本文件
├── Makefile                 # 一键启动脚本
├── docker-compose.yml        # Docker Compose 配置
├── backend/
│   ├── app/
│   │   ├── main.py          # FastAPI 入口
│   │   ├── core/
│   │   │   ├── config.py    # 配置管理
│   │   │   └── llm_gateway.py # LLM 网关代理
│   │   ├── api/
│   │   │   └── v1/
│   │   │       ├── diagnose.py   # 诊断接口
│   │   │       └── reports.py    # 报告接口
│   │   ├── diagnosis/
│   │   │   ├── engine.py        # 诊断引擎入口
│   │   │   ├── profiler.py      # 数据概览
│   │   │   ├── type_inference.py # 类型推断
│   │   │   ├── anomaly.py       # 异常检测
│   │   │   ├── consistency.py   # 一致性检查
│   │   │   └── fixer.py         # 修复建议生成
│   │   ├── services/
│   │   │   ├── file_parser.py   # 文件解析
│   │   │   └── report_gen.py    # 报告生成
│   │   ├── models/
│   │   │   └── schemas.py       # Pydantic 数据模型
│   │   └── utils/
│   │       ├── sampler.py       # 采样器
│   │       └── validator.py     # 验证器
│   ├── tests/
│   │   ├── test_diagnosis.py
│   │   └── test_anomaly.py
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── views/
│   │   │   └── DiagnoseView.vue
│   │   └── components/
│   │       ├── FileUploader.vue
│   │       ├── ReportPanel.vue
│   │       └── ProgressTracker.vue
│   └── package.json
├── docs/
│   └── architecture.md
└── scripts/
    └── generate_sample_data.py
```

## 接口概览

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | /api/v1/diagnose | 上传文件，启动诊断任务 |
| GET | /api/v1/diagnose/{task_id} | 查询诊断任务状态和结果 |
| GET | /api/v1/reports/{task_id} | 下载 HTML 报告 |
| GET | /api/v1/reports/{task_id}/json | 下载 JSON 报告 |
| POST | /api/v1/followup | 对报告进行追问 |

## 评分维度

| 维度 | 分值 |
|------|------|
| 指标达成 | ~30 |
| 代码工程质量 | 20 |
| 系统体验/鲁棒性 | ~15 |
| 创新性 | ~10 |
| 技术先进性 | ~10 |
| 演示效果 | ~15 |

## 许可证

MIT License