دليل مطور البرنامج الموحد

هذه الوثائق مخصصة لأي شخص مهتم بتأليف منطق البرنامج الموحد أو البرنامج الموحد . يفترض معرفة 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 عدم المزامنة لتنفيذ Python بشكل متزامن، كما أن تحديد منطق البرنامج كوظيفة غير متزامنة يجعل من السهل التفاعل مع تلك المكونات.

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

لا

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

الاختبارات

قم بتوفير اختبارات الوحدة لمنطق البرنامج (على سبيل المثال، Program_logic_test.py ).

برنامج

يحدد هذا القسم المبادئ التوجيهية لكيفية تأليف البرنامج .

راجع مثال البرنامج.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)

منطق بايثون

لا تكتب المنطق (مثل التحكم في التدفق، واستدعاء العمليات الحسابية، أو أي شيء يحتاج إلى اختبار) في البرنامج. بدلاً من ذلك، انقل المنطق إلى مكتبة خاصة يمكن اختبارها أو إلى منطق البرنامج الذي يستدعيه البرنامج.

وظائف غير متزامنة

لا تكتب وظائف غير متزامنة في البرنامج. بدلاً من ذلك، انقل الوظيفة إلى مكتبة خاصة يمكن اختبارها أو إلى منطق البرنامج الذي يستدعيه البرنامج.

الاختبارات

لا تكتب اختبارات الوحدة للبرنامج، إذا كان اختبار البرنامج مفيدًا فاكتب تلك الاختبارات من حيث اختبارات التكامل.