gpt-vis

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GPT-Vis 图表可视化技能

GPT-Vis Chart Visualization Skill

GPT-Vis 是一个 AI 原生的可视化库，专为 LLM 时代设计。它采用框架无关的架构，支持 26 种图表类型，通过简单自然的语法让 LLM 能够轻松生成高质量的可视化图表。

GPT-Vis is an AI-native visualization library designed specifically for the LLM era. It adopts a framework-agnostic architecture, supports 26 chart types, and enables LLMs to easily generate high-quality visualizations through simple and natural syntax.

步骤

Steps

意图识别：根据用户意图和数据特征选择图表类型
确定输出模式：根据上下文选择语法模式或代码模式
生成输出：按所选模式生成内容

Intent Recognition: Select the chart type based on user intent and data characteristics
Determine Output Mode: Choose Syntax Mode or Code Mode based on context
Generate Output: Produce content according to the selected mode

支持的图表类型

Supported Chart Types

type 值	适用场景
line	时间序列趋势
area	时间序列趋势+总量
column	分类数据对比
bar	分类对比（标签长）
pie	部分占整体比例
scatter	两变量关系
dual-axes	不同量级数据对比
histogram	连续数值频次分布
boxplot	数据分布与异常值
violin	数据分布密度
radar	多维度对比
funnel	流程转化率
waterfall	累计增减变化
liquid	百分比/进度
word-cloud	词频展示
venn	集合交并关系
treemap	层级数据占比
sankey	流量流向
flow-diagram	流程步骤
mindmap	层级知识梳理
indented-tree	树节点层级/目录
network-graph	实体间关联关系
organization-chart	组织层级
fishbone-diagram	根因分析
table	表格数据展示
summary	内容总结

Type Value	Applicable Scenario
line	Time series trends
area	Time series trends + total volume
column	Categorical data comparison
bar	Categorical comparison (long labels)
pie	Proportion of parts to the whole
scatter	Relationship between two variables
dual-axes	Comparison of data with different magnitudes
histogram	Frequency distribution of continuous values
boxplot	Data distribution and outliers
violin	Data distribution density
radar	Multi-dimensional comparison
funnel	Process conversion rate
waterfall	Cumulative increase/decrease changes
liquid	Percentage/progress display
word-cloud	Word frequency display
venn	Set intersection and union relationships
treemap	Proportion of hierarchical data
sankey	Flow direction visualization
flow-diagram	Process steps
mindmap	Hierarchical knowledge organization
indented-tree	Tree node hierarchy/directory
network-graph	Relationship between entities
organization-chart	Organizational hierarchy
fishbone-diagram	Root cause analysis
table	Tabular data display
summary	Content summarization

输出模式

Output Modes

模式一：语法模式（Syntax / JSON）

Mode 1: Syntax Mode (Syntax / JSON)

用于 LLM 应用集成场景，生成图表配置供

GPTVis.render()

消费。支持两种格式：

Syntax 格式：类 Markdown 缩进语法，适合流式输出（LLM 逐 token 生成时可实时渲染）
JSON 格式：标准 JSON 对象，适合结构化 API 调用

两种格式等价，

GPTVis.render()

均可直接接受。

For LLM application integration scenarios, generates chart configurations for

GPTVis.render()

to consume. Supports two formats:

Syntax Format: Markdown-like indentation syntax, suitable for streaming output (real-time rendering as LLM generates tokens incrementally)
JSON Format: Standard JSON object, suitable for structured API calls

Both formats are equivalent and can be directly accepted by

GPTVis.render()

模式二：代码模式

Mode 2: Code Mode

用于用户需要可直接运行的完整代码场景。生成包含安装说明和完整代码的输出。

For scenarios where users need complete runnable code. Generates output including installation instructions and full code.

GPTVis API

GPTVis

是库的统一入口类，负责创建、渲染和销毁图表。

GPTVis

is the unified entry class of the library, responsible for creating, rendering and destroying charts.

构造函数

Constructor

typescript

new GPTVis(options: VisualizationOptions)

VisualizationOptions：

参数	类型	必填	默认值	说明
`container`	`string \| HTMLElement`	是	—	CSS 选择器或 DOM 元素
`width`	`number`	否	—	图表宽度（px）
`height`	`number`	否	—	图表高度（px）
`theme`	`'default' \| 'light' \| 'dark' \| 'academy'`	否	`'light'`	主题
`wrapper`	`boolean`	否	`false`	是否显示外层 UI 容器（含标签页、下载、复制等）
`locale`	`string`	否	`'zh-CN'`	wrapper 内文案语言

typescript

new GPTVis(options: VisualizationOptions)

VisualizationOptions:

Parameter	Type	Required	Default Value	Description
`container`	`string \| HTMLElement`	Yes	—	CSS selector or DOM element
`width`	`number`	No	—	Chart width (px)
`height`	`number`	No	—	Chart height (px)
`theme`	`'default' \| 'light' \| 'dark' \| 'academy'`	No	`'light'`	Theme
`wrapper`	`boolean`	No	`false`	Whether to display outer UI container (including tabs, download, copy, etc.)
`locale`	`string`	No	`'zh-CN'`	Language of text inside wrapper

方法

Methods

render(config: string | object): void

render(config: string | object): void

渲染图表。接受两种输入：

Syntax 字符串：以
```
vis [type]
```
开头的文本，自动解析为配置对象
JSON 配置对象：包含
```
type
```
字段的对象
纯文本：不以
```
vis 
```
开头的字符串会被当作 summary 类型渲染

多次调用

render()

会自动销毁前一个图表再渲染新图表。

Renders the chart. Accepts two types of input:

Syntax String: Text starting with
```
vis [type]
```
, automatically parsed into a configuration object
JSON Configuration Object: Object containing the
```
type
```
field
Plain Text: Strings not starting with
```
vis 
```
will be rendered as summary type

Calling

render()

multiple times will automatically destroy the previous chart before rendering a new one.

destroy(): void

destroy(): void

销毁当前图表实例，释放资源。

Destroys the current chart instance and releases resources.

语法模式：JSON 格式

Syntax Mode: JSON Format

直接输出符合图表 TypeScript 类型的 JSON 对象，

GPTVis.render()

可直接消费。

Directly outputs a JSON object that conforms to the chart's TypeScript type, which can be directly consumed by

GPTVis.render()

JSON 示例

JSON Example

json

{
  "type": "column",
  "data": [
    { "category": "A产品", "value": 30, "group": "线上" },
    { "category": "B产品", "value": 50, "group": "线上" }
  ],
  "title": "产品销量对比",
  "axisXTitle": "产品",
  "axisYTitle": "销量（万）",
  "stack": true,
  "theme": "academy",
  "style": {
    "palette": ["#5B8FF9", "#61DDAA"]
  }
}

json

{
  "type": "column",
  "data": [
    { "category": "Product A", "value": 30, "group": "Online" },
    { "category": "Product B", "value": 50, "group": "Online" }
  ],
  "title": "Product Sales Comparison",
  "axisXTitle": "Product",
  "axisYTitle": "Sales (10,000 units)",
  "stack": true,
  "theme": "academy",
  "style": {
    "palette": ["#5B8FF9", "#61DDAA"]
  }
}

语法模式：Syntax 格式

Syntax Mode: Syntax Format

类 Markdown 缩进语法，支持流式渲染。第一行必须是

vis [type]

。

Markdown-like indentation syntax that supports streaming rendering. The first line must be

vis [type]

语法规则

Syntax Rules

基本属性 —

key value

，每行一个：

title 年度趋势
theme dark

对象数组 —

data

下每项用

开头，子字段缩进：

{ data: { time: string; value: number; }[]; }

对应：

data
  - time 2020
    value 100
  - time 2021
    value 120

纯值数组 — 每项用

开头：

{ data: number[] }

对应：

data
  - 10
  - 20

含空格的字符串值 — 用引号（单引号或双引号）包裹；不含空格时可省略引号：

categories
  - "North America"
  - '东南 亚'
  - 欧洲

嵌套对象 — 对象名占一行，子属性缩进：

{ style?: { backgroundColor?: string; palette?: string[] } }

对应：

style
  backgroundColor #f0f2f5
  palette
    - #5B8FF9
    - #61DDAA

递归树形 —

children

数组用

缩进：

type TreeData = { name: string; children?: TreeData[] };
{ data: TreeData; }

对应：

data
  name 根节点
  children
    - name 子节点A
      children
        - name 孙节点
    - name 子节点B

Basic Attributes —

key value

, one per line:

title Annual Trend
theme dark

Object Array — Each item under

data

starts with

, sub-fields are indented:

{ data: { time: string; value: number; }[]; }

Corresponds to:

data
  - time 2020
    value 100
  - time 2021
    value 120

Pure Value Array — Each item starts with

{ data: number[] }

Corresponds to:

data
  - 10
  - 20

String Values with Spaces — Wrap with quotation marks (single or double); quotation marks can be omitted if there are no spaces:

categories
  - "North America"
  - 'Southeast Asia'
  - Europe

Nested Objects — Object name occupies one line, sub-properties are indented:

{ style?: { backgroundColor?: string; palette?: string[] } }

Corresponds to:

style
  backgroundColor #f0f2f5
  palette
    - #5B8FF9
    - #61DDAA

Recursive Tree Structure —

children

array is indented with

type TreeData = { name: string; children?: TreeData[] };
{ data: TreeData; }

Corresponds to:

data
  name Root Node
  children
    - name Child Node A
      children
        - name Grandchild Node
    - name Child Node B

Syntax 完整示例

Complete Syntax Example

vis column
data
  - category A产品
    value 30
    group 线上
  - category B产品
    value 50
    group 线上
title 产品销量对比
axisXTitle 产品
axisYTitle 销量（万）
stack true
theme academy
style
  palette
    - #5B8FF9
    - #61DDAA

vis column
data
  - category Product A
    value 30
    group Online
  - category Product B
    value 50
    group Online
title Product Sales Comparison
axisXTitle Product
axisYTitle Sales (10,000 units)
stack true
theme academy
style
  palette
    - #5B8FF9
    - #61DDAA

Markdown 语法

Markdown Syntax

当输出为 Markdown 格式时，使用

GPT-Vis

作为 fenced code block 的语言标记，内容区写入完整的 Syntax 格式：

markdown

```GPT-Vis
vis line
data
  - time 2020
    value 100
```

格式：

```GPT-Vis
<完整的 Syntax 内容，首行 vis <chart-type>>
```

语法规则：

语言标记固定为
```
GPT-Vis
```
内容区使用 Syntax 格式规则编写，首行必须包含
vis <chart-type>
（完整列表见上方支持的图表类型）
代码块会被 Markdown 插件转换为 <code class="language-gpt-vis">，由浏览器端渲染

注意：Markdown 模式下，内容区必须写首行
vis <type>
，与纯 Syntax 模式格式一致。

When outputting in Markdown format, use

GPT-Vis

as the language tag for the fenced code block, and write the complete Syntax Format in the content area:

markdown

```GPT-Vis
vis line
data
  - time 2020
    value 100
```

Format:

```GPT-Vis
<Complete Syntax content, first line is vis <chart-type>>
```

Syntax Rules:

The language tag is fixed as
```
GPT-Vis
```
The content area is written using the Syntax Format rules, the first line must contain
vis <chart-type>
(see the full list in Supported Chart Types above)
The code block will be converted to <code class="language-gpt-vis"> by the Markdown plugin, and rendered on the browser side

Note: In Markdown mode, the content area must include the first line
vis <type>
, which is the same format as the pure Syntax mode.

代码模式

Code Mode

根据目标框架生成完整可运行代码。

Generates complete runnable code based on the target framework.

安装方式

Installation Methods

NPM：

bash

npm install @antv/gpt-vis

javascript

import { GPTVis } from '@antv/gpt-vis';

CDN：

html

<script src="https://unpkg.com/@antv/gpt-vis/dist/umd/index.min.js"></script>

CDN 引入后通过

GPTVis.GPTVis

访问主类。

NPM:

bash

npm install @antv/gpt-vis

javascript

import { GPTVis } from '@antv/gpt-vis';

CDN:

html

<script src="https://unpkg.com/@antv/gpt-vis/dist/umd/index.min.js"></script>

After CDN import, access the main class via

GPTVis.GPTVis

HTML 完整示例

Complete HTML Example

html

<html>
  <head>
    <script src="https://unpkg.com/@antv/gpt-vis/dist/umd/index.min.js"></script>
  </head>
  <body>
    <div id="container"></div>
    <script>
      const gptVis = new GPTVis.GPTVis({
        container: '#container',
        width: 600,
        height: 400,
      });

      gptVis.render(`
vis line
data
  - time 2020
    value 100
  - time 2021
    value 120
title 年度趋势
`);
    </script>
  </body>
</html>

html

<html>
  <head>
    <script src="https://unpkg.com/@antv/gpt-vis/dist/umd/index.min.js"></script>
  </head>
  <body>
    <div id="container"></div>
    <script>
      const gptVis = new GPTVis.GPTVis({
        container: '#container',
        width: 600,
        height: 400,
      });

      gptVis.render(`
vis line
data
  - time 2020
    value 100
  - time 2021
    value 120
title Annual Trend
`);
    </script>
  </body>
</html>

图表类型配置

Chart Type Configurations

通用配置

General Configuration

所有图表均包含以下字段，后续各图表类型定义中省略这些字段。各小节标题即为

type

值（如

line

、

column

），对应上方图表类型表中的 type 列。

{ type: string; title?: string; theme?: 'default' | 'light' | 'dark' | 'academy'; style?: { backgroundColor?: string; palette?: string[] } }

All charts include the following fields, which are omitted in the subsequent chart type definitions. The title of each section is the

type

value (e.g.,

line

column

), corresponding to the Type column in the chart type table above.

{ type: string; title?: string; theme?: 'default' | 'light' | 'dark' | 'academy'; style?: { backgroundColor?: string; palette?: string[] } }

line / area

{ data: { time: string | number; value: number; group?: string }[]; axisXTitle?: string; axisYTitle?: string; stack?: boolean; style?: { lineWidth?: number } }

stack

仅 area 支持。

{ data: { time: string | number; value: number; group?: string }[]; axisXTitle?: string; axisYTitle?: string; stack?: boolean; style?: { lineWidth?: number } }

stack

is only supported for area charts.

column / bar

{ data: { category: string; value: number; group?: string }[]; axisXTitle?: string; axisYTitle?: string; stack?: boolean; group?: boolean }

{ data: { category: string; value: number; group?: string }[]; axisXTitle?: string; axisYTitle?: string; stack?: boolean; group?: boolean }

pie

value 不可使用百分比数字。

{ data: { category: string; value: number }[]; innerRadius?: number }

innerRadius

设为 0.6 变为环图。

Value cannot be a percentage number.

{ data: { category: string; value: number }[]; innerRadius?: number }

Setting

innerRadius

to 0.6 turns it into a donut chart.

scatter

{ data: { x: number; y: number; group?: string }[]; axisXTitle?: string; axisYTitle?: string }

{ data: { x: number; y: number; group?: string }[]; axisXTitle?: string; axisYTitle?: string }

dual-axes

{ categories: string[]; series: { type: 'line' | 'column'; data: number[]; axisYTitle?: string }[]; axisXTitle?: string; style?: { startAtZero?: boolean } }

{ categories: string[]; series: { type: 'line' | 'column'; data: number[]; axisYTitle?: string }[]; axisXTitle?: string; style?: { startAtZero?: boolean } }

histogram

{ data: number[]; binNumber?: number; axisXTitle?: string; axisYTitle?: string }

{ data: number[]; binNumber?: number; axisXTitle?: string; axisYTitle?: string }

boxplot / violin

同一 category 需多条数据以展示分布。

{ data: { category: string; value: number; group?: string }[]; axisXTitle?: string; axisYTitle?: string; style?: { startAtZero?: boolean } }

Multiple data entries are required for the same category to display distribution.

{ data: { category: string; value: number; group?: string }[]; axisXTitle?: string; axisYTitle?: string; style?: { startAtZero?: boolean } }

radar

{ data: { name: string; value: number; group?: string }[]; align?: boolean }

align

: 是否对齐各维度比例尺，默认 false（各轴独立缩放）；true 时所有轴共享同一最大值，适合多系列绝对数值对比。

{ data: { name: string; value: number; group?: string }[]; align?: boolean }

align

: Whether to align the scales of each dimension, default is false (each axis scales independently); when true, all axes share the same maximum value, suitable for absolute value comparison of multiple series.

funnel

{ data: { category: string; value: number; }[]; }

{ data: { category: string; value: number; }[]; }

waterfall

value 可为负数表示减少。palette 为色板数组，顺序为 [正值色, 负值色, 汇总色]。

{ data: { category: string; value: number }[]; axisXTitle?: string; axisYTitle?: string; style?: { palette?: string[] } }

Value can be negative to indicate a decrease. Palette is an array of colors in the order [positive value color, negative value color, summary color].

{ data: { category: string; value: number }[]; axisXTitle?: string; axisYTitle?: string; style?: { palette?: string[] } }

liquid

percent

范围 0~1。

{ percent: number; shape?: 'rect' | 'circle' | 'pin' | 'triangle' }

percent

ranges from 0 to 1.

{ percent: number; shape?: 'rect' | 'circle' | 'pin' | 'triangle' }

word-cloud

{ data: { text: string; value: number; }[]; }

{ data: { text: string; value: number; }[]; }

venn

交集用逗号分隔集合标识：

sets: "A,B"

。

label

用于显示图表上对应集合的名称

{ data: { sets: string | string[]; value: number; label?: string }[] }

Intersections are identified by separating set labels with commas:

sets: "A,B"

label

is used to display the name of the corresponding set on the chart

{ data: { sets: string | string[]; value: number; label?: string }[] }

treemap

type TreeNode = { name: string; value: number; children?: TreeNode[] };
{ data: TreeNode[] }

type TreeNode = { name: string; value: number; children?: TreeNode[] };
{ data: TreeNode[] }

sankey

{ data: { source: string; target: string; value: number }[]; nodeAlign?: 'left' | 'center' | 'right' | 'justify' }

{ data: { source: string; target: string; value: number }[]; nodeAlign?: 'left' | 'center' | 'right' | 'justify' }

flow-diagram / network-graph

source

target

引用节点的

name

。

type GraphData = { nodes: { name: string }[]; edges: { source: string; target: string; name?: string }[] };

// flow-diagram
{ data: GraphData }

// network-graph
{ data: GraphData; layout?: 'force' | 'circular' | 'grid' | 'radial' | 'concentric' | 'dagre' }

source

target

reference the

name

of nodes.

type GraphData = { nodes: { name: string }[]; edges: { source: string; target: string; name?: string }[] };

// flow-diagram
{ data: GraphData }

// network-graph
{ data: GraphData; layout?: 'force' | 'circular' | 'grid' | 'radial' | 'concentric' | 'dagre' }

mindmap / indented-tree / organization-chart

type TreeData = { name: string; children?: TreeData[] };

// mindmap
{ data: TreeData; direction?: 'H' | 'LR' | 'RL' }

// indented-tree
{ data: TreeData; direction?: 'LR' | 'RL' | 'H' }

// organization-chart
type OrganizationChartData = {
  name: string;
  description?: string;
  children?: OrganizationChartData[];
};

{ data: OrganizationChartData }

mindmap 默认

'H'

，indented-tree 默认

'LR'

。

type TreeData = { name: string; children?: TreeData[] };

// mindmap
{ data: TreeData; direction?: 'H' | 'LR' | 'RL' }

// indented-tree
{ data: TreeData; direction?: 'LR' | 'RL' | 'H' }

// organization-chart
type OrganizationChartData = {
  name: string;
  description?: string;
  children?: OrganizationChartData[];
};

{ data: OrganizationChartData }

mindmap defaults to

'H'

, indented-tree defaults to

'LR'

fishbone-diagram

type FishboneNode = { name: string; children?: FishboneNode[] };
{ data: FishboneNode; style?: { texture?: 'rough' | 'default' } }

texture: 'rough'

为手绘风格。

type FishboneNode = { name: string; children?: FishboneNode[] };
{ data: FishboneNode; style?: { texture?: 'rough' | 'default' } }

texture: 'rough'

enables hand-drawn style.

table

{ data: Record<string, string | number>[]; }

{ data: Record<string, string | number>[]; }

summary

summary 与其他图表类型完全不同：不使用 Syntax/JSON 配置，而是使用 T8 语法（Markdown + 语义标注）。

⚠️ 生成 summary 前必须：先读取 references/summary.md 获取 T8 语法规则、完整实体类型列表、属性字段定义、生成要求和示例，然后再生成内容。跳过此步骤将导致语法错误。

summary is completely different from other chart types: It does not use Syntax/JSON configuration, but uses T8 syntax (Markdown + semantic annotation).

⚠️ Before generating summary, you must: First read references/summary.md to obtain T8 syntax rules, complete entity type list, attribute field definitions, generation requirements and examples, then generate content. Skipping this step will result in syntax errors.

最佳实践

Best Practices

饼图分类不超过 5 个，超过建议合并为"其它"或改用条形图
不要用饼图展示趋势，不要用折线图展示无序分类
数值字段必须是数字类型，分类字段必须是文本类型
连续数值的分布（如薪资、成绩、年龄）必须用直方图（histogram）
多维数据字段映射：有两个分类维度时，x 轴维度写
```
time
```
/
```
category
```
，另一个写
```
group
```
语法模式优先用 Syntax 格式（流式友好）
代码模式默认生成 HTML + CDN 方案（零安装），用户指定框架时再用 npm 方案

Do not use more than 5 categories for pie charts; if exceeded, merge into "Others" or use bar charts instead
Do not use pie charts to show trends, or line charts to show unordered categories
Numeric fields must be of number type, categorical fields must be of text type
Use histogram for distribution of continuous values (e.g., salary, grades, age)
Multi-dimensional data field mapping: When there are two categorical dimensions, write the x-axis dimension as
```
time
```
/
```
category
```
, and the other as
```
group
```
Prefer Syntax format in Syntax Mode (streaming-friendly)
Default to HTML + CDN solution (zero installation) in Code Mode; use npm solution only when user specifies a framework