IPCC AR6 Climate Retrieval

气候风险分析 Agent

用通俗语言询问地球上任何地方的高温、强降雨或大风情况，即可获得一份结构化并附有引用的风险报告，报告基于实时预报数据、60 多年的 ERA5 极端天气数据和 IPCC AR6。如果问题超出其可核查的范围，它会拒绝回答，而不是猜测。

在线演示： https://climate-risk-agent-714882950125.us-central1.run.app/（部署于公开的 Google Cloud Run）。

功能

• 可查询任何地点：输入地名进行地理编码，或直接输入纬度和经度。
• 并列展示该地点的实时预报和 60 多年的 ERA5 年度极值，并按页码引用所用的 IPCC AR6 页面。
• 根据该地点自身的重现水平曲线划分风险等级，而非使用固定阈值。
• 报告置信度的构成：该预报提前天数的实测预报技巧、气候态拟合情况，以及答案是否有引用支持。
• 原文引用包含该地点所在参考区域的 AR6 第 12 章预估变化。

测量护城河

• ERA5 GEV 危险统计数据。 每项危险数值都来自在查询位置拟合的广义极值分布，该分布基于 ERA5 超过 60 年的年度最大值。每个重现水平都附带 90% 自助法置信区间。
• 风险等级反映当地罕见程度，而非固定阈值。 等级取决于预测峰值在该位置自身曲线上的重现期：低于 2 年水平为低，2 至 10 年为中等，10 至 50 年为高，达到或超过 50 年为严重。同一个 46 °C 峰值，在普通年份就会达到这一温度的地方可能评为低，而在前所未见的地方则可能评为严重；两者使用的是同一套代码。每份报告都会附上决定等级的说明句，列明相邻重现水平和估计重现期。没有拟合气候统计数据的位置会改用绝对阈值，并明确说明这一点，不会将其伪装成当地标准。
• 非平稳 GEV。 除平稳拟合外，漂移位置的 GEV 还会检查该位置的气候是否确实在变暖，并通过似然比检验作出判断。如果趋势显著，报告的重现水平将采用最新年份的“有效”值，而非六十年间的平均值。柏林的结果约为每十年升高 +0.75 °C（p < 0.0001），并采用有效水平。德里的结果为平稳，在应用使用的两个德里位置点都没有显著趋势（UI 预设德里位置点为 p = 0.46，距离约 5 km 的地理编码城市位置点为 p = 0.84），这与已发表文献一致：气溶胶遮蔽效应抑制了南亚的高温趋势。斜率、p 值、精确坐标和代码版本见 evals/results/warming-trend-2026-10-21.json。该文件由 scripts/measure_warming_trend.py 基于全新的 ERA5 1960 至 2022 年拟合生成。
• 带有经得起核查的引文的 IPCC AR6 RAG。 每条引文都会根据针对该问题实际检索到的页面进行结构化核验。如果模型无法指出真实检索到的页面，就会拒绝作答，而不会照样引用。
• 引用而非生成的预估变化。 每份报告都包含涵盖该位置的参考区域所对应的 AR6 WG1 第 12 章气候影响驱动因子预估：一条逐字引用的第 12 章句子、变化方向、IPCC 自身校准的置信度措辞，以及其中注明的升温水平或时期。所有内容都通过正则表达式从检索到的文本块中提取，不涉及模型。如果该章节没有评估该区域和危险因素的此类变化，报告就不会包含此部分，并会说明语料库中未找到区域预估。

同一份报告向下滚动后：ERA5 重现水平表及其自助法置信区间、变暖趋势横幅，以及该次运行经测量的成本和延迟。

工作原理

自由文本问题会依次经过解析、地理编码和 AR6 区域映射，然后才会交给 Agent。之后，由一个包含五个节点的 LangGraph Agent（规划、调用、研究、预估、综合）生成类型化的 RiskReport，或拒绝作答。

flowchart LR
    Q[free-text question] --> PARSE[parse<br/>location · hazard · horizon]
    PARSE --> GEO[geocode<br/>Open-Meteo]
    GEO --> REGION[map to IPCC AR6 region<br/>reference regions v4]
    REGION --> PLAN[agent: plan<br/>scope check]
    PLAN -->|unsupported hazard| REFUSE[refusal<br/>valid typed output]
    PLAN --> CALL[agent: call<br/>forecast]
    CALL --> RESEARCH[agent: research]
    RESEARCH --> PROJECT[agent: project<br/>AR6 Ch.12 CID projection]
    PROJECT --> SYNTH[agent: synthesize]
    SYNTH --> REPORT[RiskReport<br/>typed · cited · grounded]

    subgraph HAZARD [ERA5 to GEV hazard statistics]
        ERA5[ERA5<br/>60+ yr annual maxima] --> GEV[stationary + drifting-location GEV]
        GEV --> LRT[likelihood-ratio test<br/>is the trend real?]
        LRT --> LEVELS[return levels + 90% bootstrap CI<br/>effective at latest year if trend holds]
    end
    CALL -.-> HAZARD
    HAZARD -.-> SYNTH

    subgraph RAG [IPCC AR6 RAG]
        HYBRID[BM25 + dense hybrid<br/>RRF fusion] --> VALID[citations validated<br/>against retrieved pages]
    end
    RESEARCH -.-> RAG
    RAG -.-> SYNTH

UI 会将同一次运行显示为七个具名步骤，并按以下顺序排列（agent/progress.py）：解析位置、拟合 60 年 ERA5 极值、检查问题是否在范围内、获取预报、搜索 IPCC AR6、读取第 12 章对所在区域的预估、撰写带引文的报告。

评估

• **开发集：**60 个问题，用于指导分块和检索配置等开发决策。15 个 cid-table 问题随第 12 章投影层一同加入，该数据集随后使用新的 SHA-256 重新冻结。
• **测试集：**105 个新问题，在开发集建立后编写，从未用于调优任何内容，并通过 SHA-256 冻结，确保两个数据集都不会悄然变化。其中 70 个问题可回答（24 个单页问题、22 个区域表格问题、15 个跨页问题、9 个重复区域问题），35 个问题专为拒答而设计（17 个前提注入问题、10 个范围外风险问题、8 个语料库外问题）。

开发集检索结果，共 60 个问题（49 个可回答），测量日期为 2026-09-02：

检索器	R@3	R@5	R@10	MRR
仅 BM25	76%	82%	88%	0.68
仅 dense	61%	69%	86%	0.59
混合（已部署）	82%	90%	94%	0.70

按类别划分，混合检索器的 R@3：单页 92%（n=12）、区域表格 90%（n=10）、跨页 80%（n=10）、前提注入 75%（n=4）、cid-table 67%（n=15）。cid-table 是表现最弱的类别，因此全部 60 个问题的总体结果为 82%，而原先 45 个问题的结果为 91%。

开发集端到端结果，共 60 个问题（gemini-2.5-flash，top_k 8，关闭范围防护第 2 阶段），测量日期为 2026-09-02：

项目	数量
正确回答	48
正确拒答	11
错误拒答	1
错误回答	0

引用有效性为 41/48（85%）。数值溯源率为 42/48（88%）。有依据的拒答为 3/4。此轮运行成本为 $0.20，约合每个问题 $0.0034；55 次模型调用的 p50 延迟为 5.5 秒，其中 6 次限流重试，无失败。

留出集结果（在已部署的确切配置下进行第二次评估）：

• 检索：混合检索器对 70 个可回答问题的结果（测量日期为 2026-09-07）：R@3 为 87%，R@5 为 91%，R@10 为 96%，即 70 个问题中分别命中 61、64 和 67 个。
• 端到端：全部 105 个问题（gemini-2.5-flash，top_k 8，测量日期为 2026-07-22）：49 个正确回答、35 个正确拒答、21 个错误拒答、0 个错误回答。专为拒答而设计的 35 个问题全部被拒答；代价是 70 个可回答问题中也有 21 个被拒答。
• 正确回答的引用有效性为 47/49（96%）。数值溯源率为 43/49（88%）。
• IPCC 回答步骤此轮运行成本为 $0.29，约合每个问题 $0.003；生成延迟 p50 为 3.9 秒。

**重排与查询改写：已测量，保持关闭。**二者均以 HybridRetriever 关键字参数接入，且默认关闭。在包含 45 个问题（34 个可回答）的开发集上测量，时间早于 cid-table 问题加入：

方案	R@3	R@5	R@10	MRR	p50	每个问题的成本
混合（已部署）	88%	94%	94%	0.76	40 到 48 ms	$0
+ MiniLM 交叉编码器	79%	85%	91%	0.68	4.0 s	$0
+ Gemini 重排器	82%	94%	94%	0.74	38 s	$0.0123
+ 查询改写	79%	79%	88%	0.74	6.1 s	$0.0013
+ Gemini 重排器和查询改写	74%	79%	85%	0.65	39 s	$0.0127

没有任何方案在任何 k 值下胜过基线，而其中成本最低的方案，延迟约为基线的 100 倍。代码中仍保留这些接口，因为正是测量结果让保持关闭这一选择有据可依。

**语义范围防护，第 2 阶段：已测量，保持关闭。**第 1 阶段采用词法匹配，并在任何模型调用前运行。第 2 阶段（rag/scope_semantic.py，CRG_SCOPE_STAGE2=off|embed|llm）只读取第 1 阶段判定未决的问题。在包含 45 个问题的开发集上测量，指标依次为正确回答 / 正确拒答 / 错误拒答 / 错误回答：

方案	矩阵	每个问题增加的延迟	每个问题增加的成本
关闭（已部署）	34/11/0/0	0	$0
embed	33/11/1/0	24 ms	$0
llm	34/11/0/0	2.8 s	$0.00025

所有方案的错误回答数均为零，且没有任何方案带来收益，因此默认设置保持关闭。embed 方案中那一次错误拒答包含词法风险词汇，因此从未进入第 2 阶段。待留出集运行确认矩阵保持不变后，应优先采用 embed 方案。完整说明见 LIMITATIONS.md。 每个评估产物都会记录生成它的模型，因为模型更换不会在测试套件中显现。更换回答模型后，如果没有重新运行这些评估，基准测试就发现了单元测试未发现的实用性退化：参见 adr/0001-answering-model-selection.md。

拒答按 4 格混淆矩阵评分（正确回答、正确拒答、错误拒答、错误回答）。该矩阵中只要出现一次错误回答，就会阻止发布。

**门槛：**它由退出码判定，而不是靠肉眼检查。出现任何错误回答、标题指标 R@3 比上次已提交的运行结果低超过 3 个百分点，或产物中缺少混合检索器（这意味着运行悄悄只测了 BM25），构建都会失败。参见 DEPLOY.md。

预报技能

每个灾害数值都基于一份预报，而提前六天预测的峰值与预测明天的峰值并非同一结论。我们会测量这种差距，而非想当然。scripts/measure_forecast_skill.py 会读取 Open-Meteo 的 Previous Model Runs API，该 API 存档了模型在事件发生前 1 至 7 天对每个小时的预测，并针对模型自己的第 0 天运行结果，对 2024-01-01 至 2025-12-31 期间六大洲 13 个城市的每个提前时长进行评分，每个提前天约有 9,200 个城市日。

灾害	MAE，第 1 天	MAE，第 7 天	捕捉到的极端日，第 1 天 → 第 7 天
每日最高气温	0.70 °C	1.93 °C	85% → 47%
每日降水总量	2.03 mm	3.03 mm	53% → 3%
每日最大风速	2.16 km/h	4.68 km/h	71% → 29%
每日最大阵风	3.47 km/h	8.26 km/h	69% → 34%

“捕捉到的极端日”表示：某一天的数值高于该地点自身第 95 百分位时，预报也高于该百分位的频率。冻结的数值及其来源信息保存在 tools/forecast_skill_table.json 中，tools.forecast_skill.skill_for(hazard, horizon_days) 会读取这些数值；对于超过第 7 天的预报时长（存档数据止于此处），它会将时长限制在第 7 天，并标记为外推值。

报告会使用这些数值，而非仅展示它们。置信度为 min(0.75, 0.3 * w + climatology bonus + 0.1 if IPCC-cited)，其中 w = min(hit rate over lead days 1..L) / hit rate at day 1，表示提前到第 L 天时，第 1 天的极端事件检测能力仍保留的比例。第 1 天的高温报告会保留完整的 0.3 预报项；第 7 天的报告则保留其 0.56。每份报告都会包含一个 forecast_skill 驱动项，说明起作用的数值：“第 7 天的气温预报有 47% 的概率达到当地极端值（GFS Global 与其自身第 0 天运行结果对比，13 个城市，2024-2025），因此预报证据的权重降至第 1 天数值的 0.56。”在 w 中采用运行最小值是有意为之。第 6 天的降水检测率为 1.7%，第 7 天为 3.5%；基于约 458 个极端日，这属于抽样噪声，而非预报随着提前时长增加而变准。采用最小值才能让置信度保持单调，因此不会把更长预报时长报告得更有把握。

这些数值附带三点注意事项。参考序列采用的是模型自身最新的一次运行，而非气象站观测，因此这些数值是运行间一致性误差，也是实际预报误差的下限。模型固定为 GFS Global，因为 Open-Meteo 的默认 best_match 会在不同提前时长之间拼接不同模型，制造出看似体现预报能力的偏差：在 Delhi，第 1 天的风速预报偏差达 5.3 km/h，而第 7 天的预报误差却在 0.1 km/h 以内。此外，超过预报第 120 小时后，GFS 会将逐小时输出切换为每 3 小时输出，导致每日降雨总量趋于平缓；因此，第 4 天之后降水检测率骤降，部分原因是输出分辨率，而不仅仅是预报未能捕捉到风暴。

运维

• 气候学拟合、预测和答案缓存共用一个缓存：设置 UPSTASH_REDIS_REST_URL 和 UPSTASH_REDIS_REST_TOKEN 时使用 Upstash Redis over REST，否则使用磁盘缓存。tools/cache_backend.py 会记录所选的后端，scripts/prewarm.py 会在演示前填充缓存。
• 结构化日志和逐请求遥测在每次模型调用都会经过的单一 SDK 接口处测量：延迟、令牌数、重试次数和成本。推理令牌计为计费输出；如果模型没有价格条目，其成本会报告为未知，而非零。内存事件环形缓冲区有容量上限；JSONL 接收器则保留完整历史记录。
• DEPLOY.md 中介绍了各类 Cloud Run 最小实例配置的空闲成本、实测的 30 天负载和扩容计划。
• 异步 FastAPI 服务（POST /report），提供逐请求 API 密钥访问控制和 /metrics 端点。
• 两个 MCP 服务（天气、IPCC RAG）通过 Model Context Protocol 提供相同的工具。
• CRG_BOOTSTRAP_N 用于设置每次拟合的 GEV 自助重拟合次数（默认值：平稳情形为 300，趋势调整情形为 200）；该值在导入时读取，并作为危险拟合缓存键的一部分，可在置信区间精度和拟合耗时之间权衡。
• Docker 镜像在本地测得为 0.31 GB。每次推送和拉取请求时，ci.yml 都会运行 ruff、mypy 和 pytest；在推送 v* 标签或手动触发时，evals.yml 会运行两项评估，使用作为发布资源下载的预构建嵌入缓存，因此发布时无需重新嵌入语料库。

运行

uv sync
uv run streamlit run ui/app.py

使用自然语言提问，或使用侧边栏选择地球上的任意位置：输入地点名称进行地理编码，或直接输入纬度和经度。示例按钮会加载预热过的演示城市。地图会显示所选位置（仅供展示）及其 IPCC AR6 区域；如果该位置不属于任何区域，则会显示提示。

请求运行期间，实时进度面板会显示当前步骤、每个步骤耗时（秒），并为缓存提供的步骤标注提供服务的缓存层级。

新地点的首份报告大约需要 1 到 2 分钟，因为系统需要获取 60 多年的 ERA5 日极值数据，并为该地点拟合一次 GEV。之后，拟合结果会被缓存；配置了 Redis 时使用 Redis，否则使用磁盘缓存，重复访问的响应时间不到一秒。

使用 Docker：

docker build -t climate-risk-agent .
docker run -p 7860:7860 -e GEMINI_API_KEY=... climate-risk-agent

在线演示运行在 Google Cloud Run 上。部署到 Cloud Run、本地 Docker 或其他主机，请参阅 DEPLOY.md。

使用 MCP 服务

两个服务都使用 stdio 通信。从仓库根目录开始，将任意 MCP 客户端指向它们：

{
  "mcpServers": {
    "climate-weather": {
      "command": "uv",
      "args": ["run", "--no-sync", "python", "-m", "tools.weather_mcp"]
    },
    "climate-ipcc-rag": {
      "command": "uv",
      "args": ["run", "--no-sync", "python", "-m", "tools.ipcc_mcp"]
    }
  }
}

服务	工具
climate-weather	forecast, hazard_climatology
climate-ipcc-rag	search_ipcc, answer_ipcc

两个服务都以 MCP 协议 2026-07-28（mcp 2.0.0）为目标，这是当前版本。 每个工具都标注为只读，并带有面向用户的标题和开放或封闭世界提示；每个工具都会发布 outputSchema，并按确定性顺序列出。两个测试会将每个服务作为真实子进程启动并与其进行协议通信，而不是在进程内调用工具函数。

检索采用混合方式，因此两个 IPCC 工具都会对查询进行嵌入，并需要在服务进程中提供凭据：设置 GOOGLE_GENAI_USE_VERTEXAI=true 和 GOOGLE_CLOUD_PROJECT，或设置 GEMINI_API_KEY。

客户端不会把你的 shell 交给服务。它只会传递一个简短的允许列表，其中包含少量变量（PATH、APPDATA、TEMP，……），因此服务无法窃取你的机密；这也意味着由客户端启动的服务一开始没有凭据。你可以在客户端自己的 env 块中提供凭据，或将 .env.example 复制为 .env：IPCC 服务会在启动时读取该文件，并且绝不会覆盖客户端已传递的值。

要手动探索这些工具：uv run mcp dev tools/ipcc_mcp.py。

已发布到 MCP 官方注册表

IPCC RAG 服务已发布到 MCP 官方注册表，标识为 io.github.AswaniSahoo/climate-ipcc-rag（v0.1.0），并由 GHCR 上的公开 OCI 镜像 （ghcr.io/aswanisahoo/climate-ipcc-rag-mcp:0.1.0）提供支持。任何支持 Docker/OCI 传输的 MCP 客户端 都可以直接从注册表安装。

贡献

设置方法、确切的 CI 命令、评估发布门槛和 PR 要求见 CONTRIBUTING.md；参与贡献请遵守行为准则。 问题报告请使用以下模板：错误、数据准确性和问题咨询。 返回的等级有误、页面引用有误或区域映射有误，都属于这里需要优先处理的错误，请按错误报告。

技术栈

Python、LangGraph、Google Gemini（生成）+ Vertex AI 上的 gemini-embedding-2（稠密向量）（全球端点）、BM25 + 稠密向量混合检索（RRF 融合）、Pydantic、FastAPI、Streamlit、MCP Python SDK、scipy、Docker、GitHub Actions。

局限性

• ERA5 是网格化再分析数据，并非气象站观测数据。灾害统计描述的是查询位置附近经过插值的网格单元，而不是在该位置实地测得的数据。
• 适用范围包括高温、极端降水和风。其他内容应拒绝回答，而非作答。
• 覆盖范围为全球，但 IPCC AR6 区域背景信息并非如此。位于所有 AR6 陆地区域之外的点（公海）仍会获得预报和灾害统计，并提示缺少区域背景信息。
• 用于拦截范围外灾害、避免其进入大模型的范围守卫采用词汇匹配（基于关键词）。若改述时避开已知词汇，可能绕过该守卫。

数据来源和许可

• 预报：Open-Meteo，CC BY 4.0。
• ERA5 日极端值：ERA5 再分析数据，通过 Open-Meteo 存档服务提供，适用相同许可。
• 气候评估：IPCC AR6 WG1 SPM、第 11 章和第 12 章 PDF，依据 IPCC 条款用于研究。
• AR6 参考区域多边形：从 IPCC WGI Atlas 引入并打包在 tools/ar6/ 中，适用 CC BY 4.0。必需引用：Iturbide, M., Fernández, J., Gutiérrez, J.M. 等。《在 IPCC 中实施 FAIR 原则：WGI AR6 Atlas 代码仓库》。Scientific Data 9, 629（2022）。https://doi.org/10.1038/s41597-022-01739-y

完整列表见 LIMITATIONS.md，威胁模型见 SECURITY.md。已发布的功能及后续计划见 ROADMAP.md。