医学影像分析 bowang-lab/dsh-medomni

DeepSeek Harness × MedOmni：一个用于生物医学图像分析的可组合智能体框架

图表制作由 ChatGPT 协助完成。

=22" />

演示

https://github.com/user-attachments/assets/8a098d95-8d24-44bd-8435-67e52450c524

目录

- 本插件的作用
- 演示
- 环境要求
- 快速开始
- 为粘贴的图像启用图像输入
- 使用示例
- 工具
- 添加新工具
- 禁用 / 重新启用
- 配置
- 故障排除
- 适用范围
- 许可证

本插件的作用

dsh-medomni 是 MedOmni 策略在医学图像分析方面的预览实现。它为语言模型智能体提供了一组特定模态的工具，使其能够根据自然语言请求选择合适的工作流：

- 报告生成： 为胸部 X 射线、CT、MRI 和视网膜图像生成候选报告；比较当前与既往胸部 X 射线以判断间期变化。
- 定位： 用证据框定位可疑的胸部 X 射线发现，定位指定的胸部 X 射线发现，并标注正常的胸部 X 射线解剖结构。
- 分割： 为 X 射线、超声、视网膜图像、CT NIfTI 体数据和 MRI NIfTI 体数据中提示的发现或结构生成掩膜和叠加图；对 CT 和 MRI 体数据执行固定标签的解剖结构分割。
- 分类： 对超声图像进行分类，以支持在定向定位之前先进行分类的工作流。
- 智能体引导的路由： 根据自然语言请求选择报告生成、分类、定位或分割工具，并返回结构化结果及预览图像。
- 输入处理： 通过支持图像的服务商路由粘贴受支持的 2D 图像，或通过路径提供它们。通过文件系统路径提供 3D CT/MRI 研究数据；所有 3D 工具都支持 NIfTI，而报告和固定标签分割工具支持 DICOM 目录。

数据和网络披露： 模型推理在配置的机器上本地运行。该插件连接到 Hugging Face 以下载模型检查点，并仅将 HF_TOKEN 用于受限模型的访问；该令牌从进程环境中读取，不会由插件存储。输入文件和生成的预览从本地文件系统读取或写入，并根据周围的 DSH 会话进行保留。所选 DSH 语言模型提供程序的行为由 DSH 及其提供程序配置控制，而非由本插件控制。

要求

在安装插件之前，请准备以下项目：

- 一个 DeepSeek Harness dsh 安装。
- 配备 CUDA 的 NVIDIA GPU。 某些工具可使用 CPU 模式，但这些数 GB 大小的视觉语言和分割模型在没有 GPU 的情况下通常不切实际。
- PATH 上可用的 uv、git 和 Python 3。uv 创建隔离环境；git 由 BiomedParse 在首次使用时调用。
- 对受限检查点的 Hugging Face 访问权限：接受 MAIRA-2 (microsoft/maira-2)、BiomedParse (microsoft/BiomedParse) 和 MedGemma 的条款。BiomedCLIP 是公开的。
- 一个 Hugging Face 读取令牌。在 Hugging Face 设置中创建一个，然后运行 hf auth login 或使用 export HF_TOKEN=hf_... 导出它。

无需手动下载任何检查点。所需模型会在其工具首次使用时自动下载。可选的预取命令记录如下。

快速开始

按顺序执行以下步骤。

1. 检查先决条件

确认所需命令可用：

python3 --version
uv --version
git --version

如果缺少 uv，请使用官方 uv 说明安装它。如有需要，请使用操作系统的包管理器安装 Python 3 和 Git。

2. 使用 Hugging Face 进行身份验证

在接受要求中列出的受限模型条款后，在将运行 DSH 的同一 shell 或用户账户中进行身份验证：

hf auth login

或者：

export HF_TOKEN=hf_...

3. 安装插件

dsh plugin --profile web add github:bowang-lab/dsh-medomni
这将把 dsh-medomni 添加到你的配置文件的 package.json 中，并自动安装 cordis.patch.yml（将该插件挂载到 id dsh-medomni 下）。之后重启 dsh（或你的 DSH Desktop/web 会话），以便加载新的 bundle。

4. 准备 MedOmni 环境

在安装该插件的配置文件目录中运行 setup 命令：

cd ~/.dsh/profiles/web
./node_modules/.bin/dsh-medomni setup

这会创建共享的 Python 环境并安装常用依赖。它不会安装每个模型或 BiomedParse 的额外组件。这些仍保持懒加载，因此用户只下载他们实际使用的内容。

[!NOTE]
可选：预取检查点。 正常使用会在首次使用时自动下载每个所需的检查点。仅当你希望提前下载某个检查点时，在通过 Hugging Face 完成身份验证后运行以下命令之一：

hf download microsoft/maira-2
hf download microsoft/BiomedParse biomedparse_v1.pt
hf download microsoft/BiomedCLIP-PubMedBERT_256-vit_base_patch16_224
hf download google/medgemma-1.5-4b-it

5. 用纯文本提问

无需预先构建或下载任何内容。向你的 agent 提出类似这样的请求：

“为这张胸部 X 光片生成一份放射学报告：/path/to/chest_xray.png”

它会自行选择匹配的工具。对某个模型/依赖组的首次调用可能仍会下载其检查点；BiomedParse 在首次使用时还会克隆其仓库并构建 detectron2。后续调用会复用已下载的文件。随时运行 dsh-medomni doctor 查看设置进度（参见故障排除）。

为粘贴的图片启用图像输入

接受 2D 图像的工具（X 光、超声、视网膜，以及分类/报告工具）也接受粘贴的图片，而非文件系统路径——但仅当所选的 provider 路由声明支持图像输入时。

[!IMPORTANT]
在粘贴图片之前，打开聊天输入框右下角的模型选择器，并选择标记为“+ dsh-medomni Vision”的条目。

DSH 会在任何插件看到粘贴的图片之前，就在纯文本 provider 路由上拒绝它。因此，dsh-medomni 为 2D 医学图像添加了一条启用图像的路由，它在选择器中显示为“DeepSeek + dsh-medomni Vision”。选择此路由（如下图所示），然后正常粘贴。

在粘贴 2D 医学图像之前，选择标记为 + dsh-medomni Vision 的 provider 条目。

启用图像的路由使用与原始路由相同的 provider、模型和语言模型；它不是第二个模型。其适配器会将粘贴的图片转换为一个附件标识符，语言模型可将该标识符传递给 dsh-medomni 工具。该工具会将该标识符解析为图像字节，并运行所选的医学影像模型。

[!IMPORTANT]
3D CT 和 MRI 输入必须以文件系统路径的形式提供，指向 NIfTI 卷或 DICOM 目录。粘贴图像输入仅支持该插件的 2D 图像工具；它不适用于 CT/MRI 体积工具。

在插件配置中设置 wrapProviders: false 以禁用这些启用图像的路线（参见配置）。

输入示例

3D CT/MRI — 需要文件系统路径：

Analyze this 3D scan: /path/to/scan.nii.gz

对于支持 DICOM 输入的工具，你也可以提供 DICOM 目录路径。

2D 图像 — 文件系统路径或粘贴图像：

Analyze this chest X-ray: /path/to/chest_xray.png

对于粘贴的 X 光、超声或视网膜图像，选择 + dsh-medomni Vision 路线，将图像直接粘贴到编辑器中，并在同一条消息中提出你的问题。

工具

添加新工具

新工具应遵循现有模式：在 skills// 下放置一个 Python 脚本，在 index.js 中添加 SCRIPTS 条目以及 defineTool 注册，在工具 description 中提供面向智能体的明确说明，可选支持预览附件，以及更新包/测试。

有关完整的分步检查清单和示例，请参见添加新工具。

模态技能

dsh-medomni 将这些模态工作流注册为模型可调用的 DSH 技能。当请求需要特定模态的工具序列时，智能体可以加载相关技能；现有的工具描述仍然是直接的工具选择契约。

- 胸部 X 光
- CT
- MRI
- 超声
- 视网膜成像

禁用 / 重新启用

- id: dsh-medomni
disabled: true

将其设置回 false（或删除该行）以重新启用。卸载会移除工具、启用图像的路线以及设置界面；任何已写入会话工作区的内容都会保留。

配置

无需任何配置——该插件默认使用此包内附带的 skills/ 目录。仅当你想要指向这些脚本的其他副本时，才在你的配置文件的 cordis.patch.yml 中进行覆盖：

- upsert:
- id: dsh-medomni
config:
skillsDir: /path/to/other/skills # optional, default: this package's own skills/
pythonBin: python3 # optional, default "python3"
timeoutMs: 1800000 # optional, default 30 minutes
wrapProviders: true # optional, default true — adds image-enabled "-dsh-medomni" routes
excludedProviders: [] # optional — provider ids never wrapped
故障排除

dsh-medomni doctor 会在不调用任何模型的情况下检查本机的设置——uv//git/python3 是否在 PATH 上、共享 venv 是否存在，以及 BiomedParse 的一次性设置进行到了哪一步：

cd ~/.dsh/profiles/web
./node_modules/.bin/dsh-medomni doctor

或者，直接针对本仓库的本地检出运行：

node /path/to/dsh-medomni/lib/doctor-cli.js

skills/: /path/to/dsh-medomni/skills
✓ uv — uv 0.10.7 ✓ git — git version 2.34.1 ✓ python3 — Python 3.12.12

✓ shared venv
torch pin: torch==2.10.0
torch 2.10.0+cu128, CUDA available: true

✓ BiomedParse repo cloned
✓ BiomedParse extra dependencies installed
✓ detectron2 built
✓ BiomedParse weights downloaded — 1.7GB

一行 ✗ 会准确指出缺少什么以及为什么重要。BiomedParse 某一行未勾选本身并不是错误——该阶段只会在 _biomedparse 工具首次调用时运行——但如果此类调用失败，这是首先要查看的地方。如果你的配置文件覆盖了插件的默认 skillsDir，请传入 --skills-dir 。

范围

- 这是 MedOmni 及其工具策略的预览版本，而不是涵盖所有医学影像模型系列的通用注册表。只有遵循 MedOmni 工具协议的工具才会被包含：每个工具都在 index.js 中声明其契约，使用标准执行路径，返回结构化 JSON，并在导入模型依赖之前引导一个隔离的 Python 环境。
- 其他不遵循此协议的模型系列和工具被有意排除在此预览版之外。例如，一些管/线检测和骨折工具的后端脚本没有自己的隔离 venv 引导。它们从恰好处于活动状态的任何环境 Python 环境中导入裸 torch/transformers，这可能与诸如 MAIRA-2 的 transformers>=4.48,/ 下脚本的 SCRIPTS 条目、一个匹配的 defineTool 注册（其 execute 会通过 shell 调用该脚本并解析其 JSON stdout）、明确的面向代理的工具说明，以及脚本顶部的 skills/_bootstrap.py 引导。

许可证

MIT