talent-align 0.1.1

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

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. 创建虚拟环境

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

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

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

3. 安装项目

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

# 或普通安装
pip install .

4. 配置 LLM 后端

talent-align 使用 llmdog 作为 LLM 调用接口,需要先配置 llmdog:

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

5. 验证安装

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

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

---

快速开始

第1步: 准备简历文件

将目标人选的简历文件准备好,支持以下格式:

• 纯文本: .txt, .md
• JSON: .json
• PDF: .pdf
• Excel: .xlsx, .xls(每行一份简历)

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

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

# 在当前目录创建 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

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

vim prompts_config.yaml

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

第3步: 构建职位画像

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

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

方式2: 从文件夹构建

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: 评估单个简历文件

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

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

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

方式3: 评估 Excel 中的简历

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 格式:

{
  "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):

# 特征提取提示词(必填)
# 必须包含 {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 参数指定配置文件:

# 构建画像时使用自定义提示词
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

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

# 复制示例配置
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 输出结构。例如,为技术岗位添加"代码能力"维度:

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. ✅ 占位符是否正确

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

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

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

---

命令参考

talent-align init

初始化提示词配置文件

talent-align init [OPTIONS]

选项:

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

作用与目的:

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

示例:

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

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

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

与其他命令的关系:

# 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

构建职位画像

talent-align build [OPTIONS]

选项:

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

示例:

# 从文件构建
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

评估候选人简历

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

示例:

# 评估单个文件
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: 技术岗位招聘

# 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: 产品岗位招聘

# 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: 快速评估(使用默认配置)

# 不需要自定义配置时,直接使用默认提示词
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 库使用:

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 的输出可能存在偏差或不准确的情况,不应作为唯一的人才评估依据。