人工智能深度学习机器学习【免费下载链接】onnxOpen standard for machine learning interoperability项目地址https://gitcode.com/gh_mirrors/onn/onnx点击查看免费下载ONNXOpen Neural Network Exchange是面向 AI 模型互操作性的开源标准代码库由 Python 与 C 组成并借助 protobuf 完成模型序列化。本文以仓库根目录的 AGENTS.md即 CLAUDE.md — ONNX Project Guide为核心骨架结合 pixi.toml、pyproject.toml、CONTRIBUTING.md 与 SECURITY.md 等仓库实证完整讲解该项目面向开发者与 AI 助手的工程约定从环境搭建、编译安装、测试与代码检查到自动生成文件管理、C/Python 边界划分与安全披露流程。读完本文你将掌握一套可直接复现的 ONNX 本地开发闭环并理解为什么这个开放标准项目对规范级改动如此谨慎。一、文档定位AGENTS.md 是 ONNX 的开发总纲AGENTS.md 表面上是一份供 AI 助手阅读的指导文件标题即 CLAUDE.md实际上浓缩了 ONNX 仓库的全部开发守则。它开篇就点明项目的技术底色技术栈Python C 双语言代码库使用 protobuf 进行序列化跨平台构建与运行覆盖 Linux、macOS、Windows 三大平台任何改动都必须同时考虑三者协作入口提交、推送、提 issue 或开 PR 之前必须先阅读 CONTRIBUTING.md其中定义了 PR 流程、分支/CI 预期与代码风格安全边界撰写 bug 报告或评估严重性时先查看 SECURITY.md 的披露策略——使用广泛可用工具即可发现的普通 bug 可以直接开公开 issue 或 PR而非平凡的安全漏洞必须通过 GitHub Security Advisories 私下报告不能走公开 issue。从源码结构看这份文档与仓库的规范驱动设计一脉相承onnx/目录下同时存在 onnx.proto、onnx-ml.proto、onnx-operators.proto 等多份协议定义而 onnx/gen_proto.py 负责从.in.proto模板生成它们——规范的每一次变动都会波及整个 ML 生态这正是 AGENTS.md 反复强调保守、慎重的根因。二、项目规范开放标准下的七条铁律AGENTS.md 的 Project Norms 部分给出了七条项目级规范它们共同定义了在 ONNX 里如何做正确的改动遵循行为准则所有生成的代码、注释、提交信息、PR 描述必须专业、友好禁止敌意、歧视或贬损性语言开放标准的保守性算子定义、proto schema 或 IR 规范的改动会影响整个 ML 生态必须保守、深思熟虑厂商中立代码与注释中不得偏向任何特定框架、运行时或硬件向后兼容规范或公开 API 的破坏性变更会带来超乎寻常的生态影响贴合现有模式改动前先阅读周围代码匹配既有代码风格与约定PR 聚焦不打包无关改动不在任务范围外做重构新增算子走流程必须遵循 docs/AddNewOp.md 的完整流程。此外还有一条依赖政策默认不引入新依赖如果确有必要新依赖必须是 MIT 或 Apache-2.0 许可并且应先与维护者沟通而不是单方面添加。这与仓库根目录 LICENSES 目录维护 Apache-2.0 与 BSD-2-Clause 两份许可文本的做法相互印证——ONNX 对许可证合规是显式管理的。三、构建指南两种开发安装方式AGENTS.md 给出了两种构建路径日常开发优先推荐 pixi无 pixi 时退回原生 pip。3.1 原生 pip 开发安装pip install -e . -v # 开发安装 ONNX_BUILD_TESTS1 pip install -e . -v # 连带 C 测试一起构建-eeditable实现可编辑安装-v输出详细日志纯 Python 改动在可编辑安装下立即生效C 改动需要重新构建构建产物统一落在.setuptools-cmake-build/目录历史原因沿用此名见 pyproject.toml 中[tool.scikit-build]的build-dir配置。3.2 pixi 可复现构建推荐如果环境中装有 pixi用pixi run install pixi run pytest # 运行全部 Python 测试 pixi run gtest # 运行 C googletest 测试 pixi run gen-all # 重新生成所有自动生成文件从 pixi.toml 可以还原这些任务的真实定义install任务的底层命令是pip install --no-deps --ignore-installed --verbose --no-build-isolation --force --editable .并在构建后把.setuptools-cmake-build/onnx/onnx_pb.py和*_pb2.pyi接口文件拷贝回onnx/目录——这是因为编译过程自动生成的.pyi接口文件不会进入 git而 mypy 会优先搜索onnx/目录缺失会导致类型检查报错pixi.toml 的注释详细解释了这一历史遗留问题install环境变量固定为ONNX_ML1、ONNX_BUILD_TESTS1并通过CMAKE_EXTRA_ARGS传入-DONNX_USE_PROTOBUF_SHARED_LIBSON -DONNX_HARDENINGON -DONNX_WERRORON开启加固并把警告视为错误gtest在 Windows 上使用不同路径.setuptools-cmake-build/Release/onnx_gtests.exe印证了 AGENTS.md keep all three platforms in mind 的跨平台要求gen-all依赖gen-docs运行 onnx/defs/gen_doc.py、gen-operator-coverage运行onnx/backend/test/stat_coverage.py与gen-proto运行 onnx/gen_proto.py三个子任务。四、测试指南Python 与 C 双测试体系AGENTS.md 给出的测试命令如下pytest # 所有 Python 测试 # C 测试需先用 ONNX_BUILD_TESTS1 构建 # Linux/macOS: LD_LIBRARY_PATH./.setuptools-cmake-build/ .setuptools-cmake-build/onnx_gtests # Windows: .setuptools-cmake-build\Release\onnx_gtests.exe几个值得注意的细节测试目录约定测试集中在tests/下命名遵循*_test.py。仓库实测可见 tests/python 下的 basic_test.py、checker_test.py、shape_inference_test.py 等文件以及 tests/cpp 下的 checker_test.cc、shape_inference_test.cc 等 C 测试pytest 默认行为在 pyproject.toml 的[tool.pytest.ini_options]中addopts --tbshort --coloryestestpaths [tests]即默认只扫描tests/目录C 测试依赖动态库路径Linux/macOS 下需要把构建目录加入LD_LIBRARY_PATH才能正确加载 protobuf 等动态链接库运行 C 测试的 pixi 方式直接pixi run gtest其定义见 pixi.toml 的[tasks.gtest]。五、代码检查lintrunner 是完成任务的硬门槛AGENTS.md 明确要求lintrunner 必须零错误通过一个编码任务才算完成。lintrunner init # 首次安装并初始化 lintrunner # 检查改动的文件 lintrunner -a # 自动修复从 .lintrunner.toml 可见它实际集成了多类检查器RUFFruff 代码检查与格式化、mypy_lintermypy 类型检查tests/**被排除、clang-formatC 格式化、editorconfig_checker_linter以及 AGENTS.md 提到的命名空间检查器对应 tools/check_namespace.py。配置中merge_base_with main意味着默认以main分支为基线检查改动。六、代码规范每个文件都要遵守的硬性要求AGENTS.md 定义了四条不可妥协的编码约定且都有对应的工具化强制所有 Python 文件必须包含from __future__ import annotations——该规则通过 pyproject.toml 中 ruff 的isort配置required-imports强制实施禁止相对导入统一从onnx使用绝对导入——pyproject.toml 中[tool.ruff.lint.flake8-tidy-imports]设置ban-relative-imports all将其变为 lint 错误文件头版权声明# Copyright (c) ONNX Project Contributors# SPDX-License-Identifier: Apache-2.0仓库几乎所有源文件包括 onnx/cpp2py_export.cc、onnx/defs/gen_doc.py 等都带有这一头部DCO 签名所有提交必须git commit -s签署 Developer Certificate of Origin。补充说明从 pyproject.toml 的 ruff 配置可以看到更细的规则面——lint.select启用了 pydocstyle、bandit安全、flake8-bugbear、mccabe 复杂度等数十个规则族max-args 13是保留给compose.merge_models这类历史兼容签名的上限per-file-ignores对onnx/reference/ops/**、tests/python/**、onnx/fuzz/**等目录单独放宽了魔法数字、print、参数数量等限制体现了测试与参考实现从宽、核心库从严的策略。七、自动生成文件改源不改为CI 兜底校验AGENTS.md 用一张表明确了哪些文件是生成的、谁是它们的唯一事实来源生成文件事实来源重新生成命令docs/Operators.md、docs/Changelog.md、docs/TestCoverage.mdonnx/defs/下的算子 schemapython onnx/defs/gen_doc.pyonnx/*_pb2.py、onnx/*_pb.h、onnx/onnx_data.protoonnx/onnx.in.proto 等模板python onnx/gen_proto.py核心规则是编辑.in.proto模板文件而不是.proto成品文件新增或修改算子 schema 时三个生成脚本都要跑一遍。CI 会验证这些生成文件是否与源保持同步——这正是 AGENTS.md Do Not Edit 一节的用意。从源码进一步印证onnx/defs/gen_doc.py 从onnx.defs读取算子 schema聚合后端示例实现与测试片段collect_snippets、collect_sample_implementations按 domain 区分渲染-ml变体文档onnx/gen_proto.py 内含autogen_headerWARNING: This file is automatically generated! Please edit onnx.in.proto.以及// #if ONNX-ML/// #else/// #endif条件块处理逻辑——仓库中 onnx/onnx.in.proto 通过该脚本的--ml开关展开出 onnx-ml.proto。注意不要直接编辑onnx/*.proto成品否则下一次gen_proto.py运行会覆盖你的改动。pixi 用户可用pixi run gen-all一键完成文档、覆盖率与 proto 的全部再生成。八、C/Python 边界哪些核心是原生实现AGENTS.md 明确划分了语言边界理解这一点对定位代码非常关键能力实现位置语言核心校验checkeronnx/checker.cc等C经 nanobind 暴露形状推断onnx/shape_inferenceC版本转换onnx/version_converterC算子 schema 定义onnx/defsC辅助工具、参考实现、parser、composeonnx/下对应模块纯 PythonPython 侧的类型声明集中在 onnx/onnx_cpp2py_export内含checker.pyi、defs.pyi、shape_inference.pyi、version_converter.pyi等。绑定入口 onnx/cpp2py_export.cc 使用nanobind将 checker、schema、shape inference、parser、printer、inliner、version converter 等 C 模块桥接到 Python——文件开头的ONNX_DEFINE_TYPE_CASTER宏即为AttributeProto、TypeProto、TensorProto等 protobuf 类型定义了 Python/C 双向转换器。ONNX_ML 标志ONNX_ML 标志默认开启控制传统 ML 类型sequences、maps、sparse tensors。开启时构建使用onnx-ml.in.proto变体实际对应 onnx/onnx-ml.proto而非纯onnx.in.proto。在 pyproject.toml 中可见ONNX_ML {env ONNX_ML, default ON}即未显式设置环境变量时默认启用而 pixi.toml 的install任务也固定ONNX_ML1。这解释了为什么 ONNX 同时发布 onnx 与 onnx-ml 两套协议变体——传统机器学习算子如 tree ensemble、SVM 分类器见 onnx/reference/ops/aionnxml只有在 ML 变体中才可用。九、安全披露与协作流程动手前的最后检查AGENTS.md 指向的两份配套文档值得单列说明CONTRIBUTING.md除了 PR 流程还推荐了完整的 pixi 开发体验——pixi run install可编辑安装、pixi run pre-commit-install安装与 CI 完全一致的 pre-commit 钩子、pixi run gen-all/pixi run gtest/pixi run pytest/pixi run lint/pixi run docs-build的常用任务清单。非 pixi 用户则走pip install -e . -v的原生路径SECURITY.md披露策略的落地细节——容易发现的 bug 走公开 issue/PR非平凡漏洞走 GitHub Security Advisories 私密报告维护者邮箱onnx-securitylists.lfaidata.foundation作为备选。受理后按 Confirm确认并指派负责人→ Triage按 CVSS 评估只有确认可被利用且有实际影响才签发 CVE→ Fix私密分支修复并由第二位维护者复核→ Disclose合并修复并发布公告四步走Critical/High 级别漏洞或活跃利用会触发计划外补丁发布。这两份文档与 AGENTS.md 共同构成完整的贡献闭环动手前看规范AGENTS.md→ 了解流程CONTRIBUTING.md→ 安全分级SECURITY.md→ 构建测试pixi/pip→ lint 清零 → 生成文件同步 → 提交签名 → 发起 PR。十、小结AGENTS.md 虽然篇幅不长却是理解 ONNX 仓库工程文化的最高效入口。把它与 pixi.toml、pyproject.toml、.lintrunner.toml、CONTRIBUTING.md 等文件对照阅读可以得出三个关键结论ONNX 是规范优先的项目算子 schema、proto 与 IR 的任何变更都牵动整个 ML 生态因此 AGENTS.md 要求保守改动、向后兼容、新增算子走 docs/AddNewOp.md 流程并用 CI 校验自动生成文件是否同步开发体验是可复现的pixi 提供了从 install、pytest、gtest 到 gen-all、lint 的一站式任务清单原生 pip 路径作为无 pixi 时的回退方案同样完整质量门槛是工具化的lintrunner 聚合 ruff、mypy、clang-format、editorconfig 与命名空间检查并以零错误作为任务完成标准——所有规范都以可执行的配置落到了仓库文件中。对希望为 ONNX 贡献代码的开发者或需要在该仓库中工作的 AI 助手而言按照规范 → 构建 → 测试 → lint → 生成文件 → 提交的顺序执行即可快速进入高效、合规的开发节奏。赞分享人工智能深度学习机器学习【免费下载链接】onnxOpen standard for machine learning interoperability项目地址https://gitcode.com/gh_mirrors/onn/onnx点击查看免费下载相关推荐Transformer Lab 开发协作规范全解从 AGENTS.md 读懂构建、测试与代码贡献流程Transformer Lab 开发协作规范全解从 AGENTS.md 读懂构建、测试与代码贡献流程 Transformer Lab 是一个面向 AI 研究者人工智能大模型微调模型评测本地部署模型推理服务LLMOps前端后端Helm 源码仓库开发指南从 AGENTS.md 读懂代码结构、构建测试与贡献规范Helm 源码仓库开发指南从 AGENTS.md 读懂代码结构、构建测试与贡献规范 Helm 是使用 Go 编写的 Kubernetes 包管理器它通过 C云原生容器编排CLI运维Polar SDK 生成器开发与贡献指南AGENTS.md 中的代码规范、构建流程与测试工作流Polar SDK 生成器开发与贡献指南AGENTS.md 中的代码规范、构建流程与测试工作流 导读 本文以 sdk/generator/AGENTS.md后端前端金融科技上一篇Stable Diffusion Akashic Records高级技巧如何通过种子编辑创造一致性角色形象下一篇theZoo SQLite3迁移数据库性能优化与查询效率提升创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考