跳到主要内容

联邦学习（FL）

Savitri Network 包含一个用于去中心化 AI 模型训练的链上联邦学习系统。FL 合约管理模型注册、训练轮次、更新提交、奖励分发和治理。

架构​

Governance (proposals + voting)
    │
    ▼
Model Registry
    │ register model, assign roles, version tracking
    ▼
Job Lifecycle
    │ create round → open → submit updates → seal → finalize
    ▼
Reward Pool
    │ Merkle-proof reward claims
    ▼
Trainers + Aggregators

模型注册表​

模型以元数据、版本控制和基于角色的访问控制方式在链上注册。

模型注册​

// Register a new model
FlModelRegistry::register_model(
    &mut storage,
    &db,
    &creator,           // [u8; 32] - model creator address
    "sentiment-v1",     // model name
    "ipfs://Qm.../meta", // metadata URI
    "MIT",              // license URI
    "ipfs://Qm.../weights", // initial weights URI
    &mut events,
    Some(&mut gas),
)?;

模型版本管理​

模型具有不可变的版本链，每个新版本引用其父版本：

v1 (initial) → v2 (fine-tuned) → v3 (production)

版本元数据包括：

  • metadata_uri：模型架构描述
  • weights_uri：训练权重位置
  • aggregator：产生该版本的地址
  • parent_version：链接到上一版本

基于角色的访问控制（RBAC）​

角色权限
Creator注册模型、管理版本、设置策略
Viewer读取模型元数据和版本
Trainer向轮次提交训练更新
Aggregator聚合更新、完成轮次、生成版本

训练者访问通过每个模型的允许名单/拒绝名单控制。

策略管理​

每个模型具有可配置的策略：

策略描述
access_policy_hash谁可以访问模型数据
reward_policy_hash奖励如何分发
max_trainers最大并发训练者数量
aggregator_whitelist已批准的聚合者

任务生命周期​

FL 训练以具有固定生命周期的轮次为单位组织：

Planned → Open → Sealed → Finalized
                    ↘ Aborted (via governance)

轮次状态​

状态描述允许的操作
Planned轮次已创建，尚未接受更新Open
Open接受训练者更新提交更新、Seal
Sealed不再接受更新，聚合进行中Finalize、Abort
Finalized奖励已分发，轮次完成领取奖励
Aborted轮次通过治理取消无

创建轮次​

FlJobLifecycle::create_round(
    &mut storage,
    &db,
    &creator,
    &model_id,          // [u8; 32]
    round_id,           // u64
    reward_pool_amount,  // u128
    &mut events,
    Some(&mut gas),
)?;

提交训练更新​

训练者在 Open 阶段提交模型更新：

FlJobLifecycle::submit_update(
    &mut storage,
    &db,
    &trainer,           // [u8; 32]
    &model_id,
    round_id,
    &update_data,       // training update bytes
    nonce,              // replay protection
    &mut events,
    Some(&mut gas),
)?;

重放保护：每个训练者拥有每轮次的随机数，必须严格递增。

封闭与完成​

// Seal round (stop accepting updates)
FlJobLifecycle::seal_round(&mut storage, &db, &aggregator, &model_id, round_id, ...)?;

// Finalize round (distribute rewards)
FlJobLifecycle::finalize_round(
    &mut storage, &db, &aggregator, &model_id, round_id,
    &merkle_root,       // reward distribution Merkle root
    &new_weights_uri,   // aggregated model weights
    ...
)?;

领取奖励​

训练者使用 Merkle 证明领取奖励：

FlJobLifecycle::claim_reward(
    &mut storage, &db, &trainer, &model_id, round_id,
    amount,             // reward amount
    &merkle_proof,      // proof of inclusion in reward distribution
    ...
)?;

国库费用​

可配置的百分比（fee_treasury_bps，最大 10000 = 100%）从奖励池中扣除用于网络国库。计算使用定点算术以防止舍入误差。

FL 治理提案​

FL 专项治理操作：

SetFlPolicy​

提议修改 FL 参数：

ProposalAction::SetFlPolicy {
    fee_treasury_bps: 500,      // 5% treasury fee
    max_models: 100,            // max registered models
    aggregator_whitelist: vec!["addr1", "addr2"],
}

验证：fee_treasury_bps <= 10000，max_models > 0，白名单不为空。

ApproveFlModel​

批准模型用于生产：

ProposalAction::ApproveFlModel {
    model_id: "abc123...64hex",  // 32-byte hex model ID
}

AbortFlRound​

紧急中止活跃训练轮次：

ProposalAction::AbortFlRound {
    model_id: "abc123...64hex",
    round_id: 5,
}

验证：round_id > 0，有效的 32 字节 model_id。

存储布局​

FL 合约使用从 100 开始的存储槽：

槽范围用途
100+模型元数据
200+版本链
300+轮次状态
400+更新提交
500+奖励池
600+角色映射

通过 SDK 集成​

use savitri_sdk::{TransactionBuilder, GovernanceAction};

// Create FL governance proposal
let tx = TransactionBuilder::new()
    .create_fl_proposal(
        "governance_contract_address",
        "Approve sentiment model v2",
        "Production-ready model with 95% accuracy",
        604800,  // 7-day voting period
    )
    .nonce(nonce)
    .fee(5_000_000_000_000_000)
    .build_and_sign(&wallet)?;