ResumePilot 2.0 — AI 履歷分析與互動式問答工具
上傳你的履歷，透過 AI 自動結構化分析，並支援多輪對話協助優化。
線上 Demo： https://resumepilot-frontend-338336680245.asia-east1.run.app
系統架構
使用者瀏覽器
│
▼
Cloud Run（Next.js 前端）
│ REST API + SSE Streaming
▼
Cloud Run（FastAPI 後端）
│
├── Cloud SQL（PostgreSQL + pgvector）
│ ├── 履歷、對話、訊息（關聯式資料）
│ └── Embedding 向量（pgvector）
│
└── OpenAI API（LLM + Embedding）
技術棧
| 層級 | 技術 |
|---|
| 前端 | Next.js 16、React 19、Tailwind CSS、Radix UI、SSE streaming |
| 後端 | FastAPI（Python）、LangChain、SQLAlchemy（async） |
| 資料庫 | PostgreSQL 16（Cloud SQL） |
| 向量搜尋 | pgvector（PostgreSQL extension） |
| Embedding | OpenAI text-embedding-3-small |
| LLM | OpenAI GPT-4o-mini（可切換 Claude） |
| 快取 | Redis（對話上下文快取） |
| 部署 | GCP Cloud Run、Cloud SQL、Artifact Registry、Cloud Build |
| 開發工具 | Claude Code（AI 輔助開發） |
核心功能
RAG（檢索增強生成）
- Section-based Chunking — 按履歷結構（education/experience/project）切分，非固定長度，保留語意完整性
- Top-K=3 檢索 — 平衡上下文品質與 Token 成本
- Metadata 篩選 — 只搜尋指定履歷的 chunks，不會混入其他履歷
Prompt Engineering
- 3 種分析模式 — 一般模式、HR 視角、技術面試官視角
- 結構化 JSON 輸出 — 強制輸出格式，確保前端解析穩定
- 多輪對話 — 帶入聊天歷史的上下文感知追問
Token 成本控制
- RAG Top-K 限制 — 只注入最相關的 3 個 chunks，非整份履歷
- 對話歷史裁剪 — 只保留最近 10 則訊息
- Token 用量追蹤 — 每次 API 呼叫記錄估算 token 消耗，前端面板可視化
向量搜尋（pgvector）
- Embedding 向量直接存在 PostgreSQL，透過 pgvector extension
- 一個 query 同時完成向量相似度搜尋 + metadata 過濾 + 取得內容
- 不需要額外維護獨立的 Vector DB（Chroma/Pinecone）
即時串流（SSE）
- Server-Sent Events 逐 token 即時回傳
- 前端逐步渲染 AI 回覆，大幅降低使用者感受到的延遲
專案結構
resumeCopilot2-backend/ # FastAPI 後端
├── app/
│ ├── api/v1/ # 路由處理
│ ├── models/ # SQLAlchemy ORM 模型
│ ├── schemas/ # Pydantic 請求/回應 Schema
│ ├── services/ # 商業邏輯
│ │ ├── rag_service.py # 履歷分析（RAG chain）
│ │ ├── conversation_service.py # 多輪對話 + streaming
│ │ ├── vectorstore_service.py # pgvector 整合
│ │ ├── chunking_service.py # Section-based 切分
│ │ └── pdf_service.py # PDF 文字擷取
│ └── db/ # 資料庫 + Redis 連線
├── Dockerfile
└── requirements.txt
resumeCopilot2-frontend/ # Next.js 前端
├── src/
│ ├── app/page.tsx # 主頁面
│ ├── components/ # UI 元件
│ │ ├── ResumeInput.tsx # 履歷上傳 + 文字輸入
│ │ ├── AnalysisResults.tsx # 分析結果顯示（可收合）
│ │ ├── ChatInterface.tsx # 多輪對話 + streaming
│ │ └── SettingsPanel.tsx # 模式選擇 + Token 用量
│ └── lib/api.ts # API client（fetch + SSE 解析）
├── Dockerfile
└── cloudbuild.yaml
快速開始
本地開發
前置需求： Docker、Node.js 20+、Python 3.11+
# 1. 啟動 PostgreSQL + Redis
cd resumeCopilot2-backend
docker compose up -d
# 2. 啟動後端
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # 填入你的 OPENAI_API_KEY
uvicorn app.main:app --reload
# 3. 啟動前端
cd resumeCopilot2-frontend
npm install
npm run dev
部署到 GCP
# Build & 部署後端
cd resumeCopilot2-backend
gcloud builds submit --tag asia-east1-docker.pkg.dev/PROJECT/REPO/backend
gcloud run deploy resumepilot-backend --image=... --region=asia-east1
# Build & 部署前端
cd resumeCopilot2-frontend
gcloud builds submit --config=cloudbuild.yaml
gcloud run deploy resumepilot-frontend --image=... --region=asia-east1
設計決策
| 決策 | 原因 |
|---|
| pgvector 取代 Chroma | 少維護一個服務；向量搜尋與關聯式查詢在同一個 DB 完成 |
| Section-based chunking 取代固定長度切分 | 保留履歷各區塊的語意結構完整性 |
| SSE 取代 WebSocket | 單向 LLM token 串流場景更簡潔；原生 HTTP，無額外協議 |
| Cloud Run 取代 GKE | Serverless 自動擴縮，閒置零成本；這個規模不需要 Kubernetes |
| Redis 對話上下文快取 | 高併發下減少 DB 讀取；Cache-Aside 模式，TTL 30 分鐘 |
| 模型無關架構 | LangChain 抽象層讓 OpenAI/Claude 切換只需改設定檔 |
實驗：JD 比對要用 Agentic RAG 嗎？
問題：把 JD 貼進對話問「我符合這個職缺嗎？」，原本的做法（整份 JD 當成一個 query 檢索 top-3，一次回答所有需求）常常漏看履歷裡明明有寫的經驗，也會拿相鄰的技術湊答案。我想知道 query decomposition + Corrective RAG 能不能改善，代價是多少。
評測設計
- 資料集：5 份履歷（含 2 份刪改版）× 4 份 JD，拆成 36 條需求，共 180 筆判定標註 + 50 題單點問答（可回答 / 不可回答各半）
- 標註策略：用「刪改履歷」製造確定的答案（例如刪掉所有 MCP 相關內容，該需求的答案就一定是「缺少」）；判定標準寫成文件，標註與 prompt 共用；每段標準證據都用程式確認確實出現在履歷原文中
- 為了公平比較判定品質，所有版本都使用標準需求清單作為輸入（拆解的品質另外評估）
- 每個版本跑 3 次取平均（gpt-4o-mini，temperature 0）
| 版本 | 做法 |
|---|
| A | 整份履歷直接給 LLM，一次判斷所有需求 |
| B | 整份 JD 當 query 檢索 top-3，一次判斷所有需求（原本的做法） |
| C | 每條需求各自檢索 top-3、各自判斷（LangGraph） |
| D | C + CRAG：評分檢索結果，不相關就改寫 query 重搜（最多 2 次）+ 證據驗證 |
| E | D + 判定後檢查證據是否證明這項能力本身（Self-RAG 的 support check） |
結果
| 版本 | 準確率 | 幻覺率 ↓ | 漏看率 ↓ | 證據有效率 | 每份 JD 的 LLM 呼叫 | tokens |
|---|
| A 整份履歷 | 81.5% | 9.6% | 9.7% | 73.6% | 1 | ~2.4k |
| B 單次檢索 | 78.1% | 5.0% | 13.0% | 91.2% | 1 | ~2.0k |
| C 逐條檢索 | 79.3% | 25.0% | 7.0% | 98.3% | 9 | ~10k |
| D CRAG | 79.8% | 19.6% | 4.7% | 99.3% | 29 | ~20k |
| E CRAG + verify | 76.5% | 17.5% | 5.3% | 99.1% | 34 | ~22k |
- 幻覺率：標準答案為「缺少」，卻判成符合 / 部分符合；漏看率：標準答案為符合 / 部分符合，卻判成「缺少」
- 證據有效率：模型引用的證據，有多少真的是履歷原文
- D、E 各有幾份 JD 因 rewrite 步驟輸出失控而失敗並計為錯誤（已修正，見下方），準確率略被低估
發現
- 短文件直接放全文，準確率不輸 RAG。 九成的題目三種做法都在 83–84%。需要看全貌的題目（例如加總多段經歷的年資）全文版 90%，逐條檢索只有 62%。
- 但全文版有 26% 的證據是捏造的：常把 JD 的需求原文當成履歷證據。逐條處理的版本證據有效率達 99%。準確率只看判定、不看理由，所以這個問題被掩蓋了。
- 逐條處理最大的問題是「用相鄰技術冒充」：需求是 hybrid search，履歷只有向量檢索，卻判成部分符合。D 的 47 次幻覺集中在 15 個項目、每次都錯，是系統性問題。
- 只靠 prompt 規則擋不住：在判定標準加上「相鄰技術不算」，A 幾乎不變、B 反而變差，已還原。
- 給模型中間選項，它就會往中間放：E 的驗證把相鄰技術都歸為「較基礎版本」，幻覺沒有被擋下。小規模測試顯示 gpt-4o 能正確區分、gpt-4o-mini 不行，下一步會考慮只在驗證步驟使用較強的模型（model routing）。
過程中修正的工程問題
- 中文履歷 chunking 失效：中文標題認不出來，PDF 文字沒有空行導致一個 chunk 達 4,450 字。改為支援中文標題，並在沒有空行時按「條目」切分
- 速率上限：D 一輪約 32 萬 input tokens，超過每分鐘上限；改用 client 端限速
- 輸出失控：rewrite 步驟偶爾重複輸出直到 16k tokens。為每個步驟設定輸出上限（
with_structured_output 之後 bind(max_tokens=...) 會失效，要用 model_copy），撞到上限時沿用原 query 繼續
結論
在單份履歷這種短文件的場景，Agentic RAG 沒有帶來準確率提升，成本卻是 29 倍的 LLM 呼叫，因此沒有把它上線成正式功能。它的價值會在文件放不進 context 的場景出現（例如從大量履歷中找人），或是在需要可驗證證據的場景。
限制：資料集規模小（180 筆）；標註初稿由 Claude 依規則撰寫、作者確認有爭議的項目；只測試了 gpt-4o-mini；另外準備的 held-out 驗證集尚未執行。
여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗
