yi
150 lines
5.1 KiB
Markdown
150 lines
5.1 KiB
Markdown
## 项目简介
|
||
|
||
<video src="../../Videos/Captures/全源灵动_30mb.mp4"></video>
|
||
|
||
### 项目概述
|
||
|
||
**全源灵动**是一个面向数据分析与知识检索场景的 AI 平台：用自然语言问数、自动生成图表与报告，并管理分析产物，帮助团队更快得到可验证、可复用的结论。
|
||
|
||
### 项目起源
|
||
|
||
数据分散在不同系统与文件中时，手写 SQL、手工出图、反复同步口径的成本高且难复用。全源灵动将“提问 → 查询 → 可视化 → 产出”串联为一条可复用的分析链路。
|
||
|
||
### 项目定位
|
||
|
||
- 目标用户：业务/数据分析、运营、产品、研发等需要自助分析与报告产出的角色
|
||
- 适用场景：NL2SQL 问数、知识库检索增强、自动图表与报告产出、任务委派与跟踪（A2A）
|
||
|
||
### 核心价值
|
||
|
||
- 更快：把“写 SQL / 查资料 / 出图”合并为一次对话驱动的分析流程
|
||
- 更稳：对关键结果提供可回溯的查询与产物（Artifact）
|
||
- 更灵活：支持多数据源与可配置的模型接入
|
||
|
||
## 整体架构与技术栈
|
||
|
||
### 系统架构图
|
||
|
||
```mermaid
|
||
graph TD
|
||
User([用户/浏览器]) -->|HTTP| WebUI[前端 WebUI]
|
||
WebUI -->|REST/SSE| API[后端 API]
|
||
API -->|读写| Data[(DATA_ROOT)]
|
||
API -->|连接/查询| DB[(数据源)]
|
||
API -->|调用| LLM([外部 LLM])
|
||
```
|
||
|
||
### 技术栈分类
|
||
|
||
- 后端：FastAPI（Python 3.11+）
|
||
- 前端：React 19 + Vite + TailwindCSS + Zustand
|
||
- 数据库：
|
||
- 业务元数据/会话：SQLite（默认落在 `DATA_ROOT`）
|
||
- 数据分析数据源：PostgreSQL / ClickHouse / 上传文件（CSV/Excel 等）
|
||
- 部署：Docker Compose（推荐）
|
||
|
||
## 项目目录概览
|
||
|
||
```text
|
||
.
|
||
├── dataclaw-api/ # 后端 FastAPI（API 网关、会话与数据源管理、Agent 能力）
|
||
├── dataclaw-ui/ # 前端 React + Vite（Nginx 生产静态托管）
|
||
├── agent-core/ # Agent 核心（nanobot）
|
||
├── dataclaw-voice/ # Whisper 语音服务（可选）
|
||
├── data/ # 运行时数据目录（可挂载为 DATA_ROOT）
|
||
└── docker-compose.yml # 一键启动
|
||
```
|
||
|
||
## 核心业务功能
|
||
|
||
- **自然语言转 SQL**：理解数据表结构，生成/修正 SQL 并执行查询
|
||
- **知识库检索（RAG）**：上传多种格式文档，向量检索增强问答
|
||
- **即时可视化**：根据数据特征生成交互式图表
|
||
- **动态多数据源**：PostgreSQL / Supabase / 本地文件上传解析等
|
||
- **模型配置**：支持接入 OpenAI 兼容接口的外部模型服务
|
||
- **产物管理（Artifact）**：自动提取与管理报告/图片/PDF/PPT 等结果文件
|
||
- **A2A 任务委派与跟踪**：把任务委派到远端 Agent，并可订阅状态与产物
|
||
|
||
## 实际应用场景示例
|
||
|
||
1. **运营日报/周报**：提问“近 7 天新增用户趋势与转化漏斗”，自动生成图表与报告
|
||
2. **产品指标分析**：对留存、转化、渠道贡献等指标进行归因分析，并固化仪表盘
|
||
3. **知识库问答**：上传制度/方案/投标文件等，自动总结与检索引用
|
||
|
||
## 帮助解决的核心问题
|
||
|
||
- SQL 门槛高、分析链路长、结果难复用
|
||
- 多数据源/多口径带来的协作成本高
|
||
- 报告产出与分享效率低
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Docker Desktop（推荐）
|
||
- （本地开发模式可选）Python 3.11+、Node.js 20+
|
||
|
||
### 安装步骤
|
||
|
||
在项目根目录复制环境配置模板：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
### 运行步骤（Docker 全量启动）
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
访问地址：
|
||
- 前端：`http://localhost:10002/`
|
||
- 后端（直连）：`http://localhost:10001/docs`
|
||
|
||
运行时数据目录：
|
||
- 默认挂载 `./data` 到容器内 `/app/data`（对应 `DATA_ROOT=/app/data`），用于存放上传文件、会话与配置等。
|
||
|
||
### 默认账号
|
||
|
||
系统首次注册的用户将自动成为管理员（示例：用户名 `admin`，密码 `admin`）。
|
||
|
||
### 常见问题
|
||
|
||
- **后端构建失败（APT 连接失败）**：可使用国内镜像构建：
|
||
|
||
```bash
|
||
APT_CN_MIRROR=true docker compose build
|
||
```
|
||
|
||
- **接口返回 401**：需要先登录并携带 `Authorization: Bearer <token>`
|
||
- **接口返回 422**：请求体不符合后端 schema（例如 A2A `message:send` 需要 `message.parts[0].data.project_id`）
|
||
|
||
## 运行示例截图
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|