# @antv/ava 中文文档

规范地址：https://npmcn.com/package/%40antv/ava/

版本：4\.0\.0
npm 元数据更新时间：2026-11-04T03:54:52.384Z
中文译文更新时间：2026-11-06T07:14:56.169Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40antv/ava
原文对照：https://npmcn.com/package/%40antv/ava/?lang=original
项目主页：https://ava.antv.vision/
源码仓库：https://github.com/antvis/AVA

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：701 kB，220 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.13\.0
- 运行依赖：13 个
- 首次发布：2022-11-20T14:35:45.304Z
- 最新版本发布：2026-11-04T03:54:52.221Z
- 近 30 天下载量：11809（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：58（近 12 个月 15 个）

## 中文简介

AI-原生视觉分析框架

## 安装

```sh
npm install @antv/ava
```

也可以使用：`pnpm add @antv/ava`、`yarn add @antv/ava`、`bun add @antv/ava`

## README

# AVA,AI-原生视觉分析

![AVA logo](https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*yOHIQ48aRwgAAAAAAAAAAAAADmJ7AQ/original)

 [![Website](https://img.shields.io/badge/Website-2F54EB?style=for-the-badge)](https://ava.antv.vision/)[![Documentation](https://img.shields.io/badge/Docs-722ED1?style=for-the-badge) ](https://ava.antv.vision/documentation/)[![AI Agent](https://img.shields.io/badge/AI%20Agent-EB2F96?style=for-the-badge) ](https://ava.antv.vision/ai/)[![Try Sive](https://img.shields.io/badge/Try%20Sive-13A8A8?style=for-the-badge) ](https://sive.antv.antgroup.com/ "A data analysis app built with AVA")[![GitHub](https://img.shields.io/badge/GitHub-000000?style=for-the-badge&logo=github&logoColor=white) ](https://github.com/antvis/ava)[![llms](https://img.shields.io/badge/LLMS-FA8C16?style=for-the-badge)](https://ava.antv.vision/llms.txt)

[阿富汗](https://github.com/antvis/AVA) (单位:千美元)![AVA examples](https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*QzIsSrfsCW0AAAAAAAAAAAAADmJ7AQ/original) 视觉分析(Visual Analytics)是一款为更方便的视觉分析而设计的技术框架. **A 类** 代表人工智能、自动化和增强; **瓦纳** 代表视觉分析.

> \[注\] **将AVA想作"熊猫AI"为JavaScript. 💬📊🤖**
> 
> 它为您的应用程序和AI代理带来了自然语言数据分析和可视化.

## 为什么是AVA?

<table><tbody><tr><td><h3>统一数据访问</h3><p>连接 <strong>文件和数据库</strong> 通过一个接口.</p><a href="https://ava.antv.vision/documentation/data/sources/" rel="nofollow noopener noreferrer">数据来源</a></td><td><h3>* * * 已按部就班地回答问题</h3><p>检查 <strong>查询和结果</strong> 每一个答案后面.</p><a href="https://ava.antv.vision/documentation/analysis/overview/" rel="nofollow noopener noreferrer">可信的分析 ∗∗</a></td><td><h3>智能可视化</h3><p>获取图表 <strong>您的问题和数据</strong>。 。 。 .</p><a href="https://ava.antv.vision/documentation/visualization/overview/" rel="nofollow noopener noreferrer">可视化 −</a></td></tr><tr><td><h3>* 当地执行</h3><p>选择 <strong>分析结果</strong> 和它使用的模型终点.</p><a href="https://ava.antv.vision/documentation/engines/overview/" rel="nofollow noopener noreferrer">执行发动机</a></td><td><h3>已公布的基准</h3><p>对照 <strong>参考答案</strong> 在公布的试验条件下.</p><a href="https://ava.antv.vision/documentation/reference/benchmarks/" rel="nofollow noopener noreferrer">基准 +</a></td><td><h3>代理人整合</h3><p>你的经纪人的理由; <strong>AVA 执行</strong> 数据工作流程.</p><a href="https://ava.antv.vision/documentation/agent-skill/" rel="nofollow noopener noreferrer">代理一体化 +</a></td></tr></tbody></table>

## 开始

与节点.js 22.13+安装AVA 4.0:

```bash
npm install @antv/ava@4
```

## 使用量

下载 [销售量](https://npmcn.com/package/%40antv/ava/__tests__/datasets/sales.csv) 并配置您的模型 :

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

const ava = new AVA({
  llm: {
    model: '<your-model>',
    apiKey: '<your-api-key>',
    // baseURL: '<your-provider-api-url>',
  },
});
```

### 1\. 装入

```typescript
await ava.source({ type: 'csv-file', options: { path: './sales.csv' } });
```

> \[注\] **数据预览**
> 
> 240行中的前3行, 选定的列 :
> 
> | 顺序( d) | 产品 | 销售 |
> | --- | --: | --: |
> | 2025-01-01 (英语) | 监视器 | 224.10 联合国 |
> | 2025-01-02 (中文(简体) ) | 办公室主席 | 页:1 |
> | 2025-01-04 (英语) | 监视器 | 2 191.20 (中文(简体) ) |

### 2\. 探索

检查结构和数据质量,然后添加 [商业定义](https://ava.antv.vision/documentation/data/semantic/)数字 :

```typescript
const schema = await ava.schema();
const profile = await ava.profile({ metrics: ['row_count', 'null_count'] });
await ava.semantic(undefined, () => ({
  description: 'Use the sales column for amounts after discounts and order_date for monthly comparisons.',
}));
```

> \[注\] **分析背景**
> 
> | A. 背景情况 | 细节 |
> | --- | --: |
> | 结构 | `data`: 12个栏 |
> | 质量 | 240行;缺少1行 `region` 缺少1个 `quantity` |
> | 语义 | `sales` 在折扣后; 每月比较使用 `order_date` |

### 3\. 建议

```typescript
const suggestions = await ava.suggest(3);
```

> \[注\] **建议的问题** (实例)
> 
> -   2025年1月至2月销售情况如何变化??
> -   哪些产品对销售下降贡献最大?
> -   销售额和利润如何因地区而异?

### 4\. 分析

```typescript
const result = await ava.analyze(
  'Compare January and February 2025 sales by product. Show both months and the change, ordered by the largest decline.'
);
```

> \[注\] **分析结果**
> 
> 销售总额下降 **43.94%**,由一位 **16 092.10 (中文(简体) )** 笔记本电脑销售量下降.
> 
> 9个产品中的前3个:
> 
> | 产品 | 1月销售 | 2月销售额 | 变动 |
> | --- | --: | --: | --: |
> | 手提电脑 | 19,688.10 (英语) | 3 596.00 (中文(简体) ) | \- 16,092.10岁 |
> | 常设股 | 9,655.80 (韩语) | 5 546.10 (中文(简体) ) | \-4,109.70岁 |
> | 监视器 | 6 536.25 (中文(简体) ) | 4 731.00 (中文(简体) ) | \- 1 805.25岁 |

### 5\. 视觉

```typescript
const chart = await ava.visualize({
  query: 'Plot the sales change by product from January to February 2025 as a bar chart.',
  data: result.data,
});
```

> \[注\] **图表预览**
> 
> ![Sales change by product from January to February 2025, with decreases in red and increases in green.](https://npmcn.com/package/%40antv/ava/.github/assets/sales-change.png)
> 
> _电源 [GPT - 视频](https://gpt-vis.antv.vision/)。 。 。 ._

## QQ 连接您的数据

<table><tbody><tr><td align="center"><a href="https://ava.antv.vision/documentation/data/sources/#csv" rel="nofollow noopener noreferrer"><img alt="CSV" height="32" src="https://mdn.alipayobjects.com/huamei_aphk1k/afts/img/A*SEIZRJCeCuYAAAAAQBAAAAgAegfkAQ/original" width="32" loading="lazy" decoding="async" referrerpolicy="no-referrer"><br>简历</a></td><td align="center"><a href="https://ava.antv.vision/documentation/data/sources/#json" rel="nofollow noopener noreferrer"><img alt="JSON" height="32" src="https://mdn.alipayobjects.com/huamei_aphk1k/afts/img/A*VBNjQJDMvMIAAAAAHYAAAAgAegfkAQ/original" width="32" loading="lazy" decoding="async" referrerpolicy="no-referrer"><br>贾森</a></td><td align="center"><a href="https://ava.antv.vision/documentation/data/sources/#parquet" rel="nofollow noopener noreferrer"><img alt="Parquet" height="32" src="https://mdn.alipayobjects.com/huamei_aphk1k/afts/img/A*-_h8RrPPA54AAAAAFkAAAAgAegfkAQ/original" width="32" loading="lazy" decoding="async" referrerpolicy="no-referrer"><br>公园</a></td><td align="center"><a href="https://ava.antv.vision/documentation/data/sources/#excel" rel="nofollow noopener noreferrer"><img alt="Excel" height="32" src="https://mdn.alipayobjects.com/huamei_aphk1k/afts/img/A*GfCXT7Mb_5gAAAAAQCAAAAgAegfkAQ/original" width="32" loading="lazy" decoding="async" referrerpolicy="no-referrer"><br>埃克塞尔</a></td><td align="center"><a href="https://ava.antv.vision/documentation/data/sources/#text" rel="nofollow noopener noreferrer"><img alt="Text" height="32" src="https://mdn.alipayobjects.com/huamei_aphk1k/afts/img/A*XrY8SK_9fGwAAAAAEsAAAAgAegfkAQ/original" width="32" loading="lazy" decoding="async" referrerpolicy="no-referrer"><br>文本</a></td><td align="center"><a href="https://ava.antv.vision/documentation/data/sources/#feishu-bitable" rel="nofollow noopener noreferrer"><img alt="Feishu Bitable" height="32" src="https://mdn.alipayobjects.com/huamei_aphk1k/afts/img/A*Rly3Rou8Wv8AAAAAQFAAAAgAegfkAQ/original" width="32" loading="lazy" decoding="async" referrerpolicy="no-referrer"><br>飞须可选</a></td><td align="center"><a href="https://ava.antv.vision/documentation/data/sources/#csv-files" rel="nofollow noopener noreferrer"><img alt="Tencent Docs" height="32" src="https://mdn.alipayobjects.com/huamei_aphk1k/afts/img/A*wH-PT4nF70wAAAAAMkAAAAgAegfkAQ/original" width="32" loading="lazy" decoding="async" referrerpolicy="no-referrer"><br>十美分医生</a></td></tr><tr><td align="center"><a href="https://ava.antv.vision/documentation/data/sources/#sqlite" rel="nofollow noopener noreferrer"><img alt="SQLite" height="32" src="https://mdn.alipayobjects.com/huamei_aphk1k/afts/img/A*3xulRYi0wWkAAAAAQBAAAAgAegfkAQ/original" width="32" loading="lazy" decoding="async" referrerpolicy="no-referrer"><br>SQL 点</a></td><td align="center"><a href="https://ava.antv.vision/documentation/data/sources/#mysql" rel="nofollow noopener noreferrer"><img alt="MySQL" height="32" src="https://mdn.alipayobjects.com/huamei_aphk1k/afts/img/A*8TDeSpgXAi0AAAAAQEAAAAgAegfkAQ/original" width="32" loading="lazy" decoding="async" referrerpolicy="no-referrer"><br>MySQL 数据</a></td><td align="center"><a href="https://ava.antv.vision/documentation/data/sources/#postgresql" rel="nofollow noopener noreferrer"><img alt="PostgreSQL" height="32" src="https://mdn.alipayobjects.com/huamei_aphk1k/afts/img/A*h6xsS5N0EbcAAAAAQFAAAAgAegfkAQ/original" width="32" loading="lazy" decoding="async" referrerpolicy="no-referrer"><br>邮递SQL</a></td><td align="center"><a href="https://ava.antv.vision/documentation/engines/custom/" rel="nofollow noopener noreferrer"><img alt="SQL Server" height="32" src="https://mdn.alipayobjects.com/huamei_aphk1k/afts/img/A*XVBPSaYT6p0AAAAAQJAAAAgAegfkAQ/original" width="32" loading="lazy" decoding="async" referrerpolicy="no-referrer"><br>SQL 服务器</a></td><td align="center"><a href="https://ava.antv.vision/documentation/data/sources/#mongodb" rel="nofollow noopener noreferrer"><img alt="MongoDB" height="32" src="https://mdn.alipayobjects.com/huamei_aphk1k/afts/img/A*5VYbTakXL7EAAAAAIlAAAAgAegfkAQ/original" width="32" loading="lazy" decoding="async" referrerpolicy="no-referrer"><br>蒙戈DB</a></td><td align="center"><a href="https://ava.antv.vision/documentation/data/sources/#supabase" rel="nofollow noopener noreferrer"><img alt="Supabase" height="32" src="https://mdn.alipayobjects.com/huamei_aphk1k/afts/img/A*IWbeTqNDuu4AAAAAFFAAAAgAegfkAQ/original" width="32" loading="lazy" decoding="async" referrerpolicy="no-referrer"><br>苏巴基地</a></td><td align="center"><a href="https://ava.antv.vision/documentation/data/sources/#clickhouse" rel="nofollow noopener noreferrer"><img alt="ClickHouse" height="32" src="https://mdn.alipayobjects.com/huamei_aphk1k/afts/img/A*o0VuQ5NvHZ8AAAAAELAAAAgAegfkAQ/original" width="32" loading="lazy" decoding="async" referrerpolicy="no-referrer"><br>点击之家</a></td></tr></tbody></table>

> \[TIP\] **缺少数据源? 💡🛠️**
> 
> **[打开一个问题](https://github.com/antvis/AVA/issues/new/choose)** • 妇女 **[提交拉动请求](https://github.com/antvis/AVA/compare)**

## 基准

我们根据既定基准评价AVA,以衡量其数据分析的准确性和效率.

![DataBench and Spider2-Lite evaluation results comparing raw data, schema and profile, and semantic context.](https://mdn.alipayobjects.com/huamei_aphk1k/afts/img/A*XjhtSbWcb70AAAAAUlAAAAgAegfkAQ/original)

[评价和报告](https://ava.antv.vision/documentation/reference/benchmarks/)

## 更多使用AVA的方法

代理和CLI工作流程运行于macOS或Linux上的Node.js 22.13+上.

### 与代理使用

问你的人工智能经纪人:

```text
Install the AVA skill with `npx skills add antvis/AVA`, then follow its setup instructions.
```

[代理设置指南 →](https://ava.antv.vision/documentation/agent-skill/)

### 从 CLI 使用

从终端装入并分析数据 :

```bash
ava source ./sales.csv
ava analyze '<dataset-id>' 'Compare January and February 2025 sales by product.'
```

见 [CLI 指南](https://ava.antv.vision/documentation/reference/cli/) 为设置和命令.

## 资源

-   [文档](https://ava.antv.vision/documentation/) 指南和实例
-   [分析战略](https://ava.antv.vision/documentation/analysis/strategies/) ——直接和循环执行
-   [API 参考](https://ava.antv.vision/documentation/reference/api/) - 方法和配置
-   [大赦国际](https://ava.antv.vision/ai/) ——在浏览器环境中尝试 AVA
-   [基准](https://ava.antv.vision/documentation/reference/benchmarks/) ——评价结果
-   [问题](https://github.com/antvis/AVA/issues) 错误报告和特性请求

## 捐款

欢迎捐款。 包括测试、实例和具有新特征的文件.

运行 `npm test` 测试您的变化。 模型辅助测试,复制 `.env.example` 改为 `.env` 并添加您的模型设置.

## 页:1

[维兹利特](https://vegalite-linter.idvxlab.com/) -?),一作陈克同,字克同,孙克同,F.,许克同,X.,陈克同,Z.,王克同,J.同和曹克同,N.,2021. VizLinter:用于数据可视化的Linter和Fixer框架. _IEEE 视觉和计算机图形交易_, 第28(1)页, 第206-216页.

[QQ (探索可视化设计的类型)](https://oversea.cnki.net/KCMS/detail/detail.aspx?dbcode=CJFD&dbname=CJFDAUTO&filename=MSDG202203021&uniplatform=OVERSEAS_EN&v=HcZsiecIxauSoKEB1s92_BImgnrMiazYsfZUpb-gcl0zXYx_MEwv5alz1UgtPjz1) 2022(3),149-152 (英语).

## 许可证

麻省理工学院

## 常见问题

### @antv/ava 是什么？

AI-原生视觉分析框架

### 如何安装 @antv/ava？

在项目目录运行 npm install @antv/ava，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 ava，可以用 npx ava 直接运行。

### @antv/ava 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @antv/ava 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @antv/ava 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.13\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @antv/ava 可以商用吗？

@antv/ava 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @antv/ava 的下载量有多少？

根据 npm 官方下载统计，@antv/ava 在 2026/10/06 – 2026/11/04 这 30 天内被下载 11,809 次，日均约 394 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @antv/ava 还在维护吗？

最新版本 4\.0\.0 发布于 2026/11/04（2 天前）；至今共发布 58 个版本，其中过去 12 个月发布了 15 个；首次发布于 2022/11/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。