Buckets:
| <meta charset="utf-8" /><meta name="hf:doc:metadata" content="{"title":"Documenting a model","local":"documenting-a-model","sections":[{"title":"@auto_docstring","local":"autodocstring","sections":[],"depth":2},{"title":"Documenting arguments","local":"documenting-arguments","sections":[],"depth":2},{"title":"Checking the docstrings","local":"checking-the-docstrings","sections":[],"depth":2},{"title":"modular_model.py files","local":"modularmodelpy-files","sections":[],"depth":2},{"title":"How it works","local":"how-it-works","sections":[],"depth":2},{"title":"Best practices","local":"best-practices","sections":[],"depth":2}],"depth":1}"> | |
| <link href="/docs/transformers/pr_33892/en/_app/immutable/assets/0.e3b0c442.css" rel="modulepreload"> | |
| <link rel="modulepreload" href="/docs/transformers/pr_33892/en/_app/immutable/entry/start.b2c4257a.js"> | |
| <link rel="modulepreload" href="/docs/transformers/pr_33892/en/_app/immutable/chunks/scheduler.31fdf58d.js"> | |
| <link rel="modulepreload" href="/docs/transformers/pr_33892/en/_app/immutable/chunks/singletons.9860629f.js"> | |
| <link rel="modulepreload" href="/docs/transformers/pr_33892/en/_app/immutable/chunks/index.252883d5.js"> | |
| <link rel="modulepreload" href="/docs/transformers/pr_33892/en/_app/immutable/chunks/paths.e85c0ec8.js"> | |
| <link rel="modulepreload" href="/docs/transformers/pr_33892/en/_app/immutable/entry/app.05ef1f97.js"> | |
| <link rel="modulepreload" href="/docs/transformers/pr_33892/en/_app/immutable/chunks/preload-helper.40847a0e.js"> | |
| <link rel="modulepreload" href="/docs/transformers/pr_33892/en/_app/immutable/chunks/index.2f76fdf0.js"> | |
| <link rel="modulepreload" href="/docs/transformers/pr_33892/en/_app/immutable/nodes/0.ca4aafa4.js"> | |
| <link rel="modulepreload" href="/docs/transformers/pr_33892/en/_app/immutable/chunks/each.e59479a4.js"> | |
| <link rel="modulepreload" href="/docs/transformers/pr_33892/en/_app/immutable/nodes/8.cc4dcb1c.js"> | |
| <link rel="modulepreload" href="/docs/transformers/pr_33892/en/_app/immutable/chunks/CopyLLMTxtMenu.ff482081.js"> | |
| <link rel="modulepreload" href="/docs/transformers/pr_33892/en/_app/immutable/chunks/MermaidChart.svelte_svelte_type_style_lang.71f274cc.js"> | |
| <link rel="modulepreload" href="/docs/transformers/pr_33892/en/_app/immutable/chunks/IconCopy.ac192424.js"> | |
| <link rel="modulepreload" href="/docs/transformers/pr_33892/en/_app/immutable/chunks/CodeBlock.ab12f8e1.js"> | |
| <link rel="modulepreload" href="/docs/transformers/pr_33892/en/_app/immutable/chunks/HfOption.fb051768.js"><!-- HEAD_svelte-u9bgzb_START --><meta name="hf:doc:metadata" content="{"title":"Documenting a model","local":"documenting-a-model","sections":[{"title":"@auto_docstring","local":"autodocstring","sections":[],"depth":2},{"title":"Documenting arguments","local":"documenting-arguments","sections":[],"depth":2},{"title":"Checking the docstrings","local":"checking-the-docstrings","sections":[],"depth":2},{"title":"modular_model.py files","local":"modularmodelpy-files","sections":[],"depth":2},{"title":"How it works","local":"how-it-works","sections":[],"depth":2},{"title":"Best practices","local":"best-practices","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 max-sm:gap-0.5 h-6 max-sm:h-5 px-2 max-sm:px-1.5 text-[11px] max-sm:text-[9px] 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"><svg class="w-3 h-3 max-sm:w-2.5 max-sm:h-2.5" 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-6 max-sm:h-5 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 w-3 h-3 max-sm:w-2.5 max-sm:h-2.5 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="documenting-a-model" 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-a-model"><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 a model</span></h1> <p data-svelte-h="svelte-1w8jwju">The <code>@auto_docstring</code> decorator in Transformers generates consistent docstrings for model classes and their methods. It reduces boilerplate by automatically including standard argument descriptions while also allowing overrides to add new or custom arguments. <a href="./modular_transformers">Contributing a new model</a> is easier because you don’t need to manually add the standard docstrings, and only focus on documenting new arguments.</p> <p data-svelte-h="svelte-1na6xp4">This guide describes how to use the <code>@auto_docstring</code> decorator and how it works.</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-rurmbi">Start by importing the decorator in the modeling file (<code>modular_model.py</code> or <code>modeling_model.py</code>).</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=""><!-- 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-1w3989a">Select whether you’d like to apply <code>@auto_docstring</code> to a class or function below to see how to use it.</p> <div class="flex space-x-2 items-center my-1.5 mr-8 h-7 !pl-0 -mx-3 md:mx-0"><div class="flex items-center border rounded-lg px-1.5 py-1 leading-none select-none text-smd border-gray-800 bg-black dark:bg-gray-700 text-white">classes </div><div class="flex items-center border rounded-lg px-1.5 py-1 leading-none select-none text-smd text-gray-500 cursor-pointer opacity-90 hover:text-gray-700 dark:hover:text-gray-200 hover:shadow-sm">functions </div></div> <div class="language-select"><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=""><!-- 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-lez4sy">Arguments can also be passed directly to <code>@auto_docstring</code> for more control. Use the <code>custom_intro</code> parameter to describe the argument and the <code>custom_args</code> parameter to describe the arguments.</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=""><!-- 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-af96qe">You can also choose to only use <code>custom_intro</code> and define the custom arguments directly in the class.</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=""><!-- 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>, | |
| </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-string">r""" | |
| 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 class="hljs-comment"># ...</span><!-- HTML_TAG_END --></pre></div> <p data-svelte-h="svelte-h3zv2f">You should also use the <code>@auto_docstring</code> decorator for classes that inherit from <a href="/docs/transformers/pr_33892/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=""><!-- HTML_TAG_START --><span class="hljs-meta">@dataclass</span> | |
| <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-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 like hidden_states, logits, attentions etc. can be automatically documented if the description is the same as the standard arguments.</span> | |
| <span class="hljs-comment"># However, given that the loss docstring is often different per model, you should document it in the docstring 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> </div> <h2 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></h2> <p data-svelte-h="svelte-xyj1fb">There are some rules for documenting different types of arguments and they’re listed below.</p> <ul><li data-svelte-h="svelte-l8hg8l"><p>Standard arguments (<code>input_ids</code>, <code>attention_mask</code>, <code>pixel_values</code>, etc.) are defined and retrieved from <code>auto_docstring.py</code>. It is the single source of truth for standard arguments and should not be redefined locally if an argument’s description and shape is the same as an argument in <code>auto_docstring.py</code>.</p> <p>If a standard argument behaves differently in your model, then you can override it locally in a <code>r""" """</code> block. This local definition has a higher priority. For example, the <code>labels</code> argument is often customized per model and typically requires overriding.</p></li> <li><p data-svelte-h="svelte-15gftnh">New or custom arguments should be documented within an <code>r""" """</code> block after the signature if it is a function or in the <code>__init__</code> method’s docstring if it is a class.</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=""><!-- 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><li data-svelte-h="svelte-hn76ri"><p>Include <code>type</code> in backticks.</p></li> <li data-svelte-h="svelte-iocda8"><p>Add <em>optional</em> if the argument is not required or has a default value.</p></li> <li><p data-svelte-h="svelte-1cbz19x">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>.</p> <p data-svelte-h="svelte-151nnsu">These arguments can also be passed to <code>@auto_docstring</code> as a <code>custom_args</code> argument. It is used to define the docstring block for new arguments once if they are repeated in multiple places in the modeling file.</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=""><!-- 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 class="hljs-params"> | |
| custom_intro=<span class="hljs-string">""" | |
| This is a custom introduction for the function. | |
| """</span> | |
| custom_args=<span class="hljs-string">r""" | |
| common_arg_1 (`torch.Tensor`, *optional*, defaults to `default_value`): | |
| Description of common_arg_1 | |
| """</span> | |
| </span>)</span><!-- HTML_TAG_END --></pre></div></li></ul></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-qcur1f">Transformers includes a utility script to validate the docstrings when you open a Pull Request which triggers CI (continuous integration) checks. The script checks for the following criteria.</p> <ul data-svelte-h="svelte-yrys2o"><li>Ensures <code>@auto_docstring</code> is applied to relevant mode classes and public methods.</li> <li>Ensures arguments are complete and consistent. It checks that documented arguments exist in the signature and verifies whether the types and default values in the docstring match the signature. Arguments that aren’t known standard arguments or if they lack a local description are flagged.</li> <li>Reminds you to complete placeholders like <code><fill_type></code> and <code><fill_docstring></code>.</li> <li>Ensures docstrings are formatted according to the expected docstring style.</li></ul> <p data-svelte-h="svelte-1qbeucd">You can run this check locally - before committing - by running the following command.</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=""><!-- HTML_TAG_START -->make fix-copies<!-- HTML_TAG_END --></pre></div> <p data-svelte-h="svelte-ee86s3"><code>make fix-copies</code> runs several other checks as well. If you don’t need those checks, run the command below to only perform docstring and auto-docstring checks.</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=""><!-- HTML_TAG_START -->python utils/check_docstrings.py <span class="hljs-comment"># to only check files included in the diff without fixing them</span> | |
| <span class="hljs-comment"># python utils/check_docstrings.py --fix_and_overwrite # to fix and overwrite the files in the diff</span> | |
| <span class="hljs-comment"># python utils/check_docstrings.py --fix_and_overwrite --check_all # to fix and overwrite all files</span><!-- HTML_TAG_END --></pre></div> <h2 class="relative group"><a id="modularmodelpy-files" 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="#modularmodelpy-files"><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>modular_model.py files</span></h2> <p data-svelte-h="svelte-p2msvc">When working with modular files (<code>modular_model.py</code>), follow the guidelines below for applying <code>@auto_docstring</code>.</p> <ul data-svelte-h="svelte-1l8ksz6"><li><p>For standalone models in modular files, apply <code>@auto_docstring</code> like you would in a <code>modeling_model.py</code> file.</p></li> <li><p>For models that inherit from other library models, <code>@auto_docstring</code> is automatically carried over to the generated modeling file. You don’t need to add <code>@auto_docstring</code> in your modular file.</p> <p>If you need to modify the <code>@auto_docstring</code> behavior, apply the customized decorator in your modular file. Make sure to <strong>include all other decorators</strong> that are present in the original function or class.</p></li></ul> <blockquote class="warning" data-svelte-h="svelte-54tdod"><p>When overriding any decorator in a modular file, you must include <strong>all</strong> decorators that were applied to that function or class in the parent model. If you only override some decorators, the others won’t be included in the generated modeling file.</p></blockquote> <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-1g2ibuk">The <code>@auto_docstring</code> decorator automatically generates docstrings by:</p> <ol data-svelte-h="svelte-1xoi9rp"><li><p>Inspecting the signature (arguments, types, defaults) of the decorated class’ <code>__init__</code> method or the decorated function.</p></li> <li><p>Retrieving the predefined docstrings for common arguments (<code>input_ids</code>, <code>attention_mask</code>, etc.) from internal library sources like <code>ModelArgs</code>, <code>ImageProcessorArgs</code>, and the <code>auto_docstring.py</code> file.</p></li> <li><p>Adding argument descriptions in one of two ways as shown below.</p> <table><thead><tr><th>method</th> <th>description</th> <th>usage</th></tr></thead> <tbody><tr><td><code>r""" """</code></td> <td>add custom docstring content directly to a method signature or within the <code>__init__</code> docstring</td> <td>document new arguments or override standard descriptions</td></tr> <tr><td><code>custom_args</code></td> <td>add custom docstrings for specific arguments directly in <code>@auto_docstring</code></td> <td>define docstring for new arguments once if they’re repeated in multiple places in the modeling file</td></tr></tbody></table></li> <li><p>Adding class and function descriptions. For model classes with standard naming patterns, like <code>ModelForCausalLM</code>, or if it belongs to a pipeline, <code>@auto_docstring</code> automatically generates the appropriate descriptions with <code>ClassDocstring</code> from <code>auto_docstring.py</code>.</p> <p><code>@auto_docstring</code> also accepts the <code>custom_intro</code> argument to describe a class or function.</p></li> <li><p>Using a templating system to allow predefined docstrings to include dynamic information 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> and <code>{{config_class}}</code>.</p></li> <li><p>Finding appropriate usage examples based on the model’s task or pipeline compatibility. It extracts checkpoint information form the model’s configuration class to provide concrete examples with real model identifiers.</p></li> <li><p>Adding return values to the docstring. For methods like <code>forward</code>, the decorator automatically generates the <code>Returns</code> field in the docstring based on the method’s return type annotation.</p> <p>For example, if a method returns a <a href="/docs/transformers/pr_33892/en/main_classes/output#transformers.utils.ModelOutput">ModelOutput</a> subclass, <code>@auto_docstring</code> extracts the field descriptions from the class’ docstring to create a comprehensive return value description. You can also manually specify a custom <code>Returns</code> field in a functions docstring.</p></li> <li><p>Unrolling kwargs typed with the unpack operator. For specific methods (defined in <code>UNROLL_KWARGS_METHODS</code>) or classes (defined in <code>UNROLL_KWARGS_CLASSES</code>), the decorator processes <code>**kwargs</code> parameters that are typed with <code>Unpack[KwargsTypedDict]</code>. It extracts the documentations from the <code>TypedDict</code> and adds each parameter to the function’s docstring.</p> <p>Currently only supported for <code>ImagesKwargs</code>.</p></li></ol> <h2 class="relative group"><a id="best-practices" 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="#best-practices"><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>Best practices</span></h2> <p data-svelte-h="svelte-1fwlepx">Follow the best practices below to help maintain consistent and informative documentation for Transformers!</p> <ul data-svelte-h="svelte-1pxx13u"><li>Use <code>@auto_docstring</code> for new PyTorch model classes (<a href="/docs/transformers/pr_33892/en/main_classes/model#transformers.PreTrainedModel">PreTrainedModel</a> subclasses) and their primary methods like <code>forward</code> or <code>get_text_features</code>.</li> <li>For classes, <code>@auto_docstring</code> retrieves parameter descriptions from the <code>__init__</code> method’s docstring.</li> <li>Rely on standard docstrings and do not redefine common arguments unless their behavior is different in your model.</li> <li>Document new or custom arguments clearly.</li> <li>Run <code>check_docstrings</code> locally and iteratively.</li></ul> <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_16tnnm8 = { | |
| assets: "/docs/transformers/pr_33892/en", | |
| base: "/docs/transformers/pr_33892/en", | |
| env: {} | |
| }; | |
| const element = document.currentScript.parentElement; | |
| const data = [null,null]; | |
| Promise.all([ | |
| import("/docs/transformers/pr_33892/en/_app/immutable/entry/start.b2c4257a.js"), | |
| import("/docs/transformers/pr_33892/en/_app/immutable/entry/app.05ef1f97.js") | |
| ]).then(([kit, app]) => { | |
| kit.start(app, element, { | |
| node_ids: [0, 8], | |
| data, | |
| form: null, | |
| error: null | |
| }); | |
| }); | |
| } | |
| </script> | |
Xet Storage Details
- Size:
- 44.2 kB
- Xet hash:
- 1e9dbbb0d026d5321a37966ef15bfcafcaecd00e8d228870a7e7b6699f693c35
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.