Руководство разработчика федеративной программы

Эта документация предназначена для всех, кто заинтересован в разработке логики интегрированных программ или интегрированных программ . Предполагается знание TensorFlow Federated, особенно его системы типов, и федеративных программ .

Программная логика

В этом разделе определяются рекомендации по созданию логики программы .

Дополнительную информацию смотрите в примере program_logic.py .

Подписи типов документов

Задокументируйте сигнатуру типа TFF для каждого параметра, передаваемого в логику программы, который имеет сигнатуру типа.

async def program_logic(
    train: tff.Computation,
    data_source: tff.program.FederatedDataSource,
    ...
) -> None:
  """Trains a federated model for some number of rounds.

  The following types signatures are required:

  1.  `train`:       `(<S@SERVER, D@CLIENTS> -> <S@SERVER, M@SERVER>)`
  2.  `data_source`: `D@CLIENTS`

  Where:

  *   `S`: The server state.
  *   `M`: The train metrics.
  *   `D`: The train client data.
  """

Проверьте подписи типов

Обязательно проверяйте сигнатуру типа TFF (во время выполнения) для каждого параметра, передаваемого в логику программы, который имеет сигнатуру типа.

def _check_program_logic_type_signatures(
    train: tff.Computation,
    data_source: tff.program.FederatedDataSource,
    ...
) -> None:
  ...

async def program_logic(
    train: tff.Computation,
    data_source: tff.program.FederatedDataSource,
    ...
) -> None:
  _check_program_logic_type_signatures(
      train=train,
      data_source=data_source,
  )
  ...

Тип аннотации

Укажите четко определенный тип Python для каждого параметра tff.program.ReleaseManager , передаваемого в логику программы.

async def program_logic(
    metrics_manager: Optional[
        tff.program.ReleaseManager[tff.program.ReleasableStructure, int]
    ] = None,
    ...
) -> None:
  ...

Нет

async def program_logic(
    metrics_manager,
    ...
) -> None:
  ...
async def program_logic(
    metrics_manager: Optional[tff.program.ReleaseManager] = None,
    ...
) -> None:
  ...

Состояние программы

Обеспечьте четко определенную структуру, описывающую состояние логики программы.

class _ProgramState(NamedTuple):
  state: object
  round_num: int

async def program_loic(...) -> None:
  initial_state = ...

  # Load the program state
  if program_state_manager is not None:
    structure = _ProgramState(initial_state, round_num=0)
    program_state, version = await program_state_manager.load_latest(structure)
  else:
    program_state = None
    version = 0

  # Assign state and round_num
  if program_state is not None:
    state = program_state.state
    start_round = program_state.round_num + 1
  else:
    state = initial_state
    start_round = 1

  for round_num in range(start_round, ...):
    state, _ = train(state, ...)

    # Save the program state
    program_state = _ProgramState(state, round_num)
    version = version + 1
    program_state_manager.save(program_state, version)

Опубликованные значения документа

Документируйте значения, полученные из логики программы.

async def program_logic(
    metrics_manager: Optional[tff.program.ReleaseManager] = None,
    ...
) -> None:
  """Trains a federated model for some number of rounds.

  Each round, `loss` is released to the `metrics_manager`.
  """

Особые значения выпуска

Не освобождайте из логики программы больше значений, чем требуется.

async def program_logic(...) -> None:

  for round_number in range(...):
    state, metrics = train(state, ...)

    _, metrics_type = train.type_signature.result
    loss = metrics['loss']
    loss_type = metrics_type['loss']
    metrics_manager.release(loss, loss_type, round_number)

Нет

async def program_loic(...) -> None:

  for round_number in range(...):
    state, metrics = train(state, ...)

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

Асинхронные функции

Определите логику программы как асинхронную функцию . Компоненты библиотеки интегрированных программ TFF ​​используют asyncio для одновременного выполнения Python, а определение логики программы как асинхронной функции упрощает взаимодействие с этими компонентами.

async def program_logic(...) -> None:
  ...

Нет

def program_logic(...) -> None:
  ...

Тесты

Предоставьте модульные тесты для логики программы (например, program_logic_test.py ).

Программа

В этом разделе определяются рекомендации по созданию программы .

Дополнительную информацию см. в примере program.py .

Документирование программы

Документируйте детали программы для клиента в строке документации модуля (например, program.py ):

  • Как запустить программу вручную.
  • Какая платформа, вычисления и источники данных используются в программе.
  • Как клиент должен получить доступ к информации, выпущенной из программы, в хранилище клиента.

Слишком много параметров

Не параметризуйте программу таким образом, чтобы существовали взаимоисключающие наборы параметров. Например, если для foo установлено значение X , вам также необходимо установить параметры bar , baz , в противном случае эти параметры должны быть None . Это означает, что вы могли бы создать две разные программы для разных значений foo .

Параметры группы

Используйте proto для определения связанных, но сложных или подробных параметров вместо определения множества ФЛАГОВ (go/absl.flags).

with tf.io.gfile.GFile(config_path) as f:
  proto = text_format.Parse(f.read(), vizier_pb2.StudyConfig())
return pyvizier.StudyConfig.from_proto(proto)

Логика Python

Не записывайте в программе логику (например, поток управления, вызов вычислений и т. д.) в программе. Вместо этого переместите логику в частную библиотеку, которую можно протестировать, или в логику программы, которую она вызывает.

Асинхронные функции

Не пишите в программе асинхронные функции . Вместо этого переместите функцию в частную библиотеку, которую можно протестировать, или в логику программы, которую она вызывает.

Тесты

Не пишите модульные тесты для программы. Если тестирование программы полезно, напишите эти тесты в виде интеграционных тестов.