Metadata-Version: 2.4
Name: talent-align
Version: 0.1.0
Summary: 基于 LLM 的简历画像构建与简历评估工具
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: llmdog>=0.0.3
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: pymupdf>=1.24.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# talent-align

基于 LLM 的简历画像构建与简历评估工具

## 项目简介

talent-align 是一个强大的命令行工具,利用大语言模型(LLM)实现:

1. **职位画像构建 (build)** - 从多份目标人选简历中提取特征,智能合并生成统一的职位画像
2. **简历评估 (eval)** - 以职位画像为基准,对候选人简历进行多维度匹配评估,输出结构化评分

### 核心特性

- ✅ 支持多种简历格式: TXT, MD, JSON, PDF, Excel
- ✅ 智能特征提取: 6大维度(基本信息/技术技能/业务能力/软技能/教育背景/其他特征)
- ✅ 增量合并策略: 逐份简历提取并合并,生成全面准确的职位画像
- ✅ 多维度评估: 5个评分维度 + 匹配亮点 + 差距分析 + 综合评价
- ✅ **自定义提示词**: 通过 YAML 配置文件完全自定义 LLM 提示词和评估维度
- ✅ 批量处理: 支持文件夹和 Excel 批量评估
- ✅ 错误容忍: 批量处理时单文件失败不中断

### 工作流程

```
简历文件 ──读取──> 纯文本 ──LLM提取──> 特征(MD) ──LLM合并──> 职位画像(MD)
                                                          │
候选人简历 ──读取──> 纯文本 ──LLM评估──> 评估结果(JSON) <──┘
```

---

## 安装指南

### 1. 环境要求

- Python >= 3.10
- 支持的操作系统: macOS, Linux, Windows

### 2. 创建虚拟环境

```bash
# 进入项目目录
cd /path/to/talent-align

# 创建虚拟环境
python3 -m venv venv

# 激活虚拟环境
# macOS/Linux:
source venv/bin/activate
# Windows:
venv\Scripts\activate
```

### 3. 安装项目

```bash
# 以可编辑模式安装(推荐,方便开发)
pip install -e .

# 或普通安装
pip install .
```

### 4. 配置 LLM 后端

talent-align 使用 [llmdog](https://github.com/) 作为 LLM 调用接口,需要先配置 llmdog:

```bash
# 配置 llmdog(具体配置方式参考 llmdog 文档)
# 通常需要设置 API Key 和模型提供商
```

### 5. 验证安装

```bash
# 查看帮助信息
talent-align --help

# 查看子命令帮助
talent-align build --help
talent-align eval --help
```

---

## 快速开始

### 第1步: 准备简历文件

将目标人选的简历文件准备好,支持以下格式:
- 纯文本: `.txt`, `.md`
- JSON: `.json`
- PDF: `.pdf`
- Excel: `.xlsx`, `.xls`(每行一份简历)

### 第2步: 初始化提示词配置(可选)

如果需要使用自定义提示词,先初始化配置文件:

```bash
# 在当前目录创建 prompts_config.yaml
talent-align init

# 输出示例:
# 初始化成功
# 配置文件已创建: /path/to/prompts_config.yaml
#
# 配置说明
# 1) 必填字段
#    - extract_prompt: 特征提取提示词(必须包含 {resume_text})
#    - merge_prompt: 特征合并提示词(必须包含 {existing_profile} 和 {new_features})
#    - evaluate_prompt: 简历评估提示词(必须包含 {profile} 和 {resume_text})
#
# 2) 自定义方法
#    - 修改提示词内容: 编辑 YAML 文件中的提示词文本
#    - 调整评估维度: 在 evaluate_prompt 中修改 JSON 模板的 dimension_scores
#    - 保持占位符: 确保 {resume_text} 等占位符不被删除
#
# 3) 使用配置
#    talent-align build -f ./resumes/ -c prompts_config.yaml
#    talent-align eval -p profile.md -i ./candidates/ -c prompts_config.yaml
```

然后用编辑器修改配置文件:

```bash
vim prompts_config.yaml
```

**注意**: 如果不使用 `-c` 参数,将使用内置默认提示词。

### 第3步: 构建职位画像

**方式1: 从多个简历文件构建**

```bash
talent-align build \
  -r resume1.pdf -r resume2.pdf -r resume3.md \
  -o output/profile \
  -m gpt-4
```

**方式2: 从文件夹构建**

```bash
talent-align build \
  -f ./target_resumes/ \
  -o output/profile \
  -m gpt-4
```

**参数说明:**
- `-r`: 指定简历文件路径(可多次使用)
- `-f`: 指定包含简历的文件夹
- `-o`: 输出目录(保存中间步骤和最终画像)
- `-m`: LLM 模型名称(可选)

**输出:**
- `output/profile/profile_step_1.md` - 第1份简历的特征
- `output/profile/profile_step_2.md` - 合并前2份的特征
- `output/profile/profile_final.md` - 最终职位画像

### 第4步: 评估候选人简历

**方式1: 评估单个简历文件**

```bash
talent-align eval \
  -p output/profile/profile_final.md \
  -i candidate_resume.pdf \
  -m gpt-4
```

**方式2: 评估文件夹中的所有简历**

```bash
talent-align eval \
  -p output/profile/profile_final.md \
  -i ./candidate_resumes/ \
  -m gpt-4
```

**方式3: 评估 Excel 中的简历**

```bash
talent-align eval \
  -p output/profile/profile_final.md \
  -i candidates.xlsx \
  -m gpt-4
```

**参数说明:**
- `-p`: 职位画像文件(必需)
- `-i`: 待评估的简历路径(文件/文件夹/Excel)
- `-m`: LLM 模型名称(可选)

**输出:**
- 单文件: `candidate_resume_eval.md`(JSON格式评估结果)
- 文件夹: `candidate_resumes_eval/` 目录,每份简历一个评估文件
- Excel: `candidates_eval.xlsx`,在原表最后追加 `eval_result` 列

### 第4步: 查看评估结果

评估结果为 JSON 格式:

```json
{
  "overall_score": 85,
  "dimension_scores": {
    "technical_skills": 90,
    "business_ability": 80,
    "soft_skills": 75,
    "education": 85,
    "experience": 88
  },
  "highlights": ["精通 Java 微服务架构", "5年以上大型项目经验"],
  "gaps": ["缺乏云原生经验", "英语能力未体现"],
  "summary": "候选人技术能力突出,业务理解良好,建议重点考察云原生和英语能力。"
}
```

---

## 自定义提示词配置

talent-align 支持通过 YAML 配置文件完全自定义 LLM 提示词,让你可以根据不同岗位类型(技术岗/产品岗/设计岗等)调整评估标准。

### 1. 配置文件结构

创建 YAML 配置文件(如 `my_prompts.yaml`):

```yaml
# 特征提取提示词(必填)
# 必须包含 {resume_text} 占位符
extract_prompt: |
  你是一位资深技术招聘专家...
  
  简历内容:
  {resume_text}
  
  要求:
  1. ...

# 特征合并提示词(必填)
# 必须包含 {existing_profile} 和 {new_features} 占位符
merge_prompt: |
  合并以下两个职位画像...
  
  已有画像:
  {existing_profile}
  
  新提取的特征:
  {new_features}

# 简历评估提示词(必填)
# 必须包含 {profile} 和 {resume_text} 占位符
evaluate_prompt: |
  评估候选人与职位的匹配度...
  
  职位画像:
  {profile}
  
  候选人简历:
  {resume_text}
  
  输出 JSON 格式:
  {{
    "overall_score": 0-100,
    ...
  }}
```

### 2. 必填字段说明

| 字段 | 说明 | 必填占位符 |
|------|------|-----------|
| `extract_prompt` | 从简历提取特征的提示词 | `{resume_text}` |
| `merge_prompt` | 合并多份简历特征的提示词 | `{existing_profile}`, `{new_features}` |
| `evaluate_prompt` | 评估简历匹配度的提示词 | `{profile}`, `{resume_text}` |

### 3. 占位符说明

- `{resume_text}`: 简历纯文本内容
- `{existing_profile}`: 已有职位画像(Markdown)
- `{new_features}`: 新提取的特征(Markdown)
- `{profile}`: 职位画像(Markdown)

**注意**: 在 YAML 中使用 `{` 和 `}` 时,如果是 JSON 模板需要双写为 `{{` 和 `}}`(参考 `evaluate_prompt` 示例)

### 4. 使用自定义配置

通过 `--config` 或 `-c` 参数指定配置文件:

```bash
# 构建画像时使用自定义提示词
talent-align build \
  -f ./target_resumes/ \
  -o output/profile \
  -c my_prompts.yaml \
  -m gpt-4

# 评估简历时使用自定义提示词
talent-align eval \
  -p output/profile/profile_final.md \
  -i ./candidates/ \
  -c my_prompts.yaml \
  -m gpt-4
```

### 5. 完整配置示例

项目提供了完整的配置示例文件: [examples/prompts_config.yaml](examples/prompts_config.yaml)

你可以复制此文件并根据需要修改:

```bash
# 复制示例配置
cp examples/prompts_config.yaml my_custom_prompts.yaml

# 编辑配置文件
vim my_custom_prompts.yaml

# 使用自定义配置
talent-align build -f ./resumes/ -c my_custom_prompts.yaml
```

### 6. 自定义评估维度

你可以在 `evaluate_prompt` 中自定义评估维度和 JSON 输出结构。例如,为技术岗位添加"代码能力"维度:

```yaml
evaluate_prompt: |
  评估候选人与技术岗位的匹配度...
  
  职位画像:
  {profile}
  
  候选人简历:
  {resume_text}
  
  输出 JSON 格式:
  {{
    "overall_score": 0-100,
    "dimension_scores": {{
      "technical_skills": 0-100,
      "coding_ability": 0-100,
      "system_design": 0-100,
      "business_ability": 0-100,
      "soft_skills": 0-100,
      "education": 0-100,
      "experience": 0-100
    }},
    "highlights": [],
    "gaps": [],
    "summary": ""
  }}
```

### 7. 配置验证

加载配置文件时,talent-align 会自动验证:

1. ✅ 文件是否存在
2. ✅ YAML 格式是否正确
3. ✅ 必填字段是否完整
4. ✅ 占位符是否正确

如果验证失败,会显示清晰的错误提示:

```bash
$ talent-align build -f ./resumes/ -c invalid_config.yaml

配置错误: 配置文件缺少必填字段: merge_prompt
必填字段: extract_prompt, merge_prompt, evaluate_prompt
```

---

## 命令参考

### talent-align init

初始化提示词配置文件

```bash
talent-align init [OPTIONS]
```

**选项:**

| 选项 | 短选项 | 类型 | 默认值 | 说明 |
|------|--------|------|--------|------|
| `--output` | `-o` | PATH | 当前目录/prompts_config.yaml | 输出路径 |
| `--force` | `-f` | FLAG | False | 覆盖已存在的配置文件 |

**作用与目的:**

- 快速创建 YAML 配置文件,无需手动复制
- 提供详细的配置指导,帮助用户理解必填字段和占位符
- 降低新用户上手门槛

**示例:**

```bash
# 在当前目录创建默认配置文件
talent-align init

# 创建到指定路径
talent-align init -o configs/tech_role.yaml

# 强制覆盖已存在的文件
talent-align init -f
```

**与其他命令的关系:**

```bash
# 1. 初始化配置文件
talent-align init -o my_config.yaml

# 2. 编辑配置文件(手动)
vim my_config.yaml

# 3. 使用配置文件构建画像
talent-align build -f ./resumes/ -c my_config.yaml

# 4. 使用配置文件评估简历
talent-align eval -p profile.md -i ./candidates/ -c my_config.yaml
```

### talent-align build

构建职位画像

```bash
talent-align build [OPTIONS]
```

**选项:**

| 选项 | 短选项 | 类型 | 说明 |
|------|--------|------|------|
| `--resume` | `-r` | PATH | 目标画像简历文件(可多次指定) |
| `--folder` | `-f` | PATH | 包含目标画像简历的文件夹 |
| `--output` | `-o` | PATH | 输出目录 |
| `--model` | `-m` | TEXT | LLM 模型名称 |
| `--config` | `-c` | PATH | YAML 提示词配置文件路径 |

**示例:**

```bash
# 从文件构建
talent-align build -r resume1.pdf -r resume2.md -o output

# 从文件夹构建
talent-align build -f ./resumes/ -o output -c custom.yaml

# 指定模型
talent-align build -f ./resumes/ -m gpt-4-turbo
```

### talent-align eval

评估候选人简历

```bash
talent-align eval [OPTIONS]
```

**选项:**

| 选项 | 短选项 | 类型 | 必填 | 说明 |
|------|--------|------|------|------|
| `--profile` | `-p` | PATH | ✅ | 职位画像 Markdown 文件 |
| `--input` | `-i` | PATH | ✅ | 待评估简历路径 |
| `--model` | `-m` | TEXT | ❌ | LLM 模型名称 |
| `--config` | `-c` | PATH | ❌ | YAML 提示词配置文件路径 |

**输入类型支持:**

| 输入 | 判断条件 | 输出 |
|------|----------|------|
| 单文件 | `.txt`/`.md`/`.json`/`.pdf` | `{stem}_eval.md` |
| 文件夹 | `is_dir()` | `{folder_stem}_eval/` |
| Excel | `.xlsx`/`.xls` | `{stem}_eval.xlsx` |

**示例:**

```bash
# 评估单个文件
talent-align eval -p profile.md -i candidate.pdf

# 评估文件夹
talent-align eval -p profile.md -i ./candidates/ -c custom.yaml

# 评估 Excel
talent-align eval -p profile.md -i candidates.xlsx
```

---

## 使用场景示例

### 场景1: 技术岗位招聘

```bash
# 1. 使用技术岗专用提示词配置
talent-align build \
  -f ./senior_java_resumes/ \
  -o output/java_dev \
  -c configs/tech_role.yaml

# 2. 评估候选人
talent-align eval \
  -p output/java_dev/profile_final.md \
  -i ./applicants/ \
  -c configs/tech_role.yaml
```

### 场景2: 产品岗位招聘

```bash
# 1. 构建产品岗画像
talent-align build \
  -r pm1.pdf -r pm2.pdf -r pm3.md \
  -o output/pm \
  -c configs/product_role.yaml

# 2. 批量评估 Excel 中的候选人
talent-align eval \
  -p output/pm/profile_final.md \
  -i candidates_list.xlsx \
  -c configs/product_role.yaml
```

### 场景3: 快速评估(使用默认配置)

```bash
# 不需要自定义配置时,直接使用默认提示词
talent-align build -f ./resumes/ -o output
talent-align eval -p output/profile_final.md -i ./candidates/
```

---

## 常见问题

### Q1: 如何配置 llmdog?

talent-align 依赖 llmdog 调用 LLM,请参考 llmdog 的文档配置 API Key 和模型提供商。

### Q2: 支持哪些 LLM 模型?

取决于你配置的 llmdog 后端,理论上支持所有主流模型(GPT-4, Claude, 文心一言等)。

### Q3: 自定义提示词时忘记了占位符怎么办?

配置文件加载时会自动验证占位符,如果缺失会显示明确的错误提示。参考 `examples/prompts_config.yaml` 确保包含所有必填占位符。

### Q4: 评估结果不准确如何调整?

可以通过自定义 `evaluate_prompt` 调整评估标准和输出格式,让 LLM 更关注你关心的维度。

### Q5: 批量处理时部分文件失败怎么办?

talent-align 设计了错误容忍机制,单文件失败会记录错误信息并继续处理,不会中断整个流程。

### Q6: 如何查看中间合并结果?

使用 `-o` 参数指定输出目录,系统会自动保存每步的中间结果(`profile_step_1.md`, `profile_step_2.md` 等)。

---

## 项目结构

```
talent-align/
├── src/talent_align/
│   ├── __init__.py          # 公共 API 导出
│   ├── cli.py               # 命令行接口
│   ├── config.py            # YAML 配置加载
│   ├── prompts.py           # 默认提示词模板
│   ├── reader.py            # 文件读取层
│   ├── extractor.py         # 画像构建层
│   └── evaluator.py         # 简历评估层
├── examples/
│   └── prompts_config.yaml  # 配置示例
├── pyproject.toml           # 项目配置
└── README.md                # 本文档
```

---

## 公共 API

talent-align 也可作为 Python 库使用:

```python
from talent_align import (
    build_profile_from_files,
    build_profile_from_folder,
    extract_features,
    merge_features,
    evaluate_resume,
    evaluate_file,
    evaluate_folder,
    evaluate_excel,
)
from talent_align.config import load_prompts_config

# 加载自定义配置
prompts_config = load_prompts_config("my_prompts.yaml")

# 构建画像
profile = build_profile_from_folder(
    folder=Path("./resumes/"),
    output_dir=Path("./output/"),
    prompts_config=prompts_config,
)

# 评估简历
result = evaluate_file(
    profile=profile,
    input_file=Path("candidate.pdf"),
    prompts_config=prompts_config,
)
```

---

## 技术栈

- **llmdog** >= 0.0.3 - LLM 调用接口
- **typer** >= 0.12.0 - CLI 框架
- **rich** >= 13.0.0 - 终端富文本输出
- **openpyxl** >= 3.1.0 - Excel 文件读写
- **PyMuPDF** >= 1.24.0 - PDF 文本提取
- **pyyaml** >= 6.0 - YAML 配置解析

---

## 许可

MIT License

---

## 免责声明

1. **学习研究用途**: 本工具仅供学习和研究使用,不应用于实际的生产环境或关键业务决策。

2. **合规使用**: 用户在使用本工具时应遵守所在国家或地区的相关法律法规,特别是关于个人信息保护和数据隐私的相关规定。未经候选人明确同意,不得对其简历数据进行自动化评估。

3. **责任限制**: 开发者不对因使用本工具而产生的任何直接或间接后果承担责任,包括但不限于数据损失、评估结果偏差、决策失误等。用户应自行承担使用本工具的全部风险。

4. **商业使用建议**: 如计划将本工具用于商业用途,建议在使用前进行充分的测试和验证,确保评估结果的准确性和公平性,并建议结合人工审核进行综合判断。

5. **LLM 输出说明**: 本工具依赖大型语言模型生成评估结果,LLM 的输出可能存在偏差或不准确的情况,不应作为唯一的人才评估依据。


