مشاركة عبر

التعليم: بناء تطبيق ويب وكيل في Azure App Service باستخدام Microsoft Semantic Kernel أو Foundry Agent Service (Spring Boot)

يوضح هذا البرنامج التعليمي كيفية إضافة القدرة الوكيلة إلى تطبيق Spring Boot WebFlux CRUD القائم على البيانات. يقوم بذلك باستخدام Microsoft Semantic Kernel وخدمة وكيل Foundry.

إذا كان تطبيق الويب الخاص بك يحتوي بالفعل على ميزات مفيدة مثل التسوق، حجز الفنادق، أو إدارة البيانات، فمن السهل نسبيا إضافة وظائف وكيل إلى تطبيق الويب الخاص بك عن طريق تغليف هذه الوظائف في إضافة (ل LangGraph) أو كنقطة نهاية OpenAPI (لخدمة وكلاء Foundry). في هذا البرنامج التعليمي، تبدأ بتطبيق قائمة to-do بسيط. في النهاية، ستتمكن من إنشاء المهام وتحديثها وإدارتها باستخدام عامل في تطبيق App Service.

كل من النواة الدلالية وخدمة وكيل المسبك تمكنك من بناء تطبيقات ويب وكالية بقدرات مدعومة بالذكاء الذكاء الاصطناعي. يوضح الجدول التالي بعض الاعتبارات والمقايضات:

الاعتبار نواة دلالية خدمة وكلاء المسبك
الأداء سريع (يعمل محليا) أبطأ (خدمة مدارة عن بعد)
Development كود كامل ، أقصى قدر من التحكم كود منخفض ، تكامل سريع
الاختبار الاختبارات اليدوية / الوحدة في الكود ملعب مدمج للاختبار السريع
قابلية التوسع إدارة التطبيق مدار من قبل Azure، تحجيم تلقائي
حواجز الحماية الأمنية يتطلب تنفيذ مخصص سلامة المحتوى والرقابة المدمجة
الهوية يتطلب تنفيذ مخصص معرف الوكيل المدمج والمصادقة
Enterprise تكامل مخصص مطلوب نشر Microsoft 365/Teams المدمج واستدعاءات الأدوات المتكاملة في Microsoft 365.

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

  • تحويل وظيفة التطبيق الموجودة إلى مكون إضافي ل Kernel الدلالي.
  • أضف المكون الإضافي إلى عامل Kernel الدلالي واستخدمه في تطبيق ويب.
  • حول وظائف التطبيق الحالية إلى نقطة نهاية OpenAPI لخدمة Foundry Agent.
  • اتصل بوكيل Foundry عبر تطبيق ويب.
  • تعيين الأذونات المطلوبة لاتصال الهوية المدارة.

Prerequisites

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

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

افتح في GitHub Codespaces.

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

  2. حدد الزر Code ، وحدد علامة التبويب Codespace ، وحدد Create codespace on main.

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

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

    mvn spring-boot:run

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

مراجعة التعليمات البرمجية للعامل

تتم تهيئة عامل Semantic Kernel في src/main/java/com/example/crudtaskswithagent/controller/AgentController.java، عندما يدخل المستخدم المطالبة الأولى في جلسة مستعرض جديدة.

يمكنك العثور على رمز التهيئة في المنشئ SemanticKernelAgentService (في src/main/java/com/example/crudtaskswithagent/service/SemanticKernelAgentService.java). تقوم التعليمات البرمجية للتهيئة بالآتي:

  • إنشاء نواة مع إكمال الدردشة.
  • يضيف مكونا إضافيا للنواة يغلف وظائف تطبيق CRUD (في src/main/java/com/example/crudtaskswithagent/plugin/TaskCrudPlugin.java). الأجزاء المثيرة للاهتمام من المكون الإضافي هي DefineKernelFunction التعليقات التوضيحية على إعلانات الأسلوب والمعلمات و descriptionreturnType التي تساعد النواة على استدعاء المكون الإضافي بذكاء.
  • إنشاء عامل إكمال دردشة، وتكوينه للسماح لنموذج الذكاء الاصطناعي باستدعاء الوظائف تلقائيا (FunctionChoiceBehavior.auto(true)).
  • إنشاء مؤشر ترابط عامل يدير محفوظات الدردشة تلقائيا.
        // Create OpenAI client
        OpenAIAsyncClient openAIClient = new OpenAIClientBuilder()
                .endpoint(endpoint)
                .credential(new DefaultAzureCredentialBuilder().build())
                .buildAsyncClient();
        
        // Create chat completion service
        OpenAIChatCompletion chatCompletion = OpenAIChatCompletion.builder()
                .withOpenAIAsyncClient(openAIClient)
                .withModelId(deployment)
                .build();
        
        // Create kernel plugin from the task plugin
        KernelPlugin kernelPlugin = KernelPluginFactory.createFromObject(taskCrudPlugin, "TaskPlugin");
        
        // Create kernel with TaskCrudPlugin and chat completion service
        Kernel kernel = Kernel.builder()
                .withAIService(OpenAIChatCompletion.class, chatCompletion)
                .withPlugin(kernelPlugin)
                .build();
        
        // Use automatic function calling
        InvocationContext invocationContext = InvocationContext.builder()
            .withFunctionChoiceBehavior(FunctionChoiceBehavior.auto(true))
            .build();

        // Create ChatCompletionAgent
        configuredAgent = ChatCompletionAgent.builder()
                .withKernel(kernel)
                .withName("TaskAgent")
                .withInvocationContext(invocationContext)
                .withInstructions(
                    "You are an agent that manages tasks using CRUD operations. " +
                    "Use the TaskCrudPlugin functions to create, read, update, and delete tasks. " +
                    "Always call the appropriate plugin function for any task management request. " +
                    "Don't try to handle any requests that are not related to task management."
                )
                .build();
        
    } catch (Exception e) {
        logger.error("Error initializing SemanticKernelAgentService: {}", e.getMessage(), e);
    }
}

this.agent = configuredAgent;

// Initialize thread for this instance
this.thread = ChatHistoryAgentThread.builder().build();

في كل مرة يتم فيها تلقي المطالبة، تستخدم ChatCompletionAgent.invokeAsync() التعليمات البرمجية للخادم لاستدعاء العامل مع مطالبة المستخدم ومترابط العامل. يتعقب مؤشر ترابط العامل محفوظات الدردشة.

// Use the agent to process the message with automatic function calling
return agent.invokeAsync(userMessageContent, thread)
        .<String>map(responses -> {
            
            if (responses != null && !responses.isEmpty()) {
                // Process all responses and concatenate them
                StringBuilder combinedResult = new StringBuilder();
                
                for (int i = 0; i < responses.size(); i++) {
                    var response = responses.get(i);
                    
                    // Update thread with the last response thread (as per Microsoft docs)
                    if (i == responses.size() - 1) {
                        var responseThread = response.getThread();
                        if (responseThread instanceof ChatHistoryAgentThread) {
                            this.thread = (ChatHistoryAgentThread) responseThread;
                        }
                    }
                    
                    // Get response content
                    ChatMessageContent<?> content = response.getMessage();
                    String responseContent = content != null ? content.getContent() : "";
                    
                    if (!responseContent.isEmpty()) {
                        if (combinedResult.length() > 0) {
                            combinedResult.append("\n\n"); // Separate multiple responses
                        }
                        combinedResult.append(responseContent);
                    }
                }
                
                String result = combinedResult.toString();
                if (result.isEmpty()) {
                    result = "No content returned from agent.";
                }
                return result;
            } else {
                return "I'm sorry, I couldn't process your request. Please try again.";
            }
        })
        .onErrorResume(throwable -> {
            logger.error("Error in processMessage: {}", throwable.getMessage(), throwable);
            return Mono.just("Error processing message: " + throwable.getMessage());
        });

انشر نموذج التطبيق

يحتوي نموذج المستودع على قالب Azure Developer CLI (AZD)، الذي ينشئ تطبيق App Service بهوية مدارة وينشر نموذج التطبيق الخاص بك.

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

    azd auth login

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

  2. انشر تطبيق Azure App Service باستخدام قالب AZD:

    azd up

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

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

  4. في إخراج AZD، ابحث عن عنوان URL لتطبيقك وانتقل إليه في المستعرض. يبدو عنوان URL كما يلي في إخراج AZD:

     Deploying services (azd deploy)

   (✓) Done: Deploying service web
   - Endpoint: <URL>

  5. افتح مخطط OpenAPI المولد تلقائيا عند المسار https://....azurewebsites.net/api/schema . تحتاج إلى هذا المخطط لاحقا.

    لديك الآن تطبيق App Service بهوية مدارة معينة من قبل النظام.

إنشاء وتكوين مورد Microsoft Foundry

  1. في بوابة Foundry، تأكد من أن زر الراديو العلوي في New Foundry مضبوط على التفعيل وأنشئ مشروعا.

  2. قم بنشر نموذج من اختيارك (انظر Microsoft Foundry Quickstart: إنشاء الموارد).

  3. من أعلى ملعب النماذج، انسخ اسم النموذج.

  4. أسهل طريقة للحصول على نقطة نهاية Azure OpenAI لا تزال من البوابة الكلاسيكية. اختر زر الراديو New Foundry ، ثم Azure OpenAI، ثم انسخ رابط الرابط في نقطة نهاية Azure OpenAI لاحقا.

    لقطة شاشة توضح كيفية نسخ نقطة نهاية OpenAI ونقطة نهاية مشروع المسبك في مدخل المسبك.

تعيين الأذونات المطلوبة

  1. من القائمة العلوية لبوابة Foundry الجديدة، اختر تشغيل، ثم اختر المسؤول. في صف مشروع Foundry الخاص بك، يجب أن ترى رابطين. المورد في عمود الاسم هو مورد مشروع Foundry، والمورد في عمود الموارد الأصلية هو مورد Foundry.

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

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

  3. أضف الدور التالي لهوية تطبيق خدمة التطبيقات المدارة:

    المورد المستهدف الدور المطلوب مطلوب ل
    مصهر مستخدم OpenAI للخدمات المعرفية خدمة إكمال الدردشة في Microsoft Agent Framework.

    للحصول علي الإرشادات، راجع تعيين أدوار Azure باستخدام مدخل Azure.

تكوين متغيرات الاتصال في نموذج التطبيق الخاص بك

  1. افتح src/main/resources/application.properties. باستخدام القيم التي نسختها سابقا من بوابة Foundry، قم بتكوين المتغيرات التالية:

    Variable Description
    azure.openai.endpoint نقطة نهاية Azure OpenAI (منسوخة من بوابة Foundry الكلاسيكية).
    azure.openai.deployment اسم النموذج في النشر (تم نسخه من ملعب النماذج في بوابة Foundry الجديدة).

    Note

    للحفاظ على بساطة البرنامج التعليمي، ستستخدم هذه المتغيرات في .env بدلا من الكتابة فوقها بإعدادات التطبيق في App Service.

    Note

    للحفاظ على بساطة البرنامج التعليمي، ستستخدم هذه المتغيرات في src/main/resources/application.properties بدلا من الكتابة فوقها بإعدادات التطبيق في App Service.

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

    az login

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

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

    mvn spring-boot:run

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

  5. جرب واجهة الدردشة. إذا تلقيت ردا، فهذا يعني أن تطبيقك يتصل بنجاح بمورد Microsoft Foundry.

  6. مرة أخرى في مساحة التعليمات البرمجية GitHub، انشر تغييرات التطبيق.

    azd up

  7. انتقل إلى التطبيق المنشور مرة أخرى واختبر وكلاء الدردشة.

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

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

azd down --purge

نظرا لأن قالب AZD لا يتضمن موارد Microsoft Foundry، عليك حذفها يدويا إذا أردت.

موارد إضافية

  • Last updated on