Diffusers 文檔工程指南構(gòu)建、預(yù)覽與 Google 風(fēng)格 Docstring 規(guī)范全解析【免費(fèi)下載鏈接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/di/diffusers本文是面向 Diffusers 倉(cāng)庫(kù)PyTorch 實(shí)現(xiàn)圖像、視頻、音頻擴(kuò)散模型的工具庫(kù)文檔開(kāi)發(fā)者的完整工程手冊(cè)核心內(nèi)容以 docs/README.md 為骨架展開(kāi)。你將掌握從零構(gòu)建文檔站點(diǎn)、使用 doc-builder 本地實(shí)時(shí)預(yù)覽、維護(hù)_toctree.yml導(dǎo)航樹(shù)到新增 Pipeline/Scheduler 文檔頁(yè)、遵循 Google 風(fēng)格 docstring 撰寫(xiě)規(guī)范與[[autodoc]]自動(dòng)文檔標(biāo)記語(yǔ)法的完整技能同時(shí)獲得倉(cāng)庫(kù)內(nèi)源碼與配置文件的一手佐證。文檔體系的全局布局在動(dòng)手構(gòu)建文檔之前先理解 Diffusers 文檔倉(cāng)庫(kù)的組織方式能讓后續(xù)所有命令與操作都落在正確的路徑上。多語(yǔ)言文檔目錄結(jié)構(gòu)Diffusers 的文檔源文件存放在docs/source/下并按語(yǔ)言代碼分目錄docs/source/en/英文文檔當(dāng)前最完整含index.md、installation.md、quicktour.md、using-diffusers/、api/、training/等docs/source/zh/、docs/source/ja/、docs/source/ko/、docs/source/pt/對(duì)應(yīng)中文、日文、韓文、葡萄牙文翻譯。每個(gè)語(yǔ)言目錄都包含一個(gè)名為_(kāi)toctree.yml的導(dǎo)航配置文件例如英文版位于 docs/source/en/_toctree.yml它定義了站點(diǎn)左側(cè)導(dǎo)航樹(shù)toc-tree的分組、層級(jí)與每頁(yè)的title。凡是涉及新增文檔頁(yè)調(diào)整導(dǎo)航結(jié)構(gòu)的操作最終都要落回對(duì)這個(gè)文件或?qū)?yīng)語(yǔ)言版本的_toctree.yml的修改。構(gòu)建文檔所需的依賴鏈從 setup.py 可以看到Diffusers 文檔構(gòu)建依賴被集中管理extras[docs] deps_list(hf-doc-builder)setup.pydocs這個(gè) pip extra 只依賴hf-doc-builder對(duì)應(yīng)hf-doc-builder0.3.0見(jiàn) setup.pyextras[quality]同樣包含hf-doc-buildersetup.py說(shuō)明 doc-builder 既用于文檔構(gòu)建也參與代碼質(zhì)量檢查見(jiàn)下文make style依賴版本表由腳本自動(dòng)生成至src/diffusers/dependency_versions_table.py修改_deps后需運(yùn)行make deps_table_update同步。在本地生成文檔站點(diǎn)第一步安裝構(gòu)建依賴在倉(cāng)庫(kù)根目錄執(zhí)行以下命令以可編輯模式安裝帶docsextra 的 Diffusers從而拉入構(gòu)建文檔所需的一切 Python 包pip install -e .[docs]第二步安裝開(kāi)源文檔構(gòu)建工具Diffusers 的文檔并不依賴 Sphinx而是使用 Hugging Face 開(kāi)源的 doc-builder 工具這正是hf-doc-builder在 setup.py 中被聲明為依賴、且被extras[docs]引用的原因pip install githttps://github.com/huggingface/doc-builder注意只有在本地檢查文檔效果時(shí)才需要執(zhí)行構(gòu)建——例如你想在提交前預(yù)覽改動(dòng)后的渲染結(jié)果。構(gòu)建產(chǎn)物不需要也不應(yīng)當(dāng)提交進(jìn)倉(cāng)庫(kù)。倉(cāng)庫(kù)只讀前提下上述操作僅用于本地查看與驗(yàn)證。實(shí)時(shí)預(yù)覽文檔安裝 watchdogwatchdog提供文件系統(tǒng)事件監(jiān)聽(tīng)能力是 doc-builder 實(shí)現(xiàn)改文件即時(shí)刷新的前提pip install watchdog啟動(dòng)預(yù)覽服務(wù)預(yù)覽命令的通用格式是doc-builder preview {package_name} {path_to_docs}對(duì) Diffusers 而言package_name即diffuserspath_to_docs指向英文文檔目錄doc-builder preview diffusers docs/source/en啟動(dòng)后文檔即可在http://localhost:3000查看。除此之外當(dāng)你針對(duì)文檔改動(dòng)提交 Pull Request 后PR 機(jī)器人也會(huì)在評(píng)論區(qū)附上包含你改動(dòng)的預(yù)覽鏈接。注意preview命令只對(duì)已存在的文檔文件生效。當(dāng)你新增了一個(gè)全新的文件時(shí)必須先在_toctree.yml中登記該文件并重啟預(yù)覽命令按ctrl-c停止再重新執(zhí)行doc-builder preview ...改動(dòng)才會(huì)被識(shí)別。倉(cāng)庫(kù)中的 doc-builder 輔助驗(yàn)證doc-builder 不只用于生成頁(yè)面也深度融入了 Diffusers 的質(zhì)量門(mén)禁。倉(cāng)庫(kù)根目錄的 Makefile 給出了佐證make quality會(huì)執(zhí)行doc-builder style src/diffusers docs/source --max_len 119 --check_onlyMakefile以--check_only模式檢查 docstring 排版是否超寬、是否符合規(guī)范make style則執(zhí)行doc-builder style src/diffusers docs/source --max_len 119Makefile不帶--check_only即直接對(duì) docstring 與文檔代碼塊做格式化。兩條命令都遵循單行最長(zhǎng) 119 字符的項(xiàng)目約定與后文 docstring 行寬規(guī)范相互呼應(yīng)。維護(hù)導(dǎo)航欄與章節(jié)結(jié)構(gòu)向?qū)Ш綑谔砑有略貙?dǎo)航樹(shù)只接受擴(kuò)展名為.md的 Markdown 文件。添加一個(gè)新頁(yè)面分兩步在源目錄中創(chuàng)建文件帶.md擴(kuò)展名將該文件去掉擴(kuò)展名后的名字登記進(jìn)對(duì)應(yīng)語(yǔ)言目錄的_toctree.yml從而鏈接到 toc-tree。以倉(cāng)庫(kù)現(xiàn)有的 docs/source/en/_toctree.yml 為例每個(gè)導(dǎo)航條目形如- local: using-diffusers/schedulers title: Schedulers其中l(wèi)ocal對(duì)應(yīng) Markdown 文件的路徑不含.md后綴title是站點(diǎn)側(cè)欄展示的標(biāo)題。多個(gè)條目可以聚合在一個(gè)sections:分組下并設(shè)置title例如Get startedPipelinesInference optimization等大分區(qū)某些分區(qū)還帶isExpanded: false控制默認(rèn)折疊狀態(tài)。整個(gè) toc-tree 呈現(xiàn)嚴(yán)格的嵌套層級(jí)頂層大分區(qū) → 中層級(jí)分區(qū)如 Models 下的 ControlNets / Transformers / UNets / VAEs→ 具體文檔頁(yè)條目。從英文_toctree.yml可見(jiàn)新增頁(yè)面時(shí)按主題放入 API PipelinesAPI Schedulers等對(duì)應(yīng)小節(jié)即可。重命名章節(jié)標(biāo)題與移動(dòng)章節(jié)時(shí)的錨點(diǎn)維護(hù)重命名章節(jié)標(biāo)題或?qū)⒄鹿?jié)從一個(gè)文檔移動(dòng)到另一個(gè)文檔時(shí)舊鏈接很可能已被 Issues、論壇與社交媒體引用。為了讓數(shù)月后通過(guò)舊鏈接訪問(wèn)的用戶仍能定位到原本的信息需要在原章節(jié)所在文檔末尾保留一張被移動(dòng)章節(jié)的小地圖。核心原則是保留原始錨點(diǎn)。例如把章節(jié)從 Section A 改名為 Section B 后可在文件末尾添加Sections that were moved: [ a href#section-bSection A/aa idsection-a/a ]若章節(jié)被移動(dòng)到另一個(gè)文件則把鏈接目標(biāo)改為新文件用相對(duì)路徑風(fēng)格保證多版本文檔下鏈接繼續(xù)有效Sections that were moved: [ a href../new-file#section-bSection A/aa idsection-a/a ]同時(shí)為舊錨點(diǎn)保留一個(gè)同名的a idsection-a/a空錨使指向舊錨點(diǎn)的鏈接依然命中頁(yè)面。倉(cāng)庫(kù)中一個(gè)信息量豐富的此類(lèi)移動(dòng)章節(jié)示例可參考 Transformers 的 Trainer 文檔末尾。新增教程與 Pipeline / Scheduler 文檔新增教程的兩步流程添加新教程或新章節(jié)分兩步在docs/source/languageCode下新建 Markdown 文件將該文件鏈接到docs/source/languageCode/_toctree.yml中正確的 toc-tree 位置。放置位置取決于目標(biāo)讀者新手教程通常放在Get Started之后中級(jí)讀者或研究者向的內(nèi)容則應(yīng)放入第二、三、四分區(qū)。參照英文_toctree.yml教程類(lèi)頁(yè)面按主題被組織在 Get startedPipelinesAdaptersTraining 等不同title分區(qū)下。新增 Pipeline / Scheduler 的標(biāo)準(zhǔn)流程新增 Pipeline 時(shí)在docs/source/languageCode/api/pipelines下創(chuàng)建xxx.md可復(fù)制現(xiàn)有文件作為模板在_toctree.yml的API Pipelines分區(qū)登記該文件為該擴(kuò)散模型撰寫(xiě)簡(jiǎn)短概述一般包含論文與作者信息概覽論文摘要使用要點(diǎn)tips and tricks與最佳實(shí)踐一個(gè)端到端的使用示例。在概述之后用項(xiàng)目自定義的 Markdown 語(yǔ)法列出所有應(yīng)鏈接的 Pipeline 類(lèi)。默認(rèn)寫(xiě)法如下[[autodoc]] XXXPipeline - all - __call__這會(huì)自動(dòng)收錄該 Pipeline 所有已編寫(xiě)文檔的公開(kāi)方法以及默認(rèn)不收錄的__call__方法。如果除__call__外還想補(bǔ)充額外方法只需把方法列表顯式寫(xiě)出其中仍可包含all[[autodoc]] XXXPipeline - all - __call__ - enable_attention_slicing - disable_attention_slicing - enable_xformers_memory_efficient_attention - disable_xformers_memory_efficient_attention新增Scheduler的過(guò)程與 Pipeline 完全相同只是目標(biāo)目錄換為docs/source/languageCode/api/schedulers登記位置換為_(kāi)toctree.yml的API Schedulers小節(jié)。倉(cāng)庫(kù)中的[[autodoc]]真實(shí)用法[[autodoc]]語(yǔ)法在英文文檔中被廣泛使用。以 docs/source/en/api/attnprocessor.md 為例它逐行列出每個(gè)注意力處理器類(lèi)并自動(dòng)鏈接其文檔[[autodoc]] models.attention_processor.AttnProcessor [[autodoc]] models.attention_processor.AttnProcessor2_0 [[autodoc]] models.attention_processor.FusedAttnProcessor2_0 ...而 docs/source/en/api/activations.md 也以[[autodoc]] models.activations.GELU這類(lèi)形式登記激活函數(shù)類(lèi)。實(shí)際 Pipeline 文檔頁(yè)中常見(jiàn)更完整的塊級(jí)寫(xiě)法[[autodoc]] DiffusionPipeline - all - __call__ - enable_attention_slicing ...可見(jiàn)[[autodoc]]的路徑書(shū)寫(xiě)約定為去掉src/diffusers/前綴、用點(diǎn)號(hào)連接子模塊路徑如models.attention_processor.AttnProcessor。結(jié)合當(dāng)前倉(cāng)庫(kù) src/diffusers/models 目錄中存放的 156 個(gè)模型實(shí)現(xiàn)文件可以推斷每新增一個(gè)模型類(lèi)對(duì)應(yīng) API 文檔頁(yè)便會(huì)新增一組這樣的[[autodoc]]塊而_toctree.yml中龐大的 Models 列表ControlNets / Transformers / UNets / VAEs 四級(jí)分組涵蓋 Flux、CogVideoX、Hunyuan 系列等數(shù)十個(gè)模型正是由這些塊驅(qū)動(dòng)的渲染結(jié)果。源碼文檔撰寫(xiě)規(guī)范Docstring SpecificationDiffusers 的文檔字符串遵循 Google documentation 風(fēng)格但直接以 Markdown 書(shū)寫(xiě)?；A(chǔ)排版約定需要放入code反引號(hào)中的內(nèi)容包括參數(shù)名、True/None等對(duì)象、以及任意字符串字面量。提及某個(gè)類(lèi)、函數(shù)或方法時(shí)推薦使用內(nèi)部鏈接語(yǔ)法使 doc-builder 自動(dòng)生成指向其文檔的鏈接。該語(yǔ)法要求對(duì)象位于主包內(nèi)并提供完整路徑[pipelines.ImagePipelineOutput]生成描述文字為pipelines.ImagePipelineOutput的鏈接[~pipelines.ImagePipelineOutput]加~后只保留類(lèi)名生成描述文字為ImagePipelineOutput的鏈接。方法同理既可用 [XXXClass.method]也可用 [~XXXClass.method]。方法參數(shù)的定義格式參數(shù)區(qū)以Args:或Arguments:/Parameters:前綴開(kāi)頭換行后縮進(jìn)書(shū)寫(xiě)。每個(gè)參數(shù)需依次給出參數(shù)名、類(lèi)型張量還需給出 shape、冒號(hào)、參數(shù)描述Args: n_layers (int): The number of layers of the model.若描述過(guò)長(zhǎng)需要換行則需在參數(shù)行后再增加一層縮進(jìn)。一個(gè)完整示例Args: input_ids (torch.LongTensor of shape (batch_size, sequence_length)): Indices of input sequence tokens in the vocabulary. Indices can be obtained using [AlbertTokenizer]. See [~PreTrainedTokenizer.encode] and [~PreTrainedTokenizer.__call__] for details. [What are input IDs?](https://huggingface.co/docs/transformers/main/en/glossary#input-ids)可選參數(shù)與帶默認(rèn)值參數(shù)的寫(xiě)法對(duì)于帶默認(rèn)值的可選參數(shù)遵循如下約定。假設(shè)函數(shù)簽名為def my_function(x: strNone, a: float3.14):則其文檔應(yīng)寫(xiě)作Args: x (str, *optional*): This argument controls ... a (float, *optional*, defaults to 3.14): This argument is used to ...注意事項(xiàng)當(dāng)某參數(shù)默認(rèn)值為None時(shí)總是省略 defaults to None 的表述描述參數(shù)類(lèi)型與默認(rèn)值的第一行即便很長(zhǎng)也不能拆成多行但縮進(jìn)的描述部分可任意換行見(jiàn)上文input_ids示例。多行代碼塊的寫(xiě)法展示示例的多行代碼塊使用 Markdown 標(biāo)準(zhǔn)語(yǔ)法——兩個(gè)三反引號(hào)行包圍 # first line of code # second line # etc 返回值Return塊的寫(xiě)法返回值區(qū)域以Returns:前綴開(kāi)頭換行后縮進(jìn)。首行寫(xiě)返回類(lèi)型組成返回對(duì)象的各個(gè)元素不需要再額外縮進(jìn)。單值返回示例Returns: List[int]: A list of integers in the range [0, 1] --- 1 for a special token, 0 for a sequence token.元組返回示例含多個(gè)對(duì)象、各對(duì)象帶可選說(shuō)明Returns: tuple(torch.Tensor) comprising various elements depending on the configuration ([BertConfig]) and inputs: - ** loss** (*optional*, returned when masked_lm_labels is provided) torch.Tensor of shape (1,) -- Total loss is the sum of the masked language modeling loss and the next sequence prediction (classification) loss. - **prediction_scores** (torch.Tensor of shape (batch_size, sequence_length, config.vocab_size)) -- Prediction scores of the language modeling head (scores for each vocabulary token before SoftMax).圖片資源的加入原則鑒于倉(cāng)庫(kù)體積增長(zhǎng)迅速應(yīng)避免向倉(cāng)庫(kù)引入會(huì)顯著增加體積的文件圖片、視頻等非文本文件。Diffusers 傾向于把此類(lèi)文件托管在 hf.co 的 dataset 上如hf-internal-testing系列或huggingface/documentation-images并在文檔中通過(guò) URL 引用。外部貢獻(xiàn)者可將圖片加入自己的 PR然后請(qǐng) Hugging Face 成員協(xié)助把圖片遷移到上述 dataset 中而非直接提交二進(jìn)制文件。Docstring 自動(dòng)樣式化與格式化項(xiàng)目提供make style命令自動(dòng)處理 docstring 樣式保證 docstring 充分利用規(guī)定的行寬所有代碼示例使用 black 格式化與 Transformers 庫(kù)一致。因?yàn)樵撃_本在遇到語(yǔ)法錯(cuò)誤或暴露 bug 時(shí)可能出現(xiàn)異常行為官方建議在運(yùn)行make style之前先提交commit你的改動(dòng)以便在必要時(shí)輕松回退腳本產(chǎn)生的修改。在倉(cāng)庫(kù)中這一能力由 Makefile 中的style/quality目標(biāo)落實(shí)make style調(diào)用doc-builder style src/diffusers docs/source --max_len 119直接改寫(xiě)文件make quality則用--check_only在 CI 上做只讀校驗(yàn)二者共同保證合入的文檔永遠(yuǎn)滿足排版規(guī)范。實(shí)戰(zhàn)演練為一個(gè)新 Pipeline 撰寫(xiě)文檔頁(yè)綜合以上全部規(guī)范一次完整的文檔新增實(shí)踐可按如下順序執(zhí)行復(fù)制模板在docs/source/en/api/pipelines/下復(fù)制現(xiàn)有頁(yè)面作為newmodel.md起點(diǎn)文檔明確建議復(fù)制現(xiàn)有文件當(dāng)模板撰寫(xiě)概述填入模型概述論文與作者、論文摘要、tips 與最佳實(shí)踐必要時(shí)給出端到端示例注冊(cè)自動(dòng)文檔以塊級(jí)語(yǔ)法列出該 Pipeline 的全部類(lèi)與方法并確保__call__與需要公開(kāi)的方法都被收錄登記導(dǎo)航樹(shù)把newmodel去掉.md寫(xiě)入docs/source/en/_toctree.yml的API Pipelines分區(qū)本地預(yù)覽運(yùn)行pip install watchdog后執(zhí)行doc-builder preview diffusers docs/source/en在http://localhost:3000檢查渲染效果——記住新增文件后需重啟 preview排版校驗(yàn)提交改動(dòng)后運(yùn)行make styleMakefile讓 doc-builder 自動(dòng)完成 docstring 與代碼示例的 black 格式化與行寬119 字符整理再統(tǒng)一提交。這一流程貫穿源碼注釋 → Markdown 頁(yè)面 → 自動(dòng)文檔 → 導(dǎo)航登記 → 預(yù)覽與格式化的完整鏈路正是 Diffusers 龐大 API 文檔覆蓋 150 模型與 50 Scheduler見(jiàn) docs/source/en/_toctree.yml得以持續(xù)演進(jìn)的基礎(chǔ)設(shè)施。結(jié)語(yǔ)Diffusers 的文檔體系是一套doc-builder 生成站點(diǎn) _toctree.yml組織導(dǎo)航 Google 風(fēng)格 docstring [[autodoc]]自動(dòng)回鏈源碼的完整工程化方案。掌握 docs/README.md 所述的構(gòu)建、預(yù)覽與撰寫(xiě)規(guī)范再對(duì)照 Makefile、setup.py 與 docs/source/en/_toctree.yml 中的真實(shí)配置你便能為任意 Pipeline、Scheduler 或模型類(lèi)貢獻(xiàn)出排版規(guī)范、可自動(dòng)渲染、能被搜索引擎與 Agent 順暢檢索的高質(zhì)量技術(shù)文檔?！久赓M(fèi)下載鏈接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/di/diffusers創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考