Özel veri kümeleri yazma

Yeni bir veri kümesi oluşturmak için bu kılavuzu izleyin (TFDS'de veya kendi veri havuzunuzda).

İstediğiniz veri kümesinin zaten mevcut olup olmadığını görmek için veri kümeleri listemize bakın.

TL;DR

Yeni bir veri kümesi yazmanın en kolay yolu TFDS CLI'yi kullanmaktır:

cd path/to/my/project/datasets/
tfds new my_dataset  # Create `my_dataset/my_dataset.py` template files
# [...] Manually modify `my_dataset/my_dataset_dataset_builder.py` to implement your dataset.
cd my_dataset/
tfds build  # Download and prepare the dataset to `~/tensorflow_datasets/`

Yeni veri kümesini tfds.load('my_dataset') ile kullanmak için:

  • tfds.load ~/tensorflow_datasets/my_dataset/ dosyasında oluşturulan veri kümesini (örneğin tfds build tarafından) otomatik olarak algılayacak ve yükleyecektir.
  • Alternatif olarak, veri kümenizi kaydetmek için import my.project.datasets.my_dataset : 
import my.project.datasets.my_dataset  # Register `my_dataset`

ds = tfds.load('my_dataset')  # `my_dataset` registered

Genel Bakış

Veri kümeleri her türlü formatta ve her türlü yere dağıtılır ve her zaman makine öğrenimi hattına beslenmeye hazır bir formatta saklanmazlar. TFDS'ye girin.

TFDS, bu veri kümelerini standart bir formatta (harici veriler -> serileştirilmiş dosyalar) işler ve bu daha sonra makine öğrenimi ardışık düzeni (serileştirilmiş dosyalar -> tf.data.Dataset ) olarak yüklenebilmektedir. Serileştirme yalnızca bir kez yapılır. Sonraki erişim, önceden işlenmiş dosyalardan doğrudan okunacaktır.

Ön işlemenin çoğu otomatik olarak yapılır. Her veri kümesi, aşağıdakileri belirten bir tfds.core.DatasetBuilder alt sınıfını uygular:

  • Verilerin nereden geldiği (yani URL'leri);
  • Veri kümesinin neye benzediği (yani özellikleri);
  • Verilerin nasıl bölünmesi gerektiği (örn. TRAIN ve TEST );
  • ve veri kümesindeki bireysel örnekler.

Veri kümenizi yazın

Varsayılan şablon: tfds new

Gerekli şablon python dosyalarını oluşturmak için TFDS CLI'yi kullanın.

cd path/to/project/datasets/  # Or use `--dir=path/to/project/datasets/` below
tfds new my_dataset

Bu komut aşağıdaki yapıya sahip yeni bir my_dataset/ klasörü oluşturacaktır:

my_dataset/
    __init__.py
    README.md # Markdown description of the dataset.
    CITATIONS.bib # Bibtex citation for the dataset.
    TAGS.txt # List of tags describing the dataset.
    my_dataset_dataset_builder.py # Dataset definition
    my_dataset_dataset_builder_test.py # Test
    dummy_data/ # (optional) Fake data (used for testing)
    checksum.tsv # (optional) URL checksums (see `checksums` section).

Burada TODO(my_dataset) ifadesini arayın ve buna göre değişiklik yapın.

Veri kümesi örneği

Tüm veri kümeleri, çoğu standartla ilgilenen tfds.core.DatasetBuilder öğesinin uygulanan alt sınıflarıdır. Şunları destekler:

Burada tfds.core.GeneratorBasedBuilder temel alan minimal bir veri kümesi oluşturucu örneği verilmiştir:

class Builder(tfds.core.GeneratorBasedBuilder):
  """DatasetBuilder for my_dataset dataset."""

  VERSION = tfds.core.Version('1.0.0')
  RELEASE_NOTES = {
      '1.0.0': 'Initial release.',
  }

  def _info(self) -> tfds.core.DatasetInfo:
    """Dataset metadata (homepage, citation,...)."""
    return self.dataset_info_from_configs(
        features=tfds.features.FeaturesDict({
            'image': tfds.features.Image(shape=(256, 256, 3)),
            'label': tfds.features.ClassLabel(
                names=['no', 'yes'],
                doc='Whether this is a picture of a cat'),
        }),
    )

  def _split_generators(self, dl_manager: tfds.download.DownloadManager):
    """Download the data and define splits."""
    extracted_path = dl_manager.download_and_extract('http://data.org/data.zip')
    # dl_manager returns pathlib-like objects with `path.read_text()`,
    # `path.iterdir()`,...
    return {
        'train': self._generate_examples(path=extracted_path / 'train_images'),
        'test': self._generate_examples(path=extracted_path / 'test_images'),
    }

  def _generate_examples(self, path) -> Iterator[Tuple[Key, Example]]:
    """Generator of examples for each split."""
    for img_path in path.glob('*.jpeg'):
      # Yields (key, example)
      yield img_path.name, {
          'image': img_path,
          'label': 'yes' if img_path.name.startswith('yes_') else 'no',
      }

Bazı belirli veri formatları için, çoğu veri işleme işlemini üstlenecek kullanıma hazır veri kümesi oluşturucuları sağladığımızı unutmayın.

Üzerine yazmanın 3 soyut yöntemini ayrıntılı olarak görelim.

_info : veri kümesi meta verileri

_info veri kümesi meta verilerini içeren tfds.core.DatasetInfo dosyasını döndürür.

def _info(self):
  # The `dataset_info_from_configs` base method will construct the
  # `tfds.core.DatasetInfo` object using the passed-in parameters and
  # adding: builder (self), description/citations/tags from the config
  # files located in the same package.
  return self.dataset_info_from_configs(
      homepage='https://dataset-homepage.org',
      features=tfds.features.FeaturesDict({
          'image_description': tfds.features.Text(),
          'image': tfds.features.Image(),
          # Here, 'label' can be 0-4.
          'label': tfds.features.ClassLabel(num_classes=5),
      }),
      # If there's a common `(input, target)` tuple from the features,
      # specify them here. They'll be used if as_supervised=True in
      # builder.as_dataset.
      supervised_keys=('image', 'label'),
      # Specify whether to disable shuffling on the examples. Set to False by default.
      disable_shuffling=False,
  )

Çoğu alan kendi kendini açıklayıcı olmalıdır. Bazı kesinlikler:

BibText CITATIONS.bib dosyasının yazılması:

  • Alıntı talimatları için veri kümesi web sitesinde arama yapın (bunu BibTex formatında kullanın).
  • arXiv kağıtları için: makaleyi bulun ve sağ taraftaki BibText bağlantısına tıklayın.
  • Makaleyi Google Akademik'te bulun ve başlığın altındaki çift tırnak işaretini tıklayın ve açılır pencerede BibTeX tıklayın.
  • İlişkili bir makale yoksa (örneğin, yalnızca bir web sitesi varsa), özel bir BibTeX girişi oluşturmak için BibTeX Çevrimiçi Düzenleyiciyi kullanabilirsiniz (açılır menüde Online giriş türü bulunur).

TAGS.txt dosyasını güncelleme:

  • İzin verilen tüm etiketler oluşturulan dosyaya önceden doldurulmuştur.
  • Veri kümesi için geçerli olmayan tüm etiketleri kaldırın.
  • Geçerli etiketler tensorflow_datasets/core/valid_tags.txt dosyasında listelenir.
  • Bu listeye etiket eklemek için lütfen PR gönderin.

Veri kümesi sırasını koruyun

Varsayılan olarak, aynı sınıfa ait kayıtlar bitişik olduğundan, sınıfların veri kümesindeki dağılımını daha tekdüze hale getirmek için veri kümelerinin kayıtları saklanırken karıştırılır. Veri kümesinin _generate_examples tarafından sağlanan anahtara göre sıralanması gerektiğini belirtmek için, disable_shuffling alanı True olarak ayarlanmalıdır. Varsayılan olarak False olarak ayarlanmıştır.

def _info(self):
  return self.dataset_info_from_configs(
    # [...]
    disable_shuffling=True,
    # [...]
  )

Parçalar artık paralel olarak okunamayacağından, karıştırmayı devre dışı bırakmanın performans üzerinde etkisi olduğunu unutmayın.

_split_generators : verileri indirir ve böler

Kaynak verileri indirme ve çıkarma

Çoğu veri kümesinin web'den veri indirmesi gerekir. Bu, _split_generators tfds.download.DownloadManager giriş argümanı kullanılarak yapılır. dl_manager aşağıdaki yöntemlere sahiptir:

  • download : http(s):// , ftp(s):// destekler
  • extract : şu anda .zip , .gz ve .tar dosyalarını desteklemektedir.
  • download_and_extract : dl_manager.extract(dl_manager.download(urls)) ile aynı

Tüm bu yöntemler, pathlib.Path benzeri nesneler olan tfds.core.Path ( epath.Path için takma adlar) döndürür.

Bu yöntemler, aşağıdaki gibi isteğe bağlı iç içe geçmiş yapıyı ( list , dict ) destekler: 

extracted_paths = dl_manager.download_and_extract({
    'foo': 'https://example.com/foo.zip',
    'bar': 'https://example.com/bar.zip',
})
# This returns:
assert extracted_paths == {
    'foo': Path('/path/to/extracted_foo/'),
    'bar': Path('/path/extracted_bar/'),
}

Manuel indirme ve çıkarma

Bazı veriler otomatik olarak indirilemez (örn. oturum açma gerektirir), bu durumda kullanıcı kaynak verileri manuel olarak indirecek ve manual_dir/ dizinine yerleştirecektir (varsayılan olarak ~/tensorflow_datasets/downloads/manual/ ).

Dosyalara daha sonra dl_manager.manual_dir aracılığıyla erişilebilir:

class MyDataset(tfds.core.GeneratorBasedBuilder):

  MANUAL_DOWNLOAD_INSTRUCTIONS = """
  Register into https://example.org/login to get the data. Place the `data.zip`
  file in the `manual_dir/`.
  """

  def _split_generators(self, dl_manager):
    # data_path is a pathlib-like `Path('<manual_dir>/data.zip')`
    archive_path = dl_manager.manual_dir / 'data.zip'
    # Extract the manually downloaded `data.zip`
    extracted_path = dl_manager.extract(archive_path)
    ...

manual_dir konumu tfds build --manual_dir= ile veya tfds.download.DownloadConfig kullanılarak özelleştirilebilir.

Arşivi doğrudan oku

dl_manager.iter_archive arşivleri çıkarmadan sırayla okur. Bu, depolama alanından tasarruf sağlayabilir ve bazı dosya sistemlerinde performansı artırabilir.

for filename, fobj in dl_manager.iter_archive('path/to/archive.zip'):
  ...

fobj with open('rb') as fobj: (örn. fobj.read() )

Veri kümesi bölmelerini belirtme

Veri kümesi önceden tanımlanmış bölmelerle birlikte geliyorsa (örneğin, MNIST train ve test bölmeleri vardır), bunları saklayın. Aksi takdirde, yalnızca tek bir all bölme belirtin. Kullanıcılar alt bölme API'si ile dinamik olarak kendi alt bölmelerini oluşturabilirler (örn split='train[80%:]' ). Yukarıda belirtilen all dışında herhangi bir alfabetik dizenin bölünmüş ad olarak kullanılabileceğini unutmayın. 

def _split_generators(self, dl_manager):
  # Download source data
  extracted_path = dl_manager.download_and_extract(...)

  # Specify the splits
  return {
      'train': self._generate_examples(
          images_path=extracted_path / 'train_imgs',
          label_path=extracted_path / 'train_labels.csv',
      ),
      'test': self._generate_examples(
          images_path=extracted_path / 'test_imgs',
          label_path=extracted_path / 'test_labels.csv',
      ),
  }

_generate_examples : Örnek oluşturucu

_generate_examples kaynak verilerden her bir bölünme için örnekler oluşturur.

Bu yöntem genellikle kaynak veri kümesi yapıtlarını (örneğin bir CSV dosyası) ve verim (key, feature_dict) tanımlamalarını okuyacaktır:

  • key : Örnek tanımlayıcı. Örnekleri hash(key) kullanarak deterministik olarak karıştırmak veya karıştırma devre dışı bırakıldığında anahtara göre sıralamak için kullanılır (bkz. bölüm Veri kümesi sırasını koruma ). Olmalı:
    • benzersiz : İki örnek aynı anahtarı kullanıyorsa bir istisna ortaya çıkar.
    • deterministik : download_dir , os.path.listdir sırasına bağlı olmamalıdır... Verilerin iki kez oluşturulması aynı anahtarı vermelidir.
    • karşılaştırılabilir : Karıştırma devre dışı bırakılırsa, veri kümesini sıralamak için anahtar kullanılacaktır.
  • feature_dict : Örnek değerleri içeren bir dict .
    • Yapı, tfds.core.DatasetInfo tanımlanan features= yapıyla eşleşmelidir.
    • Karmaşık veri türleri (resim, video, ses,...) otomatik olarak kodlanacaktır.
    • Her özellik genellikle birden fazla giriş türünü kabul eder (örn. video kabul /path/to/vid.mp4 , np.array(shape=(l, h, w, c)) , List[paths] , List[np.array(shape=(h, w, c)] , List[img_bytes] ,...)
    • Daha fazla bilgi için özellik konektörü kılavuzuna bakın.
def _generate_examples(self, images_path, label_path):
  # Read the input data out of the source files
  with label_path.open() as f:
    for row in csv.DictReader(f):
      image_id = row['image_id']
      # And yield (key, feature_dict)
      yield image_id, {
          'image_description': row['description'],
          'image': images_path / f'{image_id}.jpeg',
          'label': row['label'],
      }

Dosya erişimi ve tf.io.gfile

Bulut depolama sistemlerini desteklemek için Python'un yerleşik G/Ç işlemlerini kullanmaktan kaçının.

Bunun yerine dl_manager , Google Cloud depolama alanıyla doğrudan uyumlu olan pathlib benzeri nesneleri döndürür:

path = dl_manager.download_and_extract('http://some-website/my_data.zip')

json_path = path / 'data/file.json'

json.loads(json_path.read_text())

Alternatif olarak, dosya işlemleri için yerleşik yerine tf.io.gfile API'sini kullanın:

Pathlib, tf.io.gfile yerine tercih edilmelidir ( bkz .

Ekstra bağımlılıklar

Bazı veri kümeleri yalnızca oluşturma sırasında ek Python bağımlılıkları gerektirir. Örneğin, SVHN veri kümesi bazı verileri yüklemek için scipy kullanır.

TFDS deposuna veri kümesi ekliyorsanız tensorflow-datasets paketini küçük tutmak için lütfen tfds.core.lazy_imports kullanın. Kullanıcılar yalnızca gerektiğinde ek bağımlılıklar yükleyecektir.

lazy_imports kullanmak için:

  • setup.py dosyasındaki DATASET_EXTRAS içine veri kümeniz için bir giriş ekleyin. Bu, kullanıcıların ekstra bağımlılıkları yüklemek için örneğin pip install 'tensorflow-datasets[svhn]' işlemini yapabilmesini sağlar.
  • İçe aktarma işleminiz için LazyImporter ve LazyImportsTest bir giriş ekleyin.
  • DatasetBuilder bağımlılığa (örneğin, tfds.core.lazy_imports.scipy ) erişmek için tfds.core.lazy_imports kullanın.

Bozuk veriler

Bazı veri kümeleri tamamen temiz değildir ve bazı bozuk veriler içerir (örneğin, görüntüler JPEG dosyalarındadır ancak bazıları geçersiz JPEG'dir). Bu örnekler atlanmalıdır ancak veri kümesi açıklamasında kaç örneğin atlandığını ve nedenini not edin.

Veri kümesi yapılandırması/varyantları (tfds.core.BuilderConfig)

Bazı veri kümelerinin, verilerin nasıl önceden işleneceğine ve diske nasıl yazılacağına ilişkin birden fazla çeşidi veya seçeneği olabilir. Örneğin, cycle_gan'ın nesne çifti başına bir yapılandırması vardır ( cycle_gan/horse2zebra , cycle_gan/monet2photo ,...).

Bu, tfds.core.BuilderConfig s aracılığıyla yapılır:

  1. Yapılandırma nesnenizi tfds.core.BuilderConfig öğesinin bir alt sınıfı olarak tanımlayın. Örneğin, MyDatasetConfig .

    @dataclasses.dataclass
class MyDatasetConfig(tfds.core.BuilderConfig):
  img_size: Tuple[int, int] = (0, 0)

  2. MyDataset , veri kümesinin sunduğu MyDatasetConfig listeleyen BUILDER_CONFIGS = [] sınıf üyesini tanımlayın.

    class MyDataset(tfds.core.GeneratorBasedBuilder):
  VERSION = tfds.core.Version('1.0.0')
  # pytype: disable=wrong-keyword-args
  BUILDER_CONFIGS = [
      # `name` (and optionally `description`) are required for each config
      MyDatasetConfig(name='small', description='Small ...', img_size=(8, 8)),
      MyDatasetConfig(name='big', description='Big ...', img_size=(32, 32)),
  ]
  # pytype: enable=wrong-keyword-args

  3. Veri oluşturmayı yapılandırmak için MyDataset self.builder_config kullanın (örneğin, shape=self.builder_config.img_size ). Bu _info() da farklı değerlerin ayarlanmasını veya indirme veri erişiminin değiştirilmesini içerebilir.

Notlar:

  • Her yapılandırmanın benzersiz bir adı vardır. Bir yapılandırmanın tam adı dataset_name/config_name (örn. coco/2017 ).
  • Belirtilmemişse, BUILDER_CONFIGS içindeki ilk yapılandırma kullanılacaktır (örn. tfds.load('c4') varsayılanı c4/en )

BuilderConfig s'yi kullanan bir veri kümesi örneği için anli bakın.

Sürüm

Sürüm iki farklı anlama gelebilir:

  • "Harici" orijinal veri sürümü: örneğin COCO v2019, v2017,...
  • "Dahili" TFDS kod sürümü: örneğin tfds.features.FeaturesDict içindeki bir özelliği yeniden adlandırın, _generate_examples içindeki bir hatayı düzeltin

Bir veri kümesini güncellemek için:

  • "Harici" veri güncellemesi için: Birden fazla kullanıcı aynı anda belirli bir yıla/versiyona erişmek isteyebilir. Bu, sürüm başına bir tfds.core.BuilderConfig (örneğin coco/2017 , coco/2019 ) veya sürüm başına bir sınıf (örneğin Voc2007 , Voc2012 ) kullanılarak yapılır.
  • "Dahili" kod güncellemesi için: Kullanıcılar yalnızca en yeni sürümü indirir. Herhangi bir kod güncellemesinin , anlamsal sürüm belirlemeyi takiben VERSION sınıfı özniteliğini (örneğin 1.0.0 VERSION = tfds.core.Version('2.0.0') ) artırması gerekir.

Kayıt için içe aktarma ekleme

tfds.load , tfds.builder otomatik olarak kaydedilmesi için veri kümesi modülünü __init__ projenize aktarmayı unutmayın.

import my_project.datasets.my_dataset  # Register MyDataset

ds = tfds.load('my_dataset')  # MyDataset available

Örneğin, tensorflow/datasets katkıda bulunuyorsanız, modül içe aktarımını alt dizininin __init__.py dizinine ekleyin (örn. image/__init__.py .

Yaygın uygulama kazanımlarını kontrol edin

Lütfen ortak uygulama kazanımlarını kontrol edin.

Veri kümenizi test edin

İndirin ve hazırlayın: tfds build

Veri kümesini oluşturmak için my_dataset/ dizininden tfds build çalıştırın:

cd path/to/datasets/my_dataset/
tfds build --register_checksums

Geliştirme için bazı yararlı bayraklar:

  • --pdb : Bir istisna ortaya çıkarsa hata ayıklama moduna girin.
  • --overwrite : Veri kümesi zaten oluşturulmuşsa mevcut dosyaları silin.
  • --max_examples_per_split : Tam veri kümesi yerine yalnızca ilk X örneklerini (varsayılan olarak 1'dir) oluşturun.
  • --register_checksums : İndirilen URL'lerin sağlama toplamlarını kaydedin. Yalnızca geliştirme aşamasında kullanılmalıdır.

İşaretlerin tam listesi için CLI belgelerine bakın.

Sağlama toplamları

Belirleyiciliği garanti etmek, dokümantasyona yardımcı olmak için veri kümelerinizin sağlama toplamlarını kaydetmeniz önerilir. Bu, --register_checksums ile veri kümesi oluşturularak yapılır (önceki bölüme bakın).

Veri kümelerinizi PyPI aracılığıyla yayınlıyorsanız checksums.tsv dosyalarını (örneğin setup.py dosyanızın package_data dosyasında) dışa aktarmayı unutmayın.

Veri kümenizde birim testi yapın

tfds.testing.DatasetBuilderTestCase , bir veri kümesini tam olarak kullanmaya yönelik temel bir TestCase . Kaynak veri kümesinin yapısını taklit eden test verileri olarak "kukla verileri" kullanır.

  • Test verileri my_dataset/dummy_data/ dizinine yerleştirilmeli ve indirilen ve çıkarılan kaynak veri kümesi yapıtlarını taklit etmelidir. Bir komut dosyasıyla ( örnek komut dosyası ) manuel veya otomatik olarak oluşturulabilir.
  • Veri kümesi bölmeleriniz çakışırsa test başarısız olacağından, test veri bölmelerinizde farklı veriler kullandığınızdan emin olun.
  • Test verileri telif hakkıyla korunan herhangi bir materyal içermemelidir . Şüpheniz varsa, verileri orijinal veri kümesindeki materyalleri kullanarak oluşturmayın.
import tensorflow_datasets as tfds
from . import my_dataset_dataset_builder


class MyDatasetTest(tfds.testing.DatasetBuilderTestCase):
  """Tests for my_dataset dataset."""
  DATASET_CLASS = my_dataset_dataset_builder.Builder
  SPLITS = {
      'train': 3,  # Number of fake train example
      'test': 1,  # Number of fake test example
  }

  # If you are calling `download/download_and_extract` with a dict, like:
  #   dl_manager.download({'some_key': 'http://a.org/out.txt', ...})
  # then the tests needs to provide the fake output paths relative to the
  # fake data directory
  DL_EXTRACT_RESULT = {
      'name1': 'path/to/file1',  # Relative to my_dataset/dummy_data dir.
      'name2': 'file2',
  }


if __name__ == '__main__':
  tfds.testing.test_main()

Veri kümesini test etmek için aşağıdaki komutu çalıştırın. 

python my_dataset_test.py

Bize geri bildirim gönderin

Veri kümesi oluşturma iş akışını sürekli olarak iyileştirmeye çalışıyoruz ancak bunu yalnızca sorunların farkında olduğumuzda yapabiliriz. Veri kümesini oluştururken hangi sorunlarla veya hatalarla karşılaştınız? Kafa karıştırıcı olan veya ilk seferde çalışmayan bir kısım var mıydı?

Lütfen geri bildiriminizi GitHub'da paylaşın.