安装与快速开始

这篇指南带你用 TypeScript / JavaScript SDK 跑通从加载数据到生成图表的流程。如果希望直接让 AI Agent 帮你分析数据，可以从 Agent Skill 指南开始。

准备环境并安装

请使用软件包要求的 Node.js 22.13.0 或更高版本 。选择你熟悉的包管理器，安装 AVA 4.0.0：

npm install @antv/ava@4
# or
pnpm add @antv/ava@4
# or
yarn add @antv/ava@4

连接模型

下面的示例从进程环境中读取 OPENAI_API_KEY，以及可选的 OPENAI_MODEL、OPENAI_BASE_URL。请先设置这些变量再运行示例。AVA 也接受预先配置好的 AI SDK 模型实例，详见模型配置。

跑通一次分析

这是一个完整的 Node.js 示例，使用默认的 DuckDB 引擎。请在已经安装 @antv/ava 的项目中，将它保存为 ES 模块后运行。

import { AVA } from '@antv/ava';
 
const ava = new AVA({
  llm: {
    model: process.env.OPENAI_MODEL || 'gpt-4o-mini',
    apiKey: process.env.OPENAI_API_KEY,
    baseURL: process.env.OPENAI_BASE_URL,
  },
});
 
try {
  await ava.source({
    type: 'json',
    options: {
      data: [
        { region: 'East', revenue: 120 },
        { region: 'West', revenue: 90 },
        { region: 'East', revenue: 80 },
      ],
    },
  });
 
  const schema = await ava.schema();
  const profile = await ava.profile();
  console.log(schema.models, profile.models[0].metrics);
 
  const result = await ava.analyze('Show total revenue by region');
  console.log(result.text, result.data);
 
  const chart = await ava.visualize(result);
  if (chart) console.log(chart.config);
} finally {
  await ava.dispose();
}

用完后释放资源

source() 会替换当前数据集并释放之前的引擎。dispose() 会释放连接和引擎资源，清空数据结构与统计缓存。无论分析是否成功，都应等待清理完成。

接下来可以做什么

接入数据：连接文件、内存数据和数据库。
了解数据结构：查看结构并按需计算统计信息。
补充业务语义：通过销售示例了解业务规则与可复用指标。
浏览器用法：使用前端入口。
命令行工具：在终端中完成数据工作流。

各方法及其输入参数见 API 参考。