• 计算机视觉
• 深度学习
• 图像处理

导读

Kornia 是一个基于 PyTorch 的可微分计算机视觉库，覆盖几何变换、滤波、增强、特征与三维视觉等方向。本文围绕官方社区贡献文档 docs/source/community/contribute.rst，完整讲解如何参与这个开源项目——从报告 bug、提出使用问题，到用 Pixi 搭建开发环境、编写测试、遵守编码规范、提交 Pull Request 的完整链路。读完本文，你将掌握一套可直接落地的贡献流程，并理解 Kornia 在测试矩阵、变更日志（changelog）与 API 表面管理上的工程约定。

一、贡献的总体原则：每一条路径都算数

Kornia 的贡献文档开篇即表明态度："We develop Kornia for ourselves and the computer vision community"，任何形式的帮助都受欢迎。贡献不只是写代码，以下每条路径都是有效的贡献方式：

• 报告 bug（附带最小可复现示例）；
• 在 GitHub Discussions 或 Discord 上提问与解答问题；
• 提交代码或文档改进（通过 Pull Request）；
• 赞助项目（通过 Open Collective 与 GitHub Sponsors）。

仓库根目录的 CONTRIBUTING.md 进一步阐述了"社会契约"（social contract）：维护者会尽力审查 PR、修复 bug，但不承诺审查每一个 PR 或保证速度。这意味着贡献者需要做好沟通预期，把耐心和认真放在首位。

1.1 务实指南：动手前先做的事

• 开始之前先搜索已有的 issue 与 PR，避免重复劳动；
• 对于新公开 API、行为变更或大块工作，提前开 issue 或 discussion对齐方向——对话只代表对齐，不承诺一定会被合并；
• 修复 bug 时尽量附上"没有该修复就会失败"的测试，数值类改动最好给出参考实现、论文或数学不变量的来源；
• 先查找kornia中是否已有可复用的工具函数，再决定是否新增实现；
• 保持改动聚焦、贴近周边代码风格，公开行为变化时同步更新文档；
• PR 静默 15 天会被标记为 stale，但这只是队列整理信号，不会被关闭，评论或推送即可自动清除；维护者也可加pinned使其豁免清扫。

二、报告 Bug：让维护者能一次复现

官方文档建议在 GitHub issue 追踪器上新建 issue，并强调最有价值的报告包含最小可复现示例，以及 bug 模板要求的环境信息。环境行通常包括：

• Kornia、PyTorch、Python 版本；
• 操作系统（OS）类型；
• 设备后端（CPU / CUDA / MPS / TPU）；
• GPU 型号（如果相关）。

发布前请预览并脱敏任何隐私信息。

仓库的 AGENTS.md 给出了一条隐私意识良好的环境采集命令，与 bug 模板保持一致：

python -W ignore -c "import kornia, platform, sys, torch; gpu=torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'none'; backend=torch.version.cuda or getattr(torch.version, 'hip', None); print(f'kornia {kornia.__version__} | torch {torch.__version__} | python {sys.version.split()[0]} | OS {platform.platform()} | CUDA/ROCm {backend} (available={torch.cuda.is_available()}, GPU={gpu}) | MPS={torch.backends.mps.is_available()}')"

该命令只打印版本与硬件信息，不包含用户名、路径、环境变量或令牌，可安全分享。

诊断问题的通用方法（同样来自 AGENTS.md）：

1. 从最小复现与最窄的相关测试开始；
2. 不要在没有与基线版本安全对比之前就断言"故障是本来就存在的"；
3. 只索要有助于诊断的环境细节，绝不要索要敏感信息。

此外，很多"bug"其实是约定不匹配。提问前请先查阅 FAQ 与 约定页面（例如张量布局是BCHW还是BHWC、坐标系约定等）。

三、提问与讨论：问题该放哪里

使用问题与想法请走社区渠道，不要把 Q&A 放进 GitHub issues：

• GitHub Discussions（讨论区）；
• #kornia标签（PyTorch 论坛）；
• Discord 聊天。

对应的文档链接分别是文档中的 faqs.rst 与 conventions.rst。保持公开讨论（issue、discussion、PR 评论区），方便他人检索与学习。

四、贡献代码：开发环境搭建（Pixi）

4.1 环境管理：为什么用 Pixi

Kornia 使用 Pixi 中声明了default（Python 3.11）、py312、py313、py314、cuda等环境。依赖定义在 pyproject.toml 中，Pixi 任务底层调用uv，Python 测试运行在仓库.venv或版本化的.venv-py*项目环境中。

安装 Pixi（三选一）：

# Linux / macOS curl -fsSL https://pixi.sh/install.sh | bash # Windows (PowerShell) irm https://pixi.sh/install.ps1 | iex # 或通过 conda/mamba conda install -c conda-forge pixi

4.2 标准开发流程

1. Fork 仓库并克隆自己的 fork，添加上游远程：

   git clone git@github.com:<你的 GitHub 用户名>/kornia.git cd kornia git remote add upstream https://github.com/kornia/kornia.git

2. 新建分支（不要在main上直接开发）：

   git checkout upstream/main -b feat/foo_feature # 或 git checkout upstream/main -b fix/bar_bug

3. 安装开发环境：

   pixi install pixi run -e default install # 特定 Python 版本（自动使用隔离的 .venv-py312 / .venv-py313） pixi install -e py312 && pixi run -e py312 install pixi install -e py313 && pixi run -e py313 install # CUDA 开发（会重装 PyTorch，使用 CUDA 12.1） pixi run -e cuda install

4.3 Pixi 任务速查表

pixi.toml 中定义了完整的任务清单，日常开发常用命令如下：

4.4 测试环境变量与 pytest 参数

测试可用环境变量配置（pixi.toml中test任务的说明）：

# 设备：cpu, cuda, mps, tpu export KORNIA_TEST_DEVICE=cuda # dtype：float32, float64, float16, bfloat16 export KORNIA_TEST_DTYPE=float32 # 是否运行慢测试 export KORNIA_TEST_RUNSLOW=true pixi run test

也可以直接用 pytest 参数（test-module会把参数透传给 pytest）：

pixi run test-module tests/geometry --device=cpu --dtype=float32,float64 pixi run test-module tests/<TEST_TO_RUN>.py::TestClass::test_method pixi run test-module tests/<path>/ -k "expression"

• dtype 选项：bfloat16、float16、float32、float64、all
• device 选项：cpu、cuda、tpu、mps、all
• 编译测试：设置KORNIA_TEST_OPTIMIZER=inductor会启用 dynamo/compile 测试（未设置时默认剔除）
• doctest 权重：pixi run doctest-weights（或KORNIA_DOCTEST_DOWNLOAD=1）会真实运行需要下载模型权重的 docstring 示例，冷缓存约需 838 MB

五、编码规范：提交前必须遵守的规则

5.1 小步提交与注释

• 提交小而逻辑完整的改动，写清晰的提交信息，避免超大文件；
• 遵循 PEP8，行宽120 字符，使用 f-string（PEP 498）；
• 注释用英文，解释"为什么"而非"重复代码在做什么"；
• 二进制运算符后换行（W504）在特定场景可接受。

5.2 类型注解（Python >= 3.11）

• 优先直接用torch.Tensor、torch.nn.Module做类型注解（向后兼容时可从kornia.core导入）；
• 非 JIT 模块必须加from __future__ import annotations；
• 函数输入输出始终要有类型注解，用pixi run typecheck（基于ty）验证：

from __future__ import annotations import torch def homography_warp( patch_src: torch.Tensor, dst_homo_src: torch.Tensor, dsize: tuple[int, int], mode: str = 'bilinear', padding_mode: str = 'zeros' ) -> torch.Tensor: ...

5.3 依赖纪律

• 避免新增运行时依赖；确有必要时，说明现有依赖为何不够用，并权衡安装、构建与平台成本（AGENTS.md 中同样强调）。

六、测试规范：BaseTester 与测试矩阵

6.1 测试文件放哪里

测试放在 tests/ 下，可复用的测试支撑代码放在 testing/（不是tests/）。核心测试基类是 testing/base.py 中的BaseTester，它封装了assert_close（带 dtype 特定容差）、gradcheck与 dynamo 相关工具。

6.2 标准测试骨架

CONTRIBUTING.md 给出了推荐的测试类结构：

from testing.base import BaseTester class TestMyFunction(BaseTester): # 用 self.assert_close(...) 比较实际与期望张量 def test_smoke(self, device, dtype): # 用不同参数组合调用函数，确认至少能运行 pass def test_exception(self, device, dtype): # 测试函数可能抛出的异常 # with pytest.raises(<Error>) as errinfo: # your_function(<触发错误的参数>) # assert '<错误信息>' in str(errinfo) pass def test_cardinality(self, device, dtype): # 测试不同参数下输出形状是否符合预期 pass def test_feature_foo(self, device, dtype): # 基础功能测试 pass def test_gradcheck(self, device): # 梯度检查，使用 self.gradcheck(...) pass def test_dynamo(self, device, dtype, torch_optimizer): # 使用 dynamo 优化器测试 # inputs = (...) # op = your_function # op_optimized = torch_optimizer(op) # self.assert_close(op(inputs), op_optimized(inputs)) pass

6.3 设备与 dtype 覆盖

用 pytest 参数化覆盖不同设备、dtype 与 batch size：

import pytest @pytest.mark.parametrize("batch_size", [1, 2, 5]) def test_smoke(batch_size, device, dtype): x = torch.rand(batch_size, 2, 3, device=device, dtype=dtype) assert x.shape == (batch_size, 2, 3)

6.4 已知失败与精度细节（AGENTS.md 要点）

• 半精度与 MPS 已知失败通过清单管理（如 testing/known_failure_xfails/mps_float32.txt），修复后删除对应清单行；
• MPS 不支持 float64 gradcheck，且 autocast 可能改变有效 dtype；
• TF32 矩阵乘默认关闭，--tf32开启；cuDNN 卷积仍使用 PyTorch 的 TF32 默认值；
• torch.clamp不能作为可移植的梯度保护：在 torch 2.5.1/2.9.1 上clamp边界处梯度会原样通过，而在 2.14.0 上返回 0，因此求导表达式中应避免把 clamp 边界当作奇异点保护；
• 保留注入的device/dtypefixture，不要隐式创建 CPU 或默认 dtype 张量。

更完整的机制（含 guarded candidate recording、fresh-process replay）见 TESTING.md。

七、变更日志（Changelog）与文档更新

7.1 Changelog 片段机制

Kornia 用 Towncrier 管理变更日志（详见 changelog.d/README.md）。每个有用户可见变化的 PR 在 changelog.d/ 下新增一个 Markdown 片段文件，而不是直接改CHANGELOG.md，从而避免多个 PR 在同一文件冲突。

• 命名规则：<PR号>.<类型>.md，例如1234.fixed.md（用 PR 号，不是 issue 号）；
• 类型与含义：

• 若 PR 号未知，先用唯一名称如+fix-camera-shape.fixed.md，合并前改名为 PR 号；
• 内部重构、纯测试与仅 CI 的改动可省略片段，需在 PR 描述中说明并请维护者打no-changelog标签；
• 预览未发布的变更说明：pixi run changelog-preview（不修改任何文件）；
• 只有发布类 PR 才允许编辑CHANGELOG.md，发布流程用pixi run changelog-build --version X.Y.Z组装。

7.2 文档更新

• 文档源码在 docs/source/ 下，改动后运行pixi run -e default build-docs构建，用浏览器预览docs/build/html/index.html；
• 每个新的公开类或函数都要登记到对应的docs/source/*.rstAPI 页面，否则不会出现在渲染后的 API 参考中；
• 新增特征检测器/描述子时，还要更新 docs/generate_examples.py 中的responses列表，参考现有 DISK、ALIKED、XFeat 示例并保持(B, 3, H, W)图像形状。

7.3 API 表面（API surface）保护

• tests/api_surface.json 记录了稳定核心模块的公开名称，tests/test_api_surface.py 会拒绝在未同步更新清单的情况下删除公开 API；可用tests.test_api_surface.regenerate()重新生成清单；
• 被移除的 API 需同时登记到 tests/api_surface_removals.json（例如{"kornia.geometry.boxes": ["Boxes"]}）；
• 删除公开名称需走弃用窗口与发布说明流程。

八、Pull Request 全流程

8.1 填写 PR 模板

每个 PR 都要按 .github/pull_request_template.md 填写足够上下文，模板要求四部分：这个 PR 做了什么、关联的 issue 或 discussion、你检查了什么（列出运行过的测试与结果）、AI 如何帮助了你。

$ pixi run test-module tests/...

对 bug 修复，能复现 bug 的回归测试最有价值；数值/几何类改动要说明期望值来源（参考实现、论文或数学不变量）；新公开 API 或行为变更建议先有 issue 讨论。

8.2 PR 检查与合并要求

• 代码改动运行 CPU 测试矩阵、dynamo/compile 测试与ty类型检查；
• pre-commit 检查格式、lint、license 头、拼写与仓库文件卫生；
• 文档改动运行文档构建；
• 每个非 draft 的 PR 打开或被标记 ready 时自动获得 Copilot 审查，并需要一名维护者批准；
• PR 采用squash-merge合并；
• 静默过久的 PR 可能被关闭，但可以随时重新打开；
• 检查失败时请修复或解释原因。

8.3 如何挑选第一个贡献

• 文档修复、新测试和标记为good first issue的 issue 是最友好的切入点；
• help wanted标签的 issue 适合寻找功能实现起点。

九、性能、基准与 ONNX：进阶贡献须知

9.1 性能实践

• 优先原地操作（tensor.add_(other)优于tensor = tensor.add(other)）；
• 用张量视图与切片代替复制，用 PyTorch 向量化操作代替 Python 循环；
• 优化前先 profile（torch.profiler或cProfile）；
• 关注大张量的内存效率，性能关键路径可考虑torch.jit.script或torch.compile。

9.2 基准测试

性能相关改动遵循 benchmarks/README.md 的方法论契约与新增基准清单，使用 benchmarks/common.py 中的辅助函数；基准应调用公开 kornia API，而不是内嵌替代实现；性能改动需在基线与改动分支上跑同一基准对比。

9.3 ONNX 专项

ONNX 在 Kornia 中是完整子系统而非导出附庸：改动导出行为前先检查 kornia/onnx/、kornia/core/ 中的 mixin 与既有 ONNX 测试；开发依赖可选的onnx、onnxruntime、onnxscript包；同时影响图构建/导出与运行时行为的改动需要两种测试。

十、AI 协作与项目文化

Kornia 对 AI 辅助持开放态度（CONTRIBUTING.md 明确写道："You may use AI to do the work — so do we"），但要求认真对待产出：像检查自己写的代码一样检查 AI 输出，并在 PR 中简要说明 AI 帮了什么、你随后改了哪些、自己核对了什么——不需要百分比或归属类别。

AGENTS.md 则是给编码 Agent 的日常操作手册，涵盖项目结构（kornia/geometry/、kornia/filters/、kornia/augmentation/、kornia/feature/ 与 kornia/models/、kornia/onnx/、kornia/core/）、导入顺序注意事项（kornia/__init__.py中filters与geometry先于依赖它们的模块加载，改动导出时需检查循环导入）以及可编辑安装下的分支对比陷阱（比较脚本应放在 worktree 根目录以 stdin 或-c方式运行，并打印kornia.__file__确认导入的是目标树）。

十一、许可证与赞助

通过贡献，你同意以 Apache License 2.0 授权你的贡献（见 LICENSE）。如果写代码不是你的强项，也可以考虑通过 Open Collective 或 GitHub Sponsors 赞助项目；维护者同时欢迎 CUDA 服务器捐赠用于测试。详见 sponsor 页面。

小结：贡献清单速查

提交 PR 前，逐项核对：

1. 已搜索既有 issue/PR，改动聚焦单一主题；
2. 环境已就绪：pixi install+pixi run -e default install；
3. 已通过pixi run lint、pixi run pre-commit-all、pixi run typecheck；
4. 已运行相关测试（pixi run test-module tests/<path>），dtype/device 覆盖合理；
5. 新公开 API 已添加类型注解、docstring 与 API 文档登记；
6. 用户可见变化已添加changelog.d/<PR>.<type>.md片段；
7. PR 描述按模板填写，包含检查结果与 AI 使用说明。

• 计算机视觉
• 深度学习
• 图像处理