## 🎯 问题背景
每年，印度都有数千只濒危动物死于盗猎和非法野生动物贸易。执法和保护团队面临着以下挑战：
- **情报碎片化** —— 盗猎事件散布于数百个使用不同地方语言的区域新闻来源中
- **响应速度慢** —— 人工监控往往会滞后数小时甚至数天才能发现关键事件
- **缺乏集中化系统** —— 没有单一平台能够实时聚合、分析和绘制野生动物犯罪数据地图
## 💡 解决方案
**野生动物智能平台** 是一个生产级、AI 驱动的系统，可持续监控区域新闻源，从非结构化文章中提取结构化情报，并通过统一的指挥中心仪表板呈现可操作的洞察。
该平台与 **印度野生动物信托基金 (WTI)** 合作开发，旨在弥合非结构化的实地报告/新闻与积极执法之间的鸿沟。
### 与众不同之处
| 功能 | 传统方式 | 本平台 |
|---|---|---|
| **数据收集** | 人工 Google 搜索 | 自动化主动源抓取 (RSS, API, GDELT) |
| **语言支持** | 仅限英语 | 7 种优化的印度语言，包括印地语、卡纳达语、泰米尔语、泰卢固语、马拉雅拉姆语、孟加拉语 |
| **分析** | 人工阅读 | 混合智能引擎 (NER、零样本分类和风险评分) |
| **WPA 映射** | 人工查阅 | 内置《野生动物保护法》(WPA) 法律附录查询 |
| **指控书起草** | 人工检索 | 基于事件数据自动生成法律指控书草案 |
| **威胁情报** | 历史报告 | 预测性热点地图、区域威胁等级和物种预测 |
| **更新频率** | 每日/每周 | 每 3 分钟一次，全天候 24/7 并带有 WebSocket 实时更新 |
## ⚙️ 系统架构
数据自上而下流经五个层级：**多源接入** (RSS, OSINT, 新闻 API) → **去重与限速收集** → **混合 AI 处理引擎** (NER、零样本分类、物种识别) → **预测性情报层** (风险评分、热点检测、网络分析) → 最终汇入 **指挥中心仪表板** 和 **实时警报系统**。
## 🚀 核心功能
### 🤖 混合智能引擎
- **多模型 AI pipeline**：基于规则的快速通道 + mDeBERTa-v3 transformer 分类器 + 可选的 SetFit 分类器。
- **地理归因**：将位置映射到 300 多个印度地区，并为当地文字提供兜底逻辑。
- **人员 NER Pipeline**：使用 Regex + 命名实体识别模型提取嫌疑人姓名，并配有 200 多个停用词拦截列表，以消除误报（如新闻机构、日期或地名）。
### 🔮 预测性威胁情报
- **威胁等级**：根据事件发生频率、物种濒危等级和当地盗猎历史，动态计算区域脆弱性评级（低、中等、较高、高、危急）。
- **盗猎热点**：识别高风险区域，以优化实地巡逻和资源部署。
- **物种脆弱性趋势**：建模并展示当前正面临较高威胁特征的物种。
### ⚖️ WPA 法律参考工具与指控书生成器
- **WPA 附录参考**：完整引用 1972 年《印度野生动物（保护）法》（含 2022 年修正案）的数据库，将物种映射到其相应的法律附录。
- **指控书草案生成器**：根据选定的事件数据，主动生成结构化的法律草案，引用特定的 WPA 章节、附录、处罚和管辖细节。
### 📊 系统运行与实时信息流
- **WebSocket 同步**：实时反馈循环，显示活跃的爬虫同步状态、数据处理状态以及实时事件更新。
- **生产环境强化**：使用常数时间令牌比较（`hmac.compare_digest`）保护管理员设置，并配置了带有安全生产标头的 HTTP cookie。
- **数据导出**：支持 CSV、格式化的 Excel 简报以及完整的分析师简报包。
## 🔔 事件到警报的工作流
从文章被收集到现场团队收到通知的那一刻起，每个事件都会流经一个五阶段的情报 pipeline：
**1. 事件检测** → 从 RSS/API 源收集新闻文章 · **2. AI 验证** → NLP 分类、物种识别、位置提取 · **3. 风险评分** → 威胁等级评估（低 / 中 / 高 / 极高） · **4. 警报生成** → 自动创建警报并附带完整情报档案 · **5. 利益相关者通知** → 通过电子邮件、Telegram 和 WebSocket 推送至现场团队。
## 🧠 大语言模型 (LLM) 集成
该平台通过 **Ollama Cloud** 具备与大语言模型的深度集成功能（支持 OpenAI 兼容的 endpoint、Azure、OpenAI 或本地实例）。
LLM 在系统架构的两个主要组件中部署：
### 1. 结构化文章摄取与法律标注 (`app/services/summarizer.py`)
在新闻摄取过程中，摘要服务使用 **`gemma3:27b`** 或 **`deepseek-v3.1:671b-cloud`** 模型处理非结构化的文章文本。LLM 被指示扮演 *印度政府的野生动物犯罪情报分析师* 角色，并返回该事件的 **STRICT JSON** 表示。
```
# LLM 返回的 System prompt schema
{
"is_wildlife_poaching_incident": bool, # Verifies active poaching/smuggling/trade in India
"suggested_confidence_score": int, # Factuality verification score (0-100)
"llm_classification_reason": str, # Logic audit trail for classifications
"summary": str, # High-impact 2-3 sentence overview
"key_facts": list, # Structured bulleted fact lists (max 6)
"smuggling_route": str, # Transit routes detected (e.g. state border crossings)
"wpa_schedule": str, # Mapped WPA Schedule (Schedule I/II/III/IV/V/VI)
"wpa_section": str, # Target violations (e.g., Section 9, 39, 49-B, 51)
"wpa_offence_type": str, # Hunting, Possession, Illegal Trade, etc.
"wpa_penalty_class": str, # Severe, moderate, or minor severity
"protected_area_type": str, # Associated Wildlife Sanctuary/National Park
"enforcement_authority": str, # State Forest Dept, Police, WCCB, etc.
"extracted_species": list, # Singularized, lowercased English common names
"extracted_suspects": list, # Fully capitalized perpetrator names (filters officers)
"extracted_location": str # Formatted "State, District" geographic target
}
```
#### LLM Prompt 处理细节：
- **物种映射**：自动将区域性的物种名称翻译为统一的英文名称（例如，*Chital* → *spotted deer*，*Kala Hiran* → *blackbuck*）。
- **嫌疑人过滤**：过滤掉负责调查的森林官员、SP 或警察督察的姓名，仅捕捉真正的嫌疑人/被捕人员。
- **WPA 附录**：应用严格的准则，将濒危物种（老虎、豹子、大象、穿山甲、印度羚）映射到 **Schedule I**，并将受保护程度较低的物种（豺、猴子、眼镜蛇）映射到 **Schedule II**。
### 2. 检索增强生成 (RAG) 引擎 (`app/services/rag_engine.py`)
该平台包含一个交互式搜索和简报工具，由利用 **`llama3.3-70b-instruct`** 或 **`meta-llama-3.1-8b-instruct`** 模型的 RAG pipeline 提供支持。
```
[ User Query ]
│
▼
┌──────────────────────────────────┐
│ Semantic Search │
│ Matches vectors in SQLite db │
└────────────────┬─────────────────┘
│
▼
┌──────────────────────────────────┐
│ Context Ingestion & Filtering │
│ Aggregates top incident records │
└────────────────┬─────────────────┘
│
▼
┌──────────────────────────────────┐
│ LLM Synthesis Prompt │
│ Instructs to answer only based │
│ on structured context entries │
└────────────────┬─────────────────┘
│
▼
[ Analyst Briefing Pack ]
Concise sentences + [ID] citations
```
LLM 将上下文文件格式化为整合的简报响应，并在括号表示法中引用事件 ID，以提供可审计的来源验证。
## 🗣️ 优化的语言支持
为了优化抓取速度并消除 API 速率限制（例如 Google RSS 503 冷却时间），平台的查询处理器被限制为 **7 种高产语言**：
| 语言 | 文字 | 重点关注区域 |
|---|---|---|
| **英语** | 拉丁语 | 全国 |
| **印地语** (हिन्दी) | 梵文天城体 | 印度北部 / 中部 |
| **卡纳达语** (ಕನ್ನಡ) | 卡纳达文 | 卡纳塔克邦 |
| **泰米尔语** (தமிழ்) | 泰米尔文 | 泰米尔纳德邦 |
| **泰卢固语** (తెలుగు) | 泰卢固文 | 安得拉邦 / 特伦甘纳邦 |
| **马拉雅拉姆语** (മലയാളം) | 马拉雅拉姆文 | 喀拉拉邦 |
| **孟加拉语** (বাংলা) | 孟加拉文 | 西孟加拉邦 |
## 💻 技术栈
- **后端**：FastAPI, Python 3.11+, SQLAlchemy, SQLite (通过 Alembic 迁移支持 PostgreSQL)
- **AI / NLP**：Hugging Face Transformers (mDeBERTa-v3), SetFit, 多语言 NER, Ollama / OpenAI 兼容的 LLM
- **前端**：React (Vite), Tailwind CSS / Vanilla CSS, Lucide 图标, Leaflet (地图)
- **实时与基础设施**：WebSockets, Nginx, Systemd 服务, DigitalOcean droplet
- **质量保证**：pytest 套件（81 个测试），GitHub Actions CI, Alembic schema 迁移
## 🚀 快速开始
```
# 1. Clone the repository
git clone https://github.com/Siddhanthkjain2005/Wildlife-News.git
cd Wildlife-News
# 2. Create a virtual environment and install dependencies
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
# 3. Configure environment
cp .env.example .env # then edit values as needed
# 4. Apply database migrations
alembic upgrade head
# 5. Run the application
uvicorn app.main:app --reload --port 8000
```
随后即可在 **http://localhost:8000** 访问仪表板。
```
# Run the test suite
pytest tests/ -q
```
如需使用可选的 AI 高级功能（LLM 摘要、RAG、SetFit），请安装额外的要求：
```
pip install -r requirements-ai.txt
```
## 📂 项目结构
```
app/
├── api/ # FastAPI routers (incidents, dashboard, search, graph, RAG, admin, websocket)
├── services/ # Intelligence engine — collector, classifier, NER, predictor, RAG, summarizer
├── models/ # SQLAlchemy ORM models (news, intelligence, OSINT, audit, reports)
├── repositories/ # Data-access layer with reusable query filters
├── core/ # Config, database, caching, security, realtime, logging
├── workers/ # Background sync manager
└── utils/ # India geo-resolution, location data, text utilities
alembic/ # Database schema migrations
scripts/ # Maintenance, data-cleaning, and training utilities
tests/ # pytest suite (81 tests)
docs/ # Architecture diagrams and documentation
```
