Guía para desarrolladores de programas federados

Esta documentación es para cualquiera que esté interesado en crear lógica de programa federado o un programa federado . Se supone conocimiento de TensorFlow Federated, especialmente su sistema de tipos, y programas federados .

Lógica del programa

Esta sección define las pautas sobre cómo se debe crear la lógica del programa .

Consulte el ejemplo program_logic.py para obtener más información.

Firmas de tipo de documento

Documente la firma de tipo TFF para cada parámetro proporcionado a la lógica del programa que tiene una firma de tipo.

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.
  """

Comprobar tipo de firmas

Verifique la firma de tipo TFF (en tiempo de ejecución) para cada parámetro proporcionado a la lógica del programa que tiene una firma de tipo.

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,
  )
  ...

Anotaciones de tipo

Proporcione un tipo de Python bien definido para cada parámetro tff.program.ReleaseManager proporcionado a la lógica del programa.

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

No

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

Estado del programa

Proporcione una estructura bien definida que describa el estado del programa de la lógica del programa.

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)

Valores liberados del documento

Documente los valores liberados de la lógica del programa.

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`.
  """

Liberar valores específicos

No libere más valores de la lógica del programa de los necesarios.

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)

No

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)

Funciones asíncronas

Defina la lógica del programa como una función asíncrona . Los componentes de la biblioteca de programas federados de TFF usan asyncio para ejecutar Python simultáneamente y definir la lógica del programa como una función asíncrona facilita la interacción con esos componentes.

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

No

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

Pruebas

Proporcione pruebas unitarias para la lógica del programa (por ejemplo, program_logic_test.py ).

Programa

Esta sección define las pautas sobre cómo se debe crear un programa .

Consulte el programa de ejemplo.py para obtener más información.

Documentar el Programa

Documente los detalles del programa para el cliente en la cadena de documentación del módulo (por ejemplo, program.py ):

  • Cómo ejecutar manualmente el programa.
  • Qué plataforma, cálculos y fuentes de datos se utilizan en el programa.
  • Cómo un cliente debe acceder a la información liberada del programa al almacenamiento del cliente.

Demasiados parámetros

No parametrice el programa de modo que haya colecciones de parámetros mutuamente excluyentes. Por ejemplo, si foo se establece en X , también debe establecer los parámetros bar , baz ; de lo contrario, estos parámetros deben ser None . Esto indica que podría haber creado dos programas diferentes para diferentes valores de foo .

Parámetros de grupo

Utilice proto para definir parámetros relacionados pero complejos o detallados en lugar de definir muchas BANDERAS (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)

Lógica de Python

No escriba lógica (p. ej., flujo de control, cálculos de invocación, nada que deba probarse) en el programa. En su lugar, mueva la lógica a una biblioteca privada que se pueda probar o a la lógica del programa que invoca el programa.

Funciones asíncronas

No escriba funciones asíncronas en el programa. En su lugar, mueva la función a una biblioteca privada que pueda probarse o a la lógica del programa que invoca el programa.

Pruebas

No escriba pruebas unitarias para el programa, si probar el programa es útil, escriba esas pruebas en términos de pruebas de integración.