快速上手

相关源文件

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

• README.md
• pyproject.toml
• requirements.txt
• .env.template
• local_server.sh
• local_server.bat
• py-src/data_formulator/app.py
• src/lib/agents-chart/index.ts
• src/lib/agents-chart/core/index.ts
• src/lib/agents-chart/gofish/index.ts

Data Formulator 是 Microsoft Research 开发的 AI 驱动数据可视化工具原型，支持通过自然语言与界面交互相结合的方式探索和可视化数据。本节将介绍如何快速安装和启动该工具。

环境要求与安装准备

系统与 Python 版本

Data Formulator 要求 Python 版本 ≥ 3.11（pyproject.toml:9）。项目当前版本为 0.7.0a1（alpha 版本），采用 MIT 许可证（pyproject.toml:7，pyproject.toml:15）。

安装方式概览

项目支持 UV-first build，通过 uv.lock 实现可复现构建（README.md:42）。推荐使用 uv 包管理器以获得更快的安装体验（README.md:49）。

安装方式一使用 uv（推荐）

方式 1A：uvx 直接运行（最快）

如果已安装 uv，可直接运行 Data Formulator 而无需任何安装步骤：

bash
1# 直接运行（无需安装）
2uvx data_formulator

此命令会自动处理依赖并启动服务（README.md:131-133）。

方式 1B：uv pip 安装到虚拟环境

如需在项目或虚拟环境中使用：

bash
1# 安装 data_formulator
2uv pip install data_formulator
3
4# 运行
5python -m data_formulator

项目在 pyproject.toml 中配置了 uv 相关设置（pyproject.toml:67-70），支持通过 uv sync + uv run data_formulator 进行可复现构建（README.md:42）。

安装方式二使用 pip

标准安装流程

使用 pip 安装时，建议在虚拟环境中操作：

bash
1# 安装 data_formulator
2pip install data_formulator
3
4# 运行
5python -m data_formulator

上述命令在（README.md:152-158）中有详细说明。

端口配置

默认服务运行在端口 5567。如该端口被占用，可指定其他端口：

bash
1# 指定端口运行（例如 8080）
2python -m data_formulator --port 8080

此配置选项在（README.md:162）中说明。

核心依赖说明

项目依赖主要包括（requirements.txt:1-33）：

配置 API 密钥

支持的模型提供商

Data Formulator 通过 LiteLLM 支持多种 LLM 提供商（README.md:57）：

• OpenAI：推荐 gpt-4o 等具有强代码生成能力的模型
• Azure OpenAI
• Anthropic：推荐 claude-3-5-sonnet 等
• Ollama：支持本地模型

环境变量配置方法

1. 复制模板文件：

   bash
   1cp .env.template .env

2. 编辑 .env 文件，填入 API 密钥（README.md:101）：

   bash
   1# OpenAI 配置
   2OPENAI_ENABLED=true
   3OPENAI_API_KEY=your-openai-api-key
   4OPENAI_MODELS=gpt-4o,gpt-4o-mini
   5
   6# Azure OpenAI 配置
   7AZURE_ENABLED=true
   8AZURE_API_KEY=your-azure-openai-api-key
   9AZURE_API_BASE=https://your-azure-openai-endpoint.openai.azure.com/
   10AZURE_MODELS=gpt-4o
   11
   12# Anthropic 配置
   13ANTHROPIC_ENABLED=true
   14ANTHROPIC_API_KEY=your-anthropic-api-key
   15ANTHROPIC_MODELS=claude-sonnet-4-20250514

完整配置模板参见（.env.template:1-34）。

安全配置选项

.env 文件还支持以下安全设置（.env.template:10-11）：

启动与验证

启动服务

根据安装方式选择对应命令：

bash
1# uvx 方式
2uvx data_formulator
3
4# 或 pip/uv pip 安装后
5python -m data_formulator

命令行入口点 data_formulator 在（pyproject.toml:64-66）中定义，指向 data_formulator:run_app。

验证安装成功

启动后，Data Formulator 会自动在浏览器中打开以下地址（README.md:146）：

http://localhost:5567

若浏览器未自动打开，可手动访问上述地址。看到 Data Formulator 界面即表示安装成功。

安装流程图

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

常见问题与排错

问题 1：端口 5567 被占用

症状：启动时报端口绑定错误。

解决方案：使用 --port 参数指定其他端口（README.md:162）：

bash
1python -m data_formulator --port 8080

然后访问 http://localhost:8080。

问题 2：Python 版本不兼容

症状：安装时报 requires-python >= 3.11 错误。

解决方案：

1. 检查当前 Python 版本：python --version
2. 如版本低于 3.11，需升级 Python 或使用 pyenv/conda 创建 3.11+ 环境
3. 项目明确要求 requires-python = ">=3.11"（pyproject.toml:9）

问题 3：API 密钥未配置或无效

症状：界面提示 API 错误或 AI 功能不可用。

解决方案：

1. 确认已创建 .env 文件：cp .env.template .env
2. 检查对应提供商的 *_ENABLED=true 设置
3. 验证 API 密钥格式正确（无多余空格或引号）
4. 推荐使用具有强代码生成能力的模型（如 gpt-4o、claude-3-5-sonnet）（README.md:100）

问题 4：依赖安装失败

症状：pip install 过程中某些包编译错误。

解决方案：

1. 确保系统已安装 C 编译工具链（Linux: build-essential，macOS: Xcode Command Line Tools）
2. 对于数据库连接器（如 connectorx），可能需要额外的系统库
3. 尝试使用 uv 安装，通常能更好地处理依赖解析：uv pip install data_formulator

问题 5：浏览器未自动打开

症状：命令执行成功但浏览器未弹出。

解决方案：

1. 手动访问 http://localhost:5567
2. 检查终端输出确认服务已启动
3. 确认防火墙未阻止 5567 端口

下一步建议

安装完成后，可进行以下操作：

1. 加载数据：支持 CSV、TSV、XLSX 文件上传，或从截图、文本、网站、数据库提取数据（README.md:177-179）

2. 探索数据：根据控制程度选择不同层级：

   • Level 1：拖拽创建图表（完全控制）
   • Level 2：自然语言 + UI 混合指定
   • Level 3：获取 AI 推荐图表
   • Level 4：Agent 模式，提供高层目标自动探索（README.md:185-191）

3. 创建报告：使用报告构建器组合图表并分享（README.md:196-198）

4. 高级配置：

   • 开发者模式构建：参考 DEVELOPMENT.md（README.md:172）
   • Codespaces 云端运行：详见 CODESPACES.md（README.md:166）
   • 外部数据加载器：支持 MySQL、PostgreSQL、MSSQL、Azure Data Explorer、S3、Azure Blob 等（README.md:72-73）