مضيفي القدرات

‏‫ملاحظة‬

تحديث مضيفي القدرة غير مدعوم. لتعديل مضيف إمكانية، يجب حذف المضيف الموجود وإعادة إنشائه بالتكوين الجديد.

مضيفو القدرات هم موارد فرعية تقوم بتكوينها في كل من حساب Microsoft Foundry ونطاق project Foundry. يخبرون خدمة وكلاء فاوندري أين يتم تخزين ومعالجة بيانات الوكلاء، بما في ذلك:

• محفوظات المحادثات (مؤشرات الترابط)
• تحميل الملفات
• مخازن المتجهات

المتطلبات المسبقه

• Microsoft Foundry project
• إذا استخدمت مواردك الخاصة لبيانات الوكيل (إعداد وكيل قياسي)، أنشئ موارد واتصالات Azure المطلوبة:
  • استخدم مواردك الخاصة
  • أضف اتصالا جديدا إلى project
• الأذونات المطلوبة:
  • دور المساهم في حساب Foundry لإنشاء مضيفي القدرات
  • >دور <مسؤول Access المستخدم أو Owner لتعيين access لموارد Azure (لإعداد الوكيل القياسي)
  • لمزيد من التفاصيل، راجع Requireds و Role-based access control (RBAC) في Microsoft Foundry.

لماذا تستخدم مضيفي القدرة؟

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

• سيادة البيانات - احتفظ بجميع بيانات الوكيل ضمن اشتراكك Azure.
• Security control - استخدم حساباتك storage الخاصة، وقواعد البيانات، وخدمات البحث.
• الامتثال - تلبية المتطلبات التنظيمية أو التنظيمية المحددة.

كيف يعمل مضيفو القدرة؟

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

السلوك الافتراضي (الموارد التي تديرها Microsoft)

إذا لم تنشئ مضيفي القدرات، تستخدم خدمة الوكلاء تلقائيا موارد Azure المدارة من قبل مايكروسوفت ل:

• Thread storage (تاريخ المحادثات، تعريفات الوكلاء)
• File storage (المستندات المرفوعة)
• البحث عن المتجهات (التضمينات والاسترداد)

إحضار مواردك الخاصة

عندما تنشئ مضيفي القدرات على مستوى الحساب ومستوى project، تقوم موارد Azure الخاصة بك بتخزين ومعالجة بيانات وكلاء الوكلاء. هذا إعداد وكيل قياسي. لإعداد وكيل الشبكة القياسي، قم بنشر جميع الموارد ذات الصلة في نفس المنطقة التي تضم virtual network (VNet). للحصول على الإرشاد، انظر إنشاء بيئة جديدة مؤمنة بالشبكة مع هوية مدارة من قبل المستخدم.

لمعرفة المزيد عن إعداد الوكيل القياسي، راجع الجاهزية المؤسسية المدمجة مع إعداد الوكيل القياسي.

‏‫ملاحظة‬

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

التسلسل الهرمي للتكوين

يتبع مضيفو القدرة تسلسلا هرميا حيث تتجاوز التكوينات الأكثر تحديدا التكوينات الأوسع:

1. ><إعدادات الخدمة الافتراضية (البحث و storage المدارة من مايكروسوفت) - تستخدم عندما لا يكون هناك مضيف قدرات مهيأ.
2. مضيف القدرة على مستوى الحساب - يوفر الإعدادات الافتراضية المشتركة لجميع المشاريع ضمن الحساب.
3. Project مستوى مضيف - يتجاوز الافتراضيات على مستوى الحساب والخدمة لهذا project المحدد.

فهم قيود مضيف القدرات

عند إنشاء مضيفي القدرات، كن على دراية بهذه القيود المهمة لتجنب التعارضات:

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

• لا يمكنك تحديث الإعدادات: إذا احتجت لتغيير الإعدادات، احذف مضيف القدرات الحالي وأعد إنشائه.

إنشاء روابط لمضيفي القدرات

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

• Thread storage: Azure اتصال قاعدة بيانات كوزموس
• ملف storage: الاتصال Azure Storage
• Vector store: الاتصال Azure AI Search

إذا كنت ترغب في استخدام نشر النماذج من مورد Azure OpenAI الخاص بك، أنشئ أيضا اتصال Azure OpenAI.

لإضافة الاتصالات في بوابة Foundry، راجع أضف اتصالا جديدا إلى project.

تكوين مضيفي القدرات

حاليا، تدير مضيفي القدرات باستخدام واجهة برمجة تطبيقات REST. دعم SDK لإدارة مضيف القدرات غير متوفر.

الخصائص المطلوبة (مضيف قدرة project)

لاستخدام مواردك الخاصة لبيانات الوكيل (إعداد الوكيل القياسي)، قم بتكوين مضيف قدرة project بالخصائص التالية:

الخاصية	الغرض	مورد Azure المطلوب	مثال على اسم الاتصال
threadStorageConnections	يخزن تعريفات الوكيل ومحفوظات المحادثات وسلاسل المحادثات	Azure Cosmos DB	"my-cosmosdb-connection"
vectorStoreConnections	يتعامل مع storage vector للاسترجاع والبحث	Azure AI Search	"my-ai-search-connection"
storageConnections	يدير رفع الملفات وتخزين blob storage	Azure Storage Account	"my-storage-connection"

خاصية اختيارية

الخاصية	الغرض	مورد Azure المطلوب	وقت الاستخدام
aiServicesConnections	استخدام عمليات توزيع النموذج الخاصة بك	Azure OpenAI	عندما تريد استخدام النماذج من مورد Azure OpenAI الحالي بدلا من النماذج المدمجة على مستوى الحساب.

مضيف قدرة الحساب

استخدم مضيف قدرة الحساب لتمكين خدمة الوكيل و(اختياريا) تحديد الإعدادات الافتراضية التي يمكن للمشاريع وراثتها.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01

{
  "properties": {
    "capabilityHostKind": "Agents"
  }
}

مرجع: واجهة برمجة تطبيقات REST لإدارة حسابات Foundry

Project مضيف القدرات

يتجاوز هذا التكوين الإعدادات الافتراضية للخدمة وأي إعدادات على مستوى الحساب. جميع الوكلاء في هذا project سيستخدمون الموارد التي حددتها:

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts/{name}?api-version=2025-06-01

{
  "properties": {
    "capabilityHostKind": "Agents",
    "threadStorageConnections": ["my-cosmos-db-connection"],
    "vectorStoreConnections": ["my-ai-search-connection"],
    "storageConnections": ["my-storage-account-connection"],
    "aiServicesConnections": ["my-azure-openai-connection"]
  }
}

المرجع: Project مضيفو القدرات - إنشاء أو تحديث

اختياري: الافتراضيات على مستوى الحساب مع تجاوزات project

تعيين الإعدادات الافتراضية المشتركة على مستوى الحساب الذي ينطبق على جميع المشاريع:

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01

{
  "properties": {
    "capabilityHostKind": "Agents",
    "threadStorageConnections": ["shared-cosmosdb-connection"],
    "vectorStoreConnections": ["shared-ai-search-connection"],
    "storageConnections": ["shared-storage-connection"]
  }
}

‏‫ملاحظة‬

جميع مشاريع Foundry سترث هذه الإعدادات. ثم تجاوز الإعدادات المحددة على مستوى project حسب الحاجة.

تحقق من التكوين الخاص بك

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

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

   GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts?api-version=2025-06-01
   

2. احصل على مضيف project capability وتأكد من أنه يشير إلى أسماء الاتصال المتوقعة.

   GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts?api-version=2025-06-01
   

3. اختبر إعدادك عن طريق إنشاء وكيل اختبار وتشغيل محادثة. تأكد من ذلك:

   • تظهر سلاسل المحادثات في قاعدة بيانات Azure Cosmos الخاصة بك
   • الملفات المرفوعة تظهر في حسابك في Azure Storage
   • تظهر بيانات Vector في فهرس Azure AI Search الخاص بك

4. إذا قمت بتحديث الاتصالات أو أردت تغيير مكان تخزين البيانات، قم بحذف وإعادة إنشاء مضيفي القدرات مع التكوين المحدث.

حذف مضيفي القدرة

تحذير

سيؤثر حذف مضيف القدرة على جميع العوامل التي تعتمد عليه. تأكد من فهم التأثير قبل المتابعة. على سبيل المثال، إذا حذفت project ومضيف قدرات الحساب، فلن يكون لدى الوكلاء في project الخاص بك access إلى الملفات والthread والمخازن المتجهة التي كانوا يستخدمونها سابقا.

حذف مضيف إمكانية على مستوى الحساب

DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01

حذف مضيف قدرات على مستوى project

DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts/{name}?api-version=2025-06-01

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

إذا كنت تواجه مشكلات عند إنشاء مضيفي القدرات، فإن هذا القسم يوفر حلولا للمشكلات والأخطاء الأكثر شيوعا.

أخطاء تعارض HTTP 409

المشكلة: مضيفات قدرات متعددة لكل نطاق

الأعراض: تتلقى خطأ تعارض 409 عند محاولة إنشاء مضيف قدرة، على الرغم من أنك تعتقد أن النطاق فارغ.

رسالة الخطأ:

{
  "error": {
    "code": "Conflict",
    "message": "There is an existing Capability Host with name: existing-host, provisioning state: Succeeded for workspace: /subscriptions/.../workspaces/my-workspace, cannot create a new Capability Host with name: new-host for the same ClientId."
  }
}

السبب الجذري: يمكن لكل حساب وكل project أن يكون لديه مضيف قدرة نشط واحد فقط. أنت تحاول إنشاء مضيف إمكانية باسم مختلف عندما يكون واحدا موجودا بالفعل في نفس النطاق.

الحل:

1. التحقق من مضيفي القدرة الحاليين - الاستعلام عن النطاق لمعرفة ما هو موجود بالفعل
2. استخدام تسمية متسقة - تأكد من أنك تستخدم نفس الاسم عبر جميع الطلبات لنفس النطاق
3. مراجعة متطلباتك - تحديد ما إذا كان مضيف القدرات الحالي يلبي احتياجاتك

خطوات التحقق: استخدم طلبات GET في Verify Your Configuration للتأكد مما إذا كان مضيف القدرات موجودا بالفعل في النطاق المستهدف.

المشكلة: العمليات المتزامنة قيد التقدم

الأعراض: تتلقى خطأ تعارض 409 يشير إلى أن عملية أخرى قيد التشغيل حاليا.

رسالة الخطأ:

{
  "error": {
    "code": "Conflict", 
    "message": "Create: Capability Host my-host is currently in non creating, retry after its complete: /subscriptions/.../workspaces/my-workspace"
  }
}

السبب الجذري: أنت تحاول إنشاء مضيف إمكانية أثناء تقدم عملية أخرى (تحديث وحذف وتعديل) في نفس النطاق.

الحل:

1. انتظر حتى تكتمل العملية الحالية - تحقق من حالة العمليات الجارية
2. مراقبة تقدم العملية - استخدم واجهة برمجة تطبيقات العمليات لتعقب الإكمال
3. تنفيذ منطق إعادة المحاولة - استخدم التراجع الأسي للصراعات المؤقتة

مراقبة العملية:

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.CognitiveServices/locations/{location}/operationResults/{operationId}?api-version=2025-06-01

أفضل الممارسات لمنع نشوب الصراعات

1. التحقق من صحة الطلب المسبق

تحقق دائما من الحالة الحالية قبل إجراء التغييرات:

• الاستعلام عن مضيفي القدرة الموجودة في النطاق الهدف
• تحقق من وجود أي عمليات جارية
• فهم التكوين الحالي

2. تنفيذ منطق إعادة المحاولة مع التراجع الأسي

try 
{
    var response = await CreateCapabilityHostAsync(request);
    return response;
}
catch (HttpRequestException ex) when (ex.Message.Contains("409"))
{
    if (ex.Message.Contains("existing Capability Host with name"))
    {
        // Handle name conflict - check if existing resource is acceptable
        var existing = await GetExistingCapabilityHostAsync();
        if (IsAcceptable(existing))
        {
            return existing; // Use existing resource
        }
        else
        {
            throw new InvalidOperationException("Scope already has a capability host with different name");
        }
    }
    else if (ex.Message.Contains("currently in non creating"))
    {
        // Handle concurrent operation - implement retry with backoff
        await Task.Delay(TimeSpan.FromSeconds(30));
        return await CreateCapabilityHostAsync(request); // Retry once
    }
}

3. فهم السلوك غير الفعال

يدعم النظام طلبات الإنشاء غير الفعالة:

• نفس الاسم + نفس التكوين → إرجاع المورد الموجود (200 موافق)
• نفس الاسم + تكوين مختلف → إرجاع 400 طلب غير صالح
• اسم مختلف → تعارض إرجاعات 409

4. سير عمل تغيير التكوين

نظرا لأن التحديثات غير مدعومة، اتبع هذا التسلسل لتغييرات التكوين:

1. حذف مضيف الإمكانية الحالي
2. انتظر حتى يكتمل الحذف
3. إنشاء مضيف قدرات جديد بالتكوين المطلوب

السيناريوهات الشائعة

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

الخطوات التالية

• إعداد الوكيل القياسي
• جهز بيئتك
• أضف اتصالا جديدا إلى project