一、Hiring Agent 是什么
先直接说结论：Hiring Agent 是由 HackerRank（也就是 interviewstreet）开源、基于 Python 构建的一套简历自动打分流水线（Resume-to-Score pipeline），采用 MIT 协议，专门为技术岗位招聘场景量身打造。它能读取 PDF 简历，借助大模型把简历信息标准化提取出来，还能自动抓取候选人 GitHub 上的开源履历作为补充评估维度——最终输出一份带有证据、可以回溯的客观候选人评分报告。简单来说，就是为了解决传统人工筛选效率低、主观偏差大、技术能力难以量化这些招聘痛点而设计。
整套工具支持两套大模型运行方案：本地离线用 Ollama 运行开源模型，或者用云端的 Google Gemini。这样设计的好处是，既能保护数据隐私，又能利用云端算力。全程在命令行里运行，支持缓存，还能批量导出 CSV 评分报表，并且可以二次开发对接企业内部招聘系统。
二、核心功能特色
PDF简历结构化解析
基于 PyMuPDF 把 PDF 简历转换成带有排版信息的 Markdown，自动识别标题、表格、链接，然后分模块（基础信息、工作经历、教育背景、技能、项目、奖项）通过定制提示词提取出标准的 JSON Resume 数据。这样，那些格式杂乱的简历文本就能被机器准确识别。GitHub履历自动增强评估
自动提取简历里的 GitHub 账号，调用 GitHub API 获取个人主页和所有仓库，然后通过大模型从中筛选出 7 个高贡献的优质开源项目，量化开源贡献、个人项目、工程落地经验这三个技术维度，精准评估开发者的实战能力。支持配置 GitHub Token 以提高接口调用限额。公平可解释的多维度打分体系
内置了一套公平约束评分规则，分为开源贡献、个人项目、生产项目、专业技术技能四大核心打分项，同时记录每项分数对应的简历原文证据，附带加分项和扣分项明细——彻底杜绝了 AI 主观评判的黑箱问题，HR 可以完整追溯评分依据。双大模型兼容切换
一套代码就能无缝切换两种 LLM 后端：Ollama 本地离线部署（Gemma3 系列模型，数据本地存储不泄露），或者 Google Gemini 云端 API（适合高速批量处理大量简历），而且可以自由配置模型版本。本地缓存与批量报表导出
开启开发模式后，会自动缓存 PDF 解析结果和 GitHub 接口原始数据，减少重复调用 LLM 和第三方 API；还能自动生成resume_evaluations.csv批量评分文件，方便数据归档和统计分析。完善的工程化容错机制
内置了 Gemini 接口的指数退避加抖动限流策略，修复了简历解析失败后的缓存异常问题，统一清洗大模型返回的不规范 JSON，代码统一采用 Black 格式化规范，方便后续迭代维护。全流程命令行极简调度
只需一条命令就能完成完整的简历评估，无需复杂的可视化操作，轻量级且无前端依赖，既能在服务器上运行，也能在本地 PC 上离线执行。
三、技术细节
3.1 整体流水线架构（5阶段执行链路）
PDF文本转换：
pymupdf_rag.py负责把 PDF 转成 Markdown 结构化文本；简历信息抽取：
pdf.py加载prompts/templates下的 Jinja 提示词，分模块调用 LLM 生成标准简历 JSON；GitHub数据拉取与筛选：
github.py抓取仓库数据，大模型筛选优质开源项目；标准化候选人评估：
evaluator.py加载评分规则模板，生成带证据的分项得分；结果输出调度：
score.py程序入口，控制台打印报告、缓存中间数据、导出 CSV。
3.2 核心模块分工说明
| 文件名 | 核心技术职责 |
|---|---|
| score.py | 项目入口，全流程串联、结果输出、缓存控制 |
| pymupdf_rag.py / pdf.py | PDF解析、文本格式化、分段LLM抽取简历信息 |
| github.py | GitHub API交互、项目筛选、开源贡献量化 |
| evaluator.py | 评分规则执行、多维度打分、生成评估依据 |
| models.py | Pydantic数据模型、统一LLM厂商抽象接口、限流逻辑 |
| llm_utils.py | LLM实例初始化、模型响应清洗、异常处理 |
| prompt.py | LLM厂商映射、提示词模板统一加载 |
| transform.py | 清洗LLM松散JSON，转换为标准JSON Resume格式 |
| config.py | 全局开发模式开关（缓存/CSV导出控制） |
| prompts/ | 全套Jinja提示词模板，覆盖简历抽取、项目筛选、评分评估全场景 |
3.3 环境依赖与技术栈
运行环境：固定 Python 3.11.13，项目自带
.python-version文件锁定版本；PDF解析：PyMuPDF；
LLM后端二选一：Ollama（Gemma3:1b/4b/12b本地模型）、Google Gemini（gemini-2.0-flash/gemini-2.5-pro）；
配置管理：
.env环境变量配置，区分模型厂商、API密钥、GitHub令牌；数据格式：Jinja2 提示词模板、JSON Resume 标准简历结构、CSV 报表；
代码规范：Black 统一代码格式化，MIT 开源协议。
四、应用场景
技术团队校招/社招批量简历初筛
不管是研发、后端、前端、算法还是运维，技术岗位的海量简历可以通过这套工具实现自动化初筛，替代人工通读，快速过滤掉匹配度低的候选人，显著提升招聘效率与候选人筛选精准度。开源开发者专项人才挖掘
如果岗位特别看重开源能力，该工具可以自动量化候选人的 GitHub 项目贡献，精准筛选出那些拥有实战经验和开源协作经验的优秀工程师。企业内部人才库标准化打分归档
批量评估历史简历，导出 CSV 统一存储评分数据，逐步建立起可检索、可量化的技术人才储备库。外包/猎头技术候选人快速背调
无需人工逐个翻阅 GitHub 主页，工具会自动完成开源履历评估，大幅降低猎头的人工核验成本和时间投入。私有化合规招聘场景
如果使用 Ollama 本地模型离线运行，简历和候选人数据全程在本地存储，完全满足金融、政企等数据不能出内网的合规要求。二次开发集成
基于开源代码封装 API，可以对接企业自研的 ATS 招聘系统、内部 OA 或者人才管理平台，实现高效集成。
五、完整使用方法
5.1 环境前置准备
安装 Python 3.11.13；
二选一部署LLM：
本地方案：安装 Ollama，执行
ollama pull gemma3:4b拉取开源模型；云端方案：申请 Google Gemini API Key；
（可选）获取 GitHub Token，提升API访问频次限制。
5.2 项目拉取与依赖安装
#克隆仓库gitclonehttps://github.com/interviewstreet/hiring-agentcdhiring-agent#创建虚拟环境python-mvenv.venv#Mac/Linux激活环境source.venv/bin/activate#Windows激活环境.venvScriptsactivate#安装全部依赖pipinstall-rrequirements.txt
5.3 环境变量配置
复制模板文件生成配置文件，填写对应的密钥：
cp.env.example.env
核心环境变量配置项：
LLM_PROVIDER：ollama / gemini（默认ollama）DEFAULT_MODEL：模型名称，如gemma3:4b、gemini-2.5-proGEMINI_API_KEY：Gemini云端调用必填GITHUB_TOKEN：可选，提升GitHub接口限额
5.4 执行简历评估（核心命令）
pythonscore.py/你的简历文件路径/resume.pdf
执行后会自动完成 PDF 解析、GitHub 数据抓取、打分评估，控制台会输出完整的评估报告；如果开启 DEVELOPMENT_MODE=True，还会自动缓存中间数据并导出 CSV 评分表格。
六、竞品对比
这里选择了另外两款同类工具做对比：阿里开源简历解析工具 SmartResume、通用开源简历匹配工具 Resume Matcher，从多个维度来比较。
| 对比维度 | Hiring Agent | SmartResume（阿里开源） | Resume Matcher |
|---|---|---|---|
| 项目定位 | 技术岗完整简历打分流水线，集成GitHub开源能力评估 | 通用多格式简历结构化解析工具 | 求职者简历-JD匹配度优化工具 |
| 支持简历格式 | 仅PDF | PDF、Word、图片、Excel多格式 | PDF、文本简历 |
| GitHub履历评估 | ✅ 原生内置，自动筛选优质开源项目打分 | ❌ 无GitHub关联分析能力 | ❌ 不支持第三方账号挖掘 |
| LLM部署方案 | Ollama本地离线 + Gemini云端双方案 | 内置通义千问轻量化模型，无本地开源模型支持 | 仅文本向量相似度，无大模型深度抽取 |
| 评分可解释性 | ✅ 分项打分+原文证据溯源，公平约束 | ❌ 仅结构化字段提取，无标准化打分体系 | 仅匹配度数值，无分项能力评估 |
| 输出文件 | 控制台报告 + CSV批量报表 + 本地JSON缓存 | 结构化JSON数据，无报表导出 | 简历优化建议、匹配分数 |
| 适用人群 | 企业HR、技术招聘、猎头、私有化部署团队 | 企业文档解析、通用简历数字化 | 个人求职者简历优化 |
| 开源协议 | MIT | Apache | MIT |
| 核心短板 | 仅支持PDF简历，无可视化Web界面 | 缺少技术能力量化评分，无开源贡献评估 | 无简历结构化抽取，不适合企业批量筛选 |
七、常见问题解答（FAQ）
Q：Hiring Agent 只能处理PDF格式简历吗？
A：是的，项目原生仅支持 PDF 简历解析，暂不兼容 Word、图片、HTML 等其他格式。如果需要拓展多格式支持，需要基于 PyMuPDF 新增 OCR 或 Word 解析模块进行二次开发。
Q：本地Ollama和云端Gemini该如何选择？
A：如果你对数据合规有较高要求，比如政企或金融团队，简历数据隐私比较敏感，那么优先选择 Ollama 本地离线部署，所有数据不会上传到第三方；如果需要对大量简历进行批量高速处理，但本地硬件算力又不够，那就选择 Gemini 云端方案。
Q：工具无法抓取候选人GitHub信息是什么原因？
A：可能有几种情况：一是简历里没有填写 GitHub 账号地址；二是没有配置 GITHUB_TOKEN 导致 GitHub API 限流；三是候选人将 GitHub 账号设为私有，接口无法读取仓库数据。可以补充 Token 或手动补充 GitHub 链接后重新执行。
Q：DEVELOPMENT_MODE开关有什么作用？关闭会有什么影响？
A：开启后会缓存 PDF 解析和 GitHub 接口的原始数据，同时生成 resume_evaluations.csv 评分报表；关闭后不再缓存，也不导出 CSV，仅在控制台输出单次评估结果，优点是减少本地磁盘占用。
Q：运行时出现Gemini接口限流报错该怎么解决？
A：项目中的 models.py 已经内置了指数退避加抖动的重试机制，会自动重试请求；如果仍然频繁报错，可以更换一个更高配额的 Gemini API Key，或者切换到 Ollama 本地模型来规避限流问题。
Q：可以自定义打分规则和评估标准吗？
A：完全可以。所有评分和抽取逻辑都放在 prompts 目录下的 Jinja 模板文件中，直接修改 resume_evaluation_criteria.jinja 等评分模板，就能自定义各个维度的分值以及加减分规则，完全无需改动底层的 Python 代码。
Q：没有GPU电脑可以运行Ollama本地模型吗？
A：没问题。Gemma3:1b 这个轻量化模型只靠普通 CPU 就能运行，只不过解析速度会稍慢一些；如果要用 12b 的大模型，建议配备 GPU 以提升推理效率。
八、官方链接
GitHub仓库：https://github.com/interviewstreet/hiring-agent
九、总结
Hiring Agent 是一套专门为技术招聘场景打造的开源端到端 AI 简历评估流水线。它借助 PDF 解析、大模型信息抽取以及 GitHub 开源履历挖掘能力，实现了标准化、可溯源的候选人量化打分。同时提供了本地离线与云端两套大模型运行方案，既能兼顾数据隐私，又能灵活调配算力资源。项目基于 MIT 协议完全开源，模块化的代码结构让企业可以很方便地进行二次开发或私有化部署。虽然目前只支持 PDF 简历、缺少原生 Web 前端界面，但在技术人才开源能力评估和批量简历自动化初筛这两个场景下，它拥有独特优势——对于中小技术团队、猎头以及企业研发招聘来说，是一个非常实用的轻量级 AI 筛选工具。