广东省自然村机器学习项目 (Guangdong Province Natural Villages Machine Learning Project)
本项目专注于广东省自然村数据的统计分析和机器学习建模，包含 285,000+ 自然村的地理坐标、行政区划、语言分布等信息。
主要功能：
- 字符频率统计与区域倾向性分析
- 语义标注与共现网络分析
- 空间分布模式与热点检测
- 聚类分析与命名模式识别
- N-gram 模式提取与语义组合分析
📖 想了解完整功能？ 查看 功能总览文档（6300+ 行详细说明）
系统要求：
- Python 3.8+ （推荐 3.10+）
- 2GB+ 可用内存
- 5GB+ 磁盘空间
安装依赖：
# 克隆项目后，进入项目目录
cd villages-ML
# 创建虚拟环境（推荐）
python -m venv venv
# 激活虚拟环境
# Windows (Git Bash):
source venv/Scripts/activate
# Linux/Mac:
source venv/bin/activate
# 安装依赖包
pip install -r requirements.txt确认数据库文件存在：
# 检查数据库文件
ls -lh data/villages.db
# 应该看到一个 2GB+ 的文件
# 如果文件不存在或太小，请联系项目维护者获取完整数据库Phase 0 会创建预处理表 广东省自然村_预处理，所有其他阶段都依赖这个表。
# 第一步：运行数据预处理（必须！）
python run_all_phases.py --phases 0
# 第二步：查看所有可用阶段
python run_all_phases.py --list
# 第三步：运行核心分析阶段（Phase 0-7，约 30-50 分钟）
python run_all_phases.py --group core
# 或者运行所有 15 个阶段（约 1-2 小时）
python run_all_phases.py --all# 查询分析结果
python scripts/query_results.py --list-runs
# 查看全局字符频率（前 20 个）
python scripts/query_results.py --run-id <run_id> --type global --top 20# 查看所有阶段
python run_all_phases.py --list
# 查看某个阶段的详细信息
python run_all_phases.py --info 12
# 预览执行计划（不实际运行）
python run_all_phases.py --all --dry-run
# 运行特定阶段
python run_all_phases.py --phases 0,1,2,3
# 运行阶段组
python run_all_phases.py --group core # 核心阶段 (0-7)
python run_all_phases.py --group statistical # 统计阶段 (8-10)
python run_all_phases.py --group advanced # 高级阶段 (11-17)
# 单独执行数据库维护并压缩数据库（ANALYZE + optimize + VACUUM）
python run_all_phases.py --vacuum
# 运行阶段结束后额外压缩数据库（VACUUM）
python run_all_phases.py --phases 13 --vacuum
python run_all_phases.py --all --vacuumrun_all_phases.py 每次实际执行阶段后，默认会在最后运行一次轻量数据库维护：
ANALYZEPRAGMA optimize
--vacuum 有两种用法：
# 1. 单独使用：不运行任何分析阶段，只执行 ANALYZE / optimize / VACUUM
python run_all_phases.py --vacuum
# 2. 和执行模式组合：阶段结束后执行 ANALYZE / optimize / VACUUM
python run_all_phases.py --phases 13 --vacuum
python run_all_phases.py --all --vacuum如果只是想预览执行计划，--dry-run 不会执行数据库维护，也不会执行 VACUUM：
python run_all_phases.py --all --dry-run --vacuum注意：VACUUM 会重建 SQLite 数据库文件，耗时更久，并且需要额外磁盘空间；通常只在大量删除表、清理旧结果、或需要压缩数据库文件时使用。
项目包含 18 个分析阶段，分为三组：
核心阶段 (Phase 0-6) - 必需的基础分析：
| Phase | 名称 | 说明 | 时间 |
|---|---|---|---|
| 0 | 数据预处理 | 2-5 min | |
| 1 | 字符嵌入 | Word2Vec 训练（9,209 字符，100 维） | 5-10 min |
| 2 | 频率分析 | 字符频率与区域倾向性统计（含 Z-score） | 3-5 min |
| 3 | 语义分析 | VTF（9 类别）+ 语义指数，输出 semantic_vtf_global + semantic_indices | 3-5 min |
| 4 | 空间分析 | 多分辨率空间聚类 + spatial_tendency_integration（ |
25-50 min |
| 5 | 特征工程 | 提取 230+ 特征 | 3-5 min |
| 6 | 聚类分析 | 3-5 min |
注：Phase 7 特征物化 |
⚠️ 已废弃 - 被实时 SQL 替代 | <1 min |
统计阶段 (Phase 10) - 统计显著性检验：
| Phase | 名称 | 说明 | 时间 |
|---|---|---|---|
| 10 | 显著性检验 | Chi-square、p-value、效应量 | 2-3 min |
注：Phase 8（倾向性分析）和 Phase 9（Z-score 标准化）已合并到 Phase 2。
高级阶段 (Phase 11-17) - 可选的深度分析：
| Phase | 名称 | 说明 | 时间 |
|---|---|---|---|
| 11 | 查询策略 | <1 min | |
| 12 | N-gram 分析 | 提取 1,909,959 个模式 | 5-10 min |
| 13 | 空间热点 | 热点检测（8 个热点） | 2-3 min |
| 14 | 语义组合 | 语义组合模式（8 种） | 3-5 min |
| 15 | 区域相似度 | 区域命名相似度分析 | 2-3 min |
| 16 | 语义中心性 | <1 min | |
| 17 | 混合分析 | 子类别 VTF（76 子类），输出 semantic_subcategory_vtf_global/regional | 3-5 min |
| 18 | 形态模式分析 | 提取后缀/前缀模式，输出 pattern_frequency_global 和 pattern_regional_analysis | 3-5 min |
完整运行时间：约 1-2 小时（全部 18 个阶段）
⚠️ Phase 4 依赖说明: Phase 4 的--integrate-tendency步骤生成spatial_tendency_integration表，其中character_category列需要从semantic_subcategory_labels表读取字符→语义类别映射。但该表由 Phase 14（语义组合）创建，而 Phase 4 的依赖链仅含 Phase 0 和 Phase 2（semantic_subcategory_labels尚未存在）。因此首次按序运行时，character_category列为 NULL。建议在 Phase 14 完成后单独重跑 Phase 4 以回填字符类别数据：python run_all_phases.py --phases 4
-
📖 功能总览（最详细）：docs/FEATURE_OVERVIEW.md ⭐
- 6300+ 行完整文档
- 系统架构、前后端技术栈
- 7 大功能模块详解（搜索、字符、语义、空间、模式、区域、ML）
- 30+ API 端点完整说明
- 数据库架构、算法详情
- 推荐：想深入了解项目的所有功能，从这里开始！
-
🚀 运行指南：docs/RUN_ALL_PHASES_GUIDE.md
- 如何使用
run_all_phases.py - 17 个分析阶段详解
- 命令行参数说明
- 常见问题解答
- 如何使用
- 项目状态报告：docs/reports/PROJECT_STATUS.md
- API 参考文档：docs/frontend/API_REFERENCE.md
- 文档索引：docs/README.md
所有预处理常量集中在 src/preprocessing/constants.py 中：
# 行政分隔符
DELIMITERS = ["社区", "村", "寨", "片", "管区", "农场", "区"]
# 方位和大小修饰词
MODIFIERS = ["大", "小", "新", "老", "東", "西", "南", "北", "上", "下"]
# 同音字映射
HOMOPHONE_PAIRS = {
"湖下": ["湖厦", "湖夏"],
"石": ["时"],
}修改这些常量后，重新运行 Phase 0 即可应用新配置：
python run_all_phases.py --phases 0项目使用 SQLite 数据库 (data/villages.db)，包含 50 个表：
原始数据表：
广东省自然村：原始村庄数据（285K+ 记录）广东省自然村_预处理：预处理后的数据（Phase 0 生成）
分析结果表（部分）：
char_frequency_global/char_regional_analysis：字符频率与区域分析semantic_vtf_global：语义虚拟词频village_features：村庄级特征（230+ 维）spatial_clusters：多分辨率空间聚类结果village_cluster_assignments：每村聚类分配（Phase 4 产出，后端 /village/complete 依赖）cluster_assignments/cluster_profiles：区县聚类结果ngram_frequency：N-gram 频率region_similarity：区域相似度矩阵- 更多表请参考 docs/reports/DATABASE_STATUS_REPORT.md
villages-ML/
├── data/ # SQLite 数据库
├── scripts/ # 分析脚本
│ ├── core/ # 核心阶段脚本 (Phase 0-18)
│ └── experimental/ # 实验性功能
├── src/ # 源代码模块
│ ├── preprocessing/ # 数据预处理
│ ├── analysis/ # 分析算法
│ ├── clustering/ # 聚类算法
│ └── data/ # 数据访问层
├── docs/ # 文档
├── api/ # FastAPI 后端（30+ 端点）
├── tests/ # 单元测试
├── run_all_phases.py # 主执行脚本
└── requirements.txt # Python 依赖
项目包含 Claude Code 自定义技能（.claude/skills/）：
/tendency-analysis：倾向性分析技能- 在 Claude Code CLI 中使用
/skill-name调用
以下是项目的高级功能，适合深入研究和定制化分析。
# 列出所有运行记录
python scripts/query_results.py --list-runs
# 查询全局字符频率（前 20 个）
python scripts/query_results.py --run-id <run_id> --type global --top 20
# 查询特定区域的字符频率
python scripts/query_results.py --run-id <run_id> --type regional --level city --region 广州市 --top 20
# 查询字符的区域倾向性
python scripts/query_results.py --run-id <run_id> --type char-tendency --char 村 --level city
# 导出结果到 CSV
python scripts/query_results.py --run-id <run_id> --type global --top 100 --output results.csvimport sqlite3
from src.data.db_query import (
get_latest_run_id,
get_global_frequency,
get_regional_frequency,
get_char_tendency_by_region
)
# 连接数据库
conn = sqlite3.connect('data/villages.db')
# 获取最新运行 ID
run_id = get_latest_run_id(conn)
# 查询全局频率
df = get_global_frequency(conn, run_id, top_n=20)
print(df)
# 查询字符跨城市倾向性
df = get_char_tendency_by_region(conn, run_id, '村', 'city')
print(df)
conn.close()除了使用 run_all_phases.py，你也可以单独运行特定的分析脚本：
# 形态学分析
python scripts/run_morphology_analysis.py --run-id morph_001
# 村级聚类（MiniBatchKMeans）
python scripts/run_village_clustering.py --db-path data/villages.db --output-dir results/clustering --k 50
# DBSCAN 聚类（异常检测）
python scripts/run_dbscan_clustering.py --db-path data/villages.db --output-dir results/dbscan --eps 0.5
# GMM 聚类（软聚类）
python scripts/run_gmm_clustering.py --db-path data/villages.db --output-dir results/gmm --n-components 50
# 聚类可视化
python scripts/visualize_clusters.py --db-path data/villages.db --cluster-file results/clustering/village_clusters.csv --output-dir results/viz全局高频字符（前 10）：
- 村 (87,919 次，30.76%)
- 新 (45,123 次，15.82%)
- 大 (38,456 次，13.47%)
- 坑 (35,789 次，12.54%)
- ...
珠三角地区特征字符：
- 涌（Lift: 8.5）- 水系相关
- 围（Lift: 6.2）- 聚落形态
- 塘（Lift: 4.8）- 水系相关
山区特征字符：
- 坑（Lift: 7.3）- 地形相关
- 岭（Lift: 5.9）- 地形相关
- 坳（Lift: 4.5）- 地形相关
| 语义类别 | 村庄数量 | 百分比 |
|---|---|---|
| settlement（聚落） | 87,919 | 30.76% |
| direction（方位） | 77,069 | 26.96% |
| mountain（山地） | 75,030 | 26.25% |
| water（水系） | 47,324 | 16.55% |
| clan（姓氏） | 29,599 | 10.35% |
项目实现了"离线重、在线轻"的部署策略：
离线阶段（无性能限制）：
- 运行所有 17 个分析阶段
- 预计算所有特征和统计结果
- 存储到数据库
在线阶段（2 核 / 2GB 服务器）：
- 仅加载预计算结果
- 强制查询限制（最大 500-5000 行）
- 禁止全表扫描
- 支持分页查询
# 启动 FastAPI 服务器
bash start_api.sh
# 或手动启动
cd api
uvicorn main:app --host 0.0.0.0 --port 8000API 文档：访问 http://localhost:8000/docs
# 运行所有测试
pytest
# 运行带覆盖率的测试
pytest --cov=src tests/
# 运行特定测试
pytest tests/test_preprocessing.py- ✅ 后端对接修复：补齐 4 张缺失表（semantic_regional_analysis, pattern_frequency_global, pattern_regional_analysis, spatial_tendency_integration）
- ✅ spatial_tendency_integration 增加 6 列（character_category, global_tendency_mean, tendency_deviation, spatial_specificity, p_value, u_statistic）满足后端 API
⚠️ character_category 依赖 Phase 14 的 semantic_subcategory_labels 表，Phase 4 首次运行该列为 NULL，Phase 14 后需重跑 Phase 4 回填- ✅ 修复 Phase 4 依赖链（新增 Phase 2 依赖）和 Phase 6 表名引用
- ✅ 删除 6 张已废弃的空表（char_frequency_regional, regional_tendency 等优化前旧表）
- ✅ 新增 tendency_significance 索引 + semantic_regional_analysis 索引
- ✅ 完善 README.md，添加"第一次使用"指南
- ✅ 优化文档结构，突出快速开始部分
- ✅ 数据库优化：从 5.45GB 减少到 2.3GB（58% 减少）
- ✅ 移除 run_id 冗余，合并频率+倾向性表
- ✅ 添加 17 个索引优化查询性能
- ✅ 实现在线服务策略框架（Phase 11）
- ✅ 实现特征物化管道（Phase 10）
- ✅ 实现村级聚类分析（MiniBatchKMeans, DBSCAN, GMM）
- ✅ 实现 UMAP 可视化
- ✅ 实现形态学模式分析功能
- ✅ 添加 N-gram 分析（Phase 12）
- ✅ 添加空间热点检测（Phase 13）
- ✅ 实现语义分析管道（Phase 3）
- ✅ 实现形态学分析管道
- ✅ 添加 9 个语义类别的虚拟词频（VTF）分析
- ✅ 实现字符频率分析管道（Phase 2）
- ✅ 实现区域倾向性分析
- ✅ 添加数据库持久化功能
欢迎贡献！请遵循以下步骤：
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
TBD
如有问题或建议，请：
- 提交 Issue
- 查看完整功能文档：docs/FEATURE_OVERVIEW.md ⭐（最详细）
- 查看文档索引：docs/README.md
- 参考运行指南：docs/RUN_ALL_PHASES_GUIDE.md
感谢所有为广东省自然村数据收集和整理做出贡献的人员。
📦 详细功能列表（点击展开）
# Run frequency analysis pipeline
python scripts/run_frequency_analysis.py --run-id run_003
# Results will be saved to results/run_003/Analysis results are automatically persisted to the SQLite database in the following tables:
analysis_runs: Run metadata and configurationchar_frequency_global: Global character frequency statisticschar_frequency_regional: Regional character frequency (city/county/township levels)regional_tendency: Regional tendency analysis (lift, log-odds, z-score)tendency_significance: Statistical significance testing (p-values, effect sizes, confidence intervals) ✨ NEW
The system now includes statistical significance testing to identify meaningful regional naming patterns:
# Initialize database tables
python scripts/init_tendency_tables.py
# Run analysis with significance testing
python scripts/test_significance.py
# Query significant patterns
python scripts/query_tendency.py --run-id test_sig_1771260439 --significant-only
# Filter by effect size
python scripts/query_tendency.py --run-id test_sig_1771260439 --min-effect-size 0.1
# Export to CSV
python scripts/query_tendency.py --run-id test_sig_1771260439 --output results.csvFeatures:
- Chi-square test for character-region associations
- P-values and significance levels (***, **, *, ns)
- Effect sizes (Cramér's V) for measuring association strength
- 95% confidence intervals (Wilson score method)
- Fast computation: 27,000+ tests in ~3 seconds
Documentation: See docs/TENDENCY_SIGNIFICANCE_GUIDE.md for complete usage guide.
Use the query script to retrieve analysis results from the database:
# List all analysis runs
python scripts/query_results.py --list-runs
# Query global frequency (top 20 characters)
python scripts/query_results.py --run-id run_002 --type global --top 20
# Query regional frequency for a specific region
python scripts/query_results.py --run-id run_002 --type regional --level city --region 广州市 --top 20
# Query character tendency across regions
python scripts/query_results.py --run-id run_002 --type char-tendency --char 村 --level city
# Query region tendency profile (most characteristic characters)
python scripts/query_results.py --run-id run_002 --type region-profile --level city --region 广州市 --top 20
# Query top polarized characters (highest absolute tendency)
python scripts/query_results.py --run-id run_002 --type polarized --level city --top 20
# Save results to CSV
python scripts/query_results.py --run-id run_002 --type global --top 100 --output results.csvYou can also use the Python query API directly:
import sqlite3
from src.data.db_query import (
get_latest_run_id,
get_global_frequency,
get_regional_frequency,
get_char_tendency_by_region,
get_top_polarized_chars,
get_region_tendency_profile
)
# Connect to database
conn = sqlite3.connect('data/villages.db')
# Get latest run
run_id = get_latest_run_id(conn)
# Query global frequency
df = get_global_frequency(conn, run_id, top_n=20)
print(df)
# Query character tendency across cities
df = get_char_tendency_by_region(conn, run_id, '村', 'city')
print(df)
conn.close()形态学分析提取并分析村名中的结构模式，包括：
- 后缀模式：末尾1、2或3个字符（例如：村、新村、老围村）
- 前缀模式：开头2或3个字符（例如：新X、老X、大X）
这揭示了命名惯例、区域模式和功能性形态学规律（例如：水系相关后缀 vs 地形相关后缀）。
# 使用默认设置运行形态学分析
python scripts/run_morphology_analysis.py --run-id morph_001
# 自定义后缀和前缀长度
python scripts/run_morphology_analysis.py --run-id morph_002 \
--suffix-lengths 1,2,3 \
--prefix-lengths 2,3
# 结果将保存到 results/morph_001/形态学分析结果持久化到以下数据表：
pattern_frequency_global：全局模式频率统计pattern_regional_analysis：区域模式频率与倾向性分析（合并表，市/县/镇三级）
# 查询全局 suffix_1 频率（前20个模式）
python scripts/query_results.py --run-id morph_001 --type pattern-global \
--pattern-type suffix_1 --top 20
# 查询特定区域的区域后缀模式
python scripts/query_results.py --run-id morph_001 --type pattern-regional \
--pattern-type suffix_1 --level city --region 珠海市 --top 20
# 查询模式跨区域倾向性
python scripts/query_results.py --run-id morph_001 --type pattern-tendency \
--pattern-type suffix_1 --pattern 涌 --level city
# 查询区域特征模式
python scripts/query_results.py --run-id morph_001 --type pattern-profile \
--pattern-type suffix_1 --level city --region 佛山市 --top 20
# 查询最极化模式
python scripts/query_results.py --run-id morph_001 --type pattern-polarized \
--pattern-type suffix_1 --level city --top 20import sqlite3
from src.data.db_query import (
get_pattern_frequency_global,
get_pattern_frequency_regional,
get_pattern_tendency_by_region,
get_top_polarized_patterns,
get_region_pattern_profile
)
# 连接数据库
conn = sqlite3.connect('data/villages.db')
# 查询全局 suffix_1 频率
df = get_pattern_frequency_global(conn, 'morph_001', 'suffix_1', top_n=20)
print(df)
# 查询模式跨城市倾向性
df = get_pattern_tendency_by_region(conn, 'morph_001', 'suffix_1', '涌', 'city')
print(df)
# 查询区域特征后缀模式
df = get_region_pattern_profile(conn, 'morph_001', 'suffix_1', 'city', '珠海市', top_n=20)
print(df)
conn.close()形态学分析揭示：
- 三角洲地区：涌、围、塘等水系相关后缀高频出现
- 山区：坑、岭、坳等地形相关后缀高频出现
- 城乡差异：命名多样性模式不同
- 历史模式：老村、新村、大村、小村的分布规律
- 功能性形态学：系统性的区域差异
新增模块：
-
src/preprocessing/morphology_extractor.py- 形态学特征提取- 后缀模式提取：suffix_1（末1字）、suffix_2（末2字）、suffix_3（末3字）
- 前缀模式提取：prefix_2（首2字）、prefix_3（首3字）
- 支持可配置n-gram长度
-
src/analysis/morphology_frequency.py- 形态学频率分析- 全局模式频率计算
- 区域模式频率计算（市/县/镇三级）
- Lift值计算（区域倾向性度量）
-
src/pipelines/morphology_pipeline.py- 形态学分析管道- 端到端工作流编排
- 支持5种模式类型并行分析
- 自动生成分析报告
数据库扩展：
- 新增表：
pattern_frequency_global- 全局模式频率 - 新增表：
pattern_frequency_regional- 区域模式频率 - 新增表：
pattern_tendency- 区域模式倾向性 - 新增索引：优化模式类型、区域层级、模式查询性能
查询接口扩展（db_query.py）：
get_pattern_frequency_global()- 查询全局模式频率get_pattern_frequency_regional()- 查询区域模式频率get_pattern_tendency_by_region()- 查询模式跨区域倾向性get_top_polarized_patterns()- 查询最极化模式get_region_pattern_profile()- 查询区域特征模式
CLI工具：
scripts/run_morphology_analysis.py- 运行形态学分析scripts/test_morphology.py- 功能验证测试
统计方法：
- 复用字频分析统计框架
- Lift（倾向性比值）、Log-odds（对数几率）、Z-score（显著性检验）
- 支持最小支持度过滤（min_global_support, min_regional_support）
分析价值：
- 揭示水系后缀（涌、围、塘、沙）在珠三角地区的高频分布规律
- 揭示地形后缀（坑、岭、坳、寨）在山区的高频分布规律
- 识别历史命名模式（新村、老村、大村、小村）的区域差异
- 量化城乡命名多样性差异（熵值分析）
- 发现功能性形态学规律（如X涌 vs X坑的地理分布差异）
性能特征：
- 数据规模：20万+自然村
- 运行时间：约2-3分钟（完整分析）
- 数据库增长：约150-250MB/次运行
- 模式类型：5种（suffix_1/2/3, prefix_2/3）
- 区域层级：3级（市/县/镇）
聚类分析基于语义和形态学特征对区域进行分组，揭示广东省村名的深层模式。该系统使用KMeans算法对县级/市级/镇级区域进行聚类，生成可解释的聚类画像。
# 运行县级聚类分析
python scripts/run_clustering_analysis.py \
--semantic-run-id semantic_001 \
--morphology-run-id morph_001 \
--output-run-id cluster_001 \
--region-level county聚类分析结果持久化到以下数据表：
cluster_assignments：区域聚类分配结果cluster_profiles：聚类画像（区分性特征、代表性区域）clustering_metrics：聚类评估指标（轮廓系数、DB指数等）
# 查询聚类分配
python scripts/query_results.py --run-id cluster_001 --type cluster-assignments
# 查询特定聚类的画像
python scripts/query_results.py --run-id cluster_001 --type cluster-profile --cluster-id 0
# 查询聚类评估指标
python scripts/query_results.py --run-id cluster_001 --type cluster-metrics新增功能： 实现三种互补的村级聚类方法
新增脚本：
-
scripts/run_dbscan_clustering.py- DBSCAN聚类（异常检测）- 基于密度的聚类算法
- 自动识别噪声点（异常村名）
- 无需预先指定聚类数量
- 支持任意形状的聚类
-
scripts/run_gmm_clustering.py- GMM聚类（软聚类）- 高斯混合模型
- 提供概率分布（每个村庄属于各聚类的概率）
- 不确定性量化（识别命名模式模糊的村庄）
- 支持多种协方差类型（full, tied, diag, spherical）
-
scripts/visualize_clusters.py- 聚类可视化- UMAP降维至2D空间
- 生成聚类散点图
- 支持PCA降维作为备选方案
- 导出2D坐标数据
分析价值：
- DBSCAN：识别独特/罕见村名（噪声点），揭示文化异常点
- GMM：量化命名模式的不确定性，识别文化/语言边界村庄
- 可视化：直观展示聚类质量，发现子聚类和过渡区域
性能特征：
- 数据规模：284,764个自然村
- 特征维度：106维 → PCA降至50维
- 运行时间：DBSCAN约3-5分钟，GMM约5-8分钟，UMAP约10-15分钟
- 内存占用：< 2GB（符合部署约束）
方法对比：
- MiniBatchKMeans（已有）：快速、硬聚类、需指定k
- DBSCAN（新增）：异常检测、无需指定k、基于密度
- GMM（新增）：软聚类、概率分布、不确定性量化
新增功能： 实现区域级聚类分析系统
新增模块：
src/clustering/feature_builder.py- 区域特征构建器（语义+形态学+多样性特征）src/clustering/clustering_engine.py- KMeans聚类引擎src/clustering/cluster_profiler.py- 聚类画像生成器src/pipelines/clustering_pipeline.py- 聚类分析管道
新增表：
cluster_assignments- 聚类分配cluster_profiles- 聚类画像clustering_metrics- 聚类评估指标
新增脚本：
scripts/run_clustering_analysis.py- 运行聚类分析
支持粒度： 市级、县级、鎮级聚类
性能： 121个县区，230维特征，运行时间约3-5秒，最佳k=4（轮廓系数0.62）
村级聚类直接对284,764个自然村进行聚类分析，提供三种互补的聚类方法：
- MiniBatchKMeans：快速聚类，适合大规模数据
- DBSCAN：基于密度的聚类，自动识别异常村名（噪声点）
- GMM：软聚类，提供概率分布和不确定性量化
# 运行MiniBatchKMeans聚类（k=50）
python scripts/run_village_clustering.py \
--db-path data/villages.db \
--output-dir results/village_clustering \
--k 50 \
--batch-size 10000 \
--pca-components 50
# 结果保存在 results/village_clustering/
# - village_clusters.csv: 聚类分配结果
# - cluster_statistics.csv: 聚类统计信息# 运行DBSCAN聚类
python scripts/run_dbscan_clustering.py \
--db-path data/villages.db \
--output-dir results/dbscan_clustering \
--eps 0.5 \
--min-samples 10 \
--pca-components 50
# 结果保存在 results/dbscan_clustering/
# - village_clusters_dbscan.csv: 聚类分配结果
# - noise_points.csv: 异常村名（噪声点）
# - cluster_statistics.csv: 聚类统计信息DBSCAN优势：
- 自动识别异常村名（label=-1）
- 无需预先指定聚类数量
- 发现任意形状的聚类
- 基于密度的聚类，更符合地理分布特征
# 运行GMM聚类
python scripts/run_gmm_clustering.py \
--db-path data/villages.db \
--output-dir results/gmm_clustering \
--n-components 50 \
--covariance-type full \
--pca-components 50
# 结果保存在 results/gmm_clustering/
# - village_clusters_gmm.csv: 聚类分配结果（含概率分布）
# - uncertain_villages.csv: 命名模式模糊的村庄
# - cluster_statistics.csv: 聚类统计信息GMM优势：
- 软聚类：提供每个村庄属于各聚类的概率
- 不确定性量化：识别命名模式模糊的村庄
- 灵活的聚类形状：可以建模椭圆形聚类
- 概率基础：有明确的统计假设
# 使用UMAP可视化聚类结果
python scripts/visualize_clusters.py \
--db-path data/villages.db \
--cluster-file results/village_clustering/village_clusters.csv \
--output-dir results/visualization \
--method umap
# 或使用PCA可视化
python scripts/visualize_clusters.py \
--db-path data/villages.db \
--cluster-file results/dbscan_clustering/village_clusters_dbscan.csv \
--output-dir results/visualization_dbscan \
--method pca
# 结果保存在 results/visualization/
# - villages_2d.csv: 2D坐标数据
# - cluster_visualization.png: 聚类散点图村级聚类使用以下特征：
-
基础特征：
name_length：村名长度
-
后缀特征（独热编码）：
suffix_1：末尾1个字符（例如：村、坑、围）suffix_2：末尾2个字符（例如：新村、老围）- 保留前50个最常见后缀
-
语义特征（二元指标）：
sem_mountain：山地相关（山、岭、坑、岗、峰、坳）sem_water：水系相关（水、河、江、湖、塘、涌、沙、洲）sem_direction：方位相关（东、西、南、北、中、上、下、前、后）sem_settlement：聚落相关（村、庄、寨、围、堡、屯）sem_clan：姓氏相关（陈、李、王、张、刘、黄、林、吴、周、郑）
特征矩阵维度：约106维（1个基础特征 + 5个语义特征 + 100个后缀特征）
预处理：
- StandardScaler标准化
- PCA降维至50维（可选）
村级聚类揭示：
MiniBatchKMeans发现：
- Cluster 17（8.8%）："村"后缀村庄
- Cluster 41（4.7%）："坑"后缀村庄（山地地形）
- Cluster 12（2.2%）："围"后缀村庄（珠三角水乡）
- Cluster 5（3.5%）：水系相关村庄（涌、塘、沙）
DBSCAN发现：
- 核心聚类：常见命名模式（村、坑、围等）
- 边界点：过渡性命名模式
- 噪声点：独特/罕见村名（潜在文化意义）
GMM发现：
- 高概率村庄：典型命名模式
- 低概率村庄：混合命名模式（例如：同时包含山地和水系特征）
- 高熵村庄：命名模式模糊，可能位于文化/语言边界
- 数据规模：284,764个自然村
- 运行时间：
- MiniBatchKMeans：约2分钟
- DBSCAN：约3-5分钟
- GMM：约5-8分钟
- UMAP可视化：约10-15分钟
- 内存占用：< 2GB（符合部署约束）
- 特征维度：106维 → PCA降至50维
⚠️ city_aggregates、county_aggregates、town_aggregates已废弃，被实时 SQL 查询替代（广东省自然村GROUP BY +semantic_indices关联）。
村庄级特征（village_features 表）由 Phase 5 生成，包含 230+ 特征。
import sqlite3
from src.data.db_query import (
get_village_features,
get_villages_by_semantic_tag,
get_villages_by_suffix,
get_villages_by_cluster,
get_region_aggregates,
get_semantic_tag_statistics
)
conn = sqlite3.connect('data/villages.db')
# 查詢特定區域的村莊特徵
df = get_village_features(conn, run_id='feature_001', city='广州市', limit=100)
# 查詢包含山地特徵的村莊
df = get_villages_by_semantic_tag(conn, run_id='feature_001', semantic_category='mountain', limit=100)
# 查詢以"村"結尾的村莊
df = get_villages_by_suffix(conn, run_id='feature_001', suffix='村', suffix_length=1, limit=100)
# 查詢特定聚類中的村莊
df = get_villages_by_cluster(conn, run_id='feature_001', cluster_id=17, algorithm='kmeans', limit=100)
# 查詢縣級聚合統計
df = get_region_aggregates(conn, run_id='feature_001', region_level='county')
# 查詢全局語義標籤統計
df = get_semantic_tag_statistics(conn, run_id='feature_001')
conn.close()- 數據規模：284,764個自然村
- 運行時間：約67秒（~1分鐘）
- 內存占用：< 1GB
基於feature_001運行結果：
| 語義類別 | 村莊數量 | 百分比 |
|---|---|---|
| settlement（聚落） | 87,919 | 30.76% |
| direction（方位） | 77,069 | 26.96% |
| mountain（山地） | 75,030 | 26.25% |
| water（水系） | 47,324 | 16.55% |
| clan（姓氏） | 29,599 | 10.35% |
| symbolic（象徵） | 24,886 | 8.71% |
| vegetation（植被） | 21,092 | 7.38% |
| agriculture（農業） | 20,356 | 7.12% |
| infrastructure（基建） | 6,748 | 2.36% |
在線服務策略框架確保查詢在2核/2GB部署環境中安全執行，防止內存耗盡和性能問題。
- 查詢驗證：阻止全表掃描和昂貴操作
- 行數限制：強制執行最大行數限制
- 分頁支持：提供高效的分頁查詢
- 配置管理：支持生產/開發環境配置
生產模式（Production）：
- 最大行數：500（默認）/ 5,000（絕對上限）
- 全表掃描：禁用
- 運行時聚類：禁用
- 查詢超時：3秒
- 內存限制：300MB
開發模式（Development）：
- 最大行數：10,000（默認）/ 50,000（絕對上限）
- 全表掃描：允許
- 運行時聚類：禁用
- 查詢超時：10秒
- 內存限制：1GB
默認模式（Default）：
- 最大行數：1,000（默認）/ 10,000（絕對上限）
- 全表掃描：禁用
- 運行時聚類：禁用
- 查詢超時：5秒
- 內存限制：500MB
# 使用默認配置
python scripts/query_results.py --run-id feature_001 --type global --top 20
# 使用生產配置（嚴格限制）
python scripts/query_results.py --run-id feature_001 --type global --top 20 --config production
# 使用開發配置（寬鬆限制）
python scripts/query_results.py --run-id feature_001 --type global --top 20 --config development
# 自定義最大行數
python scripts/query_results.py --run-id feature_001 --type global --top 20 --max-rows 500
# 允許全表掃描（不推薦用於生產環境）
python scripts/query_results.py --run-id feature_001 --type global --top 20 --enable-full-scanimport sqlite3
from src.deployment import QueryPolicy, DeploymentConfig, SafeQueryExecutor, PolicyViolationError
from src.data.db_query import get_village_features
conn = sqlite3.connect('data/villages.db')
# 使用生產配置
config = DeploymentConfig.production()
policy = QueryPolicy(
max_rows=config.max_rows_default,
max_rows_absolute=config.max_rows_absolute,
enable_full_scan=config.enable_full_scan
)
executor = SafeQueryExecutor(conn, policy)
# 執行安全查詢
try:
result = executor.execute(
get_village_features,
run_id='feature_001',
city='广州市',
limit=100
)
print(f"查詢成功，返回 {len(result)} 行")
except PolicyViolationError as e:
print(f"查詢被阻止：{e}")
# 使用分頁查詢
results, total, has_next = executor.execute_with_pagination(
get_village_features,
run_id='feature_001',
city='广州市',
page=1,
page_size=50
)
print(f"第1頁：{len(results)} 行，總計 {total} 行，有下一頁：{has_next}")
conn.close()阻止的操作：
- 無過濾條件的全表掃描（除非明確啟用）
- 超過絕對上限的行數請求（10倍於絕對上限）
- 運行時聚類操作（必須使用預計算的cluster_id）
允許的過濾條件：
- city（城市）
- county（縣區）
- town（鄉鎮）
- cluster_id（聚類ID）
- semantic_category（語義類別）
- suffix（後綴）
- algorithm（算法）
注意：run_id不被視為有效過濾條件，因為它不能限制結果集大小。
# 運行策略測試
python scripts/test_query_policy.py
# 預期輸出：
# [Test 1] 配置加載 - [OK]
# [Test 2] 帶過濾條件的查詢 - [OK]
# [Test 3] 無過濾條件的查詢 - [OK]（被阻止）
# [Test 4] 超過上限的查詢 - [OK]（自動限制）
# [Test 5] 分頁支持 - [OK]
# [Test 6] 允許全表掃描 - [OK]配置文件位於 config/ 目錄：
deployment.json：默認配置deployment.production.json：生產環境配置deployment.development.json：開發環境配置
可以根據需要自定義配置文件。
- 新增功能：在線服務策略框架（Phase 11）
- 實現模塊：
- 查詢策略（query_policy.py）
- 配置管理（config.py）
- 安全查詢執行器（query_wrapper.py）
- 新增配置：3個部署配置文件（default/production/development）
- 更新模塊：為db_query.py添加offset參數支持
- CLI集成：為query_results.py添加策略標誌
- 測試腳本：test_query_policy.py
- 新增功能：特徵物化管道（Phase 10）
- 實現模塊：
- 特徵提取器（feature_extractor.py）
- 物化管道（feature_materialization_pipeline.py）
- 區域聚合（region_aggregation.py）
- 新增表：village_features, city_aggregates, county_aggregates, town_aggregates
- 新增腳本：run_feature_materialization.py
- 新增查詢函數：6個村莊特徵查詢函數
- 性能：67秒處理284K村莊，內存占用<1GB
- 實現村級聚類分析（MiniBatchKMeans, DBSCAN, GMM）
- 實現層次聚類分析
- 實現UMAP可視化
- 添加聚類分析腳本
- 實現語義分析管道（semantic_001）
- 實現形態學模式分析管道（morph_001）
- 添加9個語義類別的虛擬詞頻（VTF）分析
- 實現字符頻率分析管道（run_002）
- 實現區域傾向性分析
- 添加數據庫持久化功能
TBD