راهنمای توسعه دهنده برنامه فدرال

این مستند برای هر کسی است که علاقه مند به نوشتن منطق برنامه فدرال یا یک برنامه فدرال است. این فرض بر دانش 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,
  )
  ...

Annotations را تایپ کنید

برای هر پارامتر tff.program.ReleaseManager که به منطق برنامه ارائه می شود، یک نوع Python به خوبی تعریف کنید .

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 برای اجرای همزمان پایتون استفاده می کنند و تعریف منطق برنامه به عنوان یک تابع ناهمزمان تعامل با آن مؤلفه ها را آسان تر می کند.

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

نه

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

تست ها

تست های واحد را برای منطق برنامه ارائه کنید (مثلا program_logic_test.py ).

برنامه

این بخش دستورالعمل هایی را برای نحوه نگارش یک برنامه تعریف می کند.

برای اطلاعات بیشتر به مثال program.py مراجعه کنید.

برنامه را مستند کنید

جزئیات برنامه را در رشته مستند ماژول به مشتری مستند کنید (به عنوان مثال program.py ):

• نحوه اجرای دستی برنامه
• چه پلت فرم، محاسبات و منابع داده در برنامه استفاده می شود.
• چگونه یک مشتری باید به اطلاعات منتشر شده از برنامه به ذخیره سازی مشتری دسترسی داشته باشد.

پارامترهای خیلی زیاد

برنامه را طوری پارامتر نکنید که مجموعه ای از پارامترها منحصر به فرد وجود داشته باشد. برای مثال، اگر foo روی X تنظیم شده باشد، باید پارامترهای bar ، baz نیز تنظیم کنید، در غیر این صورت این پارامترها باید None باشند. این نشان می دهد که شما می توانستید دو برنامه متفاوت برای مقادیر مختلف foo بسازید.

پارامترهای گروه

از پروتو برای تعریف پارامترهای مرتبط اما پیچیده یا پرمخاطب به جای تعریف تعداد زیادی 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)

منطق پایتون

منطق (مثلاً جریان کنترل، فراخوانی محاسبات، هر چیزی که نیاز به آزمایش دارد) را در برنامه ننویسید . در عوض، منطق را به یک کتابخانه خصوصی که قابل آزمایش است یا به منطق برنامه ای که برنامه فراخوانی می کند منتقل کنید.

توابع ناهمزمان

توابع ناهمزمان را در برنامه ننویسید . در عوض، تابع را به یک کتابخانه خصوصی که قابل آزمایش است یا به منطق برنامه ای که برنامه فراخوانی می کند منتقل کنید.

تست ها

تست های واحد را برای برنامه ننویسید ، اگر آزمایش برنامه مفید است، آن تست ها را از نظر تست های یکپارچه سازی بنویسید.