如何爬取病理图片库?PathoMind爬虫crawler.py完整解析:WebPath数据抓取与图文配对实现

原创2026-10-24 17:18:451,863 阅读
文章标签:后端人工智能大模型AI AgentRAG多模态

如何爬取病理图片库?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. 失败页面延迟重放

抓取不是"一次失败就放弃":

  1. 请求异常或返回非 200 / 非 HTML 时,URL 进入 failed 列表(crawler.py#L156-L163);
  2. 当前队列清空后,若 failed 中仍有未超过 MAX_ATTEMPTS 次数的页面,整体重新入队再跑一轮(crawler.py#L196-L203);
  3. 每轮之间都 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 道防线:

  1. 合法性过滤:非图片协议(javascript:、mailto:)、非同站、不在前缀白名单内的 URL 直接跳过;
  2. 内存级去重:seen_images 集合记录已下载 URL,同一图片出现在多个页面时只下一次;
  3. 磁盘级去重:若 webpath_images/ 下对应文件已存在(crawler.py#L113-L115),说明上次已下载,直接标记跳过——这意味着爬虫支持断点续抓,中断后重跑不会重复下载;
  4. 内容类型校验:只有响应 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 智能体知识链路的第一环:

  1. 抓取:crawler.py 产出 webpath_images/(图片)+ webpath_texts/(配对文本);
  2. 向量化:图片与文本经 BAAI/bge-m3 编码为向量,存入 Postgres + pgvector(技术细节见 PathoMind-介绍文档.md 中"存储与访问"与"检索策略"章节);
  3. 检索问答:智能体收到用户提问后,通过 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 项目构建垂直领域图文数据集的新手来说,是一份可以直接参考的模板。

登录后查看全文
病理知识问答智能体PathoMind