简介：这份文档面向具备一定编程基础的研发人员、项目经理与数据分析师，聚焦如何借助DeepSeek与Mermaid实现可视化图表的自动化生成。内容从DeepSeek的发展历程、MoE架构与多场景应用切入，系统讲解Mermaid的文本语法及流程图、时序图、甘特图等图表类型，并通过电商平台开发项目实战，演示从自然语言指令到Mermaid代码、再到图表渲染的完整链路，可应用于需求分析、系统设计、编码辅助与测试验证等环节。资源包为1个docx文档，约40KB，结构紧凑，便于集中阅读与查阅。目前已有393人学习。读者可借此掌握自然语言驱动图表生成的方法，理解两者交互技巧，并参考实战案例将思路迁移到自身项目的流程梳理与架构表达中。
1. 从一张季度汇报图说起：DeepSeek+Mermaid 到底在自动化什么
季度汇报前一晚，业务方临时把「华东区销售额」改成了「华东区+华南区合并口径」，你手里那张用画图工具拖了四十分钟的柱状图，等于白做。这种场景做数据的人都不陌生：数据在变、口径在变、汇报对象在变，唯独图不能自动跟着变。DeepSeek 与 Mermaid 结合实现自动化图表生成，解决的正是这个痛点——让大模型读懂你的自然语言或结构化数据，直接吐出可渲染的 Mermaid 代码，图表随数据源更新而重新生成，而不是靠人手一次次重画。
这套方案适合三类人：一是经常出周报月报、被图表反复折磨的数据分析和运营；二是想把「文字描述→图表」嵌进内部工具的后端与全栈工程师；三是需要批量产出架构图、流程图的文档维护者。它不要求你会前端绘图库，核心成本只是把提示词和校验逻辑写扎实。下面按「先立住原理、再跑通最小闭环、最后处理翻车现场」的顺序拆开讲，中间会给出可直接抄的调用代码和参数表。
2. 拆开这条流水线：DeepSeek 出代码、Mermaid 负责渲染
2.1 为什么是 Mermaid 而不是让模型直接画图
很多人第一反应是让多模态模型直接生成图片，但那条路在工程上很难走通：图片是黑匣子，改一个数字就得整张重画，版本对比、diff、批量替换全都做不了。Mermaid 的价值在于它是文本化的图表描述语言，柱状图、流程图、时序图、甘特图都能用纯文本表达，文本就能被 Git 管理、被程序拼接、被模型稳定生成。
常见做法是让 DeepSeek 输出 Mermaid 代码块，前端用 mermaid.js 渲染，后端只存文本。这样图表和数据源解耦：数据变了，重新跑一次生成逻辑即可，历史版本还能追溯。Mermaid 支持的类型里，做数据汇报最常用的是xychart-beta（柱状图/折线图）、pie（饼图）、flowchart（流程图），选型时先确认你的渲染环境版本是否支持，老版本对xychart-beta支持不完整，这是第一个容易忽略的边界。
2.2 DeepSeek 在这条链路里扮演的角色
DeepSeek 不是「画图工具」，它是结构化文本生成器。你给它一段数据加一句意图描述，它负责把意图翻译成符合 Mermaid 语法的代码。这里的关键认知是：模型不保证语法 100% 正确，所以工程上必须加一层校验和重试，而不是拿到输出就直接渲染。
调用方式上，走 API 是最稳的，本地部署适合数据不能出内网的场景。API 调用要关注三个参数：model选对话/通用模型即可，temperature建议压到 0.2 以下保证输出稳定，max_tokens要留够，Mermaid 代码虽然不长但模型可能先输出解释文字。下面是一个最小可跑的 Python 调用示例，把「数据 + 图表类型」拼进提示词，要求模型只返回代码块。
import os import re import requests API_URL = "https://api.deepseek.com/chat/completions" # 以官方开放平台实际地址为准 API_KEY = os.environ["DEEPSEEK_API_KEY"] def gen_mermaid(data_desc: str, chart_type: str = "柱状图") -> str: prompt = f"""你是 Mermaid 代码生成器。根据下面的数据生成一张{chart_type}。 要求： 1. 只输出一个 ```mermaid 代码块，不要任何解释文字； 2. 使用 xychart-beta 语法（柱状图/折线图）； 3. 坐标轴标签用中文，数值保留原始精度。 数据：{data_desc} """ resp = requests.post( API_URL, headers={"Authorization": f"Bearer {API_KEY}"}, json={ "model": "deepseek-chat", "messages": [{"role": "user", "content": prompt}], "temperature": 0.2, # 压低随机性，保证同类输入输出稳定 "max_tokens": 1024, }, timeout=60, ) resp.raise_for_status() content = resp.json()["choices"][0]["message"]["content"] # 从返回文本里抠出 mermaid 代码块，防止模型夹带解释 match = re.search(r"```mermaid\s*(.*?)```", content, re.S) return match.group(1).strip() if match else content.strip() if __name__ == "__main__": print(gen_mermaid("2024年Q1-Q4销售额：120万、150万、180万、210万", "柱状图"))逻辑说明：提示词里明确「只输出代码块」能大幅降低模型啰嗦的概率，但不能完全依赖它，所以用正则兜底抽取。temperature=0.2是血泪经验，温度高了模型会自作主张改数据结构或加装饰性文字。timeout=60是因为复杂图表生成偶尔会慢，超时太短会误判失败。参数上，如果你的数据点超过 30 个，max_tokens要相应调大，否则代码会被截断，渲染时报语法错误。
2.3 渲染端怎么接：前端 mermaid.js 最小集成
生成出来的代码最终要落到页面上。前端集成 mermaid.js 的核心就三步：引入库、初始化、把代码文本喂给渲染函数。注意 Mermaid 渲染是异步的，且同一页面多次渲染要避免 ID 冲突。
import mermaid from "mermaid"; mermaid.initialize({ startOnLoad: false, // 手动控制渲染时机，避免和框架生命周期打架 theme: "default", securityLevel: "loose", // 允许渲染较复杂的图表，内网可信环境使用 }); async function renderChart(code, containerId) { const { svg } = await mermaid.render(`chart-${containerId}`, code); document.getElementById(containerId).innerHTML = svg; } // 调用示例 renderChart(`xychart-beta title "季度销售额" x-axis [Q1, Q2, Q3, Q4] y-axis "金额(万)" 0 --> 250 bar [120, 150, 180, 210]`, "chart-box");逻辑说明：startOnLoad: false是关键，否则页面加载时 Mermaid 会扫描全文档自动渲染，和你的手动调用冲突。mermaid.render的第一个参数是唯一 ID，用容器 ID 拼接能避免多图同页时的冲突。securityLevel在纯内网可信环境可以放宽，公网场景要谨慎，因为它涉及 HTML 注入面。参数上，theme可选default、dark、forest等，做深色主题汇报时直接切dark省事。
3. 把提示词写成模板：让 DeepSeek 稳定产出可渲染的 Mermaid 代码
3.1 提示词模板的四个必备字段
模型输出不稳定，八成是提示词太随意。我一般把提示词固定成四个字段：角色、任务、语法约束、输出格式。角色告诉模型「你是代码生成器不是聊天助手」，任务描述图表类型和数据，语法约束锁定 Mermaid 版本和图表种类，输出格式强制只要代码块。这四块缺一块，输出质量就往下掉。
下面这张表是我在实际项目里调过的参数对照，直接决定生成成功率：
| 字段 | 推荐写法 | 不写会怎样 |
|---|---|---|
| 角色 | 「你是 Mermaid 代码生成器」 | 模型开始解释、寒暄 |
| 图表类型 | 明确xychart-beta/pie/flowchart | 模型自选类型，可能不支持 |
| 语法约束 | 「只使用 xychart-beta 语法」 | 混用旧语法导致渲染失败 |
| 输出格式 | 「只输出一个 mermaid 代码块」 | 夹带解释文字，正则抽取失败 |
3.2 用 few-shot 示例把柱状图生成钉死
光靠文字约束还不够，给一两个示例（few-shot）能显著提升稳定性。做法是在提示词里塞一个「输入→输出」的样例，模型会模仿这个格式。这对 mermaid 柱状图这种有固定语法结构的场景特别有效。
FEW_SHOT = """示例： 输入：2023年A/B/C三产品销量 30、50、20 输出： ```mermaid xychart-beta title "产品销量" x-axis [A, B, C] y-axis "销量" 0 --> 60 bar [30, 50, 20]"""
def build_prompt(data_desc: str) -> str: return f"""你是 Mermaid 代码生成器，只输出 mermaid 代码块。 {FEW_SHOT} 现在请处理： 输入：{data_desc} 输出："""
逻辑说明：示例里的 `y-axis` 上限我习惯给到数据最大值的 1.2 倍左右，留出视觉余量，否则柱子顶到边框很难看。`x-axis` 的标签如果是中文，注意不要带空格和特殊符号，Mermaid 对含空格的标签解析容易出问题，必要时用引号包起来。这套模板跑下来，简单柱状图的首次生成成功率能到九成以上，剩下的靠校验重试兜底。 ### 3.3 生成后的语法校验与自动重试 再稳的提示词也会翻车，所以校验层不能省。校验分两步：先做**结构校验**（是否包含 `xychart-beta`、`x-axis`、`bar` 等关键字），再做**渲染校验**（丢给 mermaid 解析，捕获异常）。校验不过就把错误信息回灌给模型重试，最多重试两到三次。 ```python def validate_mermaid(code: str) -> bool: required = ["xychart-beta", "x-axis", "y-axis", "bar"] return all(k in code for k in required) def gen_with_retry(data_desc: str, max_retry: int = 3) -> str: for i in range(max_retry): code = gen_mermaid(data_desc) if validate_mermaid(code): return code # 把失败原因回灌，让模型针对性修正 data_desc = f"{data_desc}\n上次输出缺少必要关键字，请严格按 xychart-beta 语法重写。" raise RuntimeError("多次生成仍未通过校验，请检查数据格式")逻辑说明：结构校验是廉价的第一道闸，能拦掉大部分明显错误。回灌错误信息时不要只说「错了」，要指出缺什么，模型修正的命中率会高很多。max_retry不建议超过 3，再多说明提示词本身有问题，该回去改模板而不是硬重试。渲染校验需要在前端或 Node 环境跑，后端纯 Python 场景可以只做结构校验，把渲染校验放到前端兜底。
4. 避坑与排查：Mermaid 自动化生成最常见的五个翻车现场
4.1 现象：渲染出来一片空白，控制台报 parse error
原因：模型生成的语法和当前 mermaid.js 版本不匹配，最常见的是用了新版才支持的xychart-beta，而项目里引的是老版本。解决：先确认渲染库版本，xychart-beta需要较新的版本；如果升级成本高，就让模型改用兼容性更好的pie或flowchart表达。排查时把生成的代码贴到 Mermaid 官方在线编辑器里试，能快速定位是语法问题还是集成问题。
4.2 现象：中文标签显示成方块或乱码
原因：Mermaid 渲染依赖页面字体，SVG 里的中文如果页面没加载对应字体就会回退成方块。解决：在页面 CSS 里给 SVG 容器指定中文字体栈，比如font-family: "PingFang SC", "Microsoft YaHei", sans-serif;。另外坐标轴标签含空格或特殊符号时，用引号包裹，例如x-axis ["华东 区", "华南区"]，避免解析歧义。
4.3 现象：数据点一多，柱子挤成一团看不清
原因：xychart-beta默认按数据点均分宽度，几十个点堆在一起必然糊。解决：超过 15 个数据点就别用柱状图了，改用折线图（line替代bar），或者先做数据聚合再画。这是选型问题不是代码问题，硬调样式救不回来。我一般会在提示词里加一条规则：数据点超过 15 个时自动改用折线图。
4.4 现象：模型偶尔返回解释文字，正则抽不到代码块
原因：提示词约束不够强，或者temperature偏高。解决：双管齐下，提示词里把「只输出代码块」放到最前面并加粗强调，同时把temperature压到 0.1~0.2。正则也要写宽松点，兼容```mermaid和```两种围栏，别只匹配一种。
4.5 现象：批量生成几十张图时接口频繁超时或限流
原因：并发太高触发限流，或单次请求max_tokens设太大导致响应慢。解决：加并发控制，用信号量把并发压到个位数；max_tokens按实际需要设，柱状图 512 通常够用。批量任务建议加队列和失败重试，别用for循环裸调，一张失败整批中断。
5. 进阶：把图表生成接进文档流水线，顺带聊聊验证习惯
单张图生成跑通只是起点，真正省时间的是把它接进文档流水线。我的做法是：数据源（CSV 或数据库查询结果）→ 脚本读取并转成自然语言描述 → 调 DeepSeek 生成 Mermaid → 校验 → 写入 Markdown 文件 → CI 里用 mermaid-cli 渲染成 SVG 或 PNG 归档。这样每次数据更新，跑一遍脚本，文档里的图自动刷新，彻底告别手工重画。
验证环节我踩过的坑值得单独说：不要只看图好不好看，要看代码对不对。渲染成功不代表数据映射正确，模型可能把「120万」写成「120」丢掉单位，或者把两个系列的数据顺序搞反。我的习惯是生成后做一次数值回读——从 Mermaid 代码里把bar [...]的数组解析出来，和原始数据逐个比对，不一致就报警。这一步多花十秒，能省掉汇报现场被问「这个数怎么不对」的尴尬。
再进阶一点，可以把常用的图表类型做成配置表，让非技术同事填数据就能出图：
| 场景 | 图表类型 | 关键参数 |
|---|---|---|
| 季度销售对比 | xychart-beta bar | y-axis 上限取最大值 1.2 倍 |
| 占比分析 | pie | 数据项不超过 8 个 |
| 流程说明 | flowchart TD | 节点文字避免特殊符号 |
| 项目排期 | gantt | 日期格式统一 YYYY-MM-DD |
最后说个我自己的习惯：每次改提示词模板，我都会留一组固定的「回归测试数据」，改完跑一遍看输出有没有退化。模型和库都会更新，今天好用的提示词明天可能就翻车，有回归集才能安心迭代。这套东西不难，难的是把校验和重试当回事，别指望模型一次就对。希望帮到你。
本文还有配套的精品资源，点击获取
