# RFD4-Proteína

RFD4-Proteína هو نموذج مطابقة تدفق من مختبر بيكر ونفيديا لتصميم الجزيئات الحيوية. يقوم بتوليد تسلسلات البروتينات والبنى الذرية الكاملة معًا، مشروطًا بالسياق الجزيئي للحفاظ على: هدف الارتباط، أو نمط إنزيمي، أو رابطة، أو نقاط ساخنة، أو البنية الثانوية. يتم دمج محوّل مزدوج ومشفّر-فك تشفير ذاتي بواسطة جدولين [RFD4ProteinaScheduler](/docs/diffusers/v0.43.0/ar/api/schedulers/rfd4_proteina#diffusers.RFD4ProteinaScheduler)، أحدهما للهيكل العظمي والآخر للمتغيرات المحلية.

يستهلك خط الأنابيب متجهات الميزات المُعدّة. وتحويل ملف CIF مُعلَّم إلى تلك المتجهات، وإعادة المتجهات المُولَّدة إلى ملف CIF، هي معالجة مسبقة خاصة بالمجال وتوجد في حزمة [`rfd4-proteina-prep`](https://huggingface.co/nvidia/RFD4-Proteina-prep).

## مثال على الاستخدام

ثبّت حزمة الإعداد عند مراجعة ثابتة. فهي تحدد متجهات الميزات التي يستقبلها النموذج، لذا فإن تثبيتًا غير مثبّت سيؤدي إلى تغيير الهياكل المولّدة عند تحديث الحزمة.

```bash
pip install diffusers git+https://huggingface.co/nvidia/RFD4-Proteina-prep@c9959efdebd75ac7fe9129fbbf0e291a6e0487d5
```

```py
import torch
from huggingface_hub import hf_hub_download
from diffusers import RFD4ProteinaPipeline
from rfd4_proteina_prep import prepare_cif, write_cif

pipe = RFD4ProteinaPipeline.from_pretrained("nvidia/RFD4-Proteina-Diffusers", dtype=torch.bfloat16).to("cuda")

# An annotated CIF specifies what to hold fixed and what to design: here a PD-L1 target and a 50-120 residue binder.
input_cif = hf_hub_download("nvidia/RFD4-Proteina-Diffusers", "examples/protein_binder/input.cif")
features, atoms = prepare_cif(input_cif, seed=42, device=pipe.device)

# The masks and molecule tensors the pipeline always needs are arguments; the annotation tensors go in one mapping.
required = ["padding_mask", "is_in_context_conditioning", "supports_local_latent", "token_type", "atom37_mask"]
conditioning = {name: value for name, value in features.items() if name not in required}

output = pipe(
    padding_mask=features["padding_mask"],
    is_in_context_conditioning=features["is_in_context_conditioning"],
    supports_local_latent=features["supports_local_latent"],
    token_type=features["token_type"],
    atom37_mask=features["atom37_mask"],
    conditioning_features=conditioning,
    generator=torch.Generator("cuda").manual_seed(42),
)
write_cif(output, features, atoms, "design.cif")
```

## نصائح

* تحتوي مستودع النموذج على مدخلات مُعلَّمة وتصميم مُولَّد لكل مهمة تحت `examples/`: بروتين رابط، جسم مضاد، VHH، إنزيم، هياكل الدوافع، جزيء صغير رابط، غير مشروط، طي عكسي، وانتشار جزئي.
* مرّر `partial_t_bb_ca` و`partial_t_local_latents` مع أزمنة بداية ضمن `[0, 1)` لإعادة تصميم مدخل من بداية مُضجِبة، أو مرّر `inverse_folding=True` مع جعل كلا زمنَي البداية `0.0` للحفاظ على الهيكل الأساسي وتصميم التسلسل. يقوم كلاهما بتشفير المدخل، لذا يتطلبان إحداثيات `coords_nm` نظيفة ويرفضان الإحداثيات غير المحددة، وهي عادةً بقايا غير محلولة.
* عدد الخطوات هو طول إعداد خط الأنابيب `recycle_depths`، وهو 60 في الوصفة المنشورة (180 مرورًا للجذع). يمكنك تغيير الجدول الزمني عن طريق تمرير قائمة `recycle_depths` مختلفة عند إنشاء خط الأنابيب.
* لتوليد عدة تصاميم لكل مدخل، اضبط `num_designs_per_prompt` ومرّر مولّدًا مختلفًا لكل تصميم. يحتوي المخرَج على `batch * num_designs_per_prompt` صفوف، والصف `r` هو التصميم `r % num_designs_per_prompt` من صف المدخل `r // num_designs_per_prompt`.

  ```py
  generators = [torch.Generator("cuda").manual_seed(seed) for seed in range(8)]
  output = pipe(
      padding_mask=features["padding_mask"],
      is_in_context_conditioning=features["is_in_context_conditioning"],
      supports_local_latent=features["supports_local_latent"],
      token_type=features["token_type"],
      atom37_mask=features["atom37_mask"],
      conditioning_features=conditioning,
      num_designs_per_prompt=8,
      generator=generators,
  )
  ```

  تقرأ `write_cif` خصائص الصف الذي تكتبه، لذا كررها بالطريقة نفسها، باستخدام `repeat_interleave` بدلاً من `repeat`:

  ```py
  repeated = {k: v.repeat_interleave(8, dim=0) if torch.is_tensor(v) else v for k, v in features.items()}
  for row in range(8):
      write_cif(output, repeated, atoms, f"design_{row}.cif", row=row)
  ```

* قم بتحميل `torch.bfloat16` من أجل زيادة السرعة. تبقى حالة المُعيّن (sampler) وتضمينات الميزات (feature embeddings) في float32. قد يؤدي استخدام نوع بيانات (dtype) أو نواة (kernel) أو حجم دفعة (batch size) مختلف إلى تصميم مختلف لنفس البذرة (seed).
* البنية المولّدة ليست تصميمًا مُتحقَّقًا منه. أعد طيّها وقِسها للمهمة المقصودة.

## LoRA

النموذج المُطلَق هو نسخة LoRA مُكيَّفة بدقة بترتيب 32 (rank-32) من النموذج الأساسي المُدرَّب مسبقًا، وقد تم دمجها في الأوزان. يتوفر النموذج الأساسي والمُكيِّف (adapter) على مراجعة `pretrain-base` من مستودع النموذج، وتحمّل خط المعالجة المُكيِّف باستخدام `load_lora_weights` عبر `RFD4ProteinaLoraLoaderMixin`:

```py
pipe = RFD4ProteinaPipeline.from_pretrained(
    "nvidia/RFD4-Proteina-Diffusers", revision="pretrain-base", dtype=torch.bfloat16
).to("cuda")
pipe.load_lora_weights(
    "nvidia/RFD4-Proteina-Diffusers",
    revision="pretrain-base",
    subfolder="lora",
    weight_name="pytorch_lora_weights.safetensors",
)
```

## RFD4ProteinaPipeline[[diffusers.RFD4ProteinaPipeline]]

#### diffusers.RFD4ProteinaPipeline[[diffusers.RFD4ProteinaPipeline]]

```python
diffusers.RFD4ProteinaPipeline(transformer: RFD4ProteinaTransformer, vae: RFD4ProteinaAutoencoder, bb_ca_scheduler: RFD4ProteinaScheduler, local_latents_scheduler: RFD4ProteinaScheduler, recycle_depths: list[int] | None = None)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/rfd4_proteina/pipeline_rfd4_proteina.py#L68)

**المعاملات:**

transformer ([RFD4ProteinaTransformer](/docs/diffusers/v0.43.0/ar/api/models/rfd4_proteina_transformer#diffusers.RFD4ProteinaTransformer)) : مُزيل ضجيج السرعة للهيكل العظمي المشترك والكامن المحلي.

vae ([RFD4ProteinaAutoencoder](/docs/diffusers/v0.43.0/ar/api/models/rfd4_proteina_autoencoder#diffusers.RFD4ProteinaAutoencoder)) : مُشفِّر-المُفكِّك (Autoencoder) المرافق لنقطة التفتيش (checkpoint) الخاصة بمزيل الضوضاء.

bb_ca_scheduler ([RFD4ProteinaScheduler](/docs/diffusers/v0.43.0/ar/api/schedulers/rfd4_proteina#diffusers.RFD4ProteinaScheduler)) : يدمج إحداثيات الهيكل العظمي.

local_latents_scheduler ([RFD4ProteinaScheduler](/docs/diffusers/v0.43.0/ar/api/schedulers/rfd4_proteina#diffusers.RFD4ProteinaScheduler)) : يدمج الكمونيات المحلية.

recycle_depths (`list[int]`, *اختياري*) : جولات إعادة تدوير الجذع لكل خطوة إزالة الضوضاء. طولها هو العدد الافتراضي لخطوات الاستدلال. الافتراضي هو الجدول الزمني المُصدر المكوّن من 60 خطوة و180 جولة.

توليد الهياكل التسلسلات الجزيئية من الموترات الجزيئية المُعدّة.

يستهلك خط الأنابيب متجهات الميزات الناتجة عن تحضير مدخلات RFD4 (انظر حزمة `rfd4-proteina-prep` لملفات CIF الموثقة) ويعيد إحداثيات atom37 المفكوكة وهويات البقايا. الإحداثيات بالنانومتر.

#### __call__[[diffusers.RFD4ProteinaPipeline.__call__]]

```python
__call__(padding_mask: Tensor, is_in_context_conditioning: Tensor, supports_local_latent: Tensor, token_type: typing.Optional[torch.Tensor] = None, atom37_mask: typing.Optional[torch.Tensor] = None, coords_nm: typing.Optional[torch.Tensor] = None, conditioning_features: dict[str, typing.Any] | None = None, num_designs_per_prompt: int = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, partial_t_bb_ca: float | None = None, partial_t_local_latents: float | None = None, inverse_folding: bool = False, latents_bb_ca: typing.Optional[torch.Tensor] = None, latents_local_latents: typing.Optional[torch.Tensor] = None, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: collections.abc.Callable[[diffusers.pipelines.pipeline_utils.DiffusionPipeline, int, torch.Tensor, dict], dict | None] | None = None, callback_on_step_end_tensor_inputs: list[str] = ['bb_ca', 'local_latents'], output_type: str = 'pt', return_dict: bool = True)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/rfd4_proteina/pipeline_rfd4_proteina.py#L287)

**المعاملات:**

padding_mask (`torch.Tensor`) : قيمة منطقية `(batch, tokens)`، تكون صحيحة حيث يكون الرمز حقيقيًا وليس تعبئة.

is_in_context_conditioning (`torch.Tensor`) : قيمة منطقية `(batch, tokens)`، تكون صحيحة (true) للرموز المقدمة كسياق وتُترك دون تغيير.

supports_local_latent (`torch.Tensor`) : قيمة منطقية `(batch, tokens)`، تكون صحيحة (true) للرموز التي تحمل كامنًا محليًا. تتشارك الأقنعة الثلاثة جميعها الشكل والنفس (device) نفسه.

token_type (`torch.Tensor`، *اختياري*) : رموز أنواع الرموز `(batch, tokens)`.

atom37_mask (`torch.Tensor`، *اختياري*) : `(batch, tokens, 37)`، تكون القيمة صحيحة حيث يُستخدم خانة ذرة.

coords_nm (`torch.Tensor`، *اختياري*) : إحداثيات `(batch, tokens, 37, 3)` نظيفة للذرات الـ37 بالنانومتر، مطلوبة في الانتشار الجزئي والطي العكسي.

conditioning_features (`dict[str, Any]`، *اختياري*) : المتجهات المتبقية للبنية topology وشروط المعالجة تحت المفاتيح التي يصدرها المعالج المسبق. يجب أن يحتوي على شرط التسلسل، و`condition_sequence_1_residue`، و`molecule_iid`. يتم تحديد أي من المتجهات المتبقية تُقرأ من خلال إعداد الميزات الخاص بالنقطة الفاصلة checkpoint. وهو عبارة عن خرائط واحدة لأن المعالج المسبق يصدر حوالي 30 متجهًا اختياريًا بأسماء ثابتة، ولأن التوقيع الذي يحتوي على ذلك العدد من الحُجج سيربط خط الأنابيب pipeline بأسماء المعالج المسبق.

num_designs_per_prompt (`int`، القيمة الافتراضية `1`) : عدد التصاميم التي سيتم توليدها لكل صف من المدخلات. يتم تكرار المدخلات على محور الدفعة (batch)، لذا فإن المخرجات تحتوي على `batch * num_designs_per_prompt` صفًا، والصف `r` هو التصميم `r % num_designs_per_prompt` من صف المدخلات `r // num_designs_per_prompt`.

generator (`torch.Generator` أو `list[torch.Generator]`، *اختياري*) : مولّد واحد مختلف لكل صف من صفوف المخرجات، لتصاميم قابلة للتكرار. تتقدّم المولّدات وتُترك سلسلة PyTorch العشوائية العامة دون تغيير. احذفه للسحب من السلسلة العامة.

partial_t_bb_ca (`float`, *اختياري*) : وقت البدء في الفترة [0, 1) للعمود الفقري، للبدء من نسخة مُضجِمة من المدخل بدلاً من الضوضاء النقية. يُقدَّم مع `partial_t_local_latents`؛ ويتطلّب `coords_nm` و`atom37_mask`.

partial_t_local_latents (`float`، *اختياري*) : وقت البدء في [0، 1) للكائنات المحلية؛ راجع `partial_t_bb_ca`.

inverse_folding (`bool`، القيمة الافتراضية `False`) : يحافظ على العمود الفقري للإدخال ويصمم التسلسل. يتطلب قيمة صفرية لكل من أزمنة البدء الجزئية.

latents_bb_ca (`torch.Tensor`, *اختياري*) : حالة العمود الفقري الابتدائية المُولَّدة مسبقًا `(batch * num_designs_per_prompt, tokens, 3)`، لاستبدال الحالة التي كان من المفترض أن تُستخرج عشوائيًا في هذه الاستدعاء. يبقى الجدول الزمني دون تغيير. قدّمها معًا مع `latents_local_latents`.

latents_local_latents (`torch.Tensor`، *اختياري*) : محفزات محلية ابتدائية مُولّدة مسبقًا `(batch * num_designs_per_prompt, tokens, latent_dim)`.

attention_kwargs (`dict`، *اختياري*) : يُمرَّر إلى المحوِّل؛ `scale` يضبط مقياس LoRA.

callback_on_step_end (`Callable`، *اختياري*) : يُستدعى على شكل `callback_on_step_end(pipeline, step, timestep, callback_kwargs)` بعد كل خطوة. يحتوي `callback_kwargs` على الموترات المذكورة في `callback_on_step_end_tensor_inputs`؛ وقد يحل قاموس مُعاد محل `"bb_ca"` و`"local_latents"`.

output_type (`str`، القيمة الافتراضية هي `"pt"`) : يعيد `"pt"` تينسورات torch ويعيد `"np"` مصفوفات numpy.

callback_on_step_end_tensor_inputs (`list[str]`، القيمة الافتراضية هي `["bb_ca", "local_latents"]`) : المصفوفات (Tensors) المُمرَّرة إلى الدالة الاستدعائية (callback): `"bb_ca"`، `"local_latents"`، `"last_clean_bb_ca"`، `"last_clean_local_latents"`، `"sequence_logits"`، `"insertion_logits"`.

return_dict (`bool`، القيمة الافتراضية `True`) : إرجاع مخرجات مُنمّطة، أو مجموعة (tuple) من حقولها غير الفارغة (non-None).

**يعيد:** `RFD4ProteinaPipelineOutput` أو `tuple`

متجهات atom37 المُفكّكة (`coords_nm` بالنانومتر، `residue_type`، `emit_mask`، `atom_mask`)، والحالة الضجيجية النهائية، وآخر تقدير نظيف، وأخيرًا قيم logits للتسلسل والإدراج.

توليد الهياكل والتسلسلات من الموترات الجزيئية المُعدّة.

أمثلة:
```py
>>> import torch
>>> from diffusers import RFD4ProteinaPipeline
>>> from rfd4_proteina_prep import prepare_cif, write_cif

>>> pipe = RFD4ProteinaPipeline.from_pretrained("nvidia/RFD4-Proteina-Diffusers", dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> features, atoms = prepare_cif("input.cif", seed=42, device=pipe.device)
>>> required = ["padding_mask", "is_in_context_conditioning", "supports_local_latent", "token_type"]
>>> required += ["atom37_mask"]
>>> output = pipe(
...     padding_mask=features["padding_mask"],
...     is_in_context_conditioning=features["is_in_context_conditioning"],
...     supports_local_latent=features["supports_local_latent"],
...     token_type=features["token_type"],
...     atom37_mask=features["atom37_mask"],
...     conditioning_features={name: value for name, value in features.items() if name not in required},
...     generator=torch.Generator("cuda").manual_seed(42),
... )
>>> write_cif(output, features, atoms, "design.cif")
```

#### check_inputs[[diffusers.RFD4ProteinaPipeline.check_inputs]]

```python
check_inputs(padding_mask, is_in_context_conditioning, supports_local_latent, atom37_mask, coords_nm, conditioning_features, num_designs_per_prompt, generator, partial_t, inverse_folding, latents, callback_on_step_end_tensor_inputs, output_type)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/rfd4_proteina/pipeline_rfd4_proteina.py#L130)

تحقّق من أقنّة الجزيئات، ومولّدات التصميم لكل تصميم، والانتشار الجزئي، والنداءات العكسية.

#### noise_backbone[[diffusers.RFD4ProteinaPipeline.noise_backbone]]

```python
noise_backbone(target_backbone, bb_mask, conditioning, generators, index)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/rfd4_proteina/pipeline_rfd4_proteina.py#L278)

أضف ضوضاء إلى الهيكل المحفوظ حتى الوقت المجدول للخطوة `index`، من أجل الطي العكسي.

#### prepare_latents[[diffusers.RFD4ProteinaPipeline.prepare_latents]]

```python
prepare_latents(bb_mask: Tensor, latent_mask: Tensor, conditioning: dict[str, torch.Tensor], generators: list[torch.Generator] | None, clean_bb: typing.Optional[torch.Tensor] = None, clean_latents: typing.Optional[torch.Tensor] = None, start_times: tuple[float, float] | None = None)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/rfd4_proteina/pipeline_rfd4_proteina.py#L243)

ارسم الحالة الابتدائية: ضوضاء نقية، أو الإدخال النظيف المُضاف إليه ضوضاء حتى `start_times` (الهيكل الأساسي، الكمونيات). يمكن إهمال `clean_latents` عندما يكون زمن البدء الكموني صفراً.

تتبع عمليات السحب ترتيب المُعيّن الأصلي في كل مولّد صف: ففي التوليد الكامل، تأتي ضوضاء الهيكل الأساسي وإزاحاتها العشوائية قبل ضوضاء الكمون، بينما في الانتشار الجزئي، تُسحب كلتا الضوضاء قبل الإزاحات.

## RFD4ProteinaPipelineOutput[[diffusers.pipelines.rfd4_proteina.pipeline_output.RFD4ProteinaPipelineOutput]]

#### diffusers.pipelines.rfd4_proteina.pipeline_output.RFD4ProteinaPipelineOutput[[diffusers.pipelines.rfd4_proteina.pipeline_output.RFD4ProteinaPipelineOutput]]

```python
diffusers.pipelines.rfd4_proteina.pipeline_output.RFD4ProteinaPipelineOutput(coords_nm: Tensor, residue_type: Tensor, emit_mask: Tensor, atom_mask: Tensor, bb_ca: Tensor, local_latents: Tensor, clean_bb_ca: Tensor, clean_local_latents: Tensor, sequence_logits: Tensor, insertion_logits: Tensor)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/rfd4_proteina/pipeline_output.py#L12)

**المعاملات:**

coords_nm (`torch.Tensor`) : إحداثيات الذرّات37 المُفكّكة `(B, N, 37, 3)`.

residue_type (`torch.Tensor`) : فهارس مفردات البقايا `(B, N)`؛ القيمة -1 حيث لا تُصدر أي بقايا.

emit_mask (`torch.Tensor`) : قناع منطقي `(B, N)` للرموز التي تم تصميمها.

atom_mask (`torch.Tensor`) : قناع منطقي `(B, N, 37)` للذرات الصالحة.

bb_ca (`torch.Tensor`) : الحالة النهائية للعمود الفقري `(B, N, 3)` بالنانومتر.

local_latents (`torch.Tensor`) : الحالة المحلية الكامنة النهائية `(B, N, D)`.

clean_bb_ca (`torch.Tensor`) : تنبؤ الهيكل العظمي بالحالة النظيفة في خطوة إزالة الضوضاء الأخيرة.

clean_local_latents (`torch.Tensor`) : التنبؤ بالحالة النظيفة المحلية الكامنة في خطوة إزالة الضوضاء الأخيرة.

sequence_logits (`torch.Tensor`) : قيم اللوجيت المتبقية النهائية لكل رمز `(B, N, 147)`.

insertion_logits (`torch.Tensor`) : تنبؤات الإدراج النهائية `(B, N, N)` للحوافز غير المؤرشفة.

نتائج الاستدلال الجزيئي. الإحداثيات بالنانومتر.