履历解析模块图解总览

1. 总览图：一个入口，三段职责

外部调用只需要理解一个业务入口。内部把复杂度拆成前置抽取、门禁判定、模型结构化三段，避免体验页、评测脚本和工程入口各自实现一套逻辑。

入口收口

图中只展示主干路径。异常路径包括：非履历直接 422、URL 抓取失败返回诊断、JSON 截断提示、模型门禁拒绝等。

2. 运行时阶段：右侧进度面板的真实事件

当前 Demo 通过 /api/parse_stream 返回 NDJSON 事件。右侧进度面板不是纯前端假进度，而是服务端在输入接收、抓取、清洗、门禁、模型请求和结果准备时逐步推送。

阶段透明

1

输入接收

读取 URL、文本或上传文件，校验请求体和文件大小。超过上限会直接返回 413。

2

来源准备

文件写入临时路径，URL 识别抓取策略，纯文本进入后续门禁。

3

URL 抓取 / OCR

执行 Local、Ark、Browser、Screenshot 或文件 OCR；长等待时推送 heartbeat。

4

正文清洗评分

去导航噪音、验证码、污染文本，并给正文质量、实体一致性和抓取策略打分。

5

履历门禁

先规则判断是否为人物资料来源；边界样本再调用轻量模型门禁复核。

6

Prompt 组装

按 Fast / Full 选择不同输出契约和长度预算；URL 长正文会做信号段裁剪。

7

模型结构化

等待 LLM 返回 JSON。当前是 HTTP 阻塞请求，heartbeat 表示仍在等待，不是 token 流。

8

JSON 解析与小修

解析模型 JSON；Fast 模式必要时触发自动小修，并记录 repair_latency_ms。

9

归一化与证据

补齐物理表字段、学位/类型枚举、证据片段和 grounding 校验。

10

渲染准备

返回结果、耗时、token、成本、抓取正文、裁剪元数据和阶段耗时。

如果页面卡在“模型结构化解析”，真实含义通常是第 7 步的模型 HTTP 请求尚未返回；右侧会展示模型、输入规模、等待时长和长等待提示。

3. 关键输出：每个重要步骤应该看什么

Demo 右侧结果区承担唯一主要进度和诊断展示。核心不是只显示“进行中”，而是暴露前置抽取正文、质量评分、门禁判断、模型输入预算、结构化结果和错误阶段。

可观测性

前置抽取输出

实际使用策略：local / ark / browser / screenshot
页面标题、来源 URL、正文长度和清洗后长度
验证码、正文污染、SPA 资源兜底、百科 API 兜底等 warning

strategy_used score warnings

模型输入输出

Prompt 字符数、输出 token 上限、Fast / Full 模式
URL 原文长度、模型输入长度、是否被裁剪
LLM 耗时、token usage、估算成本和自动小修耗时

model_input_truncated usage repair_attempted

最终业务输出

名片五要素草稿和待补全项
履历物理表 resume_items[]
对话引导建议、标签建议、证据片段和完整 JSON

card_target completion_state raw_evidence

当前页面对应体验页状态 左侧按钮只保留按钮级 loading 文案；主要进度、等待原因、阶段输出和错误恢复提示都放在右侧结果面板。右侧内容随页面主滚动展示，不再被限制在内部滚动容器。

4. 输入地图：不同输入先变成可信文本

模型真正需要的是“可解析的履历文本”。所以 URL、PDF、图片、TXT/MD 会先进入不同的前置抽取路径，抽取之后再做非履历判断。

前置抽取

输入类型

第一步

抽取方式

门禁位置

失败表现

适合场景

URL

安全校验只允许 http/https，禁止 localhost 和私网。

Local / Ark / Browser / Screenshot按策略选择或兜底。

抓取后检查正文长度、验证码、污染、实体一致性。

403 / 空正文 / 污染返回策略诊断。

个人主页、百科人物页、机构人物介绍、LinkedIn 风格公开页

文本层 PDF

读取文本层先用本地 PDF 文本提取。

零模型成本能读到文本就不先 OCR。

模型前规则门禁先判断是否像履历。

非履历直接提示重新上传。

常规简历 PDF、导出的 CV

图片型 PDF / 图片

文件头和大小校验先挡明显错误。

轻量 OCR先抽文本，再判断是否履历。

OCR 后先过门禁，再做结构化。

非履历图片不进入正式解析。

扫描简历、图片简历

TXT / MD / 纯文本

直接读取按文本输入处理。

清洗文本去掉明显噪音和控制字符。

文本后规则门禁。

非履历直接拒绝。

用户复制的简历、个人介绍

5. URL 抓取图：快路径、专项兜底和强力截图分开

当前 URL 前置抽取先做安全校验，再优先使用站点专项和文本抓取。Wikipedia、百度百科和 SPA 个人主页都有专门兜底；截图 OCR 仍是显式高成本路径。

策略可控

策略选择建议

策略	用途	代价
auto	文本 Auto。Local、Ark、Browser 都失败就返回诊断，不截图。	快，成本低。
auto_with_screenshot	体验页默认 Auto。文本抓取失败后追加截图 OCR。	更稳，但慢且调用多模态。
screenshot	明确知道页面只能视觉读取时直接走截图 OCR。	最慢，适合人工排查或少量高价值页面。

核心变化：体验页的 Auto 映射到 auto_with_screenshot，而底层 auto 保持纯文本抓取，方便单测和成本控制。

站点专项路径

Wikipedia

直接调用 MediaWiki extracts API 获取纯文本，避免导航、目录和相关链接污染；适合人物百科页。

百度百科

优先走公开卡片 API 和移动百科兜底，避免桌面页 403、验证码和反爬等待；失败时再按策略继续。

SPA 个人主页

当 HTML body 正文为空时，会提取 meta 信息，并尝试读取同源前端静态 JS chunk 中的履历文本。

6. 门禁漏斗：先判断是否是可解析的人物资料来源

上传错文件、恶意输入、普通新闻、产品文档、空白图片，都应该在模型结构化前被拦截；但百科人物页、公开人物资料、学生证和工牌应允许进入解析。门禁越早越省钱，也越稳定。

安全边界

规则门禁

速度最快，挡明显非人物资料：普通新闻、论文正文、公告、产品文档、纯噪音、长度不足、注入提示等。

模型门禁

用于图片型 PDF、学生证、工牌、公开人物资料等边界内容，判断是否“足够像人物资料来源”。这一步比直接结构化便宜，也更可解释。

结果校验

结构化后检查姓名、主体、证据是否和输入一致，防止模型把非履历硬编成履历。

允许继续解析的资料类型

类型	例子	业务说明
传统履历	简历、CV、PDF 履历、个人主页、LinkedIn/GitHub/学术主页	完整进入 Fast / Full 结构化。
个人身份资料	学生证、校园卡、工牌、工作证、员工证	可作为名片初始化来源，即使信息少，也应尽量抽姓名、学校/学院、机构和身份。
公开人物资料	Wikipedia、百度百科、机构人物介绍、作者/学者/艺术家生平页	可结构化为人物履历，但不默认等同于当前登录用户本人的 onboarding 资料。
拒绝样本	普通新闻、公告、论文正文、产品文档、验证码页、无文字图片	前置失败后直接提示重新上传或换抓取策略，不进入结构化模型。

7. Fast / Full：体验优先和完整补全分层

Fast 不是“低质量完整解析”，而是名片草稿初始化。Full 才负责完整履历、证据块和后台补全。Compare 模式用于体验两者差异。

体验分层

Fast 模式：先让用户看到可确认的名片草稿

目标

快速生成五要素草稿

姓名/昵称、当前机构、当前职位、简介、核心教育或经历建议。

输出

小 JSON

限制 resume_items、tag_suggestions、qa_suggestions 数量，减少大模型输出长度。

适合

Onboarding 首屏

用户先确认资料，不等待完整证据链。

Full 模式：后台做完整履历和证据补全

目标

完整结构化

教育、职业、项目、奖项、论文、证书等尽量提全。

输出

完整契约

保留 raw_evidence、profile_patches、更多 resume_items。

适合

后台补全和评测

追求召回和可追溯，允许更慢。

模式对比

维度	Fast	Full	Compare
产品目标	名片草稿初始化	完整履历结构化	展示快速结果与完整结果差异
输出体积	小，限制条数和字数	大，包含证据和补丁	两次解析，体积最大
用户感知	更快看到可编辑内容	等待更久但信息更完整	适合内部体验和调试
推荐位置	前台默认	后台异步补全	Demo / QA / 对比评测

8. 输出契约：名片草稿 + 履历物理表

结构化结果不是自定义画像字段，而是对齐工程侧履历物理表。Fast 和 Full 都尽量落到同一份契约，只是字段丰富度不同。

工程对齐

card_target

前台名片草稿：nickname、identity_name、identity_position、bio 等。

profile_facts.name

事实层姓名。英文名、中文名尽量保持来源，不强行翻译人名。

profile_facts.resume_items[]

工程侧 user_resume 物理表对应数组。核心字段包括 resume_type、subject、qualifier、classifier、description、start_time、end_time、resource。

profile_insights

建议层：tag_suggestions、qa_suggestions。用于补充兴趣、身份、问答建议，不是物理履历事实。

raw_evidence

证据层。Full 模式更完整，Fast 模式可省略或压缩。

completion_state

名片完整度：必填是否齐全、缺失字段、推荐补充字段。

url_extraction_result

URL 前置抽取诊断：策略、标题、清洗正文、质量分、裁剪元数据、截图页数和估算 OCR 成本。

9. 评测指标：前置、后置、整体分开看

前置抓取问题不要带着大模型跑；结构化问题不要混进网页抓取。当前评测体系按阶段拆开，最后再聚合。

质量闭环

前置评测

看抓取文本是否包含关键履历片段、是否有噪音、是否命中验证码或污染。对应 extraction_eval.py。

后置评测

看模型输出是否符合物理契约，字段是否命中，同一个 resume_item 是否组合正确。对应 resume_eval.py。

整体评测

汇总前置分、结构化分、通过率、耗时、token、成本和错误阶段。对应 aggregated_eval.py。

指标看板口径

指标	回答的问题	典型用途
extraction_score	网页或文件前置抽取是否拿到了正确正文？	排查 403、验证码、正文污染、截图遗漏。
structured_score / core_score	LLM 是否把核心事实转成正确字段？	比较模型、Prompt、Fast/Full。
latency_ms	慢在抓取、OCR 还是模型结构化？	优化体验和拆后台任务。
usage / cost_cny	每次解析用了多少 token 和成本？	选择 mini/lite/pro，控制截图兜底成本。
error_stage	失败发生在 extraction、structured 还是 model？	避免把前置问题误判成模型问题。

10. 代码文件索引

如果要继续排查或修改，优先从这些文件进入。不要把体验页逻辑继续堆进一个巨型文件，后续应按前端静态页、服务路由、抓取器、门禁和评测拆开维护。

维护入口

src/app/resume/v1/service.py业务编排入口：前置门禁、模型门禁、解析调用、小修透明化。

src/app/resume/v1/parser.pyPrompt、结构化解析、物理契约构建、字段归一化。

src/app/resume/v1/url_fetcher.pyURL 策略调度：local、ark、browser、screenshot、成本和耗时记录。

src/app/resume/v1/url_cleaner.py正文清洗、污染检测、验证码/长度/实体一致性打分。

src/resume_lab/demo_server.py本地体验页后端，提供 /api/parse 和 /api/parse_stream；解析内核随 resume-lab 内嵌部署。

src/resume_lab/static/index.html本地体验页 UI，支持 Fast / Full / Compare、策略选择、阶段进度、关键输出和结果展示。

src/resume_lab/static/architecture.html当前这份图解说明页。

src/resume_lab/static/evaluation.html履历解析评测体系说明页，展示数据集、评分公式、报告口径和持续评估计划。

11. 当前边界和下一步

这部分用于统一预期：哪些问题已经有机制，哪些不应该继续靠一个页面文件硬堆。

待持续收敛

已具备的机制

非人物资料输入会在结构化前拦截；公开人物资料和身份资料会被允许进入解析。
URL 抓取策略可以单独测，不必每次带模型结构化。
Fast 用于名片草稿，Full 用于后台补全。
评测能区分前置失败和结构化失败。

仍建议优化

继续拆分 demo_server.py，避免体验、路由、安全、业务辅助混在一个文件。
将截图 OCR 作为显式高成本动作，在 UI 中持续展示费用和耗时。
积累更多真实 URL 和非履历负例，增强门禁评测集。
把 Fast 首屏和 Full 后台补全接入真实产品链路时，应使用异步任务和状态回写。

推荐产品路径 前台默认 Fast：给用户可编辑的名片草稿和缺失项提示。后台异步 Full：补全详细履历、证据和建议。遇到 URL 抓取问题时，先单测前置抽取，再决定是否启用 Auto+截图。