1. 项目概述一个AI驱动的考试分析工具最近在折腾一个挺有意思的副业项目叫 ErrorVault。这玩意儿本质上是一个专为备考学生设计的AI考试分析模块是我正在做的Rota平台的一部分。核心想法很简单学生做完模拟考把错题和空题的卷子拍个照上传系统就能用AI帮你把错题分析得明明白白——错在哪个知识点、属于什么题型、为什么错甚至还能给你生成一份详细的个人能力报告和提分建议。这比单纯对个答案、算个总分要有用太多了。我自己当年备考的时候最头疼的就是错题整理。本子记了一堆但很难看出规律哪些是粗心哪些是概念不清哪些是题型不熟全靠自己琢磨效率很低。ErrorVault想解决的就是这个问题它用AI把这种模糊的“感觉”给量化、结构化了。目前它主要针对的是土耳其的大学入学考试体系比如TYT和AYT但背后的逻辑其实可以套用到很多标准化考试的准备上像考研、考公、语言等级考试等等只要是有固定科目和题型模式的这个分析框架都能派上用场。2. 核心设计思路与技术选型2.1 为什么选择“AI分析错题”这个切入点传统的在线刷题或考试系统核心功能往往是“出题-答题-判分”。判分之后顶多给个“正确答案是C你选错了”的反馈至于为什么错、反映了你哪方面能力的缺失系统是不知道的。学生需要自己花大量时间去归因这个过程既耗时又主观。ErrorVault的设计思路是反过来的我们假设学生已经完成了考试无论是纸质的还是电子的并且知道了哪些题做错了或没做。系统的任务不是出题或判分而是对已知的“错误结果”进行深度归因分析。这就像你去看病医生不仅要告诉你发烧了判分更要通过化验AI分析告诉你是因为细菌感染还是病毒感染错误类型以及你的免疫系统哪方面比较弱知识薄弱点。这个思路决定了整个系统的架构必须是“数据驱动”和“分析导向”的。前端负责高效地收集原始数据分数、图片后端则要有一个强大的“分析引擎”来消化这些数据产出洞见。2.2 技术栈选型的背后逻辑在技术选型上我遵循了几个原则开发效率要高、生态要成熟、要能很好地支持AI集成并且成本可控。前端Next.js 14 TypeScript Tailwind CSSNext.js 14这是当前React生态里做全栈应用最顺手的框架没有之一。它的App Router模式让服务端组件、API路由、文件式路由的组织变得非常清晰。对于ErrorVault这种交互复杂、又有大量服务端逻辑图片处理、AI调用的应用来说Next.js的“全栈”能力可以让我在一个项目里搞定前后端减少了上下文切换。它的服务端渲染SSR和静态生成SSG能力也对首屏加载速度和SEO有天然好处。TypeScript项目里涉及的数据结构很多比如用户信息、考试数据、AI返回的分析结果JSON。TypeScript的强类型检查能在开发阶段就避免很多低级错误尤其是当AI API返回的数据结构可能变化时有类型定义和接口Interface约束心里踏实很多。Tailwind CSS选择它纯粹是为了开发速度。写考试分析后台这种重数据展示、重表单的界面用传统的CSS或者CSS-in-JS方案需要不断在组件文件和样式文件之间切换。Tailwind的实用类Utility-First模式让我在写JSX的同时就能把样式搞定而且设计系统颜色、间距、字体的一致性很容易维护。配合shadcn/ui这种基于Tailwind的组件库能快速搭建出既美观又专业的界面。后端与数据库Next.js API Routes Supabase后端逻辑直接写在Next.js的app/api目录下充分利用了框架的便利性。每个分析功能对应一个API路由结构清晰。Supabase这是我选型中的关键一步。它不仅仅是一个托管PostgreSQL数据库更是一个开箱即用的BaaS后端即服务。对于ErrorVault来说我需要关系型数据库存储用户、考试、题目分析这些具有复杂关联的数据。文件存储安全地存放用户上传的错题图片。简单的用户管理虽然项目初期用User ID这种简易模式但Supabase Auth为未来升级到邮箱/密码或第三方登录留足了空间。实时性Supabase的Realtime功能可以让分析进度实时反馈到前端用户体验更好。低成本启动Supabase有非常慷慨的免费额度对于项目初期验证想法、用户量不大的阶段几乎零成本。用一个Supabase把数据库、存储、认证甚至边缘函数Edge Functions的需求都覆盖了极大地简化了后端运维的复杂度。AI核心Google Gemini API这是整个项目的“大脑”。我选择了Gemini 2.5 Pro这个模型。选型时也对比过GPT-4和Claude但综合考量了成本、上下文长度、对多模态图片文本输入的支持以及API的稳定性Gemini Pro是一个性价比很高的选择。关键点在于Prompt Engineering提示词工程。要让AI从一个错题图片中准确分析出科目、知识点、错误类型、题目难度基于布鲁姆分类法需要设计极其详细和结构化的提示词。这不仅仅是告诉AI“分析这张图”而是要给它一个清晰的“分析框架”和“输出格式”。例如提示词里会明确规定“请以JSON格式返回包含以下字段subject科目 main_topic主要知识点 sub_topic子知识点 bloom_level认知层次 1-6 error_type概念性/计算性/审题性/粗心 suggested_study_focus学习建议”。这种结构化的输出是后续所有数据统计、图表生成和报告构建的基础。注意AI分析的准确性是系统的生命线。在项目初期我花了大量时间“训练”这个提示词。方法就是收集一批典型的错题图片手动标注好期望的分析结果然后反复调整提示词对比AI输出和人工标注的差异直到准确率稳定在一个可接受的水平比如85%以上。这个过程无法省略是AI类应用从“玩具”到“工具”的关键一步。3. 核心功能模块的详细拆解与实现3.1 用户数据流与前端交互设计用户使用ErrorVault的完整旅程是这样的身份识别用户在首页输入一个唯一的User ID。这里没有用复杂的注册登录是为了最大限度降低使用门槛。系统会验证这个ID是否存在或允许自动创建然后进入主仪表盘。所有后续数据都会严格绑定到这个ID下实现数据隔离。考试数据录入用户创建一个新的考试记录选择考试类型TYT或AYT。在一个精心设计的表单中按科目土耳其语、数学、科学等输入“做对”、“做错”、“未做”的题目数量。这里的前端验证会确保各科目题目数之和与考试总题数一致避免数据错误。核心交互图片上传。我为每个科目都设计了一个拖拽上传区域。用户可以把错题和空题的页面拍照然后直接拖进来或者点击选择文件。上传组件会显示预览、上传进度并支持批量上传。图片会即时上传到Supabase Storage并返回一个安全的访问URL存入数据库待分析。触发AI分析当用户提交表单后前端会调用一个/api/analyze-exam的API并把考试ID和图片URL列表传过去。这里为了用户体验我采用了异步处理。API立即返回一个“分析已开始”的响应真正的分析任务在后台队列中执行。前端则通过轮询或Supabase的Realtime订阅来更新分析进度。3.2 AI分析引擎的深度实现这是技术核心。当后端API收到分析请求后任务拆分与队列一个考试可能有几十张错题图片。我设计了一个简单的任务队列可以用bull或p-queue库实现避免同时向Gemini API发起大量请求导致速率限制。系统会为每张图片创建一个分析任务。调用Gemini API对于每个任务后端会从Supabase Storage获取图片的公开或临时访问URL。构建一个高度结构化的Prompt提示词。这个Prompt包含几个部分角色设定“你是一名经验丰富的考试辅导老师擅长从错题中诊断学生的学习问题。”任务描述“请分析以下这张考试题目图片。用户做错了或没做这道题。”图片内容将图片URL嵌入提示词。分析框架指令“请严格按照以下维度和格式进行分析并输出JSON...”输出格式约束明确JSON的每个字段名、数据类型字符串、数字、可选值枚举如error_type只能是conceptual,calculation,reading,carelessness中的一个。将构建好的Prompt发送给Gemini 2.5 Pro的API。解析与存储收到AI返回的JSON后后端会进行数据清洗和验证确保没有缺失字段或异常值。然后将这条分析结果存入Supabase的question_analyses表并与对应的考试记录、用户ID关联起来。聚合分析当一次考试的所有题目都分析完毕后系统会触发一个“聚合分析”过程。它会扫描本次考试的所有题目分析结果计算各科目的错误率、空白率。各类错误类型概念性、计算性…的分布。题目难度布鲁姆层次的分布。高频出现的薄弱知识点TOP 5。 这些聚合结果会被存入exam_analyses表用于生成报告和图表。3.3 数据可视化与报告生成分析完成后的数据展示直接决定了洞见能否被用户有效吸收。仪表盘总览首页用几个大的数据卡片KPI展示核心指标最近一次考试的总分、净得分扣除了错误惩罚后的分数、与上次考试相比的进步/退步趋势。让用户一眼看到自己的整体状态。科目维度分析页使用雷达图展示用户在各大科目上的得分率直观呈现“长板”和“短板”。使用堆叠柱状图展示每个科目内部不同错误类型的数量分布。比如数学科目是概念不清的错题多还是计算失误多一目了然。题目列表与详情页以列表形式展示所有被分析的题目支持按科目、错误类型、难度筛选。点击任意题目可以展开查看AI的完整分析结果题目图片、识别的文本、所属知识点、错误归因以及最重要的——AI给出的个性化学习建议。例如“此题考查二次函数求最值。你的错误在于忽略了定义域限制。建议复习‘含参二次函数在区间上的最值问题’并完成3-5道类似练习题。”趋势分析页使用折线图展示用户历次考试的净得分趋势线。使用热力图或面积图展示不同时间段内各科目错误率的变化帮助用户看到长期努力的成效。AI报告生成除了图表系统还提供一个“生成详细报告”的按钮。点击后后端会收集本次考试的所有聚合数据和高亮问题再次调用Gemini API但这次是让它扮演“学习顾问”生成一段连贯、自然、富有鼓励性的文字报告总结优势、指出核心问题、给出下一阶段的复习计划建议。这份报告可以PDF格式导出。4. 开发、部署与运维实战经验4.1 本地开发环境搭建要点我个人的开发流重度依赖Bun和Cursor这两个工具。Bun作为Node.js的替代运行时它的启动速度和包安装速度极快。在package.json里把npm start换成bun run dev能明显感觉到热重载Hot Reload更跟手。对于Next.js这种项目依赖不少用Bun安装bun install体验非常流畅。Cursor作为一款AI辅助的IDE在写ErrorVault这种业务逻辑明确但代码量不小的项目时效率提升显著。尤其是在编写重复性的API路由结构、Tailwind样式类、以及处理Supabase客户端查询时用CmdKComposer模式描述需求它能很快生成可靠的代码片段我只需要做调整和集成。写AI提示词Prompt时也可以让它帮忙优化结构和语言。本地环境配置步骤实录克隆与安装git clone https://github.com/violettance/error_vault.git cd error_vault bun install # 或用 npm install环境变量在项目根目录创建.env.local文件。这里有个关键点Supabase的密钥和URL必须去Supabase项目设置的API页面获取anon key和service_role key权限不同前端只能用anon key。# .env.local NEXT_PUBLIC_SUPABASE_URLhttps://your-project-ref.supabase.co NEXT_PUBLIC_SUPABASE_ANON_KEYyour-anon-key GEMINI_API_KEYyour-google-ai-studio-api-key数据库初始化在Supabase的SQL编辑器中运行项目sql/目录下的迁移文件。例如先创建用户表、考试表再创建题目分析表并建立好外键关系。务必注意表的关联关系设计这直接影响后续查询效率。4.2 部署到Vercel的注意事项Vercel是部署Next.js应用的首选几乎是无缝衔接。连接仓库在Vercel控制台导入你的GitHub仓库它会自动检测到是Next.js项目。环境变量配置在Vercel项目的Settings - Environment Variables页面将.env.local里的三个变量一模一样地填进去。切记NEXT_PUBLIC_开头的变量会被打包到客户端代码中所以SUPABASE_ANON_KEY和URL会暴露。这正是Supabase设计所允许的因为anon key只有有限的、预设的权限。但GEMINI_API_KEY是服务器端使用的绝对不能加NEXT_PUBLIC_前缀Vercel会将其作为服务端环境变量处理。构建与部署Vercel会自动运行next build。这里可能遇到的一个坑是如果项目中用了Sharp等原生模块图片处理可能需要需要在package.json中指定optionalDependencies或者在Vercel的项目设置中配置安装命令确保构建时能正确安装这些原生依赖。Serverless Function限制Next.js的API路由在Vercel上会部署为Serverless Function。Gemini API调用或复杂的图片处理如果超时可能会触发Vercel的10秒Hobby计划超时限制。对于耗时的批量分析任务我的做法是API路由只负责接收请求、创建分析任务记录并立即返回。真正的分析任务通过一个独立的、运行时间更长的后台进程来处理。这个进程可以部署在另一台服务器上或者使用Vercel的Cron Jobs定时任务来模拟一个队列消费者定期检查并处理待分析的任务。这是生产环境必须考虑的架构设计。4.3 数据库设计与性能考量Supabase使用的是PostgreSQL良好的表结构设计是性能的基础。核心表结构设计思路users表存储最简单的用户标识User ID。为未来扩展预留了email,name字段。exams表核心表之一。记录每次考试的基本信息user_id关联用户exam_typeTYT/AYTexam_datetotal_scorenet_score净得分。这里net_score是根据考试规则通常错题扣分空题不扣分计算出来的关键指标。exam_subjects表这是一个连接表。因为一次考试包含多个科目每个科目的成绩正确数、错误数、空白数单独记录在这里。它通过exam_id关联到exams表通过subject_name关联到一个预设的subjects科目表。这种设计避免了在exams表中使用JSON字段存储科目成绩使得按科目查询、统计变得非常高效。question_images表存储上传的图片信息。exam_id,subject_name,image_url指向Supabase Storageuploaded_at。这里没有直接把图片二进制存数据库而是存URL是标准做法。question_analyses表AI分析结果表。每条记录对应一张图片的分析。字段包括question_image_id外键subjectAI识别main_topic,sub_topic,bloom_level,error_type,analysis_json存储完整的AI返回结果等。这个表会频繁被查询和聚合。exam_analyses表考试聚合分析结果表。当一次考试的所有题目分析完后生成一条汇总记录。存储如exam_id,weakness_summaryJSON 薄弱点TOP5error_type_distributionJSON 错误类型分布等聚合数据。这样在查看考试报告时不需要每次都实时聚合question_analyses表的大量数据用空间换时间极大提升仪表盘加载速度。索引策略为了加速查询必须在以下字段创建数据库索引exams(user_id, exam_date DESC)快速获取某个用户按时间排序的考试列表。question_analyses(exam_id, error_type)快速筛选某次考试中特定错误类型的题目。exam_subjects(exam_id, subject_name)快速获取某次考试特定科目的成绩。5. 常见问题、踩坑记录与优化建议在实际开发和测试中遇到了不少典型问题这里做个集中记录希望能帮你避坑。5.1 AI分析相关的问题问题1AI识别科目或知识点不准确。现象上传的数学题AI识别成了物理或者一道函数题识别出的知识点过于宽泛如“代数”而不是具体的“三角函数图像变换”。排查与解决优化提示词在Prompt中提供更明确的上下文。例如告诉AI“这是土耳其TYT考试的一道数学题”并提供TYT数学的考纲或主要知识点列表作为参考。可以要求AI从提供的列表中选择最匹配的知识点。图片预处理确保上传的图片清晰、端正、光照均匀。可以在前端上传时提醒用户“请拍摄清晰、完整的单道题目”。后端也可以集成简单的图像处理库如sharp对图片进行自动旋转、裁剪增强、提高对比度等操作提升OCRAI内嵌的视觉识别能力的准确率。人工复核与反馈机制在系统中加入一个“修正”功能。如果用户发现AI分析有误可以手动选择正确的科目或知识点。系统可以记录这些修正未来或许能用于微调提示词或作为训练数据。问题2AI分析速度慢或超时。现象一次上传20张图片分析过程长达几分钟甚至前端请求超时。排查与解决异步化与队列如前所述绝不能在前端请求中同步进行批量分析。必须采用“请求-响应-轮询”的异步模式。这是架构设计问题必须在一开始就考虑。并发控制即使在后端队列中也要控制同时调用Gemini API的并发数避免触发其速率限制Rate Limit。可以设置一个并发池例如最多同时处理3个分析任务。缓存结果对于完全相同的题目图片可以通过计算图片MD5哈希判断可以跳过AI分析直接使用之前缓存的分析结果。这在题库类应用中效果显著。问题3AI返回的JSON格式不稳定。现象偶尔AI不按约定的JSON格式返回导致后端解析失败。排查与解决强化Prompt约束在Prompt中明确要求“只输出JSON不要有任何额外的解释、前缀或后缀”。可以使用类似“json ...”的标记来强调。后端健壮性处理在后端代码中不能假设AI返回的数据一定是完美的。要用try...catch包裹JSON解析过程。如果解析失败可以尝试用正则表达式从返回文本中提取JSON部分或者记录错误、将任务标记为失败等待重试或人工处理。5.2 前端与性能问题问题4大量图表导致页面卡顿。现象考试历史页面有多个复杂的ECharts或Recharts图表切换或渲染时感觉卡顿。排查与解决虚拟滚动与分页对于题目列表如果一次考试有上百道错题不要一次性渲染所有条目。使用虚拟滚动库如tanstack-virtual或简单分页。图表懒加载与按需渲染初始只加载最重要的图表如总分成线图。其他图表如各科目详细分析图可以在用户点击对应标签页时才加载和渲染。使用Next.js的动态导入dynamic import配合ssr: false可以轻松实现。优化数据序列化从Supabase查询到的数据特别是包含JSON字段的体积可能较大。确保只查询前端需要的字段使用select()精确指定避免select(*)。对于复杂的聚合数据尽量在数据库层面完成计算而不是把原始数据拉到前端再处理。问题5图片上传体验不佳。现象上传多张图片时网络稍不稳定就可能失败且用户不知道进度。排查与解决使用分片上传对于大图片可以实现前端分片上传后端再合并。Supabase Storage的JavaScript客户端库支持断点续传可以集成这个功能。提供清晰的反馈上传组件要显示每张图片的上传进度百分比、状态等待、上传中、成功、失败。失败的要提供重试按钮。前端压缩在上传前使用如browser-image-compression这样的库对图片进行压缩在不明显损失质量的前提下减小文件体积加快上传速度。5.3 数据安全与隐私问题6用户数据隔离。现象所有用户数据都在同一个数据库里如何确保用户A绝对看不到用户B的数据解决这是Supabase的强项。使用Row Level Security (RLS)。为exams,question_images等表启用RLS并创建策略Policies。例如为exams表创建策略CREATE POLICY Users can only view their own exams ON exams FOR SELECT USING (auth.uid() user_id);这样任何查询都只能看到当前登录用户自己的数据。即使前端错误地请求了其他用户的ID数据库层面也会返回空。这是最根本、最有效的安全措施必须在项目初期就配置好。问题7敏感API密钥管理。现象Gemini API Key是核心资产泄露会导致经济损失和滥用。解决永远不要提交到代码仓库.env.local文件必须在.gitignore中。使用环境变量在Vercel等部署平台严格通过环境变量配置。限制API密钥权限在Google AI Studio中为这个项目的API Key设置用量限制每日限额、甚至IP白名单如果服务器IP固定将损失风险降到最低。开发ErrorVault的过程是一个典型的“用技术解决具体场景问题”的实践。从最初的“AI分析错题”这个点子到一步步设计数据流、选择技术栈、处理各种边界情况和性能问题最终形成一个可用的产品挑战不小但成就感也很足。最大的体会是AI能力的应用关键不在于模型本身多强大而在于如何将它巧妙地、可靠地嵌入到真实的用户工作流中并处理好它带来的不确定性如输出格式不稳定、分析偶尔不准。这需要前后端、数据库、产品设计等多方面的紧密配合。如果你也在考虑做一个AI增强的应用希望这些具体的实现细节和踩坑经验能给你带来一些实实在在的参考。