nmikati3/geoinsights-data
GitHub: nmikati3/geoinsights-data
从 GDELT 全球新闻数据库中自动抽取、聚类并结构化地缘政治事件的研究型数据管线。
Stars: 1 | Forks: 0
# GeoInsights 数据
**一个自动化的 pipeline，可将全球新闻转化为结构化、去重的地缘政治事件数据库** —— 涵盖五个领域：**网络攻击、军事援助、军事攻势、制裁和国际峰会。**
它通过 BigQuery 从 [GDELT](https://www.gdeltproject.org/) 发现文章，利用混合的机器学习 + LLM 技术栈进行过滤和丰富，将相关报道聚类为独立的现实世界**事件**，并发布 JSON/Parquet 数据集。
这是一个研究项目。该代码库公开是为了展示一种将新闻文章转化为结构化事件数据集的方法。它并不旨在成为一个完全成熟的软件。
## 产出内容
对于每个领域，该 pipeline 会创建两个数据集：**reports**（经过丰富的独立文章）和 **incidents**（汇总了其对应 reports 且去重过的现实世界事件），外加用于快速查询的时间窗口切片（14 天、1/2/5 年）。跨领域连接会将所有五个领域合并为一个统一的 schema。
一个 incident 大致如下所示（示意）：
```
{
"incident_id": "20240712-cyber-0-3",
"incident_type": "Cyberattack",
"incident_start_date": "2024-07-12",
"initiating_countries": ["Russia"],
"receiving_countries": ["Ukraine", "European Union"],
"sectors": ["Energy", "Government"],
"threat_actors": ["Sandworm"],
"summary": "A coordinated cyberattack targeted Ukrainian energy-sector operators ...",
"num_reports": 14
}
```
## 架构
五个领域作为单个 Cloud Run Job（`CLOUD_RUN_TASK_INDEX` 0–4）的并行任务运行。每个领域都流经相同的 12 阶段 **增量** pipeline；一个单独的作业负责连接各项输出。
```
flowchart TD
subgraph domain["Per-domain pipeline (x5: cyber, military aid, military offensive, sanctions, summits)"]
A["GDELT via BigQuery
(multilingual keyword filters)"] --> B[translate
langdetect + Google Translate] B --> C[classify
embeddings + sklearn logistic regression] C --> D[add_content
full-article extraction] D --> E[llm_classify
LLM precision filter] E --> F[summarize
local Gemma LLM] F --> G[label
LLM extraction + PolyFuzz normalization] G --> H[cluster
temporal sliding-window embedding clustering] H --> I[add_source_info
outlet metadata join] I --> J[incident_summarize
aggregate reports - incident summary] J --> K[compute_embeddings
per-incident embeddings] end K --> L[(Domain JSON / Parquet
databases in GCS)] L --> M[join_datasets
cross-domain schema unification] M --> N[(Unified geopolitical
events database)] ``` ### 核心技术特性 - **混合 ML + LLM 漏斗**：首先通过低成本的 embedding + 专门的 logistic 回归分类器进行过滤（参见 cyber 文件夹中关于网络事件的示例 notebook），因此昂贵的 LLM 只需处理留下来的结果；使用本地 Gemma 模型处理高吞吐量的摘要阶段，以控制 API 成本。 - **时间滑动窗口事件聚类**：将摘要按周对（余弦相似度 → 图连通分量）进行聚类，然后跨重叠窗口合并聚类标签；大型事件会使用 HDBSCAN + KNN 重新聚类。参见 `[geoinsights_data/utils/cluster.py](./geoinsights_data/utils/cluster.py)`。 - **受控词表标准化**：嘈杂的 LLM 提取结果（国家、行业、威胁行为者）通过 PolyFuzz 映射到受控词表，并带有 MITRE ATT&CK 别名解析功能。 - **跨领域 schema 统一**：五个领域的 schema 折叠为一个事件模型，并包含诸如 EU 聚合等规则。 - **设计上的多语言支持**：在 GDELT 查询层，关键词集涵盖了约 25 种语言。 ## 仓库布局 ``` geoinsights_data/ ├── pipeline/ # Main orchestrator (5 parallel domain tasks) + Dockerfile ├── sources/ # News-outlet metadata enrichment job + Dockerfile ├── join_datasets/ # Cross-domain merge job + Dockerfile ├── cyber/ military_aid/ military_offensive/ sanctions/ summits/ │ # Per-domain prompts.py + keywords.yaml └── utils/ # Shared stages: collect, translate, classify, add_content, # llm, local_llms, cluster, incident_summarize, rules tests/ # Unit tests ``` ## 技术栈 Python 3.12 · GCP (Cloud Run Jobs, BigQuery, Cloud Storage, Artifact Registry, Cloud Scheduler) · scikit-learn · PyTorch · HDBSCAN · OpenAI (embeddings + LLMs) · 基于 llama-cpp 的本地 Gemma · newspaper3k · PolyFuzz · MITRE ATT&CK (attackcti) · pandas / pyarrow · Docker. ## 配置 该 pipeline 完全通过环境变量进行配置（代码库中无密钥）： | 变量 | 用途 | | -------------------------------------------- | ------------------------------------------------------------------------ | | `BUCKET_NAME` | 保存所有 pipeline 状态、模型和输出的 GCS 存储桶 | | `PROJECT_ID` | 用于 BigQuery 的 GCP 项目 | | `OPENAI_API_KEY` | OpenAI API 密钥（embeddings + chat） | | `MODEL_NAME` | 用于分类/标签的 OpenAI chat 模型 | | `EMBEDDING_MODEL` | Embedding 模型（例如 `text-embedding-3-small`） | | `CLOUD_RUN_TASK_INDEX` | 在运行 pipeline 作业时选择领域 (0–4) | | `*_CLASSIFICATION_THRESHOLD` | 各领域的分类器阈值（例如 `CYBER_CLASSIFICATION_THRESHOLD`） | | `LLAMA_MODEL_PATH`, `LLAMA_N_CTX`, `HF_HOME` | 本地 LLM（摘要生成）设置 | 训练好的分类器模型（`*.pkl`）和所有 CSV/JSON 状态都保存在 GCS 存储桶中，而不是代码库中。 ## 部署 有关完整的 Cloud Run Jobs + Artifact Registry + Cloud Scheduler 设置，请参阅 [DEPLOYMENT.md](./DEPLOYMENT.md)。 ## 数据来源与许可 - 文章发现使用了 BigQuery 上的公开 **GDELT GKG** 数据集 —— 请查阅 [GDELT 条款](https://www.gdeltproject.org/about.html#termsofuse)。 - 丰富数据的过程会调用 **OpenAI API** 和 **Google Translate**；在分发派生数据之前，请查阅其相关条款。 - 本项目的代码采用 [Apache-2.0](./LICENSE) 许可。本项目**未**隶属于 GDELT、OpenAI、Google 或 MITRE，也未受到其认可。 ## 已知简化项 这最初是一个个人产品，按原样分享。值得注意的是：测试覆盖率有限，分类器和聚类没有正式的准确性/评估测试工具，且各个领域分支之间存在一些重复。欢迎贡献代码 —— 参见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
(multilingual keyword filters)"] --> B[translate
langdetect + Google Translate] B --> C[classify
embeddings + sklearn logistic regression] C --> D[add_content
full-article extraction] D --> E[llm_classify
LLM precision filter] E --> F[summarize
local Gemma LLM] F --> G[label
LLM extraction + PolyFuzz normalization] G --> H[cluster
temporal sliding-window embedding clustering] H --> I[add_source_info
outlet metadata join] I --> J[incident_summarize
aggregate reports - incident summary] J --> K[compute_embeddings
per-incident embeddings] end K --> L[(Domain JSON / Parquet
databases in GCS)] L --> M[join_datasets
cross-domain schema unification] M --> N[(Unified geopolitical
events database)] ``` ### 核心技术特性 - **混合 ML + LLM 漏斗**：首先通过低成本的 embedding + 专门的 logistic 回归分类器进行过滤（参见 cyber 文件夹中关于网络事件的示例 notebook），因此昂贵的 LLM 只需处理留下来的结果；使用本地 Gemma 模型处理高吞吐量的摘要阶段，以控制 API 成本。 - **时间滑动窗口事件聚类**：将摘要按周对（余弦相似度 → 图连通分量）进行聚类，然后跨重叠窗口合并聚类标签；大型事件会使用 HDBSCAN + KNN 重新聚类。参见 `[geoinsights_data/utils/cluster.py](./geoinsights_data/utils/cluster.py)`。 - **受控词表标准化**：嘈杂的 LLM 提取结果（国家、行业、威胁行为者）通过 PolyFuzz 映射到受控词表，并带有 MITRE ATT&CK 别名解析功能。 - **跨领域 schema 统一**：五个领域的 schema 折叠为一个事件模型，并包含诸如 EU 聚合等规则。 - **设计上的多语言支持**：在 GDELT 查询层，关键词集涵盖了约 25 种语言。 ## 仓库布局 ``` geoinsights_data/ ├── pipeline/ # Main orchestrator (5 parallel domain tasks) + Dockerfile ├── sources/ # News-outlet metadata enrichment job + Dockerfile ├── join_datasets/ # Cross-domain merge job + Dockerfile ├── cyber/ military_aid/ military_offensive/ sanctions/ summits/ │ # Per-domain prompts.py + keywords.yaml └── utils/ # Shared stages: collect, translate, classify, add_content, # llm, local_llms, cluster, incident_summarize, rules tests/ # Unit tests ``` ## 技术栈 Python 3.12 · GCP (Cloud Run Jobs, BigQuery, Cloud Storage, Artifact Registry, Cloud Scheduler) · scikit-learn · PyTorch · HDBSCAN · OpenAI (embeddings + LLMs) · 基于 llama-cpp 的本地 Gemma · newspaper3k · PolyFuzz · MITRE ATT&CK (attackcti) · pandas / pyarrow · Docker. ## 配置 该 pipeline 完全通过环境变量进行配置（代码库中无密钥）： | 变量 | 用途 | | -------------------------------------------- | ------------------------------------------------------------------------ | | `BUCKET_NAME` | 保存所有 pipeline 状态、模型和输出的 GCS 存储桶 | | `PROJECT_ID` | 用于 BigQuery 的 GCP 项目 | | `OPENAI_API_KEY` | OpenAI API 密钥（embeddings + chat） | | `MODEL_NAME` | 用于分类/标签的 OpenAI chat 模型 | | `EMBEDDING_MODEL` | Embedding 模型（例如 `text-embedding-3-small`） | | `CLOUD_RUN_TASK_INDEX` | 在运行 pipeline 作业时选择领域 (0–4) | | `*_CLASSIFICATION_THRESHOLD` | 各领域的分类器阈值（例如 `CYBER_CLASSIFICATION_THRESHOLD`） | | `LLAMA_MODEL_PATH`, `LLAMA_N_CTX`, `HF_HOME` | 本地 LLM（摘要生成）设置 | 训练好的分类器模型（`*.pkl`）和所有 CSV/JSON 状态都保存在 GCS 存储桶中，而不是代码库中。 ## 部署 有关完整的 Cloud Run Jobs + Artifact Registry + Cloud Scheduler 设置，请参阅 [DEPLOYMENT.md](./DEPLOYMENT.md)。 ## 数据来源与许可 - 文章发现使用了 BigQuery 上的公开 **GDELT GKG** 数据集 —— 请查阅 [GDELT 条款](https://www.gdeltproject.org/about.html#termsofuse)。 - 丰富数据的过程会调用 **OpenAI API** 和 **Google Translate**；在分发派生数据之前，请查阅其相关条款。 - 本项目的代码采用 [Apache-2.0](./LICENSE) 许可。本项目**未**隶属于 GDELT、OpenAI、Google 或 MITRE，也未受到其认可。 ## 已知简化项 这最初是一个个人产品，按原样分享。值得注意的是：测试覆盖率有限，分类器和聚类没有正式的准确性/评估测试工具，且各个领域分支之间存在一些重复。欢迎贡献代码 —— 参见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
标签：BigQuery, DLL 劫持, Google Cloud, Web爬虫与抽取, 凭据扫描, 地缘政治分析, 基准测试, 大语言模型, 数据处理管线, 数据集构建, 请求拦截, 逆向工具