Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / transformers /main /en /auto_docstring.html

HuggingFaceDocBuilder

about 11 hours ago

download

raw

69.8 kB

	<meta charset="utf-8" /><meta name="hf:doc:metadata" content="{"title":"Auto-generating docstrings","local":"auto-generating-docstrings","sections":[{"title":"@auto_docstring","local":"autodocstring","sections":[],"depth":2},{"title":"Usage","local":"usage","sections":[{"title":"Model classes","local":"model-classes","sections":[],"depth":3},{"title":"Config classes","local":"config-classes","sections":[],"depth":3},{"title":"Processor classes","local":"processor-classes","sections":[{"title":"Image and video processors","local":"image-and-video-processors","sections":[],"depth":4}],"depth":3},{"title":"Functions","local":"functions","sections":[],"depth":3},{"title":"Documenting arguments","local":"documenting-arguments","sections":[],"depth":3}],"depth":2},{"title":"Checking the docstrings","local":"checking-the-docstrings","sections":[],"depth":2},{"title":"Quick-reference checklist","local":"quick-reference-checklist","sections":[],"depth":2},{"title":"How it works","local":"how-it-works","sections":[],"depth":2}],"depth":1}">
	<link href="/docs/transformers/main/en/_app/immutable/assets/0.e3b0c442.css" rel="modulepreload">
	<link rel="modulepreload" href="/docs/transformers/main/en/_app/immutable/entry/start.3d6cca8a.js">
	<link rel="modulepreload" href="/docs/transformers/main/en/_app/immutable/chunks/scheduler.31fdf58d.js">
	<link rel="modulepreload" href="/docs/transformers/main/en/_app/immutable/chunks/singletons.6af0ff6e.js">
	<link rel="modulepreload" href="/docs/transformers/main/en/_app/immutable/chunks/index.252883d5.js">
	<link rel="modulepreload" href="/docs/transformers/main/en/_app/immutable/chunks/paths.299a376b.js">
	<link rel="modulepreload" href="/docs/transformers/main/en/_app/immutable/entry/app.b6ccab0d.js">
	<link rel="modulepreload" href="/docs/transformers/main/en/_app/immutable/chunks/preload-helper.c438fa0a.js">
	<link rel="modulepreload" href="/docs/transformers/main/en/_app/immutable/chunks/index.2f76fdf0.js">
	<link rel="modulepreload" href="/docs/transformers/main/en/_app/immutable/nodes/0.f2629ed0.js">
	<link rel="modulepreload" href="/docs/transformers/main/en/_app/immutable/chunks/each.e59479a4.js">
	<link rel="modulepreload" href="/docs/transformers/main/en/_app/immutable/nodes/10.3208e115.js">
	<link rel="modulepreload" href="/docs/transformers/main/en/_app/immutable/chunks/CopyLLMTxtMenu.ad38f6ea.js">
	<link rel="modulepreload" href="/docs/transformers/main/en/_app/immutable/chunks/MermaidChart.svelte_svelte_type_style_lang.fd2f7a8a.js">
	<link rel="modulepreload" href="/docs/transformers/main/en/_app/immutable/chunks/IconCopy.ac192424.js">
	<link rel="modulepreload" href="/docs/transformers/main/en/_app/immutable/chunks/CodeBlock.e52df5d6.js"><!-- HEAD_svelte-u9bgzb_START --><meta name="hf:doc:metadata" content="{"title":"Auto-generating docstrings","local":"auto-generating-docstrings","sections":[{"title":"@auto_docstring","local":"autodocstring","sections":[],"depth":2},{"title":"Usage","local":"usage","sections":[{"title":"Model classes","local":"model-classes","sections":[],"depth":3},{"title":"Config classes","local":"config-classes","sections":[],"depth":3},{"title":"Processor classes","local":"processor-classes","sections":[{"title":"Image and video processors","local":"image-and-video-processors","sections":[],"depth":4}],"depth":3},{"title":"Functions","local":"functions","sections":[],"depth":3},{"title":"Documenting arguments","local":"documenting-arguments","sections":[],"depth":3}],"depth":2},{"title":"Checking the docstrings","local":"checking-the-docstrings","sections":[],"depth":2},{"title":"Quick-reference checklist","local":"quick-reference-checklist","sections":[],"depth":2},{"title":"How it works","local":"how-it-works","sections":[],"depth":2}],"depth":1}"><!-- HEAD_svelte-u9bgzb_END --> <p></p> <div class="items-center shrink-0 min-w-[100px] max-sm:min-w-[50px] justify-end ml-auto flex" style="float: right; margin-left: 10px; display: inline-flex; position: relative; z-index: 10;"><div class="inline-flex rounded-md max-sm:rounded-sm"><button class="inline-flex items-center gap-1 h-7 max-sm:h-7 px-2 max-sm:px-1.5 text-sm font-medium text-gray-800 border border-r-0 rounded-l-md max-sm:rounded-l-sm border-gray-200 bg-white hover:shadow-inner dark:border-gray-850 dark:bg-gray-950 dark:text-gray-200 dark:hover:bg-gray-800" aria-live="polite"><span class="inline-flex items-center justify-center rounded-md p-0.5 max-sm:p-0 hover:text-gray-800 dark:hover:text-gray-200"><svg class="sm:size-3.5 size-3" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg></span> <span>Copy page</span></button> <button class="inline-flex items-center justify-center w-6 max-sm:w-5 h-7 max-sm:h-7 disabled:pointer-events-none text-sm text-gray-500 hover:text-gray-700 dark:hover:text-white rounded-r-md max-sm:rounded-r-sm border border-l transition border-gray-200 bg-white hover:shadow-inner dark:border-gray-850 dark:bg-gray-950 dark:text-gray-200 dark:hover:bg-gray-800" aria-haspopup="menu" aria-expanded="false" aria-label="Open copy menu"><svg class="transition-transform text-gray-400 overflow-visible sm:size-3.5 size-3 rotate-0" width="1em" height="1em" viewBox="0 0 12 7" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M1 1L6 6L11 1" stroke="currentColor"></path></svg></button></div> </div> <h1 class="relative group"><a id="auto-generating-docstrings" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#auto-generating-docstrings"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Auto-generating docstrings</span></h1> <p data-svelte-h="svelte-fgagjt">The <code>@auto_docstring</code> decorator generates consistent docstrings for model classes and methods. It pulls in standard argument descriptions automatically, so you only write documentation for new or custom arguments. When <a href="./modular_transformers">adding a new model</a>, skip the boilerplate and focus on what’s new.</p> <h2 class="relative group"><a id="autodocstring" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#autodocstring"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>@auto_docstring</span></h2> <p data-svelte-h="svelte-ym560z">Import the decorator in your <code>modular_model.py</code> file (or <code>modeling_model.py</code> for older models).</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class="language-python "><!-- HTML_TAG_START --><span class="hljs-keyword">from</span> ...utils <span class="hljs-keyword">import</span> auto_docstring<!-- HTML_TAG_END --></pre></div> <p data-svelte-h="svelte-1j6be2b">If your model inherits from another library model in a modular file, <code>@auto_docstring</code> is already applied in the parent. <code>make fix-repo</code> copies it into the generated <code>modeling_model.py</code> file for you. Only apply the decorator explicitly to customize its behavior (standalone models, custom intros, or overridden arguments).</p> <blockquote class="warning" data-svelte-h="svelte-k3jpqb"><p>When overriding any decorator in a modular file, include <strong>all</strong> decorators from the parent function or class. If you only override some, the rest won’t appear in the generated modeling file.</p></blockquote> <p data-svelte-h="svelte-24hc9d">The decorator accepts the following optional arguments:</p> <table data-svelte-h="svelte-1fugs8r"><thead><tr><th>argument</th> <th>description</th></tr></thead> <tbody><tr><td><code>custom_intro</code></td> <td>A description of the class or method, inserted before the Args section. Required for classes that don’t end with a <a href="#how-it-works">recognized suffix</a> like <code>ForCausalLM</code> or <code>ForTokenClassification</code>.</td></tr> <tr><td><code>custom_args</code></td> <td>Docstring text for specific parameters. Useful when the same custom arguments appear in several places in the modeling file.</td></tr> <tr><td><code>checkpoint</code></td> <td>A model checkpoint identifier (<code>"org/my-model"</code>) used to generate usage examples. Overrides the checkpoint auto-inferred from the config class. Typically set on config classes.</td></tr></tbody></table> <h2 class="relative group"><a id="usage" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#usage"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Usage</span></h2> <p data-svelte-h="svelte-1uadcgo">How <code>@auto_docstring</code> works depends on what you’re decorating. Model classes pull parameter docs from <code>__init__</code>, config classes pull from class-level annotations, processor classes auto-generate intros from their components, and methods like <code>forward</code> get return types and usage examples.</p> <h3 class="relative group"><a id="model-classes" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#model-classes"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Model classes</span></h3> <p data-svelte-h="svelte-1948oup">Place <code>@auto_docstring</code> directly above the class definition. The decorator derives parameter descriptions from the <code>__init__</code> method’s signature and docstring.</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class="language-python "><!-- HTML_TAG_START --><span class="hljs-keyword">from</span> transformers.modeling_utils <span class="hljs-keyword">import</span> PreTrainedModel
	<span class="hljs-keyword">from</span> ...utils <span class="hljs-keyword">import</span> auto_docstring

	<span class="hljs-meta">@auto_docstring</span>
	<span class="hljs-keyword">class</span> <span class="hljs-title class_">MyAwesomeModel</span>(<span class="hljs-title class_ inherited__">PreTrainedModel</span>):
	<span class="hljs-keyword">def</span> <span class="hljs-title function_">__init__</span>(<span class="hljs-params">self, config, custom_parameter: <span class="hljs-built_in">int</span> = <span class="hljs-number">10</span>, another_custom_arg: <span class="hljs-built_in">str</span> = <span class="hljs-string">"default"</span></span>):
	<span class="hljs-string">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.
	"""</span>
	<span class="hljs-built_in">super</span>().__init__(config)
	self.custom_parameter = custom_parameter
	self.another_custom_arg = another_custom_arg
	<span class="hljs-comment"># ... rest of your init</span>

	<span class="hljs-comment"># ... other methods</span><!-- HTML_TAG_END --></pre></div> <p data-svelte-h="svelte-1xb0ker">Pass <code>custom_intro</code> and <code>custom_args</code> for more control. Custom arguments can go in <code>custom_args</code> or in the <code>__init__</code> docstring. Use <code>custom_args</code> when the same arguments repeat across several methods.</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class="language-python "><!-- HTML_TAG_START --><span class="hljs-meta">@auto_docstring(<span class="hljs-params">
	custom_intro=<span class="hljs-string">"""This model performs specific synergistic operations.
	It builds upon the standard Transformer architecture with unique modifications."""</span>,
	custom_args=<span class="hljs-string">"""
	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`.
	"""</span>
	</span>)</span>
	<span class="hljs-keyword">class</span> <span class="hljs-title class_">MySpecialModel</span>(<span class="hljs-title class_ inherited__">PreTrainedModel</span>):
	<span class="hljs-keyword">def</span> <span class="hljs-title function_">__init__</span>(<span class="hljs-params">self, config: ConfigType, custom_parameter: <span class="hljs-string">"type"</span> = <span class="hljs-string">"default_value"</span>, internal_helper_arg=<span class="hljs-literal">None</span></span>):
	<span class="hljs-comment"># ...</span><!-- HTML_TAG_END --></pre></div> <p data-svelte-h="svelte-l5yowr">Also apply <code>@auto_docstring</code> to classes that inherit from <a href="/docs/transformers/main/en/main_classes/output#transformers.utils.ModelOutput">ModelOutput</a>.</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class="language-python "><!-- HTML_TAG_START --><span class="hljs-meta">@auto_docstring(<span class="hljs-params">
	custom_intro=<span class="hljs-string">"""
	Custom model outputs with additional fields.
	"""</span>
	</span>)</span>
	<span class="hljs-meta">@dataclass</span>
	<span class="hljs-keyword">class</span> <span class="hljs-title class_">MyModelOutput</span>(<span class="hljs-title class_ inherited__">ImageClassifierOutput</span>):
	<span class="hljs-string">r"""
	loss (`torch.FloatTensor`, optional):
	The loss of the model.
	custom_field (`torch.FloatTensor` of shape `(batch_size, hidden_size)`, optional):
	A custom output field specific to this model.
	"""</span>

	<span class="hljs-comment"># Standard fields (hidden_states, logits, attentions, etc.) are documented automatically when</span>
	<span class="hljs-comment"># the description matches the standard text. Loss typically varies per model, so document it above.</span>
	loss: <span class="hljs-type">Optional</span>[torch.FloatTensor] = <span class="hljs-literal">None</span>
	logits: <span class="hljs-type">Optional</span>[torch.FloatTensor] = <span class="hljs-literal">None</span>
	hidden_states: <span class="hljs-type">Optional</span>[<span class="hljs-built_in">tuple</span>[torch.FloatTensor, ...]] = <span class="hljs-literal">None</span>
	attentions: <span class="hljs-type">Optional</span>[<span class="hljs-built_in">tuple</span>[torch.FloatTensor, ...]] = <span class="hljs-literal">None</span>
	<span class="hljs-comment"># Custom fields need to be documented in the docstring above</span>
	custom_field: <span class="hljs-type">Optional</span>[torch.FloatTensor] = <span class="hljs-literal">None</span><!-- HTML_TAG_END --></pre></div> <h3 class="relative group"><a id="config-classes" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#config-classes"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Config classes</span></h3> <p data-svelte-h="svelte-bq1abf">Place <code>@auto_docstring</code> directly above a <a href="/docs/transformers/main/en/main_classes/configuration#transformers.PreTrainedConfig">PreTrainedConfig</a> subclass, alongside the <code>@strict</code> decorator. <code>@strict</code> adds runtime type validation and turns the class into a validated dataclass. Config parameters are <em>class-level annotations</em> (not <code>__init__</code> arguments), and <code>@auto_docstring</code> reads them from the class body to generate docs.</p> <p data-svelte-h="svelte-1d9trc4"><code>ConfigArgs</code> provides standard parameters like <code>vocab_size</code>, <code>hidden_size</code>, and <code>num_hidden_layers</code>, so they don’t need a description unless the behavior differs. <a href="/docs/transformers/main/en/main_classes/configuration#transformers.PreTrainedConfig">PreTrainedConfig</a> base parameters are excluded automatically. The <code>checkpoint</code> argument generates the usage example.</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class="language-python "><!-- HTML_TAG_START --><span class="hljs-keyword">from</span> huggingface_hub.dataclasses <span class="hljs-keyword">import</span> strict
	<span class="hljs-keyword">from</span> ...configuration_utils <span class="hljs-keyword">import</span> PreTrainedConfig
	<span class="hljs-keyword">from</span> ...utils <span class="hljs-keyword">import</span> auto_docstring

	<span class="hljs-meta">@strict</span>
	<span class="hljs-meta">@auto_docstring(<span class="hljs-params">checkpoint=<span class="hljs-string">"org/my-model-checkpoint"</span></span>)</span>
	<span class="hljs-keyword">class</span> <span class="hljs-title class_">MyModelConfig</span>(<span class="hljs-title class_ inherited__">PreTrainedConfig</span>):
	<span class="hljs-string">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
	```
	"""</span>

	model_type = <span class="hljs-string">"my_model"</span>

	<span class="hljs-comment"># Standard params (vocab_size, hidden_size, etc.) are auto-documented from ConfigArgs.</span>
	vocab_size: <span class="hljs-built_in">int</span> = <span class="hljs-number">32000</span>
	hidden_size: <span class="hljs-built_in">int</span> = <span class="hljs-number">768</span>
	num_hidden_layers: <span class="hljs-built_in">int</span> = <span class="hljs-number">12</span>
	<span class="hljs-comment"># Model-specific params must be documented in the class docstring above.</span>
	custom_param: <span class="hljs-built_in">int</span> = <span class="hljs-number">64</span>
	another_param: <span class="hljs-built_in">str</span> = <span class="hljs-string">"gelu"</span><!-- HTML_TAG_END --></pre></div> <h3 class="relative group"><a id="processor-classes" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#processor-classes"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Processor classes</span></h3> <p data-svelte-h="svelte-ex4hft">Multimodal processors (<a href="/docs/transformers/main/en/main_classes/processors#transformers.ProcessorMixin">ProcessorMixin</a> subclasses, <code>processing_*.py</code>) always use the bare <code>@auto_docstring</code>. The class intro is auto-generated. Document only <code>__init__</code> parameters not already covered by <code>ProcessorArgs</code> (<code>image_processor</code>, <code>tokenizer</code>, <code>chat_template</code>, and others).</p> <p data-svelte-h="svelte-1ras5qc">If every parameter is standard, omit the docstring. Decorate <code>__call__</code> with <code>@auto_docstring</code> too. Its body docstring holds only a <code>Returns:</code> section plus any extra model-specific call arguments. <code>return_tensors</code> is appended automatically.</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class="language-python "><!-- HTML_TAG_START --><span class="hljs-keyword">from</span> ...processing_utils <span class="hljs-keyword">import</span> ProcessorMixin, ProcessingKwargs, Unpack
	<span class="hljs-keyword">from</span> ...utils <span class="hljs-keyword">import</span> auto_docstring

	<span class="hljs-keyword">class</span> <span class="hljs-title class_">MyModelProcessorKwargs</span>(ProcessingKwargs, total=<span class="hljs-literal">False</span>):
	_defaults = {<span class="hljs-string">"text_kwargs"</span>: {<span class="hljs-string">"padding"</span>: <span class="hljs-literal">False</span>}}

	<span class="hljs-meta">@auto_docstring</span>
	<span class="hljs-keyword">class</span> <span class="hljs-title class_">MyModelProcessor</span>(<span class="hljs-title class_ inherited__">ProcessorMixin</span>):
	<span class="hljs-keyword">def</span> <span class="hljs-title function_">__init__</span>(<span class="hljs-params">self, image_processor=<span class="hljs-literal">None</span>, tokenizer=<span class="hljs-literal">None</span>, custom_param: <span class="hljs-built_in">int</span> = <span class="hljs-number">4</span>, **kwargs</span>):
	<span class="hljs-string">r"""
	custom_param (`int`, optional, defaults to 4):
	A parameter specific to this processor not covered by the standard ProcessorArgs.
	"""</span>
	<span class="hljs-built_in">super</span>().__init__(image_processor, tokenizer)
	self.custom_param = custom_param

	<span class="hljs-meta"> @auto_docstring</span>
	<span class="hljs-keyword">def</span> <span class="hljs-title function_">__call__</span>(<span class="hljs-params">self, images=<span class="hljs-literal">None</span>, text=<span class="hljs-literal">None</span>, **kwargs: Unpack[MyModelProcessorKwargs]</span>):
	<span class="hljs-string">r"""
	Returns:
	[BatchFeature](/docs/transformers/main/en/main_classes/feature_extractor#transformers.BatchFeature): A [BatchFeature](/docs/transformers/main/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.
	"""</span>
	<span class="hljs-comment"># ...</span><!-- HTML_TAG_END --></pre></div> <h4 class="relative group"><a id="image-and-video-processors" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#image-and-video-processors"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Image and video processors</span></h4> <p data-svelte-h="svelte-1rj3tch">Image and video processors (<code>BaseImageProcessor</code> subclasses, <code>image_processing_*.py</code>) follow one of two patterns.</p> <p data-svelte-h="svelte-woh71j">If the processor has model-specific parameters, define a <code>XxxImageProcessorKwargs(ImagesKwargs, total=False)</code> TypedDict with a docstring for those parameters, set <code>valid_kwargs</code> on the class, and use the bare <code>@auto_docstring</code>. The <code>__init__</code> has no docstring.</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class="language-python "><!-- HTML_TAG_START --><span class="hljs-keyword">class</span> <span class="hljs-title class_">MyModelImageProcessorKwargs</span>(ImagesKwargs, total=<span class="hljs-literal">False</span>):
	<span class="hljs-string">r"""
	custom_threshold (`float`, optional, defaults to `self.custom_threshold`):
	A parameter specific to this image processor.
	"""</span>
	custom_threshold: <span class="hljs-built_in">float</span> \| <span class="hljs-literal">None</span>

	<span class="hljs-meta">@auto_docstring</span>
	<span class="hljs-keyword">class</span> <span class="hljs-title class_">MyModelImageProcessor</span>(<span class="hljs-title class_ inherited__">TorchvisionBackend</span>):
	valid_kwargs = MyModelImageProcessorKwargs
	custom_threshold: <span class="hljs-built_in">float</span> = <span class="hljs-number">0.5</span>

	<span class="hljs-keyword">def</span> <span class="hljs-title function_">__init__</span>(<span class="hljs-params">self, **kwargs: Unpack[MyModelImageProcessorKwargs]</span>):
	<span class="hljs-built_in">super</span>().__init__(**kwargs)<!-- HTML_TAG_END --></pre></div> <p data-svelte-h="svelte-hoxzx0">If the class only sets standard class-level attributes (<code>size</code>, <code>resample</code>, <code>image_mean</code>, etc.) with no custom kwargs, use <code>@auto_docstring(custom_intro="Constructs a MyModel image processor.")</code> instead.</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class="language-python "><!-- HTML_TAG_START --><span class="hljs-meta">@auto_docstring(<span class="hljs-params">custom_intro=<span class="hljs-string">"Constructs a MyModel image processor."</span></span>)</span>
	<span class="hljs-keyword">class</span> <span class="hljs-title class_">MyModelImageProcessor</span>(<span class="hljs-title class_ inherited__">TorchvisionBackend</span>):
	resample = PILImageResampling.BICUBIC
	image_mean = IMAGENET_STANDARD_MEAN
	image_std = IMAGENET_STANDARD_STD
	size = {<span class="hljs-string">"height"</span>: <span class="hljs-number">224</span>, <span class="hljs-string">"width"</span>: <span class="hljs-number">224</span>}<!-- HTML_TAG_END --></pre></div> <p data-svelte-h="svelte-a5mhm4">When overriding <code>preprocess</code>, decorate it with <code>@auto_docstring</code> and document only arguments not in <code>ImageProcessorArgs</code>. Standard arguments and <code>return_tensors</code> are included automatically.</p> <h3 class="relative group"><a id="functions" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#functions"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Functions</span></h3> <p data-svelte-h="svelte-kntbhr">Place <code>@auto_docstring</code> directly above the function definition. The decorator derives parameter descriptions from the function signature.</p> <p data-svelte-h="svelte-m6yw58">The decorator generates return-value text from the <code>ModelOutput</code> class docstring.</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class="language-python "><!-- HTML_TAG_START --><span class="hljs-keyword">class</span> <span class="hljs-title class_">MyModel</span>(<span class="hljs-title class_ inherited__">PreTrainedModel</span>):
	<span class="hljs-comment"># ...</span>
	<span class="hljs-meta"> @auto_docstring</span>
	<span class="hljs-keyword">def</span> <span class="hljs-title function_">forward</span>(<span class="hljs-params">
	self,
	input_ids: <span class="hljs-type">Optional</span>[torch.Tensor] = <span class="hljs-literal">None</span>,
	attention_mask: <span class="hljs-type">Optional</span>[torch.Tensor] = <span class="hljs-literal">None</span>,
	new_custom_argument: <span class="hljs-type">Optional</span>[torch.Tensor] = <span class="hljs-literal">None</span>,
	<span class="hljs-comment"># ... other arguments</span>
	</span>) -> <span class="hljs-type">Union</span>[<span class="hljs-type">Tuple</span>, ModelOutput]:
	<span class="hljs-string">r"""
	new_custom_argument (`torch.Tensor`, optional):
	Description of this new custom argument and its expected shape or type.
	"""</span>
	<span class="hljs-comment"># ...</span><!-- HTML_TAG_END --></pre></div> <p data-svelte-h="svelte-1d56jfy">Pass <code>custom_intro</code> and <code>custom_args</code> for more control. Use <code>custom_args</code> to define shared argument docs once when the same parameters appear in several methods.</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class="language-python "><!-- HTML_TAG_START -->MODEL_COMMON_CUSTOM_ARGS = <span class="hljs-string">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
	"""</span>

	<span class="hljs-keyword">class</span> <span class="hljs-title class_">MyModel</span>(<span class="hljs-title class_ inherited__">PreTrainedModel</span>):
	<span class="hljs-comment"># ...</span>
	<span class="hljs-meta"> @auto_docstring(<span class="hljs-params">
	custom_intro=<span class="hljs-string">"""This is a custom introduction for the function."""</span>,
	custom_args=MODEL_COMMON_CUSTOM_ARGS
	</span>)</span>
	<span class="hljs-keyword">def</span> <span class="hljs-title function_">forward</span>(<span class="hljs-params">self, input_ids=<span class="hljs-literal">None</span>, common_arg_1=<span class="hljs-literal">None</span>, common_arg_2=<span class="hljs-literal">None</span></span>) -> ModelOutput:
	<span class="hljs-string">r"""method-specific args go here"""</span>
	<span class="hljs-comment"># ...</span><!-- HTML_TAG_END --></pre></div> <p data-svelte-h="svelte-50aj9g">Write <code>Returns</code> and <code>Examples</code> sections manually in the docstring to override the auto-generated versions.</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class="language-python "><!-- HTML_TAG_START --> <span class="hljs-keyword">def</span> <span class="hljs-title function_">forward</span>(<span class="hljs-params">self, input_ids=<span class="hljs-literal">None</span></span>) -> torch.Tensor:
	<span class="hljs-string">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)
	```
	"""</span>
	<span class="hljs-comment"># ...</span><!-- HTML_TAG_END --></pre></div> <h3 class="relative group"><a id="documenting-arguments" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#documenting-arguments"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Documenting arguments</span></h3> <p data-svelte-h="svelte-l58xcp">Follow these rules when documenting different argument types.</p> <ul><li data-svelte-h="svelte-1nsxie"><p><code>auto_docstring.py</code> defines standard arguments (<code>input_ids</code>, <code>attention_mask</code>, <code>pixel_values</code>, etc.) and includes them automatically. Don’t redefine them locally unless the argument behaves differently in your model.</p> <p>If a standard argument behaves differently in your model, override it locally in a <code>r""" """</code> block. The local definition takes priority. The <code>labels</code> argument, for instance, is commonly customized per model and often needs an override.</p></li> <li data-svelte-h="svelte-1o7h9ps"><p>Standard config arguments (<code>vocab_size</code>, <code>hidden_size</code>, <code>num_hidden_layers</code>, etc.) follow the same principle but come from <code>ConfigArgs</code>. Standard processor arguments (<code>image_processor</code>, <code>tokenizer</code>, <code>do_resize</code>, <code>return_tensors</code>, etc.) come from <code>ProcessorArgs</code> and <code>ImageProcessorArgs</code>. Only document a parameter if it is model-specific or behaves differently from the standard description.</p></li> <li><p data-svelte-h="svelte-10oercv">Document new or custom arguments in an <code>r""" """</code> block. Place them after the signature for functions, in the <code>__init__</code> docstring for model or processor classes, in the class body docstring for config classes, or in the <code>XxxImageProcessorKwargs</code> TypedDict body for image processors.</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class="language-py "><!-- HTML_TAG_START -->argument_name (`<span class="hljs-built_in">type</span>`, optional, defaults to `X`):
	Description of the argument.
	Explain its purpose, expected shape/<span class="hljs-built_in">type</span> <span class="hljs-keyword">if</span> <span class="hljs-built_in">complex</span>, <span class="hljs-keyword">and</span> default behavior.
	This can span multiple lines.<!-- HTML_TAG_END --></pre></div> <ul data-svelte-h="svelte-bt0us3"><li>Include <code>type</code> in backticks.</li> <li>Add <em>optional</em> if the argument is not required or has a default value.</li> <li>Add “defaults to X” if it has a default value. You don’t need to add “defaults to <code>None</code>” if the default value is <code>None</code>.</li> <li>Pass the same block into <code>custom_args</code> when the same arguments repeat across several methods (see the <a href="#functions">Functions example above</a>).</li></ul></li> <li data-svelte-h="svelte-gqu6ul"><p>The decorator extracts types from function signatures automatically. If a parameter has a type annotation, you don’t need to repeat the type in the docstring format string. When both are present, the signature type takes precedence. The docstring type acts as a fallback for unannotated parameters.</p></li></ul> <h2 class="relative group"><a id="checking-the-docstrings" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#checking-the-docstrings"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Checking the docstrings</span></h2> <p data-svelte-h="svelte-xxopt1">A utility script validates docstrings when you open a pull request. CI runs the script and checks the following.</p> <blockquote class="tip" data-svelte-h="svelte-1j6f5ud"><p>If you see an <code>[ERROR]</code> in the output, add the parameter’s description to the docstring or the appropriate Args class in <code>auto_docstring.py</code>.</p></blockquote> <ul data-svelte-h="svelte-1pcwv0y"><li>Checks that <code>@auto_docstring</code> is applied to relevant model classes and public methods.</li> <li>Validates argument completeness and consistency: documented arguments must exist in the signature, and types and default values must match. Unknown arguments without a local description are flagged.</li> <li>Flags incomplete placeholders like <code><fill_type></code> and <code><fill_docstring></code>.</li> <li>Verifies docstrings follow the expected formatting style.</li></ul> <p data-svelte-h="svelte-1nd6vk4">Run the check locally before committing.</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class="language-bash "><!-- HTML_TAG_START -->make fix-repo<!-- HTML_TAG_END --></pre></div> <p data-svelte-h="svelte-u6jcep"><code>make fix-repo</code> runs several other checks too. To run only the docstring and auto-docstring checks, use the command below.</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class="language-bash "><!-- HTML_TAG_START --><span class="hljs-comment"># to only check files included in the diff without fixing them</span>
	python utils/check_docstrings.py
	<span class="hljs-comment"># to fix and overwrite the files in the diff</span>
	<span class="hljs-comment"># python utils/check_docstrings.py --fix_and_overwrite</span>
	<span class="hljs-comment"># to fix and overwrite all files</span>
	<span class="hljs-comment"># python utils/check_docstrings.py --fix_and_overwrite --check_all</span><!-- HTML_TAG_END --></pre></div> <h2 class="relative group"><a id="quick-reference-checklist" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#quick-reference-checklist"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Quick-reference checklist</span></h2> <table data-svelte-h="svelte-1d9tpdo"><thead><tr><th>Do</th> <th>Don’t</th></tr></thead> <tbody><tr><td>Apply <code>@auto_docstring</code> to model, config, and processor classes and their primary methods (<code>forward</code>, <code>__call__</code>, <code>preprocess</code>).</td> <td>Add <code>@auto_docstring</code> to inherited models in modular files because it carries over automatically.</td></tr> <tr><td>Document only new or model-specific arguments.</td> <td>Redefine standard arguments (<code>input_ids</code>, <code>attention_mask</code>, <code>vocab_size</code>, etc.) that behave the same as their default descriptions.</td></tr> <tr><td>Put config parameters in the class body docstring as class-level annotations.</td> <td>Put config parameters in <code>__init__</code>.</td></tr> <tr><td>Put image processor parameters in a <code>XxxImageProcessorKwargs</code> TypedDict.</td> <td>Put image processor parameters in <code>__init__</code>.</td></tr> <tr><td>Run <code>python utils/check_docstrings.py --fix_and_overwrite</code> before committing.</td> <td>Ignore <code>[ERROR]</code> output because it means a parameter is undocumented.</td></tr></tbody></table> <h2 class="relative group"><a id="how-it-works" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#how-it-works"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>How it works</span></h2> <p data-svelte-h="svelte-i9312m">The <code>@auto_docstring</code> decorator generates docstrings through the following steps.</p> <ol data-svelte-h="svelte-19ujllh"><li><p>The decorator inspects the signature to read arguments, types, and defaults from the decorated class’s <code>__init__</code> or the decorated function. For config classes, it walks class-level annotations up the inheritance chain and stops before <a href="/docs/transformers/main/en/main_classes/configuration#transformers.PreTrainedConfig">PreTrainedConfig</a>, excluding base class fields.</p> <p>It automatically filters out parameters like <code>self</code>, <code>kwargs</code>, <code>args</code>, <code>deprecated_arguments</code>, and <code>_</code>-prefixed names. A few private parameters are renamed to their public equivalents (<code>_out_features</code> → <code>out_features</code> for backbone models).</p></li> <li><p>Common argument descriptions come from <code>auto_docstring.py</code>: <code>ModelArgs</code> (model inputs), <code>ModelOutputArgs</code> (output fields like <code>hidden_states</code>), <code>ImageProcessorArgs</code> (image preprocessing), <code>ProcessorArgs</code> (multimodal processor components), and <code>ConfigArgs</code> (config hyperparameters).</p></li> <li><p>Each parameter’s description follows this priority chain:</p> <ul><li>A manual docstring (<code>r""" """</code> block or <code>custom_args</code>) takes priority.</li> <li>The predefined source dict (<code>ModelArgs</code>, <code>ConfigArgs</code>, <code>ImageProcessorArgs</code>, <code>ProcessorArgs</code>, <code>ModelOutputArgs</code>) is the fallback.</li> <li>If neither source has a description, the parameter is flagged with <code>[ERROR]</code> in the build output.</li></ul></li> <li><p>For model classes with standard names like <code>ModelForCausalLM</code>, or classes that map to a pipeline, <code>@auto_docstring</code> generates the intro. For multimodal processors, the intro lists which components (tokenizer, image processor, and so on) the class wraps. See <a href="https://github.com/huggingface/transformers/blob/main/src/transformers/utils/auto_docstring.py#L2437" rel="nofollow">ClassDocstring</a> for the full list.</p> <p>If the class name isn’t in <code>ClassDocstring</code>, set <code>custom_intro</code>.</p></li> <li><p>Predefined docstrings can reference dynamic values from Transformers’ <a href="https://github.com/huggingface/transformers/tree/main/src/transformers/models/auto" rel="nofollow">auto_modules</a>, such as <code>{processor_class}</code>, <code>{image_processor_class}</code>, and <code>{config_class}</code>. The placeholders resolve automatically.</p></li> <li><p>The decorator picks usage examples based on the model’s task or pipeline compatibility. It reads checkpoint metadata from the configuration class so examples use real model IDs. The <code>checkpoint</code> argument overrides the checkpoint inferred from the config class’s docstring. Set <code>checkpoint</code> on config classes, or when checkpoint inference fails. If you see an error like <code>"Config not found for <model_name>"</code>, add an entry to <code>HARDCODED_CONFIG_FOR_MODELS</code> in <code>auto_docstring.py</code>.</p></li> <li><p>For methods like <code>forward</code>, the decorator writes the <code>Returns</code> section from the method’s return type. When the return type is a <a href="/docs/transformers/main/en/main_classes/output#transformers.utils.ModelOutput">ModelOutput</a> subclass, <code>@auto_docstring</code> pulls field descriptions from that class’s docstring. A custom <code>Returns</code> block in the function’s docstring takes precedence.</p></li> <li><p>For methods in <code>UNROLL_KWARGS_METHODS</code> and classes in <code>UNROLL_KWARGS_CLASSES</code>, the decorator expands <code>**kwargs</code> typed with <code>Unpack[KwargsTypedDict]</code>. Each key from the <code>TypedDict</code> becomes a documented parameter.</p> <p>The same expansion applies to <code>__call__</code> and <code>preprocess</code> methods on <a href="/docs/transformers/main/en/main_classes/image_processor#transformers.BaseImageProcessor">BaseImageProcessor</a> and <a href="/docs/transformers/main/en/main_classes/processors#transformers.ProcessorMixin">ProcessorMixin</a> subclasses. Generic base types (<code>TextKwargs</code>, <code>ImagesKwargs</code>, <code>VideosKwargs</code>, <code>AudioKwargs</code>) are skipped. Only model-specific subclasses are unrolled.</p></li></ol> <a class="!text-gray-400 !no-underline text-sm flex items-center not-prose mt-4" href="https://github.com/huggingface/transformers/blob/main/docs/source/en/auto_docstring.md" target="_blank"><svg class="mr-1" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M31,16l-7,7l-1.41-1.41L28.17,16l-5.58-5.59L24,9l7,7z"></path><path d="M1,16l7-7l1.41,1.41L3.83,16l5.58,5.59L8,23l-7-7z"></path><path d="M12.419,25.484L17.639,6.552l1.932,0.518L14.351,26.002z"></path></svg> <span data-svelte-h="svelte-zjs2n5"><span class="underline">Update</span> on GitHub</span></a> <p></p>

	<script>
	{
	__sveltekit_rv114u = {
	assets: "/docs/transformers/main/en",
	base: "/docs/transformers/main/en",
	env: {}
	};

	const element = document.currentScript.parentElement;

	const data = [null,null];

	Promise.all([
	import("/docs/transformers/main/en/_app/immutable/entry/start.3d6cca8a.js"),
	import("/docs/transformers/main/en/_app/immutable/entry/app.b6ccab0d.js")
	]).then(([kit, app]) => {
	kit.start(app, element, {
	node_ids: [0, 10],
	data,
	form: null,
	error: null
	});
	});
	}
	</script>

Xet Storage Details

Size:: 69.8 kB
Xet hash:: aa51a10f9a8d59bce05df374d98b9e03528bb1ff63e5b20eabde2677740247dc

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.