מדריך למפתחי תוכנית מאוחדת

תיעוד זה מיועד לכל מי שמעוניין ליצור לוגיקה של תוכנית מאוחדת או תוכנית מאוחדת . הוא מניח ידע על 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 .

פרמטרים של קבוצה

השתמש בפרוטו כדי להגדיר פרמטרים קשורים אך מורכבים או מפורטים במקום להגדיר 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)

פייתון לוגיקה

אל תכתוב לוגיקה (למשל זרימת בקרה, הפעלת חישובים, כל דבר שצריך לבדוק) בתוכנית. במקום זאת, העבר את ההיגיון לספרייה פרטית שניתן לבדוק או ללוגיקה של התוכנית שהתוכנית מפעילה.

פונקציות אסינכרוניות

אל תכתוב פונקציות אסינכרוניות בתוכנית. במקום זאת, העבר את הפונקציה לספרייה פרטית שניתן לבדוק או ללוגיקה של התוכנית שהתוכנית מפעילה.

מבחנים

אל תכתוב מבחני יחידה עבור התוכנית, אם בדיקת התוכנית שימושית כתוב את המבחנים האלה מבחינת מבחני אינטגרציה.