一张切片如何找到相似病例?PathoMind pgvector多模态向量检索完整指南
一张切片如何找到相似病例?PathoMind pgvector多模态向量检索完整指南
PathoMind 是一个病理知识问答智能体,它的核心能力之一是多模态向量检索:上传一张病理切片,系统通过 pgvector 在病例库中秒级找出相似病例,并联动文献证据库给出结构化分析。本文带你完整理解 PathoMind 的向量检索链路:从切片图片 → 图像向量 → 相似病例命中,以及背后的 bge-m3、PostgreSQL + pgvector 与 MinIO 各自承担什么角色。
一张切片是如何"认出"相似病例的?
传统检索靠关键词:你得先知道病例里写了"干酪样坏死"才能搜到它。但一张切片图片本身没有文字,关键词检索对它完全失效。
PathoMind 的解法是多模态向量检索:
| 环节 | 技术 | 作用 |
|---|---|---|
| 图像/文本编码 | BAAI/bge-m3(文本向量)+ CLIP(图像向量) | 把图片和文字变成数字向量 |
| 向量存储 | PostgreSQL + pgvector 扩展 | 存储与距离计算,vector(1024) 维度统一 |
| 图片存储 | MinIO(S3 兼容对象存储) | 保存切片原图,生成可访问 URL |
| 检索编排 | MCP 工具 search_similar_cases |
一条指令串联"取图→算向量→查库→返回证据" |
核心思想:图片和文本被编码到同一个 1024 维向量空间。两张图越像,它们的向量距离越近;一句"梭形细胞增生"和一张含梭形细胞的切片,向量也会彼此靠近——这就是"多模态"的含义。
详细说明可见 PathoMind-介绍文档.md 的"技术实现说明"章节。
pgvector 是如何被用起来的?
pgvector 是 PostgreSQL 的向量扩展。PathoMind 只需三步就把它装好了,逻辑集中在 MCP 主服务中:
- 建扩展与建表:
CREATE EXTENSION IF NOT EXISTS vector;后自动建两张表pathology_cases(病例库):image_url、caption、tags、source_doc、source_page、image_embedding vector(1024)、text_embedding vector(1024)pathology_texts(文献文本库):doc_name、chunk、page、text_embedding vector(1024)
- 写入用 UPSERT:
INSERT ... ON CONFLICT (id) DO UPDATE,同一病例重复入库会更新而不是报错 - 查询用距离算子:
ORDER BY image_embedding <-> %s LIMIT k,<->计算向量间距离,距离最小者排最前
对应源码在 env.zip 包内的
env/mcp_app.py:建表函数ensure_tables(L143-L175)、距离查询函数query_vector(L395-L417)。
核心工具:search_similar_cases 的四步工作流
这是"一张切片找到相似病例"的关键工具,定义见 PathoMind.json。它接收 image_url、可选 query、top_k(默认 5),内部按四步执行:
Step 1 · 图像向量化
embed_image 优先调用本地 CLIP(OPEN_CLIP_MODEL,如 ViT-B-32)生成图像 embedding;同时让 VLM 为图片生成一段病理特征描述(vlm_caption)。若 CLIP 未配置,系统自动降级:用 VLM 描述文本做向量化,近似替代图像向量——即使没有 GPU 也能跑通检索。
Step 2 · 图像向量查病例库
用图像向量对 pathology_cases.image_embedding 做近邻检索,得到 cases_by_image:最像的几张切片及其 caption、来源文档与页码。
Step 3 · 文本向量双路补充
若提供了文本 query 有则用之,否则回退用 VLM 生成的描述文本向量化,再查两路:
pathology_cases.text_embedding→cases_by_text(病例的文字相似)pathology_texts.text_embedding→kb_hits(文献段落命中,如教材中的相关描述)
Step 4 · 结构化返回
返回 {vlm_caption, cases_by_image, cases_by_text, kb_hits},URL 统一映射到 MINIO_PUBLIC_ENDPOINT,保证浏览器可直接打开图片。
实现源码:env.zip 内
env/mcp_app.py的search_similar_cases_impl(L698-L743)。
💡 距离分数直观理解:few-shot 示例中"相似病例 A(相似度 0.82)、B(0.79)",分数越接近 1 表示越相似,可辅助判断结果可信度。
病例库是怎么建起来的?——批量入库流程
没有数据,检索无从谈起。PathoMind 提供从 PDF 一键建库的批处理管线:
| 步骤 | 工具/命令 | 产出 |
|---|---|---|
| 1. 抽取 | extract_pdf_images |
从 PDF 提取图片与页面文本,存至 data/extracted |
| 2. 存图 | upload_to_minio |
图片上传 MinIO,得到稳定 URL |
| 3. 向量化 | embed_image / embed_text |
图像向量 + 文本向量(bge-m3) |
| 4. 写库 | upsert_case |
记录进入 pathology_cases |
| 5. 文献 | ingest_pdf_text |
PDF 文本按 chunk_size(默认 800 字符)切块入 pathology_texts |
CLI 一键批量入库(--mode caption 表示用图注做向量编码,成本低、速度快;vlm 模式则叠加 VLM 描述):
python mcp_app.py ingest --pdf AIDS2025.pdf --mode caption --limit 20
说明:README.md 的运行说明中写作
file.pdf --mode caption;本仓库直接提供 AIDS2025.pdf 教材,核心知识库正是基于它与 webpath 抓取内容构建。
环境配置速览
运行前需准备三类服务:向量接口(API_BASE + API_KEY,模型 BAAI/bge-m3)、MinIO(MINIO_ENDPOINT / MINIO_BUCKET)、PostgreSQL + pgvector(PG_DSN)。完整键值清单见 env.zip 内 env/.env.example。
智能体如何编排整条链路?
PathoMind 智能体(配置见 PathoMind.json,视觉模型 Qwen/Qwen3-VL-32B-Instruct)遵循"意图路由 + 多模态思维链":
- 有图片输入 →
embed_image/analyze_image提取特征 →search_similar_cases检索相似病例 →knowledge_base_search补充文献证据 - 纯文本提问 → 直接走
knowledge_base_search(支持 hybrid/accurate/semantic 三种模式,默认top_k=5)
最终输出强制按五段式结构:主要特征 / 相似病例 / 文献证据 / 不确定性 / 建议,且每条证据必须标注来源([Source:ID] 内源教材或真实 URL 外源检索),避免无据结论。
常见问题:向量检索的 5 个实用细节
1. 向量维度为什么都是 1024?
统一由 VECTOR_DIM = 1024 控制,pad_vector 会把过短的向量补零、过长的截断,保证任何来源的向量都能写入同一种列。
2. 没有配置 CLIP 还能用图像检索吗? 可以。降级策略:VLM 生成图片描述 → 描述文本向量化 → 与文本向量同空间比对,精度略降但链路完整。
3. 向量检索失败怎么办?
search_pathology_images 内置回退:向量检索异常或无结果时,自动降级为 caption ILIKE '%关键词%' 模糊匹配,并在返回中标注 mode: caption。
4. 返回的图片 URL 打不开?
确认 MINIO_PUBLIC_ENDPOINT 已配置——系统会把容器内网地址映射为宿主机可访问地址(如 http://127.0.0.1:9012/...)。
5. 相似病例结果如何解读?
结合三路结果交叉验证:cases_by_image(长得像)、cases_by_text(描述像)、kb_hits(文献支撑)。三路都指向同一方向时,结论可信度最高;若互相矛盾,输出中的"不确定性"字段会提示补充染色方法、倍率等信息。
小结:PathoMind 向量检索链路一图速记
切片图片 ──CLIP/VLM──> 图像向量(1024) ──pgvector <-> 距离──> pathology_cases 相似病例
│
└─VLM描述──bge-m3──> 文本向量 ──┬──> pathology_cases(文字相似)
└──> pathology_texts(文献证据)
↓
结构化输出:特征 / 相似病例 / 文献证据 / 不确定性 / 建议(强制标注来源)
延伸资料
- 项目总览与架构:README.md
- 智能体完整介绍(工具清单/交互流程/技术实现):PathoMind-介绍文档.md
- 智能体配置导出(模型、提示词、工具定义):PathoMind.json
- 核心教材知识库来源:AIDS2025.pdf
- 权威网站数据抓取脚本(webpath 文本与图片):crawler.py
- 实际效果演示:演示视频.mp4