scientific-agent-skills：IDC DICOMweb 接入完全指南——双端点选型、QIDO/WADO 实操与数据覆盖差异

scientific-agent-skillsIDC DICOMweb 接入完全指南——双端点选型、QIDO/WADO 实操与数据覆盖差异【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills本篇基于scientific-agent-skills仓库中 imaging-data-commons 技能的 DICOMweb 指南 展开。IDCNCI Imaging Data Commons国家癌症研究所影像数据公共平台通过 Google Cloud Healthcare API 的 DICOM 存储对外提供 DICOMweb 协议访问。读完本文你将掌握何时该选 DICOMweb 而非idc-index直连、IDC 公开代理端点与 Google Healthcare API 端点在数据覆盖和配额上的差异、QIDO-RS/WADO-RS 的完整查询流程、Google Cloud 认证配置以及 400/403/429/204 等常见错误的排查路径。什么时候该用 DICOMwebDICOMweb 不是访问 IDC 的最简路径它有明确的使用场景。指南原文给出的判定条件如下出现以下需求之一时才值得走 DICOMweb 协议需要与 PACS 系统或 DICOMweb 兼容工具如 OHIF做集成需要在不下载完整 DICOM 文件的情况下流式获取元数据构建自定义 Web 查看器或前端应用复用已有的 DICOMweb 客户端库OHIF、dicomweb-client等。对于大多数其他场景idc-index更简单也是官方推荐路径。在 SKILL.md 的 Data Access Options 路由表中两条 DICOMweb 路径的定位与本文一致访问方式认证适用场景DICOMweb via IDC 代理无工具/PACS 集成有每日配额适合测试和中等用量DICOMweb via Google Healthcare需要 GCP 认证同 API 的生产级用量不受代理配额限制注意一个适用前提本技能当前校验的 IDC 数据版本为v24见 SKILL.md frontmatter 中idc-data-version: v24且要求idc-index 0.12.5。Google Healthcare 端点的 URL 中必须显式写出版本号因此在会话开始时先用client.get_idc_version()确认当前版本是必要步骤下文有代码。两个端点公开代理 vs Google Healthcare APIIDC 提供两条 DICOMweb 接入路径它们在数据覆盖、更新时效、配额、认证要求上完全不同选型前必须理解差异。端点一IDC 公开代理无需认证https://proxy.imaging.datacommons.cancer.gov/current/viewer-only-no-downloads-see-tinyurl-dot-com-slash-3j3d9jyp/dicomWeb关键特性均来自指南原文100% 数据覆盖——包含来自所有存储桶storage buckets的完整 IDC 数据自动指向最新 IDC 版本URL 中的current新 IDC 版本发布后立即更新按 IP 计每日配额per-IP daily quota适合测试和中等用量无需任何认证只读访问注意URL 中的 viewer-only-no-downloads 是历史遗留命名没有实际功能含义——你仍然可以通过它检索完整的 DICOM 实例字节。端点二Google Cloud Healthcare API需要认证https://healthcare.googleapis.com/v1/projects/nci-idc-data/locations/us-central1/datasets/idc/dicomStores/idc-store-v{VERSION}/dicomWeb将{VERSION}替换为 IDC 发布版本号。用idc-index查询当前版本from idc_index import IDCClient client IDCClient() print(client.get_idc_version()) # 例如当前版本为 v24特性对比约 96% 数据覆盖——只复制了idc-open-data一个桶的数据缺少约 4% 的其余桶数据在 IDC 版本发布后 1–2 周才更新需要 GCP 认证但提供更高配额性能更好直连无代理路由每个 IDC 版本对应一个独立的新版存储idc-store-v{VERSION}。数据覆盖差异为什么公开代理反而更全这是本文档最容易踩坑的点值得单独展开IDC 公开代理包含的数据比经过认证的 Google Healthcare 端点更多。覆盖概览端点覆盖缺失数据IDC 公开代理100%无Google Healthcare API约 96%约 4%两个桶未被复制Google Healthcare 缺了什么Google Healthcare 的 DICOM 存储只从idc-open-dataS3 桶复制数据不包含另外两个桶idc-open-data-cridc-open-data-two这两个桶通常各含数千个 series合计约占 IDC 总量 4%精确数量随 IDC 版本变化。这一点可以从仓库内另外两份材料得到交叉印证云存储指南 的桶汇总表明确列出idc-open-data为主数据桶90% 数据idc-open-data-cr/idc-open-cr为商业使用受限桶CC BY-NC约 4% 数据idc-open-data-two/idc-open-idc1为头部扫描桶。该指南还特别提醒使用idc-index获取许可信息——不要依赖桶名判断许可。SKILL.md 在 Cloud storage organization 小节同样注明idc-open-data-cr/idc-open-cr约 4% 数据受商业使用限制CC BY-NC并指向 云存储指南 获取完整桶列表与 UUID 映射。更新时序IDC 公开代理新版本发布后立即更新Google Healthcare新版本发布后 1–2 周才更新。版本发布之间的常规运行期两个端点都保持最新1–2 周的延迟只发生在新版本发布后的过渡期。IDC 官方文档对此有明确警告Google-hosted DICOM store may not contain the latest version of IDC data!——在新版本发布后的几周里务必核对。如何选端点选 IDC 公开代理当需要 100% 完整数据覆盖需要在新版本发布后立即拿到最新数据不想配置 GCP 认证用量在每 IP 配额内可向 supportcanceridc.dev 申请提升按帧访问病理切片slide microscopy图像。选 Google Healthcare API当缺失的 ~4% 数据不影响你的用例大用量场景需要更高配额想要更好的性能直连、无代理路由。用 SQL 预检你的数据是否在缺失桶中选定端点之前先用idc-index查一下目标 collection 的数据分布在哪些桶——桶信息就编码在series_aws_url列里from idc_index import IDCClient client IDCClient() # 查看你的 collection 的数据在哪些桶 results client.sql_query( SELECT series_aws_url, COUNT(*) as series_count FROM index WHERE collection_id your_collection_id GROUP BY series_aws_url ) print(results) # 寻找包含 idc-open-data-cr 或 idc-open-data-two 的 URL # 若存在则那部分数据在 Google Healthcare 端点不可用这个预检查询依赖的series_aws_url列在 云存储指南 中有详细说明它是 series 文件夹级别的 S3 URL形如s3://idc-open-data/crdc_series_uuid/*GCS 侧路径结构完全相同把s3://换成gs://。实现细节受支持的操作与可搜索 TagIDC 的 DICOMweb 由 Google Cloud Healthcare API DICOM 存储提供实现遵循 DICOM PS3.18 Web Services 规范并按 Google Healthcare DICOM conformance statement 文档化其具体行为。以下限制在写查询代码前必须牢记。受支持的操作服务描述支持情况QIDO-RS检索 DICOM 对象搜索支持WADO-RS获取 DICOM 对象与元数据支持STOW-RS存储 DICOM 对象不支持IDC 只读明确不支持URI Service、Worklist Service、Non-Patient Instance Service、Capabilities Transactions。QIDO-RS 可搜索的 DICOM Tag实现只支持一个受限的可搜索 Tag 集合层级可搜索 TagStudyStudyInstanceUID, PatientName, PatientID, AccessionNumber, ReferringPhysicianName, StudyDateSeries全部 study 级 tag SeriesInstanceUID, ModalityInstance全部 series 级 tag SOPInstanceUID重要限制只支持精确匹配唯二例外是StudyDate支持范围查询PatientName支持模糊匹配。查询规模限制最大返回结果数studies/series 搜索5,000条instances 搜索50,000条最大 offset1,000,000大于约 1 MB 的 DICOM 序列 tag 不会包含在元数据响应中会给出 BulkDataURI 作为替代获取途径。完整代码示例从 UID 发现到 WADO-RS 元数据流以下示例全部基于公开代理端点无需认证可直接复制运行。推荐的整体工作流是idc-index 负责发现DICOMweb 负责元数据流式访问——因为 QIDO-RS 的可搜索 Tag 有限用 SQL 先定位 UID再用 UID 走 DICOMweb是规避 400 错误的稳妥路径。第一步用 idc-index 发现 UIDfrom idc_index import IDCClient client IDCClient() # 找到感兴趣的 study results client.sql_query( SELECT StudyInstanceUID, SeriesInstanceUID, PatientID, Modality FROM index WHERE collection_id tcga_luad AND Modality CT LIMIT 5 ) # 将这些 UID 用于 DICOMweb study_uid results.iloc[0][StudyInstanceUID] series_uid results.iloc[0][SeriesInstanceUID] print(fStudy: {study_uid}) print(fSeries: {series_uid})QIDO-RS按 UID 搜索 Studyimport requests base_url https://proxy.imaging.datacommons.cancer.gov/current/viewer-only-no-downloads-see-tinyurl-dot-com-slash-3j3d9jyp/dicomWeb # 搜索指定 study study_uid 1.3.6.1.4.1.14519.5.2.1.6450.9002.307623500513044641407722230440 response requests.get( f{base_url}/studies, params{StudyInstanceUID: study_uid}, headers{Accept: application/dicomjson} ) if response.status_code 200: studies response.json() print(fFound {len(studies)} study)QIDO-RS列出 Study 下的 Seriesimport requests base_url https://proxy.imaging.datacommons.cancer.gov/current/viewer-only-no-downloads-see-tinyurl-dot-com-slash-3j3d9jyp/dicomWeb study_uid 1.3.6.1.4.1.14519.5.2.1.6450.9002.307623500513044641407722230440 response requests.get( f{base_url}/studies/{study_uid}/series, headers{Accept: application/dicomjson} ) if response.status_code 200: series_list response.json() for series in series_list: # DICOM tag 以十六进制编码返回 series_uid series.get(0020000E, {}).get(Value, [None])[0] modality series.get(00080060, {}).get(Value, [None])[0] description series.get(0008103E, {}).get(Value, [])[0] print(f{modality}: {description})注意响应结构的统一形态每个 tag 是{Key: Value}或{VR: ..., Value: [...]}的字典取值时要走.get(Value, [None])[0]这条链。QIDO-RS列出 Series 下的 Instanceimport requests base_url https://proxy.imaging.datacommons.cancer.gov/current/viewer-only-no-downloads-see-tinyurl-dot-com-slash-3j3d9jyp/dicomWeb study_uid 1.3.6.1.4.1.14519.5.2.1.6450.9002.307623500513044641407722230440 series_uid 1.3.6.1.4.1.14519.5.2.1.6450.9002.217441095430480124587725641302 response requests.get( f{base_url}/studies/{study_uid}/series/{series_uid}/instances, params{limit: 10}, headers{Accept: application/dicomjson} ) if response.status_code 200: instances response.json() print(fFound {len(instances)} instances) for inst in instances[:3]: sop_uid inst.get(00080018, {}).get(Value, [None])[0] print(f SOPInstanceUID: {sop_uid})WADO-RS获取 Series 元数据import requests base_url https://proxy.imaging.datacommons.cancer.gov/current/viewer-only-no-downloads-see-tinyurl-dot-com-slash-3j3d9jyp/dicomWeb study_uid 1.3.6.1.4.1.14519.5.2.1.6450.9002.307623500513044641407722230440 series_uid 1.3.6.1.4.1.14519.5.2.1.6450.9002.217441095430480124587725641302 response requests.get( f{base_url}/studies/{study_uid}/series/{series_uid}/metadata, headers{Accept: application/dicomjson} ) if response.status_code 200: instances response.json() print(fRetrieved metadata for {len(instances)} instances) # 从第一个实例中提取图像尺寸 if instances: inst instances[0] rows inst.get(00280010, {}).get(Value, [None])[0] cols inst.get(00280011, {}).get(Value, [None])[0] print(fImage dimensions: {rows} x {cols})这个例子恰好演示了 DICOMweb 的核心价值/metadata端点一次返回整个 series 所有实例的元数据不需要下载任何像素数据——对于先盘点数据再决定下载什么的场景非常关键。组合工作流idc-index 发现 DICOMweb 元数据流from idc_index import IDCClient import requests # 用 idc-index 做高效发现 idc IDCClient() results idc.sql_query( SELECT StudyInstanceUID, SeriesInstanceUID, Modality, SeriesDescription FROM index WHERE collection_id nlst AND Modality CT LIMIT 1 ) study_uid results.iloc[0][StudyInstanceUID] series_uid results.iloc[0][SeriesInstanceUID] print(fFound: {results.iloc[0][SeriesDescription]}) # 用 DICOMweb 流式获取元数据不下载文件 base_url https://proxy.imaging.datacommons.cancer.gov/current/viewer-only-no-downloads-see-tinyurl-dot-com-slash-3j3d9jyp/dicomWeb response requests.get( f{base_url}/studies/{study_uid}/series/{series_uid}/metadata, headers{Accept: application/dicomjson} ) if response.status_code 200: metadata response.json() print(fRetrieved metadata for {len(metadata)} instances without downloading files)常用 DICOM Tag 速查表DICOMweb 响应中 tag 以十六进制码为键以下是最常用的对照表与指南一致Tag名称说明00080018SOPInstanceUID实例唯一标识00080020StudyDate检查日期00080060Modality影像模态CT、MR、PT 等0008103ESeriesDescriptionseries 描述00100020PatientID患者标识0020000DStudyInstanceUIDstudy 唯一标识0020000ESeriesInstanceUIDseries 唯一标识00280010Rows图像高度像素00280011Columns图像宽度像素Google Healthcare API 的认证配置要使用高配额的 Google Healthcare 端点需要配置 GCP 认证。完整示例from google.auth import default from google.auth.transport.requests import Request import requests # 获取凭据需要先 gcloud auth credentials, project default() credentials.refresh(Request()) # 构建带认证的请求 base_url https://healthcare.googleapis.com/v1/projects/nci-idc-data/locations/us-central1/datasets/idc/dicomStores/idc-store-v24/dicomWeb response requests.get( f{base_url}/studies, params{limit: 5}, headers{ Authorization: fBearer {credentials.token}, Accept: application/dicomjson } )前置条件已安装 Google Cloud SDKgcloud已完成认证gcloud auth application-default login账户有权访问 Google Cloud 公共数据集。注意base_url中的idc-store-v24必须与实际数据版本匹配——这正是前文强调会话开始先跑client.get_idc_version()的原因版本号写错会直接查不到数据。故障排查6 类高频问题以下排查路径完整继承自指南每一条都对应一个明确的根因与解法400 Bad Request搜索查询原因使用了不受支持的搜索参数。实现只允许特定 DICOM tag 参与过滤。解法改用基于 UID 的查询StudyInstanceUID、SeriesInstanceUID。如需按 Modality 等其他属性过滤先用idc-index定位 UID再用具体 UID 查 DICOMweb。403 ForbiddenGoogle Healthcare 端点原因缺少认证或权限不足。解法执行gcloud auth application-default login并确认账户有访问权限。429 Too Many Requests原因触发速率限制。解法在请求之间加入延迟、减小limit值或改用带认证的端点获得更高配额。204 No ContentUID 明明存在原因UID 可能来自旧版 IDC 数据而不在当前数据集中或数据位于 Google Healthcare 未复制的桶中。解法先用idc-index查询确认 UID 存在检查数据是否在idc-open-data-cr或idc-open-data-two桶Google Healthcare 端点不可用切换到 IDC 公开代理获得 100% 覆盖新版本发布期间Google Healthcare 可能滞后 1–2 周。大元数据响应解析缓慢原因实例很多的 series 返回巨大 JSON。解法在 instance 查询上加limit参数或按 SOPInstanceUID 查询特定实例。响应缺少预期属性原因大于约 1 MB 的 DICOM 序列被排除在元数据响应之外。解法如需完整属性用 WADO-RS 实例检索instance retrieval获取整个 DICOM 对象。与技能内其他指南的关系本技能skills/imaging-data-commons采用主文档 按需加载参考指南的组织方式DICOMweb 只是 IDC 数据访问路径矩阵中的一环。当 DICOMweb 方案不适用时可以从以下仓库内文档继续深入云存储指南——直连 S3/GCS 桶、CRDC UUID 文件组织、版本管理与s5cmd批量下载BigQuery 指南——需要完整 DICOM 属性含私有元素时的进阶元数据查询需 GCP 认证REST API 指南——无认证的https://api.imaging.datacommons.cancer.gov/v3元数据路径index 表指南——idc-index各索引表的完整 schema 与 JOIN 规则。会话启动时的版本校验由 check_version.py 承担它验证idc-index已安装且不低于技能钉扎的最低版本当前 0.12.5版本不满足时打印针对当前解释器的安装命令并以非零码退出——该脚本自身永不安装任何东西这一行为约束由 tests/imaging-data-commons/test_check_version.py 中的TestNeverInstalls等契约用例保障。最后提醒两条来自主文档的最佳实践其一按 UID 走 DICOMweb 之前务必用idc-index做发现不要猜Modality等字符串值直接过滤——过滤猜测值导致空结果是最常见的错误来源其二IDC 数据携带许可条款约 97% CC BY、约 3% CC BY-NC且许可绑定在 series 而非 collection 级别任何下游使用与发表前都应核对许可并生成引用。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考