Hiring Agent 是一个由 HackerRank 开源的简历评估工具，它能从 PDF 简历中提取结构化信息，结合 GitHub 信号，生成一份公平且可解释的评估报告。本教程将指导你完成部署和使用。

1. 了解项目定位

项目背景与目的

HackerRank 每年收到 50,000-60,000 份实习申请，无法全部人工阅读。此工具的作用是帮助筛选简历，决定优先阅读哪些。它将打分线设置得很低，只过滤掉底部极少数申请者，绝大多数人都会进入人工审核阶段。

⚠️ 重要澄清

  • 这不是一个ATS（应聘者跟踪系统），也不是 HackerRank 的商业产品。
  • 仓库默认使用 gemma4:latest 等本地模型，因为无需API密钥即可运行。生产环境实际使用的是顶级 Gemini 模型，仓库仅提供示例配置。

项目局限性与争议

项目 README 坦诚地讨论了以下问题，使用时需特别注意：

  • 分数波动性：同一份简历多次运行可能得到不同分数（Dan Kinsky的分析指出技术技能部分稳定，项目质量判断则噪声较大）。
  • 可被利用的风险：PDF 中嵌入不可见文本可能大幅提升分数。
  • 评分偏差：GitHub 为中心的评分标准可能对主要在私有仓库工作的工程师不利。
  • 伦理考量：自动筛选简历涉及 GDPR 第22条等伦理问题。

2. 部署前准备

硬件与系统要求

  • 操作系统：Windows、Linux 或 macOS。
  • Python版本：3.11+（项目使用 3.11.13，推荐保持一致）。
  • 网络：需访问 GitHub API（如需获取GitHub信号）。

LLM 后端选择

你需要选择一种 LLM 后端来驱动评估：

  1. 本地运行（Ollama）：推荐入门。从 Ollama官网 安装，可拉取 gemma4:latest（默认）、gemma3:12b（较高配置）或 gemma3:1b（较低配置）等模型。
  2. 云端API：需获取 Google Gemini API 密钥。

3. 安装步骤

步骤1：克隆仓库并设置虚拟环境

1
2
3
4
5
6
7
8
9
git clone https://github.com/interviewstreet/hiring-agent
cd hiring-agent

# 创建并激活Python虚拟环境
python -m venv .venv
# Linux/macOS:
source .venv/bin/activate
# Windows:
# .venv\Scripts\activate

步骤2：安装Python依赖

1
pip install -r requirements.txt

步骤3：配置环境变量

1
2
# 复制示例配置文件
cp .env.example .env

编辑 .env 文件，设置你的 LLM 后端：

1
2
3
4
5
6
7
8
# 选择模型，例如 gemma4:latest 或 gemini-2.5-pro
DEFAULT_MODEL=gemma4:latest

# 如使用Gemini，需填写API密钥
GEMINI_API_KEY=你的Gemini_API_密钥

# 可选，可提高GitHub API速率限制
GITHUB_TOKEN=你的GitHub_Personal_Access_Token

模型与提供商的映射关系在 providers.json 中定义，DEFAULT_MODEL 必须存在于该文件中。

步骤4：安装并运行Ollama（如使用本地模型）

1
2
# 拉取默认模型
ollama pull gemma4:latest

4. 核心配置

配置文件 config.py

该文件包含一个关键标志：

1
DEVELOPMENT_MODE = True  # 开启缓存和CSV导出

建议在迭代测试时保持开启，它能缓存中间结果（cache/ 目录）并导出CSV文件（resume_evaluations_<role>.csv）。

角色（Role）配置

项目采用“角色”来定义不同的评估维度。内置角色为 software_engineering_intern。角色目录结构如下：

1
2
3
4
roles/software_engineering_intern/
├── role.json           # 类别、权重、最高分等
├── criteria.jinja      # 评估标准提示词
└── system_message.jinja

要添加新角色，可使用 --init-role 命令：

1
python score.py --init-role backend_engineer

这将创建一个新角色目录，然后你可以编辑其中的 role.json 和提示词文件来定制评估维度。

5. 使用方法

基本评分命令

1
python score.py ./路径/到/简历.pdf --role software_engineering_intern

--role 参数是必需的。它告诉系统使用哪个角色目录下的评分规则。

工作流程

  1. PDF提取：使用 pymupdf_rag.py 将PDF转换为Markdown式文本。
  2. 分节解析：使用 prompts/templates/ 下的 Jinja 模板，分别提取基础信息、工作经历、教育背景、技能、项目、奖项等部分，生成结构化的 JSON。
  3. GitHub增强：从简历中提取 GitHub 用户名，获取用户档案和仓库信息，并由 LLM 筛选出最多7个有意义的项目。
  4. 评估打分：evaluator.py 根据指定角色的规则进行评分，输出包含类别分数、证据、加分和扣分的报告。
  5. 输出：终端打印摘要；若 DEVELOPMENT_MODE=True，会追加记录到 CSV 文件。

6. 性能优化与故障排查

常见问题

  • DEFAULT_MODEL 未生效：确保已正确配置 .env 文件，且 config.py 中正确加载了 python-dotenv。
  • Ollama 连接失败：确认 Ollama 服务正在运行 (ollama serve)，且 providers.json 中的 base_url 指向 http://localhost:11434/v1。
  • GitHub API 速率限制：设置 GITHUB_TOKEN 环境变量可提高限制。
  • 分数波动：这是LLM非确定性的固有特性。可通过多次运行取平均、使用更稳定的模型（如Gemini）或调整评分标准来缓解。

贡献与改进

项目欢迎贡献，但需遵循以下原则：

  • 保持提示词声明式且与提供商无关。
  • 用真实简历在不同提供商下验证更改。
  • 添加针对各阶段最小输入的单元测试。

总结

Hiring Agent 是一个透明但需谨慎使用的简历评估工具。它非常适合用于初步筛选海量简历，但不应作为最终决策的唯一依据。部署相对简单，你可以在几分钟内用本地模型启动并运行。

建议：

  • 充分理解其局限性和伦理风险，特别是在自动决策场景下。
  • 在生产环境中，考虑使用更强大、更稳定的模型（如 Gemini），并搭建一套监控和审计机制来追踪评分一致性和潜在偏差。
  • 鼓励候选人自行使用社区工具（如 Resume Reality Check）了解自己的评分，减少“黑箱”感。

你可以从 python score.py ./resume/sample.pdf --role software_engineering_intern 开始，体验完整的评估流程。