MatchMaker · Resume-Match System

基于 SBERT 与 LLM 的智能简历匹配系统，完整流程为：
PDF/文本预处理 -> 语义匹配（SBERT） -> 技能匹配 -> 综合评分 -> 建议生成（规则/LLM）

系统目标：

• 输入：简历 PDF + 岗位描述（文本或 PDF）
• 输出：语义分、技能分、综合分（0-100）+ 技能命中 + 可解释建议
• 形态：Gradio 可交互网页 Demo

1. 总体实现架构（对应实现方案）

模块	方案内容	当前实现
模块1：文本预处理	PyPDF2/pdfplumber + jieba	已实现 PyPDF2 + jieba（pdfplumber 未启用）
模块2：语义匹配	SBERT 余弦相似度	已实现，模型 paraphrase-multilingual-MiniLM-L12-v2
模块3：融合打分	0.6*semantic + 0.4*skill	已实现（技能侧使用加权重叠）
模块4：建议生成	关键点提取 + LLM + 结构化输出	已实现（规则默认，支持可选 LLM）
模块5：Demo 展示	Gradio/Streamlit + 图表	已实现 Gradio + matplotlib 图表

2. 快速启动

pip install -r requirements.txt
python app.py

启动后访问终端中的地址（通常是 http://127.0.0.1:7860）。

建议首次提前运行一次，SBERT 会下载模型文件，避免演示时等待。

3. 使用流程

1. 在页面顶部选择语言：中文 / English
2. 上传简历 PDF
3. 输入岗位描述（或上传岗位 PDF / 选择示例 JD）
4. 点击 计算匹配度（英文界面为 Run Match）
5. 查看：
   • 综合分、语义分、技能分（0-100）
   • 技能命中列表
   • 分数柱状图
   • 建议生成（规则或 LLM）

说明：语言切换会同步影响页面标签、提示信息、图表标题，以及建议输出（含 LLM 提示词与回退规则建议）。

4. 评分方法

• 语义相似度：SBERT 向量余弦相似度，范围 [0,1]
• 技能匹配度：基于词典与别名映射的技能重叠（含段落加权）
• 综合评分：

[ Score = 0.6 \times Sim_{semantic} + 0.4 \times Sim_{skill} ]

网页展示按百分制（0-100）。

5. 建议生成

5.1 关键点提取（规则模板）

• 自动抽取优势与短板（语义分、技能分、命中/缺失技能）

5.2 建议生成（可选 LLM）

• 默认：规则建议（无需联网）
• 可选：OpenAI 兼容接口（Qwen/ChatGLM/本地网关）

5.3 输出格式化（结构化）

• 以 Markdown 结构化展示：优势、短板、建议、生成状态

6. LLM 配置方式

支持两种方式：

• 页面直接输入（推荐演示）
• 环境变量预设（推荐长期使用）

6.1 页面配置项（优先级最高）

• 页面语言（中文 / English）
• 启用 LLM 生成建议
• 模型名称
• API Key
• Base URL
• 超时时间（秒）

6.2 环境变量配置（PowerShell）

$env:MATCHMAKER_LLM_MODEL="qwen3.6-plus"
$env:MATCHMAKER_LLM_API_KEY="your_api_key"
$env:MATCHMAKER_LLM_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
$env:MATCHMAKER_LLM_TIMEOUT_S="80"

6.3 参数优先级

• 模型名称：页面输入 > MATCHMAKER_LLM_MODEL
• API Key：页面输入 > MATCHMAKER_LLM_API_KEY
• Base URL：页面输入 > MATCHMAKER_LLM_BASE_URL
• 超时秒数：页面输入 > MATCHMAKER_LLM_TIMEOUT_S > 100

若 LLM 配置不完整或调用失败，系统会自动回退规则建议，不影响主流程打分。

7. 数据与实验资源

• JD 来源说明：data/jd/SOURCES.md
• JD 数据文件（未随仓库提交，需本地生成）：data/jd/job_descriptions_en_500.csv
• Kaggle 简历 CSV（本地准备，不提交到仓库）：data/resume/Resume.csv
• 技能词典（500+）：data/skills/skills_en_canonical.txt
• 技能别名映射：data/skills/skills_en_aliases.csv

为减小仓库体积，*.zip 与大体积 csv 默认通过 .gitignore 排除，不再上传到 GitHub。

8. 常用脚本

8.1 CSV 简历转 PDF（用于上传演示）

python scripts/csv_resume_to_pdf.py --csv data/resume/Resume.csv --id 16852973 --out-dir data/resume/pdf_export

输出：data/resume/pdf_export/resume_<ID>.pdf

8.2 批量打分（TSV）

python scripts/kaggle_resume_batch.py --csv data/resume/Resume.csv --job-text "your JD text" --limit 50 --output data/resume/scores.tsv

说明：

• semantic/skill/final 为 0-1（乘 100 为百分制）
• Excel/WPS 打开 .tsv 时分隔符选择 Tab

9. 项目结构

路径	说明
app.py	Gradio 界面与交互流程
matchmaker/pdf_parse.py	PDF 解析、清洗、分词
matchmaker/skills.py	技能词典加载、技能抽取与加权
matchmaker/scoring.py	SBERT 语义匹配与融合评分
matchmaker/recommendation.py	关键点提取、LLM 调用、结构化输出
scripts/	数据导出、批量评估、CSV 转 PDF

10. 注意事项

• 扫描版 PDF（图片）默认无法抽取文本，需要 OCR
• 技能词典当前以英文技能为主，纯中文技能描述命中可能偏低
• LLM 调用依赖外部服务可用性（网络、权限、额度、超时）