Resume Matcher 实战指南：AI 简历定制、ATS 匹配与多供应商本地化部署

Resume Matcher 实战指南：AI 简历定制、ATS 匹配与多供应商本地化部署

【免费下载链接】Resume-MatcherThe #1 AI Harness for Building Resumes, PDFs, Cover Letters & more, locally with 100+ LLMs support.项目地址: https://gitcode.com/GitHub_Trending/re/Resume-Matcher

Resume Matcher 是一款开源的 AI 简历工作台，它围绕"主简历 + 岗位描述"的定制流程，利用 LLM 生成针对性简历内容、求职信与邮件模板，并提供 PDF 导出与多语言界面。本文以项目西班牙语文档 README.es.md 为主线，结合 SETUP.es.md 部署手册与仓库源码（后端配置、LLM 集成层、FastAPI 入口 等），完整讲解其工作原理、核心功能、安装步骤、AI 供应商配置与 Docker 部署，帮助读者快速落地一套可本地运行的简历定制系统。

一、工作原理：从主简历到定制简历的六步流程

Resume Matcher 的核心理念是先建立一份"主简历"（master resume），再针对每一份岗位描述（JD）进行定制，而不是每次从零重写。README.es.md 将其工作流概括为六步：

1. 上传你的主简历（PDF 或 DOCX）；
2. 粘贴目标岗位的职位描述；
3. 审查AI 生成的改进建议与定制内容；
4. 生成针对该岗位的求职信和申请邮件模板；
5. 定制版式与章节，使其符合你的风格；
6. 导出为你偏好的模板所渲染的专业 PDF。

从源码看，这条流程由 FastAPI 入口 挂载的多个路由器共同支撑：/api/v1/resumes（简历解析与存储）、/api/v1/jobs（岗位描述）、/api/v1/enrichment（内容增强）、/api/v1/resume_wizard（引导式生成）等，全部以/api/v1为前缀。其中简历解析依赖pdfminer.six与markitdown[docx]（见 pyproject.toml），支持 PDF 与 DOCX 两种主流格式。

二、核心功能深度解析

2.1 主简历（Master Resume）

你首先需要一份完整的主简历作为内容来源。上传后，系统通过 LLM 将其解析为结构化数据模型（对应 schemas/models.py），后续所有针对岗位的定制都基于这份结构化主简历进行，避免每次重复录入。

2.2 简历构建器（Resume Builder）

粘贴岗位描述后，构建器会借助 AI 生成针对该岗位的定制简历。文档明确列出了四项可操作能力，全部有前端组件支撑：

• 修改建议内容：AI 生成的条目可在 resume-builder.tsx 中直接编辑；
• 增删章节：通过 add-section-dialog.tsx 添加自定义章节（项目、证书、语言等）；
• 拖拽重排章节：依赖@dnd-kit/core、@dnd-kit/sortable等库实现（见 package.json），对应 draggable-section-wrapper.tsx；
• 多模板切换：在 Clásica / Moderna 两种风格的一列、两列布局间自由选择。

前端还为构建器提供了 ATS 分数卡片（ats-score-card.tsx）与差异化预览（diff-preview-modal.tsx），让每一次定制都可见、可对比。

2.3 求职信与邮件模板生成器

系统会根据岗位描述与简历内容，自动生成定制化的求职信和邮件模板。

对应后端服务位于 services/cover_letter.py，前端提供 cover-letter-editor.tsx 与 outreach-editor.tsx 进行在线编辑与预览，并支持独立打印页面（见 app/print/cover-letter/[id]/page.tsx）。

2.4 简历评分与关键词高亮（开发中）

README.es.md 指出，评分功能正在开发中，目标是分析简历与岗位描述的匹配度并给出改进建议。从源码看，该功能已有明确实现雏形：services/ats.py 定义了 ATS 风格的三项子评分及其权重：

整体分数为三项加权合成。前端配套有 keyword-matcher.ts 与 jd-comparison-view.tsx，用于展示关键词命中情况。前端测试 keyword-matcher.test.ts 对关键词匹配逻辑进行了覆盖。

2.5 PDF 导出

定制好的简历与求职信可直接导出为 PDF。导出链路由后端 pdf.py 驱动，底层使用Headless Chromium（经 Playwright）渲染前端打印页面（app/print/resumes/[id]/page.tsx），因此 PDF 与屏幕预览高度一致。

2.6 内置模板

文档提供了四套 PDF 模板，全部可在 assets/pdf-templates 中查看预览图与 PDF 样例：

模板渲染组件位于 components/resume（如 resume-modern.tsx、resume-two-column.tsx），样式遵循Swiss International Style设计体系（Tailwind CSS 4 实现）。

2.7 国际化（i18n）

• 多语言 UI：界面支持英语、西班牙语、中文、日语（README.es.md 所述）；实际配置见 i18n/config.ts，当前 locale 列表为en / es / zh / ja / pt / fr，即英文、西班牙文、中文、日文、葡萄牙文（巴西）、法文六种；
• 多语言内容：可生成指定语言的简历与求职信内容，翻译文案位于 messages 目录（en.json、es.json、zh.json、ja.json、pt-BR.json、fr.json），并有 check_locale_parity.py 脚本与测试 i18n-locale-parity.test.ts 保证各语言键的完整性与一致性。

2.8 Roadmap

文档列出的规划方向包括：关键词可视化高亮、AI Canvas 制作有冲击力且基于指标衡量的简历内容、多岗位描述批量优化。

三、安装与快速开始

3.1 前置要求

其中uv是项目推荐的 Python 包管理器，安装方式：

# macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows (PowerShell) powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # 或通过 pip pip install uv

3.2 快速开始（MacOS / WSL / Ubuntu）

# 克隆仓库 git clone https://gitcode.com/GitHub_Trending/re/Resume-Matcher.git cd Resume-Matcher # 后端（终端 1） cd apps/backend cp .env.example .env # 配置 AI 供应商 uv sync # 安装依赖 uv run app # 前端（终端 2） cd apps/frontend npm install npm run dev

随后打开http://localhost:3000，在 Settings 页面配置你的 AI 供应商即可。

3.3 逐步配置后端

后端是一个 FastAPI 应用，负责 AI 处理、简历解析与数据存储。

cd apps/backend cp .env.example .env nano .env # 或 code .env

一个最小可用的 OpenAI 配置示例：

LLM_PROVIDER=openai LLM_MODEL=gpt-5-nano-2025-08-07 LLM_API_KEY=sk-your-api-key-here # 本地开发保持默认即可 HOST=0.0.0.0 PORT=8000 FRONTEND_BASE_URL=http://localhost:3000 CORS_ORIGINS=["http://localhost:3000", "http://127.0.0.1:3000"]

关于这份.env的完整参数，可直接参考仓库中的 apps/backend/.env.example，其对应的底层解析逻辑在 apps/backend/app/config.py 的Settings类中，几个关键点：

• LLM_PROVIDER：支持openai、openai_compatible、anthropic、openrouter、gemini、deepseek、groq、ollama八种，默认openai；
• LLM_MODEL：默认gpt-5-nano-2025-08-07；
• LLM_API_BASE：用于 Ollama 或自定义兼容端点，默认为空；
• HOST / PORT：默认0.0.0.0:8000；
• RELOAD：设true时uv run app会开启热重载（仅开发）；
• REASONING_EFFORT：支持minimal | low | medium | high，留空则最大兼容，LiteLLM 会对不支持的供应商自动丢弃该参数；
• REQUEST_TIMEOUT_SECONDS：单次简历定制/改进请求的硬超时，默认 240 秒，取值被钳制在 [30, 1800]；使用本地 LLM（Ollama、llama.cpp）时应调大，且必须与前端NEXT_PUBLIC_REQUEST_TIMEOUT_MS（= 该值 × 1000）保持同步，否则前端会先中断请求；
• CORS_ORIGINS：JSON 数组格式，FRONTEND_BASE_URL会被自动追加进允许列表（见effective_cors_origins属性）。

安装依赖并启动：

uv sync # 创建虚拟环境并安装全部依赖 RELOAD=true uv run app # 开发模式启动

启动成功后终端会输出类似：

INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit) INFO: Started reloader process

后端依赖与脚本入口定义在 apps/backend/pyproject.toml：[project.scripts]中app = "app.main:main"即uv run app的入口，项目要求requires-python = ">=3.13"，核心依赖包括fastapi、litellm（多供应商统一网关）、tinydb+sqlalchemy（数据存储）、playwright（PDF 渲染）等。

3.4 配置前端

cd apps/frontend # 可选：仅当后端运行在非默认端口时才需要 cp .env.sample .env.local npm install npm run dev

启动后终端输出类似：

▲ Next.js 16.x.x (Turbopack) - Local: http://localhost:3000

前端 API 客户端位于 lib/api/client.ts：默认API_BASE为/api/v1，前端开发服务器会将请求代理到http://127.0.0.1:8000，因此本地开发时前端与后端端口无需显式互指。

四、配置你的 AI 供应商

供应商既可以在应用的Settings页面配置（推荐，API Key 会加密存储），也可以通过后端.env配置。

4.1 选项 A：云供应商

OpenAI-Compatible模式可指向任何暴露 OpenAI Chat Completions 接口的本地服务——llama.cpp、vLLM、LM Studio 等均可，API Key 为可选（留空时后端会自动传入一个占位值sk-no-key以通过客户端校验，见 llm.py 中_effective_api_key）。

Anthropic 的.env示例：

LLM_PROVIDER=anthropic LLM_MODEL=claude-haiku-4-5-20251001 LLM_API_KEY=sk-ant-your-key-here

4.2 选项 B：Ollama 本地模型（免费）

完全在本地运行、无 API 成本：

第 1 步：安装 Ollama，从官网下载并安装。

第 2 步：拉取模型

ollama pull gemma3:4b

其他可选模型：mistral、codellama、neural-chat。

第 3 步：配置.env

LLM_PROVIDER=ollama LLM_MODEL=gemma3:4b LLM_API_BASE=http://localhost:11434 # Ollama 无需 LLM_API_KEY

第 4 步：确保 Ollama 正在运行

ollama serve

通常安装后 Ollama 会自动常驻后台。

4.3 底层实现：LiteLLM 多供应商网关

为什么一个配置就能切换八种供应商？关键在于后端在 apps/backend/app/llm.py 中基于LiteLLM做了统一封装：

• 模型命名规范化：get_model_name()会自动为各供应商加上前缀（如anthropic/、gemini/、deepseek/、ollama_chat/——后者路由到 Ollama 的/api/chat端点以支持 messages 数组），OpenRouter 会强制补全openrouter/前缀；
• API Base 归一化：_normalize_api_base()会针对 Anthropic、Gemini、OpenRouter、Ollama 自动剥离用户粘贴的/v1等路径后缀，避免出现/v1/v1/...双路径 404（OpenAI 与 openai_compatible 则原样保留）；
• 重试与熔断：使用 LiteLLM Router，num_retries=3，针对超时（重试 2 次）、限流（重试 3 次）、服务端错误（重试 2 次）分别设置策略，认证与参数类错误不重试，并禁用冷却（cooldown）避免单部署场景下误伤；
• 超时自适应：_calculate_timeout()按操作类型（健康检查 30s / 补全 120s / JSON 180s）、token 量与供应商（Ollama 系数 2.0、OpenRouter 系数 1.5）动态计算超时；
• JSON 模式兜底：complete_json系列会根据 LiteLLM 模型注册表判断是否支持response_format，不支持时退化为纯 Prompt 约束，并对gpt-5等推理模型自动迁移reasoning_effort=minimal以保留历史行为。

五、Docker 部署

推荐使用 Docker Compose：

docker-compose up -d # 构建并启动 docker-compose logs -f # 查看日志 docker-compose down # 停止

仓库根目录的 docker-compose.yml 展示了镜像运行所需的完整环境变量：FRONTEND_BASE_URL（默认http://localhost:3000）、LOG_LEVEL（DEBUG/INFO/WARNING/ERROR）、LOG_LLM（LiteLLM 日志级别，默认 WARNING）、LLM_PROVIDER/LLM_MODEL/LLM_API_KEY/LLM_API_BASE，数据通过命名卷resume-data:/app/backend/data持久化。

使用 Docker 时需注意几点：

• API Key 从 UI 配置：在 http://localhost:3000/settings 页面填写（而非通过.env文件）；从源码看，API Key 经 crypto.py 加密后存入 SQLite 密钥存储，不会以明文落盘（见 config.py 中load_config_file/save_config_file的注释说明）；
• Ollama 跨容器访问：若 Ollama 运行在宿主机，Docker 容器内应把LLM_API_BASE设为http://host.docker.internal:11434而不是localhost。

六、访问应用与首次运行清单

两个服务都启动后，可通过以下地址访问：

首次运行清单：

1. 打开 http://localhost:3000/settings；
2. 选择你的 AI 供应商；
3. 输入 API Key（或配置 Ollama）；
4. 点击 "Save Configuration" 保存；
5. 点击 "Test Connection" 验证连通性（后端对应check_llm_health实现，会发送一条最小请求并检查返回内容是否非空）；
6. 回到 Dashboard，上传第一份简历。

七、常用命令参考

后端命令

cd apps/backend # 开发模式（热重载） RELOAD=true uv run app # 生产模式 uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 # 安装依赖 uv sync # 安装含开发依赖（用于测试） uv sync --group dev # 运行测试 uv run pytest # 查看数据目录（JSON/SQLite 存储） ls -la data/

前端命令

cd apps/frontend npm run dev # 开发服务器（Turbopack） npm run build # 生产构建 npm run start # 生产启动 npm run lint # ESLint 检查 npm run format # Prettier 格式化 npm run test # Vitest 单元测试 npm run dev -- -p 3001 # 换端口

数据库管理

数据存储在apps/backend/data/目录。README.es.md / SETUP.es.md 提供的管理方式如下：

ls apps/backend/data/ # 查看数据库文件 cp -r apps/backend/data apps/backend/data-backup # 备份 rm -rf apps/backend/data # 重置（从零开始）

从源码看，当前主存储为 SQLite（resume_matcher.db），应用启动时会执行幂等的 TinyDB → SQLite 迁移（见 scripts/migrate_tinydb_to_sqlite.py 与 main.py 的 lifespan 逻辑），并自动把旧版明文 API Key 迁入加密存储。

八、常见问题排查

后端无法启动

• ModuleNotFoundError：确保通过uv run执行，例如uv run uvicorn app.main:app --reload；
• LLM_API_KEY not configured：检查.env中是否填写了所选供应商的有效 Key。

前端无法启动 / 页面报 ECONNREFUSED

• 先确认后端已启动：cd apps/backend && uv run uvicorn app.main:app --reload；
• 出现构建或 TypeScript 报错时，清理 Next.js 缓存后重启：rm -rf apps/frontend/.next && npm run dev。

PDF 下载失败：Cannot connect to frontend for PDF generation

后端无法访问前端页面进行渲染，请依次检查：

1. 前端是否在运行；
2. .env中FRONTEND_BASE_URL是否与前端地址一致；
3. CORS_ORIGINS是否包含前端地址。

若前端运行在 3001 端口：

FRONTEND_BASE_URL=http://localhost:3001 CORS_ORIGINS=["http://localhost:3001", "http://127.0.0.1:3001"]

Ollama 连接失败：Connection refused to localhost:11434

1. 检查 Ollama 是否运行：ollama list；
2. 必要时手动启动：ollama serve；
3. 确认模型已下载：ollama pull gemma3:4b。

九、技术栈与项目结构

技术栈一览

项目结构

Resume-Matcher/ ├─ apps/ │ ├─ backend/ # Python FastAPI 后端 │ │ ├─ app/ │ │ │ ├─ main.py # 应用入口 │ │ │ ├─ config.py # 环境配置 │ │ │ ├─ llm.py # AI 供应商集成（LiteLLM） │ │ │ ├─ routers/ # API 端点 │ │ │ ├─ services/ # 业务逻辑（ats/cover_letter/parser…） │ │ │ └─ schemas/ # 数据模型 │ │ ├─ prompts/ # LLM 提示词模板 │ │ ├─ data/ # 数据库存储（自动创建） │ │ ├─ .env.example # 环境变量模板 │ │ └─ pyproject.toml # Python 依赖 │ └─ frontend/ # Next.js React 前端 │ ├─ app/ # 页面（dashboard、builder、tracker…） │ ├─ components/ # 可复用 React 组件 │ ├─ lib/ # 工具与 API 客户端 │ ├─ messages/ # i18n 翻译文案（6 种语言） │ └─ package.json # Node.js 依赖 ├─ docs/ # 附加文档（架构、特性、设计规范） ├─ docker-compose.yml # Docker 配置 ├─ Dockerfile # 容器构建 └─ README.md # 项目总览

十、进一步阅读

若需深入架构与二次开发，仓库内提供了丰富的配套资料：

• README.md：项目英文总览；
• SETUP.md / SETUP.zh-CN.md / SETUP.ja.md：多语言部署手册；
• docs/agent/architecture/backend-guide.md：后端架构与 API 细节；
• docs/agent/architecture/frontend-workflow.md：前端用户流与组件架构；
• docs/portable/swiss-design-system/README.md：Swiss International Style UI 设计系统；
• docs/agent/llm-integration.md：LLM 集成与供应商接入规范。

至此，你已经掌握 Resume Matcher 从"工作原理 → 功能解析 → 安装部署 → 供应商配置 → 故障排查"的完整链路。其"主简历 + 岗位定制 + 多供应商 LLM + 本地 PDF 导出"的组合，使其既可作为求职者的个人工具，也可作为学习 FastAPI + Next.js + LiteLLM 全栈 AI 应用架构的参考实现。

【免费下载链接】Resume-MatcherThe #1 AI Harness for Building Resumes, PDFs, Cover Letters & more, locally with 100+ LLMs support.项目地址: https://gitcode.com/GitHub_Trending/re/Resume-Matcher