컨테이너: 텍스트 번역

아티클
09/01/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-version	클라이언트에서 요청한 API 버전입니다. 값은 `3.0`이어야 합니다.	필수 매개 변수
보낸 사람	입력 텍스트의 언어를 지정합니다.	필수 매개 변수
끝	출력 텍스트의 언어를 지정합니다. 예를 들어 독일어로 번역하는 데 사용합니다 `to=de` . 쿼리 문자열에서 매개 변수를 반복하여 동시에 여러 언어로 번역할 수 있습니다. 예를 들어 독일어 및 이탈리아어로 번역하는 데 사용합니다 `to=de&to=it` .	필수 매개 변수

지원되는 언어 범위에 대한 translation 서비스를 쿼리할 수 있습니다.
음역에 대한 언어 지원도 참조하세요.

선택적 매개 변수

쿼리 매개 변수	설명
textType	선택적 매개 변수입니다. 번역할 텍스트가 일반 텍스트인지 HTML 텍스트인지를 정의합니다. 모든 HTML은 올바른 형식이 완전한 요소여야 합니다. 가능한 값은 `plain`(기본값) 또는 `html`입니다.
includeSentenceLength	선택적 매개 변수입니다. 입력 텍스트 및 번역된 텍스트에 대한 문장 경계를 포함할지 여부를 지정합니다. 가능한 값은 다음과 `true` 같습니다( 또는 `false` 기본값).

요청 헤더

헤더	설명	조건
인증 헤더	인증에 사용할 수 있는 옵션을 참조하세요.	필수 요청 헤더
콘텐츠-형식	페이로드의 콘텐츠 형식을 지정합니다. 허용되는 값은 .입니다 `application/json; charset=UTF-8`.	필수 요청 헤더
Content-Length	요청의 길이 본문입니다.	선택 사항
X-ClientTraceId	요청을 고유하게 식별하는 클라이언트 생성 ID입니다. 쿼리 매개 변수를 `ClientTraceId`사용하여 쿼리 문자열에 추적 ID를 포함하는 경우 이 헤더를 생략할 수 있습니다.	선택 사항

요청 본문

요청 본문은 JSON 배열입니다. 각 배열 요소는 번역할 문자열을 나타내는 문자열 Text속성이 있는 JSON 개체입니다.

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

다음과 같은 제한 사항이 적용됩니다.

배열에는 최대 100개 요소가 있을 수 있습니다.
요청에 포함된 전체 텍스트는 공백을 포함하여 50,000자를 초과할 수 없습니다.

응답 본문

성공적인 응답은 입력 배열의 각 문자열에 대해 하나의 결과가 있는 JSON 배열입니다. 결과 개체에는 다음 속성이 포함됩니다.

translations: 번역 결과의 배열입니다. 배열의 크기는 쿼리 매개 변수를 통해 지정된 대상 언어의 수와 to 일치합니다. 배열의 각 요소는 다음을 포함합니다.
to: 대상 언어의 언어 코드를 나타내는 문자열입니다.
text: 번역된 텍스트를 제공하는 문자열입니다.
sentLen: 입력 및 출력 텍스트에서 문장 경계를 반환하는 개체입니다.
srcSentLen: 입력 텍스트의 문장 길이를 나타내는 정수 배열입니다. 배열의 길이는 문장 수이며 값은 각 문장의 길이입니다.
transSentLen: 번역된 텍스트의 문장 길이를 나타내는 정수 배열입니다. 배열의 길이는 문장 수이며 값은 각 문장의 길이입니다.

문장 경계는 요청 매개 변수 includeSentenceLength가 true일 때만 포함됩니다.
- sourceText: 소스 언어의 기본 스크립트에 입력 텍스트를 제공하는 단일 text문자열 속성이 있는 개체입니다. sourceText 속성은 입력이 언어에 대한 일반적인 스크립트가 아닌 스크립트로 표현될 때만 존재합니다. 예를 들어 입력이 라틴어 스크립트로 작성된 아랍어인 경우 아랍 스크립트 sourceText.text 로 변환된 것과 동일한 아랍어 텍스트가 됩니다.

응답 헤더

헤더	설명
X-RequestId	요청을 식별하기 위해 서비스에서 생성되고 문제 해결 용도로 사용되는 값입니다.
X-MT-System	번역에 대해 요청된 각 'to'(대상) 언어에 대해 번역에 사용된 시스템 유형을 지정합니다. 값은 쉼표로 구분된 문자열 목록입니다. 각 문자열은 다음 형식을 나타냅니다. ▪ Custom - 요청에는 사용자 지정 시스템이 포함되고, 번역 중에 하나 이상의 사용자 지정 시스템이 사용되었습니다. ▪ Team - 다른 모든 요청

헤더

설명

X-RequestId

요청을 식별하기 위해 서비스에서 생성되고 문제 해결 용도로 사용되는 값입니다.

X-MT-System

번역에 대해 요청된 각 'to'(대상) 언어에 대해 번역에 사용된 시스템 유형을 지정합니다. 값은 쉼표로 구분된 문자열 목록입니다. 각 문자열은 다음 형식을 나타냅니다.

▪ Custom - 요청에는 사용자 지정 시스템이 포함되고, 번역 중에 하나 이상의 사용자 지정 시스템이 사용되었습니다.
▪ Team - 다른 모든 요청

응답 상태 코드

오류가 발생하면 요청은 JSON 오류 응답을 반환합니다. 오류 코드는 오류를 더 범주화하도록 뒤에 3자리 숫자가 오는 3자리 HTTP 상태 코드로 결합된 6자리 숫자입니다. 일반적인 오류 코드는 v3 Translator 참조 페이지에서 확인할 수 있습니다.

코드 샘플: 텍스트 번역

참고 항목

각 샘플은 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 AI Translator 엔드포인트 쿼리(텍스트)

다음은 명령으로 지정한 localhost:5000을 사용하는 cURL HTTP 요청의 예입니다 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 API를 사용하여 텍스트 번역

영어 ↔ 독일어

Swagger 페이지로 이동합니다. http://localhost:5000/swagger/index.html
POST /translate를 선택합니다.
사용해 보기를 선택합니다.
From 매개 변수를 en으로 입력합니다.
To 매개 변수를 de로 입력합니다.
api-version 매개 변수를 3.0으로 입력합니다.
texts에서 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을 지정합니다. Newtoonsoft.Json NuGet 패키지 버전 11.0.2를 추가합니다.

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>

예를 들어 영어 문장 "The word wordomatic is a dictionary entry"를 고려해보세요. 단어 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을 사용할 때와 같은 결과를 가져옵니다. 이 기능은 아쉽게 사용해야 합니다. 번역을 사용자 지정하는 적절하고 훨씬 더 나은 방법은 Custom Translator를 사용하는 것입니다. Custom Translator는 컨텍스트 및 통계적 확률을 최대한 활용합니다. 컨텍스트에서 작업 또는 구를 보여 주는 학습 데이터를 만든 경우 더 나은 결과를 얻을 수 있습니다. Custom Translator에 대해 자세히 알아보세요.

요청 제한

각 번역 요청은 번역하는 모든 대상 언어 전체에서 50,000자로 제한됩니다. 예를 들어 3,000자의 번역 요청을 전송하여 세 가지 언어로 번역하면 요청 크기가 3000x3 = 9,000자이며 요청 한도를 충족합니다. 요청 수가 아닌 문자당 요금이 청구됩니다. 더 짧은 요청을 보내는 것이 좋습니다.

다음 표에서는 Translator 번역 작업에 대한 배열 요소 및 문자 제한을 나열합니다.

연산	배열 요소의 최대 크기	배열 요소의 최대 수	최대 요청 크기(문자)
translate	10,000	100	50,000

docker compose 사용: 지원 컨테이너가 있는 Translator

Docker compose는 일반적으로 이름이 지정된 compose.yaml단일 YAML 파일을 사용하여 다중 컨테이너 애플리케이션을 구성할 수 있는 도구입니다. docker compose up 명령을 사용하여 컨테이너 애플리케이션을 시작하고 docker compose down 명령을 사용하여 컨테이너를 중지하고 제거합니다.

Docker Desktop CLI를 설치한 경우 Docker Compose와 필수 구성 요소가 포함되어 있습니다. Docker Desktop이 없으면 Docker Compose 설치 개요를 참조하세요.

다음 표에는 텍스트 및 문서 번역 작업에 필요한 지원 컨테이너가 나열되어 있습니다. 번역기 컨테이너는 Azure 계정의 Azure AI 번역기 리소스를 통해 Azure에 청구 정보를 보냅니다.

연산	쿼리 요청	Document type	지원 컨테이너
• 텍스트 번역 • 문서 번역	`from` 지정됨.	Office 문서	None
• 텍스트 번역 • 문서 번역	`from` 지정되지 않음. 소스 언어를 결정하려면 자동 언어 감지가 필요합니다.	Office 문서	✔️ Text analytics:언어 컨테이너
• 텍스트 번역 • 문서 번역	`from` 지정됨.	검사한 PDF 문서	✔️ Vision:읽기 컨테이너
• 텍스트 번역 • 문서 번역	`from`은 소스 언어를 결정하기 위해 자동 언어 감지가 필요하도록 지정되지 않았습니다.	검사한 PDF 문서	✔️ Text analytics:언어 컨테이너 ✔️ Vision:읽기 컨테이너

컨테이너 이미지 및 태그

Azure AI 서비스 컨테이너 이미지는 Microsoft 아티팩트 레지스트리 카탈로그에서 찾을 수 있습니다. 다음 표에는 텍스트 및 문서 번역을 위한 정규화된 이미지 위치가 나열되어 있습니다.

컨테이너	이미지 위치	주의
Translator: 텍스트 번역	`mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest`	MCR에서 Azure AI 서비스 텍스트 번역 버전 태그의 전체 목록을 볼 수 있습니다.
Translator: 문서 번역	TODO	TODO
Text analytics: 언어	`mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest`	MCR에서 Azure AI 서비스 Text Analytics 언어 버전 태그의 전체 목록을 볼 수 있습니다.
Vision: 읽기	`mcr.microsoft.com/azure-cognitive-services/vision/read:latest`	MCR에서 Azure AI 서비스 Computer Vision 읽기 `OCR` 버전 태그의 전체 목록을 볼 수 있습니다.

애플리케이션 만들기

기본 편집기 또는 IDE를 사용하여 container-environment라는 앱용 새 디렉터리 또는 원하는 이름을 만듭니다.
compose.yaml이라는 새 YAML 파일을 만듭니다. .yml 또는 .yaml 확장명을 모두 compose 파일에 사용할 수 있습니다.
다음 YAML 코드 샘플을 복사하여 compose.yaml 파일에 붙여넣습니다. {TRANSLATOR_KEY} 및 {TRANSLATOR_ENDPOINT_URI}를 Azure Portal Translator 인스턴스의 키 및 엔드포인트 값으로 바꿉니다. 를 사용해야 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}

터미널을 열고 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 명령으로 업데이트되지 않습니다. compose.yaml 파일의 업데이트 및 변경 내용을 반영하려면 docker compose up 명령을 사용해야 합니다.
- docker compose ps -a는 중지된 컨테이너를 포함하여 모든 컨테이너를 나열합니다.
- docker compose exec를 사용하면 실행 중인 컨테이너에서 분리하거나 환경 변수를 설정하는 명령을 실행할 수 있습니다.
자세한 내용은 docker CLI 참조를 참조하세요.

다음 단계

텍스트 번역에 대해 자세히 알아보기

다음을 통해 공유