# GeoAI-Universal-Platform **Repository Path**: luodinglin/geo-ai-universal-platform ## Basic Information - **Project Name**: GeoAI-Universal-Platform - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 7 - **Created**: 2026-04-21 - **Last Updated**: 2026-04-21 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # GeoAI 通用平台 一个基于插件的通用地理空间人工智能平台，通过大语言模型（LLM）实现与地理数据的自然语言交互。采用 TypeScript 构建，提供 SDK 库和 REST API 服务器两种模式，支持灵活集成。 ## 🎯 愿景 GeoAI 通用平台通过利用大语言模型将自然语言查询转换为可执行的地理空间操作，弥合了复杂地理空间数据与直观用户交互之间的差距。该平台支持多种数据源、LLM 提供商和行业特定插件，服务于 GIS 分析师、开发人员和领域专业人士。 ![show](./examples/show_zh.gif) ### 核心价值主张 - **🤖 LLM 提供商无关性**：支持 Anthropic Claude、通义千问、Ollama、OpenAI 和自定义提供商，并可无缝切换 - **📊 多源数据集成**：查询本地文件（GeoJSON、Shapefile、CSV）、数据库（PostGIS）和 Web 服务（WFS、PostgREST） - **🔌 插件架构**：可扩展系统，包含水务、电网、交通等行业的特定插件 - **🔍 智能元数据发现**：使用 LLM 自动扫描模式并推断语义字段 - **🌐 自然语言界面**：将中英文普通查询转换为地理空间操作和可视化 - **⚡ 双模式运行**：作为 SDK 库或独立的 REST API 服务器使用 - **🔒 离线优先安全**：本地数据处理，安全的凭证管理，支持隔离网络部署 ## 🎯 开发理念：文档驱动开发（DDD） **本项目严格遵循 DDD（Documentation-Driven Development，文档驱动开发）方法论：** 1. **设计优先**：所有功能在实现前必须有详细的设计文档 2. **代码其次**：实现严格遵循已批准的设计规范 3. **测试第三**：全面的测试验证设计和实现 4. **持续文档化**：保持文档与代码更改同步 ### DDD 工作流程 ``` 需求 → 设计文档 → 评审 → 实现 → 测试 → 文档更新 ``` **设计文档位置：** [`docs/design/`](docs/design/) ## 🏗️ 架构 平台采用分层架构，关注点清晰分离： ``` ┌─────────────────────────────────────────────┐ │ 接口层 │ │ REST API / WebSocket / CLI / Web 演示 │ └──────────────────┬──────────────────────────┘ │ ┌──────────────────▼──────────────────────────┐ │ 核心引擎层 │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ GeoAgent │ │ 工具 │ │ LLM │ │ │ │ │ │ 注册中心 │ │ 管理器 │ │ │ └──────────┘ └──────────┘ └──────────┘ │ └──────────────────┬──────────────────────────┘ │ ┌──────────────────▼──────────────────────────┐ │ 数据与服务层 │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ 本地 │ │ 数据库 │ │ Web │ │ │ │ 文件 │ │(PostGIS) │ │ 服务 │ │ │ └──────────┘ └──────────┘ └──────────┘ │ └──────────────────┬──────────────────────────┘ │ ┌──────────────────▼──────────────────────────┐ │ 插件层 │ │ 行业工具 | 自定义扩展 │ └─────────────────────────────────────────────┘ ``` ### 设计模式 - **工厂模式**：LLM 提供商创建和配置 - **策略模式**：可插拔的数据源实现 - **观察者模式**：事件驱动的工具执行监控 - **依赖注入**：模块化服务组合 - **聚合根**：LLM 提供商生命周期管理 ## ✨ 主要特性 ### LLM 集成 - **多提供商支持**：通义千问、Ollama、Anthropic Claude、OpenAI GPT 和自定义提供商 - **动态配置**：运行时切换提供商和模型，无需更改代码 - **前端覆盖**：允许用户提供自己的 API 密钥和模型偏好 - **提供商缓存**：通过智能提供商实例缓存优化性能 - **安全凭证处理**：服务器端密钥保护与临时前端凭证 ### 数据源支持 - **本地文件**：GeoJSON、Shapefile (.shp/.shx/.dbf)、CSV、Excel，具有自动类型推断 - **数据库**：PostGIS，强制执行只读查询并防止 SQL 注入 - **Web 服务**：WFS（OGC 标准）、PostgREST，支持身份验证 - **自动发现**：基于 SQLite 的注册表和本地文件扫描器，实现零配置设置 - **统一接口**：所有源类型的一致 IDataSource API ### 地理空间能力 - **空间过滤**：通过 @turf/turf 提供 6 种空间操作（相交、包含、内部、接触、穿越、不相交） - **属性过滤**：丰富的查询运算符（=、!=、>、<、>=、<=、LIKE、IN） - **自然语言查询**：将中英文查询解析为结构化地理空间操作 - **自动可视化**：检测几何类型并在 Leaflet 地图上渲染点/多边形/线 - **元数据提取**：自动生成字段模式、示例值和空间范围 ### 安全与隐私 - **离线优先架构**：无需外部依赖即可在本地处理敏感地理数据 - **安全凭证管理**：服务器端密钥保护与临时前端凭证 - **只读数据库访问**：PostGIS 连接强制执行只读查询，防止 SQL 注入 - **隔离网络部署**：支持本地 LLM（Ollama），在隔离网络中完整运行 - **数据主权**：所有处理均在本地进行，确保对敏感数据的完全控制 ### 架构与可扩展性 - **SDK + 服务器模式**：作为库导入或作为独立 Express 服务器运行 - **插件系统**：行业特定工具扩展（水务、电力、交通） - **工具注册中心**：动态工具发现，具有 LLM 兼容的能力描述 - **事件系统**：用于工具执行跟踪和错误通知的观察者模式 - **类型安全**：完整的 TypeScript 覆盖和全面的类型定义 ## 📦 项目结构 ``` GeoAI-Universal-Platform/ ├── src/ │ ├── sdk/ # 核心 SDK 库 │ │ ├── core/ # GeoAgent, ToolRegistry │ │ ├── llm/ # LLM 提供商抽象 │ │ │ ├── providers/ # 通义千问, Ollama, Anthropic, OpenAI │ │ │ ├── ILlmProvider.ts # 提供商接口 │ │ │ └── LlmProviderFactory.ts │ │ ├── datasources/ # 数据源适配器 │ │ │ ├── local/ # GeoJSON, Shapefile, CSV, Excel │ │ │ ├── database/ # PostGIS │ │ │ ├── service/ # WFS, PostgREST │ │ │ └── DataSourceFactory.ts │ │ ├── metadata/ # MetadataDiscoveryService │ │ ├── task-framework/ # SmartDataFinder, TaskExecutor │ │ ├── tools/ # 地理空间和数据工具 │ │ ├── api-registry/ # ApiServiceProvider │ │ ├── types/ # TypeScript 定义 │ │ └── utils/ # 空间过滤器、环境助手 │ ├── server/ # Express REST API 服务器 │ │ ├── controllers/ # 请求处理器 │ │ │ ├── chat.controller.ts │ │ │ ├── datasource.controller.ts │ │ │ └── ... │ │ ├── routes/ # API 路由定义 │ │ ├── services/ # 业务逻辑 │ │ │ ├── LlmProviderManager.ts │ │ │ ├── ConfigValidator.ts │ │ │ ├── QueryParser.ts │ │ │ ├── DataExtractor.ts │ │ │ └── DatasourceRegistry.ts │ │ ├── middleware/ # Express 中间件 │ │ ├── app.ts # 应用配置 │ │ └── index.ts # 服务器入口点 │ └── index.ts # SDK 入口点 ├── examples/ │ └── web-demo/ # Vue.js 演示应用 │ ├── src/ │ │ ├── views/ # ChatView, DataSourceManager │ │ ├── components/ # MapView, LayerControl, LegendPanel │ │ ├── stores/ # Pinia stores (chat, datasource) │ │ └── api/ # API 客户端模块 │ └── package.json ├── docs/ │ ├── architecture/ # 高层设计文档 │ ├── design/ # 详细设计规范（DDD） │ ├── development/ # 实现指南和进度 │ └── references/ # 参考资料 ├── tests/ │ ├── unit/ # 单元测试 │ ├── integration/ # 集成测试 │ └── e2e/ # 端到端测试 ├── data/ │ ├── sources/ # 示例地理空间数据文件 │ └── registry.db # SQLite 数据源注册表 ├── dist/ # 编译输出 ├── .env # 环境变量 ├── .env.example # 配置模板 ├── package.json ├── tsconfig.json └── rollup.config.js ``` ## 🚀 快速开始 ### 前置要求 - Node.js >= 24.0.0 - npm 或 pnpm - （可选）PostgreSQL + PostGIS 用于数据库支持 - （可选）Ollama 用于本地 LLM 推理 ### 安装 ```bash # 克隆仓库 git clone cd GeoAI-Universal-Platform # 安装依赖 npm install # 构建项目 npm run build # 运行测试 npm test ``` ### 配置 ```bash # 复制环境模板 cp .env.example .env # 编辑 .env 文件，设置服务器参数 # 注意：LLM 配置现在通过 API/UI 完成，而非 .env PORT=3000 LOCAL_DATA_DIR=./data/sources ``` **LLM 配置（新方法）：** 启动服务器后，通过以下方式配置 LLM： 1. **API：** ```bash curl -X POST http://localhost:3000/api/v1/chat/configs \ -H "Content-Type: application/json" \ -d '{ "id": "my-qwen", "name": "我的通义千问配置", "config": { "provider": "qwen", "model": "qwen-plus", "apiKey": "your-api-key" } }' # 激活配置 curl -X POST http://localhost:3000/api/v1/chat/configs/my-qwen/activate ``` 2. **前端 UI：** - 打开 http://localhost:5173 - 点击"LLM 设置"按钮 - 输入您的配置 - 点击"应用" 3. **配置文件：** - 在 `data/llm-configs/` 中创建文件 - 详见 docs/design/17-multi-llm-config-design.md **从旧格式迁移：** 如果您有旧的 `data/llm-config.json` 文件： ```bash npx tsx scripts/migrate-llm-config.ts ``` 这将自动将其转换为新的多配置格式。 ### 模式 1：SDK 库使用 ```typescript import { GeoAgent, LlmProviderFactory, ToolRegistry, DataSourceFactory } from '@geoai/universal-platform'; // 创建 LLM 提供商 const llmProvider = LlmProviderFactory.create('qwen', { apiKey: 'your-api-key', model: 'qwen-plus' }); // 创建工具注册中心并注册工具 const toolRegistry = new ToolRegistry(); // 初始化 GeoAgent const agent = new GeoAgent(llmProvider, toolRegistry); // 处理自然语言查询 const response = await agent.processQuery( '显示所有人口超过 100 万的城市' ); console.log(response); ``` ### 模式 2：REST API 服务器 ```bash # 启动服务器 npm start # 或使用开发模式，支持自动重载 npm run server:dev ``` **服务器端点：** ```bash # 健康检查 curl http://localhost:3000/health # 聊天查询（自然语言转 GeoJSON） curl -X POST http://localhost:3000/api/v1/chat/geo-query \ -H "Content-Type: application/json" \ -d '{ "message": "显示所有城市", "datasourceId": "cities" }' # 列出可用数据源 curl http://localhost:3000/api/v1/datasources/list # 获取 LLM 配置 curl http://localhost:3000/api/v1/chat/llm-config # 验证自定义 LLM 配置 curl -X POST http://localhost:3000/api/v1/chat/validate-llm-config \ -H "Content-Type: application/json" \ -d '{ "provider": "ollama", "model": "llama3", "baseUrl": "http://localhost:11434" }' ``` ### 模式 3：Web 演示应用 项目包含一个全栈 Vue.js 演示，具有对话式 UI 和交互式地图： ```bash # 进入 web 演示目录 cd examples/web-demo # 安装依赖 npm install # 启动开发服务器 npm run dev # 在浏览器中打开 http://localhost:5173 ``` **特性：** - 💬 对话式聊天界面 - 🗺️ 带有自动渲染功能的交互式 Leaflet 地图 - 📊 数据源管理面板 - 🔧 服务注册表单 - ⚙️ 实时 LLM 配置 **演示工作流程：** 1. 输入查询："显示所有城市" 2. 后端使用 LLM 解析查询 3. 提取匹配的 GeoJSON 要素 4. 前端在地图上渲染点 5. 显示包含结果的文本说明 ## 📋 开发状态 ### ✅ 已完成阶段 **第一阶段：LLM 提供商抽象** - ✅ 多提供商支持（通义千问、Ollama、Anthropic、OpenAI） - ✅ 提供商工厂，支持动态实例化 - ✅ 配置验证和环境加载 - ✅ 流式支持基础 **第二阶段：本地数据源** - ✅ GeoJSON 文件读取器，支持属性/空间过滤 - ✅ Shapefile 解析器 (.shp/.shx/.dbf)，支持流式处理 - ✅ CSV 和 Excel 支持，具有类型推断 - ✅ 元数据提取和字段语义 **第三阶段：数据库集成** - ✅ PostGIS 连接器，支持连接池 - ✅ 强制执行只读查询 - ✅ SQL 注入保护 - ✅ 自动 GeoJSON 转换 **第七阶段：服务数据源** - ✅ WFS（OGC Web Feature Service）1.0/1.1/2.0 - ✅ PostgREST 集成，支持过滤器转换 - ✅ 基础服务类，包含认证/重试逻辑 - ✅ DataSourceFactory 实现统一访问 **第八阶段：自然语言到 GeoJSON** - ✅ 基于 LLM 的查询解析器（中文/英文） - ✅ 数据提取器，支持属性过滤 - ✅ 前端地图可视化（Leaflet） - ✅ 端到端对话流程 **第九阶段：灵活的 LLM 管理** - ✅ LlmProviderManager，支持缓存 - ✅ 运行时提供商切换 - ✅ 前端 API 密钥覆盖支持 - ✅ 配置验证服务 - ✅ 缓存统计和监控 **基础设施** - ✅ SQLite 数据源注册表，支持自动发现 - ✅ Jest 测试框架（27+ 个通过测试） - ✅ Express REST API 服务器 - ✅ Vue.js Web 演示，支持热重载 - ✅ Rollup 打包器，用于 SDK 分发 - ✅ TypeScript 严格模式，完整类型覆盖 ### 🔄 进行中 - [ ] 第四阶段：业务 API 服务注册表，支持 OpenAPI 导入 - [ ] 高级地理空间分析工具（缓冲区、交集、距离） - [ ] 全面的单元和集成测试覆盖 - [ ] 使用 OpenAPI/Swagger 的 API 文档 - [ ] 速率限制和请求节流 - [ ] 身份验证和授权中间件 - [ ] WebSocket 支持，用于实时操作 ### 📅 计划中 - [ ] 行业插件系统（水务、电网、交通） - [ ] 3D 可视化支持 - [ ] 移动应用（React Native / Flutter） - [ ] 高级缓存策略（Redis） - [ ] 负载均衡的水平扩展 - [ ] 使用分析和计费跟踪 - [ ] 模型微调管道 - [ ] 离线模式，支持本地 LLM（Ollama） ## 📚 文档 所有文档遵循**文档驱动开发（DDD）**方法论 - 在实现之前创建设计文档。 ### 设计文档（DDD 产物） - [LLM 提供商设计](docs/design/01-llm-provider-design.md) - 提供商抽象和工厂模式 - [本地数据源设计](docs/design/02-local-datasource-design.md) - 基于文件的数据访问 - [PostGIS 和元数据设计](docs/design/03-postgis-metadata-design.md) - 数据库集成 - [API 服务注册表设计](docs/design/04-api-service-registry-design.md) - 业务 API 管理 - [Web 演示后端设计](docs/design/05-web-demo-backend-design.md) - REST API 架构 - [服务数据源设计](docs/design/07-service-datasources-design.md) - WFS/PostgREST - [自然语言到 GeoJSON 设计](docs/design/13-natural-language-to-geojson-design.md) - 查询解析 - [LLM 提供商管理器设计](docs/design/15-llm-provider-manager-design.md) - 动态提供商管理 ### 架构 - [愿景和产品边界](docs/architecture/01-vision.md) - [系统架构](docs/architecture/02-architecture.md) - [接口规范](docs/architecture/03-interface-specs.md) ### 开发指南 - [开发进度](docs/development/dev-progress.md) - 当前实现状态 - [项目结构](docs/development/project-structure.md) - 代码库组织 - [依赖更新](docs/development/dependency-updates.md) - 版本管理 - [差距分析](docs/development/gap-analysis.md) - 缺失功能评估 ### 参考资料 - [原始架构文档](docs/references/geoai-universal-architecture.md) ## 🛠️ 技术栈 **核心技术：** - TypeScript 6.0 - 类型安全开发 - Node.js 24+ - 运行时环境 - Express 5.x - REST API 服务器 - Vue.js 3.5 - 前端框架（Web 演示） **地理空间库：** - @turf/turf 7.3 - 空间分析和过滤 - leaflet 1.9 - 交互式地图（Web 演示） - shapefile 0.6 - Shapefile 解析 - wellknown - WKT/WKB 转换 **数据库和存储：** - pg 8.20 - PostgreSQL/PostGIS 客户端 - better-sqlite3 12.9 - SQLite 注册表 - xlsx 0.18 - Excel 文件支持 - csv-parser 3.2 - CSV 解析 **LLM 集成：** - openai 6.34 - OpenAI 兼容 API 客户端 - axios 1.12 - HTTP 客户端，用于 API 调用 **开发工具：** - Rollup 4.60 - 模块打包器 - Jest 30.3 - 测试框架 - ESLint 10.0 - 代码检查 - Prettier 3.8 - 代码格式化 - nodemon 3.1 - 开发自动重载 ## 🤝 贡献 欢迎贡献！请遵循以下准则： 1. **首先阅读设计文档**：所有功能在实现前都需要设计文档（DDD 方法论） 2. **遵循 TypeScript 标准**：严格模式、全面类型、JSDoc 注释 3. **编写测试**：为新功能编写单元测试，保持 >80% 覆盖率 4. **更新文档**：保持文档与代码更改同步 5. **提交 PR**：包括描述、测试说明和相关问题 ### 开发工作流程 ```bash # 1. Fork 并克隆仓库 git clone https://github.com/your-fork/GeoAI-Universal-Platform.git # 2. 创建功能分支 git checkout -b feature/your-feature-name # 3. 安装依赖 npm install # 4. 进行更改并编写测试 npm test # 5. 检查和格式化代码 npm run lint npm run format # 6. 构建并验证 npm run build # 7. 提交拉取请求 ``` ## 📞 支持 - **问题**：通过 GitHub Issues 报告错误和功能请求 - **讨论**：在 GitHub Discussions 中提问和分享想法 - **文档**：浏览 `docs/` 目录中的 comprehensive 文档 --- *为地理空间 AI 社区用心构建 ❤️*