我自己大概花了将近两天的时间，终于让手头的教学智能体（Agent）学会了画函数图。这中间踩了不少坑，也把方案推翻重来了两次，最后才跑通一条稳定、能用在真实课堂上的链路。今天就把整个折腾过程、方案取舍和最终实现细节写出来，给同样在做教育类智能体的朋友做个参考。
先说清楚背景。我的教学智能体跑在主流Agent框架上，核心场景就是回答初中、高中数学题，比如学生问“画一下y=sin(x)在[-π,π]区间的图像”“二次函数y=x²-2x+1的顶点在哪里”。这些问题如果只是用文字回答，学生能听懂，但缺乏直观感受。函数图像在数学教学里是刚需，尤其在讲解单调性、对称轴、周期性和图像变换的时候，一张图胜过千言万语。
但问题恰恰出在这里：大语言模型本身只擅长生成文本，它并不具备“凭空画图”的能力。LLM能够吐出LaTeX公式、能够描述图像特征，但真要让一个函数表达式变成一张可交互、可缩放、可观察的图，必须在大模型之外接一个图形渲染引擎。而在这个“智能体该如何调用外部引擎、又该如何把自然语言转化成引擎能懂的指令”的中间地带，就是这个项目最大的折腾点。
这篇博文适合正在做教育智能体、AI助教、数学学习工具的开发者，也有肉眼可见的性价比——读完以后，你不仅知道怎么让智能体画函数图，还知道在设计工具调用、参数校验、多轮状态管理时怎么避免我踩过的那些坑。
1. 需求拆解：为什么“画个函数图”会卡住一整条链路
1.1 表面需求 vs 真实需求
第一反应很简单：让大模型调一个绘图函数不就行了吗？但真实课堂场景对“画函数图”的要求远比“生成一张静态PNG”复杂得多。我把它拆成了四个层级，这也是为什么折腾了两天的根本原因。
第一层是符号化理解。学生说的是“画一个顶点在(1,-2)的抛物线”，但渲染引擎不会懂“顶点”这个拓扑概念，它只会执行形如y = a*(x - h)^2 + k这样的数学表达式。所以智能体首先要做的是：在自然语言里提取参数，把它变成一个标准数学表达式，并确定这是真的二次函数。
第二层是渲染能力。选定渲染引擎之后，需要把数学表达式翻译成引擎的语法。这里会碰到大量细节陷阱：sqrt(x)还是\sqrt{x}？log是自然对数还是常用对数？x^2在部分引擎里要写成x**2？这些都直接影响绘图成功率和图像正确性。
第三层是交互与动态。静态图片对课堂教学的帮助有限，真正有价值的是“拖动参数滑块看图像变化”“放大看交点”这种交互方式。这意味着不能只调一次引擎画一张图就结束，还要考虑参数化、多视图和视图实时更新。
第四层是对话集成与状态记忆。教学智能体是持续对话的，往往学生在看完y=x²的图像后会追问“把它向左平移2个单位再看一下”。智能体必须记住上一轮的表达式是y=x²，才能正确处理“平移”这个动作，而不是把“向左平移2个单位”当成一个无法理解的新问题。
1.2 两条技术路线的取舍：平台搭建 vs 代码自建
做智能体有两种主流方式：一种是在Coze、Dify这类平台里编排工作流，另一种是用Python代码自建Agent逻辑。平台方式上手快，内置了意图识别、记忆、工具调用等模块；代码自建更灵活，便于接入任意渲染引擎和校验逻辑。
我的选择是“混合模式”：外层对话管理用平台工作流，核心渲染链路用Python函数服务。具体来说，智能体内部的plot_function工具指向一个FastAPI微服务，这个服务接收表达式和坐标范围，返回渲染好的缩略图URL。平台负责判断什么时候调用、调用哪个参数，Python服务负责真正把图画出来。这样既保住了平台维护的便利性，又绕开了平台内置绘图组件不够灵活的瓶颈。
提示：如果你的场景只需要生成简单的静态数学图，直接用平台自带插件就够了。但如果是教学互动场景，我强烈建议把“画图能力”从“插件”上升为“独立服务”，后续扩展交互功能时你就知道这个决定有多重要了。
2. 表达式解析与校验：让LLM输出真正“可执”的数学指令
2.1 为什么不能让LLM直接输出LaTeX
第一次尝试时，我的Prompt里写的是“请输出LaTeX公式，然后调用工具绘图”。结果发现：GeoGebra对LaTeX的支持并不完整，Desmos甚至直接要求类Desmos语法（x^2、sin(x)），LaTeX里的\frac{}{}、\sqrt{}根本传不进去。更麻烦的是，LLM偶尔会在LaTeX里插入\left(、\right)这种排版命令，渲染引擎完全不认。
所以第二次设计就改成：不要LLM输出LaTeX，改为LLM输出结构化的函数表达式。我在工具的JSON Schema里直接定义了一个expression字段，并明确要求：
{ "name": "plot_function", "description": "绘制一元函数图像。expression必须使用标准数学函数语法：幂运算用^，乘法用*，函数必须写括号，例如sqrt(x)、sin(x)、abs(x)。", "parameters": { "type": "object", "properties": { "expression": { "type": "string", "description": "函数表达式，自变量必须为x。例如 x^2 + 2*x + 1" }, "xmin": { "type": "number", "description": "x轴显示最小值" }, "xmax": { "type": "number", "description": "x轴显示最大值" }, "ymin": { "type": "number", "description": "y轴显示最小值" }, "ymax": { "type": "number", "description": "y轴显示最大值" } }, "required": ["expression"] } }这个设计的核心意图是：将“数学自然语言”与“引擎语法”解耦。LLM只负责将自然语言转写为人工定义的中间表达式，后续由Python解析器完成安全性校验和语法转换。这样即便换成另一个渲染引擎，智能体核心逻辑也可以原封不动。
2.2 用SymPy做语法白名单校验
LLM生成表达式有两大风险：一是语法非法，二是恶意/无关内容（比如让学生输入“删除文件”这种指令时，大模型可能拼出一个奇怪的函数）。所以表达式不能直接拿去渲染，必须经过解析器校验。
我用SymPy的sympify函数做表达式合法性检查，但同时设置了一个非常严格的白名单：
import sympy as sp ALLOWED_FUNCTIONS = { 'sin', 'cos', 'tan', 'asin', 'acos', 'atan', 'exp', 'log', 'sqrt', 'abs', 'sinh', 'cosh', 'tanh', 'floor', 'ceiling' } def validate_expression(expr_str: str): try: expr = sp.sympify(expr_str) except Exception as e: return False, f"表达式无法解析：{e}" for atom in expr.atoms(sp.Function): if atom.func.__name__ not in ALLOWED_FUNCTIONS: return False, f"包含不允许的函数：{atom.func.__name__}" # 强制只使用x作为自由变量 free_syms = expr.free_symbols if free_syms and not {str(s) for s in free_syms}.issubset({'x', 'p', 'a', 'b', 'c', 'k', 'h', 'n'}): return False, "表达式中出现了自变量x之外的未知符号" return True, expr这里有一个细节：我并没有把所有未知符号都禁止，而是允许了p、a、b、c、k、h、n这几个常见参数符号。原因是教学中经常出现“带参数的函数”，比如学生说“画一下y = a*x^2当a=2时”这类场景。如果直接禁止全部非x符号，这个功能就废了。白名单参数由大模型在后续对话中以“参数赋值”形式补充，渲染服务再统一替换。
2.3 兜底Prompt：当解析失败时怎么办
校验失败最忌静默修复，也不能直接抛错给用户。我设计了一套“确认式纠错”流程：当SymPy校验失败时，智能体不回错误，而是把学生输入的原文转成一个可读的表达式，再反问一遍。
比如学生输入“画个二次函数，顶点在(1, -2)，开口向上”，智能体会自动生成y = (x - 1)^2 - 2，然后附上提示：“我将为你绘制 y = (x - 1)^2 - 2 的图像，请确认是否正确。”这一步让课堂上的容错率大幅提升，学生输入自然语言时经常缺这少那，这个确认机制能挡住80%的常见错误。
3. 渲染层选型与实现：从静态图到可交互图形
3.1 四类渲染引擎的对比
在选型时，我认真比较了matplotlib、Desmos、GeoGebra和Plotly，最终被现实狠狠教育了一顿：没有完美的引擎，只有适合自己的组合。这里用表格把利弊铺开：
| 引擎 | 优势 | 劣势 | 适合场景 |
|---|---|---|---|
| matplotlib | 环境熟悉、生成的图片可自由嵌入聊天记录 | 无交互、刷新动画体验差、中文支持需单独配置 | 快速生成缩略图、聊天流内静态预览 |
| Desmos Graph API | 交互极佳、学生接受度高、解析表达式的容错强 | 嵌入需要iframe、对非前端技术栈不友好 | 真正的课堂演示、参数滑块调节 |
| GeoGebra | 几何作图一流、支持3D、有丰富的教学组件 | API学习成本高、请求/集成复杂度高 | 几何与函数综合型教学内容 |
| Plotly | 支持Python直接输出交互图、代码量小 | 输出体积大、移动端Webview里略卡 | 数据分析类的可视化 |
我的最终方案是：主聊天流内用matplotlib生成缩略PNG，学生点击图片后跳转到Desmos线上交互视图。为什么这样做？一是聊天界面里放高大上的可交互JS组件渲染成本高，且移动端兼容性不稳定；二是matplotlib PNG体积小、输出稳定，教学智能体的对话响应速度更重要；三是Desmos的在线版是现成的、免登录可用，而且学生本来就熟悉它的操作方式。
3.2 Python侧渲染服务：matplotlib出图细节
作为后端渲染服务，关键是控制产物质量。下面是经过实际打磨的绘图函数，几个细节都踩了坑：
import matplotlib matplotlib.use('Agg') import matplotlib.pyplot as plt import numpy as np def render_plot(expr_str, xmin=-10, xmax=10, ymin=-10, ymax=10, title=""): # 1. 解析并符号化表达式 x = sp.symbols('x') expr = sp.sympify(expr_str) f = sp.lambdify(x, expr, modules=['numpy', 'math']) # 2. 生成采样点，避开无定义区域 xs = np.linspace(xmin, xmax, 800) ys = [] for xi in xs: try: yval = float(f(xi)) # 过滤掉inf和nan，避免图像出现断线 if np.isfinite(yval): ys.append(yval) else: ys.append(np.nan) except Exception: ys.append(np.nan) ys = np.array(ys) # 3. 绘图 plt.figure(figsize=(6, 4.5)) plt.plot(xs, ys, 'b-', linewidth=2, label=f'y = {expr_str}') plt.axhline(0, color='black', linewidth=0.8) plt.axvline(0, color='black', linewidth=0.8) plt.grid(True, linestyle='--', alpha=0.6) plt.xlim(xmin, xmax) plt.ylim(ymin, ymax) # 4. 支持中文标题 plt.rcParams['font.sans-serif'] = ['SimHei', 'WenQuanYi Zen Hei', 'PingFang SC'] plt.rcParams['axes.unicode_minus'] = False plt.title(title if title else f"y = {expr_str}") img_path = "/tmp/plot_cache/plot.png" plt.savefig(img_path, dpi=150, bbox_inches='tight') plt.close() return img_path这里采样点数为什么是800？这是平衡了几何精度和响应时延的结果。400个点在极值附近会有明显的锯齿，1200个点在高并发时CPU开销过大，800点是交互响应内的甜点值。另外对np.nan的过滤非常关键，否则y=1/x这类函数画出来会有一条竖直的假线，直接误导学生理解渐近线概念。
3.3 预生成缓存：让同图不再重复渲染
教学智能体的对话有一个特点：同一张图会被反复问到。比如一个班里20个学生，可能前后有15个人问“画一下y=x²的图像”。如果每次都重新渲染，既浪费算力又拖慢响应。
所以我在渲染服务里加了一层简单的文件缓存：以md5(expression|xmin|xmax|ymin|ymax)为key，如果缓存文件存在就直接返回URL，否则才真正绘图。实测下来命中率能到40%左右，尤其在高频函数（二次函数、绝对值函数、指数函数）上效果很明显。缓存TTL设成24小时，这样即使表达式一样、但班里学生多了新需求，也不会导致缓存污染。
注意：缓存key里必须包含坐标范围。原因很简单，学生A问“画 [-10,10] 区间的二次函数”，学生B问“放大到 [0,5] 区间看顶点”，这两张图内容完全不同。如果只对表达式做缓存，B拿到A的图就全错了。
4. 智能体工作流集成：从工具到会话状态的完整闭环
4.1 意图识别与工具调用的大门
画图工具不能“有求必应”，得让智能体知道“什么时候该调、什么时候不该调”。我做的第一步是给工具加上了非常强的意图触发说明，在系统提示词中写明：
- 当学生明确要求“画图、看一下、图像、草图、可视化”等关键词，必须调用
plot_function。 - 当学生只是在问性质（如奇偶性、单调性），不强制触发绘图工具，但如果在文字解答中附上图像会显著提升解释效果，可以调用。
- 当学生询问“怎么用手画图”这类解题过程时，不调用工具，转而输出分步解题描述。
这个设计看似简单，实际操作中却是最容易翻车的一环。LLM的通病是：明明在回答“求这个函数的零点”，却自己在文本里补充“需要我帮你画图吗”，而完全不调用工具。为此我在Prompt里专门加了一个few-shot示例：
用户：求 x^2 - 4 = 0 的根 助手：[调用 plot_function expression="x^2 - 4" xmin=-6 xmax=6 ymin=-6 ymax=6] 回答：图像与x轴的交点在 x=-2 和 x=2 处，所以方程的根是-2和2。这个示例给LLM的信号是：画图不是为了展示工具存在感，而是为了辅助数学推理。让LLM意识到“画图是整个解题链条的一部分”，它才会在合适的时机果断调用工具。
4.2 多轮状态记忆：关于“再一次”的处理
教学场景里，学生最常说的是：“刚才那个图画成[-5,5]区间”“把它左移一下”“能不能再加一条线？”这类句子单独拆出来都缺主语，需要结合会话历史才能正确渲染。我用平台会话状态加一个轻量级记忆槽位来解决：
memory = { "last_expr": "x^2 - 4", "last_xmin": -6, "last_xmax": 6, "pending_confirm": false }如果当前工具调用中的expression字段为空，而历史槽位里有last_expr，工作流会自动带上历史表达式，同时把“左移、右移、上移、下移、放大、缩小”等操作词映射为参数偏移。
平移操作的实现细节是这样：LLM在抽取意图时，直接把“左移两个单位”转成新的表达式(x+2)^2 - 4，还是直接调用工具传入参数expr=(x+2)^2 - 4？我选择后者。理由很简单：在表达式层面完成平移，渲染引擎不用做任何额外处理，而且图像表达式和学生的初始认知一致——学生会看到“y=(x+2)^2-4”这个新表达式，正好能理解“左加右减”的口诀。
4.3 回退与人工确认：稳定性优先
自动纠错并非永远可靠，所以我设了三级回退：
第一级是解析失败，智能体反问“你输入的是...吗”，并等待确认。第二级是表达式合法但超出显示范围（比如y=x^100默认范围下根本画不出可见形状），系统自动调整坐标范围，并提示学生“该函数在默认区间变化过于剧烈，已为你调整到 [-1.2, 1.2]”。第三级是渲染服务本身超时或返回500，智能体降级为文字描述图像形态，比如“该函数是开口向上的抛物线，对称轴为x=1，顶点在(1,-2)”。
这套降级策略在最开始并没有设计，是被一次线上故障逼出来的。当时某个学校的网络访问Desmos超时，导致整个Answer流卡了十几秒。现在渲染服务挂了也能用文字兜底，课堂崩溃率下降了一个量级。
5. 实测踩坑与排查技巧：两天里最值得记录的教训
5.1 常见高频Bug与解决方案
把两天的调试过程做一个真实回放：
| 现象 | 根因 | 解决方案 |
|---|---|---|
| 图像是一条“假竖线” | y=1/x在x=0处f(x)=inf，matplotlib直接把两端连起来 | 在采样循环里过滤inf和nan，替换为np.nan |
学生输入“x平方加二x加一”，LLM生成x2+2x+1 | 数学口语转符号时，平方未加^ | 在Prompt里给出20个常见口语→公式映射示例，覆盖“平方、分之、开根号”等 |
Desmos的log(x)输出自然对数，但国内教材默认常用对数 | 日志底数约定不一致 | 在工具描述里显式写明：log(x)默认表示常用对数 lg(x)，自然对数用ln(x)。SymPy校验时自动把log重写为log_10优先级高 |
| 智能体强行调用画图工具，但对图只字不提 | LLM把工具调用当成了“任务终点” | 增加输出约束：每次调用绘图工具后，必须至少用一句话描述图像特征（顶点、零点、单调性） |
表达式带中文括号（x+1）导致解析失败 | 用户输入法状态未切换 | 在Service入口统一做全角转半角，把（）、，替换为()、, |
| 多轮对话中第二次请求丢失上一轮表达式 | 平台会话变量未持久化到Memory | 在会话变量中单独存一个字段active_plot，每次绘图结束后同步更新 |
5.2 日志链路的全链路监控
我踩过最疼的一个坑是：表现上智能体疯狂报错，但所有环节看日志都正常。后来发现是缓存层命中了旧图文件，而那个旧图文件里包含了上一次绘图残留的中文标题。排查了半小时才发现原因是plt.title用了全局字体缓存，第二次绘图时标题变了，但savefig的路径因为某种竞态没有被清掉。
从那以后，我在渲染服务里加了一个结构化日志中间件，每一条请求都会记录：input_text -> intent -> extracted_expr -> validation_result -> render_status -> cache_key -> image_path。这个链路日志的价值极大，任何一次线上问题都能在两分钟内定位到目的环节，而不是靠猜。
如果你也在做类似的服务，建议不只是在入口打印日志，而是把全链路追踪ID串联起来。我用的办法是给每次会话生成一个trace_id，从智能体工作流的工具调用参数一路传到Python服务，再随响应回传给前端。这样即使排障时跨了多个系统，也能靠一个ID拉通所有日志。
5.3 性能调优：别让绘图拖垮对话
渲染服务的响应时间直接影响了教学对话的流畅度。我把耗时瓶颈分析了一下，发现大头在SymPy符号解析和lambdify处理复杂表达式上。优化点有三个：
第一是用functools.lru_cache缓存lambdify后的函数对象，避免同一表达式反复编译。第二是采样点数从1200降到800，并保持图像质量不下降，因为对线型图来说800点已经足够平滑。第三是绘图服务用FastAPI挂异步线程池，避免matplotlib的GIL阻塞影响整个服务进程。
优化以后，单次绘图耗时从平均1.2秒降到0.4秒，缓存命中时甚至能到几十毫秒。对于智能体对话场景，这个延迟完全无感知，学生体验接近即时反馈。
6. 从“画函数图”到“教学智能体工具箱”的扩展思路
画函数图只是第一步，顺手把这条路走通之后，我突然发现这个架构可以复用到更多教学场景中。
比如几何可视化：把LLM生成的几何描述（“画一个直角三角形，直角边分别为3和4”）解析成SVG或Desmos可执行指令，就能在智能体里直接输出平面几何图。再比如统计图：学生在问“一组数据的平均数、中位数”时，智能体可以顺手把频数直方图、箱线图画出来。还可以做导数与积分可视化：让智能体先从y=x^2推导出导函数y'=2x，然后在同一坐标轴里画出原函数和导函数，叠加展示“导数代表切线斜率”这个核心概念。
这些场景的共同点是：大模型负责“理解与推导”，外部渲染引擎负责“呈现与验证”。这个职责分界非常重要，我在第一版的时候尝试让LLM直接输出绘图指令，结果一塌糊涂——它写的“画两条线”完全不符合引擎语法。反过来，如果让引擎理解自然语言，那几乎不可能。所以正确的架构一定是“LLM做语义理解，引擎做精确执行”，中间靠一个结构化的工具协议衔接。
如果你也打算做一个自己的教学智能体，我的核心建议是：
- 别让LLM直接输出引擎语法，一定要先定义中间表达层。
- 绘图工具的输入参数要极简化，越少越不容易出错。
- 给表达式加一层SymPy白名单校验，比任何“防御性Prompt”都管用。
- 给渲染服务做缓存和降级方案，不然课堂直播时脸会被打肿。
- 用全链路日志和trace_id串联整个对话进程，不要相信“看起来一切正常”。
折腾这两天，最大的收获不是学会了更高级的matplotlib技巧，而是真正理解了一个道理：智能体的价值不在于单个大模型有多强，而在于怎么把大模型和外部工具结合成一个可靠的系统。画函数图只是这个协作模式的冰山一角，沿着这条路继续走下去，智能体完全可以成为一个真正能看懂、能画图、能推导的“AI数学老师”。
