連合プログラム

このドキュメントは、連合プログラムの概念の概要に関心のある方を対象としています。TensorFlow Federated の知識、特にその型システムの知識を前提としています。

連合プログラムに関するその他の情報は、以下をご覧ください。

• API ドキュメント
• 例
• 開発者ガイド

連合プログラムとは？

連合プログラムとは、連合環境で計算やその他の処理ロジックを実行するプログラムを指します。

より具体的には、連合プログラムは以下のように動作します。

• 計算を実行します。
• これにはプログラムロジックを使用します。
• プラットフォーム固有のコンポーネント
• およびプラットフォームに依存しないコンポーネントが含まれます。
• プログラムが設定する特定のパラメータ
• および顧客が設定するパラメータがあります。
• このパラメータは顧客がプログラムを実行したときに設定されます。
• プラットフォームストレージでは以下の目的でデータをマテリアライズできます。
  • Python ロジックで使用する
  • フォールトトレランスを実装する
• また、データを顧客ストレージにリリースすることもできます。

これらの概念と抽象を定義することで、連合プログラムのコンポーネントの関係を説明し、様々なロールがこれらのコンポーネントを所有して記述することが可能になります。このように切り離すことで、開発者は他の連合プログラムと共有されているコンポーネントを使用して、連合プログラムを作成することができるため、通常、多数の様々なプラットフォームで同じプログラムを実行することが可能になります。

TFF の連合プログラムライブラリ（tff.program）は、連合プログラムの作成に必要な抽象を定義し、プラットフォームに依存しないコンポーネントを提供します。

コンポーネント

TFF の連合プログラムライブラリのコンポーネントは、異なるロールが所有し、記述できるように設計されています。

注意: これはコンポーネントの高レベルの概要です。特定の API のドキュメントについては、tff.program をご覧ください。

プログラム

プログラムは、以下を行う Python バイナリです。

1. パラメータを定義します（フラグなど）。
2. プラットフォーム固有のコンポーネントとプラットフォームに依存しないコンポーネントを構築します。
3. 連合のコンテキストでプログラムロジックを使って計算を実行します。

以下に例を示します。

# Parameters set by the customer.
flags.DEFINE_string('output_dir', None, 'The output path.')

def main() -> None:

  # Parameters set by the program.
  total_rounds = 10
  num_clients = 3

  # Construct the platform-specific components.
  context = tff.program.NativeFederatedContext(...)
  data_source = tff.program.DatasetDataSource(...)

  # Construct the platform-agnostic components.
  summary_dir = os.path.join(FLAGS.output_dir, 'summary')
  metrics_manager = tff.program.GroupingReleaseManager([
      tff.program.LoggingReleaseManager(),
      tff.program.TensorBoardReleaseManager(summary_dir),
  ])
  program_state_dir = os.path.join(..., 'program_state')
  program_state_manager = tff.program.FileProgramStateManager(program_state_dir)

  # Define the computations.
  initialize = ...
  train = ...

  # Execute the computations using program logic.
  tff.framework.set_default_context(context)
  asyncio.run(
      train_federated_model(
          initialize=initialize,
          train=train,
          data_source=data_source,
          total_rounds=total_rounds,
          num_clients=num_clients,
          metrics_manager=metrics_manager,
          program_state_manager=program_state_manager,
      )
  )

パラメータ

パラメータはプログラムへの入力です。これらの入力は、フラグとして公開される場合は顧客が設定しますが、プログラムによって設定される場合もあります。上記の例では、output_dir が顧客によって設定されるパラメータで、total_rounds と num_clients がプログラムによって設定されるパラメータです。

プラットフォーム固有のコンポーネント

プラットフォーム固有のコンポーネントとは、TFF の連合プログラムライブラリで定義されている抽象インターフェースを実装するプラットフォームが提供するコンポーネントを指します。

プラットフォームに依存しないコンポーネント

プラットフォームに依存しないコンポーネントとは、TFF の連合プログラムライブラリで定義されている抽象インターフェースを実装するライブラリ（TFF など）が提供するコンポーネントを指します。

計算

計算は、抽象インターフェース tff.Computation の実装です。

たとえば、TFF プラットフォームでは、tff.tf_computation や tff.federated_computation デコレータを使用して、tff.framework.ConcreteComputation を作成できます。

詳細は、計算のライフサイクルをご覧ください。

プログラムロジック

プログラムロジックは、以下を入力として取る Python 関数です。

• 顧客とプログラムによって設定されるパラメータ
• プラットフォーム固有のコンポーネント
• プラットフォームに依存しないコンポーネント
• 計算

そして、何らかの演算を実行します。これには、通常以下が含まれます。

• 計算の実行
• Python ロジックの実行
• 以下の目的によるプラットフォームストレージでのデータのマテリアライズ:
  • Python ロジックで使用する
  • フォールトトレランスを実装する

また、何らかの出力を生成します。これには、通常以下が含まれます。

• データを顧客ストレージに指標としてリリースする

以下に例を示します。

async def program_logic(
    initialize: tff.Computation,
    train: tff.Computation,
    data_source: tff.program.FederatedDataSource,
    total_rounds: int,
    num_clients: int,
    metrics_manager: tff.program.ReleaseManager[
        tff.program.ReleasableStructure, int
    ],
) -> None:
  state = initialize()
  start_round = 1

  data_iterator = data_source.iterator()
  for round_number in range(1, total_rounds + 1):
    train_data = data_iterator.select(num_clients)
    state, metrics = train(state, train_data)

    _, metrics_type = train.type_signature.result
    metrics_manager.release(metrics, metrics_type, round_number)

ロール

連合プログラムに関しては、定義しておくと有用なロールが 3 つあります。顧客、プラットフォーム、ライブラリです。各ロールは、連合プログラムの作成に使用される一部のコンポーネントを所有し、記述しますが、単一のエンティティまたはグループが複数のロールを実行することも可能です。

顧客

顧客 は通常以下を実行できます。

• 顧客ストレージの所有
• プログラムの起動

ただし、以下を行う場合もあります。

• プログラムの記述
• プラットフォームのすべての機能

プラットフォーム

プラットフォーム は通常以下を実行できます。

• プラットフォームストレージの所有
• プラットフォーム固有のコンポーネントの記述

ただし、以下を行う場合もあります。

• プログラムの記述
• ライブラリのすべての機能

ライブラリ

ライブラリは通常以下を実行できます。

• プラットフォームに依存しないコンポーネントの記述
• 計算の記述
• プログラムロジックの記述

概念

連合プログラムに関しては、定義しておくと有用な概念がいくつかあります。

顧客ストレージ

顧客ストレージは、顧客が読み書きアクセスを持ち、プラットフォームが書き込みアクセスを持つストレージです。

プラットフォームストレージ

プラットフォームストレージは、プラットフォームのみが読み書きアクセスを持つストレージです。

リリース

値をリリースすると、顧客ストレージがその値を使用できるようになります（ダッシュボードに当たりを公開する、値をログに記録する、値をディスクに書き込むなど）。

マテリアライズ

値参照をマテリアライズすると、プログラムが参照された値を使用できるようになります。通常、値参照のマテリアライズには、値をリリースするか、プログラムロジックをフォールトトレランスにする必要があります。

フォールトトレランス

フォールトトレランスは、計算を実行する際にエラーから回復するためのプログラムロジックです。たとえば、100 ラウンド中、最初の 90 ラウンドでトレーニングに成功した後でエラーが発生した場合、プログラムロジックは 91 ラウンドからトレーニング再開できますか？それとも、1 ラウンドからやり直す必要がありますか？