Diffusers documentation

قوالب التوثيق التلقائي والمعاملات

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

قوالب التوثيق التلقائي والمعاملات

يحتوي كل 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 يصف مدخلًا واحدًا إلى كتلة.

الحقلالنوعالوصف
namestrاسم المعامل
type_hintAnyتصنيف النوع (على سبيل المثال، str، torch.Tensor)
defaultAnyالقيمة الافتراضية (إذا لم يتم تعيينها، فلا يوجد للباراميتر قيمة افتراضية)
requiredboolما إذا كان المعامل مطلوباً
descriptionstrوصف قابل للقراءة من قِبل الإنسان
kwargs_typestrاسم المجموعة للمعاملات ذات الصلة (مثل "denoiser_input_fields")
metadatadictمعلومات إضافية اختيارية

إنشاء 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 يصف مخرَجًا واحدًا من كتلة.

الحقلالنوعالوصف
namestrاسم المعامل
type_hintAnyتعريف النوع
descriptionstrوصف قابل للقراءة من قِبل الإنسان
kwargs_typestrاسم المجموعة للمعاملات ذات الصلة
metadatadictمعلومات إضافية اختيارية

إنشاء 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 وغيرها. راجع المصدر للحصول على القائمة الكاملة لأسماء القوالب المتاحة.

Update on GitHub