1. 为什么做这套系统从“看不懂JD”到“一个Agent搞定”JoyAgent-JDGenie 这套系统架构文档最早其实是内部一个探索性项目的落地产物。当时我们团队在做的方向是智能求职辅助市面上已有的产品要么只做职位搜索要么只做简历模板几乎没有人把“JD解析—画像抽取—简历匹配—面试问答”这条链路真正打通。用户的实际痛点也很直接一份JD拿到手里面写的“具备良好的跨部门沟通能力”到底重不重要我这份简历里写了三年项目经验和这个岗位到底匹配不匹配面试官大概率会问什么方向的问题这些问题的本质是传统搜索和规则匹配根本回答不了的。JD文本是非结构化信息简历也是非结构化信息它们之间存在语义鸿沟。所以 JoyAgent-JDGenie 选择了一条跟传统招聘系统完全不同的路用大模型做语义理解层把JD和简历都抽成结构化的“岗位画像”和“候选人画像”再基于画像做匹配、做问答、做面试预测同时保留一套规则引擎作为兜底。整套系统定位为“招聘场景下的智能体Agent”JDGenie 这个名字就是 Job Description Genie 的缩写意图很明确——让JD这件事变得像精灵一样听话。这套设计解决的关键问题有三个。一是把非结构化的招聘文本变成结构化数据链路二是把大模型的不确定性控制在业务可接受范围内三是在成本和稳定性之间找到平衡点。适合谁来看这篇架构文档呢如果是做AI应用层开发、智能体编排、或者招聘类SaaS的后端工程师这篇文章可以直接当设计参考如果你手头有大模型项目正在落地但被幻觉、超时、成本这些问题搞得焦头烂额那文章里的降级策略和状态机设计也会对你有帮助。这不是一篇讲“高大上”概念的文章每一层都是我们上线后拿线上数据“磨”出来的。2. 总体架构单体应用里的领域边界怎么划2.1 顶层架构视图JoyAgent-JDGenie 的整体架构并没有走微服务而是选择了一个模块化的单体应用。这个决策当时我们内部争论了很久最终确认是基于团队规模和业务复杂度做的现实判断。整个系统分四层接入层、应用服务层、领域服务层、基础设施层。接入层只做两件事API鉴权和请求分发应用服务层管会话、管任务编排领域服务层是核心包含JD解析引擎、简历解析引擎、匹配评分引擎、问答与面试模拟引擎、规则兜底引擎基础设施层负责向量数据库、关系数据库、缓存、对象存储以及大模型网关。用一张简单的文本图来表达就是接入层(API Gateway) → 应用服务层(会话管理/任务调度/事件总线) → 领域服务层(JD解析/简历解析/匹配评分/Agent问答/规则引擎) → 基础设施层(Mysql/Redis/向量库/对象存储/LLM网关)各层通过内部事件解耦比如JD解析完成之后会发布一个“JdParsed”事件匹配服务订阅这个事件后自动触发简历匹配流程匹配完成再发布“MatchCompleted”事件Agent服务根据事件结果准备下一轮对话。这套事件驱动设计让整条链路可以被异步化避免一次HTTP请求把全部计算量压在一起。2.2 关键技术选型的权衡逻辑这里重点说说两个关键选型的逻辑。第一个是“单体优先”。当时我分析过如果用微服务拆成JD服务、简历服务、匹配服务、对话服务四个系统团队光维护服务间调用链就要花掉大量时间而招聘业务早期的并发量根本不需要独立扩容。单体应用的部署成本低、调试方便、事务边界好控制等到某一个领域服务的负载真正上来之后再根据监控数据把它单独拆出去也不迟。这就是“演进式架构”的思路而不是一开始就铺一个大摊子。第二个是“LLM 只做语义理解不做计算决策”。我们在Agent问答链路里做了明确分层大模型负责抽取意图、生成自然语言回复而要不要推荐某份简历、匹配分怎么算、模板怎么填充这些“计算”完全走代码逻辑。这样做的原因很简单大模型的数学能力和确定性都不足以支撑精确的业务规则。比如候选人问“我和这个岗位匹配度是多少”模型直接输出数字大概率是不准的我们就会让它输出“请查询匹配度”后端再从缓存里取真实的匹配分拼进模板里返回给用户。实测下来这种混合模式既保留了对话的灵活度又确保关键数据绝对可信。3. 核心模块实现从JD文本到结构化画像3.1 JD解析引擎的设计细节JD解析引擎是整个系统的第一环也是最容易翻车的一环。大家拿到一份JD时看到的是一大段描述文本里面混着岗位名称、薪资范围、硬性要求、软性要求、福利信息、公司介绍甚至还有错别字和emoji。如果直接把这堆文本塞给大模型让它输出JSON看起来可行但线上你会发现三个很痛苦的问题输出字段名不稳定、数组长度随模型心情变化、重要信息被幻觉填错。我的做法是把JD解析拆成两个阶段。第一阶段是“文本清洗规则预切分”用正则和行业词库先做粗提取比如把“薪资范围”“工作地点”“经验要求”这些有明显模式的字段先用规则抓出来第二阶段才是“LLM精细化抽取”只让模型处理规则抓不到的非结构化部分比如岗位职责、任职要求、软性素质。LLM的输出会被一层校验器拦住凡是字段缺失、枚举值不合法、数组为空的结果全部降级为规则预处理结果并标记为低置信度。这套“规则先行、模型精调、校验兜底”的流程把JD解析的成功率从最初的76%拉到了95%以上。实操中还有个容易被忽略的细节Prompt里的字段定义必须给“枚举值示例”。比如“学历要求”字段如果只写“要求output学历”模型可能输出“本科及以上”“本科/硕士”“大学本科”等各种变体后续匹配枚举比对直接出问题。我们在Prompt里要求输出只能是“大专/本科/硕士/博士/不限”五种枚举之一并且给了一个“教育背景或培训经历本科”这样的示例准确率立刻提升了一截。凡是做信息抽取的同行我建议都在Prompt里做枚举约束成本几乎为零收益非常可观。3.2 语义匹配与排序是怎么算的匹配评分模块不是简单算个余弦相似度就完事。JDGenie把匹配拆成三路并联第一路是关键词加权匹配算的是简历里出现JD核心技能词的覆盖率第二路是语义向量匹配把岗位画像和候选人画像分别做向量化算 embeddings 的相似度第三路是规则硬校验比如学历要求、工作年限、硬性技能证书这些不满足就不通过的字段。最后用一层加权融合策略把三路分数合并成最终的匹配指数。这里要解释三个细节。关键词匹配里的词权重不是拍脑袋定的我们采集了历史数千条真实JD语料用TF-IDF统计出每个技能词的区分度比如“Python”这种大量出现的词权重反而低“Terraform”这种稀缺词权重高。语义向量匹配用的不是单向量全文档平均而是把JD切分成“岗位职责”“任职要求”“加分项”三个片段分别向量化再和简历里的“项目经历”“技术栈”“教育背景”三个片段做交叉匹配最终取加权最大值。交叉匹配的意义在于JD的任职要求通常和简历的某段项目经历对应全文档平均会把信息稀释掉。匹配分出来之后还需要做排序。排序时有个关键参数是阈值校准单纯看相似度绝对值没有意义因为不同模型的向量空间分布不同得分普遍会偏高或偏低。我们的做法是在线下用历史简历构造正负样本跑一遍ROC曲线取灵敏度和特异性平衡点作为匹配阈值。这个校准流程必须跟向量模型升级绑定每换一次embedding模型全部阈值必须重标否则上线后会出现大面积误判或者漏判。3.3 Agent对话编排与状态机设计Agent是JoyAgent-JDGenie的门面也是最容易失控的部分。用户在对话框里问“这个岗位怎么样”“帮我看看我的简历匹配嘛”“模拟面试一下”……如果没有约束模型很容易跑偏成闲聊。我们给对话服务设计了四层状态机INIT初始化、PROFILE_ANALYSIS画像分析、MATCH_CONSULT匹配咨询、INTERVIEW_MOCK面试模拟。每个状态下模型能触达的工具集合完全不一样在MATCH_CONSULT状态模型只能调用“获取岗位画像”“获取匹配报告”“获取简历要点”三个工具在INTERVIEW_MOCK状态则只能调用“按技能维度出题”“评估回答”两个工具。状态迁移的触发条件也严格做了限定。比如“匹配咨询”状态到“面试模拟”状态要求模型先输出一个“intent_transition”结构包含目标状态和意图置信度。后端拿到这个结构之后还要进一步判断用户最近三条消息里有没有“面试”“模拟”“考考我”这类强意图词双重确认后才会真正切换状态。这套设计避免了用户一句“嗯嗯”就触发状态跳变的尴尬。底层支撑这套编排的是一个再简单不过的循环接收用户消息→填充上下文与工具定义→调用LLM→解析结构化响应→依次执行工具调用→拼接结果→再次调用LLM→产出最终回复。这里的每一次LLM调用都要记录耗时和Token消耗我们设了一个单轮对话成本红线一次完整问答链路最多3次LLM调用的Token消耗不允许超过4000。一旦超了就直接截断工具执行结果用模板化的简短回答兜底。这个成本红线非常值得做没有它会发现月底账单异常感人。4. 数据模型与核心流程是怎么串起来的4.1 领域模型划分与表结构要点JoyAgent-JDGenie围绕两个核心聚合根组织数据JobPosition岗位和CandidateProfile候选人画像。JobPosition 表存的是JD的基本实体信息但真正承载结构化画像的是 job_profile_snapshot 表——每次JD解析都会生成一份快照里面以JSON格式存放分层抽取出的人才画像包括硬性条件、技能权重、职责要点、软性素质、面试题参考等四个大维度。使用快照而不是直接更新主表是因为同一份JD可能被多次重新解析每次结果都要留痕方便回滚和A/B对比。CandidateProfile 类似由简历解析服务生成包含技能树、项目经历节点、教育经历、工作年限、认证证书等。匹配结果存放在 match_result 表里每条记录由 job_snapshot_id candidate_profile_id 唯一确定里面的 score_detail 字段把三路评分的明细都存下来。这个细节对线上问题排查特别重要不然用户问“为什么匹配分这么低”你根本说不清楚是关键词没命中还是向量相似度低了还是硬性条件卡了。Agent会话数据单独用一套会话表每个会话绑定当前状态、最近N轮消息、关联的岗位快照和候选人快照。这里有一个容易踩的坑不要把整个消息历史全部塞进LLM上下文一定只保留经过摘要压缩的最近几轮。我们设置默认携带最近6轮原始消息整体对话摘要超出部分做滚动摘要更新。这样做既保住了多轮对话的语义连续性又把单轮Token消耗控制在一个稳定区间。4.2 核心时序一次完整匹配咨询的流转拿最常见的场景——用户上传一份简历然后问“我适合这个岗位吗”——来串一遍整体时序。用户先上传简历文件接入层把文件POST到解析服务解析服务先转成纯文本再走规则预处理和LLM抽取生成候选人画像后落库。此时用户发出了咨询消息应用服务层先判断会话状态是INIT于是系统自动为用户检索目标岗位、加载岗位快照随后触发异步匹配任务。匹配任务三步走先跑规则硬校验学历、年限、必含技能再跑关键词加权匹配和语义向量匹配最后融合出分、写入match_result表。这里我特意把匹配设计成异步的避免用户在对话框前干等十几秒。用户发出消息后前端会立即收到一个“正在分析中”的占位回复同时后端任务执行完毕后通过轮询或SSE推送真实结果。异步流程的代价是状态管理变复杂了所以我们在任务表里加了status字段PENDING、RUNNING、SUCCESS、FAILED、TIMEOUT。任何一次匹配任务超时默认8秒状态置为TIMEOUT同时触发降级策略——只返回规则硬校验的布尔结果和一条“当前信息不足建议补充XX”的模板消息。这套策略上线后最直接的收益是长尾请求的最差响应时间从30秒下降到了10秒以内。5. 稳定性设计大模型不可靠兜底策略来补5.1 依赖故障时的降级预案任何接入大模型的应用都必须假定“模型服务会挂”不是会不会挂而是什么时候挂。JoyAgent-JDGenie在稳定性上做了三层降级。第一层是超时降级LLM调用设置3秒连接超时、8秒读超时超时后不重试大模型服务超时重试往往会放大故障直接走本地缓存的最近一次解析结果或者模板回复。第二层是错误码降级当模型网关返回限流或服务不可用状态码时触发熔断器打开后续请求在30秒内不再打模型直接返回降级结果。第三层是语义降级模型返回的内容无法通过JSON解析校验时自动丢弃本轮模型结果把规则引擎产出的数据格式化后回复给用户。规则引擎在这里不是配角而是整个系统的“底线”。我们在规则引擎里维护了一份行业技能词库、岗位层级词典、薪资区间标准化规则哪怕大模型服务连续挂了10分钟用户依然可以完成“查看岗位基本信息”“查看基础匹配结论”这两个核心操作。系统上线至今遇到过两次上游模型服务长时间故障正是因为底线还在用户投诉量远低于预期。这件事也让我彻底明白AI系统的稳定性和AI本身的能力同等重要。5.2 Token成本治理与Prompt优化实录LLM的成本是隐性成本不治理就是吞金兽。我们主要做了三件事。第一是统一模型网关所有LLM调用都走内部网关网关统一做模型路由、配额控制、Token记录禁止业务代码零散直连模型供应商API。第二是Prompt分层每种任务类型维护一个独立的Prompt模板仓库模板经过版本管理任何Prompt修改都必须走评审流程并压测Token消耗。举例来说JD解析模板在V1版本平均消耗2200 TokenV2版本把职责和任职要求合并抽取、减少冗余输出格式说明Token消耗降到1400降幅36%而抽取准确率还微涨了两个点。第三是结果缓存这是见效最快的手段。JD解析结果和匹配结果都以“内容哈希参数版本号”作为缓存key缓存有效期设置为24小时。同一份JD被10个用户咨询实际解析次数只有1次同一份简历和同一个岗位被重复匹配也只会算一次。叠加缓存后整个系统的模型调用量下降了62%月底账单差不多砍了一半。如果有同类项目正在被成本问题困扰建议先做“任务级结果缓存”比单纯优化Prompt见效更快、更可控。6. 部署落地、性能调优与前端协作的实战经验6.1 部署架构与关键参数调优JoyAgent-JDGenie的部署形态是两台应用节点Nginx负载均衡数据库用的云托管MySQL8G内存规格Redis4G做缓存和会话存储向量数据库用的是独立实例对象存储放简历原文件。这个配置规模不算大但足够支撑日均万级请求量核心原因在于系统的计算密集任务全都走异步和缓存同步API链路里几乎没有重计算。部署上线阶段有几个参数必须调否则会踩坑。首先是连接池大小我们应用节点用的连接池最大连接数设为40MySQL的最大连接数调大到200。这里有个经验公式连接池最大连接数 节点数 × 单节点核心数 × 2既不会打满数据库也不会因为连接数太少导致请求排队。其次是Redis的maxmemory-policy我们设置为allkeys-lru防止某个冷门key把内存打爆之后发生逐出异常。最后是Nginx的keepalive_timeout设为75秒与后端服务的空闲连接超时保持一致避免连接复用失效导致频繁重建。向量检索的参数也值得单独提一句。我们用HNSW索引最关键的参数是M每个节点的最大连接数和efConstruction建索引时的动态列表大小。M调大能提高召回率但会增加内存占用这里设为32efConstruction设为200这是一个在索引质量和构建时间之间的折中值。查询侧efSearch参数设为64低于构建值可以在召回率和查询延迟之间取平衡。调完这套参数组合后向量检索P95延迟稳定在80毫秒左右。6.2 跟前端团队协作时踩过的坑后端架构设计得再好跟前端配合出了问题照样体验崩盘。这里分享三个典型教训。第一个是关于流式输出。JSON格式的流式响应前后端如果不提前约好解析协议会出现大量一半是JSON一半是空白的渲染异常。我们的解决方案是所有流式接口统一返回SSE格式每条事件里包含一个type字段取值有start、delta、end、error四种并且约定了error事件的错误码枚举。前端拿到error事件后主动停流并展示兜底内容一定不能干等。第二个是关于轮询时机。异步匹配任务完成后前端需要轮询后端拿结果如果轮询间隔太短每秒一次高峰期会给后端造成无谓压力如果间隔太长用户又会觉得反馈不及时。我们的方案是动态轮询前5秒每1秒轮询一次之后每3秒一次超过30秒后前端主动停止轮询展示“结果生成较慢请稍后查看”的提示。第三个是关于业务词汇的前后端共识。前端在展示“匹配指数”“硬性条件”“软性素质”这些字段时如果不跟后端共享一份字段字典就会出现前端把score_detail直接渲染成JSON字符串的怪现象。后来我们把字段定义收敛成一份共享的Swagger文档加字段注释规范这类问题基本绝迹。7. 上线后的常见问题与排查实录7.1 高频问题速查表以下是JoyAgent-JDGenie上线半年内遇到的高频问题以及排查定位方法整理成速查表适合直接存进团队的wiki里。问题现象根因分析排查方法解决策略同一份JD不同用户看到的匹配分不一样一次性问题查缓存命中率确认是否为缓存穿透为岗位快照加版本锁解析结果写入后固定不变对话答非所问Agent状态串了导出一段时间的状态迁移日志查状态重置时机在入口会话ID维度加状态锁避免并发消息覆盖状态匹配分普遍偏低向量模型换版后阈值未校准拉出最近一周匹配分分布对比波动曲线重新用历史样本跑ROC曲线校准匹配阈值大模型返回JSON字段缺失Prompt里未做枚举约束或模型版本行为漂移对比同一Prompt在模型升级前后的输出差异在SDK层加输出Schema校验失败自动重试一次高峰时期匹配任务大量超时异步任务线程池被打满查看线程池活跃线程数和队列积压数把匹配任务线程池独立隔离并设置最大等待时间Token成本异常飙升用户高频重复触发解析查没走缓存的请求链路增加解析请求的去重与频控限制7.2 印象最深的两个故障复盘第一个故障是上线第二周出现的“匹配结果大规模漂移”。现象是某天下午新增用户的匹配分突然整体下降但存量用户不受影响。排查过程很有意思先看了匹配分数分布P50从78掉到了63明显不是个别case再看模型调用日志发现那段时间向量化服务返回的平均向量模长变小了连续几批请求都是如此。跟模型供应商确认之后发现对方在前一天晚上发布了新版本模型虽然API没变但向量空间的分布整体偏移了。事后我们把模型升级流程改成了“先灰度、后全量、再校准”所有依赖模型输出的阈值参数都纳入版本化配置任何模型升级都要先在一组固定回放样本上跑回归测试通过后才能放量。第二个故障是“面试模拟场景上下文爆炸”。有个用户在面试模拟功能里连续问了20多个问题每次请求携带的上下文太长单轮耗时飙到了12秒而且连续触发模型网关限流导致同时间段其他用户的对话全部受影响。这就是典型的“聊天记录无限增长”问题。我们用两个手段处理一是对消息历史做“滚动摘要”超过6轮后把前面的消息压缩成200字以内的摘要二是对长对话强制打开“省流模式”只传当前问题对应技能维度的参考信息不再传全量简历内容。处理之后长对话场景的P95耗时从12秒降到了4秒左右限流问题也彻底消失。8. 一些心里话这套系统做下来我最深的体会是AI 应用的架构难点从来不在模型本身而在模型周围的“确定性工程”。模型总会输出意外结果、服务总会抖动、成本总会超出预期你能做的就是把所有的意外路径都设计好兜底。JoyAgent-JDGenie在技术上并没有用到什么前沿的黑科技真正值钱的反而是那些笨功夫状态机约束、输出校验、降级预案、Token治理、阈值校准。最后再分享一个亲身验证过的小技巧新项目起步时不要一上来就追求“全链路智能”。先把业务里最适合规则处理的环节用规则实现让链路先跑通再逐步用模型替换那些规则确实搞不定的环节。我们前期用规则引擎撑起了整个骨架后面每替换一个环节都带着线上数据做A/B对比每一步都有把握才敢上。这样走下来系统的稳定性是一点点长出来的不是最后补出来的。如果重新再来一次我还会这样选。