إعداد موارد وكيل قياسية

إعداد الوكيل القياسي يستخدم موارد Azure المدارة من قبل العملاء والمستأجر الواحد لتخزين حالة الوكيل والحفاظ على جميع بيانات الوكيل تحت سيطرتك. استخدم الإعداد القياسي عندما تحتاج إلى سيادة بيانات كاملة، أو الامتثال لسياسات أمان المؤسسة، أو عزل على مستوى project.

في هذا الإعداد:

• حالات الوكيل (المحادثات، الردود) مخزنة في موارد Azure الخاصة بك.
• تحافظ على السيطرة الكاملة على إقامة البيانات والوصول إلى access.

نصيحة

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

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

• اشتراك في Azure. أنشئ واحدا مجانا.
• قاعدة بيانات Azure Cosmos لحساب NoSQL. لمتطلبات النقل، انظر متطلبات معدل النقل في قاعدة بيانات كوزموس.
• حساب Azure Storage.
• مورد Azure AI Search.
• مورد Azure Key Vault لإدارة الأسرار.
• Azure CLI الإصدار 2.50 أو أحدث. ركض az --version للتحقق.
• صلاحيات كافية لتعيين الأدوار. تحتاج إلى دور Owner أو User Access Administrator في مجموعة الموارد.
• نموذج متوافق مع الوكلاء المنشور (على سبيل المثال، gpt-4o).

نظرة عامة على الموارد

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

مورد	ما الذي يخزنته
Azure Storage (ملف BYO Storage)	الملفات التي رفعها المطورون والمستخدمين النهائيون
Azure AI Search (بحث BYO)	مخازن المتجهات التي أنشأها الوكيل
Azure كوزموس DB (موضوع BYO Storage)	الرسائل، سجل المحادثات، وبيانات تعريف الوكيل

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

متطلبات معدل النقل في قاعدة بيانات كوزموس

يجب أن يكون لحساب قاعدة بيانات كوزموس Azure الخاص بك ل NoSQL حد إجمالي معدل نقل لا يقل عن 3000 RU/s. يتم دعم كل من الوضعين Provisioned ThroughputوServerless .

يوفر إعداد الإعداد القياسي ثلاث حاويات في حساب قاعدة بيانات Cosmos الخاص بك، كل واحدة تتطلب 1000 RU/s:

الحاوية	الغرض
thread-message-store	محادثات المستخدم النهائي
system-thread-message-store	رسائل النظام الداخلية
agent-entity-store	بيانات تعريف الوكيل (تعليمات، أدوات، اسم)

لعدة مشاريع تحت نفس حساب Foundry، اضرب في عدد المشاريع. على سبيل المثال، يتطلب مشروعان ما لا يقل عن 6000 رو/ث (3 حاويات × 1000 رو/ث × مشروعين).

عزل البيانات على مستوى Project

الإعداد القياسي يفرض عزل البيانات على مستوى project بشكل افتراضي. يتم توفير حاويتين blob storage تلقائيا في حساب storage الخاص بك: واحدة للملفات وواحدة لبيانات النظام الوسيطة (القطع، التضمينات). تم توفير ثلاث حاويات في حساب قاعدة بيانات كوزموس الخاصة بك: واحدة لخيوط المستخدم، وواحدة لرسائل النظام، وواحدة لبيانات تكوين الوكيل مثل التعليمات والأدوات والأسماء. يقلل هذا السلوك الافتراضي من تعقيد الإعداد مع الحفاظ على حدود بيانات صارمة بين المشاريع.

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

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

• مضيف قدرة الحساب: يحتوي على جسم طلب فارغ باستثناء المعامل capabilityHostKind="Agents".
• Project قدرة host: يحدد الموارد لتخزين حالة الوكيل، سواء كانت موارد مستأجرة متعددة مدارة من مايكروسوفت (إعداد أساسي) أو مملوكة للعميل (إعداد قياسي) للمستأجر الواحد. يعمل مضيف قدرة project كمضيف project.

القيود

• لا يمكنك تحديث مضيف القدرات بعد أن يكون مضبوطا على project أو حساب.

توفير الموارد خطوة بخطوة

‏‫ملاحظة‬

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

التوفير اليدوي

اتبع هذه الخطوات لتوفير جميع الموارد اللازمة يدويا لإعداد الوكيل القياسي. امنح حوالي 30-45 دقيقة لعملية التزويد بالكامل.

المرحلة الأولى: إنشاء موارد تابعة

1. أنشئ أو أعد استخدام الموارد التالية. يمكنك إنشاء موارد جديدة أو إدخال معرف الموارد للموارد الموجودة:
   • Azure Cosmos DB for NoSQL account
   • حساب Azure Storage
   • Azure AI Search resource
   • مورد Azure Key Vault (يستخدم لإدارة الأسرار وسلاسل الاتصال لبنية الوكلاء التحتية)
   • [اختياري] Azure Application Insights resource
   • [اختياري] مورد Foundry الحالي

المرحلة الثانية: إنشاء موارد وروابط في مجال المسبك

2. أنشئ موردا لمايكروسوفت فاوندري.
3. أنشئ علاقات على مستوى الحساب:
   • أنشئ اتصالا حسابيا بمورد Application Insights الخاص بهم.
4. نشر gpt-4o أو نموذج متوافق مع وكيل آخر.
5. أنشئ project.
6. إنشاء روابط project:
   • [إذا تم توفيره] Project Connection بمورد Foundry.
   • Project connection إلى حساب Azure Storage.
   • الاتصال بالمشروع بمورد Azure AI Search.
   • اتصال Project بحساب Cosmos DB.

المرحلة 3: تعيين الأدوار لهوية إدارة project

تشمل هوية project managed Identity كل من الهوية المدارة المعينة من قبل النظام (SMI) والهوية المدارة المعينة من قبل المستخدم (UMI).

7. تعيين الأدوار التالية لهوية project managed (ل SMI):
   • مشغل قاعدة بيانات كوزموس على مستوى الحساب لمورد قاعدة بيانات كوزموس.
   • Storage مساهم الحساب على مستوى الحساب لمورد الحساب Storage.

المرحلة 4: تكوين مضيفي القدرات

8. قم بتعيين مضيف قدرة الحساب مع قسم الخصائص الفارغة.
9. قم بضبط مضيف قدرات project باستخدام اتصالات Cosmos DB وAzure Storage وAI Search.

المرحلة 5: تخصيص صلاحيات الموارد الحبيبية

10. تعيين الأدوار التالية لهوية إدارة project (SMI و UMI) على نطاقات الموارد المحددة:
    • Azure AI Search (تعيين إما قبل أو بعد إنشاء مضيف القدرات):
      • مساهم بيانات فهرس البحث
      • مساهم Search Service
    • Azure Blob Storage الحاوية: <workspaceId>-azureml-blobstore
      • المساهم في بيانات التخزين Blob
    • Azure Blob Storage الحاوية: <workspaceId>-agents-blobstore
      • مالك بيانات تخزين Blob
    • قاعدة بيانات كوزموس لقاعدة بيانات NoSQL: enterprise_memory
      • مساهم بيانات Cosmos DB المدمج
      • النطاق: مستوى قاعدة بيانات ليشمل جميع الحاويات (لا حاجة لتعيين دور خاص بالحاوية بشكل فردي).

المرحلة 6: منح المطور access

11. تعيين جميع المطورين الذين يحتاجون لإنشاء أو تحرير الوكلاء في project بدور Azure AI User على نطاق project.

استخدام قالب Bicep

استخدم Azure OpenAI موجود، أو حساب Azure Storage، Azure قاعدة بيانات كوزموس لحساب NoSQL، أو Azure AI Search مورد من خلال توفير معرف مورد Azure Resource Manager (ARM) الكامل في ملف قالب الوكيل standard file.

استخدم مورد Azure OpenAI موجود

1. اتبع الخطوات في إعداد البيئة للحصول على معرف مورد حساب أدوات الصيد.

2. في ملف قالب الوكيل القياسي، استبدل العنصر المؤقت التالي:

   existingAoaiResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{serviceName}
   

استخدم حساب Azure Storage موجود لملفات storage

1. سجل الدخول إلى Azure CLI واختر الاشتراك باستخدام حساب storage الخاص بك:

   az login
   

2. شغل الأمر التالي للحصول على معرف مورد حساب storage الخاص بك:

   az storage account show --resource-group <your-resource-group> --name <your-storage-account> --query "id" --output tsv
   

   المخرج هو القيمة التي aiStorageAccountResourceID تحتاجها في القالب.

3. في ملف قالب الوكيل القياسي، استبدل العنصر المؤقت التالي:

   aiStorageAccountResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{storageAccountName}
   

استخدم قاعدة بيانات Azure Cosmos موجودة لحساب NoSQL for thread storage

يتم إنشاء قاعدة بيانات Azure Cosmos لحساب NoSQL لكل حساب في Foundry. لمتطلبات النقل والتكبير متعدد project، انظر Cosmos DB requirementstability availability.

‏‫ملاحظة‬

عدم كفاية سعة RU/s في حساب قاعدة بيانات كوزموس يؤدي إلى فشل في توفير مضيف القدرات أثناء النشر.

1. سجل الدخول إلى Azure CLI واختر الاشتراك باستخدام حساب Cosmos DB الخاص بك:

   az login
   

2. شغل الأمر التالي للحصول على معرف مورد حساب قاعدة بيانات Azure Cosmos الخاص بك:

   az cosmosdb show --resource-group <your-resource-group> --name <your-cosmosdb-account> --query "id" --output tsv
   

   المخرج هو القيمة التي cosmosDBResourceId تحتاجها في القالب.

3. في ملف قالب الوكيل القياسي، استبدل العنصر المؤقت التالي:

   cosmosDBResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{cosmosDbAccountName}
   

استخدم مورد Azure AI Search موجود

1. سجل الدخول إلى Azure CLI واختر الاشتراك باستخدام مورد البحث الخاص بك:

   az login
   

2. شغل الأمر التالي للحصول على معرف الموارد الخاص بك في Azure AI Search:

   az search service show --resource-group <your-resource-group> --name <your-search-service> --query "id" --output tsv
   

3. في ملف قالب الوكيل القياسي، استبدل العنصر المؤقت التالي:

   aiSearchServiceResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}
   

التحقق من الإعداد

بعد إكمال التجهيز، تحقق من أن الإعداد يعمل بشكل صحيح:

1. في Azure portal، انتقل إلى Foundry project الخاص بك وتأكد من أن جميع الاتصالات (Storage، Cosmos DB، AI Search) تظهر تحت إعدادات project.
2. تحقق من أن حالة مضيف القدرة تظهر ك Succeeded لكل من الحساب و project.
3. تحقق من تعيين الأدوار من خلال التنقل إلى صفحة Access control (IAM) لكل مورد وتأكيد أن هوية project المدارة تحتوي على الأدوار المتوقعة.
4. أنشئ وكيل اختبار لتأكيد الوظائف من البداية إلى الطرف.

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

العرض	السبب	الحل
CapabilityHostProvisioningFailed أو عروض حالة مضيف القدرات فاشلة	معدل نقل البيانات في قاعدة بيانات كوزموس غير كاف	تأكد من أن حساب قاعدة بيانات Cosmos الخاص بك يحتوي على 3000 RU/s على الأقل (1000 RU/s لكل حاوية × 3 حاويات). لعدة مشاريع، اضربها في عدد المشاريع.
403 Forbidden عندما يقرأ الوكيل أو يكتب الملفات	تعيينات أدوار storage المفقودة	تحقق من أن الهوية المدارة project تحتوي على Storage مساهم بيانات الكتل على حاوية <workspaceId>-azureml-blobstore وStorage مالك بيانات الكتل على حاوية <workspaceId>-agents-blobstore.
SearchIndexNotFound أو 403 في عمليات البحث	أدوار البحث المفقودة	تأكد من أن الهوية المدارة project تحتوي على كل من Search Index Data Contributor و Search Service Contributor على Azure AI Search موردك.
AuthorizationFailed عند إنشاء أو تحرير الوكلاء	دور المستخدم المفقود	قم بتعيين دور Azure مستخدم الذكاء الاصطناعي للمطور في نطاق project.
إعادة طلب تحديث إلى مضيف القدرات 400 BadRequest	التحديث غير مدعوم	لا يمكن تحديث مضيفي القدرات بعد الإنشاء. قم بحذف وإعادة إنشاء project إذا كانت هناك حاجة لتغييرات في الإعدادات.

المحتوى ذو الصلة

• قم بإعداد بيئتك لخدمة وكلاء الصبك
• مضيفي القدرات
• Standard agentup setting by Vicep template