# Deepness
**Repository Path**: SpharxTeam/deepness
## Basic Information
- **Project Name**: Deepness
- **Description**: deepness，L2~L4数据处理，适用于空间智能
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: main
- **Homepage**: https://atomgit.com/spharx/deepness
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-18
- **Last Updated**: 2026-04-28
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Deepness 深度加工系统
> 始于数据，终于智能
中文 | [English](README_EN.md)
## 📋 项目简介
Deepness 是 SpharxWorks 数据智能基础设施工具集（SpharxTools）的核心深度加工子系统，致力于将原始物理世界数据转化为富含语义和物理属性的高价值数据资产。系统采用模块化、容器化的设计理念，通过四个核心处理管道实现从基础数据到高级应用的完整转换链路。
*"From data intelligence emerges"*
*"始于数据，终于智能"*
## 🎯 核心价值
- **物理世界数字化**: 将现实场景转化为可计算、可仿真的数字孪生体
- **语义丰富化**: 为3D场景注入丰富的语义和物理属性信息
- **交互建模**: 记录和分析物理交互行为，支持反事实推演
- **标准输出**: 生成符合主流评测框架的标准化数据格式
## 🏗️ 系统架构
### 四层架构设计
Deepness 采用四层架构设计，参考 AgentOS K-1 至 K-4 架构原则：
```
┌─────────────────────────────────────────────────────────────┐
│ 应用层 (Pipelines) │
│ run_01_spatial_prior | run_02_physics_jepa | │
│ run_03_causal_trajectory | run_04_benchmark_export │
├─────────────────────────────────────────────────────────────┤
│ 编排层 (Orchestration) │
│ TaskQueue · ResourceManager · Scheduler · WorkflowEngine
├─────────────────────────────────────────────────────────────┤
│ 处理层 (Pipeline Base) │
│ 标准化处理接口 │
├─────────────────────────────────────────────────────────────┤
│ 核心层 (Core) │
│ Abstractions · Services · Security · Observability │
└─────────────────────────────────────────────────────────────┘
```
**📐 设计原则**:
- **K-1 极简内核**：核心仅提供基础抽象，服务可插拔
- **K-2 接口契约**：通过接口实现松耦合
- **K-3 服务隔离**：每个 Pipeline 独立容器化部署
- **K-4 插拔策略**：运行时模型切换与配置热加载
### 核心处理管道
1. **run_01_spatial_prior** (空间先验生成)
- 基于 NVIDIA Cosmos 世界模型实现空间理解
- 生成场景的语义分割和几何先验
- 为下游任务提供基础空间表征
2. **run_02_physics_jepa** (物理属性预测)
- 基于 Meta JEPA 架构预测物体物理属性
- 推断材质、密度、摩擦系数等参数
- 构建物理一致的 3D 场景模型
3. **run_03_causal_trajectory** (因果轨迹记录)
- 整合 YOLOv8 动态检测和 ORB-SLAM3/LIO-SAM 定位
- 记录物理交互轨迹和因果链
- 支持反事实推演和轨迹分析
4. **run_04_benchmark_export** (评测数据导出)
- 转换为标准评测格式（Genie Sim 3.0、JEPA、Spatial）
- 支持多种世界模型评估框架
- 提供数据质量报告和统计信息
## 🚀 快速开始
### 环境要求
- **操作系统**: Ubuntu 20.04/22.04 LTS (推荐)
- **GPU**: NVIDIA GPU 支持 CUDA 12.1+
- **内存**: 16GB+ RAM (推荐 32GB)
- **存储**: 500GB+ SSD 存储空间
### 安装部署
```bash
# 1. 克隆项目
git clone https://github.com/spharx/spharxworks.git
cd spharxworks/deepness
# 2. 配置环境变量
cp .env.template .env
# 编辑 .env 文件，设置 HF_TOKEN 等必要参数
# 3. 下载依赖和模型
./scripts/download/download_sources.sh
./scripts/download/download_models.sh
./scripts/download/download_deps.sh
# 4. 构建系统
make all
# 5. 启动服务
docker-compose up -d
```
### 验证安装
```bash
# 检查服务状态
docker-compose ps
# 查看日志
docker-compose logs -f
# 测试处理流程
docker-compose run --rm spatial --input /data/input/scene_001 --output /data/output/scene_001
```
## 📁 项目结构
```
Deepness/
├── core-deepness/ # ★ 核心代码包（四层架构）
│ ├── __init__.py # 包入口
│ ├── core/ # 核心抽象层
│ │ ├── abstractions/ # 接口、模型、异常
│ │ ├── services/ # 配置、日志服务
│ │ ├── security/ # 安全服务
│ │ └── observability/ # 可观测性
│ ├── orchestration/ # 编排层
│ │ ├── task_queue.py # 任务队列
│ │ ├── resource_manager.py # 资源管理
│ │ ├── scheduler.py # 调度器
│ │ └── workflow_engine.py # 工作流引擎
│ ├── pipelines/ # 四大处理管道
│ │ ├── base/ # 管道基类
│ │ ├── run_01_spatial_prior/ # 空间先验生成
│ │ ├── run_02_physics_jepa/ # 物理属性预测
│ │ ├── run_03_causal_trajectory/# 因果轨迹记录
│ │ └── run_04_benchmark_export/ # 评测数据导出
│ └── common/ # 公共工具
│ ├── configs/ # 配置文件
│ ├── dashboard/ # 监控仪表板
│ ├── patches/ # 补丁
│ ├── schemas/ # 数据模式
│ └── scripts/ # 工具脚本
├── base/ # 基础镜像配置
├── docs/ # 技术文档中心
├── hardware/ # 硬件支持
├── produce/ # 生产数据目录
│ ├── input/ # 输入数据
│ └── output/ # 输出数据
├── scripts/ # 自动化脚本
│ ├── build/ # 构建脚本
│ ├── deploy/ # 部署脚本
│ ├── dispose/ # 资源清理
│ ├── download/ # 依赖下载
│ ├── init/ # 初始化脚本
│ ├── lib/ # 脚本库
│ ├── pipeline/ # 管道脚本
│ └── utils/ # 工具脚本
├── tests/ # 测试套件
│ ├── unit/ # 单元测试
│ ├── scripts/ # 测试脚本
│ └── docs/ # 测试文档
├── docker-compose.yml # 服务编排配置
├── Makefile # 构建自动化
├── pyproject.toml # Python 项目配置
├── .env.template # 环境变量模板
└── README.md # 本文档
```
## 🔧 技术栈
### 核心技术
| 领域 | 技术 | 说明 |
|------|------|------|
| **深度学习** | PyTorch 2.5.1 (CUDA 12.1) | 核心计算框架 |
| **世界模型** | NVIDIA Cosmos, Meta JEPA | 空间理解与物理预测 |
| **计算机视觉** | YOLOv8, ORB-SLAM3, LIO-SAM | 目标检测与定位 |
| **3D 处理** | Open3D 0.18.0, PyTorch3D 0.7.6 | 三维数据处理 |
| **物理仿真** | PyBullet | 物理引擎集成 |
### 架构设计
- **四层架构**: 应用层 → 编排层 → 处理层 → 核心层
- **微内核设计**: 核心仅提供基础抽象，服务可插拔
- **依赖注入**: 通过接口契约实现松耦合
- **Pydantic V2**: 类型安全的数据模型验证
## 📊 数据处理流程
### 标准输入格式
```
/data/input/scene_xxx/
├── rgb/ # RGB 图像序列
├── depth/ # 深度图像序列
├── calibration/ # 相机标定参数
├── timestamps.csv # 时间戳文件
└── meta.json # 场景元数据
```
### 处理输出结构
```
/data/output/scene_xxx/
├── spatial_prior/ # 空间先验输出
│ ├── semantic_maps/
│ ├── geometry_prior/
│ └── cosmos_features.json
├── physics_jepa/ # 物理属性预测
│ ├── attributes.json
│ └── jepa_embeddings/
├── causal_trajectory/ # 因果轨迹记录
│ ├── trajectory.jsonl
│ ├── slam_poses/
│ └── dynamic_objects/
└── benchmark/ # 评测导出格式
├── genie_format/
├── jepa_format/
└── spatial_format/
```
## 🛠️ 开发指南
### 代码规范
- **Python**: 遵循 PEP 8 规范，使用 Black 格式化
- **类型检查**: 使用 Pydantic V2 进行运行时验证
- **测试**: pytest + pytest-cov，覆盖率目标 >85%
### 代码示例
```python
from deepness import (
ConfigService,
PipelineScheduler,
ValidationService,
TracingService,
)
# 初始化配置
config = ConfigService()
config.load("core-deepness/common/configs/pipeline_config.yaml")
# 创建调度器
scheduler = PipelineScheduler()
# 提交任务
task = scheduler.submit(
pipeline_name="spatial_prior",
input_path="/data/input/scene_001",
output_path="/data/output/scene_001",
)
# 执行并追踪
with TracingService.span("processing"):
scheduler.run_until_complete()
```
### 贡献流程
1. Fork 项目仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 开启 Pull Request
## 🔒 安全特性
### 四重安全防护
1. **输入净化**: SQL注入、XSS、路径遍历、命令注入检测
2. **权限控制**: RBAC角色权限体系，12种细粒度权限
3. **审计日志**: 完整操作审计，不可篡改
4. **资源隔离**: 进程/容器沙箱隔离
## 📈 性能指标
### 处理能力
- **单场景处理**: 5-10分钟（取决于复杂度）
- **并发处理**: 支持多场景并行处理
- **资源利用率**: GPU 利用率 > 70%
### 扩展性
- **水平扩展**: 支持多节点分布式部署
- **垂直扩展**: 可配置资源限制和分配
- **弹性伸缩**: 根据负载自动调整资源
## 🔄 版本历史
### 当前版本 (v2.0.0)
- ✅ 基础架构搭建完成
- ✅ Docker 容器化配置就绪
- ✅ 四个核心处理模块全部实现
- ✅ run_01_spatial_prior (Cosmos 适配器)
- ✅ run_02_physics_jepa (JEPA 物理预测)
- ✅ run_03_causal_trajectory (SLAM+ 因果推理)
- ✅ run_04_benchmark_export (多格式导出)
- ✅ 核心架构重构完成
- ✅ 四层架构（应用/编排/处理/核心）
- ✅ 安全与可观测性层
- ✅ 统一包结构
- ⏳ 端到端集成测试中 (90%)
- 🔲 性能基准测试
### 未来规划
```
v2.0.0 - 当前开发版本 (90% 完成)
v2.1.0 - 优化 JEPA 预测精度和速度
v2.2.0 - 增强 SLAM 鲁棒性和多传感器融合
v2.3.0 - 完整流水线正式发布
v2.5.0 - 性能优化和功能扩展（分布式处理）
v3.0.0 - 云原生支持和实时流式处理
```
## 📚 文档资源
### 核心文档
- [README_pipelines.md](docs/README_pipelines.md) - 处理管道详细文档
- [README_scripts.md](docs/README_scripts.md) - 脚本工具集说明
- [README_tests.md](tests/README_tests.md) - 测试套件设计文档
- [STRUCTURE.md](STRUCTURE.md) - 项目结构说明
- [STRUCTURE_REORGANIZATION_REPORT.md](docs/STRUCTURE_REORGANIZATION_REPORT.md) - 结构重组报告
- [REFACTORING_PLAN_V2.md](docs/REFACTORING_PLAN_V2.md) - V2.0 重构计划
- [V2_REFACTORING_REPORT.md](docs/V2_REFACTORING_REPORT.md) - Phase 1-2 报告
- [PHASE3_ORCHESTRATION_REPORT.md](docs/PHASE3_ORCHESTRATION_REPORT.md) - Phase 3 报告
- [PHASE4_SECURITY_OBSERVABILITY_REPORT.md](docs/PHASE4_SECURITY_OBSERVABILITY_REPORT.md) - Phase 4 报告
### 开发资源
- [配置管理](core-deepness/common/configs/) - YAML 配置文件
- [Dockerfile 参考](base/Dockerfile) - 基础镜像构建
- [Makefile 使用](Makefile) - 构建自动化指南
## 📞 技术支持
### 社区支持
- **Issues**: [GitHub Issues](https://github.com/spharx/spharxworks/issues)
- **讨论区**: [GitHub Discussions](https://github.com/spharx/spharxworks/discussions)
- **文档**: [在线文档](https://docs.spharx.cn/deepness)
### 商业支持
- **企业版**: 提供商业许可和技术支持
- **定制开发**: 根据需求定制功能模块
- **培训服务**: 提供系统使用和开发培训
## 🤝 贡献者
感谢所有为 Deepness 项目做出贡献的开发者！
## 📄 许可证
本项目采用 **GPL-3.0 开源协议 + 商业闭源授权** 双轨授权模式。
## 🙏 致谢
Deepness 项目借鉴和使用了众多优秀的开源项目：
- [NVIDIA Cosmos](https://github.com/NVIDIA/Cosmos) - 物理世界 AI 基础模型
- [Meta JEPA](https://github.com/facebookresearch/jepa) - 联合嵌入预测架构
- [YOLOv8](https://github.com/ultralytics/ultralytics) - 实时目标检测
- [ORB-SLAM3](https://github.com/UZ-SLAMLab/ORB_SLAM3) - 视觉SLAM系统
- [LIO-SAM](https://github.com/TixiaoShan/LIO-SAM) - 激光雷达惯性里程计
---
构建 AI 时代的物理世界数据基础设施
From data intelligence emerges
始于数据，终于智能
AtomGit ·
Gitee ·
GitHub ·
文档
## 许可证
SpharxWorks 采用 **GPL-3.0 开源协议 + 商业闭源授权** 双轨授权模式，您可根据自身使用场景选择对应授权。
### 开源授权（GPL-3.0）
个人学习、学术研究、非商业原型验证、开源社区贡献等非商业场景，可免费使用本项目，需严格遵守GPL-3.0协议的开源义务，完整协议详见 [LICENSE-GPL-3.0](LICENSE-GPL-3.0)。
### 商业闭源授权
任何将本项目用于闭源商业产品、商业服务、盈利性项目的行为，均需提前向SPHARX极光感知科技申请商业授权，获得闭源使用豁免、官方技术支持、定制化服务等权益。
商业授权详情详见 [LICENSE-COMMERCIAL](LICENSE-COMMERCIAL)，授权申请请联系：
- 官方邮箱：lidecheng@spharx.cn、wangliren@spharx.cn
- 官方网站：https://spharx.cn
© 2026 SPHARX Ltd. All Rights Reserved.