# data2ontology
**Repository Path**: wanghaowen2/data2ontology
## Basic Information
- **Project Name**: data2ontology
- **Description**: 知识工程工具，用于快速构建给Agent使用的Skills、RAG和本体
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 13
- **Forks**: 11
- **Created**: 2026-01-29
- **Last Updated**: 2026-06-09
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Data2Ontology
面向企业数据资产的本体建模、知识图谱部署与智能检索平台
把结构化数据、非结构化文档、领域逻辑和 Agent 工作流统一到可部署、可查询、可评估的本体工程链路中
[](https://gitee.com/wanghaowen2/data2ontology)
[](https://gitee.com/wanghaowen2/data2ontology/tree/develop)
[](LICENSE)
[](https://www.python.org/)
[](https://fastapi.tiangolo.com/)
[](front/)
[](db/)
[](db/milvus/)
> Data2Ontology 关注从数据接入到本体落地的完整工程闭环：导入数据、沉淀逻辑、建模本体、部署图谱、实例化数据、检索问答、评估与运维。
## 📑 快速导航
| | | |
|:---:|:---:|:---:|
| [🚀 快速开始](#-快速开始) | [🎯 核心能力](#-核心能力) | [🧭 工作流](#-工作流) |
| [🧩 服务组成](#-服务组成) | [📁 目录结构](#-目录结构) | [⚙️ 配置要点](#️-配置要点) |
| [🛠️ 本地开发](#️-本地开发) | [🧪 状态检查](#-状态检查) | [📚 文档索引](#-文档索引) |
## 🚀 快速开始
一键本地部署入口：
```bash
cp backend/.env.example backend/.env
# 按实际环境修改 backend/.env 中的模型、数据库、图数据库和向量库配置
bash deployment/local-source/deploy.sh
```
部署脚本会自动完成：
- 启动 PostgreSQL、Neo4j 或 HugeGraph、Milvus
- 等待 PostgreSQL / Milvus 就绪并按需导入 SQL
- 构建前端并部署到 nginx 静态目录
- 使用 tmux 启动 `authservice`、`backend`、`ontology_modeling_agent`、`ai_modeling_beta_service`
- 写入 nginx 反向代理配置并 reload nginx
部署完成后，前端默认通过 nginx 访问：
```text
/api/* -> backend
/api/auth/* -> authservice
/api/ai-modeling-beta/* -> ai_modeling_beta_service
/agent/* -> backend_agent
/ontology-agent/* -> ontology_modeling_agent
```
如需了解部署前置条件和环境变量，请看 [`deployment/local-source/DEPLOY.md`](deployment/local-source/DEPLOY.md)。
## 🎯 核心能力
### 1. 数据接入与结构化沉淀
系统支持 Excel、本地数据库、远程数据库和非结构化文档等多类输入。导入后的数据会进入统一工作区，并为本体建模、逻辑抽取和图谱实例化提供上下文。
### 2. 本体建模与语义增强
`backend`、`ontology_modeling_agent` 和 `ai_modeling_beta_service` 共同支撑本体模型构建。平台可以围绕实体、属性、关系、规则、能力问题和文档证据生成候选本体，并支持人工确认与版本化管理。
### 3. 图谱部署与实例化
本体发布后可以部署到图数据库，实例化任务会把数据、逻辑块和虚拟字段写入图谱。当前图存储支持 Neo4j，并预留 HugeGraph 后端。
### 4. RAG 与本体检索
Milvus 负责向量检索，`backend_agent` 提供面向知识图谱和本体数据的检索 Agent。前端可以通过会话接口完成问答、Trace 查看和图谱定位。
### 5. Skill 服务与评测体系
`backend_skill` 提供 Skill 管理、上传、审查、测试、图谱化和 Skill Studio 能力。`backend/app/ontology_eval` 与 `tests/` 目录承载本体评估、服务检查和端到端验证。
### 6. 交付友好的部署脚本
`deployment/local-source/deploy.sh` 面向单机交付环境，优先使用现有容器和本地镜像，集中管理数据库、前端构建、nginx 代理和后端 tmux 服务。
## 🧭 工作流
Data2Ontology 的主流程可以概括为：
```text
数据接入
-> 工作区与数据源配置
-> 本体候选建模
-> 人工确认与版本发布
-> 图数据库部署
-> 数据实例化
-> 检索问答 / Trace / 评估
```
运行时服务关系：
```text
front
├─ /api -> backend
├─ /api/auth -> authservice
├─ /ontology-agent -> ontology_modeling_agent
├─ /api/ai-modeling-beta -> ai_modeling_beta_service
└─ /agent -> backend_agent
backend
├─ PostgreSQL -> 工作区、本体、结构化数据
├─ Neo4j / HugeGraph -> 图谱部署与实例化结果
└─ Milvus -> RAG 向量库
```
## 🧩 服务组成
| 模块 | 默认端口 | 说明 |
|:---|:---:|:---|
| `front` | `5173` | Vite + React 前端，覆盖数据导入、本体建模、实例化、RAG、Skill 管理等页面 |
| `authservice` | `9001` | 鉴权、用户与工作区初始化服务 |
| `backend` | `8001` | FastAPI 主后端，负责核心 API、数据库访问、本体建模与实例化编排 |
| `ontology_modeling_agent` | `8002` | 本体建模 Agent 服务，提供执行、恢复和取消接口 |
| `ai_modeling_beta_service` | `8003` | AI 建模 Beta 服务，负责候选生成、语义归一、证据和报告 |
| `backend_agent` | `7471` 等 | 图谱检索、问答 Agent、MCP 封装和 trace 支撑 |
| `backend_skill` | `8011` | Fastify Skill 服务，负责 Skill 管理、审查、测试与 Studio |
| PostgreSQL | `5432` | 业务库、本体库、非结构化数据索引和服务状态 |
| Neo4j | `7474` / `7687` | 图谱浏览和 Bolt 写入查询 |
| Milvus | `19531` / `9092` | 向量检索服务，MinIO 默认映射为 `19000` / `19001` |
## 📁 目录结构
```text
data2ontology/
├── front/ # React + Vite 前端
├── backend/ # FastAPI 主后端
├── authservice/ # 鉴权微服务
├── ontology_modeling_agent/ # 本体建模 Agent
├── ai_modeling_beta_service/ # AI 建模 Beta 服务
├── backend_agent/ # 图谱检索 Agent、MCP 和工具服务
├── backend_skill/ # Skill 管理、审查、测试与 Studio 服务
├── db/ # PostgreSQL、Neo4j、HugeGraph、Milvus compose 与 SQL
├── deployment/ # 本地交付、云龙构建、ECS 设计与部署脚本
├── docs/ # 跨模块设计文档
├── tests/ # 集成测试、黑盒测试和部署检查
└── support/ # 客户侧定制代码、配置、脚本和文档预留目录
```
## ⚙️ 配置要点
### 后端统一配置
建议以 `backend/.env` 作为本地部署的主配置文件：
```bash
cp backend/.env.example backend/.env
```
关键配置分组：
| 配置组 | 关键项 |
|:---|:---|
| 模型接口 | `OPENAI_API_KEY`、`OPENAI_BASE_URL`、`OPENAI_MODEL` |
| PostgreSQL | `ONTOLOGY_DB_HOST`、`ONTOLOGY_DB_NAME`、`ONTOLOGY_DB_USER`、`ONTOLOGY_DB_PASSWORD` |
| 默认业务库 | `DEFAULT_DB_TYPE`、`DEFAULT_DB_HOST`、`DEFAULT_DB_DATABASE` |
| 图数据库 | `GRAPH_DB_TYPE`、`NEO4J_URI`、`NEO4J_PASSWORD`、`HUGEGRAPH_URL` |
| Milvus | `MILVUS_HOST`、`MILVUS_PORT=19531`、`MILVUS_USER`、`MILVUS_PASSWORD` |
| 实例化并发 | `ONTOLOGY_INSTANTIATION_MAX_CONCURRENT_JOBS`、`ONTOLOGY_INSTANTIATION_JOB_TIMEOUT_SECONDS` |
### 前端直连开发配置
本地 Vite 开发可复制：
```bash
cp front/.env.example front/.env
```
常用直连配置：
```env
VITE_API_BASE_URL=http://localhost:8001
VITE_AUTH_API_URL=http://localhost:9001
VITE_AGENT_API_URL=http://localhost:7471
VITE_ONTOLOGY_MODELING_AGENT_BASE_URL=http://localhost:8002
```
如果使用 `deployment/local-source/deploy.sh` 的 nginx 相对路径代理模式，请参考 [`deployment/local-source/DEPLOY.md`](deployment/local-source/DEPLOY.md) 中的 Vite 变量说明。
## 🛠️ 本地开发
### 基础设施
```bash
cd db/postgres-db && docker compose up -d
cd ../neo4j && docker compose up -d
cd ../milvus && docker compose up -d
```
如需 HugeGraph，请使用 `db/hugegraph/docker-compose.yml`，并在 `backend/.env` 中切换 `GRAPH_DB_TYPE=hugegraph`。
### Python 服务
每个 Python 服务建议使用独立虚拟环境：
```bash
cd authservice
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 9001 --reload
```
```bash
cd backend
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload
```
```bash
cd ontology_modeling_agent
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
uvicorn server:app --host 0.0.0.0 --port 8002 --reload
```
```bash
cd ai_modeling_beta_service
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
cd ..
uvicorn ai_modeling_beta_service.app:app --host 0.0.0.0 --port 8003 --reload
```
### 前端与 Skill 服务
```bash
cd front
npm install
npm run dev
```
```bash
cd backend_skill
npm install
npm run dev
```
## 🧪 状态检查
常用检查命令：
```bash
docker ps
curl http://127.0.0.1:8001/docs
curl http://127.0.0.1:9001/docs
curl http://127.0.0.1:8002/docs
curl http://127.0.0.1:8003/docs
tmux ls
```
数据库检查：
```bash
docker exec -it postgres-db psql -U root -d ontology -c "\dt"
docker logs neo4j --tail 50
docker logs milvus-standalone --tail 50
```
测试入口：
```bash
cd backend && pytest
cd ontology_modeling_agent && pytest
cd ai_modeling_beta_service && pytest
cd backend_skill && npm test
cd front && npm run build
```
## ❓ 常见问题
| 问题 | 优先检查 |
|:---|:---|
| 后端无法连接 PostgreSQL | `postgres-db` 是否运行，`backend/.env` 中 `ONTOLOGY_DB_*` 是否与容器一致 |
| Neo4j 写入或查询失败 | `NEO4J_URI`、`NEO4J_USER`、`NEO4J_PASSWORD` 是否匹配 compose 配置 |
| Milvus 连接失败 | 宿主机端口是否是 `19531`，账号密码是否为 compose 中配置的 `root` / `Milvus` |
| 前端请求失败 | `front/.env` 是否指向实际后端地址，或 nginx 代理路径是否生效 |
| Agent 问答失败 | `backend_agent` 是否启动，模型网关与 JWT / workspace 作用域配置是否完整 |
| Skill 服务失败 | `backend_skill/.env` 中 `PORT`、`JWT_SECRET`、`SKILL_DB_*`、模型 endpoint 是否配置完整 |
## 📚 文档索引
| 文档 | 内容 |
|:---|:---|
| [`deployment/local-source/DEPLOY.md`](deployment/local-source/DEPLOY.md) | 单机本地交付脚本的前置条件、配置项和 nginx 代理说明 |
| [`backend_agent/README.md`](backend_agent/README.md) | 图谱检索、问答 Agent、MCP 和请求作用域说明 |
| [`backend_skill/docs/README.md`](backend_skill/docs/README.md) | Skill 服务架构、API、环境变量和审查文档索引 |
| [`front/README.md`](front/README.md) | 前端技术栈、功能模块和开发命令 |
| [`support/README.md`](support/README.md) | 客户侧定制目录的使用边界 |
| [`docs/ai-modeling-beta-service-deployment-design.md`](docs/ai-modeling-beta-service-deployment-design.md) | AI 建模 Beta 服务部署设计 |
| [`docs/ai-modeling-beta-service-deployment-plan.md`](docs/ai-modeling-beta-service-deployment-plan.md) | AI 建模 Beta 服务部署计划 |
## 📄 License
本项目使用 [MIT License](LICENSE)。