stack retrieval augmented generation

الجيل المعزز للاسترجاع (RAG) لـ Watsonx على IBM Cloud

تقوم البنية القابلة للنشر التالية بأتمتة عملية نشر نموذج الذكاء الاصطناعي العام على IBM Cloud، بما في ذلك كل البنية التحتية الأساسية لـ IBM Cloud وWatsonX. تقوم هذه البنية بتنفيذ أفضل الممارسات لنشر Watsonx gen AI Pattern على IBM Cloud، كما هو موضح في البنية المرجعية.

توفر هذه البنية القابلة للنشر أساسًا شاملاً للثقة وإمكانية المراقبة والأمان والامتثال التنظيمي. تقوم البنية بتكوين حساب IBM Cloud للتوافق مع إعدادات التوافق. كما أنه ينشر خدمات الإدارة الرئيسية وإدارة الأسرار والبنية التحتية لدعم التكامل المستمر (CI)، والتسليم المستمر (CD)، وخطوط أنابيب الامتثال المستمر (CC) للإدارة الآمنة لدورة حياة التطبيق. كما أنه ينشر مجموعة خدمات WatsonX وIBM Cloud Elasticsearch لتسهيل نمط RAG. تسهل خطوط الأنابيب هذه نشر التطبيق، والتحقق من نقاط الضعف وقابلية التدقيق، وتساعد على ضمان النشر الآمن والموثوق لتطبيقات الذكاء الاصطناعي التوليدية على IBM Cloud.

الاختلافات

يتوفر شكلان مختلفان لهذه البنية القابلة للنشر:

1. الاختلاف الأساسي:

   • مشروع Code Engine: يوفر مشروع Code Engine، مما يوفر نظامًا أساسيًا مُدارًا بالكامل للتطبيقات الموجودة في حاويات.
   • نشر التطبيق: نشر التطبيق على مشروع Code Engine المتوفر.
   • Elasticsearch Enterprise: يوفر مثيلًا لمؤسسة Elasticsearch لإمكانيات البحث والتحليلات.

2. الاختلاف القياسي:

   • IBM Cloud OpenShift Cluster: يوفر مجموعة IBM Cloud OpenShift
   • البنية التحتية لشبكة VPC: يقوم بإعداد البنية الأساسية لشبكة VPC الأساسية لدعم مجموعة OpenShift.
   • نشر التطبيق: نشر التطبيق على مجموعة OpenShift المتوفرة.
   • خطة ElasticSearch Platinum: تستفيد من الخطة البلاتينية لـ ElasticSearch، والتي تتضمن نموذج ELSER لإمكانيات توليد المتجهات المتقدمة.

الهدف والفوائد

تم تصميم هذه البنية القابلة للنشر لعرض النشر الآلي بالكامل لتطبيق الجيل المعزز للاسترجاع من خلال IBM Cloud Projects. فهو يوفر أساسًا مرنًا وقابلاً للتخصيص لتطبيقات Watsonx الخاصة بك على IBM Cloud. تقوم هذه البنية بنشر نموذج التطبيق التالي بشكل افتراضي.

باستخدام هذه البنية، يمكنك تسريع النشر وتخصيصه لتلبية احتياجات عملك وأهداف مؤسستك.

يمكن أن تساعدك هذه البنية على تحقيق الأهداف التالية:

• إنشاء الثقة: تقوم البنية بتكوين حساب IBM Cloud للتوافق مع إعدادات الامتثال التي تم تحديدها في إطار عمل IBM Cloud for Financial Services، وملف تعريف AI Security Guardrails 2.0.
• ضمان إمكانية الملاحظة: توفر البنية إمكانية الملاحظة من خلال نشر الخدمات مثل IBM Log Analysis، وIBM Monitoring، وIBM Activity Tracker، والاحتفاظ بالسجل من خلال مستودعات IBM Cloud Object Storage.
• تنفيذ الأمان: تقوم البنية بنشر نسخ IBM Key Protect وIBM Secrets Manager.
• تحقيق الامتثال التنظيمي: تقوم البنية بتنفيذ مسارات CI وCD وCC إلى جانب IBM Security Compliance Center (SCC) لإدارة دورة حياة التطبيق بشكل آمن.

قبل أن تبدأ

قبل نشر البنية القابلة للنشر، تأكد من إكمال الإجراءات التالية:

مهم

يجب عليك استخدام مفتاح API المرتبط بمستخدم. لا يمكنك استخدام مفاتيح معرف الخدمة أو الملفات الشخصية الموثوقة.

• قم بإنشاء مفتاح API في الحساب المستهدف بالأذونات المطلوبة. الحساب الهدف هو الحساب الذي يستضيف الموارد التي يتم نشرها بواسطة هذه البنية. لمزيد من المعلومات، راجع إدارة مفاتيح واجهة برمجة تطبيقات المستخدم.

  • انسخ قيمة مفتاح API. تحتاجه في الخطوات التالية.

  • في بيئات الاختبار أو التقييم، يمكنك منح دور المسؤول على الخدمات التالية

    • خدمة هوية IAM. بالإضافة إلى دور المسؤول، عند نشر الاختلاف القياسي للبنية القابلة للنشر، قم بتعيين دور User API key creator بشكل صريح، لأنه إلزامي لنشر مجموعة OpenShift بنجاح.
    • جميع الخدمات الممكنة للهوية والوصول.
    • كافة خدمات إدارة الحسابات.

    لكي يكون نطاق الوصول أكثر تقييدًا لبيئة الإنتاج، راجع الحد الأدنى لمستوى الأذونات في علامة تبويب الأذونات الخاصة بهذه البنية القابلة للنشر.

• إنشاء وتصدير مفتاح التوقيع. هذه الخطوة اختيارية لنشر التطبيق، ولكنها مطلوبة لإكمال مسار CI بنجاح. بدون هذه الخطوة، سيقوم مسار CI بالإبلاغ عن الفشل بسبب خطوة التوقيع المفقودة. إذا كنت تريد إنشاء مفتاح توقيع وتصديره، فاتبع الخطوات التالية:
  • قم بإنشاء مفتاح توقيع أو الحصول عليه عن طريق تشغيل الأمر gpg --gen-key بدون عبارة مرور (إذا لم تكن منتهية الصلاحية، يمكنك استخدام مفتاح تم إنشاؤه مسبقًا).
  • قم بتصدير مفتاح التوقيع عن طريق تشغيل الأمر gpg --export-secret-key <email address> | base64 . لمزيد من المعلومات حول تخزين المفتاح، راجع إنشاء مفتاح GPG.
  • انسخ قيمة المفتاح ولاحظ المفتاح لوقت لاحق.

إضافة الهندسة المعمارية إلى المشروع

1. انتقل إلى صفحة تفاصيل نموذج إنشاء الاسترجاع المعزز (RAG) في سجل مجتمع كتالوج IBM Cloud.
2. حدد أحدث إصدار للمنتج في قسم الهندسة المعمارية.
3. حدد الاختلاف Basic أو Standard . يشير إلى قسم الاختلافات أعلاه للحصول على مزيد من التفاصيل حول الاختلافين.
4. انقر فوق إضافة إلى المشروع
5. حدد إنشاء جديد وأدخل التفاصيل التالية:

   1. أضف اسمًا ووصفًا.

   2. حدد المنطقة ومجموعة الموارد للمشروع. على سبيل المثال، لأغراض التقييم، يمكنك تحديد المنطقة الأقرب إليك ومجموعة الموارد الافتراضية.

      لمزيد من المعلومات حول بنيات حساب المؤسسة، راجع المستند التقني لحساب الإدارة المركزية.

   3. أدخل اسم التكوين. على سبيل المثال، "RAG" أو "dev" أو "prod". يمكن أن يساعدك الاسم لاحقًا في مطابقة هدف النشر الخاص بك.

6. انقر فوق إنشاء

تكوين المكدس الخاص بك

يمكنك الآن إنشاء التكوين الخاص بك عن طريق تعيين المتغيرات.

1. من لوحة الأمان ، حدد طريقة المصادقة التي تريد استخدامها لنشر البنية الخاصة بك.

   قم بإضافة مفتاح واجهة برمجة التطبيقات (API) من المتطلبات الأساسية الموجودة في قبل البدء.

2. في علامة التبويب الأمان > المصادقة في قسم التكوين ، حدد مفتاح واجهة برمجة التطبيقات.

3. أدخل قيم الحقول المطلوبة من علامة التبويب مطلوب .

   1. أدخل بادئة. تتم إضافة هذه البادئة إلى بداية اسم معظم الموارد التي تم إنشاؤها بواسطة البنية القابلة للنشر. تساعد البادئة على التأكد من أن أسماء الموارد فريدة، وتتجنب التعارضات مع الموارد الأخرى في نفس الحساب.

4. قم بمراجعة قيم الحقول الاختيارية من علامة التبويب اختياري :

   1. حدد متغير signing_key من المتطلبات الأساسية في قبل البدء.
   2. قم بمراجعة متغيرات الإدخال الأخرى.

5. انقر فوق حفظ . بعد التحقق من صحة قيم الإدخال، يتغير الزر إلى عرض تكوينات المكدس .

نشر البنية

يمكنك نشر بنية مكدسة قابلة للنشر من خلال وحدة تحكم IBM Cloud بطريقتين:

• باستخدام النشر التلقائي : يمكن أن تكون طريقة النشر مفيدة لبيئات العرض التوضيحي وغير الإنتاجية. من خلال النشر التلقائي، يتم التحقق من صحة كافة تكوينات أعضاء المكدس ومن ثم الموافقة عليها ونشرها.

  يمكنك التحقق من إعداد النشر التلقائي لمشروعك بالنقر فوق إدارة > الإعدادات . من خلال تشغيل النشر التلقائي، يمكنك تمكين الإعداد لجميع التكوينات في المشروع.

• بشكل فردي عن طريق نشر تكوين كل عضو. الطريقة اليدوية مناسبة للمشاريع التي تحتوي على بيئات إنتاج. يمكنك مراجعة التغييرات في تكوين كل عضو قبل تشغيل الأتمتة.

نصيحة

بعد الموافقة على التكوين، قد تتلقى رسالة الخطأ "تعذر التحقق من صحة التكوين الخاص بك". لحل المشكلة، قم بتحديث المتصفح الخاص بك.

قد ترى إشعارات "الإصدار الجديد متوفر" في عمود " يحتاج إلى اهتمام" في تكوين مشروعك. يمكنك تجاهل هذه الرسائل لأنها لا تمنعك من نشر المكدس.

نشر البنية باستخدام النشر التلقائي

1. انقر فوق أيقونة الخيارات بجوار عرض تكوينات المكدس ثم انقر فوق التحقق من الصحة .

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

نشر تكوين كل عضو

1. في مشروعك، انقر فوق علامة التبويب تكوينات .

   إذا لم يتم وضع علامة على تكوين العضو الأول للمكدس ( Account Infrastructure Base ) على أنه جاهز للتحقق ، فقم بتحديث الصفحة في المستعرض الخاص بك.

2. انقر فوق التحقق من صحة حالة المسودة في الصف Account Infrastructure Base .

3. قم بالموافقة على التكوين وانقر فوق "نشر" بعد اكتمال عملية التحقق بنجاح.

4. بعد نشر تكوين العضو الأولي، يمكنك التحقق من صحة تكوين العضو المتبقي ونشره في نفس الوقت. كرر خطوات النشر هذه لكل تكوين عضو في البنية.

يتم الآن نشر البنية القابلة للنشر لنمط إنشاء الاسترجاع المعزز في الحساب الهدف.

مراقبة البناء ونشر التطبيق

مراقبة خط أنابيب CI

بعد نشر البنية، يبدأ نموذج التطبيق في خدمة DevOps المتوفرة حديثًا.

لمراقبة إنشاء التطبيق ونشره، اتبع الخطوات التالية:

1. قم بالوصول إلى عرض DevOps Toolchains من خلال الانتقال إلى DevOps > Toolchains في الحساب المستهدف.
2. حدد مجموعة الموارد والمنطقة التي تم نشر البنية التحتية فيها. يعتمد اسم مجموعة الموارد على البادئة ومدخلات resource_group_name الخاصة بالبنية القابلة للنشر.
3. حدد RAG Sample App-CI-Toolchain .
4. في عرض سلسلة الأدوات، حدد خط أنابيب ci في خط أنابيب التسليم.
5. ابحث عن حالة تنفيذ خط أنابيب CI في قسم rag-webhook-trigger .

التحقق من تطبيق العينة

• نشر Code Engine (أساسي): بعد اكتمال مسار CI، يمكنك الوصول إلى التطبيق في مشروع Code Engine الذي تم إنشاؤه.
• نشر OpenShift (قياسي):
  1. في مشروعك، انقر فوق علامة التبويب تكوينات .
  2. انقر فوق Workload - Sample RAG App Configuration .
  3. في علامة التبويب Outputs ، يتم إدراج عنوان URL للتطبيق المنشور ضمن مخرجات sample_app_public_url .

استكشاف الأخطاء وإصلاحها

لماذا يفشل نشر IBM Cloud Secrets Manager الخاص بي؟

لتقليل التكاليف، تنشر الأتمتة خطة تسعير تجريبية لبرنامج Secrets Manager. يمكنك إنشاء نسخة تجريبية واحدة فقط من Secrets Manager. يمكنك نشر مثيل الخطة القياسية لبرنامج Secrets Manager من الإعدادات الاختيارية للمكدس.

لإصلاح هذه المشكلة، قم بحذف النسخة التجريبية. بعد الحذف، قم أيضًا بحذف الخدمة من حالة الاسترداد.

في IBM Cloud، عندما تقوم بحذف أحد الموارد، فإنه لا يختفي على الفور. وبدلاً من ذلك، فإنه يدخل في حالة الاسترداد، حيث يبقى لفترة قصيرة (عادةً 7 أيام) قبل أن يتم حذفه نهائيًا. أثناء حالة الاسترداد، يمكنك استرداد المورد، إذا لزم الأمر.

قم بتشغيل أوامر IBM Cloud CLI التالية لحذف الخدمة من حالة الاسترداد.

يسرد الأمر الأول كافة الموارد الموجودة في حالة الاسترداد.

 # List all the resources in reclamation state with its reclamation ID
ibmcloud resource reclamations

ابحث عن معرف الاسترداد لخدمة Secrets Manager. استخدم هذا المعرف في الأمر التالي.

ibmcloud resource reclamation-delete < reclamation-id >

لماذا يفشل النشر عند إنشاء خصائص خط الأنابيب؟

يمكن أن تحدث هذه المشكلة تحديدًا عندما يكون عمر نشر ALM/toolchain أكثر من 14 يومًا وتم إلغاء نشر/إعادة نشر تكوين التطبيق. ويرجع ذلك إلى أن خدمة التسليم المستمر مطلوبة لإنشاء خصائص خطوط الأنابيب وحذفها، ويحدث النشر في حالة عدم وجود خدمة القرص المضغوط. نحن نعمل على حل طويل الأمد لهذا الخطأ، ولكن في هذه الأثناء يمكن تخفيفه من خلال ضمان وجود خدمة الأقراص المضغوطة في مجموعة الموارد حيث من المتوقع إنشاء سلاسل الأدوات.

ستحدث المشكلة في Workload - Sample RAG App Configuration ، في كل من Code Engine وOCP. سيحتوي الخطأ عادةً على هذه الرسالة:

 "errors": [
  {
    "code": 403,
    "message": "Continuous Delivery service required"
  }
]

خيارات التخصيص

العديد من التخصيصات ممكنة مع هذه البنية. هذه بعض الخيارات الشائعة.

تحرير تكوينات الأعضاء

يتضمن كل تكوين عضو عددًا كبيرًا من معلمات الإدخال. يمكنك تحرير التكوين لتغيير القيم الافتراضية.

على سبيل المثال، من خلال تحرير تكوين العضو، يمكنك إنجاز هذه الأشياء:

• ضبط إعدادات الحساب
• نشر المزيد من مكونات Watson، مثل watsonx.governance
• النشر إلى مجموعة موارد موجودة
• إعادة استخدام مفاتيح حماية المفاتيح الموجودة
• إعادة استخدام نسخ خدمة IBM Cloud الموجودة (Secrets Manager، key Protect، إعلامات الأحداث، خدمات Watsonx)
• اضبط معلمات مشروع Code Engine المتوفر لديك أو مجموعة OpenShift لتلبية المتطلبات المحددة.

لتحرير تكوين العضو، حدد تحرير من أيقونة الخيارات في صف تكوين العضو.

إزالة التكوينات من المكدس

يمكنك إزالة تكوين عضو من المكدس الذي لا تعتمد عليه التكوينات الأخرى.

يمكنك إزالة التكوينات التالية في هذه البنية:

• مركز الأمن والتحكم
• نموذج لتكوين تطبيق RAG

لإزالة تكوين عضو، حدد إزالة من المكدس من أيقونة الخيارات في صف تكوين العضو.

إدارة متغيرات المدخلات والمخرجات

يمكنك إضافة أو إزالة متغيرات الإدخال والإخراج على مستوى المكدس باتباع الخطوات التالية:

1. في وحدة تحكم IBM Cloud، انقر فوق شارة قائمة التنقل > المشاريع .
2. انقر فوق المشروع ذو البنية المكدسة القابلة للنشر التي تريد تحديثها.
3. انقر فوق علامة التبويب تكوينات .
4. حدد تكوين العضو.
5. من نافذة التفاصيل المنشورة، يمكنك ترقية أي من مدخلات أو مخرجات التكوين.

توفير انتقائي لموارد المراقبة

يمكنك توفير موارد إمكانية المراقبة بشكل انتقائي مثل مسارات وأهداف تعقب النشاط، ومثيلات المراقبة السحابية باتباع الخطوات التالية:

1. في وحدة تحكم IBM Cloud، انقر فوق شارة قائمة التنقل > المشاريع .
2. انقر فوق المشروع ذو البنية المكدسة القابلة للنشر التي تريد تحديثها.
3. انقر فوق علامة التبويب تكوينات .
4. انتقل إلى التكوينات : قم بالوصول إلى تكوين "Essential Security - Logging Monitoring Activity Tracker" من خلال النقر عليه.
5. تحرير تكوين العضو : في الجانب الأيمن العلوي، انقر على 3 نقاط، ثم حدد خيار تحرير للوصول إلى صفحة تكوين العضو.
6. تحديد موقع المتغيرات الاختيارية : ضمن علامة التبويب الاختيارية، ستجد إعدادات المتغير المحددة.
7. من نافذة التفاصيل المنشورة، يمكنك تمكين أو تعطيل توفير موارد مراقبة محددة. على سبيل المثال:
   • مثيل IBM Cloud Logs ( cloud_logs_provision ): قم بتعيين هذا لتوفير أو تخطي توفير مثيل IBM Cloud Logs.
   • مثيل IBM Cloud Monitoring ( cloud_monitoring_provision ): قم بتعيين هذا لتوفير أو تخطي التزويد لطبعة مراقبة IBM السحابية.
   • توجيه الأحداث من متتبع النشاط إلى مخزن الكائنات ( enable_at_event_routing_to_cos_bucket ): اضبط هذا لتمكين أو تعطيل توجيه الأحداث من متتبع النشاط إلى حاوية تخزين الكائنات.
   • توجيه الأحداث من متتبع النشاط إلى السجلات السحابية ( enable_at_event_routing_to_cloud_logs ): اضبط هذا لتمكين أو تعطيل توجيه الأحداث من متتبع النشاط إلى السجلات السحابية.
8. بعد إجراء التغييرات اللازمة، انقر فوق حفظ، وتحقق من صحة الإعدادات، ثم قم بالنشر لتطبيق التكوين المحدث.

مشاركة الحزم المكدسة المعدلة من خلال كتالوج IBM Cloud الخاص

بعد أن تقوم بتعديل البنية القابلة للنشر الخاصة بك في المشروعات، يمكنك مشاركتها مع الآخرين من خلال كتالوج IBM Cloud الخاص. لمشاركة البنية القابلة للنشر، اتبع الخطوات الواردة في مشاركة البنية القابلة للنشر في مؤسستك.

تخصيص التطبيق الخاص بك

يمكنك استخدام التعليمات البرمجية الخاصة بنموذج الأتمتة هذا كدليل لتخصيص نموذج التطبيق لتلبية متطلباتك. الكود متاح على https://github.com/terraform-ibm-modules/terraform-ibm-rag-sample-da.

لاستخدام التطبيق الخاص بك، قم بإزالة Workload - Sample RAG App Configuration من المكدس. تكوين العضو هذا خاص بالتطبيق النموذجي الافتراضي.

إلغاء نشر المكدس والبنية التحتية

1. تنظيف التكوين

   هذه الخطوة اختيارية إذا كنت تخطط لتدمير جميع موارد Watson. يتم حذف العناصر التي تم إنشاؤها بواسطة التطبيق كجزء من إلغاء نشر موارد Watson.

   اتبع الخطوات الموضحة في ملف cleanup.md لإزالة التكوين الخاص بالتطبيق النموذجي.

2. احذف الموارد التي أنشأتها سلسلة أدوات CI

   لا يتم إتلاف الموارد التالية، التي تم إنشاؤها بواسطة سلسلة الأدوات، كجزء من إلغاء نشر المكدس في المشروع.

   • مشروع محرك الكود
     • قم بحذف مشروع مشغل التعليمات البرمجية الذي تم إنشاؤه للتطبيق النموذجي.
   • مساحة اسم تسجيل الحاوية
     • احذف مساحة اسم تسجيل الحاوية التي أنشأتها سلسلة CI.

3. حذف المشروع.

   لإلغاء نشر البنية الأساسية التي تم تكوينها بواسطة البنية القابلة للنشر، اتبع الخطوات الموجودة في حذف مشروع في مستندات IBM Cloud.