Эта документация предназначена для всех, кто заинтересован в разработке логики интегрированных программ или интегрированных программ . Предполагается знание 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
Не записывайте в программе логику (например, поток управления, вызов вычислений и т. д.) в программе. Вместо этого переместите логику в частную библиотеку, которую можно протестировать, или в логику программы, которую она вызывает.
Асинхронные функции
Не пишите в программе асинхронные функции . Вместо этого переместите функцию в частную библиотеку, которую можно протестировать, или в логику программы, которую она вызывает.
Тесты
Не пишите модульные тесты для программы. Если тестирование программы полезно, напишите эти тесты в виде интеграционных тестов.