تعيين سياق مشروع Foundry لأوامر AZD

مهم

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

تعمل الأوامر azd ai في سياقين: داخل azd المشروع (سير عمل الفريق النموذجي) ومستقلة (عمل عشوائي، سكريبتات لمرة واحدة، أو استدعاءات من الأتمتة لا azure.yaml يوجد لها تثبيت على الموقع). كلا الوضعين يستهدفان نفس موارد Microsoft Foundry. تختلف فقط في كيفية تحديد مؤشر التحكم لأي مشروع من Foundry يجب التحدث إليه. في هذا المقال، تتعلم ترتيب الحل وكيفية ضبط السياق المستقل.

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

• تم تثبيت امتدادات Azure Developer CLI Foundry.
• جلسة Azure المصادقة (azd auth login).
• نقطة نهاية مشروع Foundry موجود للاستخدام المستقل.

متى تستخدم كل سياق

السياق	كيف يبدو	استخدم عندما
في مشروع azd	تعمل azd ai ... من مجلد يحتوي على azure.yaml بيئة نشطة azd .	أنت تبني أو تدير وكيلا كجزء من مشروع متتبع وتريد للبيئة أن تتحكم في أي مشروع Foundry تستهدفه.
مستقل	أنت تعمل azd ai ... من أي دليل آخر.	تقوم بعمل عشوائي ضد مشروع Foundry موجود، أو تقوم ببرمجة عمليات لمرة واحدة من الأتمتة التي لا تملك azd مشروعا.

أوامر الموارد (azd ai connection, azd ai toolbox, azd ai skill, و azd ai routine) تعمل على مشروع Foundry واحد، لذا تحتاج إلى نقطة نهاية مشروع تم حلها من أحد هذه السياقات قبل أن تتمكن من التشغيل.

الأوامر azd ai agent (مثل run، invoke، و optimize) ليست مستقلة. تتطلب مشروعا azdazure.yaml وحل بيئي. استخدم --agent-endpoint ذلك azd ai agent invoke لاستدعاء وكيل منشور بدون مشروع azd على القرص.

كيف تعمل حل نقاط النهاية

لكل أمر يستهدف مشروع Foundry، يقوم مؤشر التحكم بحل نقطة النهاية بهذا الترتيب. المصدر الأول الذي يعيد قيمة هو الفائز، ولا يتم استشارة المصادر اللاحقة:

1. -p علم OR --project-endpoint في الأمر. دائما هو الفائز، بغض النظر عن السياق.
2. البيئة النشطة azd ، إذا كنت داخل azd دليل مشروع.
3. الإعدادات العامة، تحت extensions.ai-agents.context.endpoint الداخل ~/.azd/config.json. هذا ما azd ai project set يكتب.
4. FOUNDRY_PROJECT_ENDPOINT متغير البيئة في القشرة الحالية.
5. خطأ. يخرج مؤشر القيادة باقتراح منظم للتشغيل azd ai project set أو التمرير --project-endpoint.

نقطة النهاية هي الشيء الوحيد الذي يحتاجه مؤشر السطر. يقوم بحل معرف الموارد في Azure Resource Manager (الاشتراك، مجموعة الموارد، الحساب، والمشروع) من نقطة النهاية عند وقت الاستدعاء، لذا تعمل الأوامر بنفس الطريقة سواء حصلت على نقطة النهاية من بيئتك أو من تكوينك العام.

حدد السياق المستقل

تكتب هذه azd ai project set الأوامر نقطة نهاية مشروع Foundry النشط إلى التكوين العام azd الخاص بك، لذا يمكن للأوامر التالية التي تعمل من أي مكان حذف --project-endpoint. تأخذ الأوامر نقطة النهاية كوجيطة موضعية:

azd ai project set https://my-project.services.ai.azure.com/api/projects/my-project

الأمر غير تفاعلي تماما عندما تتجاوز نقطة النهاية. أضف --no-prompt السكريبتات وCI بحيث تفشل قيمة مفقودة أو غير محلولة بسرعة بدلا من الحظر:

azd ai project set https://my-project.services.ai.azure.com/api/projects/my-project --no-prompt

ملحوظة

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

امسح السياق المستقل

azd ai project unset

يقوم هذا الأمر بإزالة الكتلة الكاملة context من ~/.azd/config.json. لا يمس أي azd قيم بيئية.

فحص السياق النشط

azd ai project show تقوم القيادة بتتبع سلسلة الدقة الكاملة وتبلغ عن المصدر الذي قدم نقطة النهاية النشطة. استخدمه لتأكيد ما تستهدفه قيادتك التالية قبل تشغيله:

azd ai project show

عينة من الناتج عندما تأتي نقطة النهاية من التكوين العام:

Project endpoint:  https://my-project.services.ai.azure.com/api/projects/my-project
Source:            global config (~/.azd/config.json)
Tenant:            contoso.onmicrosoft.com
Subscription:      Contoso Dev (00000000-0000-0000-0000-000000000000)
Foundry project:   my-project

داخل azd المشروع، يقرأ azd env <env-name> السطر Source بدلا من ذلك، والقيم المعروضة تأتي من ملف البيئة .env وليس من التكوين العام.

موقع التخزين

السياق المستقل يقع تحت extensions.ai-agents فضاء الأسماء في ~/.azd/config.json:

{
  "extensions": {
    "ai-agents": {
      "context": {
        "endpoint": "https://my-project.services.ai.azure.com/api/projects/my-project",
        "subscription": "00000000-0000-0000-0000-000000000000",
        "tenant": "contoso.onmicrosoft.com",
        "foundryProject": "my-project",
        "setAt": "2026-01-15T10:23:00Z"
      }
    }
  }
}

فقط endpoint هو القصة الرسمية. الحقول الأخرى موجودة لجعلها azd ai project show قابلة للقراءة. مؤشر القيادة لا يقرأها أبدا عند حل هدف. يمكنك تعديل الملف يدويا، لكن azd ai project setazd ai project unset هذه هي الطريقة المدعومة لإدارته.

الأسبقية داخل مشروع azd

داخل azd المشروع، دائما ما تتفوق نقطة نهاية المشروع في البيئة النشطة على السياق العالمي. التشغيل azd ai project set من داخل المشروع لا يزال يحدث الإعدادات العامة، لكن مؤشر القيادة يطبع تحذيرا من سطر واحد بأن البيئة لا تزال تأخذ الأولوية للأوامر التي تعمل من ذلك الدليل.

هذا السلوك مقصود. قيم بيئة على مستوى Project هي جزء من سير عمل الفريق، بينما السياق العالمي هو تفضيل لكل جهاز. لتجاوز البيئة لأمر واحد من داخل المشروع، قم بتمرير --project-endpoint، أو إعدائه FOUNDRY_PROJECT_ENDPOINT في الshell، بدلا من الاعتماد على التكوين العام.

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

• البدء السريع: نشر أول وكيل مستضاف لك
• تثبيت إضافات Azure Developer CLI Foundry
• تهيئة مشروع وكيل مستضاف باستخدام واجهة برمجة Azure Developer