DEEPBOM

DEEPBOM

DEEPBOM 是一款用于分析已部署 AI 模型制品的本地静态分析器。它会审查序列化图、张量、量化、内存、兼容性和 ML-BOM 证据，不会上传模型数据。

它是多格式制品证据生成器、外部接口契约验证器，也是边界明确的 BOM 与制品核对工具。它不是官方参考实现、完整的 BOM 验证器，也不是法规合规验证器。

公开源码分发版本支持 TFLite、ONNX、GGUF、SafeTensors、Core ML 和有限范围的 ExecuTorch 制品。分析结果会区分观察到和推导出的制品事实、预测的兼容性、导入的运行时证据，以及无法通过静态分析评估的值。

Evidence IR

DEEPBOM Evidence IR 是通用表示系列：Artifact IR、Model IR、可选的 Weight IR、Activation IR、Training IR、Snapshot IR 和 Provenance IR。该草案规范包含生成的架构目录、兼容性检查和公开维护规则。

搜索输入 → IR → 输出映射，或查看 GitHub 上相同的版本化目录。这是由 DEEPBOM 维护的规范，并非获得外部认可的标准。制品元数据路径保留了 deepbom.provenance_ir.v1 及其 provenance_ir 选择器。新增的 Snapshot 工作流使用类型化的 deepbom.provenance_ir.v2 引用来表示原生状态、数据集发布版本和配置。现有文档哈希会予以保留；已弃用的名称仍不受支持。请参阅迁移规则。

对于模型变更审查，请使用合成双人群示例和浏览器证据审查。Web、CLI、Node/Python SDK 和本地 MCP 使用相同的检查项。外部测量仍属于外部证据；满足标准并不能证明其适合临床用途。

快速开始

对于导出流水线、实验跟踪和发布检查，请参阅新版 Node/TypeScript 和 Python SDK 契约以及三个可执行集成示例。受支持的 SDK 从 DEEPBOM 2.1.0 开始提供；较早的 npm 2.0.0 软件包不包含此入口点。使用 npm install [email protected] 安装。

无需克隆仓库即可运行已发布的 CLI（需要 Node.js 20 或更高版本）：

npx deepbom audit "https://raw.githubusercontent.com/JunHwan-Kwon/deepbom/main/web/samples/gpu_partition_probe.onnx#sha256=82a2feef00eb6ab03d82f2b30cd17f4d826e2d8307cb059eccd6a0f3120059b2"

固定的预期值和独立验证器位于 examples/expected-output。构建源码需要 Rust；Python 渠道还需要 Python 3.9 或更高版本。维护者设置说明另见下文。

助手集成

预览受管理文件后，安装仓库本地的 Agent Skill：

npx -y [email protected] integrate codex
npx -y [email protected] integrate codex --apply
npx -y [email protected] integrate claude-code
npx -y [email protected] integrate claude-code --apply

该 Skill 可让本地 Agent 针对受支持的部署制品问题，选择符合契约的分析器。它不会创建或调用托管分析服务。请参阅 Agent 设置指南、机器可读的能力契约，以及独立的引擎／Agent／证据版本策略。

已安装的 Skill 会依次检查 DEEPBOM_BIN、软件包内置的分析器，以及 PATH 中已有的 deepbom。只有在声明的 deepbom.agent_contract.v2 和证据契约均匹配，并且自检确认了确切的观测引擎版本后，它才会接受该运行时。除非显式提供 --allow-download，否则验证器不会联系 npm。这样可以避免将受阻的注册表查询误认为制品分析失败。

如需持久访问工具调用，请通过 stdio 将同一分析器作为 MCP 服务运行：

npx -y [email protected] mcp

它会暴露 deepbom_capabilities、deepbom_audit、deepbom_diff 和 deepbom_explain_rule，不会上传制品字节，也不会使用托管分析端点。审计调用默认返回有长度限制的人工可读摘要；详细格式和大模型扫描深度需要显式指定。除非配置了 DEEPBOM_MCP_ALLOWED_ROOTS，否则本地路径仅限启动目录。 面向 Agent 的使用指南见 DEEPBOM 技能。 Claude Desktop 用户也可以从对应的 GitHub Release 安装版本匹配的 deepbom-2.5.0.mcpb 制品。该安装包包含与 npm 渠道相同的 CLI 和 WASM 字节，并要求用户选择唯一可读取的本地目录。

如需在 ChatGPT 中分析单个附件，请连接单独设限的 Streamable HTTP 端点 https://deepbom.org/mcp。其浏览器组件会在 ChatGPT 沙盒中执行分析，并返回有长度限制、绑定哈希的结果；DEEPBOM 服务不会获取或保留模型字节。此路径已准备好接受开发者模式审核，而 ChatGPT 公共发现功能仍需通过 OpenAI 审核。请参阅 ChatGPT 集成指南。 对于机密或大型制品、包及其旁文件的闭包、完整导出和重复自动化，请使用本地 CLI 或 stdio MCP。

如需在支持远程 MCP Apps 的 Claude 主机上进行私下测试，请添加单独的 https://deepbom.org/mcp/claude 连接器。它会在 MCP App 中打开一个明确的文件选择器；不会自动读取 Claude 附件。所选字节会保留在浏览器沙盒中，同时向对话返回有长度限制的结果。Claude 公共发现功能仍需通过 Anthropic 审核。请参阅 Claude 集成指南 ；如果派生出的模型事实也必须保留在本地，请使用本地 MCPB 或 CLI。

仓库根目录也是一个可移植的 Agent Plugins 包：plugin.json 标识该 Skill，mcp.json 声明有长度限制的 ChatGPT 附件端点。.codex-plugin/ 下的兼容性清单为尚未迁移到可移植格式的客户端保留相同标识。这些文件用于准备安装和审核；并不代表已列入公共目录或获得平台批准。

由账户所有者负责的 ChatGPT、Claude、Codex 和搜索索引步骤，列于 Agent 分发运维清单。

如需以代码为先进行模型开发，请从 Python 候选循环开始。 它使用随附的原生 API，并区分可训练模型工作流与浏览器端 Structure IDE 中基于源文件的图提案。

经过验证的 2.4.0 发布渠道采用相同的分析实现。npm 和下方的 Linux x86-64 发布 wheel 已发布；其他原生平台和注册表渠道需要各自通过发布验证。

npx [email protected] audit model.onnx --format cyclonedx
npx [email protected] audit model.onnx --format sarif --output deepbom.sarif --gate defects
deepbom capabilities --compact
deepbom self-test
deepbom audit model.onnx --list-sections --compact
deepbom audit model.onnx --section quantization,memory --compact
deepbom explain-rule onnx.conv.output-shape
python -m pip install 'deepbom @ https://github.com/JunHwan-Kwon/deepbom/releases/download/channels-v2.4.0/deepbom-2.4.0-py3-none-linux_x86_64.whl'
deepbom audit model.gguf --compact
deepbom verify model.tflite --contract production-interface.json
deepbom verify model.onnx --bom supplied.cdx.json --render markdown
deepbom contract capture model.onnx -o baseline.interface-contract.json
deepbom diff baseline.gguf candidate.gguf --tensors --render markdown
deepbom capabilities --format agent-text
deepbom explore model.tflite
deepbom placement model.tflite --profiles xnnpack_cpu,tflite_coreml_delegate,litert_qualcomm_qnn
deepbom graph model.onnx --format json --output artifact-graph.json
deepbom audit model.onnx --section model_ir --compact
deepbom visualize model.onnx --view all --orientation portrait -o model-views.zip
deepbom model-summary model.onnx --format table
deepbom model-summary model.gguf --level storage --format markdown
deepbom audit model.onnx --conversion-receipt conversion-receipt.json --format cyclonedx

默认输出适合终端查看的证据摘要。--json 和 --compact 可展示完整格式证据；--format envelope 提供规范的跨格式契约；CycloneDX 1.7 和 OASIS SARIF 2.1.0 是标准投影。选择 --fail-on 时，--policy-output 会记录绑定哈希的门禁结果。--review-policy 会添加按身份限定、会过期的例外，并使执行、覆盖率和发现项策略状态彼此独立。请参阅 docs/CLI_AUTOMATION.md。完整选项清单由可执行文件生成，见 docs/CLI_REFERENCE.md。

CycloneDX 1.7 的使用者应从 metadata.component 读取已分析模型，并从 components[] 读取其他清单成员。 DEEPBOM 不会将 BOM 根节点重复放入附加组件数组。 图 JSON 输出包含保留证据的 deepbom.artifact_ir.v2 台账，以及用于可视化兼容的确定性 deepbom.graph_ir.v1 投影。序列化图、存储拓扑、架构分组、作用域量化、静态放置和导入的运行时证据彼此独立。Method 2.2.0 还会保留可选的、与输出绑定的转换收据，但不会将声明的转换器执行提升为观测证据。它仅实例化实际解码的 TFLite 子图、ONNX 嵌套图／局部函数和 ExecuTorch 主计划，不会展平条件作用域。只有通过与工件绑定的主体引用或主原生算子索引，才能协调运行时节点融合； 绝不会猜测名称。graph_ir.v1 仅保留主作用域，以兼容旧版使用方。v2 JSON Schema 发布于 docs/schemas/deepbom-artifact-ir-v2.schema.json 以及 https://deepbom.org/schemas/deepbom-artifact-ir-v2.schema.json。 转换收据 Schema 发布于 docs/schemas/deepbom-conversion-receipt-v1.schema.json。

新增的预览版 deepbom.model_ir.v1 会将这些冻结的工件事实投影为与格式无关的程序、逻辑值、存储、绑定、量化、架构以及静态／运行时证据词汇。它将来源、依赖、确定性显示顺序和观测到的运行时顺序保留为不同字段。visualize 仅使用此 IR，并生成确定性的单色 ISO A4 SVG 页面、300-DPI 黑白 PNG 衍生图、说明文字旁文件，以及 Word 插入清单。这些是可追溯的工程文档，并非符合标准或获得法规批准的判定。请参阅 docs/MODEL_IR_V1.md。

model-summary 是所有受支持适配器共用的类 Keras 摘要投影。有序列化程序时，它会输出操作行；对于无图权重容器，会输出存储行；对于安全封装，则会明确输出仅含标识信息的结果。它绝不会将序列化常量重新标记为可训练参数，也不会将确定性显示顺序重新标记为观测到的运行时顺序。JSON 使用方可以使用 deepbom.model_summary.v1，该 Schema 发布于 docs/schemas/deepbom-model-summary-v1.schema.json。

公共产品输出使用 CycloneDX 1.7。

verify 会将序列化的外部张量 ABI 与提供的、绑定到工件的生产声明进行比较。diff 使用规范的确定性多目标 TFLite 部署差异台账，而 explore 提供现有的 WASM 重设计 Pareto 搜索，但不会声称模型经过训练后的准确率。严格的自定义 TFLite 目标可通过 --target-profile profile.json 绑定；CLI 会同时记录源文件 SHA-256 和解析后的 Rust 配置 SHA-256。加速器证据与该 CPU 成本配置相互独立。源固定的 TFLite Core ML 和 LiteRT Qualcomm QNN 配置、Core ML MLComputePlan、Edge TPU 和 Qualcomm 编译器报告、TensorRT 解析器／引擎证据，以及 NVIDIA 主机配置，均使用共用的分阶段绑定机制，不会将静态或编译证据提升为观测到的执行。placement 会在同一份守恒图台账上比较所有可用配置，不会凭空设定后端优先级。

Cargo 启动器只会从对应的不可变 GitHub Release 下载与其精确软件包版本和平台匹配的引擎。在缓存或执行前，它会验证发布矩阵、字节长度和 SHA-256 摘要。

构建 npm、独立版、Python 和 Cargo 启动器发布渠道：

npm run build:channels
npm run check:public-package-boundary
npm run check:channels -- --no-build

运行公共正确性检查：

npm run check:cli
npm run check:cli-docs
npm run check:cli-automation
npm run check:formats
npm run check:rust

浏览器工作台可在 deepbom.org 使用。

证据范围

格式成熟度

支持的扩展名并不意味着分析深度相同。TFLite 和 ONNX 具有稳定的可执行图契约。GGUF 和 SafeTensors 具有稳定的容器、存储和架构契约，但不会序列化可执行图。Core ML 和 ExecuTorch 的分析仍处于预览阶段，且受测试样例限制。每种格式的具体解析器、图、量化和部署状态，可通过 deepbom capabilities --compact 在 public_product_contracts 下查看。

格式	公开静态证据
TFLite	FlatBuffer 图和张量契约、量化算术、权重完整性、内存预测、累加器证明、重新设计候选项，以及受源码约束的委派预测
ONNX	Protobuf 图、初始化器和外部数据契约、符号形状推断、操作成本、Q/DQ 和仿射量化，以及兼容执行提供程序的证据包络
GGUF	容器和张量目录完整性、量化编码清单、架构元数据，以及受限的 LLM 内存场景
SafeTensors	张量目录和分片完整性、受配置约束的架构契约、AWQ/GPTQ/HQQ/compressed-tensors 元数据，以及受限的 LLM 内存场景
Core ML	NeuralNetwork 和 ML Program 序列化图、张量/权重编码、部署下限，以及导入的计算计划证据边界
ExecuTorch	受限的 ET12/FT01 计划、受源码约束的可移植调用和已处理负载标识，以及可选的所选构建/后端/算子/二进制认证；执行仍在外部进行
GraphDef / SavedModel	受限的序列化节点、数据/控制依赖项、首个 MetaGraph SignatureDef 张量契约，以及由哈希绑定的包成员关系；不执行图
Keras / PT2	受限的声明式配置/JSON 依赖图；不构造对象、不加载 pickle、不进行降级或原生代码处理，也不声明运行时顺序
HDF5 / PyTorch checkpoint	仅提供安全封装、归档、存储成员和 pickle 风险清单；不声明对象图或可执行模型

静态兼容性无法证明实际的执行提供程序分配、设备延迟、任务准确率、临床有效性或发布就绪状态。运行时声明需要有身份绑定的运行时捕获记录。

详细的格式和加速器边界见 docs/SUPPORT_MATRIX.md。无需分享模型字节即可通过 docs/MODEL_FREE_BUG_REPORTING.md 报告错误。

分发边界

此存储库由经过审核的精确允许列表生成。不包含私有规则包生成器、托管服务基础设施和未发布的研究模块。可强制执行的边界和导出验证方法见 docs/PUBLIC_PRIVATE_BOUNDARY.md。

许可证和引用

公开源码和发布渠道中的软件包采用 Apache License 2.0 许可。第三方模型制品保留其声明的许可证。

请引用：

Kwon, J. (2026). DEEPBOM: Browser-Native Static Analysis of On-Device Neural Network Deployment Artifacts [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.21834508

可选元数据与 OMOP 连接

检查模型后，使用 deepbom audit model.onnx --metadata-template omop -o metadata.json 创建与模型绑定的输入。填写所选 OMOP 5.4/5.5 CDM_SOURCE 行以及机构/版本标识符，然后使用 --metadata metadata.json --evidence-files ./evidence --section provenance_ir --json。通用模板可通过相同的 IR 连接非 OMOP 数据集、队列、代码、运行记录和报告。

Web 元数据工作区提供导入、记录创建、交互式关系图以及 JSON/CycloneDX 下载。本地 MCP deepbom_audit 接受 metadata_template、metadata 和 evidence_files；ChatGPT/Claude 小组件只共享明确请求的计数和摘要。连接仅作为声明：文件哈希和引用一致性无法验证溯源关系或临床适用性。请参阅 OMOP 指南和通用 IR 契约。