diffusers/main/ar/modular_diffusers/auto_docstring.md

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

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