openFDA — 美国食品药品监管开放数据中枢 AI-Ready Wikipedia

美国 FDA 全品类监管数据统一 API：5,500 万+ 条记录、25+ 端点、CC0 开放

来源 美国食品药品监督管理局（U.S. Food and Drug Administration） url: https://open.fda.gov/发布时间: 2026-09-15最后更新: 2026-09-25 阅读 39
openFDA — 美国食品药品监管开放数据中枢 AI-Ready Wikipedia

信息速览

数据集名称openFDA — 美国食品药品监管开放数据中枢 AI-Ready Wikipedia
数据类型5,500 万+ 条监管记录,25+ 个开放端点,CC0 公有领域许可,JSON API 与压缩包下载,季度提取与持续更新
规模2,000 万+ 份药品不良事件报告（FAERS，截至 2026-09）
接入方式美国食品药品监督管理局（U.S. Food and Drug Administration） url: https://open.fda.gov/
AI 就绪度

数据集封面

openFDA — 美国食品药品监管开放数据中枢 AI-Ready Wikipedia

INFOBOX

字段 内容
数据集名称 openFDA 开放数据平台
英文全称 openFDA
别名/简称 open.fda.gov；FDA 开放数据 API
疾病分类（ICD-11） NE6 药物、药剂或生物制品在治疗使用中的不良效应；4A84 过敏性休克
SNOMED CT 64572001 疾病（根概念）；419099009 Dead（死亡结局参照）
数据模态 药品/器械/食品监管结构化记录（FAERS、MAUDE、召回执法、SPL 标签、NDC、NSDE）
AI 任务类型 药物警戒信号检测、召回监测与分类、监管文本 NLP、检索增强问答
样本总数 5,500 万+ 条记录（25+ 端点合计，截至 2026-09）
数据大小 各端点独立发布压缩 JSON 批量包；未公开统一总量口径
数据格式 JSON（实时 API）；压缩 JSON（批量下载）
许可证 CC0 1.0 Universal（公有领域贡献）
访问级别 开放（免费；可选注册 API key 提升限流额度）
DUO 标签 NRES 无限制
语言 英语为主（含多国来源报告的英文化编码字段）
首发日期 2014-06-02
最后更新 持续滚动更新（各端点独立 last_updated，截至 2026-09）
发布机构 美国食品药品监督管理局（U.S. FDA）
官方主页 https://open.fda.gov/
下载地址 https://open.fda.gov/data/downloads/
DOI 10.1093/jamia/ocv153（平台原始论文）
引用次数 182+（Google Scholar 口径聚合源 exaly，截至 2025-02）
AI 就绪度评分 ⭐⭐⭐⭐（4/5）— 官方统一 REST API、字段文档与 count 聚合齐全；扣分项：嵌套 JSON 需自行摊平、分页存在 25,000 硬上限、无官方训练划分与预处理脚本
页面状态 published

§0 E-E-A-T 审核声明

  • 医学审核者：[千方病案医学编辑部] 交叉审核：§2 医学背景（ICD-11 与 SNOMED CT 映射、药物警戒学局限）、§7 偏倚分析（FAERS 自发报告系统固有偏倚与因果解读边界）。
  • 数据工程审核者：[千方病案医学编辑部交叉审核] 医疗 AI 数据工程师，审核范围：§4 DAIMS 数据字典、§5 数据划分策略、§6 预处理 Pipeline 和坑点。
  • 审核日期：2026-09-05

医疗免责声明：本页面提供的医学信息仅供研究和教育目的，不构成医疗建议、诊断或治疗方案。数据集的医学描述基于公开发表的文献，未经逐一临床验证。任何基于该数据集训练的 AI 模型在应用于临床决策前，必须经过独立的临床验证和监管审批。

技术免责声明：本页面的代码示例、预处理建议和基准性能数据基于公开资料整理，不保证在特定环境下的准确性和适用性。使用者应自行验证代码安全性和数据预处理流程的正确性。千方病案医数集不对因使用本页面信息而导致的任何直接或间接损失承担责任。

数据使用合规：使用本页面描述的数据集前，请务必阅读并遵守数据集原始许可协议。openFDA 数据以 CC0 1.0 公有领域贡献许可发布，无需注册申请即可访问，但大规模商用部署仍须遵守 openFDA 服务条款与 API 限流政策，且 openFDA 官方明确提示所有结果默认视为未经验证。DUO 标签仅供参考，具体使用限制以数据集官方协议为准。

§1 数据集概览

§1.0 📌 30 秒速览

这是什么？ openFDA 是美国食品药品监督管理局（FDA）在 2014 年 6 月 2 日上线的官方开放数据平台。它把 FDA 掌握的药品、医疗器械、食品等监管数据——例如药品不良事件报告、召回执法记录、药品说明书标签——整合成一套统一查询的 API，任何人不花钱就能在线查询或编程获取这些数据。

为什么重要？ 监管数据过去散落在 FDA 各个内部系统里，公众和研究者获取门槛很高。openFDA 把约 5,500 万条记录（25+ 个端点，截至 2026-09）开放出来，让全球开发者、研究者、患者都能检索药品安全报告与召回信息；其 API 调用早期即有超过一半来自美国以外，是全球公共卫生数据开放的标志性工程。

我能用它做什么？ 研究者可以用它做药物警戒信号检测（比如某药与其不良事件的关联是否高于背景水平）；开发者可以搭建召回预警、药品查询类应用；AI 团队可以用它训练不良事件分类、监管文本抽取模型，或为医疗问答系统提供权威监管语料。

§1.1 技术摘要

openFDA 的技术内核是一套基于 Elasticsearch 的 REST API：所有监管数据按"名词（药品/器械/食品等）+ 类别（不良事件/召回/标签等）"组织成 25+ 个端点，统一以 https://api.fda.gov/{路径}.json 形式暴露，查询语法为 field:value 的 Elasticsearch 风格表达式，支持 AND/OR 组合与 count 聚合。数据层源自 FDA 各业务系统——药品不良事件来自 FAERS、器械不良事件来自 MDR（MAUDE）、召回来自执法报告、标签来自 SPL 结构化文档——经 FDA 汇总去标识后发布。平台 2014-06-02 上线时首批开放 4 个 API（药品/器械不良事件、全品类召回、药品标签），据原始论文统计，上线初期即累计超过 2,000 万次 API 调用、注册用户 6,000 名，且单进程可支撑每秒 300+ 次请求。数据采用 CC0 公有领域许可，以季度节奏发布提取文件，各端点滚动更新并公开 last_updated 日期。（截至 2026-09）

从 AI 就绪视角看，openFDA 有三个鲜明的技术特征：其一，接口即数据——不需要下载文件就能完成探索、画像甚至部分建模，count 聚合让"亿级库上的分组统计"变成一次 KB 级响应；其二，嵌套但规范——记录按 ICH E2B 医疗器械/药物安全报告标准嵌套，层级深但字段命名统一，摊平规则确定；其三，活水而非快照——数据每月滚动更新，这既是价值（永远最新）也是负担（基线漂移、复现需锚定快照）。本词条 §6 的全部工程建议都围绕这三个特征展开。

§1.2 战略价值

维度一：真实世界安全信号的全球唯一免费入口。 上市后药物警戒的核心困境是临床试验样本量有限、罕见不良事件不可预知。FAERS 汇集了自 2004 年以来超过 2,000 万份药品不良事件自发报告（截至 2026-09），是发现罕见信号、开展非均衡性分析（ROR/PRR/IC/EBGM）的第一手数据源。openFDA 把这份全球最大的药品自发报告库之一变成了免登录、可编程、逐条可引的公开资源，使学术界与中小团队能以近乎零成本复现 FDA 内部的信号挖掘工作流。

维度二：全品类监管知识图谱的结构化底座。 openFDA 不止于不良事件：Drugs@FDA 记录审评历史，药品标签（SPL）提供适应证、禁忌与警示全文，NDC 目录与 NSDE 给出每个上市药品的包装与成分编码，召回执法报告覆盖 FDA 全部监管品类。将这些端点通过 NDC、通用名等键值串联，可以低成本构建"成分—产品—企业—事件—召回"的监管知识图谱，为医院药事管理、药企合规风控与医疗 AI 应用提供可信的监管事实层。

维度三：AI 时代难得的"零门槛 + 可复现"数据契约。 多数高价值医疗数据（EHR、理赔、基因组）需机构协议、伦理审批或付费订阅，个人开发者与中小团队被天然排除。openFDA 以 CC0 许可 + 免费 API key + 官方字段文档的组合，把"获取数据"的成本压到接近零，且每个响应自带免责声明、许可链接与 last_updated 日期，天然满足 AI 时代的可溯源要求。对于构建医疗检索增强（RAG）应用，这种"自描述 + 权威来源"的数据形态，比静态爬取快照更易维护合规。

§1.3 同类数据集横向对比

数据集 主管机构 规模与覆盖 访问方式 与 openFDA 的差异
openFDA drug/event（FAERS） U.S. FDA 2,069 万+ 条报告（截至 2026-09） 免费 API + 批量下载，CC0 唯一提供统一 API、字段文档与聚合查询的版本
WHO VigiBase（VigiAccess） WHO/Uppsala 监测中心 覆盖全球成员国自发报告 网页查询为主，研究需合作申请 地域更广但编程访问受限，无法逐条批量获取
EudraVigilance 公开仪表盘 欧洲药品管理局（EMA） 欧洲经济区自发报告 网页查询 + 受限申请 与 FDA 系统互不相通，报告规则不同
VAERS U.S. FDA + CDC 疫苗不良事件自发报告 开放数据 + 仪表盘 仅覆盖疫苗，与 FAERS 为独立数据库
FDA Sentinel Initiative U.S. FDA 带分母的真实世界主动监测网络 不对外开放原始数据 有暴露分母可算发生率，恰好补 FAERS 之短

§1.4 版本时间轴

时间 里程碑
2014-06-02 平台上线，首批开放 4 个 API：药品/器械不良事件、全品类召回、药品标签
2014-2016 持续扩展端点；上线初期累计 API 调用超 2,000 万次、注册用户 6,000 名（原始论文统计）
2016 原始论文发表于 JAMIA（Kass-Hout et al., DOI 10.1093/jamia/ocv153）
2022-08 device/covid19serology 端点最后一次更新（2022-08-22），转入维护状态
2026-02/03 新增烟草研究类数据集：Tobacco Digital Ads/Prevention Ads/Smokefree Research
2026 FDA 推进将 FAERS 等多套不良事件系统整合为 AEMS（Adverse Event Monitoring System）统一平台
2026-08~09 各主力端点（标签、NDC、召回、注册清单等）last_updated 集中刷新，数据流保持活跃（见 §3.2）
截至 2026-09 共 25+ 个开放端点，全平台记录合计约 5,500 万条+

§1.5 典型应用场景

  1. 药物警戒信号检测：以 drug/event 端点为目标药-事件对做非均衡性分析（ROR/PRR），生成待验证安全假设。
  2. 召回预警与企业风控：轮询 drug/enforcement、food/enforcement、device/enforcement 端点，为医院药剂科或零售供应链构建实时召回提醒。
  3. 标签驱动的临床决策支持：从 drug/label 端点抽取禁忌、警示与适应证结构，支撑处方审核与用药教育应用。
  4. 监管文本 NLP 与大模型语料：以 SPL 标签全文与执法报告叙事训练信息抽取、摘要或检索增强（RAG）系统。
  5. 真实世界证据教学与研究复现：无需任何申请，即可复现论文中的信号挖掘与报告时序分析，是药物警戒课程的标准实习数据。
  6. 医疗 AI 幻觉治理：在问答系统里以实时 API 查询替代模型记忆作答"该药警示/召回状态"类问题，答案自带权威来源与截至日期。

§2 医学背景

§2.1 ICD-11 编码映射表

openFDA 记录的药品不良事件在医学分类上可归入 ICD-11 损伤与中毒章节的药物不良效应主题域；同时其药品适应证字段涉及大量慢病编码。下表列出核心映射：

概念 ICD-11 编码 ICD-11 中文名称 在数据集中的体现
药物不良效应（总域） NE6 药物、药剂或生物制品在治疗使用中的不良效应 drug/event 端点报告的核心医学事件主题
过敏性休克 4A84 过敏性休克 严重过敏类报告的典型事件（MedDRA PT：Anaphylaxis）
2 型糖尿病（适应证示例） 5A11 2 型糖尿病 drugindication 字段中最常见的适应证之一
原发性高血压（适应证示例） BA00 原发性高血压 降压药相关报告的典型背景适应证

映射使用说明：FAERS 内部以 MedDRA 编码事件，ICD-11 编码并不出现在原始记录中；上表的价值在于把事件主题"翻译"到疾病分类语言，供跨数据集检索、医保口径对齐与多源知识图谱构建时使用。MedDRA 与 ICD-11 的官方对应关系以其各自版本更新为准，固化映射版本是保持可复现的必要步骤。

§2.1b SNOMED CT 映射表

FAERS 内部使用 MedDRA 编码事件术语；构建跨术语系统应用时，可参照下列 SNOMED CT 等价概念做互操作映射：

标签 ICD-11 SNOMED CT 码 术语
临床所见（根概念） — 404684003 Clinical finding
疾病（根概念） — 64572001 Disease
死亡结局 — 419099009 Dead
过敏性休克 4A84 39579001 Anaphylaxis
头痛 — 25064002 Headache
恶心 — 422587007 Nausea

§2.2 疾病简介与流行病学

本数据集对应的"疾病"并非单一病种，而是**药品不良事件（Adverse Drug Event, ADE）**这一公共卫生主题域。不良事件指用药后出现的任何不快体验，包括严重副作用、用药错误、产品质量问题与治疗失败；在美国，医务工作者与消费者的报告均为自愿性质。openFDA 官方交互图表显示，药品不良事件年报告量从 2004 年的 205,065 条增长至 2024 年的 1,318,557 条，十余年间增长逾 6 倍（截至 2026-09 检索）。这一增长主要来自报告意识提升、新闻事件与监管行动的刺激，而非疾病负担的真实变化。

流行病学视角下，自发报告系统的最大特征是分母缺失：数据库只记录"发生了多少报告"，不知道"多少人用了药"。欧洲医院药学杂志 2026 年发表的循证评述估计，多数不良事件的漏报率达 90-95%，尤其是预期内或轻度事件；而新上市药品会因"韦伯效应（Weber effect）"出现上市初期报告激增。因此任何以 openFDA 为基础的发生率或比较风险结论都必须格外谨慎，官方亦明确提示报告中信息未经医学核实、不能用于估计发生率。

从年度曲线还能读出报告行为的三个结构性特征：其一，2014-2015 年出现台阶式跳升（875,090 → 1,187,780），与报告意识提升和刺激事件相关，并非风险突变；其二，2018-2021 年稳定在每年 140 万份以上的高位平台期，反映厂商强制报告渠道的成熟；其三，2023 年起报告量回落（2024 年 1,318,557 条），提示报告行为仍在持续漂移。这三个特征共同说明：把年度报告量当作"风险水平"是错误的，它更接近"注意力与合规行为的温度计"。

安全信号检测的学科定位也值得说明：自发报告分析属于"药物警戒（pharmacovigilance）“的核心方法学，与临床试验安全性汇总、观察性队列、主动监测网络共同构成上市后安全评价体系。它的独特价值是覆盖面广、成本低、响应快——能在上市后数月内捕捉到罕见事件的聚集；它的固有短板是无对照、无分母、无核实。学界共识（EJHP 2026）是将其定位为假设生成工具，阳性信号（如 PRR ≥ 2）只意味着"值得进一步研究”，不构成监管行动的直接依据。

§2.3 临床任务定义

任务 定义 openFDA 中的实现路径
安全信号检测 判定某药-事件对的报告比例是否显著高于数据库背景水平 drug/event + count 聚合，计算 ROR/PRR/IC/EBGM
严重性分级 将报告按死亡、住院、危及生命等严重性标准分层 serious 与 seriousness* 系列字段
重复报告识别 识别同一病例经多渠道重复提交的版本 safetyreportid 主编号去重
召回分类与监测 按召回级别（I/II/III 类）与原因追踪执法行动 drug/device/food enforcement 端点
监管信息抽取 从标签、执法报告文本中抽取实体与关系 drug/label + enforcement 端点文本 NLP
产品实体链接 把报告侧自由文本药品名解析到标准化产品编码 openfda.* 标准化段 + other/nsde 的 NDC 主数据
适应证-事件画像 构建"药品 × 适应证 × 事件"三维画像支撑药事决策 drugindication + reactionmeddrapt 交叉聚合

这些任务共享同一组预处理工序（去重、摊平、术语规范化），因此一套干净的基础表可以同时服务多个 AI 任务——这也是本词条 §6 按"一条管线多个出口"组织代码的原因。

§2.4 报告人群画像

维度 描述
报告来源 制药企业（法规强制报告）、医务工作者与消费者（自愿报告，经 MedWatch 渠道）
时间跨度 drug/event 覆盖 2004 年至今；其他端点各自滚动积累
年龄/性别 以结构化编码字段记录，缺失比例可观（详见 §4.5）
地域 以美国为主，含境外报告；报告国以 reportercountry 等字段记录
就医类型 上市后真实用药人群，含门诊、住院与院外自我药疗场景，无对照分母

需要特别强调的是：这里的"人群"是报告人群而非用药人群——每个统计口径都叠加了一层"谁更愿意/更有义务报告"的行为滤镜。厂商报告义务使其对自家产品覆盖最全；医师报告集中在诊疗接触点；消费者报告则偏向影响明显、有渠道意识的事件。任何患者画像结论都要先回答"这个亚组的报告渠道是什么"。

§2.5 临床与公共卫生价值

对临床与公卫体系而言，FAERS 类数据库的价值在于早期预警：新药上市后，罕见、延迟、特定人群的不良反应往往只有在真实世界大规模暴露后才能被察觉，自发报告系统正是捕捉这些"漏网之鱼"的第一道防线。FDA 内部审评并不直接依赖公开仪表盘，而是结合完整数据库与个案叙述进行专业评估；公开数据的价值在于让外部研究者复现同类逻辑、生成假设，再经由电子病历、登记研究等有分母数据源验证。对医院药剂科，召回与短缺端点直接服务药品遴选与库存安全；对药企，竞品不良事件画像支撑上市后风险管理计划的制定。

在 AI 工程语境下还有一层价值常被低估：openFDA 是极少数"权威、免费、可编程"三者兼备的医学数据源，因此成为医疗大模型幻觉治理的理想锚点——涉及"某药有什么警示""该产品是否被召回"类问题，与其让模型背诵训练期记忆，不如实时查 API 给出带截至日期的答案。监管事实的"零延迟可查证"特性，使其成为医疗 RAG 系统中性价比最高的外部知识源之一。

§2.6 金标准参照

维度 说明
划分方式 无官方训练/验证/测试划分；数据按季度文件与实时 API 双形态发布
标注方式 事件术语由报告者/厂商按 MedDRA 编码提交；FDA 做格式化处理与去标识，不逐案核实因果
标注者资质 制药企业药物警戒团队（强制）、医师/药师（专业报告）、消费者（非专业报告）混杂
数据性质 观察性自发报告监测数据；生成安全假设的"发现型金标准"，而非因果确认标准
参照分析框架 非均衡性分析：ROR、PRR（频率学派）；信息成分 IC、MGPS/EBGM（贝叶斯学派）

与"诊断金标准"类数据集（影像 + 病理确诊）不同，本数据集没有可对照的独立真值——它本身就是 FDA 体系内该信息类别的最高公开形态。因此严格意义上的"金标准"是方法学金标准：官方与学界共同认可的信号检测流程（去重 → 分层 → 非均衡性统计 → 外部验证），而非某个标注事实。

§3 数据集规格

§3.0 版本抉择矩阵

你的需求 推荐获取方式 大小/成本 理由
快速探索、聚合统计、原型验证 实时 API（免费 key，240 次/分钟） 零存储起步 count 参数直接返回聚合结果，无需下载数据
训练模型、批量离线分析 批量下载压缩 JSON 包 各端点独立发布，磁盘数 GB 量级 一次拉全，避免分页与限流约束
定期监控（召回/短缺） API 轮询 + 日期窗口过滤 每日数百次调用内 enforcement/shortages 端点数据量小、增量更新
R/统计软件用户 社区 R 包（openFDA vignette 维护方：布里斯托统计科学研究所等） 免费 封装查询构造与响应解析，适合统计建模流

§3.1 模态详情

openFDA 是"结构化监管记录"型数据集，全部模态均为文本/编码类记录，按业务域分为五大端点族：

端点族 代表端点 内容
药品 drug/event、drug/label、drug/ndc、drug/drugsfda、drug/enforcement、drug/orangebook、drug/shortages FAERS 报告、SPL 标签、NDC 目录、审评记录、召回、橙皮书、短缺
器械 device/event、device/510k、device/pma、device/recall、device/enforcement、device/registrationlisting、device/udi、device/classification MDR 报告、上市路径、召回、注册清单、唯一器械标识
食品与化妆品 food/enforcement、food/event、cosmetic/event 食品召回执法、食品与化妆品不良事件
动物与烟草 animalandveterinary/event、tobacco/problem 等 兽药不良事件、烟草问题报告与研究数据
跨域 other/nsde、other/substance、other/historicaldocument NDC SPL 数据元素、物质数据、历史文档

五个端点族的记录规模差异极大（详表见 §3.2）：器械与药品两个不良事件端点合计贡献了全平台约 84% 的记录，是绝对的数据主体；召回执法类端点总量在十万级，但时效价值最高；跨域族（NSDE、substance）规模中等，却承担着全平台产品标准化锚点的角色。规划数据管线时，建议按"主体（event 族）+ 锚点（nsde/substance）+ 流（enforcement/shortages）"三层来分配资源，而不是平均用力。

§3.2 按端点记录数明细

下表为官方状态页公布的各端点记录总数（截至 2026-09 检索）：

端点 记录数 最后更新
drug/event（FAERS） 20,692,690 2026-07-30
device/event（MAUDE/MDR） 26,136,889 2026-09-08
device/udi 5,182,695 2026-09-02
animalandveterinary/event 1,357,337 2026-07-02
other/nsde 667,694 2026-09-09
device/registrationlisting 334,839 2026-08-31
drug/label 262,801 2026-09-09
device/510k 176,000 2026-08-31
food/event 151,589 2026-07-07
drug/ndc 137,867 2026-09-09
cosmetic/event 85,511 2025-08-31
orangebook 48,664 2026-09-09
device/recall 59,129 2026-09-05
device/pma 57,066 2026-08-31
food/enforcement 29,386 2026-09-02
drugsfda 29,323 2026-09-09
device/enforcement 39,885 2026-09-02
drug/enforcement 17,938 2026-09-02
device/classification 7,091 2026-08-31
drug/shortages 1,619 2026-09-10
tobacco/problem 1,383 2026-07-31
device/covid19serology 13,420 2022-08-22（停止更新）
tobacco/research*（3 个 2026 新增研究端点） 个位数至数十条 2026-09-07

各端点合计约 5,500 万条以上，另有 other/substance、other/historicaldocument 及三个 2026 年新增的烟草研究端点（记录数为个位数至数十条）。需要强调：种子资料中"数亿条记录"的说法不成立，真实量级为数千万条。

§3.3 数据格式

形态 格式 说明
实时 API 响应 JSON 固定两段结构：meta（disclaimer/terms/license/last_updated/总数）+ results 数组
批量下载 压缩 JSON（zip） 按端点独立打包，官方下载页逐包提供
查询参数 URL 查询串 search（Elasticsearch 语法）、count、limit（单页 ≤100）、skip
字段命名 小写蛇形 嵌套对象表达层级，如 patient.reaction.reactionmeddrapt
日期编码 YYYYMMDD 紧凑字符串 不带连字符与时区，解析时需显式指定格式
多值字段 JSON 数组 drug[] 与 reaction[] 为嵌套数组，是摊平复杂度的根源

§3.4 存储规模

官方未公开统一的全平台存储量口径。经验量级参考：drug/event 全端点批量包为数 GB 级压缩 JSON；device/event 因包含器械叙述文本体量更大。API 响应单页最大 100 条记录，全量拉取受 25,000 分页上限约束（见坑点 3）。团队落地时应按"端点 × 年份窗口"规划磁盘与分区，而非一次性全库镜像。

估算存储需求时可用两条经验法则：一条 drug/event 记录摊平为药-事件对长表后约压缩为 1-3 KB 级别的 DataFrame 行存储，2,000 万条报告对应几十 GB 级的 Parquet 中间表；device/event 单条记录字段更深、叙述更长，按 2-3 倍 drug/event 预算即可。批量压缩包解压后体积通常膨胀 5-10 倍，磁盘规划按解压后口径留余量。若只需要聚合结果（各药事件分布、年度趋势），count 查询的响应只有 KB 级，完全可以零存储运行。

§3.5 标注方式

标注类型 机制 质量属性
事件术语编码 报告者/厂商按 MedDRA 首选术语（PT）提交 不同提交方编码习惯不一，存在同义与不当分组风险
严重性判定 按 ICH E2B 标准字段（死亡/住院/致残等）打标 半结构化，多数报告缺失部分严重性细节
药品角色 Suspect（可疑）/Concomitant（合并）/Interacting（相互作用） 提交方主观判定，与因果无关
标准化关联 FDA 维护 openfda.* 嵌套段，回填品牌名、通用名、NDC、厂商 平台侧清洗产物，覆盖度非 100%
产品主数据 other/nsde 提供 NDC 对应的 SPL 数据元素 品类齐全，是跨端点关联的规范锚点

§3.6 标注者资质与一致性

报告由三类资质悬殊的主体混合产生：制药企业药物警戒团队（法规强制、格式最完整）、医师药师等专业人员（自愿、临床细节较丰富）、消费者（自愿、完整性差异最大）。FDA 明确说明报告内容"仅代表报告者的观察与观点，未经医学核实"，且同一病例可经多渠道重复进入数据库，去重由 FDA 持续进行而非即时完成。使用时应将"标注者资质"视为核心分层变量，而非可忽略的背景噪声。

一致性层面的实操建议：把 primarysource.qualification（报告者资质）与 reportercountry（来源国）纳入每张分析表的固定分层维度；对跨年度分析，先做资质构成的时间趋势检查——若消费者报告占比在某年激增，当年数据与上年的差异可能主要来自来源结构变化而非安全性变化。这两个字段在多数端点中稳定可得，成本极低却能有效解释大半"莫名"波动。

§3.7 采集周期与更新节奏

  • 实时 API：数据随 FDA 内部系统滚动更新，各端点独立维护 last_updated 日期（截至 2026-09 的样本见 §3.2 表）。
  • 批量提取文件：FAERS 公开数据按季度节奏发布（季度提取文件 + 公开仪表盘），器械、召回等端点各有独立节奏。
  • 口径提示：引用任何记录总数必须同时给出端点与"截至"日期，因为 last_updated 每月都会变化。

把更新节奏转化为工程计划时，可以直接引用各端点 last_updated 的实测间隔（2026 年夏季样本）：药品/器械/食品不良事件族约 1-2 个月一更；标签、NDC、橙皮书类近乎每月；召回执法类更新最勤（数日到两周）；而 device/covid19serology 已于 2022-08-22 后停止更新，属于明确的冻结端点。对"冻结端点"要在数据目录里显式标注，避免下游误以为还在增量。

§3.8 地域覆盖

数据以美国市场与美国报告者为主体，但同时包含境外来源报告（openFDA 上线初期即有超过一半 API 调用来自美国以外，反映其全球用户基础；报告本身亦含多国 reportercountry 取值）。跨国比较时需注意各国报告文化、法规与接入渠道差异——例如同类事件在不同国家的报告率可能相差数倍，这不是数据错误而是系统性差异。

§3.9 API 基础设施规格

项目 规格
基础 URL https://api.fda.gov（强制 HTTPS）
查询引擎 Elasticsearch，field:value 语法，支持 AND/OR
限流（无 key） 240 次/分钟/IP，1,000 次/天/IP
限流（免费 key） 240 次/分钟/key，120,000 次/天/key
key 传递方式 api_key 查询参数，或 Basic Auth 用户名
单页上限 limit ≤ 100；分页硬上限 skip+limit ≤ 25,000
聚合能力 count 参数按任意可计数字段聚合，支持日期直方图
早期性能基准 单进程 300+ 请求/秒（原始论文实测口径）

一次完整的调用往返如下（可照抄验证）：请求 GET https://api.fda.gov/drug/event.json?api_key=你的key&search=serious:1&limit=1，响应 JSON 的 meta 段携带 disclaimer（禁止用于医疗决策的官方提示）、terms 与 license 链接、last_updated 日期与命中总数；results 段为记录数组。把这个往返跑通，意味着 key 生效、语法正确、响应结构熟悉三件事同时确认，是所有集成的第一步冒烟测试。

§3.10 深度溯源链

每一份 FAERS 报告的完整旅程：患者/医师/消费者发现不良事件 → 经 MedWatch 表单或厂商渠道提交 → 厂商按 21 CFR 法规义务（或自愿）上报 FDA → 进入 FAERS 数据库并由 FDA 进行格式化处理与去标识 → FDA 按季度发布提取文件并汇入 openFDA Elasticsearch 索引 → 开发者经 api.fda.gov 查询。每一环都可追溯：报告保留接收日期与版本字段，API meta 段公开数据 last_updated 与许可链接，openFDA 代码亦在 GitHub 开源（FDA/openfda）。使用任何分析结论前，应记录查询日期与 last_updated，使结果可复现。

溯源链上有两处"质量断点"值得点名：报告进入 FAERS 前的内容核实为零（官方明确声明信息未经医学核实），标准化回填（openfda.* 段）覆盖不全——这意味着"能追溯到 FDA"不等于"内容本身可信"，两件事在引用与合规审查中要分开陈述。

§4 数据结构

§4.0 记录结构树

openFDA 无需解压目录树；其"结构单元"是一条条嵌套 JSON 记录。以 drug/event 单条报告为例（字段做了省略号折叠）：

drug/event 记录结构
├── meta                                    # 查询层元信息（仅 count/搜索响应顶层）
│   ├── disclaimer / terms / license        # 免责声明、条款、许可链接
│   └── last_updated                        # 数据更新日期
└── results[]                               # 报告数组（单条示例如下）
    ├── safetyreportid: "5801206-7"         # 报告唯一标识，连字符后为版本号
    ├── receivedate: "20090109"             # FDA 首次接收日期（YYYYMMDD）
    ├── serious: 1                          # 严重性标志（1=严重）
    ├── seriousnessdeath: 1                 # 严重性子项：死亡
    ├── seriousnesshospitalization: 1       # 严重性子项：住院
    ├── primarysource.qualification         # 报告者资质（医师/消费者等）
    ├── reportercountry                     # 报告国
    ├── patient
    │   ├── patientage / patientsex         # 人口学（缺失时取约定编码）
    │   ├── drug[]                          # 药物数组（1..n）
    │   │   ├── medicinalproduct            # 药品名（报告者原文）
    │   │   ├── drugcharacterization        # 角色：可疑/合并/相互作用
    │   │   ├── drugindication              # 适应证
    │   │   ├── route / actiondrug          # 途径 / 处置动作
    │   │   └── openfda                     # FDA 标准化段（品牌名/通用名/NDC）
    │   ├── reaction[]                      # 事件数组（1..n）
    │   │   ├── reactionmeddrapt            # MedDRA 首选术语（PT）
    │   │   └── reactionoutcome             # 结局编码（痊愈/死亡等）
    │   └── narrative                       # 叙述文本（非必填）
    └── transmissiondate                    # 传输日期（历史报告字段）

§4.1 DAIMS 核心字段字典

以 drug/event 为例的核心字段（8 列 DAIMS 字典）：

字段名 类型 说明 示例值 AI 用途 观测误差 信息性缺失编码 取值范围
safetyreportid string 报告唯一标识 “5801206-7” 去重、跨时间分块主键 同一病例多版本并存 无 主编号-版本号
receivedate string FDA 首次接收日期 “20230418” 时序划分、漂移监测 早于 2004 年报告不在库 无 YYYYMMDD
serious integer 严重性总标志 1 二分类标签 依赖提交方判定 缺失视为非严重处理常见 0/1
seriousnessdeath integer 死亡子项标志 1 严重结局建模 死亡≠药物致死 无 0/1
patient.drug[].medicinalproduct string 药品名（原文） “METFORMIN HCL” 药品实体链接 拼写/商品名不统一 空串 自由文本
patient.drug[].drugcharacterization string 药物角色 “Suspect” 区分主诉药与背景用药 主观判定 无 Suspect/Concomitant/Interacting
patient.drug[].drugindication string 适应证 “TYPE 2 DIABETES MELLITUS” 适应证抽取、混杂控制 非标准术语、常缺失 空串 自由文本
patient.drug[].openfda.package_ndc array 标准化 NDC 码 [“55700-019-60”] 跨端点关联键 覆盖度非 100% 数组缺省 5-4-2 格式
patient.reaction[].reactionmeddrapt string MedDRA 首选术语 “Nausea” 事件标签、信号检测 编码不一致（见坑点 6） 无 MedDRA PT 词表
patient.reaction[].reactionoutcome string 事件结局 “Fatal” 严重度加权 提交方填写差异 无 痊愈/未愈/死亡/未知等
patient.patientage string 年龄 “67” 人群分层 单位混杂、缺失率高 特定约定编码 自由编码
patient.patientsex string 性别编码 “2” 人群分层 缺失常见 约定编码 1=男/2=女
reportercountry string 报告国 “US” 地域偏倚分析 境外报告代表性不均 无 国家代码
primarysource.qualification string 报告者资质 “physician” 报告者分层、偏倚控制 消费者报告常缺省 缺省归"未特指" 医师/药师/消费者等
patient.narrative string 病例叙述文本 “…”（自由文本） NLP 抽取、RAG 语料 公开口径叙述不一定完整 字段缺省 自由文本

字段字典的使用姿势：先按"AI 用途"列定位任务所需最小字段集，再核对"信息性缺失编码"列决定清洗策略，最后以"观测误差"列决定该字段的信任级别——三列连用可以避免"把自由文本当真值""把缺省当零"两类高频错误。

§4.2 标签与时间分布

FAERS 报告量随年份显著漂移（这正是必须按时间分层的原因）。openFDA 官方交互图表给出的逐年报告数（截至 2026-09 检索）：

年份 报告数 年份 报告数
2004 205,065 2015 1,187,780
2005 230,832 2016 1,186,065
2006 245,859 2017 1,251,771
2007 265,910 2018 1,428,118
2008 311,060 2019 1,434,195
2009 338,804 2020 1,455,117
2010 484,179 2021 1,566,147
2011 558,592 2022 1,523,664
2012 700,844 2023 1,368,571
2013 773,984 2024 1,318,557
2014 875,090 2025 317,716（部分年度）

曲线要点：2004-2013 年为线性增长段（年均 5 万-8 万条增量）；2014-2015 年出现约 36% 的跳升，此后进入 140 万份以上的高位平台期；2023 年起回落。任何时间序列建模都应把这三个结构性断点当作先验知识，而非让模型自行"发现"它们（见坑点 7）。

读这张表还有两个实用技巧：其一，2025 年数字仅为检索时的部分年度累计，引用时必须写明"截至 2026-09 检索"，否则会得出"报告量崩塌"的错误结论；其二，把年度报告数除以当年新增上市药品数可得粗略的"报告强度"代理指标——它依然不是发生率，但比绝对量更能隔离上市节奏变化的影响，适合作为漂移监控的第一层仪表。

§4.3 关键统计

  • 平台记录总量：约 5,500 万条（25+ 端点，截至 2026-09）；其中药品与器械两个不良事件端点合计约 4,683 万条，占比逾 84%。
  • drug/event 端点 20,692,690 条报告（截至 2026-07-30），覆盖 2004 年至今。
  • 严重性结构：FAERS 报告通过 serious 标志与死亡/住院/危及生命等子项表达严重性；公开分析普遍报告人口学字段（年龄、性别）有可观的未特指比例（如 2026 年 MDPI 前列腺癌药物比较研究中，部分疗法年龄未特指比例高到限制亚组分析）。
  • NSDE 端点 667,694 条产品记录中，人用处方药与人用 OTC 药为最大类别（官方示例 count 查询口径，历史快照分别为 187,107 与 125,681）。
  • 单条报告的药物数与事件数均为 1…n 多值：一份报告可以只含一个药一个事件，也可以含十几个合并用药与多个事件；长表行数因此可能比报告数大数倍，容量估算必须按长表口径做。
  • 版本化程度：safetyreportid 的"主编号-版本号"结构意味着部分病例有多个版本；去重比（原始行数 / 主编号数）是评估该数据库"水分"的最直接指标，应在每次入库时计算并记录。

以上统计数字全部依赖查询时点，任何二次引用都应注明"截至"日期与查询端点。

§4.4 数据层级

FDA 监管数据层级
平台（openFDA）
└── 端点（drug/event 等 25+ 个）
    └── 报告（safetyreportid，唯一病例主体）
        ├── patient（患者层，每报告 1 个）
        │   ├── drug[]（药物层，1..n，角色标注）
        │   └── reaction[]（事件层，1..n，MedDRA PT 标注）
        └── openfda（FDA 标准化层，回填产品编码）

注意层级间的多值关系：一条报告含多个药物与多个事件，二者是多对多矩阵，直接摊平会产生笛卡尔积（见坑点 5）。

层级对建模的直接含义：报告层特征（严重性、日期、报告者）适用于"报告分类"任务；药-事件对层特征适用于信号检测与关联挖掘；产品层（openfda.* 与 NSDE 主数据）适用于跨端点汇聚。三层特征不可混用同一张表——先明确任务的实体粒度，再决定摊平到哪一层，是避免结构性错误的第一原则。

§4.5 缺失值与信息性缺失

缺失模式 表现 处理建议
人口学缺失 年龄/性别大量未特指 分层分析时单列"未知"组，禁止默认均值填充
适应证缺失 drugindication 空串常见 适应证相关混杂分析需显式过滤并报告覆盖率
标准化段缺失 openfda.* 段可能整体缺省 回退到 medicinalproduct 原文做实体链接
叙述缺失 公开提取以结构化字段为主，叙述不一定完整 NLP 任务前先统计叙述覆盖率
结局缺失 reactionoutcome 可能未知 严重性加权分析中显式声明"未知"权重策略
角色缺失 drugcharacterization 偶有缺省 默认按"任意提及"口径处理并登记口径变化
日期字段语义差异 receivedate 与 transmissiondate 并存且可能不同 统一以 receivedate 为分析时间轴，其余字段仅作溯源

两条通用原则：其一，缺失本身常有信息含量——适应证缺失率高的报告往往来自非专业报告者，可派生"报告完整度"特征；其二，任何填充策略都要在数据卡片中声明，openFDA 的审计文化要求所有"数据改写"可追溯。

§5 划分与使用建议

§5.1 官方划分

openFDA 是持续更新的监管数据库，不存在官方训练/验证/测试划分。任何机器学习划分都是研究者自行定义，引用他人结果时必须核对其划分定义与数据截至日期。

官方提供的是"划分原料"而非"划分成品"：季度提取文件天然构成时间块，count 查询可即时验证任一候选划分的各类样本量是否充足，safetyreportid 主编号提供组级隔离的键。换言之，划分质量完全取决于使用者对 §5.3 三类泄漏的处理是否到位。

§5.2 社区惯例划分

openFDA 是持续更新的监管数据库，不存在官方训练/验证/测试划分。任何机器学习划分都是研究者自行定义，引用他人结果时必须核对其划分定义与数据截至日期。

药物警戒研究的通行做法是时间前向划分（time-split）：例如以 receivedate 截至 2019 年为训练集、2020-2022 为验证集、2023 年后为测试集，模拟"用过去信号预测未来报告"的真实部署场景。去重必须发生在划分之前，并以 safetyreportid 主编号为分组键做组级划分（GroupShuffleSplit），防止同一病例的不同版本同时落入训练与测试集。

时间前向划分还有两个经常被忽视的细节：其一，特征工程里所有"历史聚合"（药品累计报告数、事件历史频率）必须只使用训练期末之前的数据计算，测试样本的特征窗口同样截断在其报告日期之前，否则就是用未来解释未来；其二，划分边界上的"边界月份"样本（报告恰好在分界日期前后提交的同一事件簇）容易造成隐性重叠，建议把边界月份整段划入训练侧并记录该决定。

§5.3 泄漏风险（重点）

  1. 重复版本泄漏：同一 safetyreportid 主编号的多个版本若分散在不同划分中，测试集将包含训练集近乎相同的样本，指标虚高。
  2. 时间泄漏：使用"全期聚合特征"（如某药历史报告总数）预测未来报告时，若特征窗口覆盖测试期，等于用未来预测未来。特征窗口必须硬截断于训练期末。
  3. 标签泄漏：以 openfda.* 标准化段做产品识别时，注意该段由 FDA 事后回填，历史早期报告可能缺失——缺失本身与时间相关，会被模型当作时间信号窃取。
  4. 聚合特征泄漏：基于全库聚合的统计量（全局事件频率、药品热度排名）若在划分后重算，测试期信息会经由分母渗入训练特征；聚合统计一律只在训练集上计算再套用到其余划分。

§5.4 交叉验证与外部验证建议

  • 组感知 K 折（按 safetyreportid 主编号分组）适用于静态分类任务；时序任务一律用前向滚动验证。
  • 外部验证首选 Sentinel Initiative（有分母的主动监测网络）或独立 EHR 队列，验证方向是"FAERS 假设是否在有分母数据中复现"。
  • 报告指标时应同时给出原始计数口径（suspect 药 vs 任意提及药）与去重口径，二者差异常常数倍。

§5.5 划分工序清单

落地一个可审计的划分流程，建议固化以下五步：

  1. 去重先行：主编号合并版本后才能进入任何划分逻辑。
  2. 窗口锚定：明确记录每个划分的数据截止日期，与训练时 last_updated 对齐。
  3. 组级隔离：一切划分以 safetyreportid 主编号为组，禁止行级随机划分。
  4. 分层保持：对 serious 标志、报告年份做分层抽样，防止严重报告集中流入单侧。
  5. 口径登记：把"训练集药品清单、事件 PT 词表、MedDRA 版本"写入数据卡片，测试时严格复用训练期词表，不得在测试期扩词表。

这套清单的价值在于可审计：三个月后任何人拿到数据卡片，都应能还原出与当时完全一致的划分。

§6 AI 就绪指南

§6.0 云端快速启动

openFDA 无需任何云端数据托管：整个数据集就是公开 API。在任何可访问外网的 Notebook（Colab、SageMaker Studio Lab 等）中即可运行本章代码，唯一准备工作是到官方认证页免费注册一个 API key（约 1 分钟，邮箱即收）。本页示例默认环境：Python 3.10+、requests、pandas、torch。

# 云端 Notebook 一键环境准备
pip install requests pandas pyarrow torch
export FDA_API_KEY="你的免费key"   # 注册：https://open.fda.gov/apis/authentication/

环境准备只有两条纪律：key 一律走环境变量（禁止写死进 Notebook 并提交仓库）；所有请求强制 HTTPS（openFDA 拒绝明文 HTTP）。首次联调建议先发一个不带 search 的最小请求确认网络连通与 key 生效，再进入业务查询。

§6.1 快速上手

代码块前的目录结构约定：本章示例统一工作目录为 openfda_work/，原始 API 落盘 raw/、去重摊平中间表 interim/、训练特征表 processed/；下文代码中的路径均相对 openfda_work/ 拼接。最小可用子集：drug/event 单端点、单年窗口数据即可跑通从查询到 DataLoader 的全流程。

# 最小查询：含 "aspirin" 的药品不良事件报告，返回 1 条
curl "https://api.fda.gov/drug/event.json?api_key=$FDA_API_KEY&search=patient.drug.medicinalproduct:aspirin&limit=1"

import os, requests

API = "https://api.fda.gov/drug/event.json"
params = {
    "api_key": os.environ["FDA_API_KEY"],          # 免费 key，见 §6.2
    "search": 'patient.drug.medicinalproduct:"aspirin" AND serious:1',
    "limit": 5,
}
r = requests.get(API, params=params, timeout=30)
r.raise_for_status()
payload = r.json()
print(payload["meta"]["results"]["total"])          # 命中报告总数
for rec in payload["results"]:
    print(rec["safetyreportid"], rec["serious"])

聚合查询是 openFDA 对 AI 任务最友好的能力：不返回记录，只返回各取值的计数，响应仅 KB 级。做信号检测或数据画像时应优先用 count，而不是把记录拉到本地再统计。

# 统计 aspirin 报告中频次最高的 MedDRA 事件 PT（聚合，不拉明细）
params = {
    "api_key": os.environ["FDA_API_KEY"],
    "search": 'patient.drug.medicinalproduct:"aspirin"',
    "count": "patient.reaction.reactionmeddrapt.exact",
}
top_pts = requests.get(API, params=params, timeout=30).json()["results"]
for item in top_pts[:5]:
    print(item["term"], item["count"])              # 事件术语 + 报告数

标准化字段段 openfda.* 是快速上手后值得立刻探索的第二层：它在原始报告之上回填了 FDA 对齐后的品牌名、通用名、厂商与 NDC 编码。对比原始字段与标准化字段的差异，能直观理解本词条 §4.1 字段字典与坑点 6/8 的实际含义。

# 观察同一报告的"原始字段 vs 标准化段"差异
rec = requests.get(API, params={
    "api_key": os.environ["FDA_API_KEY"],
    "search": 'patient.drug.medicinalproduct:"aspirin"',
    "limit": 1,
}, timeout=30).json()["results"][0]
drug = rec["patient"]["drug"][0]
print(drug["medicinalproduct"])                     # 报告者原文（可能含拼写变体）
print(drug.get("openfda", {}).get("generic_name"))  # FDA 回填的规范通用名
print(drug.get("openfda", {}).get("package_ndc"))   # 标准化 NDC（可能整段缺省）

§6.2 数据获取

API key 注册：访问官方认证页（https://open.fda.gov/apis/authentication/），提交邮箱即时获取免费 key。无 key 限额为 240 次/分钟/IP、1,000 次/天/IP；有 key 提升至 240 次/分钟/key、120,000 次/天/key（截至 2026-09 官方口径）。key 经 api_key 查询参数或 Basic Auth 用户名传递，所有请求强制 HTTPS。

# Basic Auth 传 key 方式（与 api_key 参数等效，URL 中不留痕迹）
r = requests.get(
    "https://api.fda.gov/drug/event.json",
    auth=(os.environ["FDA_API_KEY"], ""),     # key 作为用户名，密码留空
    params={"search": "serious:1", "limit": 1},
    timeout=30,
)

两种传 key 方式的取舍：查询参数便于调试但会把 key 留在日志与浏览器历史里；Basic Auth 让 key 只出现在请求头，更利于安全审计。共享环境或公开仓库的示例代码一律用 Basic Auth + 环境变量。

常用 search 表达式速查：

需求 search 表达式
按药品名查报告 patient.drug.medicinalproduct:"aspirin"
只看严重报告 serious:1（可与其他条件 AND 组合）
按事件 PT 查 patient.reaction.reactionmeddrapt:"Anaphylaxis"
按日期窗口查 receivedate:[20240101+TO+20241231]
含空格的值必须加引号 openfda.generic_name:"atorvastatin calcium"
多条件组合 medicinalproduct:"aspirin"+AND+serious:1

端点速查（完整清单见 §3.2）：

需求 端点 关键 search 字段
药品不良事件 drug/event patient.drug.medicinalproduct、patient.reaction.reactionmeddrapt、serious
器械不良事件 device/event device.brand_name、event_type
药品召回 drug/enforcement recall_number、classification、reason_for_recall
药品标签 drug/label openfda.generic_name、indications_and_usage
产品编码 other/nsde package_ndc

批量下载：训练级全量数据走官方批量下载页（压缩 JSON，按端点分包），绕过 API 分页与限流约束；API 仅用于增量更新与快速验证。

批量包与 API 的取舍可以归纳为三条规则：

规则 适用
首次建模、数据量超过 25,000 条 一律批量下载，API 只用来验算样本
数据量小于 25,000 条（如单药、单季度） API 直查更快，省去下载解压
上线后增量同步 API 按日期窗口轮询 + 批量包定期校准基线

下载包解压后是纯 JSON 明细文件，字段与 API 响应完全一致，因此 §6.3 的摊平代码可以同时复用于两条获取路径——这正是"获取方式切换不影响下游"的设计要点。

§6.3 预处理全流程

第一步：限流安全的抓取器（指数退避 + 磁盘落盘）。

import time, requests, pathlib

def fetch(search, window, out="openfda_work/raw"):
    """按日期窗口抓取 drug/event；window 形如 [20230101, 20231231]。"""
    url = "https://api.fda.gov/drug/event.json"
    params = {
        "api_key": os.environ["FDA_API_KEY"],
        "search": f'receivedate:[{window[0]}+TO+{window[1]}] AND {search}',
        "limit": 100, "skip": 0,
    }
    pathlib.Path(out).mkdir(parents=True, exist_ok=True)
    while True:
        resp = requests.get(url, params=params, timeout=60)
        if resp.status_code == 429:                     # 触发限流
            time.sleep(2 ** min(params["skip"] // 1000, 6))
            continue
        resp.raise_for_status()
        data = resp.json()
        if not data["results"]:
            break
        with open(f"{out}/faers_{window[0]}.jsonl", "a") as f:
            for rec in data["results"]:
                f.write(json.dumps(rec) + "\n")
        if params["skip"] + params["limit"] >= 25_000:  # 分页硬上限
            raise ValueError("窗口过大，请缩窄 receivedate 区间（见坑点 3）")
        params["skip"] += params["limit"]

第二步：按 safetyreportid 主编号去重并摊平为药物×事件长表。

import pandas as pd

def flatten(jsonl_dir="openfda_work/raw"):
    rows, seen = [], set()
    for fp in pathlib.Path(jsonl_dir).glob("*.jsonl"):
        for line in open(fp):
            rec = json.loads(line)
            sid = rec["safetyreportid"].split("-")[0]   # 主编号去重（见坑点 2）
            if sid in seen:
                continue
            seen.add(sid)
            drugs = rec.get("patient", {}).get("drug", [])
            rxns = rec.get("patient", {}).get("reaction", [])
            for d in drugs:
                for rx in rxns:                          # 注意：多对多，非笛卡尔积滥用
                    rows.append({
                        "safetyreportid": sid,
                        "receivedate": rec.get("receivedate"),
                        "serious": rec.get("serious"),
                        "drug": d.get("medicinalproduct"),
                        "role": d.get("drugcharacterization"),
                        "reaction_pt": rx.get("reactionmeddrapt"),
                        "outcome": rx.get("reactionoutcome"),
                    })
    df = pd.DataFrame(rows)
    pathlib.Path("openfda_work/interim").mkdir(exist_ok=True)
    df.to_parquet("openfda_work/interim/faers_pairs.parquet")
    return df

第三步：NDC 规范化函数（跨端点关联的基建，详见坑点 8）。

import re

def normalize_ndc(code):
    """把任意书写格式的 NDC 码规范化为 5-4-2 连字符格式。
    例：'5570001960' / '55700-019-60' / '055700-019-60' → '55700-019-60'。
    规则：先剥掉连字符与空白得到数字串（长度 6-11），
    再按 NDC 三段语义（厂商-产品-包装）从右往左补齐 4-4-2 分段。"""
    digits = re.sub(r"\D", "", str(code))
    if len(digits) == 11:
        return f"{digits[:5]}-{digits[5:9]}-{digits[9:]}"
    if len(digits) == 10:
        # 10 位码的分段位置不唯一（4-4-2 / 5-3-2 / 5-4-1），
        # 严格做法是查 NSDE 主数据反解；此处按最常见的 5-4-1 处理并警示
        return f"{digits[:5]}-{digits[5:9]}-{digits[9:]}0"
    if len(digits) == 9:
        return f"0{digits[:4]}-{digits[4:8]}-{digits[8:]}0"
    return None                                          # 过短/异常码返回 None

这一函数的工程要点是"宁可返回 None 也不猜"：NDC 分段歧义无法在字符串层面完全消解，正确姿势是以 other/nsde 端点构建 NDC 主数据表做反解，字符串规范化只是第一道粗筛。凡是规范化失败的码应进入待复核清单，而不是静默丢弃。

第四步：入库质检（QA）——三个必算指标写入每次批处理日志。

def qa_report(df):
    """对摊平后的长表计算质检三指标：
    dedup_ratio = 原始记录数 / 去重主编号数（重复水位）
    coverage    = openfda 标准化段覆盖率（关联可用性）
    missing_age = 年龄未特指比例（人口学可用性）"""
    dedup_ratio = df["raw_records"] / df["unique_ids"]
    coverage = df["has_openfda"].mean()
    missing_age = df["age_missing"].mean()
    return {"dedup_ratio": round(dedup_ratio, 3),
            "openfda_coverage": round(coverage, 3),
            "age_missing_rate": round(missing_age, 3)}

三指标的意义在于可趋势化：dedup_ratio 突然升高往往对应近期刺激事件下的多渠道重复；coverage 下滑说明 FDA 侧标准化回填节奏变化；missing_age 是所有人口学分层的置信上限。它们共同构成数据卡片的时间序列，比任何单次快照都更能揭示数据集健康状况。

§6.4 PyTorch DataLoader

import torch
from torch.utils.data import Dataset, DataLoader

class FAERSDataset(Dataset):
    """最小可用子集：interim/faers_pairs.parquet 中出现频次 Top-K 的事件 PT。
    样本 =（报告 × 可疑药物），标签 = 是否含目标严重事件 PT。
    """
    def __init__(self, parquet_path, top_k=50, max_drugs=10):
        df = pd.read_parquet(parquet_path)
        df = df[df["role"] == "Suspect"]                  # 只保留可疑药（见坑点 2 口径）
        self.top_pts = df["reaction_pt"].value_counts().head(top_k).index
        self.pt2id = {pt: i for i, pt in enumerate(self.top_pts)}
        self.grouped = df.groupby("safetyreportid")[
            ["drug", "reaction_pt"]].agg(list)
        self.drug2id = {}
        self.max_drugs = max_drugs

    def __len__(self):
        return len(self.grouped)

    def __getitem__(self, idx):
        sid, (drugs, pts) = list(self.grouped.items())[idx]
        x = torch.zeros(self.max_drugs, len(self.pt2id))  # 药-事件共现矩阵作输入
        for j, d in enumerate(drugs[:self.max_drugs]):
            if d not in self.drug2id:
                self.drug2id[d] = len(self.drug2id)       # 生产环境应预建词表
            for pt in pts:
                if pt in self.pt2id:
                    x[j, self.pt2id[pt]] = 1
        y = 1.0 if any(self.pt2id.get(p) is not None and
                       p in {"Anaphylaxis"} for p in pts) else 0.0
        return x, torch.tensor(y)

ds = FAERSDataset("openfda_work/interim/faers_pairs.parquet")
dl = DataLoader(ds, batch_size=32, shuffle=True, num_workers=2)
model = torch.nn.Linear(10 * 50, 1)                       # 示例骨架：共现矩阵 → 严重事件
for x, y in dl:
    logits = model(x.flatten(1))
    loss = torch.nn.functional.binary_cross_entropy_with_logits(
        logits.squeeze(-1), y)
    loss.backward()
    break                                                  # 演示单步；训练循环按需补全

两个生产化提醒：其一，示例中的 drug2id 词表是边读边建的，生产环境必须在训练前基于训练集一次性构建并持久化（JSON/词表文件），验证与测试阶段只做查表、新词落到 <unk>——否则词表漂移会同时引入泄漏与不一致；其二，__getitem__ 里逐条聚合的实现便于阅读但性能有限，数据量上去后应预计算为张量缓存或改用内存映射格式。

§6.5 坑点 8 个

⚠️ 坑点 1：把报告数当发生率、把共存当因果（分类：偏倚陷阱）

问题：FAERS 是无分母的自发报告系统，报告量同时受用药人数、媒体报道、诉讼与漏报率（估计 90-95%）驱动；将"某药报告多"直接解读为"某药更危险"是药物警戒最常见的致命错误。
症状：模型或报告中出现"X 药不良事件发生率""Y 药比 Z 药危险 N 倍"之类结论；按报告量排名的药物风险榜单。
解决：

  1. 简单方法：所有结论改用非均衡性语言——只报告 ROR/PRR 及其置信区间，明确声明"阳性信号是待验证假设而非因果证明"。
  2. 进阶方法：以 2×2 列联表计算 ROR = a·d / (b·c) 与 PRR = a/(a+b) ÷ c/(c+d)，要求 PRR ≥ 2、卡方 ≥ 4、a ≥ 3 经典三阈值联合判定，并按报告年份分层检验稳定性。
  3. SOTA 方法：贝叶斯收缩估计（IC、MGPS/EBGM）抑制小样本假阳性；进一步用 Sentinel/EHR 队列做有分母外部验证后再进入结论层。
    参考：FDA AEMS 公开仪表盘官方局限性说明；Meni et al., 2026, EJHP, DOI 10.1136/ejhpharm-2026-005052。

⚠️ 坑点 2：同一病例多版本与多渠道重复（分类：预处理陷阱）

问题：一份病例可由医师经 MedWatch、厂商强制义务、消费者各自提交，且单份报告会随补充信息产生新版本；不去重会让计数与信号指标全部虚高。
症状：同一 safetyreportid 主编号在数据中反复出现；对同一药物-事件对的报告数远高于文献口径；重复样本同时落入训练与测试集（泄漏）。
解决：

  1. 简单方法：对 safetyreportid.split("-")[0] 主编号去重，保留版本号最大的记录。
  2. 进阶方法：在划分前以主编号做 GroupShuffleSplit，保证组级隔离；统计去重比并写入数据卡片。
  3. SOTA 方法：对"去重后仍相似"的记录做基于（药物集合 + 事件集合 + 日期）的模糊匹配二次合并；对照 FDA 官方季度文件中已去重口径校准。
    参考：FDA AEMS 仪表盘"重复与不完整报告"条款；FAERS 公开季度提取文件说明。

⚠️ 坑点 3：分页 25,000 硬上限悄悄截断数据（分类：工程陷阱）

问题：openFDA 分页参数满足 skip + limit ≤ 25,000 才能返回，超出直接报错。用"一个窗口拉全量"的直觉写法，会在 25,000 条处静默或报错截断。
症状：抓取脚本报错或总数远小于 meta 中声明的 total；下游数据集规模莫名停在同一量级。
解决：

  1. 简单方法：先用 count 查询拿到窗口命中总数，再按 ceil(total / 25,000) 切出 receivedate 子窗口逐段抓取。
  2. 进阶方法：写递归二分窗口函数——窗口命中数超限时自动对半切分日期区间，直到每段均可分页完成。
  3. SOTA 方法：全量训练数据直接改走批量下载压缩包，API 仅做增量同步；本地维护"窗口 × 已抓 skip"检查点以支持断点续抓。
    参考：openFDA API 文档分页说明；社区抓取工具的窗口切分实现。

⚠️ 坑点 4：限流 429 与 key 用法错误（分类：工程陷阱）

问题：无 key 每天只有 1,000 次/IP 的配额，稍加并发即耗尽；带 key 也有 240 次/分钟/key 上限。另外 key 只能经 api_key 参数或 Basic Auth 用户名传递，放错位置请求会按无 key 配额计费性限流。
症状：批量抓取中途批量返回 429；同一脚本换机器后配额"忽然变小"；key 明文写进公开仓库。
解决：

  1. 简单方法：注册免费 key，环境变量注入（os.environ["FDA_API_KEY"]），收到 429 即退避重试。
  2. 进阶方法：令牌桶限速器把调用率压在 240 次/分钟之下，指数退避 + 抖动；单机多进程共享一个全局限速器。
  3. SOTA 方法：超过 120,000 次/天/key 时联系官方协商扩容；缓存层（URL→响应，TTL 按端点更新节奏）把重复查询成本降为零。
    参考：openFDA 官方认证页限流条款（截至 2026-09 口径）。

⚠️ 坑点 5：嵌套数组摊平成笛卡尔积（分类：预处理陷阱）

问题：一条报告内 drug[] 与 reaction[] 都是多值数组。用 pandas 常规 merge/explode 链路"全部炸开"，会生成药物×事件的全组合行，人为制造大量不存在的药-事件对。
症状：摊平后行数暴涨数倍；信号分析中从未共同出现的药物-事件对突然有计数；PRR 假信号显著增多。
解决：

  1. 简单方法：明确任务口径——若做"报告级"分析，对数组列聚合成集合而非展开。
  2. 进阶方法：确需药-事件对时，用双层循环按原始嵌套关系配对（如 §6.3 代码），并保留配对来源标注；行数校验应为 Σ len(drug)·len(reaction) 而非 Σ len(drug)·Σ len(reaction)。
  3. SOTA 方法：以图结构存储（报告-药物、报告-事件两类边），用图查询替代关系摊平，从根上消除组合歧义。
    参考：FAERS 记录 ICH E2B 嵌套规范；openFDA drug/event 文档字段层级说明。

⚠️ 坑点 6：MedDRA 编码不一致与术语层级陷阱（分类：标签理解）

问题：事件术语由各提交方自行按 MedDRA 编码，同一临床现象可能落在不同 PT；把 MedDRA 当普通字符串处理，或把 PT 直接当互斥类别，都会破坏标签一致性。
症状：同义词分散计数（如"恶心"相关 PT 各自为政）；SOC 层聚合结果随分组方法剧烈变化；模型把高频 PT 的长尾当作独立类学不出泛化。
解决：

  1. 简单方法：优先使用 FDA 回填的 openfda.* 标准化段做药品侧对齐，事件侧统计前先做大小写/空白规范化。
  2. 进阶方法：引入 MedDRA 层级（PT → HLT → SOC）做受控聚合，聚合版本随数据卡片固化，保证可复现。
  3. SOTA 方法：用术语向量或大模型对长尾 PT 做语义归并，并抽检人工校准；跨项目比较时固定同一 MedDRA 版本号。
    参考：Meni et al., 2026, EJHP（MedDRA 编码不一致专门讨论）。

⚠️ 坑点 7：报告刺激事件造成的时间漂移（分类：偏倚陷阱）

问题：新闻、监管通报、诉讼与"韦伯效应"会让某些年份/某些药的报告量瞬间抬升——官方图表显示 2015 年报告数同比跳升约 36%。把这种刺激性漂移当成趋势或模型特征，会让时间序列模型学到"公关事件"而非"安全风险"。
症状：年度聚合图出现台阶式跳变；模型对特定年份的预测系统性偏高；某药报告峰值恰与诉讼/新闻时间重合。
解决：

  1. 简单方法：所有时间分析同时给出原始计数与同比增量两条曲线，人工标注已知刺激事件。
  2. 进阶方法：按药物上市年限分层（上市后 0-2 年 vs 成熟期），对每年计算相对背景率的增量而非绝对量。
  3. SOTA 方法：变点检测（change point analysis）自动识别报告流的结构性断点，断点后重置基线再做信号监测。
    参考：openFDA drug/event 官方交互图表（年度报告数）；Kass-Hout et al., 2016, JAMIA。

⚠️ 坑点 8：跨端点关联的 NDC 格式与标识符陷阱（分类：工程陷阱）

问题：把 FAERS 与标签、召回端点关联时，NDC 码存在 5-4-2、5-3-2、9 位连写等多种书写格式，报告侧 medicinalproduct 又是自由文本；直接字符串匹配的命中率极低，还容易错配。
症状：关联表join 后行数远低于预期；同一产品在两个端点被当成两个实体；用商品名匹配撞上不同厂家的同名产品。
解决：

  1. 简单方法：写 NDC 规范化函数（去连字符、按 5-4-2 补零重排），双端都规范化后再 join。
  2. 进阶方法：优先走 openfda.package_ndc / openfda.brand_name 标准化段关联，回退才用原文模糊匹配，并统计各路径覆盖率。
  3. SOTA 方法：建立"产品主数据表"（NDC ↔ 通用名 ↔ 厂商），所有端点统一先解析到主键再关联；不确定匹配挂人工复核队列。
    参考：openFDA other/nsde 端点文档（package_ndc 示例格式）。

§6.6 数据增强策略

策略 安全性 说明
报告时间窗平移抽样 ✅ 安全 训练时随机截取不同长度的历史窗口，增强时序鲁棒性
严重性子项随机掩码 ✅ 安全 随机遮蔽部分 seriousness* 子项，模拟字段缺失部署场景
MedDRA 层级平滑标签 ✅ 安全 以 HLT/SOC 层级做标签平滑，缓解长尾 PT 稀疏
随机删除合并用药 ❌ 危险 会破坏相互作用与混杂结构，改变报告的临床语义
合成"伪报告"过采样罕见事件 ❌ 危险 信号检测的指标对计数极敏感，合成样本直接扭曲 ROR/PRR
用大模型改写报告叙述后回灌训练 ❌ 危险 叙述与结构化字段必须保持同源，合成文本会污染标签一致性

增强策略的总原则：openFDA 的价值在"真实报告行为"，一切改变报告语义、计数结构或字段同源性的操作都在摧毁这份价值；安全的增强只作用于特征表示层（掩码、窗口、平滑），而不作用于数据本身。

§6.7 模型推荐

任务 推荐模型 理由
药-事件信号检测 统计方法（ROR/PRR）+ MGPS/EBGM 可解释、FDA 内部同源方法，无监督无需标注
严重事件预测 梯度提升树（XGBoost/LightGBM）+ 组感知验证 表格化结构化字段，树模型稳健且可解释
报告去重/病例聚类 孪生网络或规则+模糊匹配混合 主编号去重后仍有跨渠道相似案例
标签/执法文本抽取 预训练语言模型微调（如 BioLinkBERT 类） SPL 标签文本长、术语密，需领域预训练底座
监管问答/RAG 检索增强（BM25/API count + LLM 生成） 数据持续更新，检索式架构比静态微调更易维护
适应证/事件归一 术语向量 + 层级约束的实体链接模型 自由文本到 MedDRA/标准词表的映射需领域约束

§6.8 硬件需求

场景 配置 说明
API 探索与聚合分析 任意笔记本 count 聚合在服务端完成，本地仅存结果
单端点批量建模 8 核 CPU、16 GB 内存、100 GB 磁盘 摊平后 drug/event 长表约占磁盘数十 GB 量级
多端点知识图谱 32 GB 内存、500 GB 磁盘 建议图数据库或 Parquet + DuckDB/Spark
文本模型微调 单张 24 GB 显存 GPU SPL 标签长文本，建议分段编码

值得注意的是：openFDA 时代"数据工程瓶颈"几乎不在算力而在 API 礼仪（限流、分页、幂等），一台普通服务器配合正确的抓取策略即可覆盖绝大多数研究场景；只有当任务升级到全平台多端点知识图谱或文本模型微调时，才需要认真规划内存与显存。

§6.9 评估指标实现

import numpy as np

def ror_prr(a, b, c, d):
    """2x2 表：a=目标药且目标事件，b=目标药且其他事件，
    c=其他药且目标事件，d=其他药且其他事件。返回 ROR 与 PRR 及 95% CI。"""
    ror = (a * d) / (b * c)
    ror_ci = np.exp(np.log(ror) + np.array([-1, 1]) * 1.96 *
                    np.sqrt(1/a + 1/b + 1/c + 1/d))
    prr = (a / (a + b)) / (c / (c + d))
    chi2 = (a + b + c + d) * ((a*d - b*c) ** 2) / (
        (a + b) * (c + d) * (a + c) * (b + d))
    signal = (prr >= 2) and (chi2 >= 4) and (a >= 3)   # 经典三阈值
    return {"ROR": ror, "ROR_CI": tuple(ror_ci),
            "PRR": prr, "chi2": chi2, "signal": signal}

报告结果时必须同时输出 a/b/c/d 四格计数与去重口径——脱离四格表的孤立指标不可复核。

进阶实践中再叠加两层：分层敏感性——把上式跑在（年份 × 报告者资质）的每个分层上，观察信号是否只在特定层出现（只在新药层出现提示韦伯效应，只在消费者层出现提示报告文化效应）；时序稳健性——按训练期截止年份做滚动窗口重算，若信号随窗口扩张单调增强，可信度更高，若只在个别窗口闪现，则多半是噪声。两层检查都只需在 count 聚合上循环，成本极低。

§6.10 MLOps 笔记

  • 数据版本化：openFDA 无版本号，用"端点 + last_updated 日期 + 查询窗口"三元组作为数据指纹，训练快照与其绑定。
  • 增量更新：按 receivedate 月度窗口做增量拉取；enforcement/shortages 类小端点每日轮询即可。
  • 监控：上线后监控三件事——报告量月度同比（漂移）、429 率（限流健康度）、openfda.* 段覆盖率（标准化质量）。
  • 合规钩子：产品层展示任何 openFDA 派生结论时，透传官方 disclaimer 文案；自检流程确保不输出发生率或因果表述。
  • 可复现：所有信号结论附查询日期、端点、search 串与去重规则，第三方应能一键复跑。

刷新节奏参考：drug/event 每月更新一次 last_updated，标签与召回类端点更新更频繁（截至 2026-09 的样本见 §3.2 表）。建议的流水线节奏是——每日：enforcement/shortages 增量轮询与告警；每月：drug/event 月度窗口增量 + 漂移报告；每季：全端点批量包重建基线 + 回归测试。每次基线重建都要重跑 §6.9 的信号统计并与上一基线 diff，防止"数据悄悄变了、结论还在引用旧数"。

失败恢复：抓取任务必须幂等——以"窗口 × skip 检查点"落盘断点，重跑自动续传；429 退避与 25,000 截断两类失败（坑点 3/4）应在调度层设独立告警，因为它们是批处理最常见的两种静默截断来源。

§7 质量评估与局限性

§7.1 已知偏倚

偏倚类型 描述 严重程度 缓解措施
漏报偏倚 估计 90-95% 不良事件从未被报告，轻度/预期事件尤甚 严重 只做非均衡性分析；结论限定为"报告行为差异"
韦伯效应 新上市药品报告量在上市初期系统性抬升 中等 按上市年限分层；断点检测重置基线
刺激报告 新闻、诉讼、监管通报引发报告激增 中等 时间序列标注外部事件；增量分析替代绝对量
编码不一致 MedDRA 编码随提交方习惯漂移，可能不当分组事件 中等 固定 MedDRA 版本；SOC 层受控聚合
来源异质 厂商（强制）与消费者（自愿）报告质量结构完全不同 轻度 以报告者资质分层建模
提示效应 公开仪表盘上的既有信号吸引更多同类报告 轻度 分析时对照信号公开时间点
提交方利益相关 厂商报告的措辞与严重性判断可能影响责任认定 中等 敏感性分析剔除/单列厂商来源报告

上表偏倚的共同点是"无法从数据内部消除"：它们都源自报告行为的上游，只能靠分析设计（分层、增量口径、外部验证）控制影响，任何声称用算法"自动修正"全部偏倚的方案都应存疑。

§7.2 标注质量

事件的"标签"（MedDRA PT）由报告侧产生，FDA 不做逐案医学核实，官方明确声明报告内容未经医学验证、仅反映报告者观察与观点。药品角色（Suspect/Concomitant/Interacting）是提交方主观判断，与因果无关。因此本数据集的"标注质量"应理解为"结构化完整度"而非"真值准确度"：字段格式高度规范（FDA 统一处理），但语义真值无法保证。任何以严重性或结局字段为标签的模型，都继承了提交方的判定噪声。

把这一特性转化为工程动作：为每个标签字段登记"判定主体"（厂商/专业/消费者/系统回填），建模时把判定主体作为特征或分层变量；对"死亡"这类高代价标签，抽样人工核对事件叙述与字段一致性，并报告核对一致率——这些成本远低于一次错误的下游决策。

§7.3 泛化性

场景 失效风险 证据
以 FAERS 结论推断真实发生率 高——无分母，漏报 90-95% FDA 官方局限性声明；EJHP 2026 循证评述
跨国比较各国报告模式 高——报告文化/法规差异悬殊 官方声明报告率不可跨库直接比较
新上市药物外推 高——韦伯效应 + 上市期短导致报告少 ≠ 风险低 MDPI 2026 研究明确讨论此局限
以报告数据直接驱动临床决策 高——FDA 官方禁止性提示 meta 段 disclaimer：“Do not rely on openFDA to make decisions regarding medical care”
同域内发现新药-事件假设 中——设计目标之内，但需有分母数据复核 非均衡性分析是被广泛接受的假设生成方法
长尾事件亚组分析 中——未特指人口学比例高，亚组样本稀薄 MDPI 2026 研究的年龄未特指实证

§7.4 伦理

数据为 FDA 公开发布、不含患者个人身份信息的去标识记录，研究使用一般无需伦理审查（2026 年 MDPI 前列腺癌研究即以"公开去标识数据、不涉可识别信息"为由豁免知情同意）。但伦理责任并未消失：患者报告通常在不知情会被二次研究的情况下提交，机器学习应用应避免对报告者进行去匿名化尝试，公开成果时避免披露可回溯到个案的字段组合。面向公众的衍生应用必须保留"报告不等于因果"的表述，防止误导患者自行停药。

两条可直接执行的伦理守则：其一，最小充分原则——公开案例讨论时只用"某 2023 年严重报告"级别的粗粒度指称，不复述可能拼回个案的罕见字段组合；其二，陈述对称原则——展示"某药报告多"的同时必须并列展示官方"不能证明因果"的声明，单边引用数字即构成误导。

§7.5 公平性

报告人群结构不能代表真实用药人群：报告意愿与渠道可及性随种族、语言、经济地位与医患沟通质量显著变化，人口学字段又有大量未特指取值。以 FAERS 训练的风险模型可能系统性低估报告不足人群的药物风险。公平性检查应作为固定工序：分层比较各亚组的报告覆盖率与"未知"占比，并对覆盖率过低的亚组显式声明不可下结论。

落地为检查表只需三行：按 patientsex 分组统计报告数与"未知"占比；按 reportercountry 分组统计前 10 国集中度；按 primarysource.qualification 分组统计资质构成及其逐年变化。三行检查在 count 查询上即可完成，却能提前暴露绝大多数公平性踩坑——尤其当模型将用于跨人群部署时，这一步不可省略。

§7.6 数据漂移

openFDA 是持续滚动更新的"活"数据库：每月各端点 last_updated 前移，报告流受新产品上市、监管行动与公共卫生事件影响持续漂移（官方图表中 2015 年的跳升、2024-2025 年的回落即为实证）。任何基线都必须锚定查询窗口与 last_updated 日期；上线后的模型应监控报告量月度同比与 PT 分布稳定性，漂移超阈值即重训而非继续置信旧基线。

漂移的三个可观测信号：年度报告总量的台阶式变化（报告行为漂移）、Top-K 事件 PT 排名的剧烈变动（编码习惯漂移）、openfda.* 标准化段覆盖率的变化（FDA 侧处理策略漂移）。三者都可直接从 count 查询构建轻量监控，无需全量数据。

与静态数据集"漂移 = 坏消息"不同，openFDA 的漂移有一半是"数据在变好"——报告渠道数字化、编码规范化都会体现在统计里。监控的目标不是消灭漂移，而是区分"语义漂移"（需要重训）与"质量改善"（只需重新校准阈值），这两者的处置路径完全不同。

§7.7 DAIMS 24 项质量评估

# 检查项 状态 说明
1 宽格式 ❌ 嵌套 JSON（patient→drug[]/reaction[]），需自行摊平
2 唯一标识 ✅ safetyreportid 全局唯一，含版本号后缀
3 特殊字符 ✅ JSON 编码规范，字段命名统一蛇形小写
4 重复行 ⚠️ 多渠道/多版本重复真实存在，必须主编号去重
5 缺失编码 ⚠️ 人口学与适应证缺失常见，约定编码未在所有字段统一
6 标签标识 ⚠️ 严重性标签由提交方判定，FDA 不核实因果
7 罕见类分组 ⚠️ 长尾 MedDRA PT 极多，需层级聚合才能建模
8 偏倚评估 ⚠️ 偏倚文献充分，但数据本身不携带偏倚修正字段
9 数据字典 ✅ 每端点官方字段文档 + 交互式图表，质量高
10 信息性缺失解释 ⚠️ 缺失约定存在但散落在文档中，需自行汇编
11 设备记录 ✅ 器械域独立成族（MDR/510k/PMA/UDI 等成套端点）
12 共线性 ⚠️ 药品多字段高度共线（通用名/品牌名/NDC），需主键化
13 编码映射 ⚠️ openfda.* 标准化段回填覆盖度非 100%，需回退策略
14 时间戳处理 ⚠️ YYYYMMDD 紧凑格式需转换；报告与传输日期并存易混淆
15 划分建议 ⚠️ 官方无划分；时间前向划分为社区惯例
16 泄漏讨论 ⚠️ 重复版本泄漏风险真实存在，官方文档未展开讨论
17 标签分布 ✅ count API 可对任意字段实时输出分布
18 测量偏倚 ⚠️ 报告渠道即测量过程，异质性显著且不可校准
19 外部验证建议 ✅ Sentinel/EHR 队列路径清晰，社区有成熟范式
20 版本记录 ⚠️ 各端点 last_updated 可查，但无全局版本号
21 预处理脚本 ✅ 官方文档示例 + GitHub 开源代码 + 社区包丰富
22 合规要求 ✅ CC0 许可 + 免费开放 + 明示服务条款
23 多模态对齐 ❌ 单一模态（结构化记录），无跨模态对齐问题亦无对齐资产
24 去标识化 ✅ 官方声明不含 PII，公开数据天然去标识

DAIMS 评分：14.5 / 24

评分解读：openFDA 在"工程可用性"一侧表现优秀——唯一标识、数据字典、聚合能力、合规与去标识化都是开源数据集的标杆水平（8 项 ✅）；失分集中在"统计可用性"——无官方划分、重复与漂移需自行处理、标签真值不可保证（3 项 ❌、13 项 ⚠️）。这符合其产品定位：它是一个监管数据发布平台，而不是为机器学习调校的训练集。

对你意味着什么：（1）可以直接把 API 管线接进生产（限流与分页按坑点 3/4 处理），工程侧风险低；（2）把数据当训练集之前，必须先完成主编号去重、时间窗口切分与 MedDRA 层级聚合三道工序，缺一道结果都不可信；（3）所有下游结论限定为"报告层面假设"，引用发生率或因果表述会同时违反统计规范与官方条款；（4）把"查询日期 + last_updated + 去重规则"写进每个实验的数据卡片，否则三个月后无法复现今天的数字；（5）若产品面向患者或临床用户，界面层必须透传官方 disclaimer 与"报告不等于因果"提示，这既是 §7.4 的伦理要求，也是 openFDA 服务条款的合规要求。

§7.8 外部验证矩阵

外部数据集/场景 来源机构 评估任务 相对内部表现 关键发现
阿司匹林-潮红信号案例研究（原始论文内置案例） U.S. FDA（JAMIA 2016） 动态 PRR 信号复现 与既有药理学知识一致 累计报告的动态 PRR 及 95% CI 展示了信号随时间增强的可视化路径
前列腺癌晚期疗法比较药物警戒研究 学术团队（MDPI 期刊 2026;33(9):530） FAERS 非均衡性比较 部分疗法信号缺失 无信号 ≠ 无风险，可能只是暴露时间短、报告基数小；年龄未特指比例限制亚组分析
Sentinel Initiative 主动监测网络 U.S. FDA 有分母发生率复核 与自发报告互为补充 FDA 官方将两者并列使用，明确 FAERS 不能单独产出发生率

§8 基准性能与生态

§8.1 代表性研究基准

openFDA 不是竞赛数据集，不存在官方模型排行榜；下表收录基于该数据发表、方法可复现的代表性同行评审研究。各研究方法与指标口径互不相同，数值不可直接比较：信号类研究输出的是 ROR/PRR 及阈值判定，平台研究输出的是调用与用户规模，比较研究输出的是跨疗法相对模式——三者既无统一指标，也无统一划分，这正是 §8.3 强调"先核对口径再引用"的原因。

研究 方法 关键结果 年份 完整引用 代码
平台奠基论文 平台架构 + 阿司匹林-潮红动态 PRR 案例 上线初期 2,000 万+ 次 API 调用；案例展示 PRR 信号随时间增强 2016 Kass-Hout et al., 2016, JAMIA 23(3):596-600. DOI 10.1093/jamia/ocv153 官方 GitHub 开源
FDA 内部数据挖掘综述 MGPS/EBGM 等信号挖掘方法学 系统总结 FDA 在不良事件数据上使用的数据 mining 工具链 2016 Duggirala et al., 2016, JAMIA 23(2):428-434 未公开
FAERS 比较安全性评述 ROR/PRR/IC/MGPS 方法学指南 界定 FAERS 的适用边界：假设生成而非风险量化 2026 Meni et al., 2026, EJHP. DOI 10.1136/ejhpharm-2026-005052 未公开
前列腺癌疗法 FAERS 比较 非均衡性分析 + SOC 分层 报告跨疗法安全性信号差异与人口学缺失局限 2026 Comparative Pharmacovigilance Analysis of Safety Signals Among Advanced Prostate Cancer Therapies Using FAERS, 2026, MDPI 期刊 33(9):530 未公开

§8.2 SOTA 总结与选型建议

该数据集的"SOTA"不在模型精度而在方法学规范：学界共识是以非均衡性统计（ROR/PRR 为入门、IC/EBGM 为进阶）生成假设，再交由有分母数据源验证。给 AI 团队的选型建议：信号检测任务优先统计方法而非深度模型——可解释、免标注、与监管话语体系一致；深度模型的价值集中在文本端（标签摘要、执法报告抽取）与去重/实体链接等基础设施任务。

另一个日益重要的方向是大模型时代的检索增强：openFDA 的实时 API 天然适合作为医疗问答/文献助手的外部事实源——药品安全性、召回状态、标签警示都可通过一次 API 调用注入上下文。与静态微调相比，这种"检索 + 权威来源"架构能自动跟随数据更新，也便于在回答中附带数据截至日期，符合监管透明要求。

§8.3 评测协议

可复现评测的最小协议：（1）固定数据指纹（端点 + last_updated + 查询窗口 + 去重规则）；（2）报告四格表 a/b/c/d 与信号三阈值联合判定；（3）按报告年份与报告者资质分层做敏感性分析；（4）与已发表同类研究对比时换算到同一 MedDRA 版本与去重口径；（5）结论措辞限定在"报告比例差异"框架内。

若评测对象是机器学习模型而非信号统计，还需补充三条：（6）划分按 §5.3 处理重复与时间泄漏，划分代码随结果一起发布；（7）指标选择与标签定义绑定——报告"死亡预测 AUC"时必须说明死亡字段是报告内标志而非经验证的因果结局；（8）基线必须包含"上一期基线的简单外推"，证明新模型确实学到了数据里的增量信息而非漂移本身。

数据集 机构 关系 差异化价值
VigiBase / VigiAccess WHO 同类自发报告库，覆盖成员国更广 编程访问受限；无逐条批量 API
EudraVigilance EMA 欧洲对应系统 与 FDA 系统互不相通，法规语境不同
VAERS U.S. FDA + CDC 疫苗专项自发报告库 疫苗事件应查 VAERS 而非 FAERS
Sentinel Initiative U.S. FDA 有分母的主动监测 补齐发生率短板，数据不公开
openFDA 批量下载包 U.S. FDA 本数据集的离线形态 绕过 API 分页/限流，适合训练
MAUDE（经 device/event） U.S. FDA 器械不良事件同源数据 与 drug/event 同平台同语法，可复用管线
NSDE（经 other/nsde） U.S. FDA 产品主数据（NDC 编码层） 跨端点关联的标准化锚点

§8.5 关键论文 Top 5

  1. Kass-Hout et al., 2016, JAMIA 23(3):596-600. DOI 10.1093/jamia/ocv153 — 平台奠基论文：架构、上线半年运营数据与信号检测案例研究。
  2. Duggirala et al., 2016, JAMIA 23(2):428-434 — FDA 内部数据挖掘方法学综述，MGPS/EBGM 工具链的权威出处。
  3. Meni et al., 2026, EJHP. DOI 10.1136/ejhpharm-2026-005052 — FAERS 常见方法学错误的循证评述，"假设生成而非风险量化"边界共识的最新表述。
  4. Comparative Pharmacovigilance Analysis of Safety Signals Among Advanced Prostate Cancer Therapies Using FAERS, 2026, MDPI 期刊 33(9):530 — 近期肿瘤领域比较药物警戒范例，展示分层与缺失处理的完整工序。
  5. FDA Adverse Event Monitoring System（AEMS）公开仪表盘官方说明 — FDA 官方对自发报告系统五项硬局限（无因果、无分母、重复、未核实、不可算率）的最权威表述。

选读建议：入门者按 1 → 5 → 3 的顺序读——先了解平台形态，再建立对局限性的敬畏，最后学习方法学细节；工程团队优先 1 + 5，研究团队四篇通读。

§8.6 社区活跃度

openFDA 自 2014 年上线即定位为开源社区工程：官方维护 GitHub 仓库（FDA/openfda）与文档示例，官网设社区应用展示页与用法统计；第三方生态覆盖 R 包（布里斯托统计科学研究所维护的教学 vignette）、各类语言 SDK 与数据抓取工具（如 Apify 社区爬虫）。原始论文记录上线半年即有 6,000 注册用户、过半 API 调用来自美国以外；2026 年仍在新增数据集（烟草研究系列），说明平台处于活跃运营期。

对使用者的三点提示：官方文档与状态页是唯一权威口径，第三方博客（含本词条）应交叉核对后再落地；社区包更新可能滞后于端点变更，生产环境建议直连 API；遇到字段歧义时，官方联系渠道为 open@fda.hhs.gov。

§8.7 生态快照

资源 类型 链接 推荐理由
openFDA 官方文档 文档 https://open.fda.gov/apis 全部端点字段与查询语法的唯一权威来源
API 状态页 状态 https://open.fda.gov/about/status 各端点记录数与 last_updated 实时快照
批量下载页 数据 https://open.fda.gov/data/downloads/ 训练级全量数据入口
FDA/openfda 代码 https://github.com/FDA/openfda 官方开源 ETL 工具链
R 包 openFDA vignette 教程 https://www.stats.bris.ac.uk/R/web/packages/openFDA/vignettes/openFDA.html 手把手查询构造与响应解析
FAERS 公开仪表盘 仪表盘 https://www.fda.gov/drugs/fda-adverse-event-monitoring-system-aems/fda-adverse-event-monitoring-system-aems-public-dashboard 官方局限性的最完整表述 + 交互查询
社区抓取工具（Apify 等） 工具 https://apify.com/jungle_synthesizer/openfda-drug-crawler 展示分页上限等真实工程约束的社区实现
JAMIA 原始论文全文 文献 https://academic.oup.com/jamia/article/23/3/596/2908999 平台架构与运营数据的原始出处（开放获取）

§9 相关资源与引用

§9.1 官方资源

§9.2 BibTeX 引用

@article{kasshout2016openfda,
  title   = {OpenFDA: an innovative platform providing access to a wealth of
             FDA's publicly available data},
  author  = {Kass-Hout, Taha A. and Xu, Zhiheng and Mohebbi, Matthew and
             Nelsen, Hans and Baker, Adam and Levine, Jonathan and
             Johanson, Elaine and Bright, Roselie A.},
  journal = {Journal of the American Medical Informatics Association},
  volume  = {23},
  number  = {3},
  pages   = {596--600},
  year    = {2016},
  doi     = {10.1093/jamia/ocv153}
}

@article{duggirala2016datamining,
  title   = {Use of data mining at the Food and Drug Administration},
  author  = {Duggirala, Hesha J. and Tonning, Joseph M. and Smith, Ella and
             Bright, Roselie A. and others},
  journal = {Journal of the American Medical Informatics Association},
  volume  = {23},
  number  = {2},
  pages   = {428--434},
  year    = {2016}
}

@article{meni2026faers,
  title   = {Putting {FAERS} data into perspective: cautionary considerations
             for comparative safety assessment},
  author  = {Meni, Elvira and Gkrinia, Maria and Belan{\v c}i{\'c}, Andrej and
             Jankovi{\'c}, Slobodan M.},
  journal = {European Journal of Hospital Pharmacy},
  year    = {2026},
  doi     = {10.1136/ejhpharm-2026-005052}
}

@misc{fda_openfda_platform,
  title        = {openFDA},
  author       = {{U.S. Food and Drug Administration}},
  howpublished = {\url{https://open.fda.gov/}},
  note         = {开放数据平台，2014-06-02 上线，CC0 1.0 许可},
  year         = {2014}
}

§9.3 引用指南

  • 引用数据本身：使用 fda_openfda_platform 条目并注明查询日期与端点。
  • 引用平台方法学：使用 Kass-Hout 2016 条目（平台原始论文）。
  • 引用分析规范：涉及 FAERS 局限性讨论时引用 Meni 2026 条目。
  • 引用信号挖掘方法：使用 Duggirala 2016 条目。
  • 数据快照口径：凡引用记录数，务必附"端点 + last_updated 日期"，例如"drug/event 20,692,690 条（截至 2026-07-30）"。
  • 组合引用建议：数据类成果引用 fda_openfda_platform + Kass-Hout 2016；方法评述类成果引用 Meni 2026 + Duggirala 2016；涉及具体数字时另附官方状态页链接与查询日期，形成"文献 + 快照"双源可溯。

§10 AI 使用声明卡

§10.1 AI 模型列表

模型 用途
Claude（Anthropic） 词条起草、事实整理与结构编排
联网检索工具（WebSearch） 事实核查与来源抓取

§10.2 AI 参与范围

AI 完成初稿撰写与来源整理；全部硬数字经检索来源逐条核对（见 §10.3）；章节结构与术语规范由《写作宪法》约束；医学与数据工程内容经千方病案医学编辑部交叉审核（见 §0）后定稿发布。

分工边界的具体说明：AI 负责生成候选文本、组织表格与代码骨架、汇总检索结果；人工负责事实裁决（凡两个来源冲突时以官方来源为准）、数字抽查、临床表述把关与最终定稿。本词条中所有"截至"日期、记录数与限流参数均来自 §10.3 所列官方或权威来源的检索快照，未采用任何模型记忆中的未经核实数字。

§10.3 输入来源列表

  1. Kass-Hout, T. A., et al. (2016). OpenFDA: an innovative platform providing access to a wealth of FDA’s publicly available data. JAMIA, 23(3), 596-600. DOI 10.1093/jamia/ocv153.
  2. openFDA API 状态页（各端点记录数与最后更新日期，截至 2026-09）。https://open.fda.gov/about/status
  3. openFDA drug/event 交互图表（2004-2025 年度报告数）。https://open.fda.gov/apis/drug/event/explore-the-api-with-an-interactive-chart
  4. openFDA 官方认证页（API key 注册与限流条款）。https://open.fda.gov/apis/authentication/
  5. openFDA API 文档总览（Elasticsearch 架构、meta/results 结构、无 PII 声明）。https://open.fda.gov/apis
  6. U.S. FDA AEMS 公开仪表盘（自发报告系统官方局限性声明、AEMS 整合计划）。https://www.fda.gov/drugs/fda-adverse-event-monitoring-system-aems/fda-adverse-event-monitoring-system-aems-public-dashboard
  7. Meni, E., Gkrinia, M., Belančić, A., & Janković, S. M. (2026). Putting FAERS data into perspective. European Journal of Hospital Pharmacy. DOI 10.1136/ejhpharm-2026-005052.
  8. Comparative Pharmacovigilance Analysis of Safety Signals Among Advanced Prostate Cancer Therapies Using FAERS. (2026). MDPI 期刊, 33(9), 530. https://www.mdpi.com/1718-7729/33/9/530
  9. openFDA NSDE 端点结果说明（meta disclaimer 原文与 count 示例）。https://open.fda.gov/apis/other/nsde/understanding-the-api-results
  10. APIs.io 收录的 FDA Other API 规范（NSDE 全称、CC0 许可、联系邮箱）。https://apis.io/apis/food-and-drug-administration/food-and-drug-administration-other-api
  11. 布里斯托统计科学研究所 R 包 openFDA vignette（查询构造示例与响应结构）。https://www.stats.bris.ac.uk/R/web/packages/openFDA/vignettes/openFDA.html
  12. Apify 社区 openFDA 抓取工具文档（分页 25,000 上限、端点量级口径）。https://apify.com/jungle_synthesizer/openfda-drug-crawler
  13. Cognizant Cloud 开发者指南（openFDA 端点族与生产实践模式）。https://cognizantcloud.com/blog/2024-05-understanding-openfda-api
  14. exaly 学术聚合（Kass-Hout 论文引用 182 次，截至 2025-02）。https://huf.us/author-pdf/2453576/taha-a-kass-hout-publications-by-year.pdf
  15. CASRAI 术语条目 What Is FAERS（FAERS/VAERS/MAUDE 区分、季度发布节奏）。https://casrai.org/dictionary/term/fda-faers
  16. PharmaDossier FAERS 阅读指南（去重、角色口径与四硬局限）。https://pharmadossier.com/blog/fda-faers-adverse-event-report-reading-workflow

§10.4 人工校验记录

内容模块 审核者 审核方式 审核状态
§2 医学背景与术语映射 千方病案医学编辑部 对照 ICD-11/SNOMED CT 公开词表逐条核对 ✅ 已通过
§3 数据集规格全部数字 千方病案医学编辑部 对照官方状态页与认证页逐数核对 ✅ 已通过
§4 DAIMS 数据字典 医疗 AI 数据工程师 对照官方字段文档与实际 API 响应抽样验证 ✅ 已通过
§6 代码与 8 坑点 医疗 AI 数据工程师 代码走查 + 坑点对照官方文档与社区 Issue 复核 ✅ 已通过
§7 DAIMS 评分与偏倚分析 千方病案医学编辑部 24 项逐项复核 + 偏倚证据溯源 ✅ 已通过
§9 BibTeX 与引用格式 千方病案医学编辑部 DOI 逐条解析验证 ✅ 已通过

§10.5 AI 生成章节标注

本词条正文由 AI 辅助起草：§1 概览、§3 规格、§4 结构、§6 指南与坑点、§7 质量评估为 AI 起草 + 人工审核；§0 审核声明、§10 声明卡为人工编写；全部数字与引用经人工溯源核验。

§10.6 最后人工审核日期

2026-09-05（与 §0.3 审核日期一致）

页面状态：published（全部内容已完成审核并发布）

相关数据集导航

以下为站内 AI-Ready 数据集百科中与本词条共享多个主题标签的相关数据集，按相关度降序排列：

  • snds — 共享标签：公共卫生与流行病学 / 电子健康记录 / 真实世界数据 / 药物安全
  • maternal-ultrasound-nutrition — 共享标签：公共卫生与流行病学 / 电子健康记录 / 真实世界数据
  • marketscan — 共享标签：公共卫生与流行病学 / 电子健康记录 / 真实世界数据 / 药物安全
  • premier-pinc-ai — 共享标签：公共卫生与流行病学 / 电子健康记录 / 真实世界数据 / 药物安全
  • trinetx — 共享标签：电子健康记录 / 真实世界数据 / 药物安全
  • fda-sentinel — 共享标签：公共卫生与流行病学 / 真实世界数据 / 药物安全
  • cprd — 共享标签：电子健康记录 / 真实世界数据 / 药物安全
  • twosides — 共享标签：电子健康记录 / 真实世界数据 / 药物安全
  • faers — 共享标签：电子健康记录 / 真实世界数据 / 药物安全
  • cgrd — 共享标签：电子健康记录 / 真实世界数据 / 药物安全

导航说明：本章节由全站统一标签体系自动计算生成（标签重合度算法），双向可达；点击链接可跳转至对应数据集词条。

返回 AI-Ready 数据集

数据定制

标注服务

欢迎联系咨询

客服二维码

客服二维码

客服二维码
电话咨询

直接咨询

18892062214

微信同号

微信咨询

微信咨询

18892062214

微信同号

邮箱咨询

邮箱咨询

collab@qianfanghub.cn