Diffusers documentation
قوالب التوثيق التلقائي والمعاملات
قوالب التوثيق التلقائي والمعاملات
يحتوي كل ModularPipelineBlocks على خاصية doc يتم توليدها تلقائيًا من description وinputs وintermediate_outputs وexpected_components وexpected_configs. يحافظ نظام توثيق الدوال التلقائي على مزامنة توثيق الدوال مع الواجهة الفعلية للكتلة. توفر قوالب المعلمات أوصافًا موحدة للمعلمات التي تظهر عبر خطوط أنابيب متعددة.
توثيق تلقائي
كتل خط الأنابيب المعيارية قابلة للتركيب — يمكنك تضمينها، وتوصيلها في تسلسلات، وإعادة ترتيبها بحرية. تتبع سطور التوثيق الخاصة بها نفس النمط. عندما تجمع SequentialPipelineBlocks المدخلات والمخرجات من كتلها الفرعية، يجب أن يتم تحديث التوثيق تلقائيًا دون الحاجة إلى إعادة كتابة يدوية.
يولّد المؤشر # auto_docstring سطور التوثيق من خصائص الكتلة. أضِفه فوق تعريف الفئة لتحديد الفئة لتوليد سطور التوثيق تلقائيًا.
# auto_docstring
class FluxTextEncoderStep(SequentialPipelineBlocks):
...شغّل الأمر التالي لتوليد سلاسل التوثيق وإدراجها.
python utils/modular_auto_docstring.py --fix_and_overwrite
تقرأ الأداة خاصية doc الخاصة بالكتلة وتدرجها كسلسلة توثيق للفئة.
# auto_docstring
class FluxTextEncoderStep(SequentialPipelineBlocks):
"""
Text input processing step that standardizes text embeddings for the pipeline.
Inputs:
prompt_embeds (`torch.Tensor`) *required*:
text embeddings used to guide the image generation.
...
Outputs:
prompt_embeds (`torch.Tensor`):
text embeddings used to guide the image generation.
...
"""يمكنك أيضًا التحقق دون الكتابة فوق الملفات، أو استهداف ملف أو مجلد محدد.
# Check that all marked classes have up-to-date docstrings
python utils/modular_auto_docstring.py
# Check a specific file or directory
python utils/modular_auto_docstring.py src/diffusers/modular_pipelines/flux/إذا كان أي من الفئات المحددة يفتقر إلى سلسلة توثيق، فإن الفحص يفشل ويقوم بإدراج الفئات التي تحتاج إلى تحديث.
Found the following # auto_docstring markers that need docstrings:
- src/diffusers/modular_pipelines/flux/encoders.py: FluxTextEncoderStep at line 42
Run `python utils/modular_auto_docstring.py --fix_and_overwrite` to fix them.قوالب المعلمات
InputParam وOutputParam تعرّف مدخلات ومخرجات الكتلة. أنشئها مباشرةً أو استخدم .template() لتعريفات قياسية للمعاملات الشائعة مثل prompt وnum_inference_steps أو latents.
InputParam
InputParam يصف مدخلًا واحدًا إلى كتلة.
| الحقل | النوع | الوصف |
|---|---|---|
name | str | اسم المعامل |
type_hint | Any | تصنيف النوع (على سبيل المثال، str، torch.Tensor) |
default | Any | القيمة الافتراضية (إذا لم يتم تعيينها، فلا يوجد للباراميتر قيمة افتراضية) |
required | bool | ما إذا كان المعامل مطلوباً |
description | str | وصف قابل للقراءة من قِبل الإنسان |
kwargs_type | str | اسم المجموعة للمعاملات ذات الصلة (مثل "denoiser_input_fields") |
metadata | dict | معلومات إضافية اختيارية |
إنشاء InputParam مباشرة
from diffusers.modular_pipelines import InputParam
InputParam(
name="guidance_scale",
type_hint=float,
default=7.5,
description="Scale for classifier-free guidance.",
)استخدام قالب
InputParam.template("prompt")
# Equivalent to:
# InputParam(name="prompt", type_hint=str, required=True,
# description="The prompt or prompts to guide image generation.")تُعيّن القوالب name وtype_hint وdefault وrequired وdescription تلقائياً. يمكنك تجاوز أي حقل أو إضافة سياق باستخدام معامل note.
# Override the default value
InputParam.template("num_inference_steps", default=28)
# Add a note to the description
InputParam.template("prompt_embeds", note="batch-expanded")
# description becomes: "text embeddings used to guide the image generation. ... (batch-expanded)"OutputParam
OutputParam يصف مخرَجًا واحدًا من كتلة.
| الحقل | النوع | الوصف |
|---|---|---|
name | str | اسم المعامل |
type_hint | Any | تعريف النوع |
description | str | وصف قابل للقراءة من قِبل الإنسان |
kwargs_type | str | اسم المجموعة للمعاملات ذات الصلة |
metadata | dict | معلومات إضافية اختيارية |
إنشاء OutputParam مباشرة
from diffusers.modular_pipelines import OutputParam
OutputParam(name="image_latents", type_hint=torch.Tensor, description="Encoded image latents.")استخدام قالب
OutputParam.template("latents")
# Add a note to the description
OutputParam.template("prompt_embeds", note="batch-expanded")القوالب المتاحة
INPUT_PARAM_TEMPLATES وOUTPUT_PARAM_TEMPLATES معرّفة في modular_pipeline_utils.py. تتضمن هذه القوالب معلمات شائعة مثل prompt وimage وnum_inference_steps وlatents وprompt_embeds وغيرها. راجع المصدر للحصول على القائمة الكاملة لأسماء القوالب المتاحة.