# data_engine **Repository Path**: hweiming/data_engine ## Basic Information - **Project Name**: data_engine - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-07-15 - **Last Updated**: 2025-07-15 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 智能数据可视化引擎 🚀 一个基于大语言模型的智能数据可视化引擎，能够将自然语言问题转换为ECharts图表配置或表格数据，让数据分析变得更加直观和便捷。 ## ✨ 核心特性 - 🧠 **智能理解**: 基于大语言模型理解自然语言问题 - 📊 **多图表支持**: 支持折线图、柱状图、饼图、散点图、条形图、面积图和表格 - 🔧 **安全执行**: 沙箱环境中安全执行数据处理代码 - 🌐 **多语言支持**: 支持中英文问题和标签自动翻译 - 📈 **智能识别**: 自动识别最适合的图表类型 - 🛡️ **数据安全**: 严格的输入验证和代码执行限制 ## 🏗️ 系统架构 ``` DataEngine (主引擎) ├── ChartIdentifier (图表类型识别器) ├── DataProcessor (数据处理器) ├── OutputGenerator (输出生成器) └── LLMAdapter (大模型适配器) ``` ### 核心组件 - **DataEngine**: 主引擎类，协调各个组件完成数据可视化流程 - **ChartIdentifier**: 基于问题内容和数据特征识别最适合的图表类型 - **DataProcessor**: 生成并安全执行数据处理代码（聚合、筛选、排序等） - **OutputGenerator**: 生成标准的ECharts配置或表格数据 - **LLMAdapter**: 封装大语言模型调用，支持多种模型 ## 🚀 快速开始 ### 安装依赖 ```bash pip install -r requirements.txt ``` ### 基础使用示例 ```python import pandas as pd from data_engine.core.engine import DataEngine from data_engine.utils.llm_adapter import LLMAdapter # 初始化引擎 llm_client = LLMAdapter(model="gpt-3.5-turbo") engine = DataEngine(llm_client) # 加载数据集（完整描述信息） sales_data = pd.read_csv("test_data/sales_data.csv") field_descriptions = { "month": "月份", "sales": "销售金额（元）", "department": "部门", "region": "地区" } engine.load_dataset( df=sales_data, dataset_desc="公司销售数据", table_desc="记录各部门各地区每月销售金额", field_desc=field_descriptions ) # 处理自然语言问题 result = engine.process_query("显示每个月的销售额趋势") print(result) ``` ### 缺失描述信息处理 引擎支持在描述信息缺失的情况下正常工作： ```python # 场景1: 完全没有描述信息 engine.load_dataset( df=sales_data, dataset_desc=None, # 可以为None table_desc=None, # 可以为None field_desc=None # 可以为None ) # 场景2: 部分描述信息 engine.load_dataset( df=sales_data, dataset_desc="销售数据", table_desc=None, # 表格描述缺失 field_desc={ # 部分字段描述 "sales": "销售金额" # 其他字段描述缺失 } ) # 场景3: 空字符串描述 engine.load_dataset( df=sales_data, dataset_desc="", # 空字符串会被处理为None table_desc="", field_desc={} # 空字典会被处理为None ) # 引擎会自动： # 1. 使用数据字段名和数据类型信息补充缺失的字段描述 # 2. 在提示词中添加"请根据数据字段和样本数据理解数据含义"的指导 # 3. 智能组装提示词，避免冗余信息 ``` ### 输出示例 **折线图配置**: ```json { "type": "echarts", "option": { "title": { "text": "每月销售额趋势" }, "xAxis": { "type": "category", "data": ["2024-01", "2024-02", "2024-03", "2024-04"], "name": "月份" }, "yAxis": { "type": "value", "name": "销售金额（元）" }, "series": [{ "data": [1200000, 1350000, 1180000, 1420000], "type": "line", "name": "销售金额（元）", "smooth": true }] } } ``` **表格数据**: ```json { "type": "table", "columns": [ {"field": "department", "title": "部门"}, {"field": "total_sales", "title": "总销售额（元）"} ], "data": [ {"department": "销售部", "total_sales": 5200000}, {"department": "市场部", "total_sales": 3800000} ] } ``` ## 📊 支持的图表类型 | 图表类型 | 适用场景 | 示例问题 | |---------|---------|----------| | **折线图 (line)** | 趋势分析 | "显示每月销售额变化趋势" | | **柱状图 (bar)** | 对比分析 | "比较各部门的销售业绩" | | **饼图 (pie)** | 占比分析 | "各地区销售额占比情况" | | **散点图 (scatter)** | 关系分析 | "员工年龄与薪资的关系" | | **条形图 (horizontal_bar)** | 排名展示 | "产品销量排行榜" | | **面积图 (area)** | 累积趋势 | "各部门累计销售额趋势" | | **表格 (table)** | 数据列表 | "销售额最高的前10名员工" | ## 🔍 使用场景示例 ### 1. 销售数据分析 ```python # 问题1: 趋势分析 result = engine.process_query("显示2024年每个月的销售额变化趋势") # 自动识别为折线图，展示时间序列数据 # 问题2: 部门对比 result = engine.process_query("比较各个部门的总销售额") # 自动识别为柱状图，进行部门间对比 # 问题3: 地区占比 result = engine.process_query("各地区销售额占比情况") # 自动识别为饼图，展示占比关系 ``` ### 2. 员工绩效分析 ```python # 加载员工数据 employee_data = pd.read_csv("test_data/employee_data.csv") engine.load_dataset( df=employee_data, dataset_desc="员工绩效数据", table_desc="记录员工基本信息和绩效数据", field_desc={ "name": "姓名", "department": "部门", "performance_score": "绩效分数", "salary": "薪资", "work_years": "工作年限" } ) # 分析薪资与绩效关系 result = engine.process_query("员工薪资和绩效分数之间的关系") # 自动识别为散点图 # 查看高绩效员工 result = engine.process_query("绩效分数最高的前10名员工") # 自动识别为表格展示 ``` ### 3. 产品销售分析 ```python # 产品类别销量对比 result = engine.process_query("各个产品类别的销量对比") # 自动识别为柱状图 # 价格与销量关系 result = engine.process_query("产品价格和销量的关系图") # 自动识别为散点图 # 热销产品排行 result = engine.process_query("销量最高的产品排行榜") # 自动识别为条形图 ``` ## 🛠️ 高级功能 ### 多数据集支持 ```python # 同时加载多个数据集 engine.load_dataset(sales_data, "sales", "销售数据", field_desc1) engine.load_dataset(employee_data, "employee", "员工数据", field_desc2) # 跨数据集查询 result = engine.process_query("结合销售数据和员工数据，分析部门业绩") ``` ### 自定义LLM模型 ```python # 使用不同的大语言模型 llm_client = LLMAdapter( model="claude-3-sonnet-20240229", api_key="your-api-key", base_url="https://api.anthropic.com" ) # 或使用国产模型 llm_client = LLMAdapter( model="qwen-plus", api_key="your-api-key" ) ``` ### 安全配置 ```python # 配置代码执行安全参数 engine = DataEngine( llm_client=llm_client, execution_timeout=30, # 代码执行超时时间 max_memory_mb=100, # 最大内存使用 allowed_modules=['pandas', 'numpy'] # 允许的模块 ) ``` ## 🔧 配置选项 ### 环境变量配置 ```bash # LLM API配置 export OPENAI_API_KEY="your-openai-key" export ANTHROPIC_API_KEY="your-claude-key" # 日志级别 export LOG_LEVEL="INFO" # 缓存配置 export ENABLE_CACHE="true" export CACHE_TTL="3600" ``` ### 配置文件 创建 `config.yaml`: ```yaml llm: default_model: "gpt-3.5-turbo" timeout: 30 max_tokens: 2000 execution: timeout: 30 max_memory_mb: 100 charts: default_theme: "light" color_palette: ["#5470c6", "#91cc75", "#fac858"] ``` ## 📈 性能优化 ### 智能优化策略 - **单行数据优化**: 单行数据直接返回表格，处理时间从10秒降至0.089秒 - **小数据集优化**: 小于等于5行的数据集直接生成图表配置，处理时间仅需0.011秒 - **描述信息智能处理**: 当数据集描述、表格描述或字段描述缺失时，自动使用数据特征进行补充 - **提示词智能组装**: 根据描述信息的存在情况智能组装提示词，避免冗余信息 ### 缓存机制 - **LLM响应缓存**: 相同问题避免重复调用 - **数据采样缓存**: 大数据集智能采样 - **图表模板缓存**: 常用配置模板复用 ### 内存管理 - **流式处理**: 大数据集分块处理 - **内存监控**: 实时监控内存使用 - **自动清理**: 超时任务自动清理 ### 配置参数 ```python # 性能优化配置 engine = DataEngine( llm_client=llm_client, small_data_threshold=5, # 小数据集阈值 enable_grouping_filtering=True # 启用分组过滤优化 ) ``` ## 🧪 测试数据 项目提供了完整的测试数据集： - **销售数据**: 144行，包含月份、金额、部门、地区 - **员工数据**: 112行，包含绩效、薪资、工作年限等 - **产品数据**: 66行，包含价格、销量、评分等 - **财务数据**: 12行，包含收入、成本、利润等 - **用户行为数据**: 1000行，包含登录、购买行为等 ## 🔒 安全特性 ### 代码执行安全 - **沙箱环境**: 受限的Python执行环境 - **模块限制**: 只允许数据处理相关模块 - **超时控制**: 防止无限循环和长时间执行 - **内存限制**: 防止内存溢出 ### 输入验证 - **SQL注入防护**: 严格的输入清理 - **文件路径验证**: 防止路径遍历攻击 - **数据类型检查**: 确保数据类型正确 ## 📚 API文档 ### DataEngine 主要方法 ```python class DataEngine: def __init__(self, llm_client: LLMAdapter) def load_dataset(self, df: pd.DataFrame, dataset_desc: str, table_desc: str, field_desc: Dict[str, str]) def process_query(self, question: str) -> Dict def get_sample_data(self, max_rows: int = 3) -> pd.DataFrame def clear_datasets(self) ``` ### 返回数据格式 ```python # 成功响应 { "success": True, "type": "echarts|table", "option": {...}, # ECharts配置或表格数据 "processing_time": 1.23, "chart_type": "bar" } # 错误响应 { "success": False, "error": "错误描述", "error_type": "VALIDATION_ERROR|LLM_ERROR|EXECUTION_ERROR" } ``` ## 🙋‍♂️ 支持与反馈 **项目维护说明**：这是一个个人业余时间维护的开源项目，响应可能不够及时，请理解。 如果您在使用过程中遇到问题或有改进建议，请： 1. 查看现有 [Issues](https://github.com/Solming/data_engine/issues) 是否有类似问题 2. 创建新的 [Issue](https://github.com/Solming/data_engine/issues/new) 详细描述问题 3. 参与 [Discussions](https://github.com/Solming/data_engine/discussions) 讨论 4. **推荐**：直接提交PR贡献代码，这是最快的改进方式 ## 🤝 贡献指南 这个项目主要依靠社区贡献来完善功能： - 欢迎提交PR改进代码 - 欢迎完善文档和示例 - 欢迎报告bug和提出建议 - 查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详细信息 **注意**：个人精力有限，无法承诺及时回复所有Issues，鼓励社区互助。 ### 贡献流程 1. Fork 项目 2. 创建特性分支 (`git checkout -b feature/AmazingFeature`) 3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) 4. 推送到分支 (`git push origin feature/AmazingFeature`) 5. 开启 Pull Request ## 📄 许可证 本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情 ## 🙋‍♂️ 常见问题 **Q: 支持哪些大语言模型？** A: 支持OpenAI GPT系列、Claude、以及通过LiteLLM支持的所有模型 **Q: 数据安全如何保证？** A: 采用沙箱执行环境，严格限制代码执行范围，不会访问系统文件 **Q: 支持实时数据吗？** A: 当前版本支持静态数据集，实时数据支持在开发中 **Q: 如何自定义图表样式？** A: 可以通过配置文件设置主题和颜色方案，或在生成后修改ECharts配置 **Q: 作者多久回复问题？** A: 这是个人项目，通常3-7天回复，建议优先提交PR或在社区讨论 --- **作者**: Solming **许可证**: MIT **版本**: 1.0.0 **维护状态**: 个人业余项目，社区驱动 🌟 如果这个项目对您有帮助，请给我们一个 Star！期待您的贡献让项目更完善！