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 modellerine veya istatistiksel analize sahip uygulamalar için uygulamaların uygun Diferansiyel Gizlilik mekanizmaları kullanılarak düzgün şekilde anonimleştirilmesi 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; ağa, yerel disklere veya cihazda çalışan diğer hizmetlere doğrudan erişimi olmayan ancak aşağıdaki yerel olarak kalıcı veri kaynaklarına erişimi olan bir IsolatedProcess içinde geliştirici kodu ç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 Öğrenim destekli model eğitimi veya Birleşik Analytics 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 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ğırma uygulaması 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, çağrı uygulaması tarafından görülemez. İstemci uygulaması veya SDK, ODP ile geliştirme yapandan 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 süreci 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 içinde çalışan koduyla etkileşimde bulunmak 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 öğesinin her istek için IsolatedWorker öğesinin bir örneğini oluşturması gerekir.

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

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

Bir istemci uygulaması, execute yöntemini kullanarak IsolatedService adlı bir ODP'yi çağırır. ODP hizmeti, çağrıyı IsolatedWorker öğesinin onExecute yöntemine yönlendirir. IsolatedWorker, saklanması gereken kayıtları ve görüntülenecek içerikleri döndürür. ODP hizmeti, kalıcı çıkışı REQUESTS veya EVENTS tablosuna yazar ve istemci uygulamasına, görüntülenen çıkış için opak bir referans döndürür. İstemci uygulaması, kullanıcı arayüzündeki herhangi bir görüntülü içeriği 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ürdüğü uygulamadan sonra ODP hizmeti, REQUESTS tablosunda bir kayıt tutar. REQUESTS tablosundaki her kayıt, ODP hizmeti tarafından oluşturulan istek başına bazı yaygın verileri ve döndürülen Rows listesini içerir. Her Row, (key, value) çiftlik bir liste 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 de EVENTS tablosuna yazabilir. EVENTS tablosundaki her bir kayıt, REQUESTS tablosundaki bir satırla ilişkilendirilir. ODP hizmeti, her kayıtla birlikte, çağıran uygulamanın ve ODP geliştiricisinin APK'sının zaman damgası ile paket adı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 ürününde, ODP yapılandırma bilgilerini içeren paketteki bir XML kaynağına işaret eden <property> etiketi.
  2. AndroidManifest.xml öğesinde, IsolatedService öğesini genişleten sınıfı tanımlayan bir <service> etiketi (aşağıdaki örnekte gösterildiği gibi). <service> etiketindeki hizmetin exported ve isolatedProcess özellikleri true olarak ayarlanmalıdır.
  3. 1. adımda belirtilen XML kaynağında bulunan ve 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ı da <service> etiketinde hizmet sınıfını beyan etmeli ve aşağıdaki örnekte gösterildiği gibi, RemoteData tablosunu doldurmak için ODP'nin 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ştir

Android Studio dokümanlarının Geliştirici Seçeneklerini Etkinleştirme bölümünde yer alan talimatları uygulayarak geliştirici modunu etkinleştirin.

Geçiş ve İşaretleme 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 (birleşik öğrenim) işlevlerini kontrol eden anahtar; eğitimi kullanmak için yanlış değerine ayarlanır
  • _caller_app_allowliste: ODP'yi çağırmasına izin verilen kişileri 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: Yalıtılmış hizmet işleminde hangi hizmetlerin çalıştırılabileceğ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ıştığını 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şlemlerini tamamlamalarını ve oluşturulan HTML tarafından tetiklenen etkinlikleri işlemek için IsolatedWorker arayüzündeki yöntemleri uygulamaları 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 bazı kullanım alanları 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 tarafından döndürülen SurfacePackageToken içeren requestSurfacePackage çağrısı yaptığında, ODP hizmeti, sınırlı bir çerçeve içinde oluşturulacak HTML snippet'ini getirmek için IsolatedWorker#onRender çağrısını yapar. Bu aşamada geliştiricinin LocalData veya UserData erişimi yoktur. Bu, geliştiricinin oluşturulan HTML'deki öğe getirme URL'lerine hassas olabilecek UserData yerleştirmesini engeller. Geliştiriciler, oluşturulan HTML'ye eklemek üzere izleme URL'leri oluşturmak için IsolatedService#getEventUrlProvider aracını kullanabilir. HTML oluşturulduğunda ODP hizmeti, bu URL'lere yapılan isteklere müdahale eder ve IsolatedWorker#onEvent yöntemini ç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 ekleyebilecekleri 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 içinde ODP tarafından oluşturulan etkinlik URL'lerine yapılan isteklere müdahale eder, IsolatedWorker#onEvent yöntemini çağırır ve döndürülen EventLogRecord öğesini 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 RequestLogRecord eklenecek.
  • EVENTS tablosuna eklenecek EventLogRecord nesnelerinin listesi. Her nesne, daha önce yazılmış bir RequestLogRecord nesnesinin işaretçisini içerir.

Cihaz üzerinde 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 bir bilgi işlem eğitimi işi başladığında ve ODP'yi benimseyen geliştiricilerin sağladığı eğitim örneklerini almak istediğinde IsolatedWorker#onTrainingExample'i çağırır. onTrainingExample() uygularken getRemoteData(), getLocalData(), getUserData() ve getLogReader() çağrılarını çağırabilirsiniz.

Birleşik işlem işlerini planlamak veya iptal etmek isterseniz tüm ODP IsolatedService işlemleri için API 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 işlem sunucusunda bu popülasyon adına sahip bir görev önceden oluşturulmuş olmalıdır.
  • birleşik işlem sunucusu URL'si uç noktası, paket manifesti ayarlarında federated-compute-settings etiketiyle belirtilmiş olmalıdır.

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

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

Yerel tabloları okuma

LogReader sınıfı, REQUESTS ve EVENTS tablolarını okumak için API'ler sunar. 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şimde bulunulacağı 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 ç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 çıkarılması gerektiğini 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, bazı önceden hesaplanmış sonuçları önbelleğe alabilirler.

İndirme isteği biçimi

ODP, RemoteData tablosunu doldurmak amacıyla içerik getirmek için geliştirici paket manifesti'nde belirtilen URL uç noktasını düzenli olarak yoklar.

Uç noktanı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 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 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 beklenir. SyncToken, saat sınırına sabitlenmiş bir UTC zaman damgası olmalı ve önceki indirme işleminin SyncToken değerini aşmalıdır. SyncToken her iki şartı da karşılamıyorsa indirilen içerik işlenmeden silinir.

İçerik alanı, (anahtar, veri, kodlama) deliklerinin 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ı String nesnesine ve data alanı 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 işlem sunucusu API'leriyle nasıl etkileşimde bulunulacağı açıklanmaktadır.

Birleşik Compute Server 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ğını ele alacağız.

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

ODP geliştiricileri, Görev Oluşturucu için yeni bir görev oluştururken iki grup dosya 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 öğrenim kurulumunu ve diferansiyel gizlilik kurulumunu içeren bir fcp_server_config.json. Aşağıda bir 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 bulabilirsiniz.