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ün ve hizmetlerini son kullanıcılara göre özelleştirmek için 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şimler olmadığı sürece). ODP, makine öğrenimi modelleri veya istatistiksel analizler içeren uygulamaların uygun Diferansiyel Gizlilik mekanizmaları kullanılarak düzgün şekilde anonimleştirilmesini sağlamak için bir dizi hizmet ve algoritma sunar. Daha fazla bilgi için Cihaz Üzerinde Kişiselleştirme ile ilgili açıklayıcı metne bakın.

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

• RemoteData - Geçerliyse uzaktan, geliştirici tarafından işletilen arka uçlardan indirilen değişmez anahtar/değer verileri.
• LocalData: Geçerliyse geliştirici tarafından yerel olarak kalıcı hale getirilen, 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şlemede, gösterilen çıkışların oluşturulmasında, Federated Learning destekli model eğitiminde veya Federated Analytics destekli cihazlar arası istatistiksel analizde kullanılabilir.
  • Geliştiriciler, istekleri ve işleme sonuçlarını yerel REQUESTS tablosuna yazabilir.
  • Geliştiriciler, önceki bir istekle ilişkili ek verileri EVENTS tablosuna yazabilir.
• Görüntülenen çıkış:
  • Geliştiriciler, WebView içinde ODP tarafından oluşturulan HTML'yi SurfaceView içinde döndürebilir. Burada oluşturulan içerik, çağıran uygulama tarafından görünmez.
  • Geliştiriciler, oluşturulan HTML ile kullanıcı etkileşimlerinin kaydedilmesini ve işlenmesini tetiklemek için ODP tarafından sağlanan etkinlik URL'lerini HTML çıkışına yerleştirebilir. ODP, bu URL'lere yapılan istekleri yakalar ve EVENTS tablosuna yazılacak verileri oluşturmak için kodu çağırır.

İstemci uygulamaları ve SDK'lar, ODP API'lerini kullanarak SurfaceView içinde HTML içeriği görüntülemek için ODP'yi çağırabilir. SurfaceView içinde oluşturulan içerik, arayan uygulama tarafından görünmez. İstemci uygulaması veya SDK, ODP ile geliştirme yapan tüzel kişiden farklı bir tüzel kişi 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ştiricinin sağladığı uç noktalardan içerik indirir ve indirilen verilerin işlenmesi için mantığı çağırır. Ayrıca, IsolatedProcess ile diğer hizmetler ve uygulamalar arasındaki tüm iletişimi yönetir.

İstemci uygulamaları, OnDevicePersonalizationManager sınıfındaki yöntemleri kullanarak IsolatedProcess içinde çalışan geliştirici koduyla etkileşime geçer. IsolatedProcess içinde çalışan geliştirici kodu, IsolatedService sınıfını genişletir ve IsolatedWorker arayüzünü uygular. IsolatedService, her istek için IsolatedWorker örneği oluşturmalıdır.

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

Bir istemci uygulaması, adlandırılmış bir IsolatedService ile execute yöntemini kullanarak ODP'yi çağırır. ODP hizmeti, aramayı IsolatedWorker öğesinin onExecute yöntemine yönlendirir. IsolatedWorker, kalıcı hale getirilecek kayıtları ve gösterilecek içerikleri döndürür. ODP hizmeti, kalıcı çıkışı REQUESTS veya EVENTS tablosuna yazar ve görüntülenen çıkışa ilişkin opak bir referansı istemci uygulamasına döndürür. İstemci uygulaması, kullanıcı arayüzündeki görüntüleme içeriklerinden herhangi birini görüntülemek için gelecekteki bir requestSurfacePackage çağrısında bu opak referansı kullanabilir.

Kalıcı çıkış

ODP hizmeti, geliştiricinin onExecute uygulamasının dönüşünden sonra REQUESTS tablosunda bir kayıt saklar. 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'dur. Sayısal değerler toplama işleminden sonra, dize veya blob verileri ise yerel ya da merkezi diferansiyel gizlilik uygulandıktan sonra raporlanabilir. Geliştiriciler, sonraki kullanıcı etkileşimi etkinliklerini de EVENTS tablosuna yazabilir. EVENTS tablosundaki her kayıt, REQUESTS tablosundaki bir satırla ilişkilendirilir. ODP hizmeti, her kayıtta şeffaf bir şekilde zaman damgası, çağıran uygulamanın paket adı ve ODP geliştiricisinin APK'sını 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çinde, paketteki ODP yapılandırma bilgilerini içeren bir XML kaynağına işaret eden bir <property> etiketi.
2. Aşağıdaki örnekte gösterildiği gibi, IsolatedService sınıfını genişleten sınıfı tanımlayan AndroidManifest.xml içindeki bir <service> etiketi. <service> etiketindeki hizmette 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 ek ODP'ye özgü 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ının, <service> etiketinde hizmet sınıfını da bildirmesi ve aşağıdaki örnekte gösterildiği gibi ODP'nin RemoteData tablosunu doldurmak için içerik indireceği URL uç noktasını belirtmesi gerekir. Birleştirilmiş bilgi işlem özelliklerini kullanıyorsanız birleştirilmiş bilgi işlem istemcisinin bağlanacağı birleştirilmiş bilgi işlem 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çeneklerini Etkinleştirme bölümünde verilen talimatları uygulayarak geliştirici modunu etkinleştirin.

Geçiş ve işaretleme ayarları

ODP, belirli işlevleri kontrol etmek için kullanılan bir dizi anahtar ve işaret içerir:

• _global_killswitch: Tüm ODP özellikleri için genel anahtar; ODP'yi kullanmak için false olarak ayarlayın.
• _federated_compute_kill_switch: _ODP'nin tüm eğitim (birleştirilmiş öğrenme) işlevlerini kontrol eden anahtar; eğitimi kullanmak için false olarak ayarlanır.
• _caller_app_allowlist: ODP'yi kimlerin arayabileceğini kontrol eder. Buraya uygulamalar (paket adı, [isteğe bağlı] sertifika) eklenebilir veya tümüne izin vermek için * olarak ayarlanabilir.
• _isolated_service_allowlist: Hangi hizmetlerin yalıtılmış hizmet sürecinde çalışabileceğini kontrol eder.

Tüm anahtarları ve işaretleri kısıtlama olmadan ODP 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'leri

ODP için Android API referans belgelerine göz atın.

IsolatedService ile etkileşimler

IsolatedService sınıfı, ODP'ye karşı geliştirme yapmak isteyen tüm geliştiricilerin genişletmesi ve paket manifestlerinde yalıtılmış bir süreçte çalıştığını beyan etmesi gereken soyut bir temel sınıftır. ODP hizmeti, bu hizmeti izole edilmiş bir süreçte başlatır ve hizmete istekte bulunur. IsolatedService, ODP hizmetinden istek alır ve isteği işlemek için IsolatedWorker oluşturur.

Geliştiricilerin, istemci uygulaması isteklerini, indirme işlemlerinin tamamlanmasını ve oluşturulan HTML'nin tetiklediği etkinlikleri işlemek için IsolatedWorker arayüzündeki yöntemleri uygulaması gerekir. Bu yöntemlerin tümünde varsayılan olarak işlem yapmayan uygulamalar bulunur. Bu nedenle geliştiriciler, ilgilenmedikleri yöntemleri uygulamayı atlayabilir.

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

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

Arama uygulaması, OnDevicePersonalizationManager#execute ile gösterilecek içerik oluşturmak için döndürülen SurfacePackageToken nesnesini sonraki bir requestSurfacePackage çağrısında kullanarak sonucun SurfaceView içinde 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. İstemci uygulamalarının, SurfacePackage öğesini Görünüm hiyerarşisi içindeki bir SurfaceView öğesine eklemesi 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, çitli bir çerçevede oluşturulacak HTML snippet'ini getirmek için IsolatedWorker#onRender çağrısı yapar. Geliştiriciler bu aşamada LocalData veya UserData'ye 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 eklenecek 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() uygulanırken getRemoteData() çağrılabilir.

HTML içeriğindeki etkinlikleri izleme

EventUrlProvider sınıfı, geliştiricilerin HTML çıkışlarına ekleyebileceğ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 işlevini çağırır.

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

Kalıcı sonuçlar yazma

OnDevicePersonalizationManager#execute ile hizmet, verileri kalıcı depolama alanına (REQUESTS ve EVENTS tabloları) yazabilir. Bu tablolara yazılabilecek girişler şunlardır:

• RequestLogRecord, REQUESTS tablosuna eklenecek.
• EVENTS tablosuna eklenecek EventLogRecord nesnelerinin listesi. Bu nesnelerin her biri, daha önce yazılmış bir RequestLogRecord öğesine yönelik bir işaretçi içerir.

Cihaz 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

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

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

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

• Bu popülasyon adına sahip bir görev, uzak birleşik bilgi işlem sunucusunda zaten oluşturulmuş olmalıdır.
• Birleştirilmiş hesaplama sunucusu URL uç noktası, federated-compute-settings etiketiyle birlikte paket manifest ayarlarında 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 tablolarda, IsolatedService tarafından onExecute() veya onEvent() görüşmeleri sırasında yazılan veriler bulunur. Bu tablolardaki veriler, Birleşik Öğrenim destekli model eğitimi veya Birleşik Analitik destekli cihazlar arası istatistiksel analiz için kullanılabilir.

İndirilen içerikle etkileşimler

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

Sunuculardan içerik indirme

ODP hizmeti, IsolatedService paket manifestosunda belirtilen URL'den düzenli olarak içerik indirir ve indirme işlemi tamamlandıktan sonra onDownloadCompleted işlevini çağırır. İndirilen dosya, anahtar/değer çiftlerini 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 hangisinin bırakılacağını seçebilir. Geliştiriciler, indirilen içerikleri değiştiremez. Bu sayede RemoteData tablosunda kullanıcı verisi bulunmaz. Ayrıca, geliştiriciler LocalData tablosunu istedikleri gibi doldurabilir. Örneğin, önceden hesaplanmış bazı sonuçları önbelleğe alabilirler.

İndirme isteği biçimi

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

Uç noktanın, daha sonra açıklanacağı 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ğinin bir parçası olarak, daha önce tamamlanan indirme işleminin syncToken değerini ve cihazın bulunduğu ülkeyi, indirme URL'sindeki syncToken ve country parametreleri olarak sağlar. Sunucu, artımlı indirmeleri uygulamak için önceki syncToken değerini kullanabilir.

İndirilen dosya 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 beklenir. syncToken, saat sınırına sabitlenmiş bir UTC zaman damgası olmalı ve önceki indirme işleminin syncToken'ını 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) demetlerinin listesidir. key, UTF-8 dizesi olmalıdır. 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. key alanı String nesnesine, data alanı ise onDownloadCompleted(). çağrılmadan önce 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'leri

Bu bölümde, birleştirilmiş bilgi işlem sunucusu API'leriyle nasıl etkileşimde bulunacağınız açıklanmaktadır.

Federated Compute Server API'leri

İstemci tarafında birleştirilmiş bir bilgi işlem işi planlamak için uzak birleştirilmiş bilgi işlem sunucusunda oluşturulmuş bir popülasyon adına sahip bir görev gerekir. Bu bölümde, birleşik bilgi işlem sunucusunda bu tür bir görevin nasıl oluşturulacağı açıklanmaktadır.

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ı yapılarak kaydedilmiş bir tff.learning.models.FunctionalModel modeli. GitHub depomuzda bir örnek bulabilirsiniz.
2. Politikaları, federasyon öğrenimi kurulumunu ve farklı gizlilik kurulumunu 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ılar 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 bulabilirsiniz.