为 SAHI 做贡献

July 20, 2026 · View on GitHub

感谢您有兴趣为 SAHI 做贡献！本指南将帮助您快速上手。

设置开发环境

1. Fork 和克隆

git clone https://github.com/YOUR_USERNAME/sahi.git
cd sahi

2. 创建环境

我们推荐使用 Python 3.10 进行开发：

pip install uv
uv venv --python 3.10
source .venv/bin/activate  # Windows 用户: .venv\Scripts\activate

3. 安装依赖

# 安装核心 + 开发依赖
uv sync --extra dev

# 如需测试特定模型，请安装其对应的依赖。

代码格式化

我们使用 ruff 进行代码格式化和 lint 检查。格式化代码：

# 检查格式
uv run ruff check .
uv run ruff format --check .

# 修复格式
uv run ruff check --fix .
uv run ruff format .

或使用便捷脚本：

# 检查格式
python scripts/format_code.py check

# 修复格式
python scripts/format_code.py fix

运行测试

# 运行所有测试
uv run pytest

# 运行指定测试文件
uv run pytest tests/test_predict.py

# 运行并生成覆盖率报告
uv run pytest --cov=sahi

提交 Pull Request

  1. 创建新分支：git checkout -b feature-name
  2. 进行修改
  3. 格式化代码：python scripts/format_code.py fix
  4. 运行测试：uv run pytest
  5. 提交清晰的 commit 信息：git commit -m "Add feature X"
  6. 推送并创建 PR：git push origin feature-name

CI 构建失败

如果 CI 构建因格式问题失败：

  1. 查看 CI 输出，确认失败的 Python 版本

  2. 使用该版本创建环境：

    uv venv --python 3.X  # 将 X 替换为 CI 中的版本号
source .venv/bin/activate

  3. 安装开发依赖：

    uv sync --extra dev

  4. 修复格式：

    python scripts/format_code.py fix

  5. 提交并推送更改

添加新模型支持

要添加对新检测框架的支持：

  1. 在 sahi/models/your_framework.py 下创建新文件
  2. 实现继承自 DetectionModel 的类
  3. 在 sahi/auto_model.py 中将您的框架添加到 MODEL_TYPE_TO_MODEL_CLASS_NAME
  4. 在 tests/test_yourframework.py 下添加测试
  5. 在 docs/notebooks/inference_for_your_framework.ipynb 下添加示例 notebook
  6. 更新 README.md 和 docs/ 下的相关文档以包含您的新模型

请参考现有实现，如 sahi/models/ultralytics.py。

有问题？

如果您有任何疑问，欢迎发起讨论！