راهنمای توسعه‌دهنده شخصی‌سازی روی دستگاه، راهنمای توسعه‌دهنده شخصی‌سازی روی دستگاه، راهنمای توسعه‌دهنده شخصی‌سازی روی دستگاه

شخصی سازی روی دستگاه (ODP) برای محافظت از اطلاعات کاربران نهایی در برابر برنامه ها طراحی شده است. برنامه‌ها از ODP برای سفارشی‌سازی محصولات و خدمات خود برای کاربران نهایی استفاده می‌کنند، اما نمی‌توانند سفارشی‌سازی‌های دقیق انجام‌شده برای کاربر را ببینند (مگر اینکه تعاملات مستقیم خارج از ODP بین برنامه و کاربر نهایی وجود داشته باشد). برای برنامه‌های کاربردی با مدل‌های یادگیری ماشینی یا تحلیل‌های آماری، ODP مجموعه‌ای از خدمات و الگوریتم‌ها را ارائه می‌کند تا اطمینان حاصل کند که با استفاده از مکانیسم‌های Differential Privacy مناسب، ناشناس هستند. برای جزئیات بیشتر، به توضیح شخصی سازی روی دستگاه مراجعه کنید.

ODP کد برنامه‌نویس را در یک IsolatedProcess اجرا می‌کند که دسترسی مستقیم به شبکه، دیسک‌های محلی یا سایر سرویس‌های در حال اجرا بر روی دستگاه ندارد اما به منابع داده محلی زیر دسترسی دارد:

• RemoteData - داده‌های کلید-مقدار غیرقابل تغییر که در صورت وجود از راه‌دورهایی که توسط توسعه‌دهنده کار می‌کنند دانلود می‌شوند.
• LocalData - داده‌های کلید-مقدار قابل تغییر که در صورت وجود، توسط توسعه‌دهنده حفظ می‌شوند.
• UserData - داده های کاربر ارائه شده توسط پلت فرم.

خروجی های زیر پشتیبانی می شوند:

• خروجی دائمی: این خروجی ها را می توان در پردازش محلی آینده، تولید خروجی های نمایش داده شده، آموزش مدل تسهیل شده با یادگیری فدرال، یا تجزیه و تحلیل آماری بین دستگاهی تسهیل شده توسط Federated Analytics استفاده کرد.
  • توسعه دهندگان می توانند درخواست ها و همچنین نتایج پردازش آنها را در جدول REQUESTS محلی بنویسند.
  • توسعه دهندگان می توانند داده های اضافی مرتبط با درخواست قبلی را در جدول EVENTS بنویسند.
• خروجی نمایش داده شده:
  • توسعه دهندگان می توانند HTML را که توسط ODP در WebView در داخل SurfaceView ارائه شده است، برگردانند. محتوای ارائه شده در آنجا برای برنامه فراخوان قابل مشاهده نخواهد بود.
  • توسعه دهندگان می توانند URL های رویداد ارائه شده توسط ODP را در خروجی HTML جاسازی کنند تا ثبت و پردازش تعاملات کاربر با HTML ارائه شده را آغاز کنند. ODP درخواست ها را به آن URL ها رهگیری می کند و کد را برای تولید داده هایی که در جدول EVENTS نوشته می شود فراخوانی می کند.

برنامه‌های کلاینت و SDK می‌توانند از ODP برای نمایش محتوای HTML در SurfaceView با استفاده از ODP API استفاده کنند. محتوای ارائه شده در SurfaceView برای برنامه تماس قابل مشاهده نیست. برنامه سرویس گیرنده یا SDK می تواند موجودیت متفاوتی نسبت به آنچه با ODP در حال توسعه است باشد.

سرویس ODP برنامه مشتری را مدیریت می کند که می خواهد ODP را برای نمایش محتوای شخصی شده در UI خود فراخوانی کند. این برنامه محتوا را از نقاط پایانی ارائه شده توسط توسعه دهنده دانلود می کند و منطق را برای پس پردازش داده های دانلود شده فراخوانی می کند. همچنین تمام ارتباطات بین IsolatedProcess و سایر سرویس ها و برنامه ها را واسطه می کند.

برنامه‌های سرویس گیرنده از روش‌هایی در کلاس OnDevicePersonalizationManager برای تعامل با کد توسعه‌دهنده در حال اجرا در یک IsolatedProcess استفاده می‌کنند. کد برنامه نویسی که در یک IsolatedProcess اجرا می شود کلاس IsolatedService را گسترش می دهد و رابط IsolatedWorker را پیاده سازی می کند. IsolatedService باید برای هر درخواست یک نمونه از IsolatedWorker ایجاد کند.

نمودار زیر رابطه بین متدهای OnDevicePersonalizationManager و IsolatedWorker را نشان می دهد.

نمودار رابطه بین OnDevicePersonalizationManager و IsolatedWorker .

یک برنامه مشتری ODP را با استفاده از روش execute با نام IsolatedService فراخوانی می کند. سرویس ODP تماس را به متد onExecute IsolatedWorker ارسال می کند. IsolatedWorker سوابق را برای ماندگاری و نمایش محتوا برمی‌گرداند. سرویس ODP خروجی دائمی را در جدول REQUESTS یا EVENTS می نویسد و یک مرجع غیر شفاف به خروجی نمایش داده شده به برنامه مشتری برمی گرداند. برنامه مشتری می‌تواند از این مرجع غیرشفاف در یک تماس requestSurfacePackage در آینده برای نمایش هر یک از محتوای نمایشی در رابط کاربری خود استفاده کند.

خروجی پایدار

سرویس ODP یک رکورد را در جدول REQUESTS پس از اجرای برنامه onExecute برمی گرداند. هر رکورد در جدول REQUESTS حاوی برخی از داده‌های رایج در هر درخواست است که توسط سرویس ODP تولید می‌شود و فهرستی از Rows بازگردانده شده است. هر Row حاوی لیستی از جفت (key, value) است. هر مقدار یک اسکالر، رشته یا حباب است. مقادیر عددی را می توان پس از تجمیع گزارش کرد، و داده های رشته یا حباب را می توان پس از اعمال حریم خصوصی دیفرانسیل محلی یا مرکزی گزارش کرد. توسعه دهندگان همچنین می توانند رویدادهای تعامل کاربر بعدی را در جدول EVENTS بنویسند - هر رکورد در جدول EVENTS با یک ردیف در جدول REQUESTS مرتبط است. سرویس ODP به طور شفاف یک مهر زمانی و نام بسته برنامه تماس و APK توسعه دهنده ODP را با هر رکورد ثبت می کند.

قبل از شروع

قبل از شروع توسعه با ODP، باید مانیفست بسته خود را تنظیم کنید و حالت توسعه دهنده را فعال کنید.

تنظیمات مانیفست بسته

برای استفاده از ODP موارد زیر مورد نیاز است:

1. یک تگ <property> در AndroidManifest.xml که به یک منبع XML در بسته اشاره می کند که حاوی اطلاعات پیکربندی ODP است.
2. یک تگ <service> در AndroidManifest.xml که کلاسی را که IsolatedService گسترش می دهد، مشخص می کند، همانطور که در مثال زیر نشان داده شده است. سرویس در تگ <service> باید دارای ویژگی های exported و isolatedProcess باشد که روی true تنظیم شده است.
3. تگ <service> در منبع XML مشخص شده در مرحله 1 که کلاس سرویس را از مرحله 2 شناسایی می کند. تگ <service> همچنین باید تنظیمات اضافی ODP را در داخل خود تگ شامل شود، همانطور که در مثال دوم نشان داده شده است.

AndroidManifest.xml

<!-- Contents of AndroidManifest.xml -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="com.example.odpsample" >
    <application android:label="OdpSample">
        <!-- XML resource that contains other ODP settings. -->
        <property android:name="android.ondevicepersonalization.ON_DEVICE_PERSONALIZATION_CONFIG"
                  android:resource="@xml/OdpSettings"></property>
        <!-- The service that ODP binds to. -->
        <service android:name="com.example.odpsample.SampleService"
                android:exported="true" android:isolatedProcess="true" />
    </application>
</manifest>

مانیفست ODP-Specific در منبع XML

فایل منبع XML مشخص شده در تگ <property> نیز باید کلاس سرویس را در تگ <service> اعلام کند و نقطه پایانی URL را که ODP از آن محتوا را برای پر کردن جدول RemoteData دانلود می کند، مشخص کند، همانطور که در مثال زیر نشان داده شده است. اگر از ویژگی‌های محاسباتی فدرال استفاده می‌کنید، باید نقطه پایانی URL سرور محاسباتی فدرال را نیز مشخص کنید که Client محاسباتی فدرال به آن متصل می‌شود.

<!-- Contents of res/xml/OdpSettings.xml -->
<on-device-personalization>
   <!-- Name of the service subclass -->
   <service name="com.example.odpsample.SampleService">
     <!-- If this tag is present, ODP will periodically poll this URL and
          download content to populate REMOTE_DATA. Developers that do not need to
          download content from their servers can skip this tag. -->
     <download-settings url="https://example.com/get" />
     <!-- If you want to use federated compute feature to train a model, you
          need to specify this tag. -->
     <federated-compute-settings url="https://fcpserver.example.com/" />
   </service>
</on-device-personalization>

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

با دنبال کردن دستورالعمل‌های بخش Enable Developer Options در مستندات Android Studio، حالت برنامه‌نویس را فعال کنید.

تنظیمات سوئیچ و پرچم

ODP دارای مجموعه ای از سوئیچ ها و پرچم ها است که برای کنترل عملکردهای خاص استفاده می شود:

• سوئیچ _global_kill : سوئیچ جهانی برای همه ویژگی های ODP. برای استفاده از ODP روی false تنظیم کنید
• _federated_compute_kill_switch: _ سوئیچ کنترل کننده تمامی قابلیت های آموزشی (یادگیری فدرال) ODP. برای استفاده از آموزش روی false تنظیم کنید
• لیست _caller_app_allow : کنترل هایی که مجاز به تماس با ODP هستند، برنامه ها (نام pkg، گواهی [اختیاری]) را می توان در اینجا اضافه کرد یا آن را به عنوان * تنظیم کرد تا به همه اجازه دهد.
• _isolated_service_allow list : کنترل می کند که کدام سرویس ها می توانند در فرآیند Isolated Service اجرا شوند.

می‌توانید دستورات زیر را برای پیکربندی همه سوئیچ‌ها و پرچم‌ها برای استفاده از ODP بدون محدودیت اجرا کنید:

# Set flags and killswitches
adb shell device_config set_sync_disabled_for_tests persistent
adb shell device_config put on_device_personalization global_kill_switch false
adb shell device_config put on_device_personalization federated_compute_kill_switch false
adb shell device_config put on_device_personalization caller_app_allow_list \"*\"
adb shell device_config put on_device_personalization isolated_service_allow_list \"*\"

API های سمت دستگاه

مستندات مرجع Android API برای ODP را بررسی کنید.

تعامل با IsolatedService

کلاس IsolatedService یک کلاس پایه انتزاعی است که همه توسعه دهندگانی که قصد توسعه در برابر ODP را دارند باید آن را گسترش دهند و در بسته خود اعلام کنند که در یک فرآیند ایزوله اجرا می شود. سرویس ODP این سرویس را در یک فرآیند ایزوله راه اندازی می کند و درخواست هایی را برای آن ارسال می کند. IsolatedService درخواست هایی را از سرویس ODP دریافت می کند و یک IsolatedWorker برای رسیدگی به درخواست ایجاد می کند.

توسعه‌دهندگان باید روش‌هایی را از رابط IsolatedWorker پیاده‌سازی کنند تا درخواست‌های برنامه مشتری، تکمیل‌های دانلود و رویدادهایی را که توسط HTML ارائه‌شده ایجاد می‌شوند، مدیریت کنند. همه این متدها پیاده‌سازی‌های بدون عملیات پیش‌فرض دارند، بنابراین توسعه‌دهندگان می‌توانند از پیاده‌سازی روش‌هایی که علاقه‌ای به آنها ندارند صرف نظر کنند.

کلاس OnDevicePersonalizationManager یک API برای برنامه ها و SDK ها فراهم می کند تا با یک IsolatedService پیاده سازی شده توسط توسعه دهنده که در یک فرآیند ایزوله اجرا می شود تعامل داشته باشند. موارد زیر برخی از موارد استفاده مورد نظر هستند:

محتوای HTML را برای نمایش در SurfaceView تولید کنید

برای تولید محتوا برای نمایش، با OnDevicePersonalizationManager#execute ، برنامه فراخوان می‌تواند از شی SurfacePackageToken برگشتی در یک فراخوانی requestSurfacePackage بعدی استفاده کند تا نتیجه را در یک SurfaceView ارائه کند.

در صورت موفقیت، گیرنده با یک SurfacePackage برای نمای ارائه شده توسط سرویس ODP فراخوانی می شود. برنامه های مشتری باید SurfacePackage را در یک SurfaceView در سلسله مراتب View خود وارد کنند.

هنگامی که یک برنامه یک requestSurfacePackage را با SurfacePackageToken که توسط یک تماس قبلی OnDevicePersonalizationManager#execute ، سرویس ODP IsolatedWorker#onRender فراخوانی می‌کند تا قطعه HTML در یک قاب محصور ارائه شود. یک توسعه دهنده در این مرحله به LocalData یا UserData دسترسی ندارد. این مانع از برنامه‌نویس می‌شود که UserData بالقوه حساس را در URLهای واکشی دارایی در HTML تولید شده جاسازی کند. توسعه دهندگان می توانند از IsolatedService#getEventUrlProvider برای ایجاد URL های ردیابی برای گنجاندن در HTML تولید شده استفاده کنند. هنگامی که HTML ارائه می شود، سرویس ODP درخواست های این URL ها را رهگیری می کند و IsolatedWorker#onEvent فراخوانی می کند. هنگام پیاده سازی onRender() می توان getRemoteData() فراخوانی کرد.

ردیابی رویدادها در محتوای HTML

کلاس EventUrlProvider API هایی را برای ایجاد URL های ردیابی رویداد ارائه می دهد که توسعه دهندگان ممکن است در خروجی HTML خود قرار دهند. هنگامی که HTML ارائه می شود، ODP IsolatedWorker#onEvent با بارگذاری URL رویداد فراخوانی می کند.

سرویس ODP درخواست‌ها را به آدرس‌های اینترنتی رویداد تولید شده ODP در HTML رندر شده رهگیری می‌کند، IsolatedWorker#onEvent را فراخوانی می‌کند و EventLogRecord بازگشتی را در جدول EVENTS ثبت می‌کند.

نتایج پایدار را بنویسید

با OnDevicePersonalizationManager#execute ، این سرویس این گزینه را دارد که داده ها را در ذخیره سازی دائمی بنویسد (جدول REQUESTS و EVENTS ). در اینجا ورودی هایی است که می توان در این جداول نوشت:

• یک RequestLogRecord برای اضافه شدن به جدول REQUESTS .
• لیستی از اشیاء EventLogRecord که باید به جدول EVENTS اضافه شوند، که هر کدام حاوی یک اشاره گر به یک RequestLogRecord از قبل نوشته شده است.

نتایج پایدار در ذخیره سازی روی دستگاه را می توان توسط Federated Learning برای آموزش مدل مصرف کرد.

وظایف آموزشی روی دستگاه را مدیریت کنید

سرویس ODP هنگامی که یک کار آموزش محاسباتی فدرال شروع می شود و می خواهد نمونه های آموزشی ارائه شده توسط توسعه دهندگانی که ODP را اتخاذ می کنند، دریافت کند IsolatedWorker#onTrainingExample فراخوانی می کند. می توانید هنگام پیاده سازی onTrainingExample() getRemoteData() ، getLocalData() ، getUserData() و getLogReader() را فراخوانی کنید.

برای زمان‌بندی یا لغو کارهای محاسباتی فدرال، می‌توانید از کلاس FederatedComputeScheduler استفاده کنید که API را برای همه ODP IsolatedService ارائه می‌کند. هر کار محاسباتی فدرال را می توان با نام جمعیت آن شناسایی کرد.

قبل از اینکه یک کار محاسباتی فدرال جدید را برنامه ریزی کنید:

• یک کار با این نام جمعیت باید قبلاً روی سرور محاسباتی فدرال راه دور ایجاد شود.
• نقطه پایانی URL سرور محاسباتی فدرال باید از قبل در تنظیمات مانیفست بسته با تگ federated-compute-settings مشخص شده باشد.

تعامل با خروجی پایدار

بخش زیر نحوه تعامل با خروجی پایدار در ODP را شرح می دهد.

جداول محلی را بخوانید

کلاس LogReader API هایی را برای خواندن جداول REQUESTS و EVENTS ارائه می دهد. این جداول حاوی داده‌هایی هستند که توسط IsolatedService در طول فراخوانی‌های onExecute() یا onEvent() نوشته شده‌اند. داده‌های موجود در این جداول را می‌توان برای آموزش مدل تسهیل‌شده با یادگیری فدرال، یا تحلیل آماری بین دستگاهی تسهیل‌شده توسط Federated Analytics استفاده کرد.

تعامل با محتوای دانلود شده

بخش زیر نحوه تعامل با محتوای دانلود شده در ODP را شرح می دهد.

دانلود محتوا از سرورها

سرویس ODP به صورت دوره‌ای محتوا را از URL اعلام شده در مانیفست بسته IsolatedService دانلود می‌کند و پس از پایان دانلود، روی onDownloadCompleted فراخوانی می‌کند. دانلود یک فایل JSON حاوی جفت های کلید-مقدار است.

توسعه دهندگانی که ODP را اتخاذ می کنند می توانند انتخاب کنند که کدام زیرمجموعه از محتوای دانلود شده به جدول RemoteData اضافه شود و کدام یک حذف شود. برنامه نویسان نمی توانند محتویات دانلود شده را تغییر دهند - این تضمین می کند که جدول RemoteData حاوی هیچ داده کاربری نیست. علاوه بر این، توسعه دهندگان آزادند تا جدول LocalData را به دلخواه خود پر کنند. به عنوان مثال، آنها می توانند برخی از نتایج از پیش محاسبه شده را ذخیره کنند.

فرمت درخواست دانلود

ODP به صورت دوره ای نقطه پایان URL اعلام شده در مانیفست بسته توسعه دهنده را نظرسنجی می کند تا محتوا را برای پر کردن جدول RemoteData واکشی کند.

انتظار می رود نقطه پایانی همانگونه که بعدا توضیح داده شد، پاسخ JSON را برگرداند. پاسخ JSON باید حاوی یک syncToken باشد که نسخه داده ارسالی را به همراه فهرستی از جفت‌های کلید-مقدار که باید پر شوند، شناسایی می‌کند. مقدار syncToken باید یک مُهر زمانی بر حسب ثانیه باشد که به یک مرز ساعت UTC متصل شود. به عنوان بخشی از درخواست دانلود، ODP syncToken دانلود قبلی تکمیل شده و کشور دستگاه را به عنوان پارامترهای syncToken و کشور در URL دانلود ارائه می دهد. سرور می تواند از syncToken قبلی برای اجرای دانلودهای افزایشی استفاده کند.

فرمت فایل دانلود کنید

فایل دانلود شده یک فایل JSON با ساختار زیر می باشد. انتظار می رود فایل JSON حاوی یک syncToken برای شناسایی نسخه داده ای باشد که دانلود می شود. syncToken باید یک مهر زمانی UTC باشد که به مرز یک ساعت بسته شده است و باید از syncToken دانلود قبلی بیشتر باشد. اگر syncToken هر دو الزامات را برآورده نکند، محتوای دانلود شده بدون پردازش کنار گذاشته می شود.

فیلد محتویات فهرستی از چند تاپل (کلید، داده، رمزگذاری) است. انتظار می رود که key یک رشته UTF-8 باشد. فیلد encoding یک پارامتر اختیاری است که نحوه کدگذاری فیلد data را مشخص می‌کند - می‌توان آن را روی «utf8» یا «base64» تنظیم کرد و به‌طور پیش‌فرض «utf8» در نظر گرفته می‌شود. فیلد key به یک شی String و فیلد data قبل از فراخوانی onDownloadCompleted().

{
  // syncToken must be a UTC timestamp clamped to an hour boundary, and must be
  // greater than the syncToken of the previously completed download.
  "syncToken": <timeStampInSecRoundedToUtcHour>,
  "contents": [
    // List of { key, data } pairs.
    { "key": "key1",
      "data": "data1"
    },
    { "key": "key2",
      "data": "data2",
      "encoding": "base64"
    },
    // ...
  ]
}

API های سمت سرور

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

APIهای سرور محاسباتی فدرال

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

نمودار توپولوژی محاسباتی مشتری-سرور فدرال.

هنگام ایجاد یک کار جدید برای Task Builder، توسعه دهندگان ODP باید دو مجموعه از فایل ها را ارائه دهند:

1. یک مدل tff.learning.models.FunctionalModel ذخیره شده از طریق فراخوانی تماس API tff.learning.models.save_functional_model . می توانید یک نمونه را در مخزن GitHub ما پیدا کنید.
2. یک fcp_server_config.json که شامل خط‌مشی‌ها، راه‌اندازی یادگیری فدرال و تنظیم حریم خصوصی متفاوت است. مثال زیر یک نمونه از fcp_server_config.json است:

{
  # Task execution mode.
  mode: TRAINING_AND_EVAL
  # Identifies the set of client devices that participate.
  population_name: "mnist_cnn_task"
  policies {
    # Policy for sampling on-device examples. It is checked every
    # time a device is attempting to start a new training.
    min_separation_policy {
      # The minimum separation required between two successful
      # consective task executions. If a client successfully contributes
      # to a task at index `x`, the earliest they can contribute again
      # is at index `(x + minimum_separation)`. This is required by
      # DP.
      minimum_separation: 1
    }
    data_availability_policy {
      # The minimum number of examples on a device to be considered
      # eligible for training.
      min_example_count: 1
    }
    # Policy for releasing training results to developers adopting ODP.
    model_release_policy {
      # The maximum number of training rounds.
      num_max_training_rounds: 512
    }
  }

  # Federated learning setups. They are applied inside Task Builder.
  federated_learning {
    # Use federated averaging to build federated learning process.
    # Options you can choose:
      # * FED_AVG: Federated Averaging algorithm
      #            (https://arxiv.org/abs/2003.00295)
      # * FED_SGD: Federated SGD algorithm
      #            (https://arxiv.org/abs/1602.05629)
    type: FED_AVG
    learning_process {
      # Optimizer used at client side training. Options you can choose:
      # * ADAM
      # * SGD
      client_optimizer: SGD
      # Learning rate used at client side training.
      client_learning_rate: 0.02
      # Optimizer used at server side training. Options you can choose:
      # * ADAM
      # * SGD
      server_optimizer: SGD
      # Learning rate used at server side training.
      server_learning_rate: 1.0
      runtime_config {
        # Number of participating devices for each round of training.
      report_goal: 2
      }
      metrics {
        name: "sparse_categorical_accuracy"
      }
    }
    evaluation {
      # A checkpoint selector controls how checkpoints are chosen for
      # evaluation. One evaluation task typically runs per training
      # task, and on each round of execution, the eval task
      # randomly picks one checkpoint from the past 24 hours that has
      # been selected for evaluation by these rules.
      # Every_k_round and every_k_hour are definitions of quantization
      # buckets which each checkpoint is placed in for selection.
      checkpoint_selector: "every_1_round"
      # The percentage of a populate that should delicate to this
      # evaluation task.
      evaluation_traffic: 0.2
      # Number of participating devices for each round of evaluation.
      report_goal: 2
    }
  }

  # Differential Privacy setups. They are enforced inside the Task
  # Builder.
  differential_privacy {
    # * fixed_gaussian: DP-SGD with fixed clipping norm described in
    #                   "Learning Differentially Private Recurrent
    #                   Language Models"
    #                   (https://arxiv.org/abs/1710.06963).
    type: FIXED_GAUSSIAN
    #   The value of the clipping norm.
    clip_norm: 0.1
    # Noise multiplier for the Gaussian noise.
    noise_multiplier: 0.1
  }
}

می توانید نمونه های بیشتری را در مخزن GitHub ما بیابید.

پس از آماده سازی این دو ورودی، Task Builder را برای ساخت مصنوعات و ایجاد وظایف جدید فراخوانی کنید. دستورالعمل های دقیق تر در مخزن GitHub ما موجود است.