البرنامج التعليمي: إنشاء تطبيق للجيل المعزز للاسترداد في Azure App Service باستخدام Azure OpenAI وAzure الذكاء الاصطناعي Search (Spring Boot)

في هذا البرنامج التعليمي، ستقوم بإنشاء تطبيق Java Retrieval Augmented Generation (RAG) باستخدام Spring Boot وAzure OpenAI وAzure الذكاء الاصطناعي Search ونشره في Azure App Service. يوضح هذا التطبيق كيفية تنفيذ واجهة دردشة تسترد المعلومات من مستنداتك الخاصة والاستفادة من خدمات Azure الذكاء الاصطناعي لتوفير إجابات دقيقة وواعية بالسياق مع اقتباسات مناسبة. يستخدم الحل الهويات المدارة للمصادقة بدون كلمة مرور بين الخدمات.

تلميح

بينما يستخدم هذا البرنامج التعليمي Spring Boot، تنطبق المفاهيم الأساسية لبناء تطبيق RAG باستخدام Azure OpenAI وAzure الذكاء الاصطناعي Search على أي تطبيق ويب Java. إذا كنت تستخدم خيار استضافة مختلف على App Service، مثل Tomcat أو JBoss EAP، يمكنك تكييف أنماط المصادقة واستخدام Azure SDK الموضح هنا مع إطار العمل المفضل لديك.

في هذا البرنامج التعليمي، تتعلم كيفية:

• انشر تطبيق Spring Boot الذي يستخدم نمط RAG مع خدمات Azure الذكاء الاصطناعي.
• تكوين Azure OpenAI وAzure الذكاء الاصطناعي Search للبحث المختلط.
• قم بتحميل المستندات وفهرستها لاستخدامها في تطبيقك المشغل الذكاء الاصطناعي.
• استخدم الهويات المدارة للاتصال الآمن من خدمة إلى خدمة.
• اختبر تنفيذ RAG محليا باستخدام خدمات الإنتاج.

نظرة عامة على الهندسة

قبل البدء في النشر، من المفيد فهم بنية التطبيق الذي ستقوم بإنشائه. الرسم التخطيطي التالي من نمط Custom RAG ل Azure الذكاء الاصطناعي Search:

في هذا البرنامج التعليمي، يهتم تطبيق Blazer في App Service بكل من تجربة المستخدم للتطبيق وخادم التطبيق. ومع ذلك، فإنه لا يقوم بإجراء استعلام معرفي منفصل إلى Azure الذكاء الاصطناعي Search. بدلا من ذلك، يخبر Azure OpenAI بالقيام بالاستعلام المعرفي لتحديد Azure الذكاء الاصطناعي Search كمصدر بيانات. توفر هذه البنية العديد من المزايا الرئيسية:

• التوجيه المتكامل: تجعل قدرات التوجيه المتكاملة في Azure الذكاء الاصطناعي Search من السهل والسريع استيعاب جميع مستنداتك للبحث، دون الحاجة إلى المزيد من التعليمات البرمجية لإنشاء عمليات التضمين.
• الوصول المبسط لواجهة برمجة التطبيقات: باستخدام نمط Azure OpenAI On Your Data مع Azure الذكاء الاصطناعي Search كمصدر بيانات لإكمال Azure OpenAI، ليست هناك حاجة لتنفيذ البحث عن المتجهات المعقدة أو إنشاء التضمين. إنه مجرد استدعاء واجهة برمجة تطبيقات واحد ويتعامل Azure OpenAI مع كل شيء، بما في ذلك الهندسة السريعة وتحسين الاستعلام.
• قدرات البحث المتقدمة: يوفر التوجيه المتكامل كل ما هو مطلوب للبحث المختلط المتقدم مع إعادة التدوير الدلالي، والذي يجمع بين نقاط القوة في مطابقة الكلمات الأساسية، وتشابه المتجهات، وترتيب مدعوم الذكاء الاصطناعي.
• دعم الاقتباس الكامل: تتضمن الاستجابات تلقائيا اقتباسات لمستندات المصدر، ما يجعل المعلومات قابلة للتحقق منها وقابلة للتتبع.

المتطلبات الأساسية

• حساب Azure مع اشتراك نشط - إنشاء حساب مجانا.
• حساب GitHub لاستخدام GitHub Codespaces - تعرف على المزيد حول GitHub Codespaces.

1. افتح العينة باستخدام Codespaces

أسهل طريقة للبدء هي باستخدام GitHub Codespaces، والتي توفر بيئة تطوير كاملة مع جميع الأدوات المطلوبة المثبتة مسبقا.

1. انتقل إلى مستودع GitHub في https://github.com/Azure-Samples/app-service-rag-openai-ai-search-java.

2. حدد الزر Code ، وحدد علامة التبويب Codespaces ، وانقر فوق Create codespace على main.

3. انتظر بضع لحظات حتى تتم تهيئة Codespace. عندما تكون جاهزا، سترى بيئة VS Code مكونة بالكامل في متصفحك.

2. نشر نموذج البنية

1. في المحطة الطرفية، سجل الدخول إلى Azure باستخدام Azure Developer CLI:

   azd auth login
   

   اتبع الإرشادات لإكمال عملية المصادقة.

2. توفير موارد Azure باستخدام قالب AZD:

   azd provision
   

3. عند المطالبة، قدم الإجابات التالية:

   السؤال	إجابة
   أدخل اسم بيئة جديد:	اكتب اسم فريد.
   حدد اشتراك Azure لاستخدامه:	اختر الاشتراك.
   اختر مجموعة موارد لاستخدامها:	اختر إنشاء مجموعة موارد جديدة.
   حدد موقعا لإنشاء مجموعة الموارد في:	حدد أي منطقة. سيتم إنشاء الموارد فعليا في شرق الولايات المتحدة 2.
   أدخل اسما لمجموعة الموارد الجديدة:	اكتب Enter.

4. انتظر حتى يكتمل التوزيع. ستقوم هذه العملية ب:

   • إنشاء جميع موارد Azure المطلوبة.
   • نشر التطبيق إلى Azure App Service.
   • تكوين مصادقة آمنة من خدمة إلى خدمة باستخدام الهويات المدارة.
   • إعداد تعيينات الدور الضرورية للوصول الآمن بين الخدمات.

   إشعار

   لمعرفة المزيد حول كيفية عمل الهويات المدارة، راجع ما هي الهويات المدارة لموارد Azure؟وكيفية استخدام الهويات المدارة مع App Service.

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

3. تحميل المستندات وإنشاء فهرس بحث

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

1. في مدخل Microsoft Azure، انتقل إلى حساب التخزين الذي تم إنشاؤه بواسطة النشر. سيبدأ الاسم باسم البيئة الذي قدمته سابقا.

2. اخترحاوياتتخزين> البيانات من قائمة التنقل اليسرى وافتح حاوية المستندات.

3. تحميل نماذج المستندات بالنقر فوق تحميل. يمكنك استخدام نماذج المستندات من sample-docs المجلد الموجود في المستودع، أو ملفات PDF أو Word أو الملفات النصية الخاصة بك.

   

4. انتقل إلى خدمة Azure الذكاء الاصطناعي Search في مدخل Microsoft Azure.

5. اختر استيراد البيانات (جديدة) لبدء عملية إنشاء فهرس بحث.

   

6. في خطوة الاتصال ببياناتك :

   • حدد Azure Blob Storage كمصدر البيانات.
   • حدد RAG.
   • اختر حساب التخزين وحاوية المستندات .
   • اختر المصادقة باستخدام الهوية المدارة.
   • حدد التالي.

7. في الخطوة Vectorize النص الخاص بك :

   • حدد خدمة Azure OpenAI.
   • اختر text-embedding-ada-002 كنموذج تضمين. قام قالب AZD بالفعل بنشر هذا النموذج لك.
   • حدد الهوية المعينة من قبل النظام للمصادقة.
   • اختر مربع اختيار التأكيد لتكاليف إضافية.
   • حدد التالي.

   تلميح

   تعرف على المزيد حول البحث في المتجهات في Azure الذكاء الاصطناعي تضمينالبحث والنص في Azure OpenAI.

8. في خطوة Vectorize وإثراء الصور الخاصة بك :

   • احتفظ بالإعدادات الافتراضية.
   • حدد التالي.

9. في خطوة الإعدادات المتقدمة :

   • تأكد من تحديد Enable semantic ranker .
   • (اختياري) حدد جدول فهرسة. يعد هذا مفيدا إذا كنت تريد تحديث الفهرس بانتظام بأحدث تغييرات الملفات.
   • حدد التالي.

10. في خطوة المراجعة والإنشاء :

    • انسخ قيمة بادئة Objects name . إنه اسم فهرس البحث الخاص بك.
    • حدد Create لبدء عملية الفهرسة.

11. انتظر حتى تكتمل عملية الفهرسة. قد يستغرق ذلك بضع دقائق استنادا إلى حجم المستندات وعددها.

12. لاختبار استيراد البيانات، حدد بدء البحث وتجربة استعلام بحث مثل "أخبرني المزيد عن شركتك".

13. مرة أخرى في محطة Codespace الطرفية، قم بتعيين اسم فهرس البحث كمتغير بيئة AZD:

    azd env set SEARCH_INDEX_NAME <your-search-index-name>
    

    استبدل <your-search-index-name> باسم الفهرس الذي نسخته مسبقا. يستخدم AZD هذا المتغير في عمليات النشر اللاحقة لتعيين إعداد تطبيق App Service.

4. اختبار التطبيق ونشر

إذا كنت تفضل اختبار التطبيق محليا قبل النشر أو بعده، يمكنك تشغيله مباشرة من Codespace:

1. في محطة Codespace الطرفية، احصل على قيم بيئة AZD:

   azd env get-values
   

2. افتح src/main/resources/application.properties. باستخدام إخراج المحطة الطرفية، قم بتحديث القيم التالية، في العناصر النائبة المعنية <input-manually-for-local-testing>:

   • azure.openai.endpoint
   • azure.search.url
   • azure.search.index.name

3. سجل الدخول إلى Azure باستخدام Azure CLI:

   az login
   

   يسمح هذا لمكتبة عميل Azure Identity في نموذج التعليمات البرمجية بتلقي رمز مصادقة مميز للمستخدم الذي قام بتسجيل الدخول.

4. تشغيل التطبيق محليا:

   mvn spring-boot:run
   

5. عندما ترى تطبيقك قيد التشغيل على المنفذ 8080 متوفرا، حدد فتح في المستعرض.

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

7. أوقف خادم التطوير باستخدام Ctrl+C.

8. تطبيق التكوين الجديد SEARCH_INDEX_NAME في Azure ونشر نموذج التعليمات البرمجية للتطبيق:

   azd up
   

5. اختبار تطبيق RAG المنشور

مع نشر التطبيق وتكوينه بالكامل، يمكنك الآن اختبار وظيفة RAG:

1. افتح عنوان URL للتطبيق المتوفر في نهاية النشر.

2. يمكنك رؤية واجهة دردشة حيث يمكنك إدخال أسئلة حول محتوى المستندات التي تم تحميلها.

   

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

   • كيف تستخدم Contoso بياناتي الشخصية؟
   • كيف يمكنك تقديم مطالبة بالضمان؟

4. لاحظ كيف تتضمن الاستجابات اقتباسات تشير إلى المستندات المصدر. تساعد هذه الاقتباسات المستخدمين على التحقق من دقة المعلومات والعثور على مزيد من التفاصيل في المواد المصدر.

   

5. اختبر قدرات البحث المختلط عن طريق طرح الأسئلة التي قد تستفيد من نهج البحث المختلفة:

   • أسئلة ذات مصطلحات محددة (جيدة للبحث عن الكلمات الأساسية).
   • أسئلة حول المفاهيم التي يمكن وصفها باستخدام مصطلحات مختلفة (جيد للبحث في المتجهات).
   • الأسئلة المعقدة التي تتطلب فهم السياق (جيد للتصنيف الدلالي).

تنظيف الموارد

عند الانتهاء من التطبيق، يمكنك حذف جميع الموارد لتجنب تكبد المزيد من التكاليف:

azd down --purge

يحذف هذا الأمر كافة الموارد المقترنة بالتطبيق الخاص بك.

الأسئلة الشائعة

• كيف يسترد نموذج التعليمات البرمجية الاقتباسات من إكمال دردشة Azure OpenAI؟
• ما هي ميزة استخدام الهويات المدارة في هذا الحل؟
• كيف يتم استخدام الهوية المدارة المعينة من قبل النظام في هذا التصميم ونموذج التطبيق؟
• كيف يتم تنفيذ البحث المختلط مع ranker الدلالي في نموذج التطبيق؟
• لماذا يتم إنشاء جميع الموارد في شرق الولايات المتحدة 2؟
• هل يمكنني استخدام نماذج OpenAI الخاصة بي بدلا من تلك التي يوفرها Azure؟
• كيف يمكنني تحسين جودة الاستجابات؟

---

كيف يسترد نموذج التعليمات البرمجية الاقتباسات من إكمال دردشة Azure OpenAI؟

يسترد النموذج الاقتباسات باستخدام AzureSearchChatExtensionConfiguration كمصدر بيانات لعميل الدردشة. عند طلب إكمال دردشة، تتضمن الاستجابة كائنا Citations ضمن سياق الرسالة. تستخرج التعليمات البرمجية هذه الاقتباسات كما يلي:

public static ChatResponse fromChatCompletions(ChatCompletions completions) {
    ChatResponse response = new ChatResponse();
    
    if (completions.getChoices() != null && !completions.getChoices().isEmpty()) {
        var message = completions.getChoices().get(0).getMessage();
        if (message != null) {
            response.setContent(message.getContent());

            if (message.getContext() != null && message.getContext().getCitations() != null) {
                var azureCitations = message.getContext().getCitations();
                for (int i = 0; i < azureCitations.size(); i++) {
                    var azureCitation = azureCitations.get(i);
                    
                    Citation citation = new Citation();
                    citation.setIndex(i + 1);
                    citation.setTitle(azureCitation.getTitle());
                    citation.setContent(azureCitation.getContent());
                    citation.setFilePath(azureCitation.getFilepath());
                    citation.setUrl(azureCitation.getUrl());
                    
                    response.getCitations().add(citation);
                }
            }
        }
    }
    
    return response;
}

في استجابة الدردشة، يستخدم [doc#] المحتوى تدوينا للإشارة إلى الاقتباس المقابل في القائمة، مما يسمح للمستخدمين بتتبع المعلومات مرة أخرى إلى مستندات المصدر الأصلية. لمزيد من المعلومات، راجع:

• Azure OpenAI على مرجع واجهة برمجة تطبيقات البيانات
• مصدر البيانات - Azure الذكاء الاصطناعي Search

---

ما هي ميزة استخدام الهويات المدارة في هذا الحل؟

تلغي الهويات المدارة الحاجة إلى تخزين بيانات الاعتماد في التعليمات البرمجية أو التكوين. باستخدام الهويات المدارة، يمكن للتطبيق الوصول بأمان إلى خدمات Azure مثل Azure OpenAI وAzure الذكاء الاصطناعي Search دون إدارة الأسرار. يتبع هذا الأسلوب مبادئ أمان الثقة المعدومة ويقلل من مخاطر التعرض لبيانات الاعتماد.

---

كيف يتم استخدام الهوية المدارة المعينة من قبل النظام في هذا التصميم ونموذج التطبيق؟

ينشئ نشر AZD هويات مدارة معينة من قبل النظام ل Azure App Service وAzure OpenAI وAzure الذكاء الاصطناعي Search. كما أنه يقوم بتعيينات الأدوار الخاصة بكل منها (راجع ملف main.bicep ). للحصول على معلومات حول تعيينات الأدوار المطلوبة، راجع تكوين الشبكة والوصول ل Azure OpenAI على بياناتك.

في نموذج تطبيق Java، تستخدم Azure SDKs هذه الهوية المدارة للمصادقة الآمنة، لذلك لا تحتاج إلى تخزين بيانات الاعتماد أو الأسرار في أي مكان. على سبيل المثال، تتم تهيئة OpenAIAsyncClient باستخدام DefaultAzureCredential، والذي يستخدم تلقائيا الهوية المدارة عند التشغيل في Azure:

@Bean
public TokenCredential tokenCredential() {
   return new DefaultAzureCredentialBuilder().build();
}

@Bean
public OpenAIAsyncClient openAIClient(TokenCredential tokenCredential) {
   return new OpenAIClientBuilder()
         .endpoint(openAiEndpoint)
         .credential(tokenCredential)
         .buildAsyncClient();
}

وبالمثل، عند تكوين مصدر البيانات ل Azure الذكاء الاصطناعي Search، يتم تحديد الهوية المدارة للمصادقة:

AzureSearchChatExtensionConfiguration searchConfiguration =
   new AzureSearchChatExtensionConfiguration(
      new AzureSearchChatExtensionParameters(appSettings.getSearch().getUrl(), appSettings.getSearch().getIndex().getName())
         .setAuthentication(new OnYourDataSystemAssignedManagedIdentityAuthenticationOptions())
         // ...
   );

يتيح هذا الإعداد الاتصال الآمن بدون كلمة مرور بين تطبيق Spring Boot وخدمات Azure، باتباع أفضل الممارسات لأمان Zero Trust. تعرف على المزيد حول DefaultAzureCredentialومكتبة عميل Azure Identity ل Java.

---

كيف يتم تنفيذ البحث المختلط مع ranker الدلالي في نموذج التطبيق؟

يقوم نموذج التطبيق بتكوين البحث المختلط مع الترتيب الدلالي باستخدام Azure OpenAI وAzure الذكاء الاصطناعي Search Java SDKs. في الخلفية، يتم إعداد مصدر البيانات على النحو التالي:

AzureSearchChatExtensionParameters parameters = new AzureSearchChatExtensionParameters(
   appSettings.getSearch().getUrl(),
   appSettings.getSearch().getIndex().getName())
    // ...
    .setQueryType(AzureSearchQueryType.VECTOR_SEMANTIC_HYBRID)
    .setEmbeddingDependency(new OnYourDataDeploymentNameVectorizationSource(appSettings.getOpenai().getEmbedding().getDeployment()))
    .setSemanticConfiguration(appSettings.getSearch().getIndex().getName() + "-semantic-configuration");

يمكن هذا التكوين التطبيق من الجمع بين البحث عن المتجهات (التشابه الدلالي) ومطابقة الكلمة الأساسية والترتيب الدلالي في استعلام واحد. يعيد المصنف الدلالي ترتيب النتائج لإرجاع الإجابات الأكثر صلة بالموضوع والملائمة للسياق، والتي يتم استخدامها بعد ذلك من قبل Azure OpenAI لإنشاء الاستجابات.

يتم تعريف اسم التكوين الدلالي تلقائيا بواسطة عملية التوجيه المتكاملة. يستخدم اسم فهرس البحث كبادئة ويلحق -semantic-configuration كلاحقة. وهذا يضمن أن التكوين الدلالي مقترن بشكل فريد بالفهرس المقابل ويتبع اصطلاح تسمية متناسق.

---

لماذا يتم إنشاء جميع الموارد في شرق الولايات المتحدة 2؟

يستخدم النموذج نماذج gpt-4o-mini و text-embedding-ada-002 ، وكلاهما متوفر مع نوع النشر القياسي في شرق الولايات المتحدة 2. يتم اختيار هذه النماذج أيضا لأنها غير مجدولة للإيقاف قريبا، ما يوفر الاستقرار لتوزيع العينة. يمكن أن يختلف توفر النموذج وأنواع النشر حسب المنطقة، لذلك يتم تحديد شرق الولايات المتحدة 2 لضمان عمل العينة خارج الصندوق. إذا كنت تريد استخدام منطقة أو نماذج مختلفة، فتأكد من تحديد النماذج المتوفرة لنفس نوع النشر في نفس المنطقة. عند اختيار النماذج الخاصة بك، تحقق من تواريخ التوفر والإيقاف لتجنب الاضطرابات.

• توفر النموذج: نماذج خدمة Azure OpenAI
• تواريخ إيقاف النموذج: إهمال نموذج خدمة Azure OpenAI وإيقافه.

---

هل يمكنني استخدام نماذج OpenAI الخاصة بي بدلا من تلك التي يوفرها Azure؟

تم تصميم هذا الحل للعمل مع خدمة Azure OpenAI. بينما يمكنك تعديل التعليمات البرمجية لاستخدام نماذج OpenAI الأخرى، ستفقد ميزات الأمان المتكاملة ودعم الهوية المدارة والتكامل السلس مع Azure الذكاء الاصطناعي Search الذي يوفره هذا الحل.

---

كيف يمكنني تحسين جودة الاستجابات؟

يمكنك تحسين جودة الاستجابة من خلال:

• تحميل مستندات ذات جودة أعلى وأكثر صلة.
• ضبط استراتيجيات التقسيم في مسار فهرسة Azure الذكاء الاصطناعي Search. ومع ذلك، لا يمكنك تخصيص التقسيم مع المتجهات المتكاملة الموضحة في هذا البرنامج التعليمي.
• تجربة قوالب مطالبة مختلفة في التعليمات البرمجية للتطبيق.
• ضبط البحث مع خصائص أخرى في فئة AzureSearchChatExtensionParameters.
• استخدام نماذج Azure OpenAI أكثر تخصصا لمجالك المحدد.

المزيد من الموارد

• استكشاف قدرات البحث المختلط في Azure الذكاء الاصطناعي Search
• استخدام Azure OpenAI على بياناتك
• مكتبة عميل Azure OpenAI ل Java
• نماذج مكتبة عميل Azure OpenAI ل Java