1. 项目概述用自然语言生成专业图表最近在折腾一个很有意思的Side Project起因是每次写技术文档或者设计系统架构时画流程图、时序图这些玩意儿太费劲了。用传统的绘图工具吧拖拽调整对齐半天时间就没了用代码画吧比如Mermaid语法虽然能版本管理但写起来又得记一堆语法规则不够直观。我就想能不能像跟同事聊天一样用大白话描述一下我想要什么图然后工具就自动给我生成出来这个想法催生了这个项目Diagram GPT。它的核心功能非常简单你用自然语言描述你的图表它调用AI比如ChatGPT来理解你的意图并生成对应的图表代码目前主要是Mermaid语法最后实时渲染成可视化的图表。听起来是不是有点像“魔法”其实背后的技术栈并不复杂但组合起来效果拔群。它非常适合开发者、产品经理、技术写作者或者任何需要频繁绘制技术图表但又不想在绘图工具上耗费太多时间的人。你可以用它来快速绘制流程图描述一个算法或业务流程。时序图展示组件或服务之间的交互顺序。类图勾勒面向对象设计中的类关系。用户旅程图可视化用户在应用中的体验路径。甘特图规划项目时间线。C4模型图用不同层次描述软件架构。接下来我会从技术选型、实现细节、踩坑经验到部署优化完整地拆解这个项目的构建过程。如果你也对用AI赋能开发工具感兴趣或者想自己动手实现一个类似的“自然语言转图表”应用这篇长文应该能给你提供一条清晰的路径。2. 技术栈选型与架构设计在动手写代码之前技术栈的选型决定了项目的开发体验、维护成本和最终效果。我的核心思路是前端要快、要好看、交互要流畅后端要轻、要稳、要能处理好AI的“异步”特性。2.1 前端Next.js shadcn/ui Mermaid.js为什么是Next.js首先这个应用的核心交互是用户输入文本 - 发送请求 - 等待AI响应 - 渲染图表。这是一个典型的客户端与服务端交互的场景。Next.js的App Router提供了极其优雅的服务端组件Server Components和服务器动作Server Actions模式完美契合这个需求。服务端组件我可以把调用OpenAI API、生成Mermaid代码这些敏感且耗时的逻辑完全放在服务端避免将API密钥暴露给前端也提升了安全性。服务器动作在表单提交时可以直接在React组件中定义一个async函数这个函数会在服务端执行。这意味着我的前端代码可以直接“调用”后端逻辑无需手动创建API路由、处理fetch请求极大地简化了数据流。用户点击“生成”按钮触发的就是一个服务器动作干净利落。全栈一体化Next.js让我在一个项目里就能搞定前后端部署也简单比如Vercel一键部署非常适合个人项目快速迭代。UI库为什么选shadcn/ui我需要一个看起来专业、现代但又不能太臃肿的UI。shadcn/ui不是传统的npm包而是一套可以拷贝到项目中的可复用组件代码。这意味着完全可控所有组件代码都在自己项目里我可以随意修改样式、行为定制化程度极高。零运行时开销组件基于Tailwind CSS和Radix UI构建没有额外的运行时库负担性能好。开发体验佳它提供了漂亮的、可访问的组件如按钮、输入框、卡片、弹窗等让我能快速搭建出专业的界面而不用从零开始设计。图表渲染Mermaid.js这是图表生成领域的“事实标准”。它是一个基于JavaScript的图表绘制工具使用类似Markdown的文本定义来生成图表。选择它是因为文本驱动AI生成的输出正好是一段文本Mermaid代码与Mermaid.js的输入格式天然匹配。丰富的图表类型支持我们需要的所有图表类型且社区活跃文档完善。易于集成在React/Next.js项目中有成熟的库如mermaid-js/react-mermaid可以方便地集成实现动态渲染。2.2 后端与AI集成OpenAI API Vercel AI SDK核心OpenAI API这是项目的“大脑”。我们需要GPT模型来理解用户的自然语言描述并将其“翻译”成结构化的Mermaid代码。这里我主要使用gpt-3.5-turbo模型性价比高对于图表生成这种结构化输出任务能力完全足够。后续如果对复杂描述或图表准确性要求更高可以无缝升级到gpt-4。开发加速器Vercel AI SDK这是让开发变得愉悦的关键。Vercel AI SDK提供了一套统一的、类型安全的API来与各种AI模型OpenAI, Anthropic等交互。简化流式响应如果我想实现图表代码一个字一个字“流式”返回的效果增强用户体验这个SDK提供了streamText等工具处理起来比直接操作OpenAI的原始流接口简单太多。类型安全与工具调用它鼓励定义清晰的请求/响应类型并且支持OpenAI的“Function Calling”现在叫“Tool Calling”这理论上可以让AI更准确地输出我们想要的Mermaid代码格式。不过在这个项目的初版我采用了更直接的Prompt工程来实现。2.3 整体架构设计基于以上技术栈项目的架构非常清晰用户界面层Next.js前端提供输入框、图表类型选择器、渲染区域。用户在此交互。API交互层Next.js Server Action用户提交表单时触发一个定义在服务端的异步函数Server Action。AI处理层Server Action内部该函数接收用户输入和图表类型。构造一个精心设计的Prompt发送给OpenAI API。等待并接收AI返回的Mermaid代码。图表渲染层Mermaid.js将AI返回的Mermaid代码传递给React组件由Mermaid.js库在浏览器中渲染成SVG图表。状态与显示将生成的图表代码和渲染结果更新到前端界面。这个架构的优点是数据流单向、清晰安全API key在服务端且利用了Next.js的最新特性开发效率很高。3. 核心实现细节与Prompt工程有了架构接下来就是填充血肉。最核心的两个部分是如何在服务端安全地调用OpenAI以及如何设计Prompt让AI准确地输出Mermaid代码。3.1 环境配置与安全调用OpenAI首先绝对不要在客户端代码中硬编码OpenAI API密钥。正确的做法是使用环境变量。1. 创建环境变量文件在项目根目录创建.env.local文件并添加你的OpenAI API密钥。OPENAI_API_KEYsk-your-secret-key-here2. 在服务端代码中读取在你的Server Action或API Route中通过process.env.OPENAI_API_KEY来读取。Next.js会自动加载.env.local中的变量并且这些变量默认只在服务端可用。3. 初始化OpenAI客户端我通常会在项目里创建一个lib/openai.ts这样的工具文件。import OpenAI from openai; // 检查环境变量如果不存在则抛出清晰错误便于调试 if (!process.env.OPENAI_API_KEY) { throw new Error(Missing OPENAI_API_KEY environment variable); } export const openai new OpenAI({ apiKey: process.env.OPENAI_API_KEY, });这样在Server Action中我就可以导入这个配置好的openai客户端来发起请求了。注意将.env.local添加到你的.gitignore文件中确保密钥不会提交到代码仓库。这是安全底线。3.2 构建高效的Server ActionServer Action是Next.js App Router的明星特性。下面是一个简化的核心Action示例// app/actions/generate-diagram.ts use server; // 必须标记声明这是服务器动作 import { openai } from /lib/openai; import { z } from zod; // 推荐用于输入验证 // 1. 定义输入验证模式 const inputSchema z.object({ prompt: z.string().min(5, 描述太短了请多说点细节。), diagramType: z.enum([flowchart, sequence, class, user-journey, gantt, c4]), }); // 2. 导出服务器动作函数 export async function generateDiagram(prevState: any, formData: FormData) { // 3. 从formData中提取并验证数据 const rawData { prompt: formData.get(prompt) as string, diagramType: formData.get(diagramType) as string, }; const validatedData inputSchema.safeParse(rawData); if (!validatedData.success) { // 返回错误信息给前端表单 return { error: validatedData.error.errors[0]?.message || 输入数据无效, code: null, }; } const { prompt, diagramType } validatedData.data; // 4. 构建系统Prompt这是关键 const systemPrompt 你是一个专业的图表生成助手。请根据用户的描述生成对应的Mermaid.js代码。 图表类型${diagramType} 请严格遵守以下规则 1. 只输出纯粹的Mermaid代码不要有任何额外的解释、Markdown代码块标记或前言后语。 2. 代码必须符合Mermaid ${diagramType}图表的语法规范。 3. 根据用户描述合理推断实体、关系和流程使图表清晰准确。 用户描述${prompt}; try { // 5. 调用OpenAI API const completion await openai.chat.completions.create({ model: gpt-3.5-turbo, messages: [ { role: system, content: systemPrompt }, { role: user, content: 生成一个${diagramType}图。 }, ], temperature: 0.1, // 温度设低让输出更确定、更结构化 max_tokens: 1000, }); const mermaidCode completion.choices[0]?.message?.content?.trim() || ; // 6. 简单清理移除可能出现的 mermaid 代码块标记 const cleanedCode mermaidCode.replace(/^mermaid\s*|\s*$/g, ); // 7. 返回结果 return { error: null, code: cleanedCode }; } catch (error) { console.error(OpenAI API调用失败:, error); return { error: 生成图表时出错请稍后重试。, code: null }; } }关键点解析use server这个指令告诉Next.js这个模块里的函数只在服务端运行。输入验证使用zod库对前端传入的数据进行验证防止无效或恶意数据。这是生产级应用的必要步骤。系统Prompt设计这是AI能否正确工作的核心。我的Prompt明确要求AI“只输出纯粹的Mermaid代码”并指定了图表类型和规则。temperature参数设置为较低的0.1是为了减少AI的随机性让生成的代码更稳定。错误处理用try...catch包裹API调用并将错误信息友好地返回给前端。3.3 前端表单与状态管理前端需要创建一个表单来调用这个Server Action。Next.js 14的useActionState钩子原useFormState非常适合处理表单提交和状态。// app/components/diagram-form.tsx use client; // 这是一个客户端组件因为要用到状态和事件 import { useActionState, useEffect } from react; import { generateDiagram } from /app/actions/generate-diagram; import { MermaidDiagram } from ./mermaid-diagram; // 一个封装了Mermaid渲染的组件 const diagramTypes [ { value: flowchart, label: 流程图 }, { value: sequence, label: 时序图 }, { value: class, label: 类图 }, // ... 其他类型 ]; export function DiagramForm() { // 使用useActionState绑定Server Action和状态 const [state, formAction, isPending] useActionState(generateDiagram, { error: null, code: null, }); // 当生成成功且代码变化时可以触发一些副作用比如滚动到图表位置 useEffect(() { if (state.code) { // 例如图表生成成功后的反馈 console.log(图表已生成); } }, [state.code]); return ( div classNamespace-y-6 form action{formAction} classNamespace-y-4 div label htmlFordiagramType classNameblock text-sm font-medium mb-2 图表类型 /label select iddiagramType namediagramType defaultValueflowchart classNamew-full p-2 border rounded-md required {diagramTypes.map((type) ( option key{type.value} value{type.value} {type.label} /option ))} /select /div div label htmlForprompt classNameblock text-sm font-medium mb-2 用自然语言描述你的图表 /label textarea idprompt nameprompt rows{4} placeholder例如开始然后用户登录验证成功后进入主页失败则显示错误信息。 classNamew-full p-2 border rounded-md required / /div button typesubmit disabled{isPending} classNamepx-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 disabled:opacity-50 disabled:cursor-not-allowed {isPending ? 生成中... : 生成图表} /button /form {/* 显示错误信息 */} {state.error !isPending ( div classNamep-3 bg-red-50 text-red-700 rounded-md border border-red-200 p classNamefont-medium出错了/p p{state.error}/p /div )} {/* 渲染生成的图表 */} {state.code !isPending ( div classNamemt-8 h3 classNametext-lg font-semibold mb-4生成的图表/h3 MermaidDiagram code{state.code} / {/* 可选显示生成的Mermaid代码 */} details classNamemt-4 border rounded-md summary classNamep-3 cursor-pointer font-medium查看Mermaid代码/summary pre classNamep-3 bg-gray-50 text-sm overflow-auto code{state.code}/code /pre /details /div )} /div ); }关键点解析useActionState它接收我们的Server Action (generateDiagram) 和一个初始状态。它返回一个formAction可以直接绑定到form action上。当表单提交时它会调用Server Action并自动管理返回的state和提交状态isPending。这比手动用useState和fetch管理要简洁得多。isPending这个布尔值在Action执行期间为true我们可以用它来禁用提交按钮、显示加载指示器提升用户体验。状态驱动UI根据state中的error和code来条件渲染错误信息或图表组件逻辑清晰。3.4 Mermaid图表渲染组件最后我们需要一个组件来将Mermaid代码字符串渲染成可视化的图表。这里我使用了mermaid-js/react-mermaid这个社区库它封装了Mermaid的初始化、渲染和更新逻辑。// app/components/mermaid-diagram.tsx use client; import { useEffect, useRef, useState } from react; import mermaid from mermaid; // 初始化Mermaid配置可选但推荐 mermaid.initialize({ startOnLoad: false, // 我们不希望自动渲染 theme: default, // 或 dark, forest, neutral flowchart: { curve: basis }, // 流程图曲线样式 sequence: { showSequenceNumbers: true }, // 时序图显示序号 securityLevel: loose, // 对于沙盒安全限制loose更宽松 }); interface MermaidDiagramProps { code: string; } export function MermaidDiagram({ code }: MermaidDiagramProps) { const containerRef useRefHTMLDivElement(null); const [svg, setSvg] useStatestring(); const [error, setError] useStatestring | null(null); useEffect(() { // 每次code变化时重新渲染 if (!code || !containerRef.current) return; const renderDiagram async () { setError(null); try { // mermaid.render 是异步的 const { svg } await mermaid.render( mermaid-${Date.now()}, // 生成一个唯一ID code ); setSvg(svg); } catch (err) { console.error(Mermaid渲染失败:, err); setError(图表渲染失败请检查生成的Mermaid代码语法。); setSvg(); // 清空之前的SVG } }; renderDiagram(); }, [code]); // 依赖项code if (error) { return ( div classNamep-4 border border-red-300 bg-red-50 rounded-md text-red-700 p classNamefont-medium图表渲染错误/p p classNametext-sm mt-1{error}/p /div ); } // 使用dangerouslySetInnerHTML来插入SVG这是标准做法 return ( div classNameborder rounded-lg p-4 bg-white overflow-auto div ref{containerRef} classNamemermaid-container dangerouslySetInnerHTML{{ __html: svg }} / {!svg code ( div classNametext-center py-8 text-gray-500正在渲染图表.../div )} /div ); }重要提示dangerouslySetInnerHTML是React中插入HTML字符串的方法因为Mermaid输出的是SVG代码。使用它时必须确保代码来源可信。在我们的场景中代码来自我们自己的Server Action和OpenAI经过清理相对安全但仍需注意。4. 高级优化与踩坑实录基础功能跑通后接下来就是打磨体验和解决实际问题。这部分是我在实际开发中积累的“干货”。4.1 Prompt工程的迭代与优化最初的Prompt很简单“请生成一个关于[用户输入]的Mermaid流程图。”结果AI经常在代码前后加上解释性文字或者生成语法错误的代码。第一版优化明确指令你是一个Mermaid代码生成器。根据用户的描述生成对应的Mermaid流程图代码。 要求 1. 只输出代码不要任何解释。 2. 代码必须完整且可执行。 用户描述{userInput}好了一些但AI有时还是会用“mermaid”代码块包裹或者生成非流程图的代码。第二版优化最终版指定类型与严格约束这就是前面Server Action中使用的Prompt。关键改进是指定图表类型变量图表类型${diagramType}让AI目标明确。强调“纯粹”的代码“只输出纯粹的Mermaid代码不要有任何额外的解释、Markdown代码块标记或前言后语。”加入规则要求AI“严格遵守Mermaid语法规范”并“合理推断”。调整参数temperature0.1。这个参数控制输出的随机性。值越低接近0输出越确定、可预测值越高接近1或2输出越有创造性。对于生成严格遵循语法的代码低温度值更合适。实测心得即使这样AI仍有大约5%的概率输出格式不符或包含额外文本。因此在Server Action中我加了一行简单的正则表达式清理代码mermaidCode.replace(/^mermaid\s*|\s*$/g, )作为最后一道防线。4.2 实现流式输出以提升体验等待AI生成结果可能需要几秒钟让用户盯着空白页面等待体验不好。我们可以实现流式输出让Mermaid代码像打字一样逐渐显示出来最后再渲染图表。这需要用到Vercel AI SDK的streamText功能并对前端进行改造。1. 创建流式Server Action// app/actions/stream-diagram.ts use server; import { openai } from /lib/openai; import { streamText } from ai; // 从Vercel AI SDK导入 import { z } from zod; const inputSchema z.object({ prompt: z.string().min(5), diagramType: z.string(), }); export async function streamDiagram(input: z.infertypeof inputSchema) { const validatedData inputSchema.parse(input); const systemPrompt ...; // 同之前的Prompt // 使用streamText创建流 const result streamText({ model: openai.chat(gpt-3.5-turbo), messages: [ { role: system, content: systemPrompt }, { role: user, content: 生成一个${validatedData.diagramType}图${validatedData.prompt} }, ], temperature: 0.1, }); return result.toDataStreamResponse(); // 返回一个标准的Response流 }2. 前端使用useChat钩子处理流// app/components/streaming-diagram-form.tsx use client; import { useChat } from ai/react; // 从Vercel AI SDK/react导入 import { MermaidDiagram } from ./mermaid-diagram; export function StreamingDiagramForm() { const { messages, input, handleInputChange, handleSubmit, isLoading } useChat({ api: /api/chat, // 你需要创建一个API路由来代理调用上面的streamDiagram // 或者直接调用Server Action需要稍作适配 onFinish(message) { // 当流式传输完成时message.content就是完整的Mermaid代码 console.log(生成完成:, message.content); }, }); const lastMessage messages[messages.length - 1]; const generatedCode lastMessage?.role assistant ? lastMessage.content : ; return ( div form onSubmit{handleSubmit} {/* 输入框和选择器绑定到input和handleInputChange */} input nameprompt value{input} onChange{handleInputChange} placeholder描述你的图表... / button typesubmit disabled{isLoading} 生成 /button /form {/* 实时显示正在生成的代码 */} {isLoading !generatedCode divAI正在思考.../div} {generatedCode ( pre classNamebg-gray-100 p-2 text-sm overflow-auto {generatedCode} /pre MermaidDiagram code{generatedCode} / / )} /div ); }注意为了使用useChat你需要设置一个API路由如app/api/chat/route.ts来作为中间层或者使用实验性的useActionsNext.js 15来直接调用流式Server Action。这里涉及更多配置但流式体验对用户感知的提升是显著的。4.3 常见问题与排查技巧在开发和测试过程中我遇到了不少坑这里总结一下1. 图表渲染空白或报错症状Mermaid组件不显示或控制台报语法错误。排查首先检查生成的代码在UI上显示原始的Mermaid代码就像我们前面做的details部分把它复制到 Mermaid Live Editor 中验证。很多时候是AI生成的语法有细微错误比如缺少分号、节点ID包含非法字符。检查Mermaid配置确保mermaid.initialize中的securityLevel设置正确。如果图表中使用了%%{init}%%指令或某些高级功能可能需要设置为loose。查看网络请求确保Server Action调用成功并且返回了有效的code字符串。2. AI不按指令输出总是加额外文字解决强化你的系统Prompt。在Prompt的开头就用非常强硬、清晰的语气例如“你必须且只能输出Mermaid代码绝对不要有任何其他文字。你的输出将直接用于程序渲染任何额外字符都会导致错误。”同时确保temperature参数设置得足够低0.1或0.2。3. 生成的图表逻辑与描述不符解决这属于Prompt工程问题。在用户描述不够清晰时AI会自由发挥。可以尝试引导用户在输入框 placeholder 或标签中给出更具体的例子比如“描述一个登录流程包括开始、输入用户名密码、验证、成功/失败分支、结束”。优化Prompt在系统Prompt中给AI一个更具体的角色例如“你是一个严谨的软件架构师必须准确地将业务描述转化为技术图表”。4. 部署后OpenAI API调用失败症状本地开发正常部署到Vercel等平台后报错。排查环境变量确保在部署平台如Vercel的项目Settings - Environment Variables中正确设置了OPENAI_API_KEY。网络限制某些部署平台在免费计划中对出站请求有地域或频率限制。检查部署平台的日志。超时设置Server Action和OpenAI API调用可能有超时限制。Vercel的Serverless Function默认超时时间较短10秒。对于复杂图表如果AI响应慢可能需要优化Prompt或考虑使用边缘函数。5. 性能与成本优化缓存对于相同的用户输入和图表类型结果理论上是一样的。可以考虑在服务端对(prompt, diagramType)进行哈希将生成的Mermaid代码缓存一段时间例如用Redis或Vercel KV避免重复调用OpenAI API节省成本。模型选择对于大多数图表gpt-3.5-turbo足够且便宜。只有当你需要生成非常复杂、逻辑严密的架构图如C4图时才考虑使用gpt-4。Token限制在openai.chat.completions.create中设置合理的max_tokens。Mermaid代码通常不会太长500-1000个token足够了。设置上限可以防止意外产生过长的输出控制成本。5. 项目总结与扩展思考构建Diagram GPT的过程是一个将前沿AI能力与成熟Web技术栈巧妙结合的典型例子。它验证了一个想法通过自然语言这一最直观的接口来降低专业工具的使用门槛。技术上的关键收获Server Action是真香它极大地简化了全栈应用的数据流让从前端表单到服务端逻辑的调用变得像写一个普通异步函数一样简单。它代表了Next.js全栈开发的新范式。Prompt工程是“炼金术”与AI协作Prompt的质量直接决定输出结果的质量。它需要反复调试、明确约束、并用低temperature来稳定输出。这更像是在编写一种给机器看的“说明书”。Mermaid生态成熟作为文本转图表的中间表示Mermaid非常可靠。它的在线编辑器也是调试AI生成代码的绝佳工具。关于扩展性的思考这个项目目前是一个最小可行产品MVP还有很大的想象空间多模型支持除了OpenAI可以接入Claude、DeepSeek等模型让用户选择或作为备选。图表编辑与迭代生成图表后允许用户直接在生成的Mermaid代码基础上进行编辑或者通过自然语言指令进行修改如“把这里的箭头改成红色”实现交互式图表创作。历史记录与分享将生成的图表和代码保存到数据库支持用户查看历史、生成分享链接。自定义主题与样式集成Mermaid的主题系统让用户可以切换图表样式或自定义颜色、字体。更多图表类型持续跟进Mermaid.js支持的新图表类型如思维导图、象限图等。最后从产品角度看这类工具的核心价值在于降低表达成本。它不是为了替代专业的绘图工具如Draw.io、Lucidchart而是在构思、沟通、快速草绘的场景下提供一个“想到即得到”的闪电式工具。对于开发者写设计文档对于产品经理画原型流程对于教师制作教学材料它都能显著提升效率。如果你也想动手做一个我的建议是不要追求大而全先抓住一个核心痛点比如“自然语言生成流程图”用最小的技术闭环把它跑通。就像这个项目一样一个表单、一个Server Action、一个AI调用、一个渲染组件就构成了全部核心。在此基础上再去迭代优化体验、增加功能。