Cihaz üzerinde kişiselleştirme geliştirici kılavuzu

Cihaz üzerinde kişiselleştirme (ODP), son kullanıcıların bilgilerini uygulamalardan korumak için tasarlanmıştır. Uygulamalar, ürünlerini ve hizmetlerini son kullanıcılar için özelleştirmek amacıyla ODP'yi kullanır ancak kullanıcı için yapılan özelleştirmeleri tam olarak göremez (uygulama ile son kullanıcı arasında ODP dışında doğrudan etkileşim olmadığı sürece). ODP, makine öğrenimi modelleri veya istatistiksel analizler içeren uygulamalar için uygun diferansiyel gizlilik mekanizmaları kullanılarak uygun şekilde anonimleştirilmelerini sağlamak amacıyla bir dizi hizmet ve algoritma sağlar. Ayrıntılı bilgi için Cihaz üzerinde kişiselleştirme konulu açıklamayı inceleyin.

ODP, geliştirici kodunu ağ, yerel diskler veya cihazda çalışan diğer hizmetlere doğrudan erişimi olmayan ancak yerel olarak kalıcı olan aşağıdaki veri kaynaklarına erişimi olan bir IsolatedProcess içinde çalıştırır:

  • RemoteData: Varsa uzaktan, geliştirici tarafından işletilen arka uçlardan indirilen, değiştirilemeyen anahtar/değer verileri.
  • LocalData: Varsa geliştirici tarafından yerel olarak kalıcı olarak tutulan, değiştirilebilir anahtar/değer verileri.
  • UserData: Platform tarafından sağlanan kullanıcı verileri.

Aşağıdaki çıkışlar desteklenir:

  • Kalıcı çıkış: Bu çıkışlar, gelecekteki yerel işlemlerde kullanılabilir, görüntülenen çıkışlar, Birleşik Öğrenme destekli model eğitimi veya Birleşik Analizler destekli cihazlar arası istatistiksel analizler oluşturabilir.
    • Geliştiriciler, isteklerin yanı sıra işleme sonuçlarını yerel REQUESTS tablosuna yazabilir.
    • Geliştiriciler, önceki bir istekle ilişkili ek verileri EVENTS tablosuna yazabilir.
  • Gösterilen çıkış:
    • Geliştiriciler, ODP tarafından oluşturulan HTML'yi SurfaceView içinde bir WebView olarak döndürebilir. Burada oluşturulan içerik, çağıran uygulama tarafından görülemez.
    • Geliştiriciler, kullanıcı etkileşimlerinin oluşturulan HTML ile kaydedilmesini ve işlenmesini tetiklemek için ODP tarafından sağlanan etkinlik URL'lerini HTML çıktısına yerleştirebilir. ODP, bu URL'lere yönelik istekleri durdurur ve EVENTS tablosuna yazılacak verileri oluşturmak için kodu çağırır.

İstemci uygulamaları ve SDK'lar, ODP API'lerini kullanarak HTML içeriğini SurfaceView içinde görüntülemek için ODP'yi çağırabilir. SurfaceView içinde oluşturulan içerik, arayan uygulama tarafından görülemez. İstemci uygulaması veya SDK, ODP ile geliştirilen uygulamadan farklı bir varlık olabilir.

ODP hizmeti, kullanıcı arayüzünde kişiselleştirilmiş içerik göstermek için ODP'yi çağırmak isteyen istemci uygulamasını yönetir. Geliştirici tarafından sağlanan uç noktalardan içerik indirir ve indirilen verilerin son işleme tabi tutulması için mantığı çağırır. Ayrıca, IsolatedProcess ile diğer hizmetler ve uygulamalar arasındaki tüm iletişimlere aracılık eder.

İstemci uygulamaları, geliştiricinin IsolatedProcess'da çalışan koduyla etkileşime geçmek için OnDevicePersonalizationManager sınıfındaki yöntemleri kullanır. Geliştiricinin IsolatedProcess içinde çalışan kodu, IsolatedService sınıfını genişletir ve IsolatedWorker arayüzünü uygular. IsolatedService'ün her istek için bir IsolatedWorker örneği oluşturması gerekir.

Aşağıdaki şemada, OnDevicePersonalizationManager ve IsolatedWorker'daki yöntemler arasındaki ilişki gösterilmektedir.

OnDevicePersonalizationManager ile IsolatedWorker arasındaki ilişkiyi gösteren şema.

Bir istemci uygulaması, IsolatedService adlı bir execute yöntemini kullanarak ODP'yi çağırır. ODP hizmeti, çağrıyı IsolatedWorker öğesinin onExecute yöntemine yönlendirir. IsolatedWorker, kalıcı olacak kayıtları ve gösterilecek içeriği döndürür. ODP hizmeti, kalıcı çıktıyı REQUESTS veya EVENTS tablosuna yazar ve görüntülenen çıktıya dair opak bir referans döndürür. İstemci uygulaması, kullanıcı arayüzünde görüntülenen içeriklerden herhangi birini görüntülemek için gelecekteki bir requestSurfacePackage çağrısında bu opak referansı kullanabilir.

Kalıcı çıkış

Geliştiricinin onExecute döndürmesi sonrasında ODP hizmeti, REQUESTS tablosunda bir kaydı devam ettirir. REQUESTS tablosundaki her kayıt, ODP hizmeti tarafından oluşturulan bazı ortak istek başına verileri ve döndürülen Rows listesini içerir. Her Row, (key, value) çiftlerinin bir listesini içerir. Her değer bir skaler, dize veya blob'tur. Sayısal değerler toplama işleminden sonra, dize veya blob verileri ise yerel veya merkezi diferansiyel gizlilik uygulandıktan sonra raporlanabilir. Geliştiriciler, sonraki kullanıcı etkileşimi etkinliklerini EVENTS tablosuna da yazabilir. EVENTS tablosundaki her kayıt, REQUESTS tablosundaki bir satırla ilişkilendirilir. ODP hizmeti, her kayıtla birlikte zaman damgasını, çağıran uygulamanın paket adını ve ODP geliştiricisinin APK'sını şeffaf bir şekilde günlüğe kaydeder.

Başlamadan önce

ODP ile geliştirmeye başlamadan önce paket manifestinizi ayarlamanız ve geliştirici modunu etkinleştirmeniz gerekir.

Paket manifesti ayarları

ODP'yi kullanmak için aşağıdakiler gereklidir:

  1. AndroidManifest.xml içindeki ve pakette ODP yapılandırma bilgilerini içeren bir XML kaynağına işaret eden <property> etiketi.
  2. Aşağıdaki örnekte gösterildiği gibi, AndroidManifest.xml içinde IsolatedService sınıfını genişleten sınıfı tanımlayan bir <service> etiketi. <service> etiketindeki hizmetin exported ve isolatedProcess özellikleri true olarak ayarlanmalıdır.
  3. 1. adımda belirtilen XML kaynağında, 2. adımdaki hizmet sınıfını tanımlayan bir <service> etiketi. <service> etiketi, ikinci örnekte gösterildiği gibi etiketin içinde ODP'ye özgü ek ayarlar da içermelidir.

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>

XML kaynağında ODP'ye özgü manifest

<property> etiketinde belirtilen XML kaynak dosyası, <service> etiketinde hizmet sınıfını da tanımlamalı ve aşağıdaki örnekte gösterildiği gibi ODP'nin RemoteData tablosunu doldurmak için içerik indireceği URL uç noktasını belirtmelidir. Birleştirilmiş hesaplama özelliklerini kullanıyorsanız birleşik hesaplama istemcisinin bağlanacağı birleşik hesaplama sunucusu URL uç noktasını da belirtmeniz gerekir.

<!-- 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>

Geliştirici modunu etkinleştirme

Android Studio belgelerindeki Geliştirici Seçenekleri'ni Etkinleştirme bölümündeki talimatları uygulayarak geliştirici modunu etkinleştirin.

Geçiş ve işaret ayarları

ODP'de belirli işlevleri kontrol etmek için kullanılan bir dizi anahtar ve işaret vardır:

  • _global_killswitch: Tüm ODP özellikleri için genel anahtar; ODP'yi kullanmak üzere false olarak ayarlanır
  • _federated_compute_kill_switch: _ODP'nin tüm eğitim (federe öğrenme) işlevlerini kontrol eden anahtar; eğitimi kullanmak için false olarak ayarlanır
  • _caller_app_allowlist: ODP'yi kimin çağırmasına izin verileceğini kontrol eder. Uygulamalar (pkg adı, [isteğe bağlı] sertifika) buraya eklenebilir veya tümüne izin vermek için * olarak ayarlanabilir.
  • _isolated_service_allowlist: İzole Hizmet işleminde hangi hizmetlerin çalışabileceğini kontrol eder.

Tüm anahtarları ve işaretleri ODP'yi kısıtlama olmadan kullanacak şekilde yapılandırmak için aşağıdaki komutları çalıştırabilirsiniz:

# 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 \"*\"

Cihaz tarafı API'ler

ODP için Android API referans dokümanlarına göz atın.

IsolatedService ile etkileşimler

IsolatedService sınıfı, ODP'ye göre geliştirme yapmayı amaçlayan tüm geliştiricilerin genişletmesi ve paket manifestlerinde izole bir işlemde çalışacak şekilde beyan etmesi gereken soyut bir temel sınıftır. ODP hizmeti, bu hizmeti izole bir işlemde başlatır ve hizmete istek gönderir. IsolatedService, ODP hizmetinden istek alır ve isteği işlemek için bir IsolatedWorker oluşturur.

Geliştiricilerin, istemci uygulaması isteklerini, indirme işlemlerinin tamamlanmasını ve oluşturulan HTML tarafından tetiklenen etkinlikleri işlemek için IsolatedWorker arayüzündeki yöntemleri uygulaması gerekir. Bu yöntemlerin tümü varsayılan olarak işlem yapmayan uygulamalara sahiptir. Bu sayede geliştiriciler ilgilenmedikleri yöntemleri uygulamayı atlayabilir.

OnDevicePersonalizationManager sınıfı, uygulamaların ve SDK'ların, geliştirici tarafından uygulanan ve izole bir işlemde çalışan IsolatedService ile etkileşim kurması için bir API sağlar. Aşağıda, amaçlanan kullanım alanlarından bazıları verilmiştir:

SurfaceView'da görüntülenecek HTML içeriği oluşturma

Arama yapan uygulama, OnDevicePersonalizationManager#execute ile görüntülenecek içerik oluşturmak için sonraki bir requestSurfacePackage çağrısında döndürülen SurfacePackageToken nesnesini kullanarak sonucun SurfaceView olarak oluşturulmasını isteyebilir .

İşlem başarılı olduğunda alıcı, ODP hizmeti tarafından oluşturulan bir görünüm için SurfacePackage ile çağrılır. Müşteri uygulamalarının, SurfacePackage öğesini Görüntü hiyerarşisi içindeki bir SurfaceView içine yerleştirmesi gerekir.

Bir uygulama, önceki bir OnDevicePersonalizationManager#execute çağrısı tarafından döndürülen bir SurfacePackageToken ile requestSurfacePackage çağrısı yaptığında ODP hizmeti, çitle çevrili bir çerçeve içinde oluşturulacak HTML snippet'ini almak için IsolatedWorker#onRender çağrısı yapar. Geliştiriciler bu aşamada LocalData veya UserData'a erişemez. Bu, geliştiricinin oluşturulan HTML'deki öğe getirme URL'lerine hassas olabilecek UserData yerleştirmesini engeller. Geliştiriciler, oluşturulan HTML'ye dahil edilecek izleme URL'leri oluşturmak için IsolatedService#getEventUrlProvider kullanabilir. HTML oluşturulduğunda ODP hizmeti bu URL'lere yapılan istekleri durdurur ve IsolatedWorker#onEvent işlevini çağırır. onRender()'ü uygularken getRemoteData() çağrılabilir.

HTML içeriğindeki etkinlikleri izleme

EventUrlProvider sınıfı, geliştiricilerin HTML çıkışlarına dahil edebileceği etkinlik izleme URL'leri oluşturmak için API'ler sağlar. HTML oluşturulduğunda ODP, etkinlik URL'sinin yüküyle IsolatedWorker#onEvent'ü çağırır.

ODP hizmeti, oluşturulan HTML'de ODP tarafından oluşturulan etkinlik URL'lerine yönelik istekleri durdurur, IsolatedWorker#onEvent'ü çağırır ve döndürülen EventLogRecord'yi EVENTS tablosuna kaydeder.

Kalıcı sonuçlar yazma

OnDevicePersonalizationManager#execute ile hizmet, verileri kalıcı depolamaya (REQUESTS ve EVENTS tabloları) yazma seçeneğine sahiptir. Bu tablolara yazılabilecek girişler şunlardır:

  • REQUESTS tablosuna eklenecek bir RequestLogRecord.
  • EVENTS tablosuna eklenecek EventLogRecord nesnelerinin listesi. Her nesne, daha önce yazılmış bir RequestLogRecord nesnesinin işaretçisini içerir.

Cihaz üzerindeki depolama alanındaki kalıcı sonuçlar, model eğitimi için Birleşik Öğrenim tarafından kullanılabilir.

Cihaz üzerinde eğitim görevlerini yönetme

Bir birleşik bilgi işlem eğitim işi başladığında ve ODP'yi benimseyen geliştiriciler tarafından sağlanan eğitim örneklerini almak istediğinde ODP hizmeti IsolatedWorker#onTrainingExample çağrısını yapar. onTrainingExample()'i uygularken getRemoteData(), getLocalData(), getUserData() ve getLogReader()'i çağırabilirsiniz.

Birleştirilmiş hesaplama işlerini planlamak veya iptal etmek için tüm ODP IsolatedService için API'ler sağlayan FederatedComputeScheduler sınıfını kullanabilirsiniz. Her birleşik hesaplama işi, popülasyon adıyla tanımlanabilir.

Yeni bir birleşik bilgi işlem işi planlamadan önce:

  • Uzak birleşik bilgi işlem sunucusunda bu popülasyon adını taşıyan bir görev zaten oluşturulmuş olmalıdır.
  • Birleştirilmiş bilgi işlem sunucusu URL'si uç noktası, federated-compute-settings etiketiyle paket manifest ayarlarında zaten belirtilmiş olmalıdır.

Kalıcı çıkışla etkileşimler

Aşağıdaki bölümde, ODP'de kalıcı çıkışla nasıl etkileşim kurulacağı açıklanmaktadır.

Yerel tabloları okuma

LogReader sınıfı, REQUESTS ve EVENTS tablolarını okumak için API'ler sağlar. Bu tablolar, onExecute() veya onEvent() aramaları sırasında IsolatedService tarafından yazılan verileri içerir. Bu tablolardaki veriler, birleşik öğrenme destekli model eğitimi veya birleşik analiz destekli cihazlar arası istatistiksel analiz için kullanılabilir.

İndirilen içeriklerle etkileşimler

Aşağıdaki bölümde, ODP'de indirilen içerikle nasıl etkileşim kurulacağı açıklanmaktadır.

Sunuculardan içerik indirme

ODP hizmeti, IsolatedService'ün paket manifestinde belirtilen URL'den içeriği düzenli olarak indirir ve indirme işlemi tamamlandıktan sonra onDownloadCompleted işlevini çağırır. İndirilen dosya, anahtar/değer çiftleri içeren bir JSON dosyasıdır.

ODP'yi kullanan geliştiriciler, indirilen içeriğin hangi alt kümesinin RemoteData tablosuna ekleneceğini ve hangilerinin bırakılacağını seçebilir. Geliştiriciler indirilen içerikleri değiştiremez. Bu sayede RemoteData tablosu herhangi bir kullanıcı verisi içermez. Ayrıca geliştiriciler, LocalData tablosunu istedikleri gibi doldurabilirler. Örneğin, önceden hesaplanmış bazı sonuçları önbelleğe alabilirler.

İndirme isteği biçimi

ODP, RemoteData tablosunu dolduracak içeriği almak için geliştirici paket manifestinde belirtilen URL uç noktasını düzenli olarak sorar.

Uç noktasının, daha sonra açıklandığı gibi bir JSON yanıtı döndürmesi beklenir. JSON yanıtı, gönderilen verilerin sürümünü tanımlayan bir syncToken ve doldurulacak anahtar/değer çiftlerinin bir listesini içermelidir. syncToken değeri, UTC saat sınırına sabitlenmiş saniye cinsinden bir zaman damgası olmalıdır. ODP, indirme isteği kapsamında, daha önce tamamlanan indirmenin syncToken değerini ve cihazın ülkesini indirme URL'sinde syncToken ve country parametreleri olarak sağlar. Sunucu, artımlı indirmeleri uygulamak için önceki syncToken değerini kullanabilir.

İndirme dosyası biçimi

İndirilen dosya, aşağıdaki yapıya sahip bir JSON dosyasıdır. JSON dosyasının, indirilen verilerin sürümünü tanımlamak için bir syncToken içermesi gerekir. syncToken, bir saat sınırına sabitlenmiş bir UTC zaman damgası olmalı ve önceki indirme işleminin syncToken'unu aşmalıdır. syncToken her iki koşulu da karşılamıyorsa indirilen içerik işlenmeden atılır.

İçerik alanı, (anahtar, veri, kodlama) tuple'lerinin bir listesidir. key değerinin UTF-8 dizesi olması gerekir. encoding alanı, data alanının nasıl kodlandığını belirten isteğe bağlı bir parametredir. "utf8" veya "base64" olarak ayarlanabilir ve varsayılan olarak "utf8" olduğu varsayılır. onDownloadCompleted(). çağrılmadan önce key alanı bir String nesnesine, data alanı ise bir bayt dizisine dönüştürülür.

{
  // 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"
    },
    // ...
  ]
}

Sunucu tarafı API'ler

Bu bölümde, birleşik bilgi işlem sunucusu API'leriyle nasıl etkileşime geçeceğiniz açıklanmaktadır.

Birleşik Bilgi İşlem Sunucusu API'leri

İstemci tarafında birleşik hesaplama işi planlamak için uzak birleşik hesaplama sunucusunda oluşturulmuş bir popülasyon adı içeren bir göreve ihtiyacınız vardır. Bu bölümde, birleşik bilgi işlem sunucusunda bu tür bir görevin nasıl oluşturulacağı açıklanmaktadır.

Birleşik bilgi işlem istemci-sunucu topolojisinin şeması.

Görev Oluşturucu için yeni bir görev oluştururken ODP geliştiricileri iki dosya grubu sağlamalıdır:

  1. tff.learning.models.save_functional_model API çağrısı aracılığıyla kaydedilmiş bir tff.learning.models.FunctionalModel modeli. GitHub depomuzda bir örnek bulabilirsiniz.
  2. Politikaları, birleşik öğrenme ayarlarını ve diferansiyel gizlilik ayarlarını içeren bir fcp_server_config.json dosyası. Aşağıda, fcp_server_config.json örneği verilmiştir:
{
  # 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 depomuzda daha fazla örnek bulabilirsiniz.

Bu iki girişi hazırladıktan sonra, yapı oluşturmak ve yeni görevler oluşturmak için Görev Oluşturucu'yu çağırın. Daha ayrıntılı talimatlar GitHub depomuzda mevcuttur.