我去年年底到今年年初一直在捣鼓AI Agent相关的落地项目前后试了好几个技术栈最后用一个简历工具把 Next.js LangGraph.js 的组合完整跑通了。这篇文章不聊PPT架构也不画大饼就讲实际落地的技术选型、核心实现、部署排查以及我个人踩过的一堆坑。如果你也在纠结“AI Agent到底怎么接到真实业务里”这篇希望给你一些能直接抄作业的参考。1. 项目背景与整体设计思路1.1 为什么做简历工具而不是别的 Demo选简历工具作为 AI Agent 的落地场景是我反复比较后的结果。原因很简单第一简历解析和优化具备完整的多步骤工作流特征——从原始文本提取、结构化字段解析、匹配度评估到修改建议生成和最终重写每个环节都有独立的输入输出第二简历处理天然依赖“外部非结构化数据”和LLM推理的结合PDF/Word/DOCX 里提取出来的内容没法直接喂给模型必须做清洗和转换这给了 Agent 编排框架发挥空间第三这个场景的效果容易被用户感知改动前后的对比一目了然。1.2 技术选型LangGraph.js 为什么比纯 LangChain 链式调用更适合很多人入门 Agent 时用的是 LangChain 的LCEL链式调用写起来确实快几行代码就把“提取→总结→翻译”串起来了。但真实项目里很快会遇到几个坎分支逻辑怎么办失败重试怎么处理状态怎么在不同阶段共享和回滚用户在对话过程中改了需求整个流程怎么重新编排LangGraph.js 给我的核心价值是它把 Agent 执行过程抽象成了有状态图StateGraph节点Node代表一个执行步骤边Edge代表状态流转条件边Conditional Edge则让路由逻辑显式化。跟链式调用相比最大的区别是“流程可回溯、状态可共享、分支可控制”——这三个特性对简历工具这种长流程应用来说非常关键。举个例子用户上传一份简历后解析阶段可能成功也可能失败PDF 加密、扫描件 OCR 识别率过低等如果解析失败我们需要让用户重新上传而不是直接终止整个流程这在链式调用里很难优雅实现但在 Graph 里只需要为parse_node加一条条件路由失败时跳回collect_input节点等待新的输入整个过程非常自然。1.3 为什么选 Next.js 作为前端框架选 Next.js 有几个非常务实的理由。首先是API Routes 与流式响应Streaming的支持这是当前前端框架里最成熟、坑最少的一档。AI Agent 的响应时间普遍在 5-10 秒甚至更长如果像传统接口那样等全部生成完再返回用户的等待焦虑会非常明显。Next.js 的 Route Handlers 天然支持ReadableStream配合前端fetch的流式读取可以实现“首屏 token 秒出后续 token 陆续到达”的体验体感上比完整等待快太多了。其次是Server Actions和 API Routes 可以共用 Node.js 运行时直接复用 LangGraph.js 的代码逻辑不需要为前端做 BFF 层减少一层网络开销和类型维护成本。小团队单人开发时这种“一个项目内自闭环”的体验非常舒服。最后Next.js 对部署生态的支持太好了Vercel 上直接跑国外用户访问延迟低配合 Redis 做状态存储非常顺手。1.4 与“AI Agent 主流架构”的对位思考接触过 Agent 的人应该知道业内目前主流的 Agent 架构大致可以分成三类ReAct/Function-Calling Loop工具调用循环、Plan-and-Execute先计划再执行、以及 Graph Workflow图工作流。我刻意选择了 Graph Workflow 而不是 ReAct Loop。原因是简历工具的核心需求不是“让模型自己决定要调哪个工具”而是“让流程严格按照业务逻辑来走”——解析、提取、评估、重写这一步一步的顺序是一开始就确定的不需要模型发挥创造力去跳步。如果硬要用 ReAct Loop模型会在不必要的地方做多余决策增加 token 消耗和不可控的延迟。LangGraph.js 在这方面给出了一个特别优雅的抽象允许你在同一个 StateGraph 里混用确定性边和条件边。确定性边保证主流程的稳定条件边只在特定节点让模型做必要的决策比如是否需要继续追问。这样既保留了对业务的控制力又给模型留出了自由度。2. 核心系统架构与状态设计2.1 整体架构拆解整个系统从上层到下层可以拆成四个层次。最上层是 Next.js 前端页面App Router负责三个核心交互简历上传、文本编辑预览、Agent 工作流可视化调试用。中间层是 Next.js Route Handlers暴露两个端点一个处理简历上传multipart/form-data一个处理 Agent 工作流触发与流式响应POST JSON 或 SSE。再往下是 LangGraph.js 的核心执行引擎里面定义了ResumeGraph由 6 个节点组成每个节点是纯函数式逻辑负责一个明确的子任务。最底层是模型与基础服务gpt-4o-mini-2024-07-18后来换成了 gpt-4.1-mini文本拆分器Redis用于状态持久化和恢复以及 PDF 上传服务。这个分层跟很多前端项目完全不一样的地方在于核心业务逻辑不在前端、也不在传统意义上的后端 API 层里而在图编排引擎里。前端只负责展示与输入收集API 层只做协议转换与流式通道真正的决策、分支、循环都在 LangGraph 内部流转。2.2 工作流状态设计与类型定义LangGraph.js 的核心是状态对象。状态会随节点执行不断更新。我在项目里用 TypeScript 定义了ResumeStatetype ResumeState { rawText: string; // 原始文本从PDF/DOCX提取 fileName: string; // 上传文件名 fileType: string; // 文件类型 structuredData: ResumeSchema | null; // 结构化字段 jdText?: string; // 职位描述可选输入 matchingScore: number; // 匹配度 0-100 analysisReport?: AnalysisResult; // 评估报告 rewriteResult?: string; // 最终改写结果 };比较关键的设计是所有节点只通过 State 传递数据不自己维护私有状态。哪怕rewrite_node需要structuredData和analysisReport两个上游产出它也不直接从全局变量取而是从 State 里拿。这个约束让每个节点都能被单独测试——我们确实在开发期做了大量单点调试把原始文本喂到parse_node看看结构化提取效果再把parse_node输出喂进evaluate_node模拟 Agent 工作流里的数据传递。2.3 状态共享与上下文累积LLM 的 Agent 应用中状态共享和上下文累积是一对矛盾。如果所有历史信息都塞进上下文token 消耗会指数级增长如果只保留最终结果中间步骤的细节比如“JD 中要求熟悉 Kubernetes但简历里完全没提”就会丢失。解决方案是LangGraph.js 允许定义State的reducer控制状态更新方式。我写了一个简单的合并 reducer保证每次更新都追加到对应字段而不是覆盖同时只保留最近 N 轮信息。const stateReducer { analysisReport: (prev, next) next ?? prev, rewriteResult: (prev, next) next ?? prev, };这本质上跟“记忆管理”是同一个问题。小项目不需要引入专门向量库做长期记忆一个拷贝语义copy-with-merge加上字段级别的更新时机控制就够用了。不过如果后续做“多轮对话优化简历”就得考虑引入单独的记忆节点把每次优化建议固化到持久化存储里。2.4 图定义与执行流程LangGraph.js 的图定义代码并不复杂import { StateGraph, END } from langchain/langgraph; const workflow new StateGraph({ channels: stateReducer, }) .addNode(collect_input, collectInputNode) .addNode(parse_node, parseResumeNode) .addNode(extract_node, extractStructuredNode) .addNode(evaluate_node, evaluateResumeNode) .addNode(rewrite_node, rewriteResumeNode) .addNode(output_node, outputResultNode); workflow.addEdge(collect_input, parse_node); workflow.addConditionalEdges(parse_node, routeAfterParse, { success: extract_node, reparse: collect_input, fail: collect_input, }); workflow.addEdge(extract_node, evaluate_node); workflow.addEdge(evaluate_node, rewrite_node); workflow.addEdge(rewrite_node, output_node); workflow.addEdge(output_node, END); export const resumeGraph workflow.compile();一些细节说一下。collect_input是一个“入口节点”在这里接收用户上传的原始文本和可选的 JD 文本。它不触发 LLM只是一个数据汇聚层。一开始我没加这个节点直接让parse_node接收上传数据结果状态初始化出现的次数特别多加了一个显式集合节点后状态结构就清晰了。条件路由routeAfterParse里我返回的是字符串键LangGraph.js 会根据映射关系决定走哪条边。核心判断逻辑是如果文本提取结果为空会重试如果非空但解析置信度过低就建议重新上传只有结构完整才继续。LLM 调用节点在实现上遵循一套统一模式先从 State 里取数据、构造 Prompt、调用模型、后处理解析结果尤其是 JSON 解析容错必须做足再返回部分状态。这个模式写多了以后会发现Graph 开发跟传统后端开发的核心区别是你始终在描述状态如何从一个形态演化到另一个形态而不是在描述一个函数如何被调用。3. 核心实操LangGraph.js 节点实现与流式交互3.1 文档解析节点PDF/DOCX 提取的工程细节简历上传最常见的格式是 PDF其次是 DOCX。解析这块的难点不在调库而在异常处理。PDF 我用的是pdf-parse它对纯文本类 PDF 的提取效果很好。但有两类实际问题一是扫描件 PDF 完全没有文本层提取结果为空需要提示用户“该 PDF 可能是扫描件请转换为可复制文本的 PDF”二是 PDF 含加密锁需要密码才能打开pdf-parse会直接抛异常。所以我给parse_node写了多层防御先尝试提取文本文本过短则返回fail把这两个分支写成路由比在节点内部强行 OCR 要靠谱——OCR 服务比如 Tesseract对中文简历的识别率并没有到可接受的水平。DOCX 处理用的是mammoth它能把 Word 文档转成 HTML我再从 HTML 里剥离标签得到纯文本。这里踩过一个坑直接解析 DOCX 转换后的纯文本会把列表符号和缩进全部丢掉导致简历的结构信息丢失后面结构化提取效果大打折扣。我的做法是先从 HTML 里识别出ul、li、h1-h3等标签把它们转成 Markdown 风格的-和#再喂给 LLM。模型对 Markdown 的语义理解能力比对纯文本好很多。3.2 结构化信息提取节点这一节点非常重要因为后续评估和重写都依赖于结构化结果的一致性。这里有个选型问题是继续让 GPT-4o-mini 直接输出结构还是走 Function Calling我选了 Function CallingOpenAI Responses API / Chat Completions 的tools参数因为它能把输出强约束在 JSON Schema 范围内而不是靠 Prompt 加“请输出 JSON”。LangGraph.js 官方文档里也推荐在节点内调用模型时使用结构化输出来实现节点内部的任务约束。Schema 大致长这样const resumeSchema z.object({ personalInfo: z.object({ name: z.string().optional(), email: z.string().optional(), phone: z.string().optional(), }), education: z.array(z.object({ school: z.string(), major: z.string(), degree: z.string(), duration: z.string(), })), experience: z.array(z.object({ company: z.string(), position: z.string(), duration: z.string(), highlights: z.array(z.string()), })), skills: z.array(z.string()), });实际测试下来用zod做 schema 约束之后输出格式的稳定性有质的提升。之前纯 Prompt 解析时十次里有三四次 JSON 损坏或字段缺失换了 Function Calling 后基本很少再坏。唯一的遗憾是OpenAI 的gpt-4o-mini在这个场景下不能保证 100% 遵守函数调用约定偶尔会出现把函数调用说明文本混入输出的情况所以我额外加了一层“尝试解析 JSON → 失败则用正则兜底 → 再失败则要求模型只输出 JSON”的重试逻辑这个兜底逻辑在部署后救了不少次。3.3 评估节点与命中率计算评估节点的输入是全量结构化数据和可选的 JD。核心任务是生成匹配度分数和结构化评估报告。Prompt 里我加了一个关键技巧要求模型必须逐条输出“JD 要求”和“简历内容”的对照矩阵而不是直接给一个分数。这个对照过程会强制模型逐项核对准确率比直接打分高很多而且生成的评估报告用户能打印出来自己对照信任感强。匹配分数我用的是 0-100 整数制。算分数的 Prompt 写法是你是资深技术面试官。请根据简历内容与 Job Description 的匹配程度打分。打分依据 - 技术栈重合度40% - 业务领域重合度30% - 职级匹配度20% - 项目复杂度匹配度10% 请先输出逐项依据再输出 score、strengths、weaknesses、suggestions 四个字段的 JSON。这种带权重的 Prompt 设计比“给个星”更稳定。实际测试中分数分布比不带权重的版本更合理不会出现大家都 80 分以上的通胀局面。3.4 重写节点与代码宏控制在实战中的作用重写节点的 Prompt 设计核心是“让简历更适合目标 JD”。我试过好几个方案最好用的方法是提供重写模板再要求模型在约束范围内重写。模板的核心策略是量化优先要求将“负责XX系统”改写为“主导XX系统的设计与落地日请求量 1w可用性 99.95%”这类可验证的表达动词强化使用 developed、designed、led 等强动作动词避免“参与、协助、了解”这类弱词语与 JD 对齐要求模型将 JD 中明确出现的核心名词技术栈、业务关键词自然嵌入重写后的描述但不能造假。还有个 token 控制的经验。重写时如果直接把整个 PDF 解析出来的长文本约 3000-4000 token加 JD 全量塞给 LLM很容易突破 gpt-4o-mini 的上下文窗口。我的做法是按“最近 2 份工作经历 项目经历 技能清单”来切片先指导模型重写最相关的部分其他部分优先保持原样这样既节省 token也能让修改建议更聚焦。毕竟简历优化的核心诉求是“针对目标 JD 调整”而不是从头通篇重写。3.5 前后流式交互从 LangGraph 到浏览器LangGraph.js 支持流式返回节点级事件。我这里用的是.stream()加自己封装 EventSource 的方式——后端 Route Handler 大致逻辑export async function POST(req: Request) { const body await req.json(); const config { configurable: { thread_id: body.threadId } }; const stream await resumeGraph.stream( { rawText: body.rawText, jdText: body.jdText }, { ...config, streamMode: updates } ); // 转成 SSE const encoder new TextEncoder(); const readable new ReadableStream({ async start(controller) { for await (const event of stream) { const chunk data: ${JSON.stringify(event)}\n\n; controller.enqueue(encoder.encode(chunk)); } controller.close(); }, }); return new Response(readable, { headers: { Content-Type: text/event-stream, Cache-Control: no-cache, Connection: keep-alive, }, }); }配置里thread_id这一项值得单独说说。它是 LangGraph 的会话标识符同一thread_id的所有交互会共享同一个状态。这个字段对长对话流程非常重要——如果用户中途修改了 JDAgent 需要基于原有状态继续更新而不是从零开始。在 Vercel 这种 serverless 环境下checkpointer需要外部存储来做持久化我选择了 InMemorySaver 以外最简单的方案用 Redis 自实现一个 CheckpointSaver 接口因为 InMemorySaver 在 serverless 上完全不可用每个实例的内存都是隔离的。前端接收流的逻辑比较简单const response await fetch(/api/agent, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify(params), }); const reader response.body.getReader(); const decoder new TextDecoder(); while (true) { const { value, done } await reader.read(); if (done) break; const text decoder.decode(value); // 解析 SSE 数据按节点名更新 UI 状态 }前端 UI 建议用事件溯源模式来做——每收到一个节点完成事件就更新一次 UI 状态解析中、提取中、评估中、重写中。这样用户在等待时也心里有数不至于以为页面卡死了。这里一个小细节是React 组件里如果直接对 stream 做循环更新因为并发更新会互相覆盖需要用useReducer或者把更新动作传入flushSync否则会出现 UI 显示状态和实际进度错位的问题。3.6 在 Next.js 中配置模型密钥与环境服务端模型调用密钥统一从环境变量读取OPENAI_API_KEY。开发环境再用.env.local管理。有个部署时容易踩坑的地方是在.env.local里的变量在 Vercel 部署后会失效必须在项目后台的 Environment Variables 里重新配置。另外 prevention of SSRF 或者密钥泄露全靠服务端 API Route 代理模型调用绝对不要在前端直接掉 openai不然密钥直接暴露在浏览器源码里这是安全红线。4. 部署与评测实际运行效果与成本4.1 部署到 Vercel 的踩坑记录与解决我先说结果直接在 Vercel 上用 Node.js runtime而非 Edge Runtime运行 LangGraph.js 是可行的但有几个配置需要注意。第一个坑是 Next.js 的默认运行时。当你在 API Route 里export const runtime nodejs时没有问题但如果某个页面不小心启用了 Edge Runtime比如自动推断LangGraph 的一些依赖在 Edge 上会直接报错。建议所有涉及 Graph 执行的 Route Handler 都在顶部显式声明 Node.js runtime不要依赖自动推断。第二个坑是压缩层对 SSE 的影响。Vercel 的压缩和代理有时候会缓冲流式响应导致前端收到的不是实时的逐 token 事件而是一大段数据一次性到达。怎么排查看 Network 面板里响应是不是 chunked transfer如果显示(pending)资源一直不返回再把前端fetch的 cache 设置为no-store试试。另外也可以改成 WebSocket 推送但这里有一点复杂常规的 SSE 已经能达到不错的体验。第三个坑与冷启动有关。Graph 定义是静态的首次调用会做图编译、schema 校验、依赖加载冷启动耗时经常达到 3-4 秒。我的缓解方案有两个一是把 Graph 实例做模块级缓存globalThis上避免 next dev 热更新时重复创建二是给 Vercel 函数增加maxDuration到 60 秒否则超时时间默认 10 秒连冷启动都无法完成。需要注意maxDuration在 hobby 计划里可能不生效要 upgrade 到 Pro 才能用更长的执行时长。4.2 内部评测集的构建方式为了让 Agent 的改动有据可循我建了一个小规模的评测集——5 份真实脱敏简历加 3 条不同方向的 JD。每次修改 Prompt 或图结构后跑一遍评测集看三个指标字段提取准确率人工核对 30 个核心字段的提取是否完整、正确。匹配分数的稳定性对同一份简历跑 5 次看分数方差是否过大。改写有效比例改写后的简历是否保留了原有的量化成果比如不要随意捏造数据是否合理嵌入 JD 关键词是否破坏了原格式。这个评测集的价值非常大。有一次我调整了评估节点的 Prompt结果分数提高了 8 分左右但人工检查发现是因为模型“迎合”JD 做了虚高打分而不是真实匹配度上升——评测集立刻暴露了这个问题Prompt 方向也就立刻回滚了。4.3 token 成本估算用 gpt-4o-mini 跑完整流程的总 token 消耗大约是解析提取 3-4k评估 2-3k重写 4-5k合计平均 10k token 上下。按官方价格估算每次完整操作成本约 0.003-0.004 美元。一个月 1000 次使用也才几美元成本完全可以接受。但有个容易忽视的隐藏成本失败重跑。解析失败、JSON 解析重试、用户取消任务等场景下 token 照样消耗。有一次我在调试 parse 失败重试逻辑发现每次失败分支都会重新调用一遍模型导致成本翻倍。后来加了一个“最多重试 2 次”的限制同时在第一次失败时直接返回错误提示而不是让模型进行二次猜测这才把失败场景的成本降下来。4.4 无头浏览器生成 PDF 输出的实现细节用户改完简历后自然希望导出 PDF。前端直接用浏览器打印最简便但为了稳定输出和自定义样式我用 Puppeteer 在服务端做了一次 HTML 到 PDF 的转换。这里有一个合作上的教训Puppeteer 在 Vercel 上没有预装 Chrome 浏览器需要借助chrome-aws-lambda和puppeteer-core来加载他打好的二进制包同时要把 Vercel 函数的 maxDuration 提得很高。此外函数的 bundle 大小会超过 Vercel 默认 250MB 的限制要把 Chrome 的二进制文件放入public目录并给定特殊后缀然后在运行时加载。这个环节是整个系统里最麻烦的部分如果后续能改成提供 HTML/Markdown 导出而不是强行生成 PDF成本和维护量会大幅下降。5. 常见问题与排查技巧实录5.1 症状响应挂起长时间无流式输出这个现象在部署早期出现得特别多。排查路径是先看 Vercel 函数日志再看是不是冷启动超时通过浏览器 Network 面板可以明显看到请求一直 pending再确认是否 Node.js runtime 被某个依赖偷偷切到 Edge最后看模型 API 是否因为超时或限流在等待。一个很有用的技巧是给 Route Handler 加一个“性能埋点”在 Graphstart和end时分别打印耗时再在日志平台聚合。我加了之后发现最容易超时的节点是rewrite_node原因是它对全量 State 做了一个深度拷贝而ResumeState里包含很多的字符串数组拷贝耗时拉高了整个图执行时间。后来改成只拷贝不想变的字段引用问题立刻消失了。5.2 症状JSON 解析失败或字段缺失结构化提取的阶段出问题最多尤其是用户的简历包含大量非标准格式比如用表格排版、两栏布局、中英混杂。总结下来有三个措施提取后给 LLM 附上文本增强的上下文说明让模型保留要点提高temperature到 0.1 以下输出确定性会大幅提升用函数调用约束 schema已说并实现“先严格校验 Schema → 校验失败 → 自动降级解析只提取文本中的关键字段”的多级防线。最后这条降级逻辑很推荐做成通用能力毕竟模型输出永远有可能不遵守约定盲目反复重试只会放大成本。5.3 症状用户上传的简历内容过长token 撑爆简历长度超过模型上下文窗口时不要直接截断因为截断点很可能落在最关键的项目经历中间。更推荐的做法是“按优先级排序”先提取个人基本信息 最近经历 技能清单这部分必须完整保留再压缩其他部分只保留公司名、职位名、年份必要时对超长内容做摘要后再进入结构化提取。这个策略同样适用于评估和重写节点。合理控制 Context Window 的方法论是被验证有效的也很值得推广到所有 Agent 的 Prompt 设计里。5.4 测试方法用 LangGraph 的 debug 模式与单节测试最推荐的调试方式不是跑完整图而是先单节测试。在代码里把每个节点导出成纯函数写脚本直接调const result await extractStructuredNode({ rawText: pdfText, fileName: test.pdf }); console.log(result.structuredData);Graph 模式的问题在于一旦有错误很难定位是哪个节点出错。但如果你把每个节点都设计成可独立调用的纯函数这个痛苦直接减半。第二个技巧是开debug或trace模式LangGraph 的compile({ debug: true })会在图执行时打出每一步的状态与输入输出非常适合初学。6. 后续扩展方向与个人复盘6.1 代码可复用性的思考这次项目里最值得复用的是“Graph 纯函数节点”的架构思维。后续任何“多步骤、分支、状态共享、可回溯”的业务流程都可以用 LangGraph 这套思想重新建模。比如文章生成、多轮对话客服、审核流程、数据处理管道差别只在节点的抽取方式和 Prompt 设计上。6.2 多 Agent 协作的下一步当前的图是线性加分支还没到多 Agent 协作的程度。如果后续要扩展吕自然的方向是引入一个manager_agent调度者让它根据 JD 的复杂程度动态决定调用summary_agent还是rewrite_agent或者并行评估几份不同风格的简历再择优。LangGraph.js 的StateGraph对这种多 Agent 编排也完全能支持因为本质上图结构允许一个节点触发多个子图addNode里套 subgraph。但我也要泼一盆冷水多 Agent 意味着引入更多的延迟延迟不是所有场景都值得上。简历优化这种单轮为主、流程高度固定的场景用单 Agent 加图编排反而是最优解。多 Agent 更适合“自动化程度要求高、单智能体无法覆盖、需要多个工具协同”的场景。6.3 个人实际体感最后我聊聊真实感受。你要是让我用一个词说 LangGraph.js 的体验我会说可控。它让 Agent 的执行过程从“黑盒”变成了“白盒状态机”这在调试、维护、信任上带来的价值极大。对于刚开始接触 AI Agent 的开发者我的建议是不用上来就追最新的多 Agent 框架也别急着上向量数据库、记忆网络这一堆概念。先找一个具体问题定义清楚输入输出用 LangGraph 把流程编排出来把状态管理好把流式体验做好把一个真实可用的东西跑通——比积累一堆名词更有用。简历工具只是我选的载体这套方法论本身才是这次尝试真正的收获。
我去年年底到今年年初一直在捣鼓AI Agent相关的落地项目前后试了好几个技术栈最后用一个简历工具把 Next.js LangGraph.js 的组合完整跑通了。这篇文章不聊PPT架构也不画大饼就讲实际落地的技术选型、核心实现、部署排查以及我个人踩过的一堆坑。如果你也在纠结“AI Agent到底怎么接到真实业务里”这篇希望给你一些能直接抄作业的参考。1. 项目背景与整体设计思路1.1 为什么做简历工具而不是别的 Demo选简历工具作为 AI Agent 的落地场景是我反复比较后的结果。原因很简单第一简历解析和优化具备完整的多步骤工作流特征——从原始文本提取、结构化字段解析、匹配度评估到修改建议生成和最终重写每个环节都有独立的输入输出第二简历处理天然依赖“外部非结构化数据”和LLM推理的结合PDF/Word/DOCX 里提取出来的内容没法直接喂给模型必须做清洗和转换这给了 Agent 编排框架发挥空间第三这个场景的效果容易被用户感知改动前后的对比一目了然。1.2 技术选型LangGraph.js 为什么比纯 LangChain 链式调用更适合很多人入门 Agent 时用的是 LangChain 的LCEL链式调用写起来确实快几行代码就把“提取→总结→翻译”串起来了。但真实项目里很快会遇到几个坎分支逻辑怎么办失败重试怎么处理状态怎么在不同阶段共享和回滚用户在对话过程中改了需求整个流程怎么重新编排LangGraph.js 给我的核心价值是它把 Agent 执行过程抽象成了有状态图StateGraph节点Node代表一个执行步骤边Edge代表状态流转条件边Conditional Edge则让路由逻辑显式化。跟链式调用相比最大的区别是“流程可回溯、状态可共享、分支可控制”——这三个特性对简历工具这种长流程应用来说非常关键。举个例子用户上传一份简历后解析阶段可能成功也可能失败PDF 加密、扫描件 OCR 识别率过低等如果解析失败我们需要让用户重新上传而不是直接终止整个流程这在链式调用里很难优雅实现但在 Graph 里只需要为parse_node加一条条件路由失败时跳回collect_input节点等待新的输入整个过程非常自然。1.3 为什么选 Next.js 作为前端框架选 Next.js 有几个非常务实的理由。首先是API Routes 与流式响应Streaming的支持这是当前前端框架里最成熟、坑最少的一档。AI Agent 的响应时间普遍在 5-10 秒甚至更长如果像传统接口那样等全部生成完再返回用户的等待焦虑会非常明显。Next.js 的 Route Handlers 天然支持ReadableStream配合前端fetch的流式读取可以实现“首屏 token 秒出后续 token 陆续到达”的体验体感上比完整等待快太多了。其次是Server Actions和 API Routes 可以共用 Node.js 运行时直接复用 LangGraph.js 的代码逻辑不需要为前端做 BFF 层减少一层网络开销和类型维护成本。小团队单人开发时这种“一个项目内自闭环”的体验非常舒服。最后Next.js 对部署生态的支持太好了Vercel 上直接跑国外用户访问延迟低配合 Redis 做状态存储非常顺手。1.4 与“AI Agent 主流架构”的对位思考接触过 Agent 的人应该知道业内目前主流的 Agent 架构大致可以分成三类ReAct/Function-Calling Loop工具调用循环、Plan-and-Execute先计划再执行、以及 Graph Workflow图工作流。我刻意选择了 Graph Workflow 而不是 ReAct Loop。原因是简历工具的核心需求不是“让模型自己决定要调哪个工具”而是“让流程严格按照业务逻辑来走”——解析、提取、评估、重写这一步一步的顺序是一开始就确定的不需要模型发挥创造力去跳步。如果硬要用 ReAct Loop模型会在不必要的地方做多余决策增加 token 消耗和不可控的延迟。LangGraph.js 在这方面给出了一个特别优雅的抽象允许你在同一个 StateGraph 里混用确定性边和条件边。确定性边保证主流程的稳定条件边只在特定节点让模型做必要的决策比如是否需要继续追问。这样既保留了对业务的控制力又给模型留出了自由度。2. 核心系统架构与状态设计2.1 整体架构拆解整个系统从上层到下层可以拆成四个层次。最上层是 Next.js 前端页面App Router负责三个核心交互简历上传、文本编辑预览、Agent 工作流可视化调试用。中间层是 Next.js Route Handlers暴露两个端点一个处理简历上传multipart/form-data一个处理 Agent 工作流触发与流式响应POST JSON 或 SSE。再往下是 LangGraph.js 的核心执行引擎里面定义了ResumeGraph由 6 个节点组成每个节点是纯函数式逻辑负责一个明确的子任务。最底层是模型与基础服务gpt-4o-mini-2024-07-18后来换成了 gpt-4.1-mini文本拆分器Redis用于状态持久化和恢复以及 PDF 上传服务。这个分层跟很多前端项目完全不一样的地方在于核心业务逻辑不在前端、也不在传统意义上的后端 API 层里而在图编排引擎里。前端只负责展示与输入收集API 层只做协议转换与流式通道真正的决策、分支、循环都在 LangGraph 内部流转。2.2 工作流状态设计与类型定义LangGraph.js 的核心是状态对象。状态会随节点执行不断更新。我在项目里用 TypeScript 定义了ResumeStatetype ResumeState { rawText: string; // 原始文本从PDF/DOCX提取 fileName: string; // 上传文件名 fileType: string; // 文件类型 structuredData: ResumeSchema | null; // 结构化字段 jdText?: string; // 职位描述可选输入 matchingScore: number; // 匹配度 0-100 analysisReport?: AnalysisResult; // 评估报告 rewriteResult?: string; // 最终改写结果 };比较关键的设计是所有节点只通过 State 传递数据不自己维护私有状态。哪怕rewrite_node需要structuredData和analysisReport两个上游产出它也不直接从全局变量取而是从 State 里拿。这个约束让每个节点都能被单独测试——我们确实在开发期做了大量单点调试把原始文本喂到parse_node看看结构化提取效果再把parse_node输出喂进evaluate_node模拟 Agent 工作流里的数据传递。2.3 状态共享与上下文累积LLM 的 Agent 应用中状态共享和上下文累积是一对矛盾。如果所有历史信息都塞进上下文token 消耗会指数级增长如果只保留最终结果中间步骤的细节比如“JD 中要求熟悉 Kubernetes但简历里完全没提”就会丢失。解决方案是LangGraph.js 允许定义State的reducer控制状态更新方式。我写了一个简单的合并 reducer保证每次更新都追加到对应字段而不是覆盖同时只保留最近 N 轮信息。const stateReducer { analysisReport: (prev, next) next ?? prev, rewriteResult: (prev, next) next ?? prev, };这本质上跟“记忆管理”是同一个问题。小项目不需要引入专门向量库做长期记忆一个拷贝语义copy-with-merge加上字段级别的更新时机控制就够用了。不过如果后续做“多轮对话优化简历”就得考虑引入单独的记忆节点把每次优化建议固化到持久化存储里。2.4 图定义与执行流程LangGraph.js 的图定义代码并不复杂import { StateGraph, END } from langchain/langgraph; const workflow new StateGraph({ channels: stateReducer, }) .addNode(collect_input, collectInputNode) .addNode(parse_node, parseResumeNode) .addNode(extract_node, extractStructuredNode) .addNode(evaluate_node, evaluateResumeNode) .addNode(rewrite_node, rewriteResumeNode) .addNode(output_node, outputResultNode); workflow.addEdge(collect_input, parse_node); workflow.addConditionalEdges(parse_node, routeAfterParse, { success: extract_node, reparse: collect_input, fail: collect_input, }); workflow.addEdge(extract_node, evaluate_node); workflow.addEdge(evaluate_node, rewrite_node); workflow.addEdge(rewrite_node, output_node); workflow.addEdge(output_node, END); export const resumeGraph workflow.compile();一些细节说一下。collect_input是一个“入口节点”在这里接收用户上传的原始文本和可选的 JD 文本。它不触发 LLM只是一个数据汇聚层。一开始我没加这个节点直接让parse_node接收上传数据结果状态初始化出现的次数特别多加了一个显式集合节点后状态结构就清晰了。条件路由routeAfterParse里我返回的是字符串键LangGraph.js 会根据映射关系决定走哪条边。核心判断逻辑是如果文本提取结果为空会重试如果非空但解析置信度过低就建议重新上传只有结构完整才继续。LLM 调用节点在实现上遵循一套统一模式先从 State 里取数据、构造 Prompt、调用模型、后处理解析结果尤其是 JSON 解析容错必须做足再返回部分状态。这个模式写多了以后会发现Graph 开发跟传统后端开发的核心区别是你始终在描述状态如何从一个形态演化到另一个形态而不是在描述一个函数如何被调用。3. 核心实操LangGraph.js 节点实现与流式交互3.1 文档解析节点PDF/DOCX 提取的工程细节简历上传最常见的格式是 PDF其次是 DOCX。解析这块的难点不在调库而在异常处理。PDF 我用的是pdf-parse它对纯文本类 PDF 的提取效果很好。但有两类实际问题一是扫描件 PDF 完全没有文本层提取结果为空需要提示用户“该 PDF 可能是扫描件请转换为可复制文本的 PDF”二是 PDF 含加密锁需要密码才能打开pdf-parse会直接抛异常。所以我给parse_node写了多层防御先尝试提取文本文本过短则返回fail把这两个分支写成路由比在节点内部强行 OCR 要靠谱——OCR 服务比如 Tesseract对中文简历的识别率并没有到可接受的水平。DOCX 处理用的是mammoth它能把 Word 文档转成 HTML我再从 HTML 里剥离标签得到纯文本。这里踩过一个坑直接解析 DOCX 转换后的纯文本会把列表符号和缩进全部丢掉导致简历的结构信息丢失后面结构化提取效果大打折扣。我的做法是先从 HTML 里识别出ul、li、h1-h3等标签把它们转成 Markdown 风格的-和#再喂给 LLM。模型对 Markdown 的语义理解能力比对纯文本好很多。3.2 结构化信息提取节点这一节点非常重要因为后续评估和重写都依赖于结构化结果的一致性。这里有个选型问题是继续让 GPT-4o-mini 直接输出结构还是走 Function Calling我选了 Function CallingOpenAI Responses API / Chat Completions 的tools参数因为它能把输出强约束在 JSON Schema 范围内而不是靠 Prompt 加“请输出 JSON”。LangGraph.js 官方文档里也推荐在节点内调用模型时使用结构化输出来实现节点内部的任务约束。Schema 大致长这样const resumeSchema z.object({ personalInfo: z.object({ name: z.string().optional(), email: z.string().optional(), phone: z.string().optional(), }), education: z.array(z.object({ school: z.string(), major: z.string(), degree: z.string(), duration: z.string(), })), experience: z.array(z.object({ company: z.string(), position: z.string(), duration: z.string(), highlights: z.array(z.string()), })), skills: z.array(z.string()), });实际测试下来用zod做 schema 约束之后输出格式的稳定性有质的提升。之前纯 Prompt 解析时十次里有三四次 JSON 损坏或字段缺失换了 Function Calling 后基本很少再坏。唯一的遗憾是OpenAI 的gpt-4o-mini在这个场景下不能保证 100% 遵守函数调用约定偶尔会出现把函数调用说明文本混入输出的情况所以我额外加了一层“尝试解析 JSON → 失败则用正则兜底 → 再失败则要求模型只输出 JSON”的重试逻辑这个兜底逻辑在部署后救了不少次。3.3 评估节点与命中率计算评估节点的输入是全量结构化数据和可选的 JD。核心任务是生成匹配度分数和结构化评估报告。Prompt 里我加了一个关键技巧要求模型必须逐条输出“JD 要求”和“简历内容”的对照矩阵而不是直接给一个分数。这个对照过程会强制模型逐项核对准确率比直接打分高很多而且生成的评估报告用户能打印出来自己对照信任感强。匹配分数我用的是 0-100 整数制。算分数的 Prompt 写法是你是资深技术面试官。请根据简历内容与 Job Description 的匹配程度打分。打分依据 - 技术栈重合度40% - 业务领域重合度30% - 职级匹配度20% - 项目复杂度匹配度10% 请先输出逐项依据再输出 score、strengths、weaknesses、suggestions 四个字段的 JSON。这种带权重的 Prompt 设计比“给个星”更稳定。实际测试中分数分布比不带权重的版本更合理不会出现大家都 80 分以上的通胀局面。3.4 重写节点与代码宏控制在实战中的作用重写节点的 Prompt 设计核心是“让简历更适合目标 JD”。我试过好几个方案最好用的方法是提供重写模板再要求模型在约束范围内重写。模板的核心策略是量化优先要求将“负责XX系统”改写为“主导XX系统的设计与落地日请求量 1w可用性 99.95%”这类可验证的表达动词强化使用 developed、designed、led 等强动作动词避免“参与、协助、了解”这类弱词语与 JD 对齐要求模型将 JD 中明确出现的核心名词技术栈、业务关键词自然嵌入重写后的描述但不能造假。还有个 token 控制的经验。重写时如果直接把整个 PDF 解析出来的长文本约 3000-4000 token加 JD 全量塞给 LLM很容易突破 gpt-4o-mini 的上下文窗口。我的做法是按“最近 2 份工作经历 项目经历 技能清单”来切片先指导模型重写最相关的部分其他部分优先保持原样这样既节省 token也能让修改建议更聚焦。毕竟简历优化的核心诉求是“针对目标 JD 调整”而不是从头通篇重写。3.5 前后流式交互从 LangGraph 到浏览器LangGraph.js 支持流式返回节点级事件。我这里用的是.stream()加自己封装 EventSource 的方式——后端 Route Handler 大致逻辑export async function POST(req: Request) { const body await req.json(); const config { configurable: { thread_id: body.threadId } }; const stream await resumeGraph.stream( { rawText: body.rawText, jdText: body.jdText }, { ...config, streamMode: updates } ); // 转成 SSE const encoder new TextEncoder(); const readable new ReadableStream({ async start(controller) { for await (const event of stream) { const chunk data: ${JSON.stringify(event)}\n\n; controller.enqueue(encoder.encode(chunk)); } controller.close(); }, }); return new Response(readable, { headers: { Content-Type: text/event-stream, Cache-Control: no-cache, Connection: keep-alive, }, }); }配置里thread_id这一项值得单独说说。它是 LangGraph 的会话标识符同一thread_id的所有交互会共享同一个状态。这个字段对长对话流程非常重要——如果用户中途修改了 JDAgent 需要基于原有状态继续更新而不是从零开始。在 Vercel 这种 serverless 环境下checkpointer需要外部存储来做持久化我选择了 InMemorySaver 以外最简单的方案用 Redis 自实现一个 CheckpointSaver 接口因为 InMemorySaver 在 serverless 上完全不可用每个实例的内存都是隔离的。前端接收流的逻辑比较简单const response await fetch(/api/agent, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify(params), }); const reader response.body.getReader(); const decoder new TextDecoder(); while (true) { const { value, done } await reader.read(); if (done) break; const text decoder.decode(value); // 解析 SSE 数据按节点名更新 UI 状态 }前端 UI 建议用事件溯源模式来做——每收到一个节点完成事件就更新一次 UI 状态解析中、提取中、评估中、重写中。这样用户在等待时也心里有数不至于以为页面卡死了。这里一个小细节是React 组件里如果直接对 stream 做循环更新因为并发更新会互相覆盖需要用useReducer或者把更新动作传入flushSync否则会出现 UI 显示状态和实际进度错位的问题。3.6 在 Next.js 中配置模型密钥与环境服务端模型调用密钥统一从环境变量读取OPENAI_API_KEY。开发环境再用.env.local管理。有个部署时容易踩坑的地方是在.env.local里的变量在 Vercel 部署后会失效必须在项目后台的 Environment Variables 里重新配置。另外 prevention of SSRF 或者密钥泄露全靠服务端 API Route 代理模型调用绝对不要在前端直接掉 openai不然密钥直接暴露在浏览器源码里这是安全红线。4. 部署与评测实际运行效果与成本4.1 部署到 Vercel 的踩坑记录与解决我先说结果直接在 Vercel 上用 Node.js runtime而非 Edge Runtime运行 LangGraph.js 是可行的但有几个配置需要注意。第一个坑是 Next.js 的默认运行时。当你在 API Route 里export const runtime nodejs时没有问题但如果某个页面不小心启用了 Edge Runtime比如自动推断LangGraph 的一些依赖在 Edge 上会直接报错。建议所有涉及 Graph 执行的 Route Handler 都在顶部显式声明 Node.js runtime不要依赖自动推断。第二个坑是压缩层对 SSE 的影响。Vercel 的压缩和代理有时候会缓冲流式响应导致前端收到的不是实时的逐 token 事件而是一大段数据一次性到达。怎么排查看 Network 面板里响应是不是 chunked transfer如果显示(pending)资源一直不返回再把前端fetch的 cache 设置为no-store试试。另外也可以改成 WebSocket 推送但这里有一点复杂常规的 SSE 已经能达到不错的体验。第三个坑与冷启动有关。Graph 定义是静态的首次调用会做图编译、schema 校验、依赖加载冷启动耗时经常达到 3-4 秒。我的缓解方案有两个一是把 Graph 实例做模块级缓存globalThis上避免 next dev 热更新时重复创建二是给 Vercel 函数增加maxDuration到 60 秒否则超时时间默认 10 秒连冷启动都无法完成。需要注意maxDuration在 hobby 计划里可能不生效要 upgrade 到 Pro 才能用更长的执行时长。4.2 内部评测集的构建方式为了让 Agent 的改动有据可循我建了一个小规模的评测集——5 份真实脱敏简历加 3 条不同方向的 JD。每次修改 Prompt 或图结构后跑一遍评测集看三个指标字段提取准确率人工核对 30 个核心字段的提取是否完整、正确。匹配分数的稳定性对同一份简历跑 5 次看分数方差是否过大。改写有效比例改写后的简历是否保留了原有的量化成果比如不要随意捏造数据是否合理嵌入 JD 关键词是否破坏了原格式。这个评测集的价值非常大。有一次我调整了评估节点的 Prompt结果分数提高了 8 分左右但人工检查发现是因为模型“迎合”JD 做了虚高打分而不是真实匹配度上升——评测集立刻暴露了这个问题Prompt 方向也就立刻回滚了。4.3 token 成本估算用 gpt-4o-mini 跑完整流程的总 token 消耗大约是解析提取 3-4k评估 2-3k重写 4-5k合计平均 10k token 上下。按官方价格估算每次完整操作成本约 0.003-0.004 美元。一个月 1000 次使用也才几美元成本完全可以接受。但有个容易忽视的隐藏成本失败重跑。解析失败、JSON 解析重试、用户取消任务等场景下 token 照样消耗。有一次我在调试 parse 失败重试逻辑发现每次失败分支都会重新调用一遍模型导致成本翻倍。后来加了一个“最多重试 2 次”的限制同时在第一次失败时直接返回错误提示而不是让模型进行二次猜测这才把失败场景的成本降下来。4.4 无头浏览器生成 PDF 输出的实现细节用户改完简历后自然希望导出 PDF。前端直接用浏览器打印最简便但为了稳定输出和自定义样式我用 Puppeteer 在服务端做了一次 HTML 到 PDF 的转换。这里有一个合作上的教训Puppeteer 在 Vercel 上没有预装 Chrome 浏览器需要借助chrome-aws-lambda和puppeteer-core来加载他打好的二进制包同时要把 Vercel 函数的 maxDuration 提得很高。此外函数的 bundle 大小会超过 Vercel 默认 250MB 的限制要把 Chrome 的二进制文件放入public目录并给定特殊后缀然后在运行时加载。这个环节是整个系统里最麻烦的部分如果后续能改成提供 HTML/Markdown 导出而不是强行生成 PDF成本和维护量会大幅下降。5. 常见问题与排查技巧实录5.1 症状响应挂起长时间无流式输出这个现象在部署早期出现得特别多。排查路径是先看 Vercel 函数日志再看是不是冷启动超时通过浏览器 Network 面板可以明显看到请求一直 pending再确认是否 Node.js runtime 被某个依赖偷偷切到 Edge最后看模型 API 是否因为超时或限流在等待。一个很有用的技巧是给 Route Handler 加一个“性能埋点”在 Graphstart和end时分别打印耗时再在日志平台聚合。我加了之后发现最容易超时的节点是rewrite_node原因是它对全量 State 做了一个深度拷贝而ResumeState里包含很多的字符串数组拷贝耗时拉高了整个图执行时间。后来改成只拷贝不想变的字段引用问题立刻消失了。5.2 症状JSON 解析失败或字段缺失结构化提取的阶段出问题最多尤其是用户的简历包含大量非标准格式比如用表格排版、两栏布局、中英混杂。总结下来有三个措施提取后给 LLM 附上文本增强的上下文说明让模型保留要点提高temperature到 0.1 以下输出确定性会大幅提升用函数调用约束 schema已说并实现“先严格校验 Schema → 校验失败 → 自动降级解析只提取文本中的关键字段”的多级防线。最后这条降级逻辑很推荐做成通用能力毕竟模型输出永远有可能不遵守约定盲目反复重试只会放大成本。5.3 症状用户上传的简历内容过长token 撑爆简历长度超过模型上下文窗口时不要直接截断因为截断点很可能落在最关键的项目经历中间。更推荐的做法是“按优先级排序”先提取个人基本信息 最近经历 技能清单这部分必须完整保留再压缩其他部分只保留公司名、职位名、年份必要时对超长内容做摘要后再进入结构化提取。这个策略同样适用于评估和重写节点。合理控制 Context Window 的方法论是被验证有效的也很值得推广到所有 Agent 的 Prompt 设计里。5.4 测试方法用 LangGraph 的 debug 模式与单节测试最推荐的调试方式不是跑完整图而是先单节测试。在代码里把每个节点导出成纯函数写脚本直接调const result await extractStructuredNode({ rawText: pdfText, fileName: test.pdf }); console.log(result.structuredData);Graph 模式的问题在于一旦有错误很难定位是哪个节点出错。但如果你把每个节点都设计成可独立调用的纯函数这个痛苦直接减半。第二个技巧是开debug或trace模式LangGraph 的compile({ debug: true })会在图执行时打出每一步的状态与输入输出非常适合初学。6. 后续扩展方向与个人复盘6.1 代码可复用性的思考这次项目里最值得复用的是“Graph 纯函数节点”的架构思维。后续任何“多步骤、分支、状态共享、可回溯”的业务流程都可以用 LangGraph 这套思想重新建模。比如文章生成、多轮对话客服、审核流程、数据处理管道差别只在节点的抽取方式和 Prompt 设计上。6.2 多 Agent 协作的下一步当前的图是线性加分支还没到多 Agent 协作的程度。如果后续要扩展吕自然的方向是引入一个manager_agent调度者让它根据 JD 的复杂程度动态决定调用summary_agent还是rewrite_agent或者并行评估几份不同风格的简历再择优。LangGraph.js 的StateGraph对这种多 Agent 编排也完全能支持因为本质上图结构允许一个节点触发多个子图addNode里套 subgraph。但我也要泼一盆冷水多 Agent 意味着引入更多的延迟延迟不是所有场景都值得上。简历优化这种单轮为主、流程高度固定的场景用单 Agent 加图编排反而是最优解。多 Agent 更适合“自动化程度要求高、单智能体无法覆盖、需要多个工具协同”的场景。6.3 个人实际体感最后我聊聊真实感受。你要是让我用一个词说 LangGraph.js 的体验我会说可控。它让 Agent 的执行过程从“黑盒”变成了“白盒状态机”这在调试、维护、信任上带来的价值极大。对于刚开始接触 AI Agent 的开发者我的建议是不用上来就追最新的多 Agent 框架也别急着上向量数据库、记忆网络这一堆概念。先找一个具体问题定义清楚输入输出用 LangGraph 把流程编排出来把状态管理好把流式体验做好把一个真实可用的东西跑通——比积累一堆名词更有用。简历工具只是我选的载体这套方法论本身才是这次尝试真正的收获。
+New API+OpenWebUI 并接入 TaoToken 统一 Key)
