Transformers documentation
Kontribusi model legacy
Kontribusi model legacy
Coba tambahkan model baru dengan pendekatan yang lebih modular terlebih dahulu. Hal ini membuat kontribusi model ke Transformers jauh lebih mudah!
Banyak model di Transformers disumbangkan oleh pengembang dan peneliti. Sebagai proyek open-source, kami berkomitmen untuk memberdayakan komunitas agar dapat secara aktif dan mandiri menambahkan lebih banyak model.
Saat Anda menambahkan model ke Transformers, Anda akan mempelajari:
- lebih lanjut tentang praktik terbaik open-source
- tentang arsitektur model
- tentang prinsip desain Transformers
- cara menguji model besar secara efisien
- cara menggunakan utilitas Python seperti Black dan Ruff untuk membuat kode yang bersih dan mudah dibaca
Ini adalah proses yang menantang namun memuaskan.
Panduan ini akan memandu Anda menambahkan contoh model PyTorch BrandNewLlama ke Transformers. Sebelum memulai, sebaiknya Anda terlebih dahulu membiasakan diri dengan pustaka ini.
Ikhtisar Transformers
Transformers adalah pustaka yang memiliki pandangan kuat dengan filosofi dan pilihan desainnya yang unik. Pilihan-pilihan ini membantu kami untuk secara berkelanjutan memperluas dan memelihara Transformers.
Pelajari lebih lanjut tentang prinsip desain kami di dokumen Filosofi.
Beberapa pilihan desain tersebut adalah:
- komposisi > abstraksi berlebihan
- kode duplikat tidak selalu buruk jika sangat meningkatkan keterbacaan dan aksesibilitas
- file model bersifat mandiri dan semua kode model yang diperlukan terdapat dalam file
modeling_mymodel.py
Pilihan desain ini penting bagi semua orang yang berinteraksi dengan model. Model menjadi lebih mudah dibaca, dipahami, dan dimodifikasi.
Bagian ini menjelaskan bagaimana kelas model dan konfigurasi berinteraksi serta gaya kode Transformers.
Model dan konfigurasi
Semua model Transformers mewarisi dari kelas dasar PreTrainedModel dan PreTrainedConfig. Konfigurasi adalah cetak biru model.
Tidak pernah ada lebih dari dua tingkat abstraksi untuk model apa pun agar kode tetap mudah dibaca. Model contoh di sini, BrandNewLlama, mewarisi dari BrandNewLlamaPreTrainedModel dan PreTrainedModel. Penting bahwa model baru hanya bergantung pada PreTrainedModel agar dapat menggunakan metode from_pretrained() dan save_pretrained().
Fungsi penting lainnya seperti metode forward didefinisikan dalam file modeling.py.
Kepala model spesifik (misalnya, klasifikasi urutan atau pemodelan bahasa) sebaiknya memanggil model dasar pada jalur maju (forward pass) alih-alih mewarisinya, agar abstraksi tetap rendah.
Model baru memerlukan konfigurasi, misalnya BrandNewLlamaConfig, yang disimpan sebagai atribut dari PreTrainedModel.
model = BrandNewLlamaModel.from_pretrained("username/brand_new_llama")
model.configPreTrainedConfig menyediakan metode from_pretrained() dan save_pretrained().
Saat Anda menggunakan PreTrainedModel.save_pretrained(), fungsi ini secara otomatis memanggil PreTrainedConfig.save_pretrained() sehingga model dan konfigurasi disimpan bersama.
Model disimpan ke file model.safetensors dan konfigurasi disimpan ke file config.json.
Gaya kode
Transformers lebih mengutamakan kode yang bersih dan mudah dibaca daripada gaya kode yang lebih abstrak. Beberapa pilihan gaya kode meliputi:
Kode harus dapat diakses oleh pengguna non-bahasa Inggris. Pilih nama variabel yang deskriptif dan hindari singkatan. Misalnya, “activation” lebih disarankan daripada “act”. Nama variabel satu huruf sangat tidak disarankan kecuali itu adalah indeks dalam perulangan for.
Kode eksplisit lebih disukai - meskipun lebih panjang - daripada kode yang lebih pendek.
Hindari membuat subclass dari nn.Sequential. Buat subclass dari nn.Module sebagai gantinya agar kode dapat dengan cepat di-debug menggunakan pernyataan print atau breakpoint.
Signature fungsi harus diberi anotasi tipe. Jika tidak, gunakan nama variabel yang baik agar lebih mudah dipahami.
Masalah penambahan model baru
Buka issue Penambahan model baru untuk menambahkan model tertentu.
Gunakan label New model di GitHub untuk memfilter, melihat, dan menambahkan permintaan model yang sudah ada.
Sekarang adalah waktu yang tepat untuk mulai mengenal BrandNewLlama. Membaca makalah penelitian model sangat membantu untuk memahami desain teknis dan implementasinya. Anda tidak perlu terlalu khawatir tentang detail teoretis. Sebaliknya, fokuslah pada detail praktisnya. Gunakan pertanyaan di bawah ini sebagai panduan dalam membaca.
- Jenis model apa BrandNewLlama? Apakah itu model encoder, decoder, atau encoder-decoder?
- Tugas apa saja yang dapat dilakukan oleh BrandNewLlama?
- Apa yang membedakan BrandNewLlama dari model-model lain?
- Model apa di Transformers yang paling mirip dengan BrandNewLlama?
- Tokenizer apa yang digunakan oleh BrandNewLlama?
Selain mempelajari lebih lanjut tentang model Anda, gunakan tips di bawah ini untuk membantu Anda menambahkan model lebih cepat.
Setiap kontributor memiliki gaya dan alur kerja unik untuk menambahkan model ke Transformers. Sebagai contoh, lihat bagaimana Gemma ditambahkan.
- Jangan mengulang pekerjaan yang sudah ada! Luangkan waktu untuk menjelajahi model dan tokenizer yang sudah ada untuk melihat apa yang bisa Anda salin dan gunakan kembali. Grep dan ripgrep adalah alat yang sangat baik untuk hal ini.
- Ini lebih merupakan tantangan rekayasa daripada tantangan sains. Fokuskan pada aspek yang lebih praktis (misalnya, menyiapkan lingkungan debugging yang efisien) daripada aspek teoretis dari model.
- Jangan ragu untuk meminta bantuan! Kami di sini untuk mendukung Anda. 🤗
Lingkungan pengembangan
Klik tombol Fork pada repositori Transformers untuk membuat salinan Anda sendiri yang akan dikerjakan. Klon repositori ke disk lokal Anda dan tambahkan repositori dasar sebagai remote.
git clone https://github.com/[your Github handle]/transformers.git
cd transformers
git remote add upstream https://github.com/huggingface/transformers.gitBuat lingkungan virtual dan lakukan instal yang dapat diedit dari pustaka dengan dependensi “dev” atau pengembangan.
python -m venv .env
source .env/bin/activate
pip install -e ".[dev]"Karena jumlah dependensi opsional Transformers yang terus bertambah, perintah ini mungkin gagal. Dalam hal ini, pasang dependensi “quality”. Pastikan juga Anda telah memasang framework deep learning.
pip install -e ".[quality]"Kembali ke direktori induk dan klon serta instal repositori BrandNewLlama asli.
git clone https://github.com/org_that_created_brand_new_llama_org/brand_new_llama.git
cd brand_new_bert
pip install -e .Kembali ke klon Transformers Anda untuk mulai memindahkan BrandNewLlama.
cd transformersTerdapat dua lingkungan debugging yang mungkin untuk menjalankan model asli, yaitu notebook (Google Colab atau Jupyter) atau skrip Python lokal.
Kami tidak merekomendasikan untuk menyiapkan lingkungan GPU untuk menjalankan model asli karena biayanya dapat mahal. Sebagai gantinya, kerjakan terlebih dahulu di lingkungan CPU untuk memverifikasi bahwa model berfungsi di Transformers. Setelah berhasil, Anda dapat memverifikasinya di GPU.
Notebook sangat berguna untuk mengeksekusi kode per sel, yang dapat membantu memisahkan komponen logis satu sama lain. Hal ini juga dapat mempercepat siklus debugging karena hasil antara dapat disimpan. Anda juga dapat membagikan notebook saat bekerja dengan kontributor lain.
Kekurangannya adalah jika Anda belum terbiasa, mungkin akan butuh waktu untuk membiasakan diri.
Jika arsitektur model identik dengan model yang sudah ada, lewati ke bagian konversi checkpoint, karena Anda dapat menggunakan kembali arsitektur dari model yang sudah ada tersebut.
Jalankan perintah di bawah untuk memulai dan menyelesaikan kuesioner dengan beberapa informasi dasar tentang model baru. Perintah ini mempercepat proses dengan secara otomatis menghasilkan beberapa kode model yang perlu Anda sesuaikan.
transformers add-new-model-like
Buat pull request
Sebelum Anda mulai mengadaptasi kode, buat pull request untuk melacak kemajuan Anda dan mendapatkan umpan balik dari tim Transformers. Beri judul pull request Anda [WIP] Add BrandNewLlama agar jelas bahwa ini masih dalam proses pengerjaan.
Buat cabang dengan nama yang deskriptif dari cabang utama Anda.
git checkout -b add_brand_new_bert
Commit kode, lalu fetch dan rebase pada branch utama.
git add . git commit git fetch upstream git rebase upstream/main
Push perubahan apa pun ke branch Anda dan klik Compare & pull request untuk membuka pull request di GitHub. Buka pull request sebagai draft untuk menandakan bahwa ini masih dalam proses pengerjaan.
git push -u origin a-descriptive-name-for-my-changes
Sertakan anggota tim Hugging Face yang relevan dengan menambahkan handle GitHub mereka di pull request untuk pertanyaan, umpan balik, komentar, dan ulasan. Arahkan anggota tim ke bagian kode tertentu yang Anda inginkan dengan mengklik tab Files changed, lalu mengklik + di sebelah kiri nomor baris untuk menambahkan komentar. Ketika pertanyaan atau masalah terselesaikan, klik Resolve untuk menandakan bahwa masalah tersebut telah diselesaikan. Hal ini menjaga percakapan tetap terorganisir dan rapi.
Ingatlah untuk secara berkala melakukan commit dan push pekerjaan Anda, serta memperbarui pekerjaan Anda dengan cabang main saat ini.
git fetch upstream git merge upstream/main
Checkpoint asli
Luangkan waktu untuk mengerjakan implementasi model asli terlebih dahulu untuk memahami cara kerjanya.
Hal ini bisa menjadi sulit jika repositori model asli kurang dokumentasi atau jika basis kode tersebut kompleks. Namun, Anda sebaiknya menjadikan hal ini sebagai motivasi untuk mengimplementasikan model di Transformers. Kontribusi Anda membuatnya lebih mudah diakses dan ramah pengguna bagi semua orang!
Orientasikan diri Anda dengan repositori asli dengan melakukan hal-hal berikut.
- Lokasikan bobot terlatih sebelumnya.
- Tentukan cara memuat bobot terlatih ke dalam model.
- Tentukan cara menjalankan tokenizer secara independen dari model.
- Lacak satu langkah maju (forward pass) untuk memahami kelas dan fungsi apa saja yang diperlukan. Kemungkinan besar, ini adalah satu-satunya kelas dan fungsi yang harus Anda implementasikan.
- Lokasikan semua komponen penting (kelas model, subkelas model, lapisan self-attention, dll.) dari model.
- Tentukan cara untuk men-debug model di repositori aslinya. Tambahkan pernyataan print, gunakan debugger interaktif seperti ipdb, atau lingkungan pengembangan terintegrasi (IDE) yang efisien seperti PyCharm.
Poin terakhir ini sangat penting karena Anda perlu memahami secara menyeluruh apa yang terjadi di dalam model asli sebelum Anda dapat mengimplementasikannya ulang di Transformers. Jangan ragu untuk membuka isu dan pull request di repositori asli jika Anda menemui masalah.
Langkah awal yang baik adalah memuat checkpoint kecil yang telah dilatih sebelumnya dan mencoba mereproduksi satu langkah forward pass dengan vektor integer contoh dari input. Misalnya, dalam pseudocode, ini bisa terlihat seperti berikut.
model = BrandNewLlamaModel.load_pretrained_checkpoint("/path/to/checkpoint/")
input_ids = [0, 4, 5, 2, 3, 7, 9] # vector of input ids
original_output = model.generate(input_ids)Debugging
Jika Anda menemui masalah, Anda perlu memilih salah satu strategi debugging berikut berdasarkan codebase model asli.
Strategi ini bergantung pada pemecahan model asli menjadi sub-komponen yang lebih kecil, seperti ketika kode dapat dengan mudah dijalankan dalam mode eager. Meskipun lebih sulit, pendekatan ini memiliki beberapa keuntungan.
- Lebih mudah untuk membandingkan model asli dengan implementasi Anda di kemudian hari. Anda dapat memverifikasi secara otomatis bahwa setiap komponen individual cocok dengan komponen yang bersesuaian dalam implementasi Transformers. Hal ini lebih baik daripada mengandalkan perbandingan visual berdasarkan pernyataan print.
- Lebih mudah untuk memindahkan komponen individual daripada seluruh model.
- Lebih mudah memahami cara kerja model dengan memecahnya menjadi bagian-bagian yang lebih kecil.
- Mencegah regresi pada tahap selanjutnya menjadi lebih mudah saat Anda mengubah kode berkat pengujian per komponen.
Lihat periksa integrasi ELECTRA sebagai contoh yang baik tentang cara memecah model menjadi komponen yang lebih kecil.
Strategi ini layak digunakan ketika basis kode asli terlalu kompleks, hanya memungkinkan komponen perantara untuk dijalankan dalam mode terkompilasi, atau memisahkan model menjadi sub-komponen yang lebih kecil terlalu memakan waktu (bahkan mungkin tidak mungkin).
Sebagai contoh, implementasi T5 di MeshTensorFlow terlalu kompleks dan tidak menyediakan cara sederhana untuk mengurai model menjadi sub-komponennya. Dalam situasi ini, Anda harus mengandalkan verifikasi pernyataan print.
Strategi apa pun yang Anda pilih, disarankan untuk men-debug lapisan awal terlebih dahulu dan lapisan akhir terakhir. Ambil output, baik dengan pernyataan print atau fungsi sub-komponen, dari lapisan-lapisan berikut dalam urutan ini.
- input ids yang diteruskan ke model
- embedding kata
- input dari lapisan Transformer pertama
- output dari lapisan Transformer pertama
- output dari n-1 lapisan Transformer berikut
- output dari seluruh model
Input ids seharusnya hanya berupa array bilangan bulat seperti input_ids = [0, 4, 4, 3, 2, 4, 1, 7, 19].
Output lapisan sering kali terdiri dari array float multi-dimensi.
[[
[-0.1465, -0.6501, 0.1993, ..., 0.1451, 0.3430, 0.6024],
[-0.4417, -0.5920, 0.3450, ..., -0.3062, 0.6182, 0.7132],
[-0.5009, -0.7122, 0.4548, ..., -0.3662, 0.6091, 0.7648],
...,
[-0.5613, -0.6332, 0.4324, ..., -0.3792, 0.7372, 0.9288],
[-0.5416, -0.6345, 0.4180, ..., -0.3564, 0.6992, 0.9191],
[-0.5334, -0.6403, 0.4271, ..., -0.3339, 0.6533, 0.8694]]],Setiap output model Transformers harus memiliki presisi atau toleransi kesalahan sebesar 1e-3. Hal ini memperhitungkan perbedaan output apa pun yang muncul akibat penggunaan kerangka pustaka yang berbeda. Bandingkan output antara model asli dengan implementasi Transformers untuk memastikan keduanya hampir identik. Memiliki lingkungan debugging yang efisien sangat penting untuk langkah ini.
Berikut adalah beberapa tips untuk lingkungan debugging yang efisien.
Untuk men-debug hasil perantara, hal ini bergantung pada framework machine learning yang digunakan oleh repositori model asli. Untuk PyTorch, Anda sebaiknya menulis skrip untuk mengurai model asli menjadi sub-komponen yang lebih kecil guna mengambil nilai-nilai perantara.
Debugging lebih cepat dilakukan dengan checkpoint pretrained yang lebih kecil dibandingkan checkpoint yang lebih besar, di mana forward pass memakan waktu lebih dari 10 detik. Jika hanya tersedia checkpoint besar, buat model dummy dengan bobot yang diinisialisasi secara acak dan simpan bobot tersebut untuk dibandingkan dengan implementasi Transformers.
Cari cara termudah untuk memanggil forward pass model. Idealnya, fungsi ini (yang mungkin bernama
predict,evaluate,forward, atau__call__) hanya memanggil forward pass satu kali. Fungsi yang memanggil forward pass beberapa kali lebih sulit untuk di-debug.Pisahkan tokenisasi dari langkah maju (forward pass). Temukan di mana input string diubah menjadi input ids dalam langkah maju dan mulai dari sana. Anda mungkin perlu membuat skrip kecil atau memodifikasi kode asli untuk langsung memasukkan input ids alih-alih string input.
Pastikan model tidak berada dalam mode pelatihan. Hal ini dapat menghasilkan output acak karena adanya beberapa lapisan dropout dalam model. Forward pass di lingkungan debugging Anda harus deterministik agar lapisan dropout tidak digunakan.
Setelah Anda mampu menjalankan checkpoint asli, Anda siap untuk mulai mengadaptasi kode model untuk Transformers.
Sesuaikan kode model
Perintah transformers add-new-model-like seharusnya telah menghasilkan file model dan konfigurasi.
src/transformers/models/brand_new_llama/modeling_brand_new_llama.pysrc/transformers/models/brand_new_llama/configuration_brand_new_llama.py
Kode yang dihasilkan secara otomatis di file modeling.py memiliki arsitektur yang sama dengan Llama jika Anda menjawab bahwa itu adalah model decoder-only, atau akan memiliki arsitektur yang sama dengan BART jika Anda menjawab bahwa itu adalah model encoder-decoder. Kode yang dihasilkan hanyalah titik awal. Berdasarkan penelitian Anda tentang model baru, Anda perlu mengimplementasikan perubahan spesifik tersebut dengan menyesuaikan kode yang dihasilkan. Hal ini mungkin melibatkan perubahan pada lapisan self-attention, urutan lapisan normalisasi, dan sebagainya.
Inisialisasi model
Pada tahap ini, kode Anda tidak perlu rapi atau bahkan sepenuhnya benar. Lebih efisien untuk membuat draf pertama dengan cepat lalu memperbaikinya secara iteratif. Hal terpenting adalah model Anda dapat diinstansiasi dari Transformers. Perintah di bawah ini membuat model dari konfigurasi dengan bobot acak, memverifikasi bahwa metode __init__ berfungsi.
from transformers import BrandNewLlama, BrandNewLlamaConfig
model = BrandNewLlama(BrandNewLlamaConfig())Inisialisasi acak terjadi di metode _init_weights dari BrandNewLlamaPreTrainedModel. Semua modul daun diinisialisasi berdasarkan variabel konfigurasi. Gunakan helper dari modul transformers.initialization untuk mengatur nilai, alih-alih memanggil operasi in-place secara langsung pada bobot atau .data miliknya.
from transformers import initialization as init
def _init_weights(self, module):
"""Initialize the weights"""
if isinstance(module, nn.Linear):
init.normal_(module.weight, mean=0.0, std=self.config.initializer_range)
if module.bias is not None:
init.zeros_(module.bias)
elif isinstance(module, nn.Embedding):
init.normal_(module.weight, mean=0.0, std=self.config.initializer_range)
if module.padding_idx is not None:
init.zeros_(module.weight[module.padding_idx])
elif isinstance(module, nn.LayerNorm):
init.zeros_(module.bias)
init.ones_(module.weight)Selalu inisialisasi bobot melalui helper transformers.initialization. Operasi in-place seperti module.bias.zero_() atau apa pun yang menyentuh module.weight.data melewati _is_hf_initialized yang menandai parameter mana yang sudah dimuat. from_pretrained() menjalankan _init_weights setelah memuat checkpoint, sehingga operasi in-place secara diam-diam menimpa bobot yang dimuat dengan nilai acak. Hal ini dipaksakan untuk model Transformers oleh aturan TRF012.
Selama from_pretrained(), model biasanya diinisialisasi pada perangkat
meta. Loader membuat ulang buffer non-persistent sebagai tensor kosong, sehingga nilai yang ditugaskan di__init__tidak dipertahankan. Inisialisasi buffer ini di_init_weightsagar memiliki nilai yang benar setelah dimuat. Untuk contoh, lihat bagaimana BERT menginisialisasi ID posisi dan ID tipe tokennya.
Skema inisialisasi dapat terlihat berbeda jika Anda perlu menyesuaikannya dengan model Anda. Submodul dengan metode reset_parameters miliknya sendiri dapat memanggilnya secara langsung. Sebagai contoh, Wav2Vec2ForPreTraining menginisialisasi nn.Linear pada dua lapisan linear terakhirnya. Panggilan ini aman karena from_pretrained() mem-patch fungsi torch.nn.init yang mendasarinya untuk menghormati flag _is_hf_initialized saat menjalankan _init_weights, sehingga bobot yang dimuat tidak akan ditimpa.
def _init_weights(self, module):
"""Initialize the weights"""
if isinstance(module, Wav2Vec2ForPreTraining):
module.project_hid.reset_parameters()
module.project_q.reset_parameters()Mengonversi checkpoint ke Transformers
Checkpoint asli harus dikonversi menjadi checkpoint yang kompatibel dengan Transformers.
Coba cari skrip konversi yang sudah ada untuk disalin, diadaptasi, dan digunakan kembali untuk model Anda!
- Jika Anda memindahkan model dari TensorFlow ke PyTorch, titik awal yang baik mungkin adalah skrip konversi BERT.
- Jika Anda memindahkan model dari PyTorch ke PyTorch, titik awal yang baik mungkin adalah skrip konversi BART.
Pastikan semua bobot yang diperlukan telah diinisialisasi dan tampilkan semua bobot checkpoint yang tidak digunakan untuk inisialisasi guna memastikan model telah dikonversi dengan benar.
Anda mungkin akan menemukan pernyataan bentuk yang salah atau penugasan nama selama konversi. Hal ini kemungkinan besar disebabkan oleh parameter yang salah dalam BrandNewLlamaConfig, arsitektur yang salah, bug pada metode init dari implementasi Anda, atau Anda perlu mentranspose salah satu bobot checkpoint.
Lanjutkan iterasi pada bagian Adapt the model code hingga semua bobot checkpoint dimuat dengan benar. Setelah Anda dapat memuat checkpoint ke dalam model Anda, simpan ke sebuah folder. Folder ini harus berisi file model.safetensors dan file config.json.
model.save_pretrained("/path/to/converted/checkpoint/folder")Untuk membantu proses konversi, bagian berikut secara singkat menjelaskan bagaimana model PyTorch menyimpan dan mendefinisikan bobot serta nama lapisan.
Bobot dan nama lapisan PyTorch
Membuat model PyTorch dasar sangat membantu untuk memahami bagaimana nama layer didefinisikan dan bobot diinisialisasi.
from torch import nn
class SimpleModel(nn.Module):
def __init__(self):
super().__init__()
self.dense = nn.Linear(10, 10)
self.intermediate = nn.Linear(10, 10)
self.layer_norm = nn.LayerNorm(10)Nama layer PyTorch didefinisikan oleh nama atribut kelas dari layer tersebut (dense, intermediate, layer_norm). Buat sebuah instance dari SimpleModel untuk mengisi semua layer dengan bobot acak.
model = SimpleModel()
print(model)
SimpleModel(
(dense): Linear(in_features=10, out_features=10, bias=True)
(intermediate): Linear(in_features=10, out_features=10, bias=True)
(layer_norm): LayerNorm((10,), eps=1e-05, elementwise_affine=True)
)Nilai bobot dari lapisan tertentu diinisialisasi secara acak.
print(model.dense.weight.data)
tensor([[-0.0818, 0.2207, -0.0749, -0.0030, 0.0045, -0.1569, -0.1598, 0.0212,
-0.2077, 0.2157],
[ 0.1044, 0.0201, 0.0990, 0.2482, 0.3116, 0.2509, 0.2866, -0.2190,
0.2166, -0.0212],
[-0.2000, 0.1107, -0.1999, -0.3119, 0.1559, 0.0993, 0.1776, -0.1950,
-0.1023, -0.0447],
[-0.0888, -0.1092, 0.2281, 0.0336, 0.1817, -0.0115, 0.2096, 0.1415,
-0.1876, -0.2467],
[ 0.2208, -0.2352, -0.1426, -0.2636, -0.2889, -0.2061, -0.2849, -0.0465,
0.2577, 0.0402],
[ 0.1502, 0.2465, 0.2566, 0.0693, 0.2352, -0.0530, 0.1859, -0.0604,
0.2132, 0.1680],
[ 0.1733, -0.2407, -0.1721, 0.1484, 0.0358, -0.0633, -0.0721, -0.0090,
0.2707, -0.2509],
[-0.1173, 0.1561, 0.2945, 0.0595, -0.1996, 0.2988, -0.0802, 0.0407,
0.1829, -0.1568],
[-0.1164, -0.2228, -0.0403, 0.0428, 0.1339, 0.0047, 0.1967, 0.2923,
0.0333, -0.0536],
[-0.1492, -0.1616, 0.1057, 0.1950, -0.2807, -0.2710, -0.1586, 0.0739,
0.2220, 0.2358]]).Dalam skrip konversi, bobot acak harus diganti dengan bobot yang tepat dari lapisan yang sesuai dalam checkpoint asli.
# retrieve matching layer weights with recursive algorithm
layer_name = "dense"
pretrained_weight = array_of_dense_layer
model_pointer = getattr(model, "dense")
model_pointer.weight.data = torch.from_numpy(pretrained_weight)Verifikasi bahwa bobot yang diinisialisasi secara acak dan bobot checkpoint pretrained yang bersesuaian memiliki shape dan name yang identik. Tambahkan pernyataan assert untuk shape dan tampilkan nama-nama bobot checkpoint.
assert (
model_pointer.weight.shape == pretrained_weight.shape
), f"Pointer shape of random weight {model_pointer.shape} and array shape of checkpoint weight {pretrained_weight.shape} mismatched"
logger.info(f"Initialize PyTorch weight {layer_name} from {pretrained_weight.name}")Ketika bentuk atau nama tidak cocok, Anda mungkin telah menetapkan bobot checkpoint yang salah ke lapisan yang diinisialisasi secara acak. Bentuk yang salah mungkin terjadi karena parameter BrandNewLlama tidak sepenuhnya cocok dengan parameter model asli. Namun, hal ini juga bisa disebabkan oleh implementasi lapisan PyTorch yang mengharuskan bobot ditranspos terlebih dahulu.
Implementasikan jalur maju
Langkah selanjutnya yang harus diimplementasikan adalah forward pass jika model berhasil dimuat dengan benar. Proses ini menerima beberapa input dan mengembalikan output model.
model = BrandNewLlamaModel.from_pretrained("/path/to/converted/checkpoint/folder")
input_ids = [0, 4, 4, 3, 2, 4, 1, 7, 19]
output = model.generate(input_ids).last_hidden_statesJangan berkecil hati jika forward pass Anda tidak identik dengan output dari model asli atau jika mengembalikan error. Periksa bahwa forward pass tidak melempar error apa pun. Hal ini sering terjadi karena dimensi salah atau karena tipe data yang salah digunakan (torch.long alih-alih torch.float32).
Output Anda harus memiliki presisi 1e-3. Pastikan bentuk output dan nilai output identik. Alasan umum mengapa output tidak identik meliputi:
- Beberapa lapisan tidak ditambahkan (lapisan aktivasi atau koneksi residual).
- Matriks embedding kata tidak terikat.
- Embedding posisional yang salah digunakan karena implementasi asli menyertakan offset.
- Dropout diterapkan selama forward pass. Perbaiki kesalahan ini dengan memastikan
model.trainingadalahFalsedan meneruskanself.trainingke torch.nn.functional.dropout.
Bandingkan forward pass dari model asli dan implementasi Anda untuk memeriksa apakah ada perbedaan. Idealnya, lakukan debug dan cetak keluaran antara (intermediate outputs) dari kedua implementasi forward pass untuk mengidentifikasi di mana implementasi asli berbeda dari implementasi Anda.
- Pastikan
input_idsyang di-hardcode di kedua implementasi identik. - Verifikasi bahwa output dari transformasi pertama dari
input_ids(biasanya word embeddings) identik, lalu lanjutkan hingga lapisan terakhir.
Setiap perbedaan antara kedua implementasi tersebut harus menunjukkan adanya bug dalam implementasi Anda.
Salah satu strategi terbaik adalah menambahkan banyak pernyataan print pada posisi yang sama di kedua implementasi, lalu menghapusnya secara bertahap ketika mereka menghasilkan nilai yang identik untuk output antara.
Ketika kedua implementasi menghasilkan output yang sama, verifikasi bahwa output berada dalam presisi 1e-3.
torch.allclose(original_output, output, atol=1e-3)Ini biasanya merupakan bagian paling sulit dari prosesnya. Selamat jika Anda sudah sampai sejauh ini!
Dan jika Anda terjebak atau kesulitan dengan langkah ini, jangan ragu untuk meminta bantuan di pull request Anda.
Tambahkan pengujian model
Meskipun modelnya berfungsi, Anda masih perlu menambahkan tes untuk memastikan kompatibilitasnya dengan Transformers. Tes penting karena membantu pengguna memahami pekerjaan Anda dengan melihat tes tertentu, dan karena mencegah model Anda rusak di masa depan jika ada perubahan yang dilakukan.
Cookiecutter seharusnya telah menambahkan file uji untuk model Anda. Jalankan file uji di bawah ini untuk memastikan semua uji umum lulus.
pytest tests/models/brand_new_llama/test_modeling_brand_new_llama.py
Tes integrasi harus ditambahkan terlebih dahulu karena berfungsi sama seperti skrip debugging yang Anda gunakan sebelumnya untuk mengimplementasikan model baru di Transformers. Templat tes model tersebut, BrandNewLlamaModelIntegrationTests, telah ditambahkan oleh Cookiecutter dan perlu diisi. Untuk memastikan tes tersebut lulus, jalankan perintah berikut.
RUN_SLOW=1 pytest -sv tests/models/brand_new_llama/test_modeling_brand_new_llama.py::BrandNewLlamaModelIntegrationTests
SET RUN_SLOW=1 pytest -sv tests/models/brand_new_llama/test_modeling_brand_new_llama.py::BrandNewLlamaModelIntegrationTests
Semua fitur yang unik untuk BrandNewLlama harus diuji dalam pengujian terpisah di bawah BrandNewLlamaModelTester/BrandNewLlamaModelTest. Pengujian ini sering terlewatkan, tetapi sangat penting karena:
- hal ini membantu mentransfer pengetahuan yang Anda peroleh selama proses tersebut ke komunitas dengan menunjukkan bagaimana fitur-fitur baru model tersebut bekerja
- kontributor di masa depan dapat dengan cepat menguji perubahan pada model dengan menjalankan tes khusus ini
Implementasi tokenizer
Kami merekomendasikan untuk menambahkan tokenizer cepat (PreTrainedTokenizerFast) agar pengguna mendapatkan performa terbaik. Silakan tandai @ArthurZucker atau @itazap di PR Anda untuk bantuan tentang cara menambahkan PreTrainedTokenizerFast.
Dengan model sudah selesai, saatnya fokus pada tokenizer. Tokenizer harus identik atau sangat mirip dengan tokenizer yang sudah ada di Transformers.
Cari dan muat file tokenizer asli ke dalam implementasi Anda. Buat skrip di repositori asli yang menerima string sebagai input dan mengembalikan input_ids. Pseudocode-nya sebaiknya mirip dengan kode di bawah.
input_str = "This is a long example input string containing special characters .$?-, numbers 2872 234 12 and words."
model = BrandNewLlamaModel.load_pretrained_checkpoint("/path/to/checkpoint/")
input_ids = model.tokenize(input_str)Anda mungkin perlu mencari repositori asli untuk menemukan fungsi tokenizer yang tepat atau memodifikasi tokenizer yang ada di klon repositori asli Anda agar hanya mengembalikan input_ids. Skrip untuk tokenizer Anda sebaiknya mirip dengan berikut.
from transformers import BrandNewLlamaTokenizer
input_str = "This is a long example input string containing special characters .$?-, numbers 2872 234 12 and words."
tokenizer = BrandNewLlamaTokenizer.from_pretrained("/path/to/tokenizer/folder/")
input_ids = tokenizer(input_str).input_idsKetika kedua implementasi memiliki input_ids yang sama, tambahkan file uji tokenizer. File ini serupa dengan file uji pemodelan. File uji tokenizer harus berisi beberapa uji integrasi yang di-hardcode.
Implementasi pemroses gambar
Image processors kini menggunakan arsitektur berbasis backend. Backend default adalah TorchvisionBackend, yang menggunakan pustaka torchvision dan dapat melakukan pemrosesan gambar di GPU. Backend alternatif PIL/NumPy (PilBackend) juga disediakan. Kedua backend diimpor dari
image_processing_backends. Silakan tag @yonigozlan untuk bantuan.
Meskipun contoh ini tidak mencakup image processor, Anda mungkin perlu mengimplementasikannya jika model Anda memerlukan input gambar. Image processor bertanggung jawab untuk mengonversi gambar ke dalam format yang sesuai untuk model Anda. Sebelum mengimplementasikan yang baru, periksa apakah image processor yang sudah ada di pustaka Transformers dapat digunakan kembali, karena banyak model berbagi teknik pemrosesan gambar yang serupa. Perhatikan bahwa Anda juga dapat menggunakan modular untuk image processor guna menggunakan kembali komponen yang sudah ada.
Jika Anda memang perlu mengimplementasikan pemroses gambar baru, setiap model memiliki dua file pemroses:
image_processing_<model>.py: prosesor default berbasis torchvision (<Model>ImageProcessor), yang mewarisi dari TorchvisionBackend. Ini menggantikan prosesor “fast” lama.image_processing_pil_<model>.py: pemroses alternatif PIL/NumPy (<Model>ImageProcessorPil), yang mewarisi dari PilBackend. Ini menggantikan pemroses “lambat” lama.
File backend torchvision juga mendefinisikan kelas kwargs kustom apa pun yang diimpor oleh file PIL. Kedua file menggunakan dekorator @auto_docstring — jangan tambahkan docstring kelas manual. Lihat IMAGE_PROCESSOR_REFACTORING_GUIDE.md untuk panduan langkah demi langkah dan contoh lengkap.
Tambahkan tes untuk image processor di tests/models/your_model_name/test_image_processing_your_model_name.py. Tes ini sebaiknya serupa dengan tes untuk image processor lainnya dan harus memverifikasi bahwa image processor menangani input gambar dengan benar. Jika image processor Anda mencakup fitur atau metode pemrosesan yang unik, pastikan Anda juga menambahkan tes spesifik untuk hal-hal tersebut.
Implementasi prosesor
Jika model Anda menerima beberapa modalitas, seperti teks dan gambar, Anda perlu menambahkan sebuah processor. Processor ini memusatkan pra-pemrosesan dari berbagai modalitas sebelum meneruskannya ke model.
Processor harus memanggil processor yang sesuai untuk setiap modalitas di dalam fungsi __call__ untuk menangani setiap jenis input dengan benar. Pastikan untuk memeriksa processor yang sudah ada di dalam pustaka untuk memahami struktur yang diharapkan. Transformers menggunakan konvensi berikut dalam tanda tangan fungsi __call__.
def __call__(
self,
images: ImageInput = None,
text: Union[TextInput, PreTokenizedInput, list[TextInput], list[PreTokenizedInput]] = None,
audio=None,
videos=None,
**kwargs: Unpack[YourModelProcessorKwargs],
) -> BatchFeature:
...YourModelProcessorKwargs adalah TypedDict yang mencakup semua argumen pemrosesan umum serta argumen tambahan yang mungkin diperlukan oleh prosesor tertentu.
Tambahkan tes untuk prosesor di tests/models/your_model_name/test_processor_your_model_name.py. Tes ini harus serupa dengan tes untuk prosesor lain dan harus memverifikasi bahwa prosesor menangani modalitas yang berbeda dengan benar.
Uji integrasi
Sekarang Anda sudah memiliki model dan tokenizer, tambahkan uji integrasi end-to-end untuk model dan tokenizer ke tests/models/brand_new_llama/test_modeling_brand_new_llama.py.
Tes harus menyediakan contoh teks-ke-teks yang bermakna untuk menunjukkan bahwa model bekerja sesuai harapan. Misalnya, Anda dapat menyertakan pasangan terjemahan sumber-ke-target, pasangan artikel-ke-ringkasan, atau pasangan pertanyaan-ke-jawaban.
Jika checkpoint belum dihaluskan pada tugas turunan, maka pengujian model sudah cukup.
Terakhir, usahakan agar tes Anda dapat dijalankan di GPU dengan menambahkan pernyataan .to(self.device) ke tensor internal model. Jika Anda tidak memiliki akses ke GPU, kami dapat menanganinya untuk Anda.
Tambahkan dokumentasi
Model Anda hanya berguna jika pengguna tahu cara menggunakannya. Inilah mengapa penting untuk menambahkan dokumentasi dan docstring. Cookiecutter menambahkan file template, docs/source/model_doc/brand_new_llama.md, yang dapat Anda isi dengan informasi tentang model Anda.
Ini umumnya merupakan interaksi pertama pengguna dengan model, sehingga dokumentasinya harus jelas dan ringkas. Sering kali sangat berguna untuk menambahkan contoh cara penggunaan model.
Pastikan docstring ditambahkan ke src/transformers/models/brand_new_llama/modeling_brand_new_llama.py dan mencakup semua input dan output yang diperlukan. Tinjau panduan kami untuk menulis dokumentasi dan docstring.
Refactor
Saatnya merapikan dan memastikan gaya kode konsisten dengan bagian lain pustaka. Jalankan perintah berikut untuk memperbaiki gaya yang salah secara otomatis.
make style
Untuk memverifikasi bahwa gaya kode lolos pemeriksaan kualitas, jalankan perintah di bawah ini.
make check-repo
Mungkin ada tes atau pemeriksaan lain yang gagal (docstring yang hilang atau penamaan yang salah) pada pull request Anda karena tes desain ketat dari Transformers. Kami dapat membantu Anda dengan masalah-masalah ini jika Anda terjebak.
Setelah memastikan kode berjalan dengan benar, Anda mungkin ingin melakukan refactoring agar lebih mudah dibaca atau lebih rapi.
Unggah ke Hub
Konversi dan unggah semua checkpoint ke Hub. Tambahkan model card untuk memberikan transparansi dan konteks yang lebih baik tentang model. Model card harus menyoroti karakteristik spesifik dari sebuah checkpoint, bagaimana model tersebut dilatih, dan contoh kode tentang cara menggunakannya.
Dalam banyak kasus, menambahkan notebook interaktif yang dapat dijalankan oleh pengguna merupakan cara yang sangat baik untuk menunjukkan cara menggunakan model untuk inferensi atau melakukan fine-tuning pada tugas downstream. Meskipun tidak diwajibkan, menyertakan notebook dapat mendorong adopsi model Anda menjadi lebih besar.
Anda juga harus berkonsultasi dengan tim Transformers untuk menentukan nama yang tepat untuk model, serta mendapatkan hak akses yang diperlukan untuk mengunggah model.
Gunakan metode push_to_hub() untuk mengunggah model.
brand_new_bert.push_to_hub("brand_new_llama")Lihat panduan Sharing untuk informasi lebih lanjut tentang mengunggah model ke Hub.
Gabungkan model Anda
Anda akhirnya siap untuk menggabungkan pull request Anda dan secara resmi menambahkan model ke Transformers! Pastikan semua tes lulus dan semua komentar serta umpan balik telah ditangani.
Selamat karena telah menambahkan model baru ke Transformers! 🥳
Ini adalah kontribusi yang sangat signifikan. Karya Anda membuat Transformers lebih mudah diakses oleh pengembang dan peneliti di seluruh dunia. Anda harus bangga dengan kontribusi Anda dan bagikan pencapaian Anda dengan komunitas!
Lihat juga
- Aturan struktur model — aturan statis yang diterapkan pada semua file
modeling_*.pydanconfiguration_*.py. Jalankanmake typinguntuk memeriksanya sebelum membuka PR. - Periksa pull request — referensi lengkap tentang pemeriksaan CI yang dijalankan pada PR Anda dan cara untuk lolos dari pemeriksaan tersebut.