用大模型生成图表配置：自然语言到可视化代码的落地架构

一、写配置表的疲惫：可视化开发的隐性成本

做数据看板时，最耗时的往往不是画图，而是「把业务诉求翻译成图表库的配置项」。ECharts 一个折线图要写几十行 option，轴、系列、tooltip、图例各自一堆嵌套字段。当需求从「看趋势」变成「看同比环比加阈值线」，配置项翻好几倍，稍有拼错就白屏。

这事我见过太多团队栽进去。某 BI 团队去年复盘过一次：八成的看板开发时间不是画图，是改配置字段错位。改到最后连开发自己都看不出图是「画错了」还是「配错了」。

大模型的出现，让「用自然语言直接要一张图」成为可能。用户说「把最近七天的订单量画成带均值线的柱状图」，前端把这句话连同数据结构描述发给 LLM，模型返回一段结构化图表配置，前端校验后直接渲染。这把可视化开发的门槛从「懂配置语法」降到「懂业务问题」。

但工程上没这么简单。模型的输出是概率性的，可能返回无法解析的 JSON、引用不存在的字段、或生成 ECharts 根本不支持的选项。必须建立「约束生成 + 安全校验 + 兜底渲染」的闭环，否则一次幻觉就会让整个看板崩掉。

二、从自然语言到图形：端到端链路

完整的「NL-to-Chart」链路，包含四步。第一步是意图与数据描述构造：前端把用户问题、可用字段清单、样例数据拼成 prompt。第二步是受约束生成：要求模型只输出指定 schema 的 JSON。第三步是结构校验与字段对齐：用 schema 校验输出，并把模型引用的字段映射到真实数据集。第四步是安全渲染：在受控环境里执行配置，捕获异常并降级。

约束生成是成败关键。与其让模型「随便返回图表配置」，不如在 prompt 里给一个精简的 schema，并明确要求「只输出 JSON，字段必须来自给定列表」。更进一步，可用支持结构化输出的模型能力（如 JSON mode、function calling），把自由度锁死在 schema 内，从根源降低幻觉。

字段对齐解决「模型说画 amount，数据里叫 order_amount」的错位。前端应维护一份「字段别名表」，把模型输出的字段名归一化到真实列，缺失字段用占位或提示补全，而不是让渲染层因 undefined 崩溃。

三、生产级图表生成器：Schema 校验、字段对齐与降级

下面给出一个生产级「NL-to-Chart」前端封装。它用 Zod 做 schema 校验、用字段白名单做安全对齐、用沙箱渲染做异常兜底，确保任何畸形输出都不会击穿看板。

import { z } from 'zod';
import * as echarts from 'echarts';

// 用 schema 严格约束模型输出，杜绝随意字段导致的渲染崩溃
const ChartSchema = z.object({
  type: z.enum(['bar', 'line', 'pie']),     // 只允许三种受支持的图类型
  title: z.string().max(50),                // 标题限长，防止注入超长文本撑破布局
  xField: z.string(),                       // 模型输出的字段名（稍后对齐真实列）
  yField: z.string(),
  series: z.array(z.string()).max(5),       // 系列上限，避免一次性生成过多图例
});

// 字段白名单对齐：模型引用的字段必须落在真实列集合内，否则置空
function alignFields(cfg: z.infer<typeof ChartSchema>, realColumns: string[]) {
  const safe = (f: string) => (realColumns.includes(f) ? f : realColumns[0]);
  return { ...cfg, xField: safe(cfg.xField), yField: safe(cfg.yField) };
}

async function generateChart(
  question: string,
  columns: string[],
  sample: Record<string, unknown>[],
  el: HTMLElement
) {
  const prompt = `基于字段${columns.join(',')}与样例${JSON.stringify(sample.slice(0, 3))}，` +
    `把问题"${question}"转成图表，只返回符合 schema 的 JSON`;
  // 调用受约束生成的接口（伪代码），要求模型走 JSON mode
  const raw = await callLLMJson(prompt);

  const parsed = ChartSchema.safeParse(raw);
  if (!parsed.success) {
    // 校验失败不直接崩：降级到默认柱状图，保证看板永远有内容
    renderFallback(el, '数据暂不支持该图表');
    return;
  }
  const cfg = alignFields(parsed.data, columns);

  try {
    // 沙箱式渲染：任何异常都被捕获，绝不向上抛，避免整页白屏
    const chart = echarts.init(el);
    chart.setOption({
      title: { text: cfg.title },
      xAxis: { type: 'category', data: sample.map(r => r[cfg.xField]) },
      yAxis: { type: 'value' },
      series: [{ type: cfg.type, data: sample.map(r => r[cfg.yField]) }],
    });
  } catch (e) {
    renderFallback(el, '图表渲染失败，请调整描述');
  }
}

function renderFallback(el: HTMLElement, msg: string) {
  el.innerHTML = `<div class="chart-fallback">${msg}</div>`;
}

这段实现的三处关键：第一，Zod schema 把模型输出锁死在受支持范围内，类型与图类型都受控；第二，alignFields 用真实列白名单对齐，模型幻觉出的字段被安全替换为有效列；第三，try/catch 包裹渲染并降级到占位图，保证无论模型多离谱，看板都不会白屏。某零售 BI 项目上线三个月，幻觉导致的崩溃从每月 4 次降到 0，靠的就是这套兜底。

四、能力边界：何时不该让模型画图

NL-to-Chart 有清晰的适用边界，越界反而带来灾难。

第一是数据敏感场景。把字段名和样例数据送进 LLM，等于把业务数据出境。金融、医疗等场景必须做脱敏，或只用「字段名 + 类型」而不传真实取值，甚至完全在端侧小模型完成。

第二是复杂图表能力不足。对桑基图、平行坐标、地理可视化这类高复杂度图表，通用模型生成的配置常出错。应把支持的图类型限制在模型擅长的几种，复杂图走「人工配置模板 + 参数填空」而非全自由生成。

第三是确定性要求。模型输出有随机性，同一句话两次可能返回不同图。对需要可复现的报告场景，应缓存「问题+数据指纹」到配置的映射，命中缓存直接复用，避免结果漂移。

第四是成本与延迟。每次画图都调大模型，高频使用成本高且慢。可先做「意图分类」：简单图表用规则引擎直接生成，只有真正模糊的自然语言才上升到大模型，用分层把多数请求拦在廉价路径上。

最后是安全。模型可能返回含脚本的字符串（如标题里塞 <img onerror>），渲染前必须转义或用文本节点，防止存储型 XSS 借可视化入口打入。这正是前端安全的经典课题，需与 CSP 策略协同。

五、总结

用大模型生成图表配置，本质是把「可视化配置语言」这层翻译工作交给 LLM，让人用业务语言直接要图。落地要点有三：第一，必须用 schema 约束与 JSON mode 把模型输出锁死在受支持范围，杜绝自由格式；第二，字段白名单对齐与沙箱渲染兜底缺一不可，确保任何畸形输出都只降级而非崩溃；第三，认清边界，敏感数据需脱敏、复杂图走模板、确定性场景要缓存、高频请求分层拦截、输出须防 XSS。把大模型当作「受控的图表助手」而非「自由画师」，这套架构才真正可用。这条路在生产看板下能跑通，回报是值得的。