Transformers documentation
Đóng góp mô hình cũ
Đóng góp mô hình cũ
Hãy thử thêm các mô hình mới với cách tiếp cận độc lập hơn trước. Điều này giúp việc đóng góp một mô hình cho Transformers trở nên dễ dàng hơn đáng kể!
Nhiều mô hình trong Transformers được đóng góp bởi các nhà phát triển và nhà nghiên cứu. Là một dự án mã nguồn mở, chúng tôi cam kết trao quyền cho cộng đồng để chủ động và độc lập thêm nhiều mô hình hơn.
Khi bạn thêm một mô hình vào Transformers, bạn sẽ học được:
- tìm hiểu thêm về các thực hành tốt nhất mã nguồn mở
- về kiến trúc của một mô hình
- về các nguyên tắc thiết kế của Transformers
- cách kiểm tra các mô hình lớn một cách hiệu quả
- cách sử dụng các tiện ích Python như Black và Ruff để tạo ra mã nguồn sạch sẽ và dễ đọc
Đây là một quá trình đầy thách thức nhưng cũng rất đáng giá.
Hướng dẫn này sẽ giúp bạn thêm một mô hình PyTorch BrandNewLlama mẫu vào Transformers. Trước khi bắt đầu, bạn nên làm quen với thư viện này.
Tổng quan về Transformers
Transformers là một thư viện có quan điểm riêng với triết lý và các lựa chọn thiết kế độc đáo. Những lựa chọn này giúp chúng tôi mở rộng và duy trì Transformers một cách bền vững.
Tìm hiểu thêm về các nguyên tắc thiết kế của chúng tôi trong tài liệu Triết lý.
Một số lựa chọn thiết kế trong số đó là:
- composition > over-abstraction
- Việc lặp lại mã không phải lúc nào cũng là điều xấu nếu nó cải thiện đáng kể tính dễ đọc và khả năng tiếp cận
- các tệp model tự chứa và toàn bộ mã model cần thiết được tìm thấy trong tệp
modeling_mymodel.py
Những lựa chọn thiết kế này rất quan trọng đối với tất cả mọi người tương tác với mô hình. Chúng dễ đọc, dễ hiểu và dễ chỉnh sửa hơn.
Phần này mô tả cách các lớp mô hình và cấu hình tương tác với nhau cũng như phong cách mã nguồn của Transformers.
Mô hình và cấu hình
Tất cả các mô hình của Transformers kế thừa từ lớp cơ sở PreTrainedModel và PreTrainedConfig. Cấu hình là bản thiết kế của các mô hình.
Mỗi model không bao giờ có quá hai cấp độ trừu tượng để giữ cho mã dễ đọc. Model ví dụ ở đây, BrandNewLlama, kế thừa từ BrandNewLlamaPreTrainedModel và PreTrainedModel. Điều quan trọng là một model mới chỉ phụ thuộc vào PreTrainedModel để có thể sử dụng các phương thức from_pretrained() và save_pretrained().
Các hàm quan trọng khác như phương thức forward được định nghĩa trong tệp modeling.py.
Các đầu mô hình cụ thể (ví dụ: phân loại chuỗi hoặc mô hình hóa ngôn ngữ) nên gọi mô hình cơ sở trong bước truyền tiến (forward pass) thay vì kế thừa từ nó để giữ mức độ trừu tượng thấp.
Các mô hình mới yêu cầu một cấu hình, ví dụ BrandNewLlamaConfig, được lưu trữ dưới dạng thuộc tính của PreTrainedModel.
model = BrandNewLlamaModel.from_pretrained("username/brand_new_llama")
model.configPreTrainedConfig cung cấp các phương thức from_pretrained() và save_pretrained().
Khi bạn sử dụng PreTrainedModel.save_pretrained(), nó sẽ tự động gọi PreTrainedConfig.save_pretrained() để lưu cả mô hình và cấu hình cùng nhau.
Một mô hình được lưu vào tệp model.safetensors và cấu hình được lưu vào tệp config.json.
Phong cách mã
Transformers ưu tiên mã sạch và dễ đọc hơn so với phong cách mã trừu tượng hơn. Một số lựa chọn về phong cách mã bao gồm:
Mã nguồn nên dễ tiếp cận với người dùng không nói tiếng Anh. Hãy chọn tên biến mô tả rõ ràng và tránh dùng từ viết tắt. Ví dụ, “activation” được ưu tiên hơn “act”. Tên biến chỉ gồm một chữ cái rất không được khuyến khích, trừ khi đó là chỉ số trong vòng lặp for.
Mã rõ ràng được ưu tiên - ngay cả khi nó dài hơn - so với mã ngắn gọn hơn.
Tránh kế thừa nn.Sequential. Thay vào đó, hãy kế thừa nn.Module để có thể gỡ lỗi mã nhanh chóng bằng các câu lệnh in hoặc điểm dừng.
Cú hàm nên được chú thích kiểu. Nếu không, hãy sử dụng tên biến rõ ràng để dễ hiểu hơn.
Vấn đề thêm mô hình mới
Mở một issue Thêm model mới để thêm một model cụ thể.
Lọc theo nhãn New model trên GitHub để xem và thêm các yêu cầu mô hình hiện có.
Đây là thời điểm tốt để làm quen với BrandNewLlama. Việc đọc bài báo nghiên cứu về mô hình sẽ giúp bạn hiểu rõ hơn về thiết kế kỹ thuật và cách triển khai của nó. Bạn không nhất thiết phải lo lắng quá nhiều về các chi tiết lý thuyết. Thay vào đó, hãy tập trung vào các khía cạnh thực tiễn. Sử dụng các câu hỏi bên dưới để định hướng cho việc đọc của bạn.
- BrandNewLlama là loại mô hình nào? Nó là mô hình encoder, decoder, hay encoder-decoder?
- BrandNewLlama có thể được sử dụng cho những tác vụ nào?
- Điều gì khiến BrandNewLlama khác biệt so với các mô hình khác?
- Những mô hình nào trong Transformers có sự tương đồng nhất với BrandNewLlama?
- BrandNewLlama sử dụng tokenizer nào?
Ngoài việc tìm hiểu thêm về mô hình của bạn, hãy sử dụng các mẹo bên dưới để giúp bạn thêm mô hình nhanh hơn.
Mỗi người đóng góp có phong cách và quy trình làm việc riêng khi thêm mô hình vào Transformers. Để có ví dụ, hãy xem cách Gemma được thêm vào.
- Đừng phát minh lại bánh xe! Hãy dành thời gian khám phá các mô hình và bộ phân từ (tokenizer) hiện có để xem bạn có thể sao chép và tái sử dụng những gì. Grep và ripgrep là những công cụ tuyệt vời cho việc này.
- Đây là thách thức thiên về kỹ thuật hơn là khoa học. Hãy tập trung vào các khía cạnh thực tế hơn (ví dụ như thiết lập môi trường gỡ lỗi hiệu quả) thay vì các khía cạnh lý thuyết của mô hình.
- Đừng ngại nhờ sự giúp đỡ! Chúng tôi luôn sẵn sàng hỗ trợ bạn. 🤗
Môi trường phát triển
Nhấp vào nút Fork trên kho Transformers để tạo bản sao của riêng bạn để làm việc. Clone kho về ổ đĩa cục bộ và thêm kho gốc dưới dạng remote.
git clone https://github.com/[your Github handle]/transformers.git
cd transformers
git remote add upstream https://github.com/huggingface/transformers.gitTạo một môi trường ảo và thực hiện cài đặt dạng chỉnh sửa được thư viện với các phụ thuộc “dev” hoặc phát triển.
python -m venv .env
source .env/bin/activate
pip install -e ".[dev]"Do số lượng các phụ thuộc tùy chọn của Transformers ngày càng tăng, lệnh này có thể thất bại. Trong trường hợp đó, hãy cài đặt các phụ thuộc “quality”. Đồng thời, hãy đảm bảo bạn đã cài đặt một framework học sâu.
pip install -e ".[quality]"Quay lại thư mục cha và clone và cài đặt kho BrandNewLlama gốc.
git clone https://github.com/org_that_created_brand_new_llama_org/brand_new_llama.git
cd brand_new_bert
pip install -e .Quay lại bản clone của Transformers của bạn để bắt đầu chuyển đổi BrandNewLlama.
cd transformersCó hai môi trường gỡ lỗi khả dụng để chạy mô hình gốc, đó là notebook (Google Colab hoặc Jupyter) hoặc một script Python cục bộ.
Chúng tôi không khuyến nghị thiết lập môi trường GPU để chạy mô hình gốc vì chi phí có thể rất cao. Thay vào đó, hãy làm việc trong môi trường CPU trước để xác minh mô hình hoạt động trong Transformers. Sau khi hoàn tất, bạn có thể xác minh nó trên GPU.
Notebooks rất hữu ích để thực thi code theo từng cell, giúp tách biệt các thành phần logic khỏi nhau. Nó cũng có thể rút ngắn chu kỳ gỡ lỗi vì các kết quả trung gian có thể được lưu trữ. Bạn cũng có thể chia sẻ notebooks khi làm việc với các cộng tác viên khác.
Nhược điểm là nếu bạn chưa quen với chúng, có thể sẽ mất một chút thời gian để làm quen.
Nếu kiến trúc mô hình giống hệt với một mô hình hiện có, hãy bỏ qua và chuyển đến chuyển đổi checkpoint, vì bạn có thể tái sử dụng kiến trúc của mô hình hiện có.
Chạy lệnh bên dưới để bắt đầu và hoàn thành bảng khảo sát với một số thông tin cơ bản về mô hình mới. Lệnh này khởi động quy trình bằng cách tự động tạo ra một số mã mô hình mà bạn sẽ cần điều chỉnh.
transformers add-new-model-like
Tạo một pull request
Trước khi bắt đầu điều chỉnh mã, hãy tạo một pull request để theo dõi tiến độ và nhận phản hồi từ đội ngũ Transformers. Đặt tiêu đề pull request của bạn là [WIP] Add BrandNewLlama để rõ ràng rằng đây là một công việc đang được thực hiện.
Tạo một nhánh có tên mô tả từ nhánh chính của bạn.
git checkout -b add_brand_new_bert
Commit mã, sau đó fetch và rebase trên nhánh main.
git add . git commit git fetch upstream git rebase upstream/main
Đẩy mọi thay đổi lên nhánh của bạn và nhấp vào Compare & pull request để mở một pull request trên GitHub. Mở pull request ở dạng draft để cho biết đây là công việc đang được thực hiện.
git push -u origin a-descriptive-name-for-my-changes
Hãy mời các thành viên liên quan của đội Hugging Face tham gia bằng cách thêm tên GitHub của họ vào pull request để hỏi đáp, phản hồi, bình luận và xem xét. Chỉ dẫn các thành viên đến phần cụ thể trong mã mà bạn muốn họ xem bằng cách nhấp vào tab Files changed, sau đó nhấp vào + bên trái số thứ tự dòng để thêm bình luận. Khi một câu hỏi hoặc vấn đề được giải quyết, nhấp vào Resolve để xác nhận vấn đề đã được xử lý. Điều này giúp cuộc trò chuyện được tổ chức gọn gàng và rõ ràng.
Hãy nhớ định kỳ commit và push công việc của bạn, đồng thời cập nhật công việc của bạn với nhánh main hiện tại.
git fetch upstream git merge upstream/main
Checkpoint gốc
Hãy dành thời gian làm việc với bản triển khai mô hình gốc trước để hiểu cách nó hoạt động.
Điều này có thể gây khó khăn nếu kho lưu trữ mô hình gốc thiếu tài liệu hoặc nếu mã nguồn phức tạp. Nhưng bạn nên coi đây là động lực để triển khai mô hình trong Transformers. Đóng góp của bạn giúp mô hình trở nên dễ tiếp cận và thân thiện hơn với người dùng cho tất cả mọi người!
Hãy làm quen với kho lưu trữ gốc bằng cách thực hiện các bước sau.
- Xác định vị trí các trọng số được huấn luyện trước.
- Tìm cách nạp trọng số được huấn luyện trước vào mô hình.
- Tìm cách chạy tokenizer độc lập với model.
- Theo dõi một lần truyền tiến (forward pass) để hiểu các lớp và hàm nào là bắt buộc. Đây có lẽ là những lớp và hàm duy nhất mà bạn sẽ phải triển khai.
- Xác định tất cả các thành phần quan trọng (lớp mô hình, các lớp con của mô hình, lớp self-attention, v.v.) của mô hình.
- Tìm cách gỡ lỗi mô hình trong kho lưu trữ gốc. Thêm các câu lệnh in, sử dụng trình gỡ lỗi tương tác như ipdb, hoặc một môi trường phát triển tích hợp (IDE) hiệu quả như PyCharm.
Điểm cuối cùng đặc biệt quan trọng vì bạn cần hiểu rõ những gì đang diễn ra bên trong mô hình gốc trước khi có thể triển khai lại nó trong Transformers. Hãy thoải mái mở issue và pull request trong kho lưu trữ gốc nếu bạn gặp bất kỳ vấn đề nào.
Bước đầu tiên tốt là tải một checkpoint nhỏ đã được huấn luyện trước và thử tái tạo một lần truyền tiến với một vector nguyên mẫu của các đầu vào. Ví dụ, trong mã giả, điều này có thể trông như sau.
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)Gỡ lỗi
Nếu bạn gặp sự cố, bạn sẽ cần chọn một trong các chiến lược gỡ lỗi sau tùy thuộc vào mã nguồn của mô hình gốc.
Chiến lược này dựa vào việc chia nhỏ mô hình gốc thành các thành phần con nhỏ hơn, chẳng hạn như khi mã có thể chạy dễ dàng ở chế độ eager. Mặc dù khó khăn hơn, cách tiếp cận này có một số ưu điểm.
- Việc so sánh mô hình gốc với cài đặt của bạn sẽ dễ dàng hơn về sau. Bạn có thể tự động kiểm tra xem từng thành phần riêng lẻ có khớp với thành phần tương ứng trong cài đặt của Transformers hay không. Cách này tốt hơn là dựa vào việc so sánh trực quan dựa trên các câu lệnh in.
- Việc chuyển đổi từng thành phần riêng lẻ dễ dàng hơn so với việc chuyển đổi toàn bộ mô hình.
- Việc chia nhỏ mô hình thành các phần nhỏ hơn giúp dễ hiểu hơn cách hoạt động của nó.
- Việc ngăn chặn các lỗi hồi quy ở giai đoạn sau khi bạn thay đổi mã sẽ dễ dàng hơn nhờ vào các bài kiểm tra từng thành phần.
Tham khảo các kiểm tra tích hợp của ELECTRA để có một ví dụ tốt về cách phân tách một mô hình thành các thành phần nhỏ hơn.
Chiến lược này khả thi khi mã nguồn gốc quá phức tạp, chỉ cho phép chạy các thành phần trung gian ở chế độ biên dịch, hoặc khi việc tách mô hình thành các thành phần con nhỏ hơn quá tốn thời gian (hoặc thậm chí là không thể).
Ví dụ, bản triển khai T5 của MeshTensorFlow quá phức tạp và không cung cấp cách đơn giản để tách mô hình thành các thành phần con. Trong tình huống này, bạn sẽ phải dựa vào việc kiểm tra các câu lệnh in.
Dù bạn chọn chiến lược nào, nên gỡ lỗi các lớp đầu tiên trước và các lớp cuối cùng sau. Lấy đầu ra, bằng các câu lệnh in hoặc các hàm thành phần con, của các lớp sau theo thứ tự này.
- các id đầu vào được truyền vào mô hình
- nhúng từ
- đầu vào của lớp Transformer đầu tiên
- đầu ra của lớp Transformer đầu tiên
- đầu ra của n-1 lớp Transformer tiếp theo
- đầu ra của toàn bộ mô hình
Các id đầu vào chỉ cần là một mảng các số nguyên như input_ids = [0, 4, 4, 3, 2, 4, 1, 7, 19].
Đầu ra của các lớp thường bao gồm các mảng float nhiều chiều.
[[
[-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]]],Mọi đầu ra của model Transformers đều phải có độ chính xác hoặc dung sai lỗi là 1e-3. Điều này tính đến các khác biệt đầu ra phát sinh từ việc sử dụng framework thư viện khác nhau. Hãy so sánh các đầu ra trung gian của model gốc với cài đặt Transformers để đảm bảo chúng gần như giống hệt nhau. Việc có một môi trường gỡ lỗi hiệu quả là rất quan trọng cho bước này.
Dưới đây là một số mẹo để có môi trường gỡ lỗi hiệu quả.
Để gỡ lỗi các kết quả trung gian, bạn cần dựa vào framework machine learning mà kho lưu trữ mô hình gốc đang sử dụng. Đối với PyTorch, bạn nên viết một script để phân tách mô hình gốc thành các thành phần con nhỏ hơn nhằm lấy các giá trị trung gian.
Việc gỡ lỗi sẽ nhanh hơn khi sử dụng checkpoint được huấn luyện trước có kích thước nhỏ so với checkpoint lớn, nơi mà bước truyền thẳng (forward pass) mất hơn 10 giây. Nếu chỉ có các checkpoint lớn, hãy tạo một mô hình giả (dummy model) với các trọng số được khởi tạo ngẫu nhiên và lưu các trọng số đó để so sánh với cài đặt của Transformers.
Tìm cách dễ nhất để gọi bước truyền thẳng (forward pass) của mô hình. Lý tưởng nhất, hàm này (có thể được gọi là
predict,evaluate,forward, hoặc__call__) chỉ nên gọi bước truyền thẳng một lần. Việc gỡ lỗi một hàm gọi bước truyền thẳng nhiều lần sẽ khó khăn hơn.Tách biệt quá trình tokenization khỏi bước forward. Xác định vị trí mà chuỗi đầu vào được chuyển đổi thành input ids trong bước forward và bắt đầu từ đó. Bạn có thể cần tạo một script nhỏ hoặc sửa đổi mã gốc để trực tiếp đưa vào input ids thay vì chuỗi đầu vào.
Đảm bảo rằng model không ở chế độ huấn luyện. Điều này có thể tạo ra các đầu ra ngẫu nhiên do nhiều lớp dropout trong model. Quá trình truyền thuận trong môi trường gỡ lỗi của bạn phải mang tính tất định để các lớp dropout không được sử dụng.
Khi bạn đã có thể chạy checkpoint gốc, bạn đã sẵn sàng bắt đầu điều chỉnh mã mô hình cho Transformers.
Điều chỉnh mã mô hình
Lệnh transformers add-new-model-like lẽ ra đã tạo ra tệp mô hình và tệp cấu hình.
src/transformers/models/brand_new_llama/modeling_brand_new_llama.pysrc/transformers/models/brand_new_llama/configuration_brand_new_llama.py
Mã được tạo tự động trong tệp modeling.py có kiến trúc giống Llama nếu bạn trả lời rằng đó là mô hình chỉ có decoder, hoặc sẽ có kiến trúc giống BART nếu bạn trả lời rằng đó là mô hình encoder-decoder. Mã được tạo ra chỉ là điểm khởi đầu. Dựa trên nghiên cứu của bạn về mô hình mới, bạn sẽ cần triển khai những thay đổi cụ thể đó bằng cách điều chỉnh mã đã được tạo. Điều này có thể bao gồm các thay đổi đối với lớp self-attention, thứ tự của lớp normalization, v.v.
Khởi tạo mô hình
Ở bước này, mã của bạn không cần phải sạch sẽ hay thậm chí hoàn toàn chính xác. Hiệu quả hơn là nhanh chóng tạo bản nháp đầu tiên rồi cải tiến dần dần. Điều quan trọng nhất là mô hình của bạn có thể được khởi tạo từ Transformers. Lệnh bên dưới tạo một mô hình từ cấu hình với trọng số ngẫu nhiên, xác minh rằng phương thức __init__ hoạt động.
from transformers import BrandNewLlama, BrandNewLlamaConfig
model = BrandNewLlama(BrandNewLlamaConfig())Khởi tạo ngẫu nhiên diễn ra trong phương thức _init_weights của BrandNewLlamaPreTrainedModel. Tất cả các module lá được khởi tạo dựa trên các biến trong cấu hình. Hãy sử dụng các hàm trợ giúp từ module transformers.initialization để đặt giá trị, thay vì gọi trực tiếp các thao tác in-place trên một trọng số hoặc .data của nó.
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)Luôn khởi tạo trọng số thông qua các tiện ích transformers.initialization. Các thao tác tại chỗ như module.bias.zero_() hoặc bất kỳ thao tác nào chạm đến module.weight.data sẽ bỏ qua _is_hf_initialized, thành phần đánh dấu các tham số đã được nạp. from_pretrained() chạy _init_weights sau khi nạp checkpoint, do đó các thao tác tại chỗ sẽ âm thầm ghi đè các trọng số đã nạp bằng các giá trị ngẫu nhiên. Điều này được thực thi cho các mô hình Transformers bằng quy tắc TRF012.
Trong quá trình from_pretrained(), các mô hình thường được khởi tạo trên thiết bị
meta. Trình tải lại tạo các buffer không bền (non-persistent) dưới dạng tensor rỗng, do đó các giá trị được gán trong__init__sẽ không được giữ lại. Hãy khởi tạo các buffer này trong_init_weightsđể chúng có giá trị chính xác sau khi tải. Để xem ví dụ, hãy xem cách BERT khởi tạo position IDs và token type IDs của nó.
Phương án khởi tạo có thể trông khác đi nếu bạn cần điều chỉnh nó cho phù hợp với mô hình của mình. Một submodule có phương thức reset_parameters riêng có thể gọi trực tiếp phương thức đó. Ví dụ, Wav2Vec2ForPreTraining khởi tạo nn.Linear trong hai lớp tuyến tính cuối cùng của nó. Việc gọi này là an toàn vì from_pretrained() vá các hàm torch.nn.init bên dưới để tôn trọng cờ _is_hf_initialized trong khi chạy _init_weights, do đó các trọng số đã tải sẽ không bị ghi đè.
def _init_weights(self, module):
"""Initialize the weights"""
if isinstance(module, Wav2Vec2ForPreTraining):
module.project_hid.reset_parameters()
module.project_q.reset_parameters()Chuyển đổi checkpoint sang Transformers
Checkpoint gốc phải được chuyển đổi thành checkpoint tương thích với Transformers.
Hãy thử tìm một script chuyển đổi có sẵn để sao chép, điều chỉnh và tái sử dụng cho mô hình của bạn!
- Nếu bạn đang chuyển đổi một mô hình từ TensorFlow sang PyTorch, một điểm khởi đầu tốt có thể là script chuyển đổi của BERT.
- Nếu bạn đang chuyển đổi một mô hình từ PyTorch sang PyTorch, một điểm khởi đầu tốt có thể là script chuyển đổi của BART.
Hãy đảm bảo rằng mọi trọng số bắt buộc đều được khởi tạo và in ra tất cả các trọng số checkpoint chưa được sử dụng để khởi tạo nhằm xác nhận rằng mô hình đã được chuyển đổi chính xác.
Bạn có thể gặp các phát biểu sai về shape hoặc gán tên trong quá trình chuyển đổi. Nguyên nhân có thể do các tham số không chính xác trong BrandNewLlamaConfig, kiến trúc sai, lỗi trong phương thức init của cài đặt của bạn, hoặc bạn cần chuyển vị (transpose) một trong các trọng số checkpoint.
Tiếp tục lặp lại phần Điều chỉnh mã mô hình cho đến khi tất cả trọng số checkpoint được nạp đúng. Khi bạn có thể nạp một checkpoint vào mô hình của mình, hãy lưu nó vào một thư mục. Thư mục này phải chứa tệp model.safetensors và tệp config.json.
model.save_pretrained("/path/to/converted/checkpoint/folder")Để hỗ trợ việc chuyển đổi, phần tiếp theo mô tả ngắn gọn cách các mô hình PyTorch lưu trữ và xác định trọng số cũng như tên của các lớp.
Trọng số và tên lớp PyTorch
Việc tạo một mô hình PyTorch cơ bản sẽ giúp ích để hiểu cách tên lớp được định nghĩa và trọng số được khởi tạo.
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)Tên lớp PyTorch được xác định bởi tên thuộc tính lớp của lớp đó (dense, intermediate, layer_norm). Hãy tạo một instance của SimpleModel để điền tất cả các lớp bằng trọng số ngẫu nhiên.
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)
)Các giá trị trọng số của một lớp cụ thể được khởi tạo ngẫu nhiên.
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]]).Trong script chuyển đổi, các trọng số ngẫu nhiên cần được thay thế bằng chính xác các trọng số từ lớp tương ứng trong checkpoint gốc.
# 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)Kiểm tra xem trọng số được khởi tạo ngẫu nhiên và trọng số checkpoint được huấn luyện trước tương ứng có cùng shape và name hay không. Thêm các câu lệnh assert cho shape và in ra tên của các trọng số 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}")Khi hình dạng hoặc tên không khớp, có thể bạn đã gán sai trọng số checkpoint cho một lớp được khởi tạo ngẫu nhiên. Hình dạng không chính xác có thể là do các tham số của BrandNewLlama không khớp hoàn toàn với tham số của mô hình gốc. Tuy nhiên, cũng có thể là do việc triển khai lớp PyTorch yêu cầu phải chuyển vị trọng số trước.
Thực hiện bước truyền thuận
Nếu model được nạp đúng cách, bước tiếp theo cần triển khai là forward pass. Nó nhận một số đầu vào và trả về đầu ra của 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_statesĐừng nản lòng nếu forward pass của bạn không giống hệt với đầu ra của mô hình gốc hoặc nếu nó trả về lỗi. Hãy kiểm tra xem forward pass có gây ra lỗi nào không. Điều này thường xảy ra do kích thước (dimensions) không đúng hoặc do sử dụng sai kiểu dữ liệu (torch.long thay vì torch.float32).
Đầu ra của bạn phải có độ chính xác là 1e-3. Đảm bảo hình dạng đầu ra và giá trị đầu ra là giống hệt nhau. Các lý do phổ biến khiến đầu ra không giống hệt nhau bao gồm:
- Một số lớp không được thêm vào (lớp kích hoạt hoặc kết nối phần dư).
- Ma trận nhúng từ không được liên kết.
- Các embedding vị trí sai được sử dụng vì cài đặt gốc bao gồm một offset.
- Dropout được áp dụng trong quá trình truyền thuận. Sửa lỗi này bằng cách đảm bảo
model.traininglàFalsevà truyềnself.trainingvào torch.nn.functional.dropout.
So sánh bước truyền thẳng (forward pass) của mô hình gốc và cài đặt của bạn để kiểm tra xem có sự khác biệt nào không. Tốt nhất, hãy gỡ lỗi và in ra các đầu ra trung gian của cả hai cài đặt bước truyền thẳng để xác định chính xác vị trí mà cài đặt gốc khác với cài đặt của bạn.
- Hãy đảm bảo rằng
input_idsđược hardcode trong cả hai cài đặt là giống hệt nhau. - Kiểm tra xem đầu ra của phép biến đổi đầu tiên của
input_ids(thường là word embeddings) có giống hệt nhau không, và làm tương tự cho đến lớp cuối cùng.
Bất kỳ sự khác biệt nào giữa hai bản triển khai đều chỉ ra lỗi trong bản triển khai của bạn.
Một trong những chiến lược tốt nhất là thêm nhiều câu lệnh in vào cùng các vị trí trong cả hai bản triển khai, sau đó lần lượt xóa chúng đi khi chúng cho ra các giá trị giống hệt nhau đối với các đầu ra trung gian.
Khi cả hai cài đặt đều tạo ra cùng một kết quả, hãy xác minh rằng các kết quả nằm trong độ chính xác 1e-3.
torch.allclose(original_output, output, atol=1e-3)Đây thường là phần khó khăn nhất trong quy trình. Chúc mừng bạn đã đi được đến đây!
Và nếu bạn bị mắc kẹt hoặc gặp khó khăn ở bước này, đừng ngần ngại nhờ hỗ trợ trên pull request của bạn.
Thêm các bài kiểm tra mô hình
Trong khi mô hình đang hoạt động, bạn vẫn cần thêm các bài kiểm tra để đảm bảo tính tương thích với Transformers. Các bài kiểm tra rất quan trọng vì chúng giúp người dùng hiểu công việc của bạn bằng cách xem xét các bài kiểm tra cụ thể, và vì chúng ngăn chặn việc mô hình của bạn bị lỗi trong tương lai nếu có bất kỳ thay đổi nào.
Cookiecutter đã thêm một tệp kiểm thử cho mô hình của bạn. Chạy tệp kiểm thử bên dưới để đảm bảo tất cả các kiểm thử chung đều đạt.
pytest tests/models/brand_new_llama/test_modeling_brand_new_llama.py
Các bài kiểm thử tích hợp nên được thêm vào trước vì chúng phục vụ cùng mục đích với các script gỡ lỗi mà bạn đã sử dụng trước đó để triển khai mô hình mới trong Transformers. Một mẫu cho các bài kiểm thử mô hình đó, BrandNewLlamaModelIntegrationTests, đã được thêm bởi Cookiecutter và cần được điền đầy đủ. Để đảm bảo bài kiểm thử đạt yêu cầu, hãy chạy lệnh sau.
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
Tất cả các tính năng độc quyền của BrandNewLlama phải được kiểm thử trong một bài kiểm thử riêng dưới BrandNewLlamaModelTester/BrandNewLlamaModelTest. Bài kiểm thử này thường bị bỏ qua, nhưng nó cực kỳ quan trọng vì:
- nó giúp chuyển giao kiến thức bạn đã tích lũy trong quá trình đó cho cộng đồng bằng cách cho thấy các tính năng mới của mô hình hoạt động như thế nào
- các nhà đóng góp trong tương lai có thể nhanh chóng kiểm tra các thay đổi đối với mô hình bằng cách chạy các bài kiểm tra đặc biệt này
Triển khai tokenizer
Chúng tôi khuyến nghị thêm một tokenizer nhanh (PreTrainedTokenizerFast) để mang lại hiệu suất tốt nhất cho người dùng. Bạn có thể thoải mái gắn thẻ @ArthurZucker hoặc @itazap trong PR của mình để được hỗ trợ về cách thêm PreTrainedTokenizerFast.
Khi đã xử lý xong mô hình, đến lúc tập trung vào tokenizer. Tokenizer nên giống hệt hoặc rất giống với một tokenizer hiện có trong Transformers.
Tìm và nạp tệp tokenizer gốc vào cài đặt của bạn. Tạo một script trong kho lưu trữ gốc nhận một chuỗi và trả về input_ids. Pseudocode nên trông tương tự như mã bên dưới.
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)Bạn có thể cần tìm kiếm trong kho lưu trữ gốc để tìm hàm tokenizer chính xác hoặc sửa đổi tokenizer hiện có trong bản sao của kho lưu trữ gốc để chỉ trả về input_ids. Script cho tokenizer của bạn nên trông tương tự như sau.
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_idsKhi cả hai cài đặt đều có cùng input_ids, hãy thêm một tệp kiểm tra tokenizer. Tệp này tương tự như các tệp kiểm tra modeling. Các tệp kiểm tra tokenizer nên chứa một vài bài kiểm tra tích hợp được hardcode.
Triển khai bộ xử lý ảnh
Bộ xử lý ảnh hiện sử dụng kiến trúc dựa trên backend. Backend mặc định là TorchvisionBackend, sử dụng thư viện torchvision và có thể thực hiện xử lý ảnh trên GPU. Một backend thay thế dựa trên PIL/NumPy (PilBackend) cũng được cung cấp. Cả hai backend đều được nhập từ
image_processing_backends. Bạn có thể gắn thẻ @yonigozlan để được hỗ trợ.
Mặc dù ví dụ này không bao gồm bộ xử lý ảnh, bạn có thể cần triển khai một bộ xử lý nếu mô hình của bạn yêu cầu đầu vào là ảnh. Bộ xử lý ảnh chịu trách nhiệm chuyển đổi ảnh sang định dạng phù hợp cho mô hình của bạn. Trước khi triển khai một bộ xử lý mới, hãy kiểm tra xem có thể tái sử dụng bộ xử lý ảnh hiện có trong thư viện Transformers hay không, vì nhiều mô hình chia sẻ các kỹ thuật xử lý ảnh tương tự. Lưu ý rằng bạn cũng có thể sử dụng modular cho các bộ xử lý ảnh để tái sử dụng các thành phần hiện có.
Nếu bạn thực sự cần triển khai một bộ xử lý ảnh mới, mỗi mô hình có hai tệp xử lý:
image_processing_<model>.py: bộ xử lý mặc định dựa trên torchvision (<Model>ImageProcessor), kế thừa từ TorchvisionBackend. File này thay thế cho bộ xử lý “fast” cũ.image_processing_pil_<model>.py: bộ xử lý thay thế dùng PIL/NumPy (<Model>ImageProcessorPil), kế thừa từ PilBackend. File này thay thế cho bộ xử lý “chậm” cũ.
Tệp backend torchvision cũng định nghĩa bất kỳ class kwargs tùy chỉnh nào mà tệp PIL import. Cả hai tệp đều sử dụng decorator @auto_docstring — không thêm docstring class thủ công. Tham khảo IMAGE_PROCESSOR_REFACTORING_GUIDE.md để xem hướng dẫn từng bước và các ví dụ hoàn chỉnh.
Thêm các bài kiểm tra cho bộ xử lý ảnh trong tests/models/your_model_name/test_image_processing_your_model_name.py. Các bài kiểm tra này nên tương tự như các bài kiểm tra dành cho các bộ xử lý ảnh khác và cần xác minh rằng bộ xử lý ảnh xử lý đúng các đầu vào ảnh. Nếu bộ xử lý ảnh của bạn bao gồm các tính năng hoặc phương pháp xử lý độc đáo, hãy đảm bảo thêm các bài kiểm tra cụ thể cho chúng.
Thực hiện bộ xử lý
Nếu mô hình của bạn nhận vào nhiều chế độ dữ liệu (modality), chẳng hạn như văn bản và hình ảnh, bạn cần thêm một bộ xử lý (processor). Bộ xử lý tập trung hóa việc tiền xử lý các chế độ dữ liệu khác nhau trước khi truyền chúng vào mô hình.
Bộ xử lý nên gọi các bộ xử lý riêng cho từng phương thức (modality) tương ứng bên trong hàm __call__ của nó để xử lý đúng từng loại đầu vào. Hãy chắc chắn kiểm tra các bộ xử lý hiện có trong thư viện để hiểu cấu trúc mong đợi của chúng. Transformers sử dụng quy ước sau trong chữ ký hàm __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 là một TypedDict bao gồm tất cả các đối số xử lý thông thường và bất kỳ đối số bổ sung nào mà một bộ xử lý cụ thể có thể yêu cầu.
Thêm các bài kiểm tra cho processor trong tests/models/your_model_name/test_processor_your_model_name.py. Các bài kiểm tra này nên tương tự như các bài kiểm tra cho các processor khác và cần xác minh rằng processor xử lý chính xác các modalities khác nhau.
Kiểm thử tích hợp
Bây giờ bạn đã có model và tokenizer, hãy thêm các bài kiểm tra tích hợp end-to-end cho model và tokenizer vào tests/models/brand_new_llama/test_modeling_brand_new_llama.py.
Bài kiểm tra nên cung cấp một ví dụ text-to-text có ý nghĩa để cho thấy mô hình hoạt động như mong đợi. Ví dụ, bạn có thể bao gồm một cặp dịch từ nguồn sang đích, một cặp bài viết sang tóm tắt, hoặc một cặp câu hỏi sang câu trả lời.
Nếu checkpoint chưa được tinh chỉnh trên một tác vụ hạ nguồn, thì các bài kiểm tra mô hình là đủ.
Cuối cùng, hãy cố gắng đảm bảo các bài kiểm tra của bạn có thể chạy trên GPU bằng cách thêm các câu lệnh .to(self.device) vào các tensor bên trong của mô hình. Nếu bạn không có quyền truy cập vào GPU, chúng tôi có thể xử lý điều đó cho bạn.
Thêm tài liệu
Mô hình của bạn chỉ thực sự hữu ích khi người dùng biết cách sử dụng nó. Đó là lý do tại sao việc thêm tài liệu và docstring là rất quan trọng. Cookiecutter đã thêm một tệp mẫu, docs/source/model_doc/brand_new_llama.md, để bạn điền thông tin về mô hình của mình.
Đây thường là tương tác đầu tiên của người dùng với một mô hình, vì vậy tài liệu nên rõ ràng và ngắn gọn. Việc bổ sung các ví dụ về cách sử dụng mô hình thường rất hữu ích.
Hãy đảm bảo rằng các docstring được thêm vào src/transformers/models/brand_new_llama/modeling_brand_new_llama.py và bao gồm tất cả các đầu vào và đầu ra cần thiết. Xem hướng dẫn của chúng tôi về cách viết tài liệu và docstring.
Tái cấu trúc
Đã đến lúc dọn dẹp và đảm bảo phong cách mã nhất quán với phần còn lại của thư viện. Chạy lệnh sau để tự động sửa các lỗi phong cách.
make style
Để xác nhận rằng mã nguồn đáp ứng các kiểm tra chất lượng về phong cách, hãy chạy lệnh bên dưới.
make check-repo
Có thể có các bài kiểm tra hoặc bước kiểm tra khác bị lỗi (thiếu docstring hoặc đặt tên không chính xác) trong pull request của bạn do các bài kiểm tra thiết kế nghiêm ngặt của Transformers. Chúng tôi có thể hỗ trợ bạn xử lý các vấn đề này nếu bạn gặp khó khăn.
Sau khi đảm bảo mã chạy chính xác, bạn có thể muốn tái cấu trúc nó để dễ đọc hơn hoặc gọn gàng hơn.
Tải lên Hub
Chuyển đổi và tải lên tất cả các checkpoint lên Hub. Thêm model card để cung cấp thêm sự minh bạch và ngữ cảnh về mô hình. Model card nên làm nổi bật các đặc điểm cụ thể của một checkpoint, cách mô hình được huấn luyện, và các ví dụ mã nguồn về cách sử dụng nó.
Trong nhiều trường hợp, việc thêm một notebook tương tác mà người dùng có thể chạy là một cách tuyệt vời để giới thiệu cách sử dụng mô hình cho suy luận hoặc tinh chỉnh nó trên một tác vụ hạ nguồn. Mặc dù không bắt buộc, việc bao gồm một notebook có thể thúc đẩy việc áp dụng mô hình của bạn nhiều hơn.
Bạn cũng nên tham khảo ý kiến của nhóm Transformers để quyết định tên phù hợp cho mô hình và xin các quyền truy cập cần thiết để tải mô hình lên.
Sử dụng phương thức push_to_hub() để tải lên mô hình.
brand_new_bert.push_to_hub("brand_new_llama")Tham khảo hướng dẫn Chia sẻ để biết thêm thông tin về việc tải các mô hình lên Hub.
Gộp mô hình của bạn
Bạn cuối cùng cũng đã sẵn sàng để hợp nhất pull request của mình và chính thức thêm mô hình vào Transformers! Hãy đảm bảo rằng tất cả các bài kiểm tra đều đạt và mọi bình luận cũng như phản hồi đều đã được xử lý.
Chúc mừng bạn đã thêm một mô hình mới vào Transformers! 🥳
Đây là một đóng góp vô cùng ý nghĩa. Công việc của bạn giúp Transformers trở nên dễ tiếp cận hơn với các nhà phát triển và nhà nghiên cứu trên toàn thế giới. Bạn nên tự hào về đóng góp của mình và chia sẻ thành tựu này với cộng đồng!
Xem thêm
- Quy tắc cấu trúc mô hình — các quy tắc tĩnh được áp dụng cho tất cả các tệp
modeling_*.pyvàconfiguration_*.py. Chạymake typingđể kiểm tra chúng trước khi mở PR. - Các kiểm tra pull request — tài liệu tham khảo đầy đủ về các kiểm tra CI được chạy trên PR của bạn và cách để vượt qua chúng.