如何爬取病理图片库?PathoMind爬虫crawler.py完整解析:WebPath数据抓取与图文配对实现
如何爬取病理图片库?PathoMind爬虫crawler.py完整解析:WebPath数据抓取与图文配对实现
想搭建病理知识问答智能体,第一步往往是爬取病理图片库。本文以 PathoMind 项目中的 crawler.py 为例,手把手拆解一个面向 WebPath 权威病理网站的爬虫实现:广度优先抓取、限速重试、图片下载去重,以及最关键的图文配对——如何为每张图片自动提取描述文本。读完你即可掌握一套可复用的"数据抓取 + 图文配对"完整思路。
一、为什么选择 WebPath 作为病理图片库数据源
PathoMind 病理知识问答智能体的核心知识库由三部分组成:权威教材、WebPath 网页文本(webpath_texts 目录)和 WebPath 病理图片(webpath_images 目录),见 README.md。
WebPath(webpath.med.utah.edu)是犹他大学医学中心维护的开放病理教学网站,包含海量组织切片、大体标本图片和配套教学文字,非常适合用作病理 AI 的图文训练与检索数据源。
💡 提示:爬虫的 User-Agent 中已注明
for-personal-study-only,请务必仅将抓取数据用于个人学习与研究。
二、crawler.py 整体架构:BFS 爬虫 + 限速 + 重试
整个 crawler.py 只有 210 行左右,结构清晰,可拆成 4 个模块:
| 模块 | 位置 | 职责 |
|---|---|---|
| 站点与会话配置 | crawler.py#L12-L30 | 定义目标站点、超时、重试策略 |
| URL 工具函数 | crawler.py#L37-L51 | 同站判断、前缀过滤、URL 规范化 |
| 图文配对与下载 | crawler.py#L75-L128 | 提取图片描述、下载并去重 |
| BFS 抓取主循环 | crawler.py#L131-L204 | 广度优先遍历页面、失败重放 |
核心流程一句话概括:
从入口页出发 → 广度优先发现页面 → 每页保存纯文本 → 每张图片配对描述后下载 → 失败页面延迟重放
1. 关键配置项一览
爬虫行为由顶部的一组常量控制(crawler.py#L12-L20),新手可按需调整:
| 参数 | 默认值 | 作用 |
|---|---|---|
REQUEST_TIMEOUT |
20 秒 | 单请求超时,防止挂起 |
MAX_ATTEMPTS |
3 | 每个 URL 最多尝试次数 |
DELAY |
0.2 秒 | 每页之间的礼貌延迟 |
MAX_DEPTH |
5 | BFS 最大深度,防止抓太深 |
ALLOWED_PREFIX |
None |
路径前缀白名单,如 "/ATHHTML/";为 None 表示不限制 |
其中 ALLOWED_PREFIX 是个很实用的"刹车":只想抓某个科室目录时,把它设为对应前缀即可,其余页面会被 is_allowed_prefix 直接跳过。
2. 会话级自动重试:应对 429/5xx
retry = Retry(total=3, backoff_factor=1, status_forcelist=[429, 500, 502, 503, 504])
在 crawler.py#L27-L30 中,爬虫把 urllib3 的 Retry 挂载到 requests.Session 上。这意味着遇到 429(请求过快)或服务器错误 时,底层会按指数退避自动重试 3 次,新手无需自己写重试循环。
三、广度优先抓取主循环:如何不重不漏地遍历页面
主函数 crawl()(crawler.py#L131-L204)实现了三个关键机制:
1. 去重:seen_pages 防止重复抓取
每处理完一个页面就加入 seen_pages 集合(crawler.py#L193)。BFS 队列中同一个 URL 可能出现多次,去重保证每页只抓一次。
2. 深度与域名双重护栏
出队时先做三重过滤(crawler.py#L143-L144):
depth > max_depth:超过深度上限直接丢弃,控制抓取规模;is_same_site:只抓webpath.med.utah.edu同域页面,防止爬虫"跑飞"到其他网站;is_allowed_prefix:尊重前缀白名单。
同时 normalize_url 会去掉 URL 的 # 锚点部分,避免 webpath.html#MENU 和 webpath.html 被当成两个页面。
3. 失败页面延迟重放
抓取不是"一次失败就放弃":
- 请求异常或返回非 200 / 非 HTML 时,URL 进入
failed列表(crawler.py#L156-L163); - 当前队列清空后,若
failed中仍有未超过MAX_ATTEMPTS次数的页面,整体重新入队再跑一轮(crawler.py#L196-L203); - 每轮之间都
time.sleep(delay)保持礼貌限速。
这套"队列清空 → 重放失败项 → 再清空"的循环,让偶发的网络抖动不会造成数据缺失。
四、图文配对:extract_desc 的多级描述提取策略
图片配对了什么描述,直接决定后续向量检索的质量。 extract_desc()(crawler.py#L75-L99)采用"由近及远、逐级回退"的策略,按优先级依次尝试 5 个来源:
| 优先级 | 来源 | 说明 |
|---|---|---|
| 1 | <img alt> 属性 |
图片自带替代文本,最权威 |
| 2 | <img title> 属性 |
鼠标悬停提示文字 |
| 3 | 父级 <figure> 的 <figcaption> |
标准的图注标签 |
| 4 | 父级 <td> 单元格全文 |
适配 WebPath 大量使用的表格布局 |
| 5 | 父级 <p> 段落 + 紧邻的后继文本节点 |
兜底:图片后面的说明文字 |
提取出的多条文本会去重后用 " | " 拼接成一条完整描述(crawler.py#L95-L99)。
🎯 这个设计的巧妙之处在于:不同网站标注图片的方式差异很大,单一来源(比如只看
alt)经常落空。多级回退 + 去重拼接,保证了绝大多数图片都能拿到可用的描述文本。
五、图片下载:内容类型校验与两级去重
download_image() 是图片落盘函数,包含 4 道防线:
- 合法性过滤:非图片协议(
javascript:、mailto:)、非同站、不在前缀白名单内的 URL 直接跳过; - 内存级去重:
seen_images集合记录已下载 URL,同一图片出现在多个页面时只下一次; - 磁盘级去重:若
webpath_images/下对应文件已存在(crawler.py#L113-L115),说明上次已下载,直接标记跳过——这意味着爬虫支持断点续抓,中断后重跑不会重复下载; - 内容类型校验:只有响应
content-type以image开头才写入文件(crawler.py#L120-L122),防止把 HTML 错误页当图片存下来。
输出目录结构
图片按原始 URL 的路径结构保存,例如 https://webpath.med.utah.edu/ATHHTML/.../fig1.jpg 会存为:
webpath_images/ATHHTML/.../fig1.jpg
webpath_texts/ATHHTML/.../index.txt
目录结构与站点一一对应,方便人工核对数据来源。
六、运行方法:3 步启动爬虫
# 1. 安装依赖
pip install requests beautifulsoup4
# 2. 进入项目目录后运行
python crawler.py
运行前无需任何额外配置,脚本会自动创建 webpath_images 与 webpath_texts 两个输出目录(crawler.py#L207-L209)。
建议根据本地网络与目标网站承受能力调整 DELAY:默认 0.2 秒的页间延迟属于比较克制的节奏;如需降低对目标站点的压力,可以调大到 1 秒以上。
七、数据流向:从抓取结果到 PathoMind 向量知识库
爬虫的产物不是终点,而是 PathoMind 智能体知识链路的第一环:
- 抓取:
crawler.py产出webpath_images/(图片)+webpath_texts/(配对文本); - 向量化:图片与文本经
BAAI/bge-m3编码为向量,存入 Postgres + pgvector(技术细节见 PathoMind-介绍文档.md 中"存储与访问"与"检索策略"章节); - 检索问答:智能体收到用户提问后,通过
search_pathology_images按关键词检索病理图片并返回image_url与caption,配合knowledge_base_search输出带来源的结构化诊断要点。
也就是说,爬虫阶段的图文配对质量,直接决定了后续"按文字找病理图"这类检索能不能命中——这也是本文花大篇幅讲 extract_desc 的原因。
八、常见问题(FAQ)
Q1:如何只抓取网站的某一个专题目录?
把 ALLOWED_PREFIX 改为目标路径前缀,如 "/ATHHTML/",即可让爬虫只在该目录下工作。
Q2:中断后重跑,已经下载的图片会重复下载吗?
不会。磁盘级去重(文件已存在即跳过)+ seen_images 内存去重,天然支持断点续抓。
Q3:遇到 429 错误怎么办?
两层机制兜底:底层 Retry 自动指数退避重试 3 次;仍失败的页面进入 failed 列表,在当前轮次结束后整体重放,最多 MAX_ATTEMPTS 轮。若 429 频繁出现,把 DELAY 调大即可。
Q4:爬取的数据能用于商业用途吗?
请遵守目标网站的使用条款与 license(Apache 2.0 仅限本项目代码)。User-Agent 中已声明 for-personal-study-only,建议数据仅用于个人学习、研究与教学场景。
小结
本文完整解析了 PathoMind 项目中 crawler.py 的四个核心能力:会话级自动重试、BFS 广度优先遍历 + 失败重放、多级回退的图文配对、两级去重的图片下载。整套方案不到 250 行代码,却覆盖了实用爬虫的关键工程点——限速、去重、断点续抓、失败恢复,对想为自己 AI 项目构建垂直领域图文数据集的新手来说,是一份可以直接参考的模板。