NPS-Release

English Version

中文版

Cognon Budget 规范

Version: 0.7 Date: 2026-05-21

1. 概述

Cognon Budget 机制允许 Agent 在请求中声明本次操作的最大 token 消耗上限。Node 据此裁剪响应字段、限制返回条数或拒绝超预算请求。

为解决不同 LLM 的 token 计算差异，NPS 引入 Cognon（CGN） 作为标准化计量单位。

2. Cognon（CGN）

2.1 定义

Cognon（CGN）是 NPS 协议族内部的标准 token 计量单位。各 LLM 的原生 token 通过汇率转换为 CGN。

CGN 定义为两个命名 profile，其合规性要求互不重叠（issue #40）。在线传递的每一个 CGN 值 MUST 明确关联到其中一个且只有一个 profile；对端 MUST NOT 混用两者。

Profile	用途	使用场景
CGN-Estimate	估算、预算提示、遥测、可采样流程	`X-NWP-Budget` 强制、CapsFrame 的 `token_est`、推送流逐事件 `cgn_est` 上报
CGN-Billing	商业结算、争议与冲销处理	计费的计量与对端之间交换的签名计量记录

CGN-Estimate（估算级）

Tokenizer 来源 MAY 为 declared_tokenizer（NPS-3-NIP §5.1）或更高等级。
允许使用 §2.2 的字节数 fallback。
允许采样（详见 §6.2）。
与模型原生计数之间允许 ±5 % 的汇率漂移。
记录无需签名，无需审计日志集成。

CGN-Billing（结算级）

发出 CGN-Billing 记录的 Node MUST 同时满足以下全部要求：

所用 tokenizer MUST 达到 NPS-3-NIP §5.1 定义的 verified_tokenizer 等级。declared_tokenizer、observed_tokenizer_profile 以及 §2.2 的字节数 fallback 均禁止作为计费输入。
每一条计量记录 MUST 由发起 Node 的 NID 签名，并 MUST 持久化到与 NOP §8.3（以及在已部署场景下 NPS-RFC-0004 logging）兼容的审计日志中。
MUST NOT 使用采样。每一个被计费的 CGN 值 MUST 逐条精确计算，不允许估算。
计数 MUST 确定且非近似；§2.3 的 ±5 % 漂移容差不适用，因为计费费率属于精确合同条款，而非估算值。
争议与冲销 MUST 仅凭审计日志即可独立支撑，不得依赖任何易失的 Node 进程态。
汇率表版本 MUST 由双方在会话开始时刻（或更早）互相 pin 定，并记录在签名计量记录中。

发出以 CGN 计价的商业收费时，Node MUST 在线传输与响应头中（详见 §4.2）将其标记为 CGN-Billing。以 CGN-Estimate 形式或不带 profile 标记呈现的收费均不合规结算用途，对端 MAY 直接拒付争议，且无须援引 tokenizer 信任等级。

2.2 默认计算方法（Fallback）—— 仅适用于 CGN-Estimate

当 tokenizer 无法确定时，CGN-Estimate MAY 回退至以下公式：

CGN = ceil(UTF-8_bytes / 4)

UTF-8_bytes 是逻辑载荷以 UTF-8 表达时的字节数（例如 JSON 编码帧的序列化 JSON 字节数）。对于 NCP 二进制等非 JSON 线格式，UTF-8_bytes MUST NOT 取原始线帧字节数——请参见 §2.4 中保留线格式无关性的字段级分解方法。

此公式基于主流 LLM tokenizer 的平均行为（英文约 4 bytes/token，中文约 3 bytes/token），作为最保守的估算基线。

字节数 fallback 在任何情况下 MUST NOT 用于 CGN-Billing。若 Node 无法为某条将被计费的请求解析出 verified_tokenizer，MUST 拒绝为该请求发出 CGN-Billing 记录，并采取以下两种处理之一：(a) 将该路面降级为 CGN-Estimate（仅作不可计费遥测）；(b) 以计费类错误拒绝该请求。

2.3 规范转换 Profile（CGN v1）

规范的模型 token 转换算法为 cgn.v1：

CGN = ceil(((input_tokens * input_weight)
          + (output_tokens * output_weight)
          + (thinking_tokens * thinking_weight))
          * model_coefficient / scale)

缺失的 token 类别均按 0 处理。结果类型为 uint32。默认权重为： input_weight = 1、output_weight = 4、thinking_weight = 2、 scale = 1000、model_coefficient = 1。

Provider / model 系数、未知模型行为和合规测试向量的机器可读权威源是 cgn-profiles.yaml。当前覆盖 DeepSeek chat/reasoner、 OpenAI general/reasoning、Anthropic Haiku/Sonnet/Opus、Ollama 本地模型以及默认 unknown fallback。

未知 provider 或模型 id MUST 使用 default.unknown 作为 CGN-Estimate， SHOULD 发出 cgn_profile_defaulted 遥测警告，且 MUST NOT 用于 CGN-Billing。运维 MAY 在本地覆盖 model-pattern 映射，但此类覆盖 MUST 使用不同的 profile id 或版本，以便对端能区分它们与规范表。

Profile 适用范围。 cgn.v1 与 cgn-profiles.yaml 对 CGN-Estimate 是 normative 的，并允许表内值与模型原生计数之间存在文档化的 ±5 % 漂移。对 CGN-Billing，双方对端 MUST 互相 pin 定一个特定 profile 版本（在会话开始时刻或更早，并记录到签名计量记录中），且 MUST 使用与之匹配的、由 verified_tokenizer 得出的原生计数；±5 % 容差不适用。default.unknown 仅适用于 CGN-Estimate；CGN-Billing 没有 fallback 行。

2.4 线格式无关性（normative）

CGN MUST 在逻辑帧层（序列化之前）计算，且对相同语义内容在任意线格式下的结果 MUST 一致：

线格式	相对 JSON 的大小	CGN
JSON（UTF-8）	100 %（基准）	直接对 JSON UTF-8 字节应用字节公式（§2.2）
NCP 二进制	≈ JSON 的 30–60 %	与等价 JSON 内容的 CGN 相同
MsgPack	≈ JSON 的 50–75 %	与等价 JSON 内容的 CGN 相同

NCP 帧 CGN（CGN-Estimate fallback）。 以 NCP 二进制格式传输帧且无可用的 verified tokenizer 时，Node MUST NOT 以原始线帧字节数作为 §2.2 的字节计数输入，而应采用以下字段级分解：

NCP_CGN = Σ ceil(utf8_bytes(string_field) / 4)    // 所有字符串类型字段
         + Σ 1                                     // 所有数值 / 布尔字段
         + Σ ceil(blob_bytes / 4)                  // 所有二进制 / blob 字段

utf8_bytes(string_field) 为该字段值以 UTF-8 重新编码后的字节长度。 blob_bytes 为 blob 载荷的原始字节长度（不计 base64 或 hex 展开后的长度）。

设计原因。 NPS 交互的主导成本是 Agent 侧的 LLM 推理，其操作对象是解码后的逻辑内容。NCP 二进制编码虽然降低了线路带宽与 Node I/O 成本，却不减少 Agent 的推理 token 负担。将 CGN 绑定到逻辑内容，可确保经济信号追踪实际消耗的资源——即 Agent 注意力——而非传输侧的节省。若 Node 以线字节计费，相同信息下 NCP 调用者将比 JSON 调用者被少收费，破坏公平计量的基础，并使 CGN 依赖于传输格式。

X-NWP-Tokens 与 X-NWP-Tokens-Native 响应头 MUST 反映逻辑层 CGN 计数，而非序列化线字节数。

3. Tokenizer 解析链

Agent 发起请求时，Node 按以下优先级确定 tokenizer：

1. Agent 显式声明（X-NWP-Tokenizer 头）
   ↓ 未声明
2. 从 Agent 配置/IdentFrame 自动匹配
   ↓ 匹配失败
3. 使用默认计算方法（UTF-8 bytes / 4）

3.1 显式声明（优先级最高）

Agent 在请求头中声明 tokenizer：

X-NWP-Tokenizer: cl100k_base

Node MUST 识别声明的 tokenizer 并使用对应算法计算 token。若 Node 不支持该 tokenizer，SHOULD 回退到自动匹配。

3.2 自动匹配

Node 根据 IdentFrame 中的元数据推断 Agent 使用的模型族：

IdentFrame.metadata.model_family：如 "openai/gpt-4o"、"anthropic/claude-4"
IdentFrame.metadata.tokenizer：如 "cl100k_base"

若 IdentFrame 包含以上字段，Node 使用对应的 tokenizer。

估算专用警示（normative —— issue #39）。 metadata.model_family 与 metadata.tokenizer 抵达节点时均属于 NPS-3-NIP §5.1 —— 未签名 metadata 的信任边界定义的 tokenizer 三层信任模型中的 declared_tokenizer 层；§3.1 的 X-NWP-Tokenizer 请求头与之同等信任级别。本节自动匹配出的取值 MUST 仅作为估算提示使用，MUST NOT 驱动计费、结算、配额提升、声誉评分或任何安全相关决策。结算级与策略级流程 MUST 改用 verified_tokenizer（CA 或平台背书）信号；observed_tokenizer_profile 仅可用于 Node 内部滥用检测的回退。基于 declared_tokenizer 计费或授予配额提升的 Node 不合规。

3.3 默认 Fallback

无法确定 tokenizer 时，使用 ceil(UTF-8_bytes / 4) 计算 CGN（非 JSON 线格式请参见 §2.4）。

4. 请求与响应

4.1 请求头

头	必填	描述
`X-NWP-Budget`	可选	最大 CGN 预算（uint32）
`X-NWP-Tokenizer`	可选	Agent 使用的 tokenizer 标识

4.2 响应头

头	Profile	描述
`X-NWP-Tokens`	CGN-Estimate	本响应实际消耗的 CGN（估算级）
`X-NWP-Tokens-Native`	CGN-Estimate	本响应原生 token 消耗（若已知 tokenizer）
`X-NWP-Tokenizer-Used`	两者	Node 实际使用的 tokenizer 标识
`X-NWP-Tokens-Profile`	两者	取值为 `estimate` 或 `billing`。缺省或 `estimate` MUST 由对端视为 CGN-Estimate。
`X-NWP-Billing-Record`	CGN-Billing	指向本响应签名计量记录的引用（URI 或内容哈希）。当且仅当本响应按 CGN-Billing 计费时 MUST 存在。
`X-NWP-Billing-Tokenizer-Tier`	CGN-Billing	MUST 为 `verified_tokenizer`。缺省 → 不可计费。

同时缺失 X-NWP-Billing-Record 与 X-NWP-Billing-Tokenizer-Tier 的响应 MUST 由对端解释为 CGN-Estimate，无论双方是否存在任何商业约定；Node MUST NOT 基于仅含 CGN-Estimate 信号的响应进行结算。

4.3 超预算处理

当响应将超过 X-NWP-Budget 时：

Node SHOULD 优先裁剪响应（减少返回字段或条数），使结果在预算内
若无法裁剪（如单条记录已超预算），Node MUST 返回 NWP-BUDGET-EXCEEDED 错误
Node MUST NOT 静默截断结构化数据（截断可能导致 Agent 收到不完整结构）

5. CapsFrame 中的 token 估算

CapsFrame 的 token_est 字段值为 CGN：

{
  "frame": "0x04",
  "anchor_ref": "sha256:...",
  "count": 2,
  "data": [...],
  "token_est": 180,
  "tokenizer_used": "cl100k_base"
}

6. 实现注意事项

6.1 通用

Node 实现 SHOULD 内置至少 cl100k_base（GPT-4 系列）tokenizer。
汇率表建议作为可热更新配置，不硬编码。
CGN 值始终为 uint32，最大 4,294,967,295。
在线传输的 CGN 值若不带显式 profile 标记，其默认 profile 为 CGN-Estimate。意图采用 CGN-Billing 语义的 Node MUST 按 §4.2 标记响应——沉默从来不是结算信号。

6.2 CGN-Estimate

高频场景下 token 估算 MAY 采样而非逐条计算。采样估值属于观察级信号，与 §3.2 警示对 declared_tokenizer 的限制相同：MUST NOT 单独用于计费、结算、配额提升、声誉或授权。
当 tokenizer 无法解析时，允许使用 §2.2 的字节数 fallback。
与原生计数之间允许 ±5 % 汇率漂移。
CGN-Estimate 记录无需签名、审计日志持久化或争议处理机制。

6.3 CGN-Billing

Node 在发出任何 CGN-Billing 记录之前，MUST 将该请求的 tokenizer 解析至 verified_tokenizer 等级（NPS-3-NIP §5.1）。若解析失败，Node MUST NOT 对该请求计费——见 §2.2。
禁止采样。每一个被计费的 CGN 值 MUST 使用 tokenizer 的原生计数与 pin 定的汇率表项进行逐条精确计算。
每条计量记录 MUST 由发起 Node 的 NID 签名，并 MUST 持久化到与 NOP §8.3（以及在已部署场景下 NPS-RFC-0004 logging）兼容的审计日志中。
审计日志 MUST 仅凭自身即可重建该笔收费、支撑争议 / 冲销处理，并能在 Node 进程重启后存活。
每一条 CGN-Billing 响应 MUST 同时携带 X-NWP-Tokens-Profile: billing、X-NWP-Billing-Record 与 X-NWP-Billing-Tokenizer-Tier: verified_tokenizer 三个响应头（详见 §4.2）。
覆盖 CGN-Billing 记录签名与验证的合规性测试向量将随下一版 AaaS-Profile L3 合规性套件一同发布（跟踪 issue #40）；在该套件正式发布之前，结算级实现 SHOULD 自行公开其签名方案，使对端可独立验证其声明。

7. Node 运营方 CGN 上限（`cgn_limit`）

X-NWP-Budget 是 Agent 声明的单请求上限，而 cgn_limit 是 Node 运营方在服务侧对单次请求可消耗 CGN 的上限。两者独立存在；任意请求的有效预算为：

effective_budget = min(cgn_limit, X-NWP-Budget)   // 0 表示不限制

若 X-NWP-Budget 缺失，则 effective_budget = cgn_limit。若 cgn_limit 为 0（默认值），仅 Agent 提供的 X-NWP-Budget 生效。

7.1 NWM 声明

设置 cgn_limit > 0 的 Node MUST 在 NWM 的 token_budget.cgn_limit 字段中发布该值，使 Agent 在发送请求之前即可发现此上限：

{
  "token_budget": {
    "cgn_limit": 5000,
    "profile": "cgn.v1"
  }
}

7.2 在 `AnchorNodeMiddleware` 中的强制执行

AnchorNodeOptions.CgnLimit（uint32，默认 0）设置单请求的 Node 上限。中间件的执行逻辑：

从请求头读取 X-NWP-Budget（Agent 上限，可能缺失）。
计算 effective_budget = cgn_limit > 0 ? min(cgn_limit, x_nwp_budget_or_max) : x_nwp_budget_or_max。
将 effective_budget 传入响应构建器与 CGN-Estimate 累计器。
若响应的 CGN 合计将超过 effective_budget：优先裁剪（减少字段 / 条数）；若无法裁剪，返回 NWP-CGN-LIMIT-EXCEEDED（HTTP 400，NPS 状态 NPS-CLIENT-REQUEST-TOO-LARGE）。

7.3 CGN-Estimate 与 CGN-Billing 的执行差异

Profile	`cgn_limit` 行为
CGN-Estimate	建议性：Node SHOULD 裁剪；若无法裁剪且超出量已在 `X-NWP-Tokens` 中标记，MAY 允许超出。
CGN-Billing	严格性：Node MUST NOT 发出超过 `effective_budget` 的响应；超出时 `NWP-CGN-LIMIT-EXCEEDED` 是强制要求。

7.4 错误码

错误码	HTTP 状态	NPS 状态	描述
`NWP-CGN-LIMIT-EXCEEDED`	400	`NPS-CLIENT-REQUEST-TOO-LARGE`	响应将超过有效 CGN 预算（`min(cgn_limit, X-NWP-Budget)`）；且无法裁剪。响应体 SHOULD 包含 `effective_budget` 与 `estimated_cgn`。

8. 流式与订阅预算策略

X-NWP-Budget 上限仅适用于同步请求/响应操作（QueryFrame → CapsFrame / StreamFrame 批次）。以下持续推送操作遵循不同规则：

8.1 流式查询（QueryFrame `stream: true`）

X-NWP-Budget 按每个 StreamFrame 批次执行，不针对整个流。
若处理某批次会超出声明预算，节点 MUST 对该批次进行裁剪或终止。
响应头 X-NWP-Tokens 仅报告当前批次消耗的 CGN。
Agent 可在累计预算耗尽后主动断开连接。

8.2 SubscribeFrame / 推送流（topology.stream、事件订阅）

长连续推送流（如通过 SubscribeFrame 建立的 topology.stream）由一系列大小不固定的事件组成，预算语义有所不同：

方面	行为
`X-NWP-Budget` 强制	节点不执行；推送事件的生成独立于任何请求级预算上限
`X-NWP-Tokens` 上报	节点 SHOULD 在每个推送事件（DiffFrame）中附带此响应头，报告该事件有效载荷的 CGN
Agent 侧强制	Agent 负责跨事件累计 CGN，并在会话预算耗尽时主动断开连接

设计原因：对推送流执行 X-NWP-Budget 将要求节点缓冲未来事件，与实时拓扑变更交付的设计目标不兼容。订阅流的预算控制应由 Agent 侧负责。

归属：LabAcacia / INNO LOTUS PTY LTD · Apache 2.0

This site is open source. Improve this page.