gabzz/cv-matcher

CV Matcher 🎯

一个AI驱动的Python库，用于分析简历与职位描述的匹配度。获取匹配分数、识别缺失技能，并接收专业的格式建议以改进简历。

✨ 内置Web UI，搭配OpenAI GPT-4实现最佳性能 ✨

https://img.shields.io/badge/python-3.9+-blue.svg](https://www.python.org/downloads/) https://img.shields.io/badge/License-MIT-yellow.svg](https://opensource.org/licenses/MIT)

特性 ✨

• 🌐 Web界面：基于Gradio的美观界面 - 无需编码！
• 🤖 AI驱动分析：使用OpenAI GPT-4进行智能、准确的分析
• 🔓 本地模型选项：支持本地AI模型（Phi-3、***等）- 无需API密钥
• 📄 PDF简历解析：轻松从PDF简历中提取文本
• 🔍 职位描述获取：支持文本形式的职位描述或从URL获取
• 📊 详细匹配评分：获取技能、经验、教育背景和关键词的匹配分数
• 💡 格式建议：接收可操作的建议以改进简历
• 🎨 美观输出：丰富、彩色的终端和Web界面
• 📤 结果导出：将分析结果保存为JSON以便进一步处理

安装 📦

使用pip

bash
pip install cv-matcher

# 创建配置文件.env
cp .env.example .env

# 编辑.env并设置偏好：
# - USE_LOCAL_MODEL=false（使用OpenAI，推荐）
# - USE_LOCAL_MODEL=true（使用本地模型，无需API密钥）
# - OPENAI_API_KEY=your-key-here（若USE_LOCAL_MODEL=false则必填）

仅本地模型

bash
# 安装包含本地模型依赖的版本
pip install cv-matcher[local]

# 在.env中设置USE_LOCAL_MODEL=true
echo "USE_LOCAL_MODEL=true" > .env

使用uv（推荐用于开发）

bash
# 若未安装uv，先安装
curl -LsSf https://astral.sh/uv/install.sh | sh

# 克隆仓库
git clone https://github.com/yourusername/cv-matcher.git
cd cv-matcher

# 创建虚拟环境并安装依赖
uv venv
source .venv/bin/activate  # Windows系统：.venv\Scripts\activate
uv pip install -e .

配置 ⚙️

环境变量（.env文件）

在项目根目录创建.env文件以配置AI后端：

bash
# 切换本地模型和OpenAI模型
USE_LOCAL_MODEL=false  # false=OpenAI（默认），true=本地模型

# OpenAI配置（若USE_LOCAL_MODEL=false则必填）
OPENAI_API_KEY=your-openai-api-key-here
# OPENAI_MODEL=gpt-4o-mini  # 可选，默认gpt-4o-mini

# 本地模型配置（若USE_LOCAL_MODEL=true则使用）
# LOCAL_MODEL_NAME=microsoft/Phi-3-mini-4k-instruct  # 可选

切换模型：

• 设置USE_LOCAL_MODEL=false使用OpenAI（更快、更准确，需要API密钥）
• 设置USE_LOCAL_MODEL=true使用本地模型（隐私保护，无需API密钥，速度较慢）

启动脚本会自动读取这些设置 - 无需修改代码！

快速开始 🚀

选项1：Web界面（最简单！🌐）

python
from docker.xuanyuan.run/cv_matcher import launch_ui

# 启动Web界面
# 使用.env文件中的设置（USE_LOCAL_MODEL和OPENAI_API_KEY）
launch_ui()

或从命令行启动：

bash
python launch_ui.py  # 从.env读取USE_LOCAL_MODEL设置

然后在浏览器中打开http://localhost:7860开始分析简历！

💡 提示： 通过修改.env文件中的USE_LOCAL_MODEL值可切换OpenAI和本地模型 - 无需修改代码！

选项2：Python API与OpenAI（推荐！⚡）

python
import os
from docker.xuanyuan.run/cv_matcher import CVMatcher

# 设置OpenAI API密钥
os.environ["OPENAI_API_KEY"] = "your-api-key-here"

# 初始化为OpenAI（默认以获得最佳性能）
matcher = CVMatcher(use_local_model=False)

# 分析简历与职位描述的匹配度
analysis = matcher.analyze_cv(
    cv_path="path/to/cv.pdf",
    job_description="职位描述文本或URL",
    verbose=True
)

# 打印结果
matcher.print_analysis(analysis)

# 导出为JSON
matcher.export_analysis(analysis, "analysis_results.json")

选项3：使用本地模型（无需API密钥 🔓）

python
from docker.xuanyuan.run/cv_matcher import CVMatcher

# 使用本地AI模型（无需API密钥，但速度较慢）
matcher = CVMatcher(
    use_local_model=True,
    local_model_name="microsoft/Phi-3-mini-4k-instruct"  # 可选，默认值
)

analysis = matcher.analyze_cv("cv.pdf", "职位描述")

从命令行启动Web界面

bash
# 简单方式
python launch_ui.py

# 或使用Python命令
python -c "from cv_matcher import launch_ui; launch_ui()"

# 创建可共享的公共URL
python -c "from cv_matcher import launch_ui; launch_ui(share=True)"

从URL获取职位描述

python
matcher = CVMatcher()

# 从URL获取职位描述
analysis = matcher.analyze_cv(
    cv_path="cv.pdf",
    job_description="https://example.com/job-posting"
)

API配置 🔧

CVMatcher参数

python
CVMatcher(
    use_local_model: bool = False,    # False=OpenAI（默认），True=本地模型
    local_model_name: str = "microsoft/Phi-3-mini-4k-instruct",
    api_key: Optional[str] = None,    # OpenAI密钥（若未提供则从.env读取）
    model: str = "gpt-4o-mini",       # OpenAI模型名称
    timeout: int = 10                 # HTTP超时时间（秒）
)

推荐： 使用.env文件进行配置，而非硬编码参数。

支持的本地模型（无需API密钥）

• microsoft/Phi-3-mini-4k-instruct（默认，快速，3.8B参数）
• mistralai/Mistral-7B-Instruct-v0.2（更大，功能更强）
• 任何Hugging Face指令调优的聊天模型

支持的OpenAI模型（需要API密钥）

• gpt-4o-mini（性价比高）
• gpt-4o（更高级）
• gpt-4-turbo（高性能）

输出格式 📋

分析返回一个CVAnalysis对象，包含：

匹配分数

• 总体分数：0-100%的匹配评级
• 技能匹配：技能匹配程度
• 经验匹配：经验水平匹配度
• 教育匹配：教育要求匹配度
• 关键词匹配：重要关键词覆盖率
• 匹配/缺失技能：已找到和需补充的技能列表
• 匹配/缺失关键词：关键术语分析

格式建议

• 优势：简历的优点
• 不足：需要改进的地方
• 建议：具体、可操作的改进建议
• 结构反馈：布局和组织建议
• 内容反馈：内容质量评估

总结与建议

• 简历与职位匹配度的总体评估
• 明确的后续步骤建议

示例 📚

查看examples目录获取更详细的使用示例：

• local_model_usage.py：使用本地AI模型（无需API密钥）
• basic_usage.py：简单简历分析（支持本地和OpenAI模型）
• batch_analysis.py：分析多个简历
• url_fetching.py：从URL获取职位描述
• custom_model.py：使用不同的AI模型
• launch_ui.py：启动Web界面

开发 🛠️

设置开发环境

bash
# 克隆仓库
git clone https://github.com/officialgabzz/cv-matcher.git
cd cv-matcher

# 安装开发依赖
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

运行测试

bash
pytest tests/ -v --cov=cv_matcher

代码格式化

bash
# 格式化代码
black src/cv_matcher

# 代码检查
ruff check src/cv_matcher

# 类型检查
mypy src/cv_matcher

项目结构 📁

cv-matcher/
├── src/
│   └── cv_matcher/
│       ├── __init__.py          # 包初始化
│       ├── matcher.py           # 主要CVMatcher类
│       ├── models.py            # Pydantic数据模型
│       ├── pdf_parser.py        # PDF文本提取
│       ├── job_fetcher.py       # 职位描述获取
│       └── ai_analyzer.py       # AI分析逻辑
├── tests/                       # 测试文件
├── examples/                    # 使用示例
├── pyproject.toml              # 项目配置
├── README.md                   # 本文档
└── LICENSE                     # MIT许可证

要求 📋

• Python 3.9+
• 无需API密钥（使用本地模型时）
• 依赖项（自动安装）：
  • pypdf
  • requests
  • beautifulsoup4
  • transformers
  • torch
  • gradio
  • pydantic
  • rich
  • accelerate

注意： 首次运行将下载AI模型（根据模型选择，约3-7GB）。后续运行使用缓存模型。

API参考 📖

CVMatcher

简历分析的主类。

方法

• analyze_cv(cv_path, job_description, verbose=False)：分析简历
• print_analysis(analysis, detailed=True)：显示结果
• export_analysis(analysis, output_path)：保存为JSON

模型

• CVAnalysis：完整分析结果
• MatchScore：匹配评分详情
• FormattingAdvice：简历改进建议

隐私与安全 🔒

使用本地模型时（默认）🔐

• 100%隐私保护：所有数据保留在本地设备
• 无需联网：模型下载后完全离线运行
• 无需API密钥：不涉及外部服务
• 您的数据绝不会离开您的计算机

使用OpenAI时（可选）

• 您的简历和职位描述数据将发送至OpenAI进行分析
• 本库不存储任何数据
• 使用环境变量存储API密钥（切勿硬编码）
• 本地开发时建议使用.env文件（排除在git之外）

贡献 🤝

欢迎贡献！请随时提交Pull Request。对于重大更改，请先打开issue讨论您想要更改的内容。

1. Fork仓库
2. 创建功能分支（git checkout -b feature/AmazingFeature）
3. 提交更改（git commit -m 'Add some AmazingFeature'）
4. 推送到分支（git push origin feature/AmazingFeature）
5. 打开Pull Request

许可证 📄

本项目采用MIT许可证 - 详见LICENSE文件。

路线图 🗺️

• Gradio Web界面
• 本地AI模型（无需API密钥）
• 支持更多文件格式（DOCX、TXT）
• 移动响应式UI
• 特定行业的自定义AI提示
• 与招聘网站API集成
• 基于职位描述的简历生成器
• 批量处理UI
• 多语言支持
• 用于轻松部署的Docker容器

支持 💬

• 📧 ：
• 🐛 问题：https://github.com/officialgabzz/cv-matcher/issues
• 💬 讨论：https://github.com/officialgabzz/cv-matcher/discussions

致谢 🙏

• OpenAI提供GPT API
• Python社区提供优秀的库
• 本库的所有贡献者和用户

---

由CV Matcher团队制作 ❤️