Esta documentação é para qualquer pessoa interessada na criação de lógica de programa federado ou de um programa federado . Ele pressupõe conhecimento do TensorFlow Federated, especialmente seu sistema de tipos, e programas federados .
Lógica do Programa
Esta seção define diretrizes sobre como a lógica do programa deve ser criada.
Veja o exemplo program_logic.py para obter mais informações.
Assinaturas de tipo de documento
Documente a assinatura de tipo TFF para cada parâmetro fornecido à lógica do programa que possui uma assinatura 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.
"""
Verifique as assinaturas de tipo
Verifique a assinatura de tipo TFF (em tempo de execução) para cada parâmetro fornecido à lógica do programa que possui uma assinatura 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,
)
...
Anotações de tipo
Forneça um tipo Python bem definido para cada parâmetro tff.program.ReleaseManager fornecido à lógica do programa.
async def program_logic(
metrics_manager: Optional[
tff.program.ReleaseManager[tff.program.ReleasableStructure, int]
] = None,
...
) -> None:
...
Não
async def program_logic(
metrics_manager,
...
) -> None:
...
async def program_logic(
metrics_manager: Optional[tff.program.ReleaseManager] = None,
...
) -> None:
...
Estado do programa
Forneça uma estrutura bem definida que descreva o estado da lógica do 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 do documento
Documente os valores liberados da lógica do 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
Não libere mais valores da lógica do programa do que o necessário.
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)
Não
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)
Funções Assíncronas
Defina a lógica do programa como uma função assíncrona . Os componentes da biblioteca de programas federados do TFF usam asyncio para executar Python simultaneamente e definir a lógica do programa como uma função assíncrona facilita a interação com esses componentes.
async def program_logic(...) -> None:
...
Não
def program_logic(...) -> None:
...
Testes
Forneça testes de unidade para a lógica do programa (por exemplo, program_logic_test.py ).
Programa
Esta seção define diretrizes sobre como um programa deve ser criado.
Veja o exemplo program.py para obter mais informações.
Documente o Programa
Documente os detalhes do programa para o cliente na documentação do módulo (por exemplo, program.py ):
- Como executar manualmente o programa.
- Qual plataforma, cálculos e fontes de dados são usados no programa.
- Como um cliente deve acessar as informações liberadas do programa para o armazenamento do cliente.
Muitos parâmetros
Não parametrize o programa de forma que haja coleções de parâmetros mutuamente exclusivas. Por exemplo, se foo estiver definido como X , você também deverá definir os parâmetros bar , baz , caso contrário, esses parâmetros deverão ser None . Isso indica que você poderia ter feito dois programas diferentes para valores diferentes de foo .
Parâmetros de grupo
Use proto para definir parâmetros relacionados, mas complexos ou detalhados, em vez de definir muitos FLAGS (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 Python
Não escreva lógica (por exemplo, controle de fluxo, invocação de cálculos, qualquer coisa que precise ser testada) no programa. Em vez disso, mova a lógica para uma biblioteca privada que possa ser testada ou para a lógica do programa que o programa invoca.
Funções Assíncronas
Não escreva funções assíncronas no programa. Em vez disso, mova a função para uma biblioteca privada que possa ser testada ou para a lógica do programa que o programa invoca.
Testes
Não escreva testes de unidade para o programa; se testar o programa for útil, escreva esses testes em termos de testes de integração.