Transformers documentation
Tự động tạo docstring
Tự động tạo docstring
Trình trang trí @auto_docstring tạo ra các docstring nhất quán cho các lớp và phương thức của model. Nó tự động lấy các mô tả tham số chuẩn, vì vậy bạn chỉ cần viết tài liệu cho các tham số mới hoặc tùy chỉnh. Khi thêm một model mới, hãy bỏ qua các phần lặp lại và tập trung vào những gì mới.
@auto_docstring
Nhập decorator trong tệp modular_model.py của bạn (hoặc modeling_model.py đối với các model cũ hơn).
from ...utils import auto_docstringNếu model của bạn kế thừa từ một model của thư viện khác trong một file modular, @auto_docstring đã được áp dụng trong class cha. make fix-repo sẽ sao chép nó vào file modeling_model.py được tạo ra cho bạn. Chỉ cần áp dụng decorator một cách tường minh để tùy chỉnh hành vi của nó (các model độc lập, custom intros, hoặc các argument bị ghi đè).
Khi ghi đè bất kỳ decorator nào trong một file modular, hãy bao gồm tất cả các decorator từ hàm hoặc lớp cha. Nếu bạn chỉ ghi đè một số, phần còn lại sẽ không xuất hiện trong file modeling được tạo ra.
Trình trang trí chấp nhận các đối số tùy chọn sau:
| tham số | mô tả |
|---|---|
custom_intro | Mô tả lớp hoặc phương thức, được chèn vào trước phần Args. Bắt buộc đối với các lớp không kết thúc bằng hậu tố được công nhận như ForCausalLM hoặc ForTokenClassification. |
custom_args | Văn bản docstring cho các tham số cụ thể. Hữu ích khi cùng một tập hợp các đối số tùy chỉnh xuất hiện ở nhiều vị trí khác nhau trong tệp modeling. |
checkpoint | Một định danh checkpoint mô hình ("org/my-model") được sử dụng để tạo các ví dụ sử dụng. Ghi đè checkpoint được suy luận tự động từ lớp cấu hình. Thường được đặt trên các lớp cấu hình. |
Cách sử dụng
Cách @auto_docstring hoạt động phụ thuộc vào đối tượng bạn đang trang trí. Các lớp Model lấy tài liệu tham số từ __init__, các lớp config lấy từ các chú thích ở cấp lớp, các lớp processor tự động tạo mô tả từ các thành phần của chúng, và các phương thức như forward sẽ nhận được kiểu trả về cùng các ví dụ sử dụng.
Các lớp mô hình
Đặt @auto_docstring ngay phía trên định nghĩa lớp. Bộ trang trí này suy ra mô tả tham số từ chữ ký và docstring của phương thức __init__.
from transformers.modeling_utils import PreTrainedModel
from ...utils import auto_docstring
@auto_docstring
class MyAwesomeModel(PreTrainedModel):
def __init__(self, config, custom_parameter: int = 10, another_custom_arg: str = "default"):
r"""
custom_parameter (`int`, *optional*, defaults to 10):
Description of the custom_parameter for MyAwesomeModel.
another_custom_arg (`str`, *optional*, defaults to "default"):
Documentation for another unique argument.
"""
super().__init__(config)
self.custom_parameter = custom_parameter
self.another_custom_arg = another_custom_arg
# ... rest of your init
# ... other methodsTruyền custom_intro và custom_args để có thêm quyền kiểm soát. Các đối số tùy chỉnh có thể đặt trong custom_args hoặc trong docstring của __init__. Sử dụng custom_args khi cùng một tập hợp đối số lặp lại ở nhiều phương thức khác nhau.
@auto_docstring(
custom_intro="""This model performs specific synergistic operations.
It builds upon the standard Transformer architecture with unique modifications.""",
custom_args="""
custom_parameter (`type`, *optional*, defaults to `default_value`):
A concise description for custom_parameter if not defined or overriding the description in `auto_docstring.py`.
internal_helper_arg (`type`, *optional*, defaults to `default_value`):
A concise description for internal_helper_arg if not defined or overriding the description in `auto_docstring.py`.
"""
)
class MySpecialModel(PreTrainedModel):
def __init__(self, config: ConfigType, custom_parameter: "type" = "default_value", internal_helper_arg=None):
# ...Cũng áp dụng @auto_docstring cho các lớp kế thừa từ ModelOutput.
@auto_docstring(
custom_intro="""
Custom model outputs with additional fields.
"""
)
@dataclass
class MyModelOutput(ImageClassifierOutput):
r"""
loss (`torch.Tensor`, *optional*):
The loss of the model.
custom_field (`torch.Tensor` of shape `(batch_size, hidden_size)`, *optional*):
A custom output field specific to this model.
"""
# Standard fields (hidden_states, logits, attentions, etc.) are documented automatically when
# the description matches the standard text. Loss typically varies per model, so document it above.
loss: Optional[torch.Tensor] = None
logits: Optional[torch.Tensor] = None
hidden_states: Optional[tuple[torch.Tensor, ...]] = None
attentions: Optional[tuple[torch.Tensor, ...]] = None
# Custom fields need to be documented in the docstring above
custom_field: Optional[torch.Tensor] = NoneCác lớp cấu hình
Đặt @auto_docstring ngay phía trên một lớp con của PreTrainedConfig, cùng với decorator @strict. @strict thêm vào việc kiểm tra kiểu dữ liệu lúc runtime và biến lớp thành một dataclass đã được kiểm chứng. Các tham số cấu hình là ghi chú kiểu ở cấp lớp (không phải các đối số của __init__), và @auto_docstring đọc chúng từ thân lớp để tạo tài liệu.
ConfigArgs cung cấp các tham số chuẩn như vocab_size, hidden_size và num_hidden_layers, do đó chúng không cần mô tả trừ khi hành vi khác đi. Các tham số cơ sở của PreTrainedConfig được loại bỏ tự động. Đối số checkpoint tạo ra ví dụ sử dụng.
from huggingface_hub.dataclasses import strict
from ...configuration_utils import PreTrainedConfig
from ...utils import auto_docstring
@strict
@auto_docstring(checkpoint="org/my-model-checkpoint")
class MyModelConfig(PreTrainedConfig):
r"""
custom_param (`int`, *optional*, defaults to 64):
Description of a parameter specific to this model.
another_param (`str`, *optional*, defaults to `"gelu"`):
Description of another model-specific parameter.
```python
from transformers import MyModelConfig, MyModel
configuration = MyModelConfig()
model = MyModel(configuration)
configuration = model.config
```
"""
model_type = "my_model"
# Standard params (vocab_size, hidden_size, etc.) are auto-documented from ConfigArgs.
vocab_size: int = 32000
hidden_size: int = 768
num_hidden_layers: int = 12
# Model-specific params must be documented in the class docstring above.
custom_param: int = 64
another_param: str = "gelu"Các lớp Processor
Bộ xử lý đa phương thức (các lớp con của ProcessorMixin, processing_*.py) luôn sử dụng @auto_docstring thuần. Phần giới thiệu lớp được tạo tự động. Chỉ tài liệu hóa các tham số của __init__ chưa được bao phủ bởi ProcessorArgs (image_processor, tokenizer, chat_template, và các tham số khác).
Nếu mọi tham số đều là chuẩn, hãy bỏ qua docstring. Trang trí __call__ bằng @auto_docstring cũng vậy. Docstring thân của nó chỉ chứa một phần Returns: cùng bất kỳ đối số gọi cụ thể nào của mô hình. return_tensors được thêm vào tự động.
from ...processing_utils import ProcessorMixin, ProcessingKwargs, Unpack
from ...utils import auto_docstring
class MyModelProcessorKwargs(ProcessingKwargs, total=False):
"""
custom_call_kwarg (`bool`, *optional*, defaults to `False`):
A parameter with a default that can passed to __call__ which is not
covered by the standard processor arguments (including each modality).
"""
custom_call_kwarg: bool
@auto_docstring
class MyModelProcessor(ProcessorMixin):
valid_processor_kwargs = MyModelProcessorKwargs
custom_call_kwarg = False
def __init__(self, image_processor=None, tokenizer=None, custom_param: int = 4, **kwargs):
r"""
custom_param (`int`, *optional*, defaults to 4):
A parameter specific to this processor not covered by the standard ProcessorArgs.
"""
super().__init__(image_processor, tokenizer)
self.custom_param = custom_param
@auto_docstring
def __call__(self, images=None, text=None, **kwargs: Unpack[MyModelProcessorKwargs]):
r"""
Returns:
[BatchFeature](/docs/transformers/v5.23.0/en/main_classes/feature_extractor#transformers.BatchFeature): A [BatchFeature](/docs/transformers/v5.23.0/en/main_classes/feature_extractor#transformers.BatchFeature) with the following fields:
- **input_ids** -- Token ids to be fed to the model.
- **pixel_values** -- Pixel values to be fed to the model.
"""
# ...Bộ xử lý hình ảnh và video
Bộ xử lý hình ảnh và video (các lớp con của BaseImageProcessor, image_processing_*.py) tuân theo một trong hai mẫu.
Nếu bộ xử lý có các tham số cụ thể cho mô hình, hãy định nghĩa một TypedDict XxxImageProcessorKwargs(ImagesKwargs, total=False) với docstring cho các tham số đó, đặt valid_kwargs trên lớp và sử dụng @auto_docstring trần. __init__ không có docstring.
class MyModelImageProcessorKwargs(ImagesKwargs, total=False):
r"""
custom_threshold (`float`, *optional*, defaults to `self.custom_threshold`):
A parameter specific to this image processor.
"""
custom_threshold: float | None
@auto_docstring
class MyModelImageProcessor(TorchvisionBackend):
valid_kwargs = MyModelImageProcessorKwargs
custom_threshold: float = 0.5
def __init__(self, **kwargs: Unpack[MyModelImageProcessorKwargs]):
super().__init__(**kwargs)Nếu lớp chỉ đặt các thuộc tính cấp lớp chuẩn (size, resample, image_mean, v.v.) mà không có kwargs tùy chỉnh nào, hãy dùng @auto_docstring(custom_intro="Constructs a MyModel image processor.") thay thế.
@auto_docstring(custom_intro="Constructs a MyModel image processor.")
class MyModelImageProcessor(TorchvisionBackend):
resample = PILImageResampling.BICUBIC
image_mean = IMAGENET_STANDARD_MEAN
image_std = IMAGENET_STANDARD_STD
size = {"height": 224, "width": 224}Khi ghi đè preprocess, hãy trang trí nó bằng @auto_docstring và chỉ tài liệu hóa các đối số không có trong ImageProcessorArgs. Các đối số chuẩn và return_tensors sẽ được bao gồm tự động.
Hàm
Đặt @auto_docstring ngay phía trên định nghĩa hàm. Bộ trang trí này suy ra mô tả tham số từ chữ ký của hàm.
Trình trang trí tạo ra văn bản giá trị trả về từ docstring của lớp ModelOutput.
class MyModel(PreTrainedModel):
# ...
@auto_docstring
def forward(
self,
input_ids: Optional[torch.Tensor] = None,
attention_mask: Optional[torch.Tensor] = None,
new_custom_argument: Optional[torch.Tensor] = None,
# ... other arguments
) -> Union[Tuple, ModelOutput]:
r"""
new_custom_argument (`torch.Tensor`, *optional*):
Description of this new custom argument and its expected shape or type.
"""
# ...Truyền custom_intro và custom_args để có thêm quyền kiểm soát. Sử dụng custom_args để định nghĩa tài liệu cho các tham số dùng chung một lần khi cùng một tập tham số xuất hiện trong nhiều phương thức.
MODEL_COMMON_CUSTOM_ARGS = r"""
common_arg_1 (`torch.Tensor`, *optional*, defaults to `default_value`):
Description of common_arg_1
common_arg_2 (`torch.Tensor`, *optional*, defaults to `default_value`):
Description of common_arg_2
"""
class MyModel(PreTrainedModel):
# ...
@auto_docstring(
custom_intro="""This is a custom introduction for the function.""",
custom_args=MODEL_COMMON_CUSTOM_ARGS
)
def forward(self, input_ids=None, common_arg_1=None, common_arg_2=None) -> ModelOutput:
r"""method-specific args go here"""
# ...Viết các phần Returns và Examples thủ công trong docstring để ghi đè các phiên bản được tạo tự động.
def forward(self, input_ids=None) -> torch.Tensor:
r"""
Returns:
`torch.Tensor`: A custom Returns section for non-ModelOutput return types.
Example:
```python
model = MyModel.from_pretrained("org/my-model")
output = model(input_ids)
```
"""
# ...Tài liệu hóa các đối số
Tuân theo các quy tắc sau khi tài liệu hóa các kiểu đối số khác nhau.
auto_docstring.pyđịnh nghĩa các đối số chuẩn (input_ids,attention_mask,pixel_values, v.v.) và tự động bao gồm chúng. Không định nghĩa lại chúng cục bộ trừ khi đối số hoạt động khác trong mô hình của bạn.Nếu một đối số chuẩn hoạt động khác đi trong model của bạn, hãy ghi đè cục bộ trong khối
r""" """. Định nghĩa cục bộ có độ ưu tiên cao hơn. Ví dụ, đối sốlabelsthường được tùy chỉnh riêng cho từng model và thường cần được ghi đè.Các đối số cấu hình chuẩn (
vocab_size,hidden_size,num_hidden_layers, v.v.) tuân theo cùng một nguyên tắc nhưng được lấy từConfigArgs. Các đối số bộ xử lý chuẩn (image_processor,tokenizer,do_resize,return_tensors, v.v.) được lấy từProcessorArgsvàImageProcessorArgs. Chỉ tài liệu hóa một tham số nếu nó đặc thù cho mô hình hoặc có hành vi khác so với mô tả chuẩn.Tài liệu hóa các đối số mới hoặc tùy chỉnh trong khối
r""" """. Đặt chúng sau chữ ký đối với các hàm, trong docstring của__init__đối với các lớp model hoặc processor, trong docstring thân lớp đối với các lớp config, hoặc trong thân TypedDictXxxImageProcessorKwargsđối với các image processor.argument_name (`type`, *optional*, defaults to `X`): Description of the argument. Explain its purpose, expected shape/type if complex, and default behavior. This can span multiple lines.- Bao gồm
typetrong dấu backtick. - Thêm optional nếu đối số không bắt buộc hoặc có giá trị mặc định.
- Thêm “mặc định là X” nếu nó có giá trị mặc định. Bạn không cần thêm “mặc định là
None” nếu giá trị mặc định làNone. - Truyền cùng một khối vào
custom_argskhi cùng các đối số lặp lại qua nhiều phương thức (xem ví dụ về Functions ở trên).
- Bao gồm
Trình trang trí (decorator) tự động trích xuất các kiểu dữ liệu từ chữ ký của hàm. Nếu một tham số có chú thích kiểu dữ liệu, bạn không cần lặp lại kiểu đó trong chuỗi định dạng của docstring. Khi cả hai đều có mặt, kiểu dữ liệu trong chữ ký sẽ được ưu tiên. Kiểu dữ liệu trong docstring đóng vai trò là phương án dự phòng cho các tham số không có chú thích.
Kiểm tra các docstring
Một script tiện ích xác thực docstring khi bạn mở một pull request. CI chạy script và kiểm tra các mục sau.
Nếu bạn thấy
[ERROR]trong đầu ra, hãy thêm mô tả của tham số vào docstring hoặc lớp Args phù hợp trongauto_docstring.py.
- Kiểm tra xem
@auto_docstringcó được áp dụng cho các lớp model và phương thức công khai liên quan hay không. - Kiểm tra tính đầy đủ và nhất quán của các đối số: các đối số được tài liệu hóa phải tồn tại trong chữ ký, và kiểu dữ liệu cùng giá trị mặc định phải khớp. Các đối số không xác định mà không có mô tả cục bộ sẽ được đánh dấu.
- Đánh dấu các placeholder chưa hoàn chỉnh như
<fill_type>và<fill_docstring>. - Kiểm tra xem các docstring có tuân theo phong cách định dạng mong đợi hay không.
Chạy kiểm tra cục bộ trước khi cam kết.
make fix-repo
make fix-repo cũng chạy một số kiểm tra khác. Để chỉ chạy các kiểm tra docstring và auto-docstring, hãy sử dụng lệnh bên dưới.
# to only check files included in the diff without fixing them
python utils/check_docstrings.py
# to fix and overwrite the files in the diff
# python utils/check_docstrings.py --fix_and_overwrite
# to fix and overwrite all files
# python utils/check_docstrings.py --fix_and_overwrite --check_allDanh sách kiểm tra tham khảo nhanh
| Làm | Đừng |
|---|---|
Áp dụng @auto_docstring cho các lớp model, config và processor cùng các phương thức chính của chúng (forward, __call__, preprocess). | Thêm @auto_docstring vào các model kế thừa trong các file modular vì nó được kế thừa tự động. |
| Chỉ tài liệu hóa các đối số mới hoặc các đối số cụ thể cho mô hình. | Định nghĩa lại các đối số chuẩn (input_ids, attention_mask, vocab_size, v.v.) có hành vi giống như mô tả mặc định của chúng. |
| Đặt các tham số cấu hình trong docstring của thân lớp dưới dạng chú thích cấp lớp. | Đặt các tham số cấu hình trong __init__. |
Đặt các tham số bộ xử lý ảnh vào một TypedDict XxxImageProcessorKwargs. | Đặt các tham số bộ xử lý ảnh trong __init__. |
Chạy python utils/check_docstrings.py --fix_and_overwrite trước khi commit. | Bỏ qua đầu ra [ERROR] vì nó có nghĩa là một tham số chưa được tài liệu hóa. |
Cách hoạt động
Trình trang trí @auto_docstring tạo ra các docstring thông qua các bước sau.
Trình trang trí kiểm tra chữ ký để đọc các đối số, kiểu dữ liệu và giá trị mặc định từ
__init__của lớp được trang trí hoặc từ hàm được trang trí. Đối với các lớp cấu hình, nó duyệt qua các chú thích ở cấp độ lớp dọc theo chuỗi kế thừa và dừng lại trước PreTrainedConfig, loại trừ các trường của lớp cơ sở.Nó tự động lọc ra các tham số như
self,kwargs,args,deprecated_argumentsvà các tên có tiền tố_. Một số tham số riêng tư được đổi tên thành tương đương công khai của chúng (_out_features→out_featuresđối với các mô hình backbone).Mô tả các đối số phổ biến được lấy từ
auto_docstring.py:ModelArgs(đầu vào của model),ModelOutputArgs(các trường đầu ra nhưhidden_states),ImageProcessorArgs(tiền xử lý ảnh),ProcessorArgs(các thành phần của processor đa phương tiện) vàConfigArgs(các siêu tham số cấu hình).Mô tả của từng tham số tuân theo chuỗi ưu tiên sau:
- Docstring thủ công (
r""" """block hoặccustom_args) có độ ưu tiên cao hơn. - Từ điển nguồn được định nghĩa trước (
ModelArgs,ModelForArgs,ConfigArgs,ImageProcessorArgs,ProcessorArgs,ModelOutputArgs) là phương án dự phòng. - Nếu cả hai nguồn đều không có mô tả, tham số sẽ được đánh dấu bằng
[ERROR]trong kết quả build.
- Docstring thủ công (
Đối với các lớp mô hình có tên chuẩn như
ModelForCausalLM, hoặc các lớp được ánh xạ tới một pipeline,@auto_docstringsẽ tạo phần giới thiệu. Đối với các bộ xử lý đa phương thức, phần giới thiệu sẽ liệt kê các thành phần (tokenizer, image processor, v.v.) mà lớp đó bao bọc. Xem ClassDocstring để biết danh sách đầy đủ.Nếu tên lớp không có trong
ClassDocstring, hãy đặtcustom_intro.Docstring được định nghĩa sẵn có thể tham chiếu các giá trị động từ auto_modules của Transformers, chẳng hạn như
{processor_class},{image_processor_class}và{config_class}. Các placeholder sẽ được tự động phân giải.Trình trang trí (decorator) chọn các ví dụ sử dụng dựa trên tác vụ hoặc khả năng tương thích pipeline của mô hình. Nó đọc metadata checkpoint từ lớp cấu hình để các ví dụ sử dụng các ID mô hình thực. Đối số
checkpointghi đè lên checkpoint được suy ra từ docstring của lớp cấu hình. Đặtcheckpointtrên các lớp cấu hình, hoặc khi việc suy luận checkpoint thất bại. Nếu bạn thấy lỗi như"Config not found for <model_name>", hãy thêm một mục vàoHARDCODED_CONFIG_FOR_MODELStrongauto_docstring.py.Đối với các phương thức như
forward, decorator sẽ viết phầnReturnstừ kiểu trả về của phương thức. Khi kiểu trả về là một lớp con của ModelOutput,@auto_docstringsẽ lấy mô tả các trường từ docstring của lớp đó. KhốiReturnstùy chỉnh trong docstring của hàm sẽ có quyền ưu tiên cao hơn.Đối với các phương thức trong
UNROLL_KWARGS_METHODSvà các lớp trongUNROLL_KWARGS_CLASSES, bộ trang trí sẽ mở rộng**kwargsđược đánh kiểu bằngUnpack[KwargsTypedDict]. Mỗi khóa từTypedDictsẽ trở thành một tham số được tài liệu hóa.Cùng sự mở rộng này được áp dụng cho các phương thức
__call__vàpreprocesstrên các lớp con của BaseImageProcessor và ProcessorMixin. Các kiểu cơ sở chung (TextKwargs,ImagesKwargs,VideosKwargs,AudioKwargs) bị bỏ qua. Chỉ các lớp con cụ thể cho từng model mới được mở rộng.