interviewstreet hiring-agent

以下是您要求的英文文章的中文翻译，已按照您指定的格式和规则进行输出。

interviewstreet hiring-agent

概述

Hiring Agent 简历到评分（Resume-to-Score）管道，可从 PDF 中提取结构化数据，通过 GitHub 信号进行丰富，并输出公平、可解释的评估结果。

概述

Hiring Agent 将简历 PDF 解析为 Markdown，使用本地或托管的 LLM 提取分段的 JSON，通过 GitHub 个人资料和仓库信号增强数据，然后生成包含类别评分、证据、加分项和扣分项的客观评估。您可以完全在本地使用 Ollama 运行，也可以使用 Google Gemini。

架构

流程

pymupdf_rag.py 将 PDF 页面转换为类似 Markdown 的文本。
pdf.py 使用 prompts/templates 下的 Jinja 模板，按段落调用 LLM。
github.py 获取个人资料和仓库，对项目进行分类，并让 LLM 选择前 7 个。
evaluator.py 运行带有公平性约束的严格评分评估。
score.py 端到端地协调所有步骤，并在开发模式下写入 CSV。

关键模块

models.py：Pydantic 模式和 LLM 提供商接口。
llm_utils.py：提供商初始化和响应清理。
transform.py：将松散的 LLM JSON 规范化为 JSON Resume 风格。
prompts/：所有用于提取和评分的 Jinja 模板。

安装与设置

前提条件

Python 3.11+
仓库将 .python-version 锁定为 3.11.13。
一个 LLM 后端（任选其一）
Ollama：用于本地模型。从[官方网站](https://ollama.com)安装，然后运行 ollama serve。
Google Gemini：如果您有 API 密钥，请从[此处](https://aistudio.google.com/apikey)获取。

使用 pip 快速设置

$ git clone https://github.com/interviewstreet/hiring-agent
$ cd hiring-agent
$ python -m venv .venv
# Linux 或 macOS
$ source .venv/bin/activate
# Windows
# .venv\Scripts\activate
$ pip install -r requirements.txt

Ollama 模型

拉取您想要使用的模型。例如：

$ ollama pull gemma3:4b

如果您想要不同的结果，可以拉取其他模型，例如：

# 适用于较高系统配置
$ ollama pull gemma3:12b
# 适用于较低系统配置
$ ollama pull gemma3:1b

配置

复制模板并设置您的环境变量。

$ cp .env.example .env

环境变量

| 变量 | 值 | 描述 | | :--- | :--- | :--- | | LLM_PROVIDER | ollama 或 gemini | 选择提供商。默认为 Ollama。 | | DEFAULT_MODEL | 例如 gemma3:4b 或 gemini-2.5-pro | 传递给提供商的模型名称。 | | GEMINI_API_KEY | 字符串 | 当 LLM_PROVIDER=gemini 时必需。 | | GITHUB_TOKEN | 可选 | 继承自您的 shell 环境，可提高 GitHub API 速率限制。 |

提供商映射位于 prompt.py 和 models.py 中。config.py 文件包含一个单一标志：

# config.py
DEVELOPMENT_MODE = True # 启用缓存和 CSV 导出

您可以在迭代期间保持其开启状态。详情请参阅下一节。

工作原理

1) PDF 提取

pymupdf_rag.py 和 pdf.py 使用 PyMuPDF 读取 PDF，并将页面转换为类似 Markdown 的文本。to_markdown 例程处理标题、链接、表格和基本格式。

2) 段落解析与模板

prompts/templates/*.jinja 为每个段落（基本信息、工作经历、教育背景、技能、项目、奖项）定义了严格的指令。pdf.PDFHandler 按段落调用 LLM，并组装成一个 JSONResume 对象（参见 models.py）。

3) GitHub 信息增强

github.py 从简历个人资料中提取用户名，获取个人资料和仓库，并对每个项目进行分类。它让 LLM 选择恰好 7 个独特的项目，并设置最低作者提交阈值，倾向于有意义的贡献。

4) 评估

evaluator.py 使用编码了公平性和评分规则的模板。评分包括 open_source、self_projects、production 和 technical_skills，外加加分项和扣分项，最后提供证据解释。

5) 输出与 CSV 导出

score.py 向标准输出打印可读的摘要。当 DEVELOPMENT_MODE=True 时，它会创建或追加一个包含关键字段的 resume_evaluations.csv 文件，并将中间 JSON 缓存到 cache/ 目录下。

CLI 使用

端到端评分

提供简历 PDF 的路径。

$ python score.py /path/to/resume.pdf

执行过程：

如果开发模式开启，PDF 提取结果将缓存到 cache/resumecache_.json。
如果在简历中找到 GitHub 个人资料，将获取仓库并缓存到 cache/githubcache_.json。
评估器打印一份报告，并且在开发模式下，将一行 CSV 数据追加到 resume_evaluations.csv。

目录布局

.
├── .env.example
├── .python-version
├── config.py
├── evaluator.py
├── github.py
├── llm_utils.py
├── models.py
├── pdf.py
├── prompt.py
├── prompts/
│   ├── template_manager.py
│   └── templates/
│       ├── awards.jinja
│       ├── basics.jinja
│       ├── education.jinja
│       ├── github_project_selection.jinja
│       ├── projects.jinja
│       ├── resume_evaluation_criteria.jinja
│       ├── resume_evaluation_system_message.jinja
│       ├── skills.jinja
│       ├── system_message.jinja
│       └── work.jinja
├── pymupdf_rag.py
├── requirements.txt
├── score.py
└── transform.py

提供商详情

Ollama

设置 LLM_PROVIDER=ollama
设置 DEFAULT_MODEL 为任何已拉取的模型，例如 gemma3:4b
models.OllamaProvider 中的提供商包装器调用 ollama.chat

Gemini

设置 LLM_PROVIDER=gemini
设置 DEFAULT_MODEL 为支持的 Gemini 模型，例如 gemini-2.0-flash
提供 GEMINI_API_KEY
models.GeminiProvider 中的包装器将响应适配为统一格式

贡献指南

请阅读 CONTRIBUTING.md 以获取关于提交问题、提议更改和提交拉取请求的详细指南。关键原则包括：

保持提示的声明性和提供商无关性。
使用不同提供商下的几份真实简历验证更改。
添加或调整无单元冒烟测试，以最小输入调用每个阶段。

interviewstreet hiring-agent