RepoThread Logo
RepoThread
价格

项目总览

相关源文件

本页面内容基于以下源文件生成：

项目简介与核心定位

Data Formulator 是微软研究院推出的 AI 驱动数据可视化原型工具，旨在通过 AI Agent 辅助分析师进行迭代式的数据探索与可视化创作。该项目打破了传统 BI 工具的操作模式，允许用户从任意格式的数据源（如截图、文本、CSV 文件或数据库连接）入手，通过混合界面——结合用户界面交互与自然语言输入——来精准传达分析意图。

该工具的核心价值在于将用户从繁琐的图表配置中解放出来。用户无需记忆复杂的 VGL（Vega-Lite）语法或手动调整编码通道，只需通过拖拽字段或简单的自然语言描述，即可控制探索的分支方向，并生成可交互的报告以分享洞察。项目目前处于活跃的 Beta 开发阶段（v0.7.0a1），持续集成最新的 LLM 能力与数据处理技术。

技术架构与依赖

Data Formulator 采用典型的前后端分离架构，后端基于 Python 生态构建，前端则使用 React 框架。系统设计高度模块化，支持从本地文件到云端数据库的多种数据接入方式，并通过 LiteLLM 实现了对多种大语言模型的统一调用。

核心技术栈

技术领域核心组件/库版本/说明用途
后端框架Flask-提供 REST API 服务与前端资源托管
数据处理DuckDB, Pandas-支持大规模数据的本地存储与高效查询
AI 集成LiteLLM-统一接入 OpenAI, Azure, Anthropic, Ollama 等模型
云服务Azure SDK, boto3-支持 Azure Blob, S3, Kusto 等外部数据源
前端构建React, TypeScript-构建响应式单页应用 (SPA)
包管理uv-实现可复现的快速构建与依赖管理

架构依赖关系

系统架构清晰地划分为数据接入层、逻辑处理层和表现层。

正在加载图表渲染器...

架构说明：

  1. 前端表现层：由 React 驱动，负责用户交互、状态管理和视图渲染。核心入口为 App.tsx，并包含专门的数据上传对话框组件 (index.html:32-37)。
  2. 后端逻辑层：使用 Flask 构建，处理前端的 API 请求。集成了 AI Agent 负责将用户意图转化为数据处理代码或可视化规范。
  3. 数据存储层：利用 DuckDB 处理大规模本地数据集，同时支持通过 Data Loaders 连接外部数据源（如 MySQL, Azure 等）。
  4. AI 模型层：通过 LiteLLM 适配器，屏蔽不同模型厂商的接口差异，提供统一的推理能力。
  • 依赖证据：项目依赖列表包含 Flask, DuckDB, LiteLLM 及各类云 SDK (pyproject.toml:23-53)
  • 构建策略：采用 UV-first 构建模式，确保环境复现与安全加固 (README.md:41-44)

版本演进历程

Data Formulator 的迭代路径清晰地展示了从基础可视化工具向智能数据分析平台的演进过程。每个版本都在数据接入能力、交互体验和 AI 智能化方面进行了显著增强。

关键里程碑

  • v0.6 (Current): 引入了实时数据洞察功能，支持连接 URL 和数据库并自动刷新，同时增强了安全性（代码签名、沙箱执行）。
  • v0.2: 解决了大数据处理瓶颈，集成了 DuckDB，使得在本地浏览器中处理百万级行数据成为可能，并支持 AI 生成 SQL 进行数据转换 (README.md:78-84)。
  • v0.1.6: 突破了单表限制，支持多表联合分析，系统能自动推断表连接关系 (README.md:93-96)。
  • v0.1.7: 引入了“数据锚定”概念，允许用户固定中间数据集，避免 AI 在后续分析中偏离上下文 (README.md:87-90)。

演进时序图

以下时序图展示了从数据接入到可视化生成的核心交互流程，反映了系统在处理不同数据源时的演进能力。

正在加载图表渲染器...

流程说明：

  1. 数据接入：前端通过 UnifiedDataUploadDialog 组件处理文件选择，根据文件类型（CSV, Excel, JSON）调用不同的解析逻辑 (src/views/UnifiedDataUploadDialog.tsx:637-669)。
  2. 状态管理：上传成功后，数据表结构被同步至前端状态，供后续可视化使用。
  3. 意图解析：用户通过 UI 交互（如拖拽字段到 Shelf）或自然语言输入表达意图，后端 AI Agent 结合当前数据上下文生成可视化代码。
  4. 结果反馈：生成的 Vega-Lite 规范或 SQL 查询结果返回前端，由 React 组件渲染最终图表。
  • 历史记录：详细的版本更新日志记录了从 v0.1 到 v0.6 的功能迭代 (README.md:45-62)

核心模块解析

基于源码分析，系统主要由以下几个核心模块构成，各司其职地完成从数据加载到可视化呈现的全流程。

1. 应用主控模块

职责：作为 React 应用的根组件，负责全局状态管理、会话持久化以及顶层路由控制。

  • 关键功能：
    • 会话管理：提供了完整的保存与加载机制。用户可以将当前的表结构、视图状态等全量状态保存至后端，并在需要时恢复 (src/app/App.tsx:179-199)。
    • 消息分发：集中处理系统内的通知消息，通过 dispatch 机制向用户反馈操作结果（如保存成功、加载失败等）。
    • 身份认证：集成了 fetchWithIdentity 方法，确保 API 请求携带必要的身份凭证。

2. 统一数据上传模块

职责：提供多模态的数据接入入口，屏蔽不同数据源（文件、数据库、粘贴板）的差异。

3. 数据线程与视图模块

职责：负责单次数据分析任务的上下文维护，包括数据变换、可视化生成和历史记录。

  • 交互逻辑：
    • 维护一个线性的操作历史栈，允许用户回溯或分支探索。
    • 集成 ChartRecBox 组件，展示 AI 推荐的可视化图表。
    • 处理用户对数据字段的增删改查操作，并实时触发视图更新。

4. 报告生成模块

职责：将探索过程中的关键快照组合成可分享的分析报告。

  • 功能点：
    • 支持将多个图表快照添加至报告画板。
    • 提供简单的排版和注释功能。
    • 导出为静态 HTML 或 PDF 格式（需后端支持）。

安装与快速启动

Data Formulator 提供了灵活的安装方式，既支持通过 Python 包管理器进行本地部署，也支持通过 uvx 进行无安装运行。

推荐安装方式

使用 uv（极速 Python 包管理器）是官方推荐的启动方式，能够最大程度减少依赖冲突。

bash
1# 方式一：直接运行（无需安装）
2uvx data_formulator
3
4# 方式二：安装到本地环境
5uv pip install data_formulator
6python -m data_formulator

环境要求

  • Python 版本：>= 3.11 (pyproject.toml:9)
  • 操作系统：Windows, macOS, Linux
  • API Key：需配置 OpenAI/Azure 等 API Key 以启用 AI 功能（支持本地模型如 Ollama）

启动流程

  1. 执行启动命令后，本地 Flask 服务器会默认运行在 http://localhost:5000。
  2. 浏览器自动打开 index.html，加载 React 应用。
  3. 前端通过 /src/index.tsx 渲染根组件 App.tsx，进入主界面 (index.html:37)。

适用场景与最佳实践

Data Formulator 特别适合以下场景：

  1. 快速数据探索：当你拿到一个新的 CSV 或 Excel 文件，希望快速了解数据分布、相关性时，可以通过简单的拖拽或自然语言描述迅速生成多种图表。
  2. 多源数据整合：需要结合本地 CSV 和数据库中的数据进行联合分析时，其自动 Join 功能能大幅减少 SQL 编写工作。
  3. 非技术用户可视化：对于不熟悉 D3.js 或 Vega-Lite 语法的分析师，AI Agent 能够充当翻译官，将自然语言转化为代码。
  4. 迭代式报告生成：在探索过程中，随时将有价值的视图“锚定”并添加到报告中，形成完整的分析故事。

最佳实践建议：

  • 数据清洗：利用 v0.1.7 的锚定功能，先对原始数据进行清洗并固定，再让 AI 基于清洗后的数据进行分析，能显著提高准确性。
  • 大数据处理：对于超过 100MB 的文件，建议使用 DuckDB 导入功能，而非直接在浏览器内存中处理。
  • 提示词工程：在使用自然语言交互时，明确指定字段名和期望的图表类型（如“用折线图展示 A 和 B 的关系”）通常能得到更精确的结果。