جلسات مترجم التعليمات البرمجية بلا خادم في Azure Container Apps

مقالة
10/24/2024

توفر جلسات Azure Container Apps الديناميكية وصولا سريعا وقابلا للتطوير إلى مترجم التعليمات البرمجية. يتم عزل كل جلسة مترجم تعليمة برمجية بشكل كامل بواسطة حد Hyper-V وتم تصميمها لتشغيل التعليمات البرمجية غير الموثوق بها.

يستخدم لجلسات مترجم التعليمات البرمجية

جلسات مترجم التعليمات البرمجية مثالية للسيناريوهات التي تحتاج فيها إلى تشغيل التعليمات البرمجية التي يحتمل أن تكون ضارة أو قد تسبب ضررا للنظام المضيف أو المستخدمين الآخرين، مثل:

التعليمات البرمجية التي تم إنشاؤها بواسطة نموذج لغة كبير (LLM).
التعليمات البرمجية المرسلة من قبل مستخدم في تطبيق ويب أو SaaS.

بالنسبة لأطر عمل LLM الشائعة مثل LangChain أو LlamaIndex أو Kernel الدلالي، يمكنك استخدام الأدوات والمكونات الإضافية لدمج تطبيقات الذكاء الاصطناعي مع جلسات مترجم التعليمات البرمجية.

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

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

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

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

يمكنك إنشاء تجمع جلسة عمل باستخدام مدخل Microsoft Azure أو Azure CLI أو قوالب Azure Resource Manager. بعد إنشاء تجمع جلسة عمل، يمكنك استخدام نقاط نهاية API لإدارة التجمع لإدارة التعليمات البرمجية وتنفيذها داخل جلسة عمل.

إنشاء تجمع جلسة عمل باستخدام Azure CLI

لإنشاء تجمع جلسة مترجم التعليمات البرمجية باستخدام Azure CLI، تأكد من أن لديك أحدث إصدارات Azure CLI وملحق Azure Container Apps مع الأوامر التالية:

# Upgrade the Azure CLI
az upgrade

# Install or upgrade the Azure Container Apps extension
az extension add --name containerapp --upgrade --allow-preview true -y

az containerapps sessionpool create استخدم الأمر لإنشاء التجمع. ينشئ المثال التالي تجمع جلسة مترجم تعليمة برمجية Python باسم my-session-pool. تأكد من استبدال <RESOURCE_GROUP> باسم مجموعة الموارد قبل تشغيل الأمر.

az containerapp sessionpool create \
    --name my-session-pool \
    --resource-group <RESOURCE_GROUP> \
    --location westus2 \
    --container-type PythonLTS \
    --max-sessions 100 \
    --cooldown-period 300 \
    --network-status EgressDisabled

يمكنك تحديد الإعدادات التالية عند إنشاء تجمع جلسة عمل:

الإعدادات	‏‏الوصف
`--container-type`	نوع مترجم التعليمات البرمجية المراد استخدامه. القيمة الوحيدة المدعومة هي `PythonLTS`.
`--max-sessions`	الحد الأقصى لعدد جلسات العمل المخصصة المسموح بها بشكل متزامن. القيمة القصوى هي `600`.
`--cooldown-period`	عدد ثواني الخمول المسموح بها قبل الإنهاء. تتم إعادة تعيين فترة الخمول في كل مرة يتم فيها استدعاء واجهة برمجة تطبيقات الجلسة. النطاق المسموح به بين `300` و `3600`.
`--network-status`	تعيين ما إذا كان يسمح بنسبة استخدام الشبكة الصادرة من جلسة العمل. القيم الصالحة هي `EgressDisabled` (افتراضي) و `EgressEnabled`.

هام

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

الحصول على نقطة نهاية API لإدارة التجمع باستخدام Azure CLI

لاستخدام جلسات مترجم التعليمات البرمجية مع تكاملات إطار عمل LLM أو عن طريق استدعاء نقاط نهاية API للإدارة مباشرة، تحتاج إلى نقطة نهاية API لإدارة التجمع. نقطة النهاية بالتنسيق https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>.

لاسترداد نقطة نهاية واجهة برمجة تطبيقات الإدارة لتجمع جلسة عمل، استخدم az containerapps sessionpool show الأمر . تأكد من استبدال <RESOURCE_GROUP> باسم مجموعة الموارد قبل تشغيل الأمر.

az containerapp sessionpool show \
    --name my-session-pool \
    --resource-group <RESOURCE_GROUP> \
    --query 'properties.poolManagementEndpoint' -o tsv

تنفيذ التعليمات البرمجية في جلسة عمل

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

معرفات الجلسة

هام

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

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

إذا كانت هناك جلسة عمل قيد التشغيل مع المعرف، تتم إعادة استخدام الجلسة. إذا لم تكن هناك جلسة عمل قيد التشغيل مع المعرف، يتم إنشاء جلسة عمل جديدة تلقائيا.

لمعرفة المزيد حول معرفات الجلسة، راجع نظرة عامة على الجلسات.

المصادقة

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

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

إذا كنت تستخدم نقاط نهاية API لإدارة التجمع مباشرة، يجب إنشاء رمز مميز وتضمينه في Authorization عنوان طلبات HTTP الخاصة بك. بالإضافة إلى تعيينات الدور المذكورة سابقا، يجب أن يحتوي الرمز المميز على مطالبة جماعة مستهدفة (aud) بقيمة https://dynamicsessions.io.

لمعرفة المزيد، راجع المصادقة.

تكاملات إطار عمل LLM

بدلا من استخدام واجهة برمجة تطبيقات إدارة تجمع الجلسة مباشرة، توفر أطر عمل LLM التالية عمليات تكامل مع جلسات مترجم التعليمات البرمجية:

Framework	الحزمة	برنامج تعليمي
LangChain	Python: `langchain-azure-dynamic-sessions`	تعليمي
LlamaIndex	Python: `llama-index-tools-azure-code-interpreter`	تعليمي
نواة دلالية	Python: `semantic-kernel` (الإصدار 0.9.8-b1 أو أحدث)	تعليمي

نقاط نهاية واجهة برمجة تطبيقات الإدارة

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

تتوفر نقاط النهاية التالية لإدارة جلسات العمل في تجمع:

مسار نقطة النهاية	الطريقة	‏‏الوصف
`code/execute`	`POST`	تنفيذ التعليمات البرمجية في جلسة عمل.
`files/upload`	`POST`	تحميل ملف إلى جلسة عمل.
`files/content/{filename}`	`GET`	قم بتنزيل ملف من جلسة عمل.
`files`	`GET`	سرد الملفات في جلسة عمل.

أنشئ عنوان URL الكامل لكل نقطة نهاية عن طريق ربط نقطة نهاية API لإدارة التجمع بمسار نقطة النهاية. يجب أن تتضمن سلسلة الاستعلام معلمة identifier تحتوي على معرف جلسة العمل، ومعلمة api-version بقيمة 2024-02-02-preview.

على سبيل المثال: https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/code/execute?api-version=2024-02-02-preview&identifier=<IDENTIFIER>

تنفيذ التعليمات البرمجية في جلسة عمل

لتنفيذ التعليمات البرمجية في جلسة عمل، أرسل POST طلبا إلى code/execute نقطة النهاية مع التعليمات البرمجية للتشغيل في نص الطلب. يطبع هذا المثال "Hello, world!" في Python.

قبل إرسال الطلب، استبدل العناصر النائبة بين الأقواس <> بالقيم المناسبة لتجمع جلسة العمل ومعرف الجلسة.

POST https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/code/execute?api-version=2024-02-02-preview&identifier=<SESSION_ID>
Content-Type: application/json
Authorization: Bearer <token>

{
    "properties": {
        "codeInputType": "inline",
        "executionType": "synchronous",
        "code": "print('Hello, world!')"
    }
}

لإعادة استخدام جلسة عمل، حدد نفس معرف جلسة العمل في الطلبات اللاحقة.

تحميل ملف إلى جلسة عمل

لتحميل ملف إلى جلسة عمل، أرسل POST طلبا إلى uploadFile نقطة النهاية في طلب بيانات نموذج متعدد الأحزاب. تضمين بيانات الملف في نص الطلب. يجب أن يتضمن الملف اسم ملف.

يتم تخزين الملفات التي تم تحميلها في نظام ملفات الجلسة ضمن /mnt/data الدليل.

قبل إرسال الطلب، استبدل العناصر النائبة بين الأقواس <> بقيم خاصة بطلبك.

POST https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files/upload?api-version=2024-02-02-preview&identifier=<SESSION_ID>
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Authorization: Bearer <token>

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="<FILE_NAME_AND_EXTENSION>"
Content-Type: application/octet-stream

(data)
------WebKitFormBoundary7MA4YWxkTrZu0gW--

إشعار

حد تحميل الملف هو 128MB. إذا تم HTTP 413 تجاوز ذلك، فقد يتم إرجاع.

تنزيل ملف من جلسة عمل

لتنزيل ملف من دليل جلسة /mnt/data عمل، أرسل GET طلبا إلى file/content/{filename} نقطة النهاية. تتضمن الاستجابة بيانات الملف.

قبل إرسال الطلب، استبدل العناصر النائبة بين الأقواس <> بقيم خاصة بطلبك.

GET https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files/content/<FILE_NAME_AND_EXTENSION>?api-version=2024-02-02-preview&identifier=<SESSION_ID>
Authorization: Bearer <TOKEN>

سرد الملفات في جلسة عمل

لسرد الملفات في دليل جلسة /mnt/data العمل، أرسل GET طلبا إلى files نقطة النهاية.

قبل إرسال الطلب، استبدل العناصر النائبة بين الأقواس <> بقيم خاصة بطلبك.

GET https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files?api-version=2024-02-02-preview&identifier=<SESSION_ID>
Authorization: Bearer <TOKEN>

تحتوي الاستجابة على قائمة بالملفات في جلسة العمل.

تعرض القائمة التالية عينة من نوع الاستجابة التي يمكنك توقعها من طلب محتويات جلسة العمل.

{
    "$id": "1",
    "value": [
        {
            "$id": "2",
            "properties": {
                "$id": "3",
                "filename": "test1.txt",
                "size": 16,
                "lastModifiedTime": "2024-05-02T07:21:07.9922617Z"
            }
        },
        {
            "$id": "4",
            "properties": {
                "$id": "5",
                "filename": "test2.txt",
                "size": 17,
                "lastModifiedTime": "2024-05-02T07:21:08.8802793Z"
            }
        }
    ]
}

الحزم المثبتة مسبقا

تتضمن جلسات مترجم تعليمة Python البرمجية حزم Python الشائعة مثل NumPy وpandas وscikit-learn.

لإخراج قائمة الحزم المثبتة مسبقا، قم باستدعاء code/execute نقطة النهاية بالتعليمات البرمجية التالية.

قبل إرسال الطلب، استبدل العناصر النائبة بين الأقواس <> بقيم خاصة بطلبك.

POST https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/identifier/<SESSION_ID>/code/execute?api-version=2024-02-02-preview&identifier=<SESSION_ID>
Content-Type: application/json
Authorization: Bearer <TOKEN>

{
    "properties": {
        "codeInputType": "inline",
        "executionType": "synchronous",
        "code": "import pkg_resources\n[(d.project_name, d.version) for d in pkg_resources.working_set]"
    }
}

الفوترة

تتم فوترة جلسات مترجم التعليمات البرمجية استنادا إلى مدة كل جلسة. راجع الفوترة لمزيد من المعلومات.

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

التشغيل السريع: استخدام جلسات مترجم التعليمات البرمجية مع LangChain

مشاركة عبر

جلسات مترجم التعليمات البرمجية بلا خادم في Azure Container Apps

يستخدم لجلسات مترجم التعليمات البرمجية

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

إنشاء تجمع جلسة عمل باستخدام Azure CLI

الحصول على نقطة نهاية API لإدارة التجمع باستخدام Azure CLI

تنفيذ التعليمات البرمجية في جلسة عمل

معرفات الجلسة

المصادقة

تكاملات إطار عمل LLM

نقاط نهاية واجهة برمجة تطبيقات الإدارة

تنفيذ التعليمات البرمجية في جلسة عمل

تحميل ملف إلى جلسة عمل

تنزيل ملف من جلسة عمل

سرد الملفات في جلسة عمل

الحزم المثبتة مسبقا

تسجيل الدخول

الفوترة

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

الملاحظات

الموارد الإضافية