دعم المستند الأصلي للغة Azure الذكاء الاصطناعي (معاينة)

هام

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

• توفر إصدارات المعاينة العامة للغة Azure الذكاء الاصطناعي الوصول المبكر إلى الميزات قيد التطوير النشط.

• قد تتغير الميزات والنهج والعمليات، قبل التوفر العام (GA)، استنادا إلى ملاحظات المستخدم.

Azure الذكاء الاصطناعي Language هي خدمة مستندة إلى السحابة تطبق ميزات معالجة اللغة الطبيعية (NLP) على البيانات المستندة إلى النص. تمكنك إمكانية دعم المستند الأصلي من إرسال طلبات واجهة برمجة التطبيقات بشكل غير متزامن، باستخدام نص طلب HTTP POST لإرسال البيانات وسلسلة استعلام طلب HTTP GET لاسترداد نتائج الحالة. توجد المستندات المعالجة في حاوية هدف Azure Blob Storage.

يشير المستند الأصلي إلى تنسيق الملف المستخدم لإنشاء المستند الأصلي مثل Microsoft Word (docx) أو ملف مستند محمول (pdf). يلغي دعم المستند الأصلي الحاجة إلى المعالجة المسبقة للنص قبل استخدام قدرات مورد Azure الذكاء الاصطناعي Language. حاليا، يتوفر دعم المستند الأصلي للقدرات التالية:

• معلومات التعريف الشخصية (PII). يمكن لميزة الكشف عن PII تحديد وتصنيف وتنقيح المعلومات الحساسة في نص غير منظم. PiiEntityRecognition تدعم واجهة برمجة التطبيقات معالجة المستندات الأصلية.

• تلخيص المستند. يستخدم تلخيص المستندات معالجة اللغة الطبيعية لإنشاء ملخصات استخراجية (استخراج الجملة البارزة) أو ملخصات تجريدية (استخراج الكلمات السياقية) للمستندات. تدعم واجهات AbstractiveSummarization برمجة التطبيقات و ExtractiveSummarization معالجة المستندات الأصلية.

تنسيقات المستندات المعتمدة

تستخدم التطبيقات تنسيقات الملفات الأصلية لإنشاء المستندات الأصلية أو حفظها أو فتحها. تدعم إمكانات PII وتلخيصالمستندات حاليا تنسيقات المستندات الأصلية التالية:

نوع الملف	امتداد الملف	‏‏الوصف
نص	.txt	مستند نصي غير منسق.
Adobe PDF	.pdf	مستند محمول بتنسيق ملف مستند.
Microsoft Word	.docx	ملف مستند Microsoft Word.

إرشادات الإدخال

تنسيقات الملفات المدعومة

نوع	الدعم والقيود
ملفات pdf	ملفات PDF الممسوحة ضوئيا بالكامل غير مدعومة.
النص داخل الصور	الصور الرقمية ذات النص المضمن غير مدعومة.
الجداول الرقمية	الجداول في المستندات الممسوحة ضوئيا غير مدعومة.

حجم المستند

السمة	حد الإدخال
إجمالي عدد المستندات لكل طلب	≤ 20
إجمالي حجم المحتوى لكل طلب	≤ 1 ميغابايت

تضمين المستندات الأصلية مع طلب HTTP

لنبدأ:

• بالنسبة لهذا المشروع، نستخدم أداة سطر أوامر cURL لإجراء استدعاءات REST API.

  إشعار

  يتم تثبيت حزمة cURL مسبقا على معظم Windows 10 وWindows 11 ومعظم توزيعات macOS وLinux. يمكنك التحقق من إصدار الحزمة باستخدام الأوامر التالية: Windows: curl.exe -V macOS curl -V Linux: curl --version

• إذا لم يتم تثبيت cURL، فإليك روابط التثبيت للنظام الأساسي الخاص بك:

  • Windows.
  • Mac أو Linux.

• حساب Azureنشط. إذا لم يكن لديك حساب، يمكنك إنشاء حساب مجاني.

• حساب Azure Blob Storage. تحتاج أيضا إلى إنشاء حاويات في حساب Azure Blob Storage للملفات المصدر والهدف:

  • حاوية المصدر. هذه الحاوية هي المكان الذي تقوم فيه بتحميل ملفاتك الأصلية للتحليل (مطلوب).
  • الحاوية الهدف. هذه الحاوية هي المكان الذي يتم فيه تخزين الملفات التي تم تحليلها (مطلوب).

• مورد لغة خدمة واحدة (وليس مورد خدمات Azure الذكاء الاصطناعي متعدد الخدمات):

  أكمل حقلي "Language resource project" و"instance details" كما يلي:

  1. «Subscription» (الاشتراك) حدد أحد اشتراكات Azure المتوفرة.

  2. مجموعة الموارد يمكنك إنشاء مجموعة موارد جديدة أو إضافة المورد الخاص بك إلى مجموعة موارد موجودة مسبقًا تشترك في نفس دورة الحياة والأذونات والنُهج.

  3. منطقة المورد. اختر Global ما لم يتطلب عملك أو تطبيقك منطقة معينة. إذا كنت تخطط لاستخدام هوية مدارة معينة من قبل النظام (RBAC) للمصادقة، فاختر منطقة جغرافية مثل غرب الولايات المتحدة.

  4. الاسم. أدخل الاسم الذي اخترته للمورد الخاص بك. يجب أن يكون الاسم الذي تختاره فريدًا في Azure.

  5. مستوى الأسعار. يمكنك استخدام مستوى التسعير الحر (Free F0) لتجربة الخدمة، والترقية لاحقًا إلى مستوى مدفوع للإنتاج.

  6. حدد "استعراض + إنشاء".

  7. راجع شروط الخدمة وحدد Create لتوزيع موردك.

  8. بعد نشر المورد بنجاح، حدد Go to resource.

استرداد نقطة نهاية خدمة المفتاح واللغة

تتطلب الطلبات إلى خدمة Language مفتاحا للقراءة فقط ونقطة نهاية مخصصة لمصادقة الوصول.

1. إذا قمت بإنشاء مورد جديد، بعد نشره، فحدد Go to resource. إذا كان لديك مورد خدمة لغة موجود، فانتقل مباشرة إلى صفحة المورد.

2. في الجهة اليسرى، ضمن إدارة الموارد،حدد مفاتيح ونقطة النهاية.

3. يمكنك نسخ ولصق و key في language service instance endpoint نماذج التعليمات البرمجية لمصادقة طلبك إلى خدمة Language. مفتاح واحد فقط ضروري لإجراء استدعاء واجهة برمجة التطبيقات.

إنشاء حاويات تخزين Azure Blob

إنشاء حاويات في حساب Azure Blob Storage للملفات المصدر والهدف.

• حاوية المصدر. هذه الحاوية هي المكان الذي تقوم فيه بتحميل ملفاتك الأصلية للتحليل (مطلوب).
• الحاوية الهدف. هذه الحاوية هي المكان الذي يتم فيه تخزين الملفات التي تم تحليلها (مطلوب).

المصادقة

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

• الرموز المميزة لتوقيع الوصول المشترك (SAS). يتم تأمين رموز SAS المميزة لتفويض المستخدم باستخدام بيانات اعتماد Microsoft Entra. توفر رموز SAS وصولاً آمناً ومفوضاً إلى الموارد في حساب تخزين Azure الخاص بك.

• التحكم في الوصول المستند إلى دور الهوية المدارة (RBAC). الهويات المدارة لموارد Azure هي أساسيات الخدمة التي تنشئ هوية Microsoft Entra وأذونات محددة لموارد Azure المدارة.

بالنسبة لهذا المشروع، نقوم بمصادقة الوصول إلى source location وعناوين target location URL باستخدام الرموز المميزة لتوقيع الوصول المشترك (SAS) الملحقة كسلاسل استعلام. يتم تعيين كل رمز مميز إلى كائن ثنائي كبير الحجم معين (ملف).

• يجب أن تعين حاوية المصدر أو الكائن الثنائي كبير الحجم الوصول للقراءة والقائمة.
• يجب أن تعين الحاوية الهدف أو الكائن الثنائي كبير الحجم الوصول للكتابة والقائمة.

تلميح

نظرا لأننا نعالج ملفا واحدا (blob)، نوصي بتفويض الوصول إلى SAS على مستوى الكائن الثنائي كبير الحجم.

طلب الرؤوس والمعلمات

المعلمة	‏‏الوصف‬
-X POST <endpoint>	تحديد نقطة نهاية مورد اللغة للوصول إلى واجهة برمجة التطبيقات.
--header Content-Type: application/json	نوع المحتوى لإرسال بيانات JSON.
--header "Ocp-Apim-Subscription-Key:<key>	تحديد مفتاح مورد اللغة للوصول إلى واجهة برمجة التطبيقات.
-data	ملف JSON الذي يحتوي على البيانات التي تريد تمريرها مع طلبك.

يتم تنفيذ أوامر cURL التالية من BASH shell. قم بتحرير هذه الأوامر باستخدام اسم المورد الخاص بك ومفتاح المورد وقيم JSON. حاول تحليل المستندات الأصلية عن طريق تحديد نموذج المشروع أو Document Summarization التعليمات البرمجيةPersonally Identifiable Information (PII):

معلومات التعريف الشخصية (PII)

مستند نموذج PII

لبدء التشغيل السريع هذا، تحتاج إلى مستند مصدر تم تحميله إلى الحاوية المصدر. يمكنك تنزيل نموذج مستند Microsoft Word أو Adobe PDF لهذا المشروع. اللغة المصدر هي الإنجليزية.

إنشاء طلب POST

1. باستخدام المحرر المفضل لديك أو IDE، قم بإنشاء دليل جديد لتطبيقك المسمى native-document.

2. إنشاء ملف json جديد يسمى pii-detection.json في دليل المستند الأصلي.

3. انسخ والصق نموذج طلب معلومات التعريف الشخصية (PII) التالي في ملفكpii-detection.json. استبدل {your-source-container-SAS-URL} و {your-target-container-SAS-URL} بقيم من مثيل حاويات حساب تخزين مدخل Microsoft Azure:

نموذج الطلب

{
    "displayName": "Extracting Location & US Region",
    "analysisInput": {
        "documents": [
            {
                "language": "en-US",
                "id": "Output-excel-file",
                "source": {
                    "location": "{your-source-blob-with-SAS-URL}"
                },
                "target": {
                    "location": "{your-target-container-with-SAS-URL}"
                }
            } 
        ]
    },
    "tasks": [
        {
            "kind": "PiiEntityRecognition",
            "parameters":{
                "excludePiiCategories" : ["PersonType", "Category2", "Category3"],
                "redactionPolicy": "UseRedactionCharacterWithRefId" 
            }
        }
    ]
}

• القيمة المصدر location هي عنوان URL SAS للمستند المصدر (blob)، وليس عنوان URL ل SAS للحاوية المصدر.

• القيم المحتملة redactionPolicy هي UseRedactionCharacterWithRefId (افتراضي) أو UseEntityTypeName. لمزيد من المعلومات، راجعمعلمات PiiTask.

تشغيل طلب POST

1. فيما يلي البنية الأولية لطلب POST:

      POST {your-language-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview
   

2. قبل تشغيل طلب POST ، استبدل {your-language-resource-endpoint}{your-key} و بالقيم من مثيل خدمة لغة مدخل Microsoft Azure.

   هام

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

   بوويرشيل

      cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@pii-detection.json"
   

   موجه الأوامر / المحطة الطرفية

      curl -v -X POST "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@pii-detection.json"
   

3. فيما يلي نموذج استجابة:

   HTTP/1.1 202 Accepted
   Content-Length: 0
   operation-location: https://{your-language-resource-endpoint}/language/analyze-documents/jobs/f1cc29ff-9738-42ea-afa5-98d2d3cabf94?api-version=2023-11-15-preview
   apim-request-id: e7d6fa0c-0efd-416a-8b1e-1cd9287f5f81
   x-ms-region: West US 2
   Date: Thu, 25 Jan 2024 15:12:32 GMT
   

استجابة POST (معرف الوظيفة)

تتلقى استجابة 202 (نجاح) تتضمن عنوان Operation-Location للقراءة فقط. تحتوي قيمة هذا العنوان على معرف وظيفة يمكن الاستعلام عنه للحصول على حالة العملية غير المتزامنة واسترداد النتائج باستخدام طلب GET :

الحصول على نتائج التحليل (طلب GET)

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

2. فيما يلي البنية الأولية لطلب GET :

     GET {your-language-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview
   

3. قبل تشغيل الأمر، يرجى إجراء هذه التغييرات:

   • استبدل {jobId} برأس Operation-Location من استجابة POST.

   • استبدل {your-language-resource-endpoint} و{your-key} بالقيم من مثيل خدمة Language في مدخل Microsoft Azure.

الحصول على طلب

    cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview" -i -X GET --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

    curl -v -X GET "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

فحص الاستجابة

تتلقى استجابة 200 (نجاح) مع إخراج JSON. يشير حقل الحالة إلى نتيجة العملية. إذا لم تكتمل العملية، تكون قيمة الحالة "قيد التشغيل" أو "notStarted"، ويجب عليك استدعاء واجهة برمجة التطبيقات مرة أخرى، إما يدويا أو من خلال برنامج نصي. نوصي بفاصل زمني من ثانية واحدة أو أكثر بين كل استدعاء وآخر.

استجابة العينة

{
  "jobId": "f1cc29ff-9738-42ea-afa5-98d2d3cabf94",
  "lastUpdatedDateTime": "2024-01-24T13:17:58Z",
  "createdDateTime": "2024-01-24T13:17:47Z",
  "expirationDateTime": "2024-01-25T13:17:47Z",
  "status": "succeeded",
  "errors": [],
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "PiiEntityRecognitionLROResults",
        "lastUpdateDateTime": "2024-01-24T13:17:58.33934Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "id": "doc_0",
              "source": {
                "kind": "AzureBlob",
                "location": "https://myaccount.blob.core.windows.net/sample-input/input.pdf"
              },
              "targets": [
                {
                  "kind": "AzureBlob",
                  "location": "https://myaccount.blob.core.windows.net/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/PiiEntityRecognition-0001/input.result.json"
                },
                {
                  "kind": "AzureBlob",
                  "location": "https://myaccount.blob.core.windows.net/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/PiiEntityRecognition-0001/input.docx"
                }
              ],
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2023-09-01"
        }
      }
    ]
  }
}

تلخيص المستند

مستند عينة التلخيص

لهذا المشروع، تحتاج إلى مستند مصدر تم تحميله إلى الحاوية المصدر. يمكنك تنزيل نموذج مستند Microsoft Word أو Adobe PDF لبدء التشغيل السريع هذا. اللغة المصدر هي الإنجليزية.

إنشاء طلب POST

1. باستخدام المحرر المفضل لديك أو IDE، قم بإنشاء دليل جديد لتطبيقك المسمى native-document.

2. إنشاء ملف json جديد يسمى document-summarization.json في دليل المستند الأصلي.

3. انسخ نموذج طلب تلخيص المستند والصقه في document-summarization.json الملف. استبدل {your-source-container-SAS-URL} و {your-target-container-SAS-URL} بقيم من مثيل حاويات حساب تخزين مدخل Microsoft Azure:

نموذج الطلب

{
"tasks": [
  {
    "kind": "ExtractiveSummarization",
    "parameters": {
      "sentenceCount": 6
    }
  }
],
"analysisInput": {
  "documents": [
    {
      "source": {
        "location": "{your-source-blob-SAS-URL}"
      },
      "targets": {
        "location": "{your-target-container-SAS-URL}"
      }
    }
  ]
}
}

تشغيل طلب POST

قبل تشغيل طلب POST ، استبدل {your-language-resource-endpoint} و {your-key} بقيمة نقطة النهاية من مثيل مورد لغة مدخل Microsoft Azure.

هام

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

بوويرشيل

 cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@document-summarization.json"

موجه الأوامر / المحطة الطرفية

curl -v -X POST "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@document-summarization.json"

فيما يلي نموذج استجابة:

HTTP/1.1 202 Accepted
Content-Length: 0
operation-location: https://{your-language-resource-endpoint}/language/analyze-documents/jobs/f1cc29ff-9738-42ea-afa5-98d2d3cabf94?api-version=2023-11-15-preview
apim-request-id: e7d6fa0c-0efd-416a-8b1e-1cd9287f5f81
x-ms-region: West US 2
Date: Thu, 25 Jan 2024 15:12:32 GMT

استجابة POST (معرف الوظيفة)

تتلقى استجابة 202 (نجاح) تتضمن عنوان Operation-Location للقراءة فقط. تحتوي قيمة هذا العنوان على معرف وظيفة يمكن الاستعلام عنه للحصول على حالة العملية غير المتزامنة واسترداد النتائج باستخدام طلب GET:

الحصول على نتائج التحليل (طلب GET)

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

2. فيما يلي بنية طلب GET :

   GET {cognitive-service-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview
   

3. قبل تشغيل الأمر، يرجى إجراء هذه التغييرات:

   • استبدل {jobId} برأس Operation-Location من استجابة POST.

   • استبدل {your-language-resource-endpoint} و{your-key} بالقيم من مثيل خدمة Language في مدخل Microsoft Azure.

الحصول على طلب

    cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview" -i -X GET --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

    curl -v -X GET "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

فحص الاستجابة

تتلقى استجابة 200 (نجاح) مع إخراج JSON. يشير حقل الحالة إلى نتيجة العملية. إذا لم تكتمل العملية، تكون قيمة الحالة "قيد التشغيل" أو "notStarted"، ويجب عليك استدعاء واجهة برمجة التطبيقات مرة أخرى، إما يدويا أو من خلال برنامج نصي. نوصي بفاصل زمني من ثانية واحدة أو أكثر بين كل استدعاء وآخر.

استجابة العينة

{
  "jobId": "f1cc29ff-9738-42ea-afa5-98d2d3cabf94",
  "lastUpdatedDateTime": "2024-01-24T13:17:58Z",
  "createdDateTime": "2024-01-24T13:17:47Z",
  "expirationDateTime": "2024-01-25T13:17:47Z",
  "status": "succeeded",
  "errors": [],
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "ExtractiveSummarizationLROResults",
        "lastUpdateDateTime": "2024-01-24T13:17:58.33934Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "id": "doc_0",
              "source": {
                "kind": "AzureBlob",
                "location": "https://myaccount.blob.core.windows.net/sample-input/input.pdf"
              },
              "targets": [
                {
                  "kind": "AzureBlob",
                  "location": "https://myaccount.blob.core.windows.net/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/ExtractiveSummarization-0001/input.result.json"
                }
              ],
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2023-02-01-preview"
        }
      }
    ]
  }
}

عند الانتهاء بنجاح:

• يمكن العثور على المستندات التي تم تحليلها في الحاوية الهدف.
• يقوم أسلوب POST الناجح بإرجاع 202 Accepted رمز استجابة يشير إلى أن الخدمة أنشأت طلب الدفعة.
• أرجع طلب POST أيضا رؤوس الاستجابة بما في ذلك Operation-Location التي توفر قيمة مستخدمة في طلبات GET اللاحقة.

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

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

• المدخل
• Azure CLI

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

نظرة عامة على الكشف عن PII نظرة عامةعلى ملخص المستند