---
url: /guide/ai.md
---
# AI 生成

让图表从数据与一句话需求里长出来：粘贴表格数据，引擎自动识别列类型（时间 / 数值 / 类目）、选择图表类型、映射字段并渲染；描述里带「趋势 / 占比 / 排行 / 堆叠 / 关系」等意图词时按意图选型，留空则按数据形状推断。年份列（`1970` 这类裸年份，或数值型年份配「年份 / year」表头）自动认作时间维度；多个度量之间量级悬殊（峰值相差百倍以上）时自动切双轴——大度量柱走左轴、其余线走右轴，小度量不再被压成贴地直线。三维同一条路径可达：明确要三维或数据天然三维（三个数值列无类目维度）时产出三维 Spec。要接自己的大模型？`buildChartPrompt()` 产出标准提示词，模型返回的 JSON 过一遍 `lintChartSpec()` 自检修正，`setSpec()` 回放即得图。

## 数据直生

下面是一个可编辑的完整闭环：改表格或改描述，点「生成图表」——列推断、选型理由与自检结论全部可见。

`setSpec()` 是整体替换：每点一次「生成图表」就是换一张图，图例、缩放、焦点等交互态一并重置。

## 三维生成

二维能讲清的数据不会硬上三维。两种情况进三维选型：描述里明确要「三维 / 立体 / 3D」，或数据天然三维——三个数值列且没有类目维度（二维散点必丢一维）。三个数值列恰好构成完整网格（前两列取值的组合覆盖全部行）时产出 `surface3d` 高度场，稀疏三元组则是 `scatter3d`；带类目或时间维度时按意图映射 `bar3d` 柱林 / `line3d` 空间折线 / `pie3d` 三维饼，维度不足则告警并回退二维。`lintChartSpec()` 遇到 `*3d` 图型会自动切三维契约校验。

三维图型与相机配置详见[三维篇章](/3d/)。

## 接入大模型

库不做内置模型调用——`buildChartPrompt()` 把 Schema、数据预览与硬性规则打包成提示词，喂给你自己的模型（在线 API 或私有部署均可），返回的 JSON 自检后回放：

```js
import { buildChartPrompt, lintChartSpec } from '@wil-works/evoke-charts'

// 1. 组提示词（含 options JSON Schema、数据预览与硬性规则）
const prompt = buildChartPrompt({ data: tableText, requirement: '近半年各渠道销售额占比' })

// 2. 喂给你的模型，取回 JSON（示意）
const spec = JSON.parse(await myLLM.complete(prompt))

// 3. 自检修正后 setSpec 回放
const { spec: safe, issues } = lintChartSpec(spec)
if (!issues.some((i) => i.level === 'error')) chartRef.value.setSpec(safe)
```

模型不可用或返回不合格时，`generateChartSpec()` 的确定性推断就是兜底路径——同一段数据，两条路产出同一份 Spec 契约。要生成三维配置，把 `mode` 换成 `'3d'`：Schema、few-shot 示例与硬性规则整套切到三维篇章契约（EvChart3d options）。

## API

## 相关

* [Spec 契约](/chart/api#spec-契约)（getSpec / setSpec / validateOptions）
* [折线图](/chart/line)（叙述注解与分幕编排示例）