背景

AVA v1 至 v3 主要通过规则完成自动分析、洞察和可视化推荐。这套方式在确定性场景中有效，但面对自然语言问题、多表数据和长尾分析需求时，覆盖范围有限，扩展成本也比较高。

大模型、Text-to-SQL、代码执行和图表 Skills 已经可以较好地完成数据理解、分析和可视化。AVA v4 希望在此基础上重新设计 AVA：不再围绕规则枚举分析场景，而是围绕一条完整、可信的 AI 数据分析流程组织能力。

定位

A framework for AI-native Visual Analytics.

AVA 依然是一个开发框架，不是完整的数据分析产品。

AVA 负责：

• 接入和理解数据。
• 将自然语言问题转换为可执行分析。
• 安全执行并核对结果。
• 输出结构化结论和可视化。

账号、权限、数据集管理、审批、持久化、协作和发布等产品能力，由接入 AVA 的应用负责。

基本使用

import { AVA } from '@antv/ava';

const ava = new AVA({
  llm: {
    model: 'inclusionai/ling-1t',
    apiKey: process.env.OPENAI_API_KEY!,
    baseURL: process.env.OPENAI_BASE_URL,
  },
});

await ava.load({
  type: 'csv-file',
  options: { path: 'data/companies.csv' },
});

const result = await ava.analysis('比较各地区的平均收入');

console.log(result.analysis.summary);
console.table(result.result.rows);

await ava.dispose();

生成图表：

const analysis = await ava.analysis('比较各地区的平均收入');
const visualization = await ava.visualize(analysis);

console.log(visualization.spec);
console.log(visualization.html);

核心原则

AI 负责理解，执行引擎负责计算

模型负责理解问题、识别分析口径、选择分析方法和生成执行计划；具体数值计算交给确定性的执行引擎。

AVA 不需要把完整数据集放入模型上下文。模型主要接收 Schema、字段画像、必要的数据预览和最终查询结果。

一次分析必须有数据依据

AVA 输出的结论必须能够追溯到实际数据和执行结果。

完整分析流程为：

加载数据
  → 生成画像
  → 理解问题
  → 生成查询或计算
  → 安全执行
  → 核对并有限纠错
  → 形成可信结果
  → 生成结论和可视化

无法安全回答时，返回 blocked 或 failed，而不是生成缺少数据依据的答案。

范围

AVA v4 关注以下通用能力：

• 统一的数据接入和数据画像。
• 自然语言问题理解与查询生成。
• 安全、可限制的查询和计算执行。
• 结果核对与有限纠错。
• 结构化分析结果。
• 声明式可视化。
• 多数据源与多任务运行。
• Node.js、Browser、CLI 和 Agent 等使用入口。
• 面向结果正确性的评测与运行观测。

非目标

AVA v4 不负责：

• 账号、组织和权限系统。
• 数据集管理产品。
• 审批、审计和协作界面。
• 会话和结果持久化。
• 报告发布和分享。
• 没有真实调用需求的通用抽象。

Roadmap

阶段 1：数据理解与质量

• 统一 Dataset Schema 与关系描述
• 有界的数据画像与采样
• 面向模型的 Context 构建
• 业务指标与语义建模
• 数据质量检测
• 结构化质量报告

阶段 2：可信查询与分析

• 多方言 SQL 生成
• 只读查询安全与资源限制
• 统一查询结果与错误结构
• 基于执行结果的正确性评测
• 可扩展的 Query Strategy
• Evidence 追踪
• 结构化 AnalysisArtifact
• Golden Query 检索
• 常见分析方法

阶段 3：GPT-Vis 可视化分析

• 可视化推荐
• 声明式 VisualizationSpec
• GPT-Vis Renderer
• 可视化与分析 Evidence 关联

阶段 4：复杂分析与报告

• 复杂目标的任务拆解
• 多任务与并行分析
• 跨任务分析口径管理
• 报告规划与内容组织
• 结构化 ReportArtifact
• Markdown / HTML 报告渲染

阶段 5：Runtime 与多环境交付

1. Engine

• 统一 Engine 接口 — 统一查询、计算、限制和执行结果契约
• DuckDB Engine — 支持本地文件和分析型 SQL 执行
• Remote SQL Engine — 支持远程数据库上的受限查询
• JavaScript Interpreter — 支持 JavaScript 代码执行与数据处理
• Python Interpreter — 支持 Python 代码执行与数据分析
• 自定义 Engine — 支持注册自定义执行引擎

2. Runtime

• Runtime 生命周期 — 支持初始化、资源释放
• 运行控制 — 支持取消、超时和资源限制
• 标准运行事件 — 暴露分析各阶段的标准事件
• 多数据源 Runtime — 在同一 Runtime 中管理多个具名数据源

3. Source

• 统一 Source 接口 — 统一不同数据源的加载、Schema 获取和生命周期
• CSV 数据源 — 支持 CSV 文件加载
• JSON 数据源 — 支持 JSON / NDJSON 文件加载
• Parquet 数据源 — 支持 Parquet 文件加载
• Excel 数据源 — 支持 Excel 工作簿加载
• HTTP File 数据源 — 支持通过 HTTP / HTTPS 加载远程 CSV、JSON、Parquet 等文件
• SQLite 数据源 — 支持 SQLite 数据库文件
• MySQL 数据源 — 支持 MySQL 数据库连接
• PostgreSQL 数据源 — 支持 PostgreSQL 数据库连接
• SQL Server 数据源 — 支持 Microsoft SQL Server
• Oracle 数据源 — 支持 Oracle Database
• ClickHouse 数据源 — 支持 ClickHouse 分析数据库
• Snowflake 数据源 — 支持 Snowflake 云数据仓库
• BigQuery 数据源 — 支持 Google BigQuery
• Databricks 数据源 — 支持 Databricks Lakehouse
• MongoDB 数据源 — 支持 MongoDB 文档数据库
• ODBC 数据源 — 通过 ODBC 接入其他企业数据库
• S3 数据源 — 支持 Amazon S3 及 S3 兼容对象存储
• OSS 数据源 — 支持阿里云 OSS 对象存储
• Iceberg 数据源 — 支持 Apache Iceberg 数据湖表
• Delta Lake 数据源 — 支持 Delta Lake 数据湖表
• Google Sheets 数据源 — 支持 Google Sheets 在线表格
• 飞书多维表格数据源 — 支持飞书多维表格

4. Delivery

• Node.js SDK — 提供完整的服务端分析入口
• Browser 支持 — 提供浏览器环境下的数据分析入口
• CLI — 支持命令行和自动化流程调用
• Agent Skill — 支持 Codex、Claude Code、Cursor 等 Agent 环境调用

贯穿所有阶段：评测与可观测性

• 统一评测框架与固定回归集
• Text2SQL 评测（使用 DataBench 公开数据集，CSV 文件）
• Text2SQL 评测（使用 Spider2-lite 公开数据集，Sqlite 数据库，大宽表）
• Monkey Test
• 真实业务 Case 评测
• Runtime Trace 与关键运行指标
• 发布回归门槛

工程约束

• 使用 TypeScript，支持 Node.js 18 及以上版本。
• LLM 调用继续使用 Vercel AI SDK。
• 优先复用现有依赖和平台能力。
• 不增加没有真实调用方的抽象。
• 新增非平凡逻辑必须提供可执行测试。
• 修改公共行为时同步更新 README、CLI Help 和 Agent Skill。
• 新契约稳定后删除旧路径，不长期维护 Alpha 兼容层。