1. 为什么我看上Vercel AI Gateway简历匹配这个场景的中间人1.1 直接调 Jev API 不行吗行但会很痛先说结论如果只是写一个给自己用两天的脚本完全可以直接拿着 Jev 的 API Key 去调根本不用绕网关。但我这次要做的是一个正经的简历匹配服务接完 Jev 之后还要接别的模型对比效果还要让同事也能用、还要看日志排错这就不是能调通的问题了。直接调 Jev API 最烦的地方在于每次想对比模型效果都要改代码里的一堆常量。简历匹配这个场景尤其明显——你可能觉得 Jev 评分比较合理但想要看一眼另一个模型跑出来的分数差异那就得把 baseURL、请求头、错误码处理逻辑全部改一遍。如果你接触过几家不同风格的大模型 API还会发现它们所谓OpenAI 兼容只不过是大方向兼容真到了超时时间、错误码字段、流式返回格式这些细节上各家的脾气完全不同。业务代码里塞满了这种适配逻辑项目很快就会变得又脏又难维护。所以我把接入层抽了出来让所有模型请求统一走 Vercel AI Gateway。请求先到网关再由网关转发到真实的 Jev 模型服务。业务代码里只需要维护一个 OpenAI 风格的客户端、一个 baseURL、一个网关 Token模型切换变成了配置项而不是代码改动。后面我会具体写这个切换过程。1.2 网关替你兜住的脏活路由、重试、可观测性Vercel AI Gateway 在我这个项目里承担了三件脏活这三件事单独拎出来自己做都不难但全堆在业务代码里就很恶心。第一是路由。网关后面可以挂多个模型服务商每个 Provider 都有自己的地址和密钥。调用方不需要关心目标模型到底部署在哪只需要在 model 字段里带上一个配置好的标识网关会自己去找对应的后端。我这次配好 Jev 之后业务侧完全不用保存 Jev 的真实 API 地址自然也就不存在地址散落在各个文件里的问题。第二是重试和限流。模型服务经常返回 429、5xx或者干脆连接超时。网关层可以做统一的退避重试策略业务侧收到失败响应后不用自己写一坨超时重试逻辑。简历匹配这种请求动辄几秒甚至几十秒中间偶发一次网络抖动要是全让上层代码去处理那每个接口都得套一个重试框架想想就头大。第三是可观测性。网关注定每个请求的耗时、token 消耗、错误码还有一个统一的面板可以看。简历匹配上线之后你一定会被问到今天跑了多少份平均耗时多少成本多少这种问题。有了网关日志直接截图导出就行不用自己在数据库里埋一堆打点。1.3 网关不是银弹什么场景不建议绕这一层把网关说得这么好也该泼点冷水。如果你的场景是一次性的离线脚本数据量只有十几份简历跑完就完事那直接调 Jev API 就好多一层网关反而多一个故障点。如果你的企业对数据隐私要求极高要求请求链路不能经过任何第三方转发层那网关也可能不合适——虽然网关本身不保存模型内容但多经手一层这件事在某些合规场景下就是要额外论证。我的判断标准很简单凡是要持续迭代、要多人使用、要切换模型做对比的项目值得上网关凡是跑一次就扔、追求最小依赖的活别上。简历匹配恰好是前者所以我选了网关方案。2. 开工之前从Jev密钥到网关Provider配置2.1 拿到Jev API密钥注册、建Key、权限最小化接入的第一步当然是先拿到 Jev 模型的访问凭证。去模型官方站点注册账号之后在控制台里找到 API Keys / 密钥管理页面创建一个新的密钥。这里有几个实操细节值得多说一句。第一生产环境和本地调试最好用两个不同的密钥不要图省事共用一个。原因很简单本地环境变量文件有可能会被误提交到仓库里如果密钥是专用的泄露后只需要吊销这一把不影响线上。第二大多数模型平台允许给密钥设置额度上限建议新建密钥时顺手设一个月额度防止测试阶段被某个死循环脚本把余额刷光。第三别把密钥填到任何前端代码里这一点后面踩坑部分我专门会讲。顺便回应一个很多人关心的问题Jev 模型是否开源。对做应用层的我们来说模型开不开源其实不太影响接入方式——只要它的 API 是 OpenAI 兼容格式你把 baseURL 和 apiKey 一换代码就能跑。如果哪一天你想自托管那也只是把 baseURL 指向你自己的推理服务地址业务代码不需要变化。所以开源吗这个问题在你决定走云 API 的路线上基本不影响决策。2.2 在AI Gateway面板添加Provider登录 Vercel 控制台找到 AI Gateway 相关入口新建 Provider。填三样东西Provider 名称、Jev 模型 API 的基础地址、Jev API Key。Provider 名称其实是个别名我填的是jev后面在请求里就是用这个名字来路由的。配置完成之后网关会给你一个统一的调用地址通常形如https://gateway.vercel.ai/v1。如果面板支持创建项目级端点我也建议用项目级地址后续可以按项目区分调用量、分别配置限额多环境管理会舒服很多。因为各家网关面板的界面时不时会改字段名称可能略有出入但核心概念都一样你把自己的模型 Provider 挂到网关下面得到一个统一的 OpenAI 兼容 endpoint之后所有调用都打到这个 endpoint 上。遇到配置细节不确定的时候对照面板里的 Provider 配置说明把 Jev 的 API 地址和密钥填进去基本都不会错。2.3 本地开发环境必要的变量、依赖和目录结构我这次用的是 Next.js 项目主要是图它 API Route 写起来方便部署到 Vercel 也顺。不过网关接入这层其实跟框架无关你用 Express、Fastify 甚至一个 Python FastAPI 服务都完全没问题核心思路是一样的服务端持有网关 Token通过 OpenAI 兼容客户端完成请求。项目里需要装的东西不多npm install openai pdf-parse mammoth zodopenai官方 OpenAI SDK用来调用 OpenAI 兼容接口走网关时把 baseURL 换成网关地址即可。pdf-parse解析 PDF 简历。mammoth把 docx 转成纯文本。zod校验模型返回的 JSON 结构防止评分字段缺失或类型不对。环境变量这样配# .env.local JEV_GATEWAY_URLhttps://gateway.vercel.ai/v1 JEV_GATEWAY_TOKEN你的网关Token JEV_MODEL_IDjev:模型标识目录结构保持简单app/api/match/route.ts # 匹配接口 lib/parser.ts # 简历文档解析 lib/matcher.ts # 网关调用与评分逻辑 lib/schema.ts # 输出JSON校验3. 简历匹配的主流程从简历文本到结构化评分3.1 文档解析PDF和Word怎么变成干净的文本很多人觉得简历匹配的重点是选个聪明的模型实际上接到的简历里 PDF、Word、纯文本乱七八糟什么都有第一步反而是怎么把文件内容变成干净的文本。PDF 我用pdf-parseWord 用mammoth实现都不复杂// lib/parser.ts import pdf from pdf-parse; import mammoth from mammoth; export async function extractText(file: { name: string; buffer: Buffer }) { if (file.name.endsWith(.pdf)) { const result await pdf(file.buffer); return result.text.replace(/\n{3,}/g, \n\n).trim(); } if (file.name.endsWith(.docx) || file.name.endsWith(.doc)) { const result await mammoth.extractRawText({ buffer: file.buffer }); return result.value.trim(); } return file.buffer.toString(utf-8).trim(); }这里有个容易忽略的问题pdf-parse对扫描版 PDF 完全无能为力它会返回一堆空白或者乱码。正常电子签名的简历没问题但如果候选人发的是拍照件就必须先做 OCR这一步在 MVP 阶段可以先不处理我后面会再提。另一个经验是解析完之后要把多余的空行压缩掉简历文档经常有各种格式残留全塞进 Prompt 里既浪费 token 又会干扰模型判断。3.2 Prompt设计让模型同时扮演招聘专家和岗位剖析师解析文本只是准备工作真正决定匹配质量的是 Prompt。我第一次写的 Prompt 特别简陋就一句请评估这份简历和职位的匹配度结果模型给出来的评分没有维度拆解也没有解释理由根本没法用。后来我把 Prompt 调整成了招聘专家 岗位剖析师的双重角色设定核心要求是明确区分岗位职责和任职要求。这两种内容对匹配评估的权重完全不同岗位职责描述的是日常做什么任职要求才是硬性筛选条件。如果模型把两者混在一起很容易把负责团队管理这种职责内容当成候选人需要具备管理经验来打分导致误判。每个评分维度都必须给出依据。不能光给一个分数还要说明是根据简历里哪一段经历、哪一项技能判断的。必须输出 JSON字段应符合我在下一节定义的 schema。系统提示词我最终写成这样你是一位资深招聘专家擅长分析候选人简历与职位描述JD的匹配度。 你被给定两份内容候选人简历文本、职位描述文本。 请从以下五个维度分别打分每个维度0到100分 - experience工作经验与岗位所需经验的匹配程度 - skills硬技能与岗位技能的覆盖程度 - education学历与专业背景的匹配程度 - stability任职稳定性与职业路径的合理程度 - culture从简历内容推断的协作风格、行业背景契合度 同时输出 - matched_skills候选简历中命中JD要求的技能列表必须是简历原文中出现过的技能 - missing_skillsJD中明确要求但简历中缺乏的技能列表必须从JD原文提取不要推测 - summary150字以内的匹配总结 - recommendation建议强烈推荐/推荐/待定/不推荐 只输出JSON对象不要输出Markdown代码块不要加任何解释。这个 Prompt 看起来长但每句话都在约束模型的行为边界。尤其是必须是简历原文中出现过的技能和不要推测这两句是我经历了幻觉问题之后加上去的后面踩坑部分会仔细展开。3.3 输出约束JSON Schema与字段说明模型输出自由文本容易稳定输出结构难。我在lib/schema.ts里定义了完整的 zod schema// lib/schema.ts import { z } from zod; export const MatchResultSchema z.object({ scores: z.object({ experience: z.number().min(0).max(100), skills: z.number().min(0).max(100), education: z.number().min(0).max(100), stability: z.number().min(0).max(100), culture: z.number().min(0).max(100), }), matched_skills: z.array(z.string()), missing_skills: z.array(z.string()), summary: z.string().min(10), recommendation: z.enum([强烈推荐, 推荐, 待定, 不推荐]), }); export type MatchResult z.infertypeof MatchResultSchema;字段这么设计是有原因的。scores里五个维度全部用 0 到 100 的整数而不是高/中/低或者 1 到 5 星是因为后续做批量排序、画雷达图、算加权总分全部需要数值化数据。1 到 5 星粒度太粗两份明显不同的简历可能都打 4 星没法排序。matched_skills和missing_skills是为了可解释性——HR 拿到一份自动评分报告总得知道为什么是这个分数技能清单就是最直观的佐证。4. 接入代码实战Jev通过网关调用的完整写法4.1 统一客户端初始化网关的 endpoint 是 OpenAI 兼容的所以直接复用 OpenAI SDK只改 baseURL 和 apiKey// lib/matcher.ts import OpenAI from openai; const gatewayClient new OpenAI({ baseURL: process.env.JEV_GATEWAY_URL, apiKey: process.env.JEV_GATEWAY_TOKEN, });这里有一个关键认知SDK 里的apiKey字段在这里填的其实是 Vercel AI Gateway 的 Token而不是 Jev 平台的原始密钥。Jev 的真实密钥只存在于网关口配置里业务代码完全接触不到。这就很舒服——即使代码仓库泄露攻击者拿到的也只是网关 Token而网关 Token 的权限范围和撤销方式都是在你的掌控之下的。4.2 带重试的匹配函数下面是一个完整可用的匹配函数包含了构建 messages、调用模型、容错解析、重试几个部分// lib/matcher.ts import OpenAI from openai; import { MatchResultSchema, type MatchResult } from ./schema; export async function matchResume(resumeText: string, jdText: string): PromiseMatchResult { const systemPrompt 你是一位资深招聘专家擅长分析候选人简历与职位描述JD的匹配度。...只输出JSON对象不要输出Markdown代码块不要加任何解释。; const userPrompt 候选人简历\n${resumeText.slice(0, 8000)}\n\n职位描述\n${jdText.slice(0, 3000)}; let lastError: unknown; // 第一遍用标准结构化输出模式 for (let attempt 0; attempt 2; attempt) { try { const response await gatewayClient.chat.completions.create({ model: process.env.JEV_MODEL_ID as string, messages: [ { role: system, content: systemPrompt }, { role: user, content: userPrompt }, ], temperature: attempt 0 ? 0.2 : 0, max_tokens: 1500, response_format: { type: json_object }, }); const content response.choices[0]?.message?.content ?? ; const parsed extractJson(content); return MatchResultSchema.parse(parsed); } catch (err) { lastError err; // 短暂等待后重试第二次把 temperature 降到 0减少随机性 await new Promise((resolve) setTimeout(resolve, 1500)); } } throw lastError; } function extractJson(content: string) { // 有些模型兼容 openai 的 response_format有些会返回 markdown 代码块 const fenced content.match(/(?:json)?\s*([\s\S]*?)\s*/); if (fenced) return JSON.parse(fenced[1]); return JSON.parse(content); }关于response_format有一点要特别注意并不是所有 OpenAI 兼容模型都支持这个参数。Jev 这块你在实测时最好先试一下如果传了报错就把这个参数去掉然后依赖上面的extractJson对 Markdown 代码块做兜底解析。这是兼容各种 OpenAI 兼容模型的关键小技巧。4.3 返回结果给前端时的格式化处理API Route 里把匹配结果再包一层统一结构返回给前端方便调用方处理// app/api/match/route.ts import { NextResponse } from next/server; import { extractText } from /lib/parser; import { matchResume } from /lib/matcher; export async function POST(req: Request) { const startedAt Date.now(); const formData await req.formData(); const file formData.get(resume) as File; const jd formData.get(jd) as string; if (!file || !jd) { return NextResponse.json({ error: 缺少简历文件或JD文本 }, { status: 400 }); } const buffer Buffer.from(await file.arrayBuffer()); const resumeText await extractText({ name: file.name, buffer }); if (resumeText.length 50) { return NextResponse.json({ error: 简历解析结果为空请确认文件不是扫描件 }, { status: 422 }); } try { const result await matchResume(resumeText, jd); return NextResponse.json({ data: result, meta: { elapsedMs: Date.now() - startedAt }, }); } catch (err) { console.error(匹配失败:, err); return NextResponse.json({ error: 匹配服务暂时不可用请稍后重试 }, { status: 502 }); } }这里还顺手做了一个最小鲁棒性校验如果解析出来的简历文本不足 50 字直接拒绝避免把空文本送进模型返回一堆瞎评分。前端拿到elapsedMs也能在界面上显示本次匹配耗时 xx 秒让用户有个合理预期。5. 踩坑记录密钥暴露、响应解析和长文档超时5.1 前端环境变量里的密钥差点裸奔这是我在项目最初期差点犯下的错误。当时为了快速出 Demo我把JEV_GATEWAY_TOKEN用NEXT_PUBLIC_前缀的形式放在了环境变量里然后在一个客户端组件里直接调用网关。从功能上讲浏览器确实能发请求拿到匹配结果但代价是网关 Token 被完整打包进了浏览器端 JavaScript 文件里任何人打开控制台都能看到。这种做法的危险在于你原本指望通过网关把真实模型密钥藏起来结果网关 Token 又在前端裸奔了等于绕了一圈又回到了起点。正确做法是严格的服务端代理——前端只把文件传给自己的 API Route由 Route 持有 Token 调用网关然后把结果返回给前端。这样浏览器永远只跟自己的服务端打交道跟 Vercel AI Gateway、跟 Jev 平台之间都没有直接联系。5.2 长简历超时截断、拆块与并发第一次真实测试我丢进去一份 6 页纸的资深技术负责人简历还带了一堆项目描述。结果等了将近一分钟接口直接超时。问题出在简历文本太长模型需要在超长上下文里做分析生成时间也跟着拉长。我用的第一个修复手段是截断。把简历文本 slice 到 8000 字符JD slice 到 3000 字符保证 Prompt 总量可控。实测下来对于绝大多数候选人简历保留前 8000 字符基本能覆盖最近三段工作经历和技能列表——这也是 HR 最看重的部分。截断毕竟会丢信息所以后来我又做了第二层优化拆块评估。把简历按基本信息技能列表工作经历项目经历切成三个块分别让模型打一次分最后再让模型基于三个子评估汇总出一个总分。这样每个子任务更聚焦也不容易超时。代价是调用次数翻了好几倍、成本翻倍。我的建议是MVP 阶段先截断跑通了再考虑拆块如果每天处理的简历量不大截断带来的精度损失完全可以接受。5.3 对话中的幻觉关键词怎么识别和抑制在评估一份没有提到任何容器化经验的简历时Jev 生成的missing_skills里居然出现了Kubernetes和Docker——这俩词在职位描述原文里根本不存在。这就不是评分问题了而是模型在脑补技能清单如果照单全收给 HR 看会让人怀疑你的系统在胡编。这个问题我做了两层防御。第一层是 Prompt 层面约束这也是最有效的在系统提示词里明确写matched_skills 必须是简历原文中出现过的技能missing_skills 必须从 JD 原文提取不要推测。大多数情况下模型会遵守这个约束。第二层是代码层面的后置过滤从模型返回的matched_skills和missing_skills里过滤掉那些既不出现在简历原文、也不出现在 JD 原文里的词。注意这个过滤不能做得太机械因为简历写熟悉消息队列JD 写RabbitMQ俩词在字面上完全不同但语义相关。所以我会保留原始结果给前端展示同时在后端计算一个strictMatch列表作为参考字段让审核的人有据可查。这个问题的根因在于模型在生成 JSON 时会在概率分布里选择最像技能列表的词而不会时刻记得我从哪句话得到这个结论。唯一的解法就是反复提示它基于原文再加一个程序化过滤器作为最终防线。6. 批量筛人的进阶思路实测评估与扩展方向6.1 我实测下来的效果、耗时和成本用 30 份真实简历做了一轮测试当然脱敏了这里记录一下我的体感数据不是严谨评测仅供参考。单份简历的匹配耗时大概在 20 到 40 秒之间主要取决于简历长度和模型服务的实时负载。Prompt 平均 token 消耗在 4000 到 6000 之间其中大部分是简历文本。如果按模型平台的 token 单价粗略估算单份简历的成本约在几美分这个量级考虑到它省下的人工阅读时间性价比非常高。和人工评估的一致性方面我拿 10 份简历让 HR 同事人工打分再用服务跑一遍差额基本控制在 ±10 分以内。不能说模型比人工更准但它最大的价值是标准统一——同一个 JD 下所有简历都按同一套维度打分不存在人工审阅时前面严格后面宽松的疲劳效应。6.2 从单份匹配到批量初筛Embedding 可以怎么介入上面的实现是单份简历 JD → 评分。如果简历量变成几百份每一份都走完整的大模型调用耗时和成本都会线性增长。这时候我建议先做一层基于向量的初筛。思路是把 JD 和每份简历分别向量化计算语义相似度先召回最相关的前 20 份到 30 份再对这部分候选走前面写的 Jev 精审评分。Embedding 初筛这一步非常便宜且快速虽然精度不如大模型精评但足以把明显不相关的简历挡在门外。像pgvector或者本地的向量库都能做这个召回如果不想引入向量数据库也可以退而求其次用关键词倒排过滤但召回质量会明显差一截。6.3 如果继续迭代我下一步会做这几件事第一把 JD 也结构化。现在 JD 是直接粘进去的纯文本但同一家公司不同岗位的 JD 结构差异很大。如果先把 JD 拆成职责硬性要求加分项三个字段再喂给模型评分维度的解释会更清晰。第二做成异步批处理。在线同步匹配只适合单份试用真正的批量筛选应该走任务队列上传一批简历 → 服务端逐份处理 → 每份处理完通过 Webhook 通知前端。这样就算处理一百份简历要一两个小时用户也不用一直开着页面等。第三增加一个人工复核出口。模型给的分数和技能清单应该允许 HR 在界面上修改修改后的结果沉淀下来未来可以反哺 Prompt 或做成反馈数据。简历匹配这种决策场景模型当助手、人做最终判断才是最务实的产品形态。最后分享一个我自己踩过之后总结出来的习惯做 AI 应用宁可让用户多等三秒也不要返回一份半截 JSON。稳定的输出结构、完善的容错解析、严格的后端校验这三件事的重要性排序永远排在选哪个模型前面。模型可以随时换坏了结构就会让你的一系列下游逻辑全部崩盘。