nmspace 算力 / 模型能力接入方案（P2P 能力网络）

把「算力（GPU/边缘计算）」与「模型能力（LLM/嵌入/ASR/TTS…）」接入 nmspace P2P 网络，
让人、设备、机器人、Agent 都能就近、按需、可授权、可计量地使用。
文档先行——审核通过后再落地（与 FEDERATION_SCALING_DESIGN.md / MAIL_BRIDGE_DESIGN.md 同节奏）。

状态：草案 v1（2026-10-08）。6 项关键决策已定（§12）+ C0 能力注册规范已固化（§13）。核心判断：几乎零新协议——nmspace 的统一实体模型本就是为此设计的
（proto 里 Entity.kind 的注释示例即 "compute.inference"，attributes 即 region/gpu/model/status，
能力枚举含 COMMAND/JOB/STREAM，DirectoryQuery 即按 kind_prefix + capabilities + attributes 发现）。

0. 目标 / 非目标

目标

• 任意一台有算力/模型的机器，注册即成为网络里可被发现、可被调用的「能力实体」。
• 任意消费方（人/设备/机器人/Agent）经目录发现 + 撮合 + 按需调用用上算力/模型。
• 授权（Grant 签名）、计量/配额、就近/负载调度、离线可用（长任务结果补投）。

非目标（本期不做，列后续）

• 不做去信任的结算/链上支付（先做用量计量 + 授权；计费/积分是上层）。
• 不做机密计算/TEE（提供方天然可见输入；隐私推理留后续）。
• 不做复杂调度器/编排 DAG（先做"选一个 provider 调用"，编排是上层）。

1. 为什么 nmspace 天生适配

能力提供方不是新物种，而是一类 Entity：kind=compute.*/model.*/agent.*，带发现属性与能力位，归属某 home node，经目录被发现、经命令被调用。现有原语一一对应：

需要的能力	nmspace 现成原语	位置
能力即实体（身份/签名/归属）	Entity{kind, attributes, capabilities, profile, home_node, signature}	nm.proto
声明「我能被调用/接任务/能流式」	Capability::{COMMAND(5), JOB(6), STREAM(7)}	nm.proto
按模型/GPU/地域/负载发现	DirectoryQuery{kind_prefix, require_capabilities, match_attributes}	nm.proto
跨节点发现	目录 s2s 同步（FedSyncReq / spawn_federation_sync）	nm-node
发起调用 / 作为被调方	Client::call(target, method, params) · Session::next_command/reply	nm-client
授权访问	Grant{audience, action, resource, expires, sig} · issue_grant · Command.grant	nm-proto / nm-client
大输入/输出	内容寻址 blob_put/blob_get（BlobRef{hash,home_node}）	nm-client
token 流 / 遥测	频道 ChannelHub + STREAM / TELEMETRY_*	nm-gossip / nm-node
传输 / 穿透	iroh QUIC + 中继 + 按公钥发现	nm-transport

结论：主体工作是"约定 + 一个 provider 运行时 + 一个消费 SDK 便捷层"，而非改底层协议。

2. 能力实体模型（如何注册一个提供方）

一台算力/模型机器跑一个 provider 运行时（复用 nm-client）：online 到 home node → register_as 一个实体 → 循环 next_command 接请求、reply 回结果。

kind 命名规范（建议）

kind	含义	典型 method
model.llm	大语言模型	model.infer / model.stream
model.embed	向量/嵌入	model.embed
model.asr / model.tts	语音转写/合成	model.asr / model.tts
model.vision	多模态/图像	model.infer
compute.gpu / compute.cpu	原始算力	job.submit
compute.edge	边缘设备算力	model.infer（小模型）
agent.tool	工具/技能 Agent	自定义 method

attributes 发现标签（建议）：model（如 llama3-70b）、gpu（A100）、vram、region、ctx_len、max_batch、price（如 tok:0.000x）、status（idle/busy）、load（0–100）。消费方据此过滤 + 撮合。

capabilities：按能力勾选 COMMAND（同步）、STREAM（流式）、JOB（长任务）、TELEMETRY_PUB（上报负载）。

3. 发现与撮合

• 发现：directory_query(kind_prefix="model.", require_capabilities=[COMMAND], match_attributes={"model":"llama3-70b"}) → 候选实体集（含各自 home_node 与属性）。目录经 s2s 同步，跨节点可见。
• 撮合（选哪一个）：按 status/load（presence 实时负载）+ 就近（region/RTT）+ price 打分。首期消费端本地撮合；规模化后可引入 Broker 实体（agent.broker）集中撮合 + 配额 + 失败转移。
• 亮点：发现是联邦级的——你本地没有的模型，可自动发现并调用他节点的算力。

4. 三种调用形态

• 同步 COMMAND：call(provider, "model.infer", {...}) → CommandResult{result}。短请求、低时延（分类/改写/短补全/嵌入）。
• 流式 STREAM：开 uni/bi 流或每请求一个临时频道，provider 持续回推 token。LLM 长文本/ASR/TTS。
• 长任务 JOB：call(provider, "job.submit", {...}) → job_id；进度/结果异步回传，consumer 离线时结果入其 home node 收件箱、上线补投（复用 inbox）。训练/微调/批量/渲染。

选择建议：响应 < 数秒且结果小 → 同步；要逐字输出 → 流式；分钟级以上或批量 → 任务。

5. 大负载与流式

• 大输入/输出走 blob：长上下文、图片、嵌入批、模型产物等，blob_put 得 BlobRef{hash,home_node}，在命令里传引用；对端 blob_get 取回。内容寻址天然去重、可跨节点回源。
• token 流：首期用 iroh uni 流逐段回推；或"每请求临时频道"（nmspace-infer:<req_id>）承载流，复用频道 pub/sub。

6. 授权与计量

• 授权（Grant）：资源属主/提供方 issue_grant(audience=consumer, action="model.infer", resource="model:llama3-70b", expires) 签发；消费方在 Command.grant 出示，提供方验签 + 校验 action/resource/过期。天然支持"离线可验证"的委托授权。
• 计量：提供方按 (consumer, 用量: tokens / compute-秒 / 调用次) 记账，TELEMETRY_PUB 上报聚合用量。配额/限速在提供方或 Broker 落地。
• 计费/积分（后续）：在计量之上做（预付额度 / 积分 / 链上结算任选），不绑死核心。

7. 调度 / 负载 / 容灾

• 多提供者：同一模型多实例 → 撮合按 load/RTT/price 选；忙/超时 → 自动换一个（failover）。
• Broker 网关（可选实体）：对外呈现"一个模型端点"，对内 fan-out 到后端 GPU 池 + 配额 + 重试；适合规模化。
• 负载感知：提供方经 presence/telemetry 周期上报 load/status，撮合据此避开热点。

8. 角色对等（人/设备/机器人/Agent 既消费又提供）

统一实体 + Command/Job/Stream 使同一个体可双角色：

• 机器人既 call 云端大模型（消费），又以 agent.tool/compute.edge 对外提供本地推理/技能（提供）。
• 手机/车机消费模型；闲时也可贡献边缘算力。
• Agent 调模型完成任务，同时作为"可被别人调用的技能"注册。

9. 安全与隐私

• 传输加密：iroh QUIC 端到端（节点间）；命令走定向路由，不随火管/频道广播。
• E2E（后续 MLS）：让提供方之外不可读——但提供方必须见明文才能算，故"对提供方保密"属机密计算/TEE 范畴（更后）。
• 沙箱：提供方对不可信输入做推理，需进程/容器沙箱。
• 抗滥用：Grant + 配额/限速 + 发送方密码学身份（可追责），抑制匿名滥用。

10. 与现有代码集成点（已核对）

用途	现成 API	位置
注册能力实体	register_as::<Kind>(profile, name, attributes)（attributes 带 model/gpu/…）	nm-client
发现	directory_query(DirectoryQuery{kind_prefix, require_capabilities, match_attributes})	nm-client / nm-proto
调用（消费端）	Client::call(target_id, method, params) -> CommandResult	nm-client:643
接请求（提供端）	Session::next_command() -> (Gram, Command) · reply(...)	nm-client:312/317
授权	issue_grant(audience, action, resource, expires) → Command.grant	nm-client:89
大负载	blob_put(data,mime) / blob_get(hash,home_node)	nm-client:470/485
能力位	Capability::{COMMAND,JOB,STREAM,TELEMETRY_PUB}	nm-proto
跨节点发现	目录 s2s 同步（spawn_federation_sync）	nm-node

几乎不改 proto：新增的多是 method 约定（model.infer/stream/embed、job.submit/status）与 params/result 的 Any 载荷格式；可选加 job.* 的小结构与若干 kind 约定。

11. 分阶段里程碑

里程碑	内容	验证
C0 约定	定 kind/method/attributes/载荷/计量 schema —— 已完成，见 §13	规范固化（v1）
C1 provider 运行时	nm-compute（bin）：online+register_as(model.llm,…)+next_command→接 model.infer→回结果（先接一个本地模型后端，如 ollama/llama.cpp）	本机起 provider，目录可见
C2 消费 SDK 便捷层	nm-client 加 infer/embed/stream/job 便捷方法（封装 call + grant + blob）	一行代码跨节点调用成功
C3 发现+撮合	directory_query 过滤 + 本地撮合（负载/就近） + failover	多 provider 自动选优/容灾
C4 流式 + 大负载	token 流 + blob 外置大输入输出	流式生成 + 大图/长上下文往返
C5 授权+计量	Grant 门禁 + 用量计量/配额	无授权被拒；用量可查
后续	Broker 网关 · 结算/积分 · 机密计算 · 编排	—

12. 已定决策（v1，含理由与留口）

取向：最小闭环先跑通 + 不锁死未来——C1 就能"一行代码跨节点调一个真实模型"，
每个"更重的东西"都留了不改契约的升级口。

#	决策	定值（v1）	理由	留口（将来升级不破契约）
1	provider 后端	先 Ollama，适配层 pluggable	一行装、自带模型管理、HTTP API 稳、本机/Mac 友好，验证最省力	trait ModelBackend{infer/embed/stream}；vLLM/llama.cpp 后加 impl，对网络契约不变
2	载荷格式	OpenAI 兼容 JSON（装进 Any，type_url 标注）	生态红利压倒一切：现成客户端/SDK/Agent 几乎零改造即可当消费方；Ollama 自带 OpenAI 兼容端点、适配近直通	Any{type_url="openai.chat.v1", value=<JSON>}；将来要强类型再加 proto type_url 并存
3	流式	iroh 原始流（uni）	点对点、低开销、天然背压、req→token流一一对应；临时频道是广播语义、杀鸡用牛刀	消费端 SDK 封装"开流+收 token"；"一对多直播型推理"真有需求再上频道
4	撮合位置	先纯消费端；Broker 留到 C3 之后按需	本地撮合（load/region/price 打分 + failover）即满足"选一个能用的"，零新组件、无单点；过早上 Broker = 先造中心化网关	需要统一入口/集中配额/对外单端点时，把 Broker 做成 agent.broker 实体（自己也是网络一员），非中心服务器
5	计量/计费	先只计量（usage accounting），计费分离	计量是无争议的基础，先做扎实可审计；计费/积分/结算涉及信任模型/防双花/链上与否，是独立大设计	计量记录从一开始带 (consumer,provider,resource,amount,ts,sig)，计费层直接在其上做，无需回填
6	kind/method 命名	固化（§2 规范），标注 v1 + x- 扩展	命名是跨实现契约（provider 注册的 kind 与消费方 query 的 method 必须一致），现在不定死则各做各的	官方命名空间冻结；第三方自定义能力走 x- 前缀（如 x-acme.rerank），不污染官方

一句话组合：Ollama(pluggable trait) · OpenAI 兼容 JSON · iroh uni 流 · 消费端撮合 · 只计量 · 固化命名(v1+x-扩展)。确切 schema 见 §13 · C0 能力注册规范。

13. C0 · 能力注册规范（跨实现契约）

provider 与 consumer 必须遵守本节的 kind / attributes / method / 载荷 / 计量 schema，方能互通。
本节即里程碑 C0 的交付物。版本：v1。

13.1 实体 kind（固化）

model.llm        大语言模型（chat/completion）
model.embed      向量 / 嵌入
model.asr        语音转文字
model.tts        文字转语音
model.vision     多模态 / 图像理解
compute.gpu      原始 GPU 算力（跑 job）
compute.cpu      原始 CPU 算力（跑 job）
compute.edge     边缘设备算力（小模型本地推理）
agent.tool       工具 / 技能 Agent（自定义 method）
agent.broker     撮合/网关实体（C3+，对外呈现统一端点）

第三方自定义能力一律 x-<vendor>.<name>（如 x-acme.rerank），不得占用上述官方前缀。

13.2 发现属性 attributes（string→string；用于 match_attributes 过滤 + 撮合打分）

key	示例	说明
model	llama3-70b	模型标识（consumer 据此精确匹配）
models	llama3-70b,qwen2-7b	可选：一个 provider 服务多模型（逗号分隔）
gpu	A100 / M3-Max / cpu	加速器型号
vram	80G	显存
ctx_len	131072	最大上下文
max_batch	32	最大并发/批
region	cn-east / us-west	就近调度
price	tok:0.0000002 / sec:0.0003	计价提示（单位:计量项:单价，仅声明，不强制）
status	idle / busy / draining	可用状态（经 presence 周期刷新）
load	0–100	当前负载百分比（撮合避开热点）
api	openai.chat.v1	载荷契约版本（见 §13.4）

status/load 走 presence/telemetry 周期更新；其余相对静态，随 register_as 的 attributes 注册。

13.3 method（固化；装入 Command.method）

method	适用 kind	形态	入/出载荷 type_url
model.infer	model.llm / vision	同步 Command	openai.chat.v1 → openai.chat.completion.v1
model.stream	model.llm / vision	流式（§13.5）	openai.chat.v1 → 流：openai.chat.chunk.v1
model.embed	model.embed	同步 Command	openai.embed.v1 → openai.embed.result.v1
model.asr	model.asr	同步/流式	nm.asr.v1（音频走 blob） → nm.asr.result.v1
model.tts	model.tts	同步/流式	nm.tts.v1 → 音频 blob 引用
job.submit	compute.* / model.*	长任务	nm.job.v1 → nm.job.ack.v1{job_id}
job.status	同上	查询	nm.job.query.v1{job_id} → nm.job.status.v1
job.cancel	同上	取消	nm.job.query.v1{job_id} → CommandResult{ok}

13.4 载荷格式（OpenAI 兼容 JSON，装入 Any）

• 约定：Command.params = Any{ type_url="openai.chat.v1", value=<UTF-8 JSON bytes> }；
  CommandResult.result = Any{ type_url="openai.chat.completion.v1", value=<JSON> }。
• model.infer 请求（OpenAI /chat/completions 子集）：

  { "model": "llama3-70b", "messages": [{"role":"user","content":"..."}],
    "temperature": 0.7, "max_tokens": 1024, "stream": false }
  

• model.infer 响应：OpenAI chat.completion 结构（choices[].message.content + usage{prompt_tokens,completion_tokens}）。usage 必填（计量依赖，见 §13.6）。
• model.embed：请求 {"model","input":[...]} → 响应 {"data":[{"embedding":[...]}], "usage":{...}}。
• 大负载：单个 JSON 字段（图片/音频/长上下文/嵌入批）超阈值（默认 256 KB）→ 抽出 blob_put → JSON 里以 {"$blob":{"hash":"...","home_node":"..."}} 占位；对端取回后还原。阈值与是否外置由 provider 在 attributes 或握手声明。

13.5 流式（iroh uni 流）

• consumer 调 model.stream；provider 不在 CommandResult 里给内容，而是开一条 uni 流回推若干帧，每帧一条 OpenAI chat.completion.chunk JSON（choices[].delta.content），以 [DONE] 帧结束。
• 末帧附带 usage（计量）。断流/超时按失败处理，consumer 可重试或换 provider。
• 消费端 SDK 封装"发起 stream + 聚合 chunk"，上层只拿到 token 迭代器。

13.6 计量记录（usage accounting，v1）

provider 每次完成后生成一条签名计量记录（本地留存 + 可选经 TELEMETRY_PUB 上报聚合）：

{ "v": 1, "consumer": "<pubkey hex>", "provider": "<pubkey hex>",
  "resource": "model:llama3-70b", "method": "model.infer",
  "amount": { "prompt_tokens": 128, "completion_tokens": 512 },
  "unit": "tokens", "ts_ms": 1733650000000, "req_id": "...",
  "sig": "<provider 对以上规范字节的签名>" }

• compute.* 的 unit 为 compute_sec；按次计的为 calls。
• 该结构即计费层（后续）的输入；v1 只记录/可查/可审计，不做扣费。

13.7 授权（Grant）绑定

• action = method（如 model.infer）；resource = model:<model> 或 compute:<kind>。
• provider 收到 Command 后：验 Command.grant 签名 → 校验 audience==caller、action==method、resource 匹配、未过期 → 不符即拒（CommandResult{ok=false, error}）。
• 开放/免费 provider 可声明 attributes{auth:"open"} 跳过 Grant（仍受配额/限速约束）。

---

一句话评审结论：契合度极高、几乎零新协议——把算力/模型建模为 compute.*/model.* 实体，复用目录发现 + Command/Stream/Job + Grant + blob 即可打通。建议按 C1 provider 运行时 + C2 消费便捷层 做最小闭环（一行代码跨节点调用一个模型），再逐步补发现/撮合/流式/授权。