# DataCopilot

**Repository Path**: khc-warehouse/data-copilot

## Basic Information

- **Project Name**: DataCopilot
- **Description**: 企业数据库中沉淀大量业务数据，但非技术人员无法写SQL查询，每次看数据都依赖开发排期。
本系统通过AI Agent实现自然语言交互，自动完成“理解意图→生成SQL→查询数据库→推荐图表→前端渲染”，让任何人都能自助分析数据。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-19
- **Last Updated**: 2026-05-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DataCopilot —— 自然语言驱动的数据库自助分析Agent

<p align="center">
  <img src="docs/demo.gif" alt="DataCopilot 运行效果演示" width="700"/>
</p>

## 解决的问题
企业数据库中沉淀大量业务数据，但非技术人员无法写SQL查询，每次看数据都依赖开发排期。
本系统通过AI Agent实现自然语言交互，自动完成"理解意图→生成SQL→查询数据库→推荐图表→前端渲染"，让任何人都能自助分析数据。

## 适用场景
- 企业内部数据自助查询（销售、运营、生产、财务等均可）
- 工业MES数据实时分析
- 电商/零售运营数据看板
- BI报表自动化雏形

## 技术架构
```
用户输入 → Vue3 (对话界面) → FastAPI后端 → Agent主循环
                                          ↓ 工具调用
                              Text-to-SQL → SQLite → 结果集 → 图表决策 → ECharts配置 → 前端渲染
```

- **前端**：Vue3 + Vite + ECharts
- **Agent后端**：Python FastAPI + 自实现Agent循环（不依赖LangChain）
- **模型工厂**：支持 OpenAI / DeepSeek / Mock 多厂商，可扩展（DeepSeek 自动传入 `extra_body` 关闭联网搜索）
- **通信**：SSE 流式输出，前端逐 token 渲染，实时展示思考状态
- **数据库**：SQLite（含模拟MES生产数据）
- **部署**：Docker Compose（规划中）

## 当前进度

### Stage 1: Agent后端核心 (已完成)
| 模块 | 说明 |
|------|------|
| 模型工厂 | `BaseLLM` 抽象 + `OpenAILLM` 实现 + `LLMFactory` 工厂类，扩展新厂商只需继承 |
| Agent主循环 | 自实现tool-calling循环，支持多轮工具调用，不依赖LangChain |
| Text-to-SQL | 自然语言 → LLM生成SQL → 执行查询 → 返回结果 |
| 图表推荐 | 分析数据 → 推荐图表类型 → 生成ECharts配置 |
| 模拟数据 | SQLite 4张MES表（产量/质量/OEE/工单），1786条记录 |
| API接口 | `POST /api/chat` + `GET /api/tables` + `GET /health` |

### Stage 2: 前端对话界面 (已完成)
| 模块 | 说明 |
|------|------|
| 对话界面 | Vue3 + ECharts 消息列表 + 图表渲染，支持流式追问 |
| SSE 流式输出 | 后端 `run_stream()` → FastAPI `StreamingResponse` → 前端 `fetch` + `ReadableStream` 逐 token 渲染 |
| 状态提示 | 实时展示 "正在分析问题..." / "AI 思考中（第 N 轮）..." / "正在生成回答..." |

### Stage 3: DeepSeek 集成 + 安全增强 (已完成)
| 模块 | 说明 |
|------|------|
| DeepSeek 集成 | `LLMFactory` 支持 `(class, kwargs)` 元组注册，自动传入 `extra_body` 禁用深度思考 |
| 流式对齐 | 所有 model provider 统一实现 `chat_stream()`，向上兼容 |
| SQL 安全校验 | 正则拦截 `INSERT/UPDATE/DELETE/DROP` 等危险操作，阻止多语句注入 |
| Agent 自动重试 | Prompt 引导 LLM 在 SQL 报错时自动分析错误并重试（最多 2 次） |

### Stage 4: 容器化部署 (规划中)

## 快速开始

### 后端
```bash
cd backend
uv venv && source .venv/Scripts/activate
uv pip install -r requirements.txt
cp .env.example .env                         # 填入 OpenAI API Key（可选）
# Mock模式无需API Key
LLM_PROVIDER=mock uvicorn app.main:app --reload --port 8000
```

### 前端
```bash
cd frontend
npm install
npm run dev
# 访问 http://localhost:5173
```

### 测试Agent
```bash
cd backend
python test_agent.py
```

## 典型问题示例
- "各产线的产量是多少？"
- "最近的良率趋势如何？"
- "设备OEE排名怎样？"
- "哪些工单还没完成？"
- "哪个产品的合格率最高？"

## 项目结构
```
DataCopilot/
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI入口
│   │   ├── config.py            # 配置管理
│   │   ├── agent/
│   │   │   ├── core.py          # Agent主循环（核心）
│   │   │   └── prompt.py        # System prompt
│   │   ├── models/
│   │   │   ├── base.py          # LLM抽象基类
│   │   │   ├── factory.py       # 模型工厂
│   │   │   ├── openai_model.py  # OpenAI实现
│   │   │   └── mock_model.py    # Mock实现
│   │   ├── tools/
│   │   │   ├── base.py          # Tool抽象基类
│   │   │   ├── text_to_sql.py   # Text-to-SQL工具
│   │   │   └── chart_recommender.py
│   │   ├── database/
│   │   │   ├── connection.py    # SQLite连接
│   │   │   └── schema.py        # 表结构+种子数据
│   │   └── api/
│   │       └── routes.py        # API路由
│   ├── requirements.txt
│   └── .env.example
├── frontend/                     # Vue3 + ECharts (Stage 2)
├── docs/
│   └── stage1-backend-agent.md
└── README.md
```