Hiring Agent：开源AI简历评估工具，自动解析PDF简历+GitHub技术能力打分

一、Hiring Agent 是什么

先直接说结论：

是由 HackerRank（也就是 interviewstreet）开源、基于 Python 构建的一套，采用 MIT 协议，专门为技术岗位招聘场景量身打造。它能读取 PDF 简历，借助大模型把简历信息标准化提取出来，还能自动抓取候选人 GitHub 上的开源履历作为补充评估维度——最终输出一份带有证据、可以回溯的客观候选人评分报告。说白了，就是为了解决传统人工筛选效率低、主观偏差大、技术能力难以量化这些招聘痛点。

整套工具支持两套大模型运行方案：本地离线用 Ollama 跑开源模型，或者用云端的 Google Gemini。这么设计的好处是，既能照顾数据隐私，又能利用云端算力。全程都在命令行里跑，支持缓存，还能批量导出 CSV 评分报表，并且可以二次开发对接企业内部招聘系统。

二、核心功能特色

1. PDF简历结构化解析
   
   基于 PyMuPDF 把 PDF 简历转换成带排版信息的 Markdown，自动识别标题、表格、链接，然后分模块（基础信息、工作经历、教育背景、技能、项目、奖项）通过定制提示词提取出标准的 JSON Resume 数据。这样一来，那些格式混乱的简历文本就能被机器识别了。

2. GitHub履历自动增强评估
   
   自动提取简历里的 GitHub 账号，调用 GitHub API 获取个人主页和全部仓库，然后让大模型从中筛选出 7 个高贡献的优质开源项目，量化开源贡献、个人项目、工程落地经验这三个技术维度，精准评估开发者的实战能力。支持配置 GitHub Token 来提高接口调用限额。

3. 公平可解释多维度打分体系
   
   内置了一套公平约束评分规则，分为开源贡献、个人项目、生产项目、专业技术技能四大核心打分项，同时记录每项分数对应的简历原文证据，附带加分项和扣分项明细——彻底杜绝了 AI 主观评判的黑箱问题，HR 可以完整追溯评分依据。

4. 双大模型兼容切换
   
   一套代码就能无缝切换两种 LLM 后端：Ollama 本地离线部署（Gemma3 系列模型，数据本地存储不泄露），或者 Google Gemini 云端 API（适合高速批量处理大量简历），而且可以自由配置模型版本。

5. 本地缓存与批量报表导出
   
   开启开发模式后，会自动缓存 PDF 解析结果和 GitHub 接口原始数据，减少重复调用 LLM 和第三方 API；还能自动生成 resume_evaluations.csv 批量评分文件，方便数据归档和统计分析。

6. 完善工程化容错机制
   
   内置了 Gemini 接口的指数退避加抖动限流策略，修复了简历解析失败后的缓存异常问题，统一清洗大模型返回的不规范 JSON，代码统一采用 Black 格式化规范，方便后续迭代维护。

7. 全流程命令行极简调度
   
   只需要一条命令就能完成完整的简历评估，不需要复杂的可视化操作，轻量无前端依赖，既能在服务器上跑，也能在本地 PC 上离线运行。

三、技术细节

3.1 整体流水线架构（5阶段执行链路）

1. PDF文本转换：pymupdf_rag.py 负责把 PDF 转成 Markdown 结构化文本；

2. 简历信息抽取：pdf.py 加载 prompts/templates 下的 Jinja 提示词，分模块调用 LLM 生成标准简历 JSON；

3. GitHub数据拉取与筛选：github.py 抓取仓库数据，大模型筛选优质开源项目；

4. 标准化候选人评估：evaluator.py 加载评分规则模板，生成带证据的分项得分；

5. 结果输出调度：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 环境依赖与技术栈

1. 运行环境：固定 Python 3.11.13，项目自带 .python-version 文件锁定版本；

2. PDF解析：PyMuPDF；

3. LLM后端二选一：Ollama（Gemma3:1b/4b/12b本地模型）、Google Gemini（gemini-2.0-flash/gemini-2.5-pro）；

4. 配置管理：.env 环境变量配置，区分模型厂商、API密钥、GitHub令牌；

5. 数据格式：Jinja2 提示词模板、JSON Resume 标准简历结构、CSV 报表；

6. 代码规范：Black 统一代码格式化，MIT 开源协议。

四、应用场景

1. 技术团队校招/社招批量简历初筛
   
   不管是研发、后端、前端、算法还是运维，技术岗的海量简历可以通过这套工具自动化初筛，替代人工通读，快速过滤掉匹配度低的候选人，显著提升招聘效率。

2. 开源开发者专项人才挖掘
   
   如果岗位特别看重开源能力，工具可以自动量化候选人的 GitHub 项目贡献，精准筛选出那些拥有实战经验和开源协作经验的工程师。

3. 企业内部人才库标准化打分归档
   
   批量评估历史简历，导出 CSV 统一存储评分数据，逐步建立起可检索、可量化的技术人才库。

4. 外包/猎头技术候选人快速背调
   
   不需要人工去翻 GitHub 主页，工具会自动完成开源履历评估，大大降低猎头的人工核验成本。

5. 私有化合规招聘场景
   
   如果使用 Ollama 本地模型离线运行，简历和候选人数据全程都在本地存储，完全满足金融、政企等数据不出内网的合规要求。

6. 二次开发集成
   
   基于开源代码封装 API，可以对接企业自研的 ATS 招聘系统、内部 OA 或者人才管理平台。

五、完整使用方法

5.1 环境前置准备

1. 安装 Python 3.11.13；

2. 二选一部署LLM：

• 本地方案：安装 Ollama，执行 ollama pull gemma3:4b 拉取开源模型；

• 云端方案：申请 Google Gemini API Key；

3. （可选）获取 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-pro

• GEMINI_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）

A：是的，项目原生仅支持 PDF 简历解析，暂不兼容 Word、图片、HTML 等其他格式。如果需要拓展多格式，需要基于 PyMuPDF 新增 OCR 或 Word 解析模块做二次开发。

A：如果你对数据合规有要求，比如政企或金融团队，简历隐私比较敏感，那优先选 Ollama 本地离线部署，所有数据不会上传到第三方；如果需要对大量简历做批量高速处理，但本地硬件算力又不够，那就选 Gemini 云端方案。

A：可能有几种情况：一是简历里没有填写 GitHub 账号地址；二是没有配置 GITHUB_TOKEN 导致 GitHub API 限流；三是候选人把 GitHub 账号设成了私有，接口无法读取仓库数据。可以补充 Token 或者手动补充 GitHub 链接重新执行。

A：开启后会缓存 PDF 解析和 GitHub 接口的原始数据，同时生成 resume_evaluations.csv 评分报表；关闭后不再缓存，也不导出 CSV，只在控制台输出单次评估结果，好处是减少本地磁盘占用。

A：项目里的 models.py 已经内置了指数退避加抖动的重试机制，会自动重试请求；如果还是频繁报错，可以换一个更高配额的 Gemini API Key，或者切换到 Ollama 本地模型来规避限流。

A：完全可以。所有评分和抽取逻辑都放在 prompts 目录下的 Jinja 模板文件里，直接修改 resume_evaluation_criteria.jinja 等评分模板，就能自定义各维度的分值以及加分扣分规则，完全不需要动底层的 Python 代码。

A：没问题。Gemma3:1b 这个轻量化模型只用普通 CPU 就能跑，只不过解析速度会慢一些；如果要用 12b 的大模型，建议还是配 GPU 来提升推理效率。

八、官方链接

• GitHub仓库：https://github.com/interviewstreet/hiring-agent

九、总结

Hiring Agent 是一套专门为技术招聘打造的开源端到端 AI 简历评估流水线。它借助 PDF 解析、大模型信息抽取以及 GitHub 开源履历挖掘能力，实现了标准化、可溯源的候选人量化打分。同时提供了本地离线与云端两套大模型运行方案，既能照顾数据隐私，又能兼顾算力灵活性。项目基于 MIT 协议完全开源，模块化的代码结构让企业可以很方便地二次开发或私有化部署。虽然目前只支持 PDF 简历、没有原生 Web 前端界面，但在技术人才开源能力评估和批量简历自动化初筛这两个场景下，有它独特的优势——对于中小技术团队、猎头以及企业研发招聘来说，是一个轻量级 AI 筛选工具的不错选择。