Niniejsza dokumentacja jest przeznaczona dla każdego, kto jest zainteresowany tworzeniem logiki programu stowarzyszonego lub programu stowarzyszonego . Zakłada znajomość TensorFlow Federated, zwłaszcza jego systemu typów i programów stowarzyszonych .
Logika programu
W tej sekcji zdefiniowano wytyczne dotyczące sposobu tworzenia logiki programu .
Aby uzyskać więcej informacji, zobacz przykład program_logic.py .
Podpisy typów dokumentów
Udokumentuj sygnaturę typu TFF dla każdego parametru dostarczonego do logiki programu, który ma sygnaturę typu.
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.
"""
Sprawdź podpisy typów
Sprawdź sygnaturę typu TFF (w czasie wykonywania) dla każdego parametru dostarczonego do logiki programu, który ma sygnaturę typu.
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,
)
...
Wpisz adnotacje
Podaj dobrze zdefiniowany typ języka Python dla każdego parametru tff.program.ReleaseManager dostarczonego do logiki programu.
async def program_logic(
metrics_manager: Optional[
tff.program.ReleaseManager[tff.program.ReleasableStructure, int]
] = None,
...
) -> None:
...
Nie
async def program_logic(
metrics_manager,
...
) -> None:
...
async def program_logic(
metrics_manager: Optional[tff.program.ReleaseManager] = None,
...
) -> None:
...
Stan programu
Zapewnij dobrze zdefiniowaną strukturę opisującą stan logiki programu.
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)
Dokument wydanych wartości
Dokumentuj wartości uwolnione z logiki programu.
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`.
"""
Zwolnij określone wartości
Nie zwalniaj więcej wartości z logiki programu, niż jest to wymagane.
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)
Nie
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)
Funkcje asynchroniczne
Zdefiniuj logikę programu jako funkcję asynchroniczną . Komponenty stowarzyszonej biblioteki programów TFF korzystają z asyncio do jednoczesnego wykonywania języka Python, a zdefiniowanie logiki programu jako funkcji asynchronicznej ułatwia interakcję z tymi komponentami.
async def program_logic(...) -> None:
...
Nie
def program_logic(...) -> None:
...
Testy
Zapewnij testy jednostkowe dla logiki programu (np. program_logic_test.py ).
Program
W tej sekcji zdefiniowano wytyczne dotyczące sposobu tworzenia programu .
Aby uzyskać więcej informacji, zobacz przykładowy plik program.py .
Udokumentuj program
Udokumentuj szczegóły programu klientowi w dokumentacji modułu (np. program.py ):
- Jak ręcznie uruchomić program.
- Jaka platforma, obliczenia i źródła danych są używane w programie.
- W jaki sposób klient powinien uzyskiwać dostęp do informacji udostępnianych przez program w pamięci klienta.
Za dużo parametrów
Nie parametryzuj programu w taki sposób, aby istniały wzajemnie wykluczające się kolekcje parametrów. Na przykład, jeśli foo jest ustawione na X , musisz także ustawić parametry bar , baz , w przeciwnym razie te parametry muszą mieć None . Oznacza to, że mogłeś stworzyć dwa różne programy dla różnych wartości foo .
Parametry grupy
Używaj proto do definiowania powiązanych, ale złożonych lub pełnych parametrów, zamiast definiować wiele FLAG (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)
Logika Pythona
Nie pisz logiki (np. przepływu sterowania, wywoływania obliczeń, niczego, co wymaga przetestowania) w programie. Zamiast tego przenieś logikę do prywatnej biblioteki, którą można przetestować, lub do logiki programu, który program wywołuje.
Funkcje asynchroniczne
Nie pisz w programie funkcji asynchronicznych . Zamiast tego przenieś funkcję do prywatnej biblioteki, którą można przetestować, lub do logiki programu, który program wywołuje.
Testy
Nie pisz testów jednostkowych dla programu, jeśli testowanie programu jest przydatne, napisz te testy w kategoriach testów integracyjnych.