computeledger

ComputeLedger

安装 • 快速入门 • 功能 • CLI 参考 • 比较 • 常见问题

对计算用量进行签名、哈希链式记录并独立验证，可在任意服务提供商之间移植。

ComputeLedger 会将计算任务的用量（GPU 小时数、硬件、时长、工作负载类型）记录为经过加密签名的凭证，并将其追加到具有防篡改能力的本地账本中。任何人都可以验证凭证的真实性和账本的完整性，无需信任签发方，也无需绑定到任何单一云平台、区块链或供应商的技术栈。

安装

npm install -g computeledger-cli

pip install computeledger-cli

这两个软件包都会安装同一个 computeledger 命令。两种方式生成的凭证都可以互操作：由 npm 二进制文件签名的凭证可由 PyPI 二进制文件正确验证，反之亦然。

快速入门

$ computeledger keys generate --local
Generated Ed25519 keypair.
Public key: COxK/lkoWxWB42QKXjvcHnmBPozH4Oo2JHoOKDjsoU8=
Private key: ./.computeledger/keys/ed25519.pem (mode 600)

$ computeledger record --local --provider aws --hardware nvidia-h100 \
    --duration-seconds 3600 --gpu-hours 1 --workload-type training
Recorded usage receipt 39952199-0897-48b8-92c5-e351f773c83d.

$ computeledger ledger verify --local
Ledger valid: 1 entries, unbroken hash chain.

或者直接包装真实任务，无需手动调用 record：

computeledger run --local --provider on-prem --hardware nvidia-a100 -- python train.py

run 会将包装的命令作为真实子进程执行（绝不通过 shell），测量实际运行时长，在存在 nvidia-smi 时采样 GPU 利用率，并自动签名和追加生成的凭证。在没有 NVIDIA GPU 的计算机上，它仍会生成仅包含时长的凭证。

将凭证交给任何人、在任何计算机上验证，无需 ComputeLedger 账户，也无需网络请求：

computeledger verify receipt.json

为何创建此项目

多云和多服务提供商的 GPU 用量缺少可移植、可验证的记录。成本仪表板只能告诉你服务提供商声称你用了多少资源，却无法让第三方独立确认记录事后未被篡改，而且只适用于与其集成的服务提供商。ComputeLedger 是一种轻量级、与服务提供商无关的证明格式：任何能运行 CLI 命令或调用 MCP 工具的进程都可以生成凭证；任何语言中的任何进程都可以验证凭证。

本项目的定位刻意保持狭窄。它不与 GPU 市场、成本仪表板或机密计算平台竞争，这些产品各自承担不同且实际的工作。具体界限请参阅下文的比较。

功能

• 通过 Node 内置库和 Python 标准加密库实现 Ed25519 签名。 不使用自定义加密方案，TypeScript 端也没有外部加密依赖。
• 哈希链式账本。 每张收据都包含上一张收据的哈希。删除、重排或编辑历史条目都会破坏哈希链，ledger verify 可以检测到这一点，即使被篡改条目自身的签名看起来仍然有效。
• 从设计上确保跨语言互操作。 由 npm 包的 computeledger 二进制文件签名的收据，可通过 PyPI 包的 computeledger 二进制文件正确验证。两种实现都会在哈希计算前，通过相同的确定性规范 JSON 算法序列化收据载荷。
• 与提供商无关。 无需账户或 API 密钥，也不依赖任何特定云服务或区块链。在笔记本电脑、本地集群或任何云 VM 上的运行方式都相同。
• 面向 Agent 原生设计。 每个子命令都支持 --json，用于输出结构化内容；computeledger mcp 会启动一个 Model Context Protocol 服务，提供可调用的 record_usage、verify_receipt、list_ledger 和 verify_ledger 工具。
• 不存在 Shell 注入攻击面。 computeledger run -- <command> 通过参数数组执行被包装的命令，而不是使用 Shell 字符串，因此被包装命令中的元字符不会产生作用。

CLI 参考

computeledger keys generate [--local]
computeledger keys show [--local] [--json]
computeledger run [--local] [--provider <name>] [--hardware <type>] [--workload-type training|inference|unknown] [--no-record-command] [--json] -- <command...>
computeledger record --provider <name> --hardware <type> --duration-seconds <n> [--gpu-hours <n>] [--flops <n>] [--workload-type <type>] [--local] [--json]
computeledger verify <receipt.json> [--json]
computeledger ledger list [--local] [--json]
computeledger ledger show <id> [--local] [--json]
computeledger ledger verify [--local] [--json]
computeledger export --format json|csv [--out <file>] [--local]
computeledger mcp

标志	含义
--local	使用当前目录中的 ./.computeledger，而不是 ~/.computeledger
--json	在 stdout 输出结构化 JSON，而不是人类可读文本
--no-record-command	不在收据中记录被包装的命令字符串（仅限 run）

MCP 服务

ComputeLedger 提供了一个 Model Context Protocol 服务，让 AI Agent（Claude、Cursor 或任何兼容 MCP 的客户端）可以直接记录和验证计算用量收据，无需人工手动调用 CLI。Python 包将该服务作为子命令提供，而不是单独的控制台脚本，因此实际调用方式是 computeledger mcp，而非 computeledger-mcp。

pip install computeledger-cli

将其添加到 MCP 客户端的配置中（对于 Claude Desktop，请使用 claude_desktop_config.json）：

{
  "mcpServers": {
    "computeledger": {
      "command": "uvx",
      "args": ["--from", "computeledger-cli", "computeledger", "mcp"]
    }
  }
}

该服务提供四种工具，与 CLI 一一对应：

• record_usage(provider, hardware, durationSeconds, gpuHours?, estimatedFlops?, workloadType?, local?)：使用本地 Ed25519 密钥对用量条目签名，将其追加到哈希链式账本，并返回已签名的收据。
• verify_receipt(receipt)：独立验证收据的签名和哈希完整性。
• list_ledger(local?)：列出本地账本中记录的所有收据。
• verify_ledger(local?)：验证每个条目的签名，以及整个账本中未中断的哈希链。

调用示例：

record_usage(provider="lambda-labs", hardware="nvidia-h100", durationSeconds=3600, gpuHours=1, workloadType="training")

传输方式为 stdio，因此无需托管：MCP 客户端会将服务作为本地子进程启动。源代码：python/src/computeledger/mcp/server.py。

npm 包通过原生 TypeScript 服务（src/mcp/server.ts）提供相同的四种工具，调用方式相同，使用 npx computeledger-cli mcp 即可。两种实现经过交叉验证，可互操作；每种工具返回的结构化 JSON 格式也与 CLI 的 --json 模式相同。

库 API

import { createReceipt, verifyReceipt, Ledger, verifyChain, loadKeyPair, resolvePaths } from "computeledger-cli";

from computeledger import create_receipt, verify_receipt, Ledger, verify_chain, load_key_pair

对比

ComputeLedger 填补了一个范围狭窄而明确的空白：提供可移植、可通过加密方式验证的使用凭证，无需采用任何单一提供商的链或平台。它并非要取代下列工具；这些工具各自都有不同的实际用途。

	ComputeLedger	SkyPilot	OpenCost	AICert
定位	已签名、可移植的使用凭证	多云任务编排 + 成本管理	Kubernetes/云成本监控	训练来源证明
加密验证	是（Ed25519，可离线验证）	否	否	是（基于 TPM）
提供商锁定	无	编排特定云平台	Kubernetes/云原生	无
防篡改历史记录	是（哈希链式账本）	否	否	否（单个产物，无链）
GitHub 星标数	新项目	10,441	6,659（CNCF）	20
项目活跃度	活跃	活跃	活跃	自 2024 年 6 月以来没有提交
面向 Agent 原生（MCP/--json）	是	部分支持（API/SDK）	否	否

SkyPilot 和 OpenCost 解决了相邻领域的实际问题（跨云运行任务，以及展示任务的成本），且其规模和成熟度远高于本项目。它们都不会生成已签名、可独立验证的使用记录。AICert 曾尝试将训练计算来源证明作为独立的 OSS 工具，采用基于 TPM 的证明机制，但自 2024 年 6 月以来没有提交；ComputeLedger 的范围则刻意设得更窄（提供使用凭证，而非完整的训练来源证明框架），并从第一天起同时发布 npm 和 PyPI 软件包，正是为了让凭证格式不局限于某一种语言的生态系统。

ComputeLedger 是什么？它为何存在？

ComputeLedger 是一个开源 CLI、库和 MCP 服务，用于生成并验证经过加密签名的计算用量记录。它之所以存在，是因为目前计算用量声明（消耗的 GPU 小时数、使用的硬件、工作负载时长）没有可移植、可离线验证的证明格式：计费仪表板的可信度取决于出具它的提供商，而且只涵盖该提供商。ComputeLedger 的凭证是自包含的已签名 JSON 对象，任何参与方都能在任何机器上，通过两种独立维护的语言实现之一进行验证，无需网络调用或可信第三方。

常见问题

ComputeLedger 是否需要账户或 API 密钥？ 不需要。所有操作都在本地运行。密钥会在你自己的机器上生成并存储（~/.computeledger，或使用 --local 时存储在 ./.computeledger）。

收据能伪造吗？ 如果没有用于签名的私钥，就无法伪造。verify 会重新计算载荷哈希，并使用嵌入的公钥检查 Ed25519 签名；公钥本身也是签名载荷的一部分，因此替换成其他密钥会改变哈希，使收据失效。

如果没有 GPU，会发生什么？ computeledger run 会平稳降级：记录墙钟时间以及你指定的 --hardware/--provider，如果找不到 nvidia-smi，则会直接省略 GPU 利用率采样。

这会与 SkyPilot 或 OpenCost 竞争吗？ 不会，参见上方的对比表。这些工具解决的是编排和成本可视化问题；ComputeLedger 解决的是对用量声明进行独立验证的问题。两者互为补充：使用 SkyPilot 或 OpenCost 进行编排和成本管理，并在需要签名记录的地方使用 ComputeLedger。

收据格式是区块链吗？ 它是一个本地的哈希链式只追加日志，理念类似 Merkle 日志或 git 提交链。它不涉及代币、共识机制或网络。

ComputeLedger 能在 Windows 上运行吗？ npm 和 PyPI 软件包可以在 Node.js 18+ 或 Python 3.10+ 支持的任何平台上安装和运行，包括 Windows。需要注意的是：私钥文件会使用 POSIX 权限位（模式 600）写入，这在 Linux 和 macOS 上会限制访问；Windows 不执行相同的 POSIX 权限模型，因此文件虽然会写入，但相应的访问限制在 Windows 上不起作用。目前 CI 仅在 Linux 上运行，因此上游不会持续测试 Windows 和 macOS。

我可以将 ComputeLedger 用于商业项目吗？ 可以。TypeScript 和 Python 软件包均采用 Apache-2.0 许可证，允许商业使用、修改和再分发，包括用于闭源产品，但须保留许可证和版权声明。

如果我需要多云编排或成本仪表板，该怎么办？ ComputeLedger 不提供这两项功能。它只生成并验证签名用量收据。如果需要这些功能，可将它与 SkyPilot（用于编排）或 OpenCost（用于成本可视化）搭配使用。

参与贡献

欢迎提交问题和拉取请求。提交 PR 前，请运行 npm test（TypeScript）或 pytest（python/）：两种语言的实现都附带完整的测试套件，任何涉及收据或规范 JSON 格式的更改，都必须确保两端保持互操作（参见 CONTRIBUTING.md）。

许可证

Apache-2.0