基于Jev与Vercel AI Gateway的简历智能匹配系统实践

上个月我接了个有点尴尬的内部需求HR 那边要处理几百份简历按岗位 JD 做一轮智能初筛输出的不能只是“匹配/不匹配”还得有可解释的评分、匹配点和风险点。我一开始想拿关键词匹配糊弄过去结果一测就被打脸——简历写“熟悉 TensorFlow”JD 写“有深度学习框架使用经验”关键词算法直接判不匹配。换成语义理解之后我把 Jev 模型接进来做判断再用 Vercel AI Gateway 做统一接入、缓存和限流这套简历匹配流程才算真正跑通。这篇文章就把整个方案的思路、代码和踩坑记录完整复盘一遍。这套东西适合谁看如果你正在做招聘系统、简历筛选工具或者任何“让大模型批量读文档然后输出结构化结论”的任务都可以直接参考。Jev 负责语义判断Vercel AI Gateway 负责把模型接入这件事变得可控两者组合之后简历匹配从“玩具”变成了能上生产的工具。1. 项目背景简历匹配为什么不能靠关键词很多人第一次做简历匹配第一反应就是“分词 关键词打分”。这个思路在简历量小、岗位描述高度模板化的时候勉强能用但真实场景里处处是坑。1.1 简历匹配的“反直觉”难点第一个难点是语义等价。JD 写“熟悉容器化部署”简历写“用过 Docker Compose 和 K8s”关键词匹配会把这两个句子当成完全不相关的内容。第二个难点是信息缺失和模糊表达简历经常不写时间、不写项目规模只有一句“负责系统优化”没有上下文根本没法判断这个“优化”是改了个配置还是重构了架构。第三个难点是量化HR 想要的是“这个人到底合不合适”的判断而不是一堆关键词命中率数字。这些问题恰好是大语言模型的强项。Jev 这类模型能理解同义表达能根据上下文补全缺失信息的推断更重要的是能输出结构化的 JSON方便后续直接存库、排序、展示。我试过几轮后确认把“语义判断”交给模型把“规则判断”留给代码才是这套方案最合理的分工。1.2 Jev 模型在项目里的位置Jev 是这个方案里的“大脑”。它负责三件事读懂 JD 里的硬性要求和加分项读懂简历里的技能、项目经验和岗位经历最后输出一份结构化的匹配评估。我选用它不是因为它在某个榜单上有多靠前而是实测下来它的中文指令跟随和 JSON 输出稳定性都不错。简历匹配这种任务不需要模型有太强的创造性但要求它“听话”——让它按指定 schema 输出就别在前面加一堆解释文字。Jev 在这一点的表现符合预期。另外很多人关心的“Jev 模型开源吗”这个问题坦白说我用的是 API 服务模型是否开源并不影响下面的接入流程。你只需要有一个可用的 API 密钥剩下的调用方式和 OpenAI 兼容接口基本一致。这也是为什么它能顺利接进 Vercel AI Gateway。1.3 Vercel AI Gateway 在项目里的角色Vercel AI Gateway 是个云上 AI 网关服务它把各家模型统一成一个 OpenAI 兼容的入口。你在代码里只需要面对一个 endpoint它可以帮你转发到 Jev、OpenAI、Anthropic 或者其他模型同时提供缓存、限流、降级、可观测性这些能力。在我的方案里网关解决的是“生产可用”问题。没有网关时直接调模型 API 会碰到三件麻烦事一是服务不稳定模型偶发 5xx 错误就得自己写重试二是重复请求多同一份 JD 配五十份简历JD 部分每次都重新计费三是出了线上问题没有日志和指标不知道是模型超时还是限流。这些网关基本都能覆盖而且接入成本很低。2. 技术方案选型为什么是“LLM 网关”而不是其他简历匹配这条路业界其实有好几种走法。我在动手前把主流方案都过了一遍各有适用场景但在这个需求下LLM 配合网关是最合适的选择。2.1 三条技术路线的对比我把关键词匹配、向量检索、LLM 结构化评估做了个对比直接看表就行方案召回能力语义理解可解释性成本实现复杂度关键词/规则匹配差无高极低低向量检索Embedding 余弦相似度中中低低中LLM 结构化评估本项目方案高高高中中关键词匹配问题最大的是召回太差同义表达直接漏掉。向量检索比关键词好很多但它只能回答“相似”不能回答“合不合适”而且需要你调相似度阈值行业经验不足的时候阈值很难拍。LLM 结构化评估的优势在于能直接产出多维评分、优缺点列表、面试建议这是 HR 真正想要的东西。缺点是单次调用成本比前两者高响应时间也长。我的做法是让 LLM 做主评估同时配合网关缓存来摊薄成本后面第 7 节会算这笔账。2.2 网关带来哪些具体收益网关在这套方案里有几个实打实的收益不是锦上添花。第一是模型可替换。今天用 Jev明天想切到别的模型代码不用动只改一个模型名和密钥。网关天然支持多模型方便你做 A/B 对比也方便某个模型抽风时快速切换。第二是缓存。网关的语义缓存能把“相同或相近的请求”直接命中缓存不重复调用模型。简历匹配场景里一份 JD 要匹配几十份简历JD 部分几乎完全一样缓存命中率相当可观。我实测下来缓存能让总成本下降三成到五成这个收益非常直接。第三是限流和降级。批量跑简历时如果并发开太快模型服务商很容易返回 429。网关能统一做速率控制还可以配置 fallback 模型主模型挂了自动降级到备用模型不至于整个批处理任务中断。2.3 整体数据流设计整个流程我拆成了五步每一步的输入输出都很明确用户上传简历文件PDF 或 DOCX前端把文件发到 API 路由。后端解析简历文件提取纯文本去除非必要格式。拼接 JD 和简历文本构造评估 Prompt调用 Vercel AI Gateway。网关转发请求到 Jev 模型拿到 JSON 结果。代码解析 JSON做字段校验和评分计算返回前端展示。这个数据流里真正属于“模型业务逻辑”的只有第 3、4 步其余都是工程代码。这样做的好处是职责清晰模型只负责语义评估文件解析、并发控制、结果校验都由确定性的代码完成出了问题容易定位。3. 环境准备与 Gateway 接入新手可直接抄这一节我尽量写细一些从初始化项目到验证连通性照着做基本不会卡壳。3.1 初始化项目与依赖我用的是 Next.js App Router因为项目本身要部署在 Vercel 上和网关同生态体验最顺。创建一个新项目npx create-next-applatest resume-matcher进入目录后安装这次要用的依赖npm install openai pdf-parse mammoth注意默认情况下 pdf-parse 需要一个测试文件装完建议确认一下版本。mammoth 负责解析 DOCX 文件pdf-parse 负责解析 PDF。如果你们内部简历大多是扫描件这步会变成 OCR 方案第 5 节会讲。3.2 拿到 Jev 密钥并配置环境变量很多人搜“Jev 密钥”其实就是卡在第一步。操作路径很简单去 Jev 官网注册账号进入模型控制台或 API 管理页面创建一个 API Key复制保存。这个 Key 的权限粒度和有效期以你开通的服务为准建议只在服务端环境变量里保存不要写进前端代码。项目根目录创建.env.localJEV_API_KEY你的密钥 GATEWAY_BASE_URLhttps://gateway.vercel.ai/v1 MATCH_MODELjev/jev-chatMATCH_MODEL这个变量是你要调用的模型 ID。我写的jev/jev-chat是示例实际以你在网关里能看到的模型列表为准。如果你在网关列表里找不到 Jev大概率需要在网关控制台把它配置成自定义的 OpenAI 兼容端点并绑定你的 Jev 密钥这一步各家控制台入口不同按官方文档走即可。3.3 把 Gateway 接进代码两种方式第一种方式如果你只是想把请求转发到 Jev不在乎网关特有的缓存、限流这些能力直接用 OpenAI SDK 改 baseURL 就行import OpenAI from openai; const gateway new OpenAI({ apiKey: process.env.JEV_API_KEY, baseURL: process.env.GATEWAY_BASE_URL ?? https://gateway.vercel.ai/v1, timeout: 60_000, });这样就能像调用 OpenAI 一样调用网关模型名写jev/jev-chat。胜在简单缺点是网关的高级能力缓存、fallback 等需要额外配置请求头SDK 里每次设置比较麻烦。第二种方式直接用原生 fetch把网关能力完全打开。我的生产代码用的是这种因为简历匹配这个场景太需要缓存和降级了。核心代码如下// lib/gateway.ts export interface MatchRequest { jobDesc: string; resumeText: string; useCache?: boolean; } export async function matchResume({ jobDesc, resumeText, useCache true }: MatchRequest) { const headers: Recordstring, string { Content-Type: application/json, Authorization: Bearer ${process.env.JEV_API_KEY}, x-vercel-ai-gateway-model: process.env.MATCH_MODEL ?? jev/jev-chat, }; if (useCache) { headers[x-vercel-ai-gateway-cache] JSON.stringify({ type: semantic }); } const res await fetch(https://gateway.vercel.ai/v1/chat/completions, { method: POST, headers, body: JSON.stringify({ model: process.env.MATCH_MODEL ?? jev/jev-chat, temperature: 0.2, response_format: { type: json_object }, messages: [ { role: system, content: SYSTEM_PROMPT }, { role: user, content: buildUserPrompt(jobDesc, resumeText) }, ], }), }); if (!res.ok) { const text await res.text(); throw new Error(Gateway request failed: ${res.status} ${text}); } const data await res.json(); const content data.choices?.[0]?.message?.content; if (!content) { throw new Error(Empty completion); } return JSON.parse(content); }这段代码里有三个关键点。第一x-vercel-ai-gateway-model请求头指定了要路由到的真实模型第二x-vercel-ai-gateway-cache开启了语义缓存第三response_format要求模型输出 JSON 对象。如果 Jev 这条链路不支持 JSON 模式把response_format去掉也能跑只是解析端要做容错第 6 节会讲。3.4 验证连接与查看模型列表代码写完先别急着跑业务先验证连通性。最快的办法是拉一遍网关的模型列表curl -H Authorization: Bearer $JEV_API_KEY \ https://gateway.vercel.ai/v1/models返回列表之后确认你要用的模型 ID把它填进.env.local的MATCH_MODEL。如果列表里没有 Jev多半是它还没被配成网关的自定义模型回到控制台检查一下。再跑一个最小请求验证整体链路curl https://gateway.vercel.ai/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $JEV_API_KEY \ -d { model: jev/jev-chat, messages: [{role: user, content: 只回复两个字正常}] }能正常返回文字说明 Jev 的密钥、网关路由、模型 ID 都没问题可以进入下一步写业务逻辑。4. 核心环节简历匹配的 Prompt 与结构化输出接入模型只是开始真正决定匹配质量的是 Prompt 设计和输出 Schema。我在这块迭代了好几版把关键思路拆开讲。4.1 输出 Schema 设计思路我先定义了一份 JSON Schema让模型严格按这个结构输出{ overall_score: 78, dimensions: { technical_match: 82, experience_relevance: 75, project_quality: 70, team_fit: 60 }, strengths: [擅长 Vue3 组件化开发, 有 4 年前端工程化经验], gaps: [JD 要求 Node.js 后端能力简历未体现, 缺少性能优化方向的项目案例], recommendation: yes, suggested_questions: [请描述一次你主导的前端性能优化过程, 是否独立设计过 Node.js 服务端接口] }这份 Schema 的设计有几个用意。overall_score是总分但我不让模型直接自由发挥而是在 Prompt 里给出明确的加权规则技能匹配度占 40%、经验相关性占 30%、项目质量占 20%、契合度占 10%。recommendation用枚举值避免模型输出模棱两可的“建议考虑一下”。suggested_questions是给 HR 的增值内容面试官可以直接拿这些问题去追问候选人。注意字段名我用英文而不是中文JSON 键名用英文能避免编码问题值用中文不影响。模型一般更擅长处理英文键名解析时也省心。4.2 System Prompt 与 User Prompt 的写法我的 System Prompt 只强调两件事角色定位和诚实原则。不要给模型堆砌太多要求核心限制放到 User Prompt 里因为它是每次请求都会变的。export const SYSTEM_PROMPT 你是一位有 10 年经验的技术招聘顾问负责为企业筛选候选人简历。 你的原则是从简历真实信息出发不脑补。 当简历缺少判断所必需的信息时请在对应字段中说明而不是自行编造。; export function buildUserPrompt(jobDesc: string, resumeText: string) { return 请评估候选人简历与职位描述的匹配程度严格按 JSON 输出。 ## 职位描述JD ${jobDesc} ## 候选人简历 ${resumeText} ## 评分规则 - overall_score 为 0-100 整数按以下权重计算 技能匹配度 40%、经验相关性 30%、项目质量 20%、团队契合度 10%。 - 如果 JD 中有硬性要求如“必须精通 Vue3”简历完全未体现overall_score 不得超过 60。 - recommendation 只能是 strong_yes、yes、hold、no 之一。 - strengths、gaps、suggested_questions 各写 2 到 4 条每条不超过 30 个字。 ## 输出格式 直接输出 JSON不要包含 markdown 代码块标记不要输出任何解释文字 { overall_score: 0, dimensions: { technical_match: 0, experience_relevance: 0, project_quality: 0, team_fit: 0 }, strengths: [], gaps: [], recommendation: yes, suggested_questions: [] }; }这里有个重要的细节“硬性要求缺失时总分不得超过 60”。我踩过坑才发现如果不加这条硬约束模型经常会给出一个不痛不痒的 70 分但 HR 一看 JD 里明确写了“必须会 X”候选人完全不会这种人就该直接过滤掉。把这种规则写进 Prompt比事后写代码判断要简单得多因为“简历是否体现能力”是模型一眼能判断的事。4.3 温度、JSON 模式与稳定性的取舍温度我固定为 0.2偶尔用 0。简历匹配是判断类任务不需要模型发挥创意温度越高越容易在不同轮次给出不一致的分数。同样一份简历同一份 JD如果连续调用两次结果差 20 分说明温度太高或者 Prompt 太模糊先降温度再查 Prompt。JSON 模式方面我在代码里开了response_format: { type: json_object }这能大大降低输出额外文字的概率。但千万不要完全依赖它因为网关链路上的模型服务商不一定都完整支持。我的解析函数里做了一层容错把内容里的 markdown 代码块标记剥掉再尝试提取第一个{到最后一个}之间的子串最后才JSON.parse。export function parseJsonContent(content: string): unknown { const trimmed content.trim(); try { return JSON.parse(trimmed); } catch { const start trimmed.indexOf({); const end trimmed.lastIndexOf(}); if (start ! -1 end start) { return JSON.parse(trimmed.slice(start, end 1)); } throw new Error(无法解析模型输出: ${trimmed.slice(0, 200)}); } }输出 Schema 里如果有字段缺失我还会在解析后做一个校验缺哪个字段就把整体标为“解析异常”让这批简历走人工复核而不是直接报错中断整个批处理。5. 完整实操从简历 PDF 到匹配报告基础能力和 Prompt 都准备好了这节是把整套流程串起来的完整实操从文件上传到前端展示评分卡。5.1 简历文本提取PDF / DOCX简历文件的解析是第一步也是最容易翻车的一步。我用的方案// lib/resume-parser.ts import pdfParse from pdf-parse; import mammoth from mammoth; export async function parseResume(file: Buffer, filename: string): Promisestring { const ext filename.split(.).pop()?.toLowerCase(); if (ext pdf) { const result await pdfParse(file); return result.text; } if (ext docx) { const result await mammoth.extractRawText({ buffer: file }); return result.value; } throw new Error(暂不支持的文件类型: ${ext}); }需要提醒的是很多“PDF 简历”其实是扫描图片或者导出时没有保留文字层pdf-parse提取出来是空字符串。这种情况只能走 OCR。我第二版迭代时接入了 OCR 方案把扫描版 PDF 先转成图片再用 OCR 引擎识别文字。OCR 的识别质量会直接影响匹配结果乱码文本被模型当成了能力描述这事我见过不止一次。如果你的场景里有大量扫描件记得把 OCR 准确率纳入整体评估。5.2 API 路由与批量并发控制提取完文本之后调用匹配函数。我写了一个标准的 Next.js API 路由// app/api/match/route.ts import { NextRequest, NextResponse } from next/server; import { matchResume } from /lib/gateway; export const runtime nodejs; export async function POST(req: NextRequest) { try { const body await req.json(); const { jobDesc, resumeText } body; if (!jobDesc?.trim() || !resumeText?.trim()) { return NextResponse.json({ ok: false, error: 参数缺失 }, { status: 400 }); } const result await matchResume({ jobDesc, resumeText }); return NextResponse.json({ ok: true, data: result }); } catch (error) { console.error([match], error); return NextResponse.json({ ok: false, error: (error as Error).message }, { status: 500 }); } }批量匹配时我强烈建议加一个并发控制不要一次性把所有简历都丢出去。模型 API 的并发限制比你想象中低100 份简历同时请求一半会返回 429。我写了一个简单的并发限制器// lib/batch.ts export async function runWithConcurrencyT( items: T[], worker: (item: T) Promiseunknown, limit 3 ): Promisevoid { const queue [...items]; const workers Array.from({ length: Math.min(limit, queue.length) }, async () { while (queue.length 0) { const item queue.shift(); if (item) { await worker(item); } } }); await Promise.all(workers); }并发数我一般设 3 到 5具体看模型侧的速率限制。宁可慢一点也不要把任务跑挂。跑批的时候在日志里记录每份简历的状态码和耗时方便事后分析哪一批触发了限流。5.3 结果解析与前端展示含评分卡示例前端部分不需要多复杂一个上传按钮加一个结果列表就行。核心请求逻辑const resp await fetch(/api/match, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ jobDesc, resumeText }), }); const { ok, data, error } await resp.json(); if (ok) { // data 就是完整的 JSON 评估结果 renderScoreCard(data); } else { console.error(error); }渲染评分卡时我用总分做主视觉四个维度做条形图或雷达图strengths和gaps做成两列列表recommendation做成明显的标签。HR 最关心的其实是“为什么给这个分”所以gaps列表一定要展示得足够显眼。有一次我直接把模型返回的 JSON 表格渲染给 HR 看她问的第一句话是“为什么这里写了‘简历未体现 Node.js 经验’”这就是可解释性的价值。有了gaps字段HR 能直接看到判断依据而不是对着一个莫名奇妙的 78 分发呆。6. 常见问题与排查技巧踩坑实录这套方案跑了两周遇到的坑不少我把高频问题整理成一份速查表每一条都是实际遇到过并且排查过的。6.1 请求失败的几种典型报错现象常见原因处理办法429 Too Many Requests触发模型服务商或网关速率限制降低并发数检查是否命中限流策略适当加重试退避400 invalid model模型 ID 写错或未被网关识别调用/v1/models拉取真实 ID 列表确认自定义模型已配置401 UnauthorizedJev 密钥错误或已过期检查密钥前后是否有空格到控制台重新生成408 / 504 超时简历文本过长模型生成时间太久截断简历或缩短输出条数客户端超时时间放宽到 60 秒以上解析 JSON 报错模型输出带了解释文字或代码块标记用容错解析函数Prompt 强制“不要输出解释”必要时关闭 JSON 模式最让我头疼的是 429。第一次批量跑 80 份简历并发设了 10结果跑了不到三十份就全线飘红。后来我把并发降到 3同时在 catch 里做了指数退避重试情况才稳定下来。重试代码不长但一定要有async function callWithRetry(fn: () Promiseunknown, maxRetries 3) { for (let i 0; i maxRetries; i) { try { return await fn(); } catch (err) { const status (err as { status?: number }).status; if (status status 500 status ! 429) { throw err; // 参数错误之类的问题重试没用 } await new Promise((resolve) setTimeout(resolve, 500 * 2 ** i)); } } throw new Error(重试后仍然失败); }6.2 匹配质量不稳定的排查思路如果两份条件差不多的简历评分却差很远先别怀疑模型“不聪明”大概率是输入的问题。我总结的排查顺序是先检查简历文本有没有截断再检查 Prompt 里的 JD 有没有被简历文本覆盖最后再降温度做验证。简历文本被截断是常见原因。有些简历特别长超过了模型的上下文窗口我做了按字数截断但截断位置很讲究。只保留最近两份工作经历通常比保留所有内容效果好因为招聘匹配更看重最近的经验。另外JD 和简历拼接时我会在中间加明确的分隔标记避免模型把两份文本混在一起读。还有一个细节文件名和附加说明不要拼进 Prompt。有一次我在简历后面追加了一句“候选人来自内推”模型居然在评估理由里写“内推背景建议优先考虑”这明显是噪声。所有与能力无关的信息都不要进模型的输入。6.3 缓存与限流的真实效果语义缓存开启之后我观察到的现象是同一份 JD 批量匹配时从第 3 份简历开始响应时间明显下降部分请求直接走了缓存。但也不要无脑开缓存我发现语义缓存偶尔会把两份“看起来差不多但实际关键技能不同”的简历判成同一类导致结果串味。后来我调整了策略普通批量任务开启语义缓存因为大部分简历都是常规写法对于内部标注“高优岗位”或者 JD 特殊度很高的场景关闭缓存保证每次都是新鲜推理。这个开关在matchResume函数里用useCache参数控制成本多花一点但准确率更稳。还有一个经验缓存要设置合理的 TTL。JD 可能随时更新如果缓存时间太长改完 JD 后还在用旧结果HR 就懵了。我用的是一天左右的 TTL具体字段格式以网关官方文档为准。7. 成本、隐私与后续扩展方案跑通之后接着要面对的是钱和安全。这两件事在个人项目里可以忽视上生产系统时绝对不能。7.1 成本估算与缓存省钱策略先算一笔账。假设一份 JD 大约 1500 字简历大约 3000 字加上 Prompt 模板单次请求的输入 token 大概在 5000 左右输出 JSON 大约 600 token。按一个假设的模型单价输入 2 元/百万 token输出 8 元/百万 token单次匹配成本大约是输入5000 ÷ 1000000 × 2 0.01 元输出600 ÷ 1000000 × 8 0.0048 元合计约 0.015 元/份一千份简历跑下来模型调用成本大约十五元。这个数字在模型单价波动时会变但量级很清楚单份成本非常低瓶颈从来不是模型费用而是你自己的工程能力和限流控制。缓存能让这个数字再降三到五成。因为同一份 JD 匹配多份简历时JD 部分几乎不变语义缓存命中后直接跳过模型推理。我建议把你最常跑的 JD 做成预热的缓存先把 JD 单独跑一次再开始批量匹配命中率会更高。7.2 简历敏感信息处理简历里全是个人信息姓名、电话、邮箱、教育经历甚至身份证号。这些数据送进模型服务商之前必须做脱敏。我的做法是在解析完简历文本后先做一轮 PII 替换。把手机号、邮箱、身份证号替换成占位符姓名在匹配阶段也用“候选人”代替。匹配本身根本不需要知道候选人是谁HR 是在看结果列表时才需要对应到人。脱敏后再送模型既能降低数据泄露影响也能避免模型把“某公司”之类信息当能力信号读进去。日志也要管住。我不会把完整的 Prompt 打印到日志里只记录请求 ID、耗时、状态码和模型返回的 JSON 长度。一旦出问题需要排查再通过请求 ID 去网关侧查详细链路。7.3 还能怎么扩展这套“网关 模型 结构化输出”的模式跑通之后扩展方向非常明确。我可以直接复用同一套网关接入代码加一个简历摘要任务让模型输出候选人的核心卖点也可以加一个面试题生成任务从suggested_questions扩展成完整面试提纲。另一个值得做的扩展是混合筛选先用规则或向量检索做粗筛把明显不合格的简历挡在外面剩下的才走 LLM 精评。粗筛解决的是算力浪费LLM 解决的是语义准确率两者互补。粗筛规则可以很简单比如“工作年限小于 1 年直接过滤”“期望薪资范围与 JD 不符直接过滤”这些规则是确定性的成本为零。如果后续简历量级到几千份还可以把匹配结果落到数据库做一个简单的“候选人评分排行榜”页面。每份简历对应的overall_score、gaps字段都能结构化存储HR 按分数排序再点开看详细理由这基本就是一个小型 ATS 的雏形了。最后说一句个人体会。这套方案里最花时间的地方不是接代码而是打磨 Prompt 和调稳定性的细节。我一开始也幼稚地以为 GPT 类模型是万能的丢一段简历进去就能出完美结果后来发现在真实数据面前模型会犯各种脑补错误。把规则写进 Prompt、把容错写进代码、把缓存和限流配好这三件事做到位整个系统才敢交给 HR 用。Jev 加上 Vercel AI Gateway 的组合解决了我最头疼的“接入不稳定”和“重复请求浪费”两个问题如果你也在做类似的批量文本评估任务这个组合值得直接抄作业。