用DeepSeek API打造一个可交互、能答题的元素周期表探索器

元素周期表这玩意儿上学的时候谁没被它折磨过。118个元素一堆数字和符号老师让你背、让你默考完就忘。但你有没有想过把它做成一个能点、能玩、能答题的东西我最近就用DeepSeek API做了个《元素周期表探索器》把118个元素全部做成可交互的卡片点开任何一个元素属性立刻展示出来切到测验模式它会根据元素随机出题回答完直接判分。整个项目纯前端实现没有后端服务所有智能问答和判题逻辑都靠DeepSeek的接口撑起来。这篇文章就把完整思路、核心代码、API接入细节和踩过的坑写出来适合三类人看一直想接大模型API但不知道怎么落地的前端开发者、做教育类小工具或科普产品的朋友以及单纯想学“怎么让AI按你的规矩输出结构化内容”的人。我把话说在前面这项目本身不复杂难的是让大模型稳定输出你想要的JSON格式、控制延迟、控制成本这些我都会展开讲。1. 项目拆解这个探索器到底在做什么1.1 三个核心模块各自解决什么问题拿到这个标题的时候我第一反应是把需求拆成三个独立模块元素展示、属性详情、测验判分。为什么一定要拆因为这三个模块对数据的要求完全不同。元素展示解决的是“一眼看到全部118个元素”的问题。化学元素周期表是标准的网格布局每个元素有自己的位置周期和族数据是死的、确定的这部分根本不需要大模型参与我直接用一份公开的JSON数据渲染就行。属性详情解决的是“点开某个元素看具体信息”的问题。这部分有两种做法一种是把JSON数据里的字段直接展示另一种是调用DeepSeek生成更丰富的解释。我两者都做了基础属性走本地数据保证秒开扩展解释和趣味冷知识走API延迟可以接受。测验判分则是整个项目最有价值的部分它需要从118个元素里随机抽题、判断用户答得对不对、还要解释为什么错这必须靠大模型。拆完模块后整个项目就变成流水线了数据层准备好了交互层只负责点击和展示AI层只负责出题和判分。互不干扰出问题也好排查。1.2 技术选型为什么不用本地题库非要接API很多朋友看到“答题测验”第一反应是本地题库不就行了自己写50道题放JSON里然后随机抽判分用字符串匹配这确实能做。但我接API的目的不是为了炫技而是解决两个真实痛点。第一是题目多样性。本地题库写死的题用户刷两遍就腻了。DeepSeek可以基于元素周期表即时生成近乎无限的题目组合今天考“哪个元素的原子量最接近63.55”明天考“第4周期第VIB族是什么元素”题目不重样。第二是解释能力。用户答错的时候我希望它能给出“为什么错”以及“正确答案的化学背景”这不是字符串匹配能搞定的。当然纯用API也有代价最直接的就是延迟和成本。所以我的策略是分层不需要智能的部分比如展示原子序数、原子量、电子排布全走本地数据需要生成和判断的部分才走DeepSeek。这个取舍很关键否则每次点元素卡片都转圈体验会非常糟糕。2. 前期准备接口、数据、项目结构2.1 获取DeepSeek API Key并配置环境做这个项目之前你需要一个DeepSeek的API Key。流程很简单去DeepSeek开放平台注册账号在控制台创建一个API Key创建的时候记得把Key复制保存下来它只会显示一次。然后给账户充一点额度DeepSeek的聊天模型价格很便宜后面我会专门算账。我在本地开发的时候直接把Key放在一个config.js文件里用变量存着。但这里必须提个醒如果你要部署到公网千万别把Key写进前端代码否则任何人打开浏览器控制台都能看到你的Key。我后文在部署章节会专门讲怎么用Serverless函数把Key藏起来。本地开发图省事可以直接放但心里要明白这是临时方案。2.2 元素数据从哪来一份公开的JSON就够了118个元素的完整数据不需要自己手工录入开源社区早就整理好了。我在项目里用的是一份比较通用的JSON数据每个元素包含这些核心字段字段含义示例symbol元素符号Fename元素名称铁atomicNumber原子序数26atomicMass相对原子质量55.845category元素分类transition metalgroup / period族 / 周期8 / 4electronConfiguration电子排布[Ar] 3d6 4s2electronegativity电负性1.83你可以在GitHub上搜“Periodic Table JSON”很多项目都内置了类似的数据。下载下来后我做了两步处理第一步把category等英文分类映射成中文方便界面展示第二步做了一份索引表以symbol为key这样点击元素卡片时查找数据的时间复杂度是O(1)不会卡顿。2.3 项目结构零依赖三个文件搞定整个项目我刻意保持了极简结构没有用任何框架纯HTML CSS JavaScript加上一个config.js。目录如下periodic-explorer/ ├── index.html # 页面结构 ├── style.css # 周期表网格与面板样式 ├── data.js # 118个元素的本地数据 ├── config.js # API Key与常量配置 └── app.js # 渲染与API调用逻辑为什么不用Vue或React因为元素周期表是静态网格点击事件逻辑也不复杂原生JS足够胜任。少一个框架就少一份体积页面加载速度也更快。这个项目的核心卖点是内容本身和AI交互而不是前端架构所以一切从简。3. 从零搭建探索器页面网格渲染与交互3.1 HTML骨架容器、信息面板、测验区三大块页面结构我设计成三个区域顶部一个标题栏中间的主体区域分左右两栏——左侧是周期表网格右侧是信息面板/测验区。HTML骨架大致是这样div classapp header h1元素周期表探索器/h1 div classmode-switch button idbtn-explore探索模式/button button idbtn-quiz测验模式/button /div /header main div idperiodic-grid classgrid/div aside iddetail-panel div idelement-info/div div idquiz-area classhidden/div /aside /main /div这套结构的关键在于两个模式共用同一个信息面板区域。探索模式下面显示元素详情测验模式下同一个区域变成答题卡。这样切换模式时不需要销毁重建DOM只切换内部组件的显隐。3.2 渲染118个元素卡片CSS Grid是关键周期表布局非常规整18个族、7个周期用CSS Grid可以完美还原。我设置了一个18列的网格容器然后根据每个元素的group和period计算它在网格中的位置。#periodic-grid { display: grid; grid-template-columns: repeat(18, minmax(36px, 1fr)); gap: 4px; }渲染逻辑是这样的遍历118个元素对每个元素创建一个div卡片通过计算gridColumnStart group、gridRowStart period实现精准定位。镧系和锕系元素虽然放不进主表格但我单独加了两行紧凑行来展示。卡片样式我按元素分类做了颜色区分碱金属、碱土金属、过渡金属、非金属、贵气体等各给一套背景色。这样做的好处非常明显即使不看文字扫一眼颜色就知道元素的大致类别这也是周期表本身的学习价值之一。卡片内部只展示symbol和原子序数名称和信息保持干净等点击后再展示。3.3 点击交互本地数据秒开详情API请求做扩展元素卡片的点击逻辑分两步。第一步从本地JSON数据里取这个元素的所有基础字段填充到右侧面板包括中文名称、英文名、符号、原子序数、原子量、周期、族、电子排布、电负性这些全部同步渲染毫秒级完成。第二步如果用户想听点“有意思的”我加了一个“问问AI”的按钮点击后把该元素的名称和用户附带问题一起发给DeepSeek让它生成一段关于这个元素的介绍或冷知识。这一步的设计思路是不能让用户每次点击都等一个API响应。基础属性是确定的它不该受网络波动影响AI是增量价值它可以慢慢加载。我测试下来本地渲染大概2msAI响应在3~8秒不等把两者混在一起会让最基础的操作都变得卡顿这是交互上最容易犯的错误。4. DeepSeek API接入让模型按你的规矩说话4.1 标准请求姿势endpoint、鉴权与Body结构DeepSeek的API兼容OpenAI的Chat Completions格式熟悉GPT接口的人几乎零成本迁移。核心调用就一个HTTPS请求示例如下async function askDeepSeek(messages) { const resp await fetch(https://api.deepseek.com/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${API_KEY} }, body: JSON.stringify({ model: deepseek-chat, messages: messages, temperature: 0.3, max_tokens: 800 }) }); const data await resp.json(); return data.choices[0].message.content; }关于参数我重点说三个。model用deepseek-chat就够这是通用对话模型能力和成本平衡得很好temperature我压到了0.3因为出题和讲解需要稳定输出温度太高会生成随机性太强的题目甚至错误信息max_tokens控制在800防止一次回答生成太长的文本既费token又拖慢前端渲染。4.2 让AI输出结构化JSON提示词约定 兜底解析这是我踩坑最深的地方。刚开始我让DeepSeek“介绍一下铁元素”它会回一堆带Markdown标题的文本前端根本没法直接渲染成结构化面板。后来我痛定思痛prompt里强制要求它只返回JSON并且用代码块约定输出格式。你是一个元素周期表助手。用户会给你一个元素符号和问题。 请以JSON格式回答且只输出JSON不要输出任何其他文字。 JSON格式如下 { summary: 一句话点明这个元素的核心特征, highlight: { title: 一个亮点标题, content: 关于这个亮点的2-3句详细说明 }, fun_fact: 一个冷知识 }即使这样模型偶尔还是会返回json这类代码块包裹。所以我在前端解析时加了一层兜底用正则把内容里json和的部分剥掉再尝试JSON.parse。如果解析失败就降级为纯文本显示。这个降级策略非常重要它保证了AI偶发抽风时用户看到的是“丑了点”的内容而不是一个崩溃的白屏或红字报错。4.3 成本与延迟控制一次问答到底花了多少钱有朋友一听“接大模型API”就觉得烧钱实际算下来非常便宜。DeepSeek的定价按输入和输出分开计费我以当时的公开价格为例估算一笔账输入大约每百万token几块钱输出大约每百万token十几块钱。一次元素介绍请求输入prompt加元素名大约200 token输出控制在600 token总成本折合人民币不到一分钱。就算用户狂点一整天累计也花不了几块钱。延迟方面普通对话请求实测在2秒到6秒之间高峰期可能到10秒。我在前端做了三个处理加loading动画、设置15秒超时、失败后提示用户重试。不要试图让大模型响应变得和本地数据库一样快这不现实。接受它的速度然后用交互设计去弥补。5. 测验功能实现出题、判分、解释一个不落5.1 出题策略随机抽元素 题型模板测验模式的设计目标不是“难倒用户”而是“通过答题加深对周期表的理解”。我的出题流程是这样的每次测验生成5道题从118个元素里随机抽取5个不重复的元素每个元素对应一种随机题型。题型我定义了三类全部让DeepSeek即时生成题型题目示例考察点符号↔名称“Fe的元素符号对应的中文名称是什么”符号记忆属性判断“氯和溴相比哪个电负性更高”规律理解周期定位“位于第3周期第VIA族的元素是”周期结构感知prompt这样写请基于这套元素周期表数据出5道选择题用户是中学生。 题目必须涉及以下5个元素[{randomElements}] 每道题返回如下JSON格式 { quiz: [ { question: 题干, options: [A选项,B选项,C选项,D选项], answer: 正确选项的字母, explanation: 为什么选这个 } ] }核心技巧是把抽取元素的动作放在前端完成传给API后让它围绕这5个元素出题。这样一来模型不需要自己随机选元素出题范围可控也不会出现一道题重复考同一个元素的情况。5.2 判分逻辑前端判分 AI解释两段式设计关于判分我做过两版方案第一版是把用户的答案发给DeepSeek让它判对错。实测发现延迟太高用户提交一道题要等5秒体验很差。后来我改了选择题的答案就藏在answer字段里用户点击选项后前端本地比对字母立刻知道对错对错判定后再把“题目 用户答案 正确解析”发给DeepSeek生成一段详细解释。这个两段式设计最大的好处是判分零延迟解释有深度。判分是确定性逻辑不该交给概率模型解释是生成式任务正该交给大模型。前端拿到判分结果后显示“答对了/答错了”同时后端流式返回解释内容。测试下来解释加载的几秒钟里用户已经被对错的结果留住了流失感要小很多。5.3 成绩计算与记录5道题答完我会统计得分并给出一个总评。因为每道题难度随机全部答对不代表化学天才但全部答错肯定说明基础没打牢。所以我设计了一个简单但带激励的评价体系5题全对显示“周期表大师”徽章并生成一段鼓励性评语。答对3-4题显示“优秀”提示哪类题型容易错。答对1-2题显示“继续努力”列出建议复习的几个元素。5题全错不显示惩罚性文字只让AI生成“从零开始复习”的计划。这个设计的背后逻辑是学习工具的反馈机制越正向用户再来的概率越高。即便做的是AI项目产品设计上也不能只追求功能完整还得考虑情绪价值。6. 部署上线与成本控制实录6.1 本地验证先跑通再考虑上线开发阶段我用的是VS Code加Live Server插件直接本地起一个http服务。这一步主要是验证三件事周期表网格是否按预期排列、本地数据点击是否秒开、API请求能否正常返回。本地验证时我都会打开浏览器Network面板确认每个请求的耗时和返回结构尤其要看返回的JSON有没有被截断——max_tokens太小会导致内容被硬切JSON直接解析失败。6.2 公开部署Vercel Serverless Function保护API Key如果只是自己做着玩本地跑跑就够了。但如果你想分享给朋友或者挂到网站上那就必须解决API Key泄露的问题。我最开始图省事把Key直接写在前端JS里部署到Vercel结果发到群里三分钟就有人发消息说“兄弟你Key露了”。所以这里我必须敲黑板前端代码里出现的任何字符串用户都能在控制台看到。API Key绝对不能在公网前端明文出现。正确的做法是加一层薄薄的Serverless函数做代理。在Vercel项目里添加一个/api/chat.js接口前端只请求这个接口真正的API调用在服务端完成Key只存在于服务端环境变量里。前端代码变成这样const resp await fetch(/api/chat, { method: POST, body: JSON.stringify({ messages: messages }) });服务端代码只需要20行左右把请求转发到DeepSeek再返回结果。核心目的是让Key不出服务器。6.3 成本预估一个学习型项目一个月花多少钱我用Excel简单算过一笔账。假设每天有50个人使用每人平均点开5次AI问答、完成2次测验。一次问答约800~1000 token一次测验包含出题和后续解释约2000 token。按当时DeepSeek的价格折算一天消耗大约20万token一个月600万token总成本折算下来大概在30~60元人民币左右。这还包含了一些失败重试的浪费。所以对学生、个人开发者、小团队来说这个量级的成本基本可以忽略。如果你担心成本失控有两条实用建议给前端加上“每日请求次数限制”用localStorage存计数或者在后端代理里加一个简单的每日额度阀门。深度学习项目的成本控制不是等账单爆了再处理而是从一开始就要设好闸门。7. 常见问题与排查技巧实录7.1 浏览器直接请求DeepSeek API报CORS错误这是第一个坑。浏览器里直接用fetch请求api.deepseek.com控制台会看到CORS报错。原因很简单DeepSeek服务器没有配置允许浏览器页面跨域访问这个接口主要是为服务端设计的。解决办法就是我前面说的加一层Serverless代理。如果你只是本地测试也可以用某些浏览器插件禁用CORS但那只适合开发调试不适合正式项目。7.2 JSON.parse总是失败模型要么包了markdown要么多了结尾句我在开发时遇到最频繁的问题就是模型返回的内容不是纯JSON。明明prompt写了“只输出JSON”它偶尔还是会夹带“好的以下是……”。我的解决思路分三层第一前端写一个extractJSON函数用正则去掉首尾的json标记第二找到第一个{和最后一个}并截取第三如果解析失败不直接报错而是把原始文本展示为普通段落。这套容灾机制上线后API偶尔抽风时用户几乎无感。7.3 响应太慢用户以为卡死了大模型的响应速度不是你能控制的但你至少可以做三件事。第一是加载提示要明显我用了一个旋转的原子图标加“AI思考中……”文案第二是设置合理的超时时间我定的是15秒超过就提示“这次思考太久请重试”第三是丢弃历史消息只保留必要的上下文减轻模型负担。有一点经验供参考请求体里的messages数组只放最近几轮对话不要无限累积既省token又提速。7.4 输入token超限长对话崩了quiz模式里用户连续做五六次测验后messages数组累积了大量历史可能会碰上下文长度上限。我的办法是每次新测验开始时重置会话只保留系统提示词和本次测验的5个元素列表。这个方法在长对话场景下非常管用相当于给AI“翻篇”让它每次只看当前任务而不是背着几万字的历史包袱。7.5 元素位置对不齐镧系锕系全挤到一块CSS Grid渲染主体周期表没问题但镧系和锕系是单独的两行容易跟主表挤在一起。我最后的方案是给这两行做独立的Grid上下文并加上“镧系”和“锕系”的行标签。如果你拿到的JSON数据里已经有row这个字段直接用它定位会更稳。8. 实测感受与扩展方向这个项目做完之后我自己连着玩了一个星期最大的感受是接大模型API这件事真正的门槛根本不在写代码而在于你怎么和它约定规则、怎么容错、怎么控制成本。让DeepSeek返回一个字段完整、格式正确的JSON比它生成一段漂亮的文字难多了。你需要在prompt里反复明确格式在代码里反复处理意外这两个能力才是AI应用开发的核心基本功。后续我打算在这个探索器上再加两个功能一个是“元素对战模式”随机两个元素比属性用户猜谁会赢另一个是想接入DeepSeek的流式接口让AI讲解内容像打字机一样逐字出现那体验会比现在“loading转圈然后整段出现”自然得多。如果你也想做类似的AI交互工具建议先把这个项目的骨架抄一遍再换成你自己的知识领域比如做一套“昆虫图鉴AI问答”或“历史人物探索器”底层逻辑完全通用。