23. 附录 D: 常见问题 (FAQ)

23.1. 安装问题

23.1.1. Q: Python 版本不兼容怎么办？

A: SimKit 需要 Python 3.10+。使用以下命令检查版本：

python --version

23.1.2. Q: uv 和 pip 应该选哪个？

A: 推荐使用 uv，它更快且依赖解析更可靠。

23.1.3. Q: 安装时遇到依赖冲突怎么办？

A: 尝试清除缓存后重新安装：

pip cache purge
pip install --force-reinstall -e .

23.2. 使用问题

23.2.1. Q: 如何加载 HSSD 场景？

A: 使用 HssdSceneEnv:

from simkit import HssdSceneEnv

env = HssdSceneEnv(
    scene="102343992",
    dataset_root="/path/to/hssd"
)

23.2.2. Q: 如何切换仿真器？

A: 使用相应的适配器：

from simkit.simulators.maniskill import ManiSkillAdapter
from simkit.simulators.sapien import SapienAdapter

# ManiSkill
env = ManiSkillAdapter().create_env(scene)

# SAPIEN
env = SapienAdapter().create_env(scene)

23.2.3. Q: 如何生成 RGB-D 数据？

A: 使用环境的 render 方法：

obs = env.render()
rgb = obs['rgb']
depth = obs['depth']

23.3. 性能问题

23.3.1. Q: 如何提高渲染速度？

A:

  1. 使用 GPU 加速

  2. 降低渲染分辨率

  3. 使用并行渲染

23.3.2. Q: 内存占用过高怎么办？

A:

  1. 减少并行环境数

  2. 及时释放不用的环境

  3. 使用 del env 和 gc.collect()

23.4. 开发问题

23.4.1. Q: 如何贡献代码？

A: 参考 附录 E: 贡献指南

23.4.2. Q: 如何报告 Bug?

A: 在 GitHub Issues 中创建 issue，包含：

  • 问题描述

  • 复现步骤

  • 环境信息

  • 错误日志