الدرس التعليمي: الجزء الأول - إعداد بيئة المشاريع والتطوير لبناء تطبيق مخصص لاسترجاع المعرفة (RAG) باستخدام Microsoft Foundry SDK (الكلاسيكي)

ينطبق فقط على:بوابة Foundry (كلاسيكية). هذه المقالة غير متاحة لبوابة Foundry الجديدة. تعرف على المزيد حول البوابة الجديدة.

‏‫ملاحظة‬

قد تفتح الروابط في هذا المقال محتوى في وثائق Microsoft Foundry الجديدة بدلا من وثائق Foundry (الكلاسيكية) التي تشاهدها الآن.

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

• إنشاء مشروع
• Create an البحث باستخدام الذكاء الاصطناعي في Azure index
• تثبيت Azure CLI وتسجيل الدخول
• تثبيت Python والحزم
• نشر النماذج في مشروعك
• تكوين متغيرات البيئة الخاصة بك

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

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

مهم

توفر هذه المقالة دعما قديما للمشاريع القائمة على المركز. لن تنجح مع مشاريع Foundry. انظر: كيف أعرف نوع المشروع الذي لدي؟

<ملاحظة توافق ال c0>SDK: أمثلة الكود تتطلب نسخة محددة من Microsoft Foundry SDK. إذا واجهت مشاكل في التوافق، فكر في الانتقال من مشروع يعتمد على المركز إلى مشروع Foundry.

• حساب Azure مع اشتراك نشط ودور Owner أو Contributor مخصص. إذا لم يكن لديك حساب، فبادر بإنشاء حساب مجانا.
• Microsoft Foundry: دور المالك أو المساهم لإنشاء مشروع.

إنشاء مشروع مستند إلى المركز

لإنشاء مشروع قائم على المحور في Microsoft Foundry، اتبع الخطوات التالية:

1. سجل الدخول إلى Microsoft Foundry. تأكد من إيقاف مفتاح New Foundry . تشير هذه الخطوات إلى Foundry (الكلاسيكي).

   

2. يعتمد ما تقوم به بعد ذلك على مكان تواجدك:

   • إذا لم تكن في مشروع أو لم يكن لديك أي مشاريع بعد: اختر إنشاء جديد في أعلى اليمين لإنشاء مشروع Foundry جديد

     

   • إذا كنت في مشروع: حدد مسار التنقل للمشروع، ثم حدد إنشاء مورد جديد.

     

3. حدد الذكاء الاصطناعي hub resource، ثم حدد Next.

4. أدخل اسمًا للمشروع.

5. إذا كان لديك مركز، فسترى المركز الذي استخدمته مؤخرا محددا.

   • إذا كان لديك حق الوصول إلى أكثر من مركز واحد، يمكنك تحديد مركز مختلف من القائمة المنسدلة.

   • إذا أردت إنشاء مركز جديد، اختر إنشاء مركز جديد من القائمة المنسدلة.

     

6. إذا لم يكن لديك مركز، يتم إنشاء مركز افتراضي لك.

7. حدد إنشاء.

توزيع الوحدات

تحتاج إلى نموذجين لبناء تطبيق دردشة قائم على RAG: نموذج دردشة OpenAI Azure (gpt-4o-mini) ونموذج تضمين OpenAI Azure (text-embedding-ada-002). قم بنشر هذه النماذج في مشروع Foundry الخاص بك باستخدام هذه المجموعة من الخطوات لكل نموذج.

تقوم هذه الخطوات بنشر نموذج إلى نقطة نهاية في الوقت الحقيقي من كتالوج نماذج بوابة Foundry:

نصيحة

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

1. في الجزء الأيمن، حدد Model catalog.

2. حدد نموذج gpt-4o-mini من قائمة النماذج. يمكنك استخدام شريط البحث للعثور عليه.

   

3. في صفحة تفاصيل النموذج، حدد استخدام هذا النموذج.

4. اترك اسم النشر الافتراضي واختر النشر. أو، إذا لم يكن النموذج متوفرا في منطقتك، يتم تحديد منطقة مختلفة لك ومتصلة بمشروعك. في هذه الحالة، حدد Connect and deploy.

بعد نشر gpt-4o-mini، كرر الخطوات لنشر نموذج text-embedding-ada-002 .

Create an البحث باستخدام الذكاء الاصطناعي في Azure service

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

تحتاج إلى خدمة البحث باستخدام الذكاء الاصطناعي في Azure واتصال لإنشاء فهرس بحث.

‏‫ملاحظة‬

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

إذا كان لديك خدمة البحث باستخدام الذكاء الاصطناعي في Azure بالفعل، اذهب إلى next قسم.

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

نصيحة

هذه الخطوة هي المرة الوحيدة التي تستخدم فيها بوابة Azure في هذه السلسلة التعليمية. تقوم ببقية عملك في بوابة Foundry أو في بيئة التطوير المحلية.

1. إنشاء خدمة البحث باستخدام الذكاء الاصطناعي في Azure في بوابة Azure.
2. حدد مجموعة الموارد وتفاصيل المثيل. تحقق من مستويات الأسعار والتسعير في هذه الصفحة. لهذا الدرس، استخدم مستوى تسعير أساسي أو أعلى.
3. تابع من خلال المعالج وحدد Review + assign لإنشاء المورد.
4. تأكد من تفاصيل خدمة البحث باستخدام الذكاء الاصطناعي في Azure الخاصة بك، بما في ذلك التكلفة المقدرة.
5. اختر Create لإنشاء خدمة البحث باستخدام الذكاء الاصطناعي في Azure.

ربط البحث باستخدام الذكاء الاصطناعي في Azure بمشروعك

إذا كان مشروعك يحتوي بالفعل على اتصال البحث باستخدام الذكاء الاصطناعي في Azure، اذهب إلى تثبيت Azure CLI وسجل الدخول.

في بوابة Foundry، تحقق من وجود مورد متصل ب البحث باستخدام الذكاء الاصطناعي في Azure.

1. في Foundry، اذهب إلى مشروعك واختر مركز الإدارة من اللوحة اليسرى.

2. في قسم Connected resources، تحقق مما إذا كان لديك اتصال من النوع البحث باستخدام الذكاء الاصطناعي في Azure.

3. إذا كان لديك اتصال البحث باستخدام الذكاء الاصطناعي في Azure، يمكنك تخطي الخطوات التالية.

4. وإلا، اختر New connection ثم البحث باستخدام الذكاء الاصطناعي في Azure.

5. ابحث عن خدمة البحث باستخدام الذكاء الاصطناعي في Azure الخاصة بك في الخيارات واختر Add connection.

6. استخدم مفتاح APIللمصادقة.

   مهم

   لا يوصى بخيار مفتاح API للإنتاج. النهج الموصى به هو المصادقة Microsoft Entra ID، والتي تتطلب أدوار Search Index Data Contributor و Search Service Contributor (المكونة في المتطلبات المسبقة). لمزيد من المعلومات، راجع Connect to البحث باستخدام الذكاء الاصطناعي في Azure باستخدام roles. في هذا الدرس، مفتاح API مقبول إذا أردت التقدم بسرعة. انتقل إلى Entra ID قبل النشر في الإنتاج.

7. حدد إضافة اتصال.

إنشاء بيئة Python جديدة

في IDE الذي تختاره، أنشئ مجلدا جديدا لمشروعك. افتح نافذة طرفية في هذا المجلد.

أولا، أنشئ بيئة Python جديدة. لا تقم بتثبيت الحزم في تثبيت Python العالمي الخاص بك. استخدم دائما بيئة افتراضية أو بيئة كوندا عند تثبيت حزم Python. وإلا، يمكنك كسر تثبيت Python العالمي الخاص بك.

إذا لزم الأمر، قم بتثبيت Python

استخدم Python 3.10 أو أحدث، لكن على الأقل Python 3.9 مطلوب. إذا لم يكن لديك نسخة مناسبة من Python مثبتة، اتبع التعليمات في ><دليل Python VS لأسهل طريقة لتثبيت Python على نظام التشغيل الخاص بك.

إنشاء بيئة ظاهرية

إذا كان لديك بالفعل Python 3.10 أو أقدم، أنشئ بيئة افتراضية باستخدام الأوامر التالية:

Windows

py -3 -m venv .venv
.venv\scripts\activate

ينكس

python3 -m venv .venv
source .venv/bin/activate

python3 -m venv .venv
source .venv/bin/activate

عند تفعيل بيئة Python، فإن تشغيل python أو pip من سطر الأوامر يستخدم مفسر Python في مجلد .venv في تطبيقك.

‏‫ملاحظة‬

استخدم أمر deactivate للخروج من البيئة الافتراضية Python. يمكنك إعادة تفعيله لاحقا عند الحاجة.

تثبيت الحزم

تثبيت الحزم المطلوبة.

1. أنشئ ملفا باسم requirements.txt في مجلد مشروعك. أضف الحزم التالية إلى الملف:

   azure-ai-projects==1.0.0b10
   azure-ai-inference[prompts]
   azure-identity
   azure-search-documents
   pandas
   python-dotenv
   opentelemetry-api
   

   المراجع: Azure مكتبة عملاء مشاريع الذكاء الاصطناعي، azure-ai-inference، python-dotenv.

2. قم بتثبيت الحزم المطلوبة:

   pip install -r requirements.txt
   

تكوين متغيرات البيئة

سلسلة سلسلة الاتصال الخاصة بمشروعك مطلوبة لاستدعاء Azure OpenAI في Microsoft Foundry Models من كودك. في هذا التشغيل السريع، يمكنك حفظ هذه القيمة في .env ملف، وهو ملف يحتوي على متغيرات البيئة التي يمكن للتطبيق الخاص بك قراءتها.

.env إنشاء ملف، ولصق التعليمات البرمجية التالية:

AIPROJECT_CONNECTION_STRING=<your-connection-string>
AISEARCH_INDEX_NAME="example-index"
EMBEDDINGS_MODEL="text-embedding-ada-002"
INTENT_MAPPING_MODEL="gpt-4o-mini"
CHAT_MODEL="gpt-4o-mini"
EVALUATION_MODEL="gpt-4o-mini"

• ابحث عن سلسلة الاتصال في مشروع Foundry الذي أنشأته في ملعب Foundry quickstart. افتح المشروع، ثم ابحث عن سلسلة الاتصال في صفحة نظرة عامة. انسخ سلسلة الاتصال والصقه في ملف .env.

  

• إذا لم يكن لديك فهرس بحث بعد، فاحتفظ بالقيمة "example-index" ل AISEARCH_INDEX_NAME. في الجزء الثاني من هذا البرنامج التعليمي، ستقوم بإنشاء الفهرس باستخدام هذا الاسم. إذا قمت مسبقا بإنشاء فهرس بحث تريد استخدامه بدلا من ذلك، فقم بتحديث القيمة لمطابقة اسم فهرس البحث هذا.

• إذا قمت بتغيير أسماء النماذج عند نشرها، فقم بتحديث القيم الموجودة .env في الملف لمطابقة الأسماء التي استخدمتها.

نصيحة

إذا كنت تعمل في VS Code، أغلق نافذة المحطة الطرفية وأعد فتحها بعد حفظ التغييرات في .env الملف.

تحذير

تأكد من وجودك .env في ملفك .gitignore بحيث لا تحقق منه عن طريق الخطأ في مستودع git الخاص بك.

تثبيت Azure CLI وتسجيل الدخول

تقوم بتثبيت Azure CLI وتسجيل الدخول من بيئة التطوير المحلية لديك حتى يتمكن كودك من استخدام بيانات اعتماد المستخدم لاستدعاء خدمات Azure عبر Foundry.

في معظم الحالات يمكنك تثبيت Azure CLI من جهازك الطرفي باستخدام الأمر التالي:

Windows

winget install -e --id Microsoft.AzureCLI

ينكس

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

brew update && brew install azure-cli

يمكنك اتباع التعليمات كيفية تثبيت Azure CLI إذا لم تعمل هذه الأوامر مع نظام التشغيل أو إعدادك الخاص.

بعد تثبيت Azure CLI، سجل الدخول باستخدام أمر az login وسجل الدخول باستخدام المتصفح:

az login

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

az login --use-device-code

احتفظ بنافذة الطرفية مفتوحة لتشغيل سكريبتات بايثون من هنا أيضا، بعد تسجيل الدخول.

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

تحقق من أن بيئتك مضبوطة بشكل صحيح من خلال إجراء اختبار سريع:

import os
from azure.identity import DefaultAzureCredential
import azure.ai.projects

# Check the SDK version
print(f"Azure AI Projects SDK version: {azure.ai.projects.__version__}")

# Test that you can connect to your project
project = AIProjectClient.from_connection_string(
    conn_str=os.environ["AIPROJECT_CONNECTION_STRING"], credential=DefaultAzureCredential()
)
print("✓ Setup verified! Ready to build your RAG app.")

إذا رأيت "Setup successful!"، فإن بيانات اعتماد Azure وSDK لديك مضبوطة بشكل صحيح.

نصيحة

يتطلب هذا الدرس Azure إصدار حزمة تطوير البرمجيات للذكاء الاصطناعي 1.0.0b10. النسخة المعروضة أعلاه تساعدك على التحقق من التوافق. إذا كان لديك نسخة مختلفة، قد لا تكون الطريقة from_connection_string() متاحة. لتثبيت النسخة المطلوبة، قم بتشغيل pip install azure-ai-projects==1.0.0b10.

المراجع: Azure مكتبة عملاء مشاريع الذكاء الاصطناعي، DefaultAzureCredential.

إنشاء برنامج نصي مساعد

إنشاء مجلد لعملك. أنشئ ملفا باسم config.py في هذا المجلد. ستستخدم هذا السكربت المساعد في الجزأين التاليين من سلسلة الدروس التعليمية. يقوم السكربت بتحميل متغيرات البيئة ويقوم بتهيئة عميل Azure AI Projects. أضف التعليمات البرمجية التالية:

# ruff: noqa: ANN201, ANN001

import os
import sys
import pathlib
import logging
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.inference.tracing import AIInferenceInstrumentor

# load environment variables from the .env file
from dotenv import load_dotenv

load_dotenv()

# Set "./assets" as the path where assets are stored, resolving the absolute path:
ASSET_PATH = pathlib.Path(__file__).parent.resolve() / "assets"

# Configure an root app logger that prints info level logs to stdout
logger = logging.getLogger("app")
logger.setLevel(logging.INFO)
logger.addHandler(logging.StreamHandler(stream=sys.stdout))


# Returns a module-specific logger, inheriting from the root app logger
def get_logger(module_name):
    return logging.getLogger(f"app.{module_name}")


# Enable instrumentation and logging of telemetry to the project
def enable_telemetry(log_to_project: bool = False):
    AIInferenceInstrumentor().instrument()

    # enable logging message contents
    os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "true"

    if log_to_project:
        from azure.monitor.opentelemetry import configure_azure_monitor

        project = AIProjectClient.from_connection_string(
            conn_str=os.environ["AIPROJECT_CONNECTION_STRING"], credential=DefaultAzureCredential()
        )
        tracing_link = f"https://ai.azure.com/tracing?wsid=/subscriptions/{project.scope['subscription_id']}/resourceGroups/{project.scope['resource_group_name']}/providers/Microsoft.MachineLearningServices/workspaces/{project.scope['project_name']}"
        application_insights_connection_string = project.telemetry.get_connection_string()
        if not application_insights_connection_string:
            logger.warning(
                "No application insights configured, telemetry will not be logged to project. Add application insights at:"
            )
            logger.warning(tracing_link)

            return

        configure_azure_monitor(connection_string=application_insights_connection_string)
        logger.info("Enabled telemetry logging to project, view traces at:")
        logger.info(tracing_link)

المراجع: AIProjectClient، DefaultAzureCredential، load_dotenv.

‏‫ملاحظة‬

يستخدم هذا البرنامج النصي أيضا حزمة لم تقم بتثبيتها بعد، azure.monitor.opentelemetry. ستقوم بتثبيت هذه الحزمة في الجزء التالي من سلسلة البرامج التعليمية.

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

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

لكن لا تحذفها الآن إذا كنت تريد بناء تطبيق دردشة في الجزء القادم من هذه السلسلة الدروسية.

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

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

الجزء 2: ابن تطبيق دردشة مخصص باستخدام Azure AI SDK