Model Ledger

model-ledger

模型的 git ——了解你部署了哪些模型、它们运行在哪里、依赖什么，以及发生了哪些变化。

📖 文档 · 快速入门 · 概念 · 治理

---

model-ledger 是一款适用于任何部署了模型的组织的模型清单工具。它能跨平台发现模型、启发式规则和 ETL，自动绘制依赖关系图，并将每次变更记录为不可变事件。与绑定单一平台（MLflow、SageMaker、W&B）的注册表不同，它覆盖所有平台——将它们整合为一张互联的图，并支持通过原生 MCP 服务由 AI Agent 驱动。

经生产规模基准测试：在包含 28.8k 个模型和 212k 个事件的账本上完整重建清单，耗时不到一秒（CHANGELOG，v0.7.4）。

安装

pip install model-ledger

图谱自动构建

每个模型都是一个带有类型化输入和输出端口的 DataNode。当输出端口名称与输入端口名称匹配时，connect() 会创建依赖边——无需手动连线。

from model_ledger import Ledger, DataNode

ledger = Ledger()

ledger.add([
    DataNode("segmentation", platform="etl",      outputs=["customer_segments"]),
    DataNode("fraud_scorer", platform="ml",       inputs=["customer_segments"], outputs=["risk_scores"]),
    DataNode("fraud_alerts", platform="alerting", inputs=["risk_scores"]),
])
ledger.connect()

ledger.trace("fraud_alerts")
# ['segmentation', 'fraud_scorer', 'fraud_alerts']

每次变更都会记录为不可变的 Snapshot——一种仅追加的事件日志，可提供完整历史记录并支持按时间点重建，因为任何内容都不会被覆盖。

与你的清单交互

MCP 服务是一流的使用入口——让 Claude（或任何 MCP Agent）连接到它：

pip install "model-ledger[mcp]"
claude mcp add model-ledger -- model-ledger mcp --demo

**你：**如果我们弃用 customer_features，会有什么影响？

**Claude：**有 3 个模型直接使用它，另外还有 2 个模型间接使用它。

文档

所有内容都托管在 block.github.io/model-ledger 上——API 参考由源代码生成，且每个示例都会在 CI 中运行，因此文档不会与实际实现脱节：

• 快速入门 ——从安装到追踪第一个依赖，仅需 60 秒
• 概念 ——通过三个概念了解 DataNode、Snapshot 和 Composite
• Agent（MCP） ——包含完整对话示例的八工具 Agent 接口
• 连接器 ——从 SQL、REST、GitHub 或你自己的平台中发现模型
• 后端 ——内存、SQLite、JSON、Snowflake 或远程 HTTP
• 治理 ——了解这些基本组件如何映射到 SR 11‑7/SR 26‑2、EU AI Act 和 NIST AI RMF
• API 参考 ——由源代码生成

架构

flowchart LR
    subgraph Sources
        C1[SQL / REST / GitHub / Prefect<br/>connectors]
    end
    subgraph Core
        L[Ledger<br/>append-only event log,<br/>point-in-time reconstruction]
        G[Dependency graph]
        V[Compliance profiles<br/>SR 11-7/SR 26-2 · EU AI Act · NIST AI RMF]
    end
    subgraph Surfaces
        S1[Python SDK]
        S2[CLI]
        S3[REST API]
        S4[MCP server · 8 tools]
    end
    B1[(in-memory · SQLite · JSON ·<br/>Snowflake · remote HTTP)]
    C1 --> L
    L --> G
    L --> V
    L --- B1
    S1 --> L
    S2 --> L
    S3 --> L
    S4 --> L

面向组织

开源核心负责发现、图谱构建、变更跟踪、存储、Agent 协议和合规性验证——SR 11‑7/SR 26‑2、EU AI Act Annex IV 和 NIST AI RMF 配置已包含在 model_ledger.validate 中。你的内部包只需在此基础上提供轻量级功能：连接器配置、面向内部平台的自定义连接器，以及凭据。保持配置精简，无需重新实现逻辑。

贡献

请参阅 CONTRIBUTING.md。 所有提交都必须通过 DCO 签署。

安全

有关如何私下报告漏洞，请参阅 SECURITY.md。

许可证

Apache-2.0。请参阅 LICENSE。

由 Block 的 Vignesh Narayanaswamy 创建并维护。