الحاوية: ترجمة النص

مقالة
04/29/2024

ترجمة النص.

URL للطلب

إرسال طلب POST إلى:

POST http://localhost:{port}/translate?api-version=3.0&&from={from}&to={to}

طلب مثال

curl -x POST "https:localhost:5000/translate?api-version=3.0&from=en&to=es" -H "Content-Type: application/json" -d "[{
'Text': 'I would really like to drive your car.'}]"

مثال على الاستجابة

[
  {
    "translations": [
      {
        "text": "Realmente me gustaría conducir su coche.",
        "to": "es"
      }
    ]
  }
]

معلمات الطلب

معلمات الطلب التي تم تمريرها على سلسلة الاستعلام هي:

تتمثل المعلمات المطلوبة في الآتي

معلمة الاستعلام	‏‏الوصف	الحالة
نسخة واجهة برمجة التطبيقات	إصدار API التي طلبها العميل. يجب أن تكون القيمة `3.0`.	المعلمة المطلوبة
من	اكتشاف لغة نص الإدخال.	المعلمة المطلوبة
to	اكتشاف لغةِ نص الإخراج. على سبيل المثال، استخدم `to=de` للترجمة إلى الألمانية. يمكن الترجمة إلى لغات متعددة في وقت واحد عن طريق تكرار المعلمة في سلسلة الاستعلام. على سبيل المثال، استخدم `to=de&to=it` للترجمة إلى الألمانية والإيطالية.	المعلمة المطلوبة

يمكنك الاستعلام عن الخدمة للغات translation المدعومة بالنطاق.
راجع أيضادعم اللغة لللغة.

تتمثل المعلمات الاختيارية في الآتي

معلمة الاستعلام	‏‏الوصف
textType	المعلمة الاختيارية. تحديد ما إن كان النص الذي تتم ترجمته نصًا عاديًا أو نص HTML. يجب أن يكون أي HTML ببنية صحيحة وعناصر كاملة. القيم المحتملة هي `plain` (افتراضي) أو `html`.
includeSentenceLength	المعلمة الاختيارية. تحديد ما إن كان يجب تضمين حدود الجملة لنص الإدخال والنص المترجم. القيم المحتملة هي: `true` أو `false` (افتراضي).

عناوين الطلبات

الرؤوس	‏‏الوصف	الحالة
رؤوس المصادقة	راجعالخيارات المتوفرة للمصادقة.	عنوان الطلب المطلوب
نوع المحتوى	يحدد نوع محتوى الحمولة. القيمة المقبولة هي: `application/json; charset=UTF-8`.	عنوان الطلب المطلوب
طول المحتوى	طول نص الطلب.	اختياري
X-ClientTraceId	معرّف GUID تم إنشاؤه بواسطة العميل لتعريف الطلب بشكل فريد. يمكنك حذف هذا الرأس إذا قمت بتضمين معرف التتبع في سلسلة الاستعلام باستخدام معلمة الاستعلام المسماة `ClientTraceId`.	اختياري

نص الطلب

نص الطلب عبارة عن صفيف JSON. كل عنصر صفيف هو كائن JSON بخاصية سلسلة تسمى Text، والتي تمثل السلسلة المراد ترجمتها.

[
    {"Text":"I would really like to drive your car around the block a few times."}
]

تُطبق القيود التالية:

يمكن أن يحتوي الصفيف على 100 عنصر كحد أقصى.
لا يمكن أن يزيد النص المضمن في الطلب عن 10000 حرف بما في ذلك المسافات.

هيئة الاستجابة

الاستجابة الناجحة هي صفيف JSON مع نتيجة واحدة لكل سلسلة في الصفيفِ الخاص بالإدخال. يتضمن عنصر النتيجة الخصائص التالية:

translations: صفيف من نتائج الترجمة. يطابق حجم الصفيف عدد اللغات المستهدفة والمحددة من خلال معلمة الاستعلام to. يشمل كل عنصر في الصفيف ما يلي:
to: سلسلة تمثل التعليمات البرمجية للغة الهدف.
text: سلسلة تقدم النص المترجم.
sentLen: كائن يرجع حدود الجملة في نصوص الإدخال والإخراج.
srcSentLen: صفيف عدد صحيح يمثل طول الجمل في نص الإدخال. طول الصفيف هو عدد الجمل، والقيم هي طول كل جملة.
transSentLen: صفيف عدد صحيح يمثل طول الجمل في النص المترجم. طول الصفيف هو عدد الجمل، والقيم هي طول كل جملة.

يتم تضمين حدود الجملة فقط عندما تكون معلمة الطلب includeSentenceLength هي true.
- sourceText: كائن بخاصية سلسلة واحدة تسمى text، والذي يعطي نص الإدخال في البرنامج النصي الافتراضي للغة المصدر. الخاصية sourceText موجودة فقط عندما يتم التعبير عن الإدخال في برنامج نصي وهو ليس البرنامج النصي المعتاد للغة. على سبيل المثال، إذا كان الإدخال باللغة العربية ومكتوبًا بأحرف لاتينية، فسيكون sourceText.text النص العربي نفسه الذي تم تحويله إلى أحرف عربية.

رؤوس الردود

الرؤوس	‏‏الوصف
X-RequestId	القيمة التي تم إنشاؤها بواسطة الخدمة لتحديد الطلب واستخدامها لأغراض استكشاف الأخطاء وإصلاحها.
X-MT-System	يحدد نوع النظام الذي تم استخدامه للترجمة لكل لغة «إلى» المطلوبة للترجمة. القيمة هي قائمة سلاسل مفصولة بفواصل. تشير كل سلسلة إلى نوع: ▪ مخصص - يتضمن الطلب نظاما مخصصا وتم استخدام نظام مخصص واحد على الأقل أثناء الترجمة. ▪ الفريق - جميع الطلبات الأخرى

الرؤوس

‏‏الوصف

X-RequestId

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

X-MT-System

يحدد نوع النظام الذي تم استخدامه للترجمة لكل لغة «إلى» المطلوبة للترجمة. القيمة هي قائمة سلاسل مفصولة بفواصل. تشير كل سلسلة إلى نوع:

▪ مخصص - يتضمن الطلب نظاما مخصصا وتم استخدام نظام مخصص واحد على الأقل أثناء الترجمة.
▪ الفريق - جميع الطلبات الأخرى

رموز حالة الاستجابة

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

نماذج التعليمات البرمجية: ترجمة النص

إشعار

يتم تشغيل كل نموذج على localhost الذي حددته باستخدام docker run الأمر .
أثناء تشغيل الحاوية الخاصة بك، localhost يشير إلى الحاوية نفسها.
ليس عليك استخدام localhost:5000. يمكنك استخدام أي منفذ غير مستخدم بالفعل في بيئة المضيف.

ترجمة إدخال واحد

يوضح المثال ترجمة جملة واحدة من الإنجليزية إلى الصينية المبسطة.

curl -X POST "http://localhost:{port}/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

نص الاستجابة هو:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"}
        ]
    }
]

يتضمن الصفيف translations عنصرًا واحدًا، والذي يوفر ترجمة جزء واحد من النص في الإدخال.

الاستعلام عن نقطة نهاية Azure الذكاء الاصطناعي المترجم (نص)

فيما يلي مثال لطلب cURL HTTP باستخدام localhost:5000 الذي حددته مع docker run الأمر:

  curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-HANS"
    -H "Content-Type: application/json" -d "[{'Text':'Hello, what is your name?'}]"

إشعار

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

ترجمة النص باستخدام واجهة برمجة تطبيقات Swagger

الإنجليزية ↔ الألمانية

انتقل إلى صفحة Swagger: http://localhost:5000/swagger/index.html
حدد POST /translate
حدد Try it out
أدخل المعلمة From كـ en
أدخل المعلمة To كـ de
أدخل معلمة api-version كـ 3.0
تحت النصوص، استبدال string بـ JSON التالية

  [
        {
            "text": "hello, how are you"
        }
  ]

حدد تنفيذ، والترجمات الناتجة هي الإخراج في نص الاستجابة. يجب أن تتلقى الرد الآتي:

"translations": [
      {
          "text": "hallo, wie geht es dir",
          "to": "de"
      }
    ]

ترجمة النص باستخدام Python

الإنجليزية ↔ الفرنسية

import requests, json

url = 'http://localhost:5000/translate?api-version=3.0&from=en&to=fr'
headers = { 'Content-Type': 'application/json' }
body = [{ 'text': 'Hello, how are you' }]

request = requests.post(url, headers=headers, json=body)
response = request.json()

print(json.dumps(
    response,
    sort_keys=True,
     indent=4,
     ensure_ascii=False,
     separators=(',', ': ')))

ترجمة النص باستخدام تطبيق وحدة التحكم C#/.NET

الأسبانية الإنجليزية ↔

افتح Visual Studio وأنشئ تطبيق وحدة تحكم جديد. قم بتحرير *.csproj الملف لإضافة العقدة <LangVersion>7.1</LangVersion> — يحدد C# 7.1. أضف الإصدار 11.0.2 من حزمة Newtoonsoft.Json NuGet.

في Program.cs استبدل كافة التعليمات البرمجية الموجودة بالبرنامج النصي التالي:

using Newtonsoft.Json;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

namespace TranslateContainer
{
    class Program
    {
        const string ApiHostEndpoint = "http://localhost:5000";
        const string TranslateApi = "/translate?api-version=3.0&from=en&to=es";

        static async Task Main(string[] args)
        {
            var textToTranslate = "Sunny day in Seattle";
            var result = await TranslateTextAsync(textToTranslate);

            Console.WriteLine(result);
            Console.ReadLine();
        }

        static async Task<string> TranslateTextAsync(string textToTranslate)
        {
            var body = new object[] { new { Text = textToTranslate } };
            var requestBody = JsonConvert.SerializeObject(body);

            var client = new HttpClient();
            using (var request =
                new HttpRequestMessage
                {
                    Method = HttpMethod.Post,
                    RequestUri = new Uri($"{ApiHostEndpoint}{TranslateApi}"),
                    Content = new StringContent(requestBody, Encoding.UTF8, "application/json")
                })
            {
                // Send the request and await a response.
                var response = await client.SendAsync(request);

                return await response.Content.ReadAsStringAsync();
            }
        }
    }
}

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

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

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}, {'Text':'I am fine, thank you.'}]"

تحتوي الاستجابة على ترجمة جميع أجزاء النص بنفس الترتيب تمامًا كما في الطلب. نص الاستجابة هو:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"}
        ]
    },
    {
        "translations":[
            {"text":"我很好，谢谢你。","to":"zh-Hans"}
        ]
    }
]

الترجمة للغات متعددة

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

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-Hans&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

نص الاستجابة هو:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"},
            {"text":"Hallo, was ist dein Name?","to":"de"}
        ]
    }
]

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

من الشائع ترجمة المحتوى الذي يحتوي على علامات مثل المحتوى من صفحة HTML أو محتوى من مستند XML. قم بتضمين معلمة الاستعلام textType=html في أثناء ترجمة المحتوى الذي يحتوي على علامات. بالإضافة إلى ذلك، من المفيد أحيانًا استبعاد محتوى معين من الترجمة. يمكنك استخدام السمة class=notranslate لتحديد المحتوى الذي يجب أن يظل بلغته الأصلية. في المثال التالي، لا تتم ترجمة المحتوى داخل العنصر الأول div ، بينما تتم ترجمة المحتوى في العنصر الثاني div .

<div class="notranslate">This will not be translated.</div>
<div>This will be translated. </div>

فيما يلي عينة طلب لتوضيحه.

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-Hans&textType=html" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'<div class=\"notranslate\">This will not be translated.</div><div>This will be translated.</div>'}]"

الاستجابة هي:

[
    {
        "translations":[
            {"text":"<div class=\"notranslate\">This will not be translated.</div><div>这将被翻译。</div>","to":"zh-Hans"}
        ]
    }
]

الترجمة باستخدام قاموس ديناميكي

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

تستخدم العلامة المفترض توفيرها البنية التالية.

<mstrans:dictionary translation="translation of phrase">phrase</mstrans:dictionary>

على سبيل المثال، ضع في اعتبارك الجملة الإنجليزية «كلمة wordomatic هي إدخال قاموس.» للحفاظ على كلمة wordomatic في الترجمة، أرسل الطلب:

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The word <mstrans:dictionary translation=\"wordomatic\">word or phrase</mstrans:dictionary> is a dictionary entry.'}]"

النتيجة هي:

[
    {
        "translations":[
            {"text":"Das Wort \"wordomatic\" ist ein Wörterbucheintrag.","to":"de"}
        ]
    }
]

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

حدود الطلب

يقتصر كل طلب ترجمة على 10000 حرف، عبر جميع اللغات المستهدفة التي تترجم إليها. على سبيل المثال، يؤدي إرسال طلب ترجمة مكون من 3000 حرف للترجمة إلى ثلاث لغات مختلفة إلى حجم طلب يبلغ 3000x3 = 9000 حرف، والذي يلبي حد الطلب. يتم تحصيل رسوم منك لكل حرف، وليس بعدد الطلبات. نوصي بإرسال طلبات أقصر.

يسرد الجدول التالي عنصر الصفيف وحدود الأحرف لكل عملية من عمليات ترجمة المترجم.

العملية	الحد الأقصى لحجم عنصر الصفيف	الحد الأقصى لعدد عناصر الصفيف	الحد الأقصى لحجم الطلب (أحرف)
translate	10,000	100	10,000

استخدام docker compose: المترجم مع الحاويات الداعمة

Docker compose هو أداة تمكنك من تكوين تطبيقات متعددة الحاويات باستخدام ملف YAML واحد يسمى compose.yamlعادة . docker compose up استخدم الأمر لبدء تشغيل تطبيق الحاوية docker compose down والأمر لإيقاف الحاويات وإزالتها.

إذا قمت بتثبيت Docker Desktop CLI، فإنه يتضمن Docker compose ومتطلباته الأساسية. إذا لم يكن لديك Docker Desktop، فشاهد نظرة عامة على Installing Docker Compose.

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

العملية	طلب استعلام	نوع المستند	الحاويات الداعمة
•ترجمة النص • ترجمة المستندات	`from` المحدد.	مستندات Office	بلا
•ترجمة النص • ترجمة المستندات	`from` غير محدد. يتطلب الكشف التلقائي عن اللغة لتحديد اللغة المصدر.	مستندات Office	✔️ تحليلات النص: حاوية اللغة
•ترجمة النص • ترجمة المستندات	`from` المحدد.	مستندات PDF الممسوحة ضوئيا	✔️ حاوية Vision:read
•ترجمة النص • ترجمة المستندات	`from` غير محدد يتطلب الكشف التلقائي عن اللغة لتحديد لغة المصدر.	مستندات PDF الممسوحة ضوئيا	✔️ تحليلات النص: حاوية اللغة ✔️ حاوية Vision:read

صور الحاوية وعلاماتها

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

الحاوية	موقع الصورة	ملاحظات
المترجم: ترجمة النص	`mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest`	يمكنك عرض القائمة الكاملة لعلامات إصدار ترجمة نصية لخدمات Azure الذكاء الاصطناعي على MCR.
المترجم: ترجمة المستندات	Todo	Todo
تحليلات النص: اللغة	`mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest`	يمكنك عرض القائمة الكاملة لخدمات Azure الذكاء الاصطناعي علامات إصدار لغة تحليلات النص على MCR.
الرؤية: قراءة	`mcr.microsoft.com/azure-cognitive-services/vision/read:latest`	يمكنك عرض القائمة الكاملة لخدمات Azure الذكاء الاصطناعي علامات إصدار Computer Vision Read `OCR` على MCR.

أنشئ التطبيق الخاص بك

باستخدام المحرر المفضل لديك أو IDE، قم بإنشاء دليل جديد لتطبيقك باسم container-environment أو اسم من اختيارك.
إنشاء ملف YAML جديد باسم compose.yaml. يمكن استخدام كل من ملحقات .yml أو .yaml للملف compose .
انسخ والصق نموذج التعليمات البرمجية YAML التالي في ملفك compose.yaml . استبدل {TRANSLATOR_KEY} و {TRANSLATOR_ENDPOINT_URI} بقيم المفتاح ونقطة النهاية من مدخل Microsoft Azure المترجم المثيل. تأكد من استخدام document translation endpoint.
اسم المستوى الأعلى (azure-ai-translator، ، azure-ai-language، azure-ai-read) هو المعلمة التي تحددها.

container_name هي معلمة اختيارية تعين اسما للحاوية عند تشغيلها، بدلا من السماح docker compose بإنشاء اسم.

services:
  azure-ai-translator:
    container_name: azure-ai-translator
    image: mcr.microsoft.com/product/azure-cognitive-services/translator/text-translation:latest
    environment:
        - EULA=accept
        - billing={TRANSLATOR_ENDPOINT_URI}
        - apiKey={TRANSLATOR_KEY}
        - AzureAiLanguageHost=http://azure-ai-language:5000
        - AzureAiReadHost=http://azure-ai-read:5000
    ports:
          - "5000:5000"
    azure-ai-language:
      container_name: azure-ai-language
      image:  mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest
      environment:
          - EULA=accept
          - billing={TRANSLATOR_ENDPOINT_URI}
          - apiKey={TRANSLATOR_KEY}
    azure-ai-read:
      container_name: azure-ai-read
      image:  mcr.microsoft.com/azure-cognitive-services/vision/read:latest
      environment:
          - EULA=accept
          - billing={TRANSLATOR_ENDPOINT_URI}
          - apiKey={TRANSLATOR_KEY}

افتح terminal انتقل إلى container-environment المجلد، وابدأ تشغيل الحاويات باستخدام الأمر التالي docker-compose :
```
docker compose up
```
لإيقاف الحاويات، استخدم الأمر التالي:
```
docker compose down
```
تلميح

docker compose الاوامر:
- docker compose pause إيقاف تشغيل الحاويات مؤقتا.
- docker compose unpause {your-container-name} إلغاء إيقاف الحاويات المتوقفة مؤقتا.
- docker compose restart إعادة تشغيل كافة الحاوية المتوقفة وتشغيلها مع جميع تغييراتها السابقة سليمة. إذا قمت بإجراء تغييرات على التكوين الخاص بك compose.yaml ، فلن يتم تحديث هذه التغييرات باستخدام docker compose restart الأمر . يجب عليك استخدام docker compose up الأمر لعكس التحديثات والتغييرات في compose.yaml الملف.
- docker compose ps -a يسرد جميع الحاويات، بما في ذلك تلك التي تم إيقافها.
- docker compose execيمكنك من تنفيذ الأوامر لفصل متغيرات البيئة أو تعيينها في حاوية قيد التشغيل.
لمزيد من المعلومات، راجعمرجع docker CLI.

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

معرفة المزيد حول ترجمة النص

مشاركة عبر