Azure AI 모델 유추 REST API 참조

아티클
03/05/2025

Azure AI 모델 유추는 기본 모델에 대한 일반적인 기능 집합을 노출하고 개발자가 균일하고 일관된 방식으로 다양한 모델 집합의 예측을 사용하는 데 사용할 수 있는 API입니다. 개발자는 사용 중인 기본 코드를 변경하지 않고 Azure AI Foundry 포털에 배포된 다양한 모델과 통신할 수 있습니다.

혜택

언어 모델과 같은 기본 모델은 실제로 최근 몇 년 동안 놀라운 진전을 이루었습니다. 이러한 발전은 자연어 처리 및 컴퓨터 비전을 포함한 다양한 분야에 혁명을 일으켰으며 챗봇, 가상 도우미 및 언어 번역 서비스와 같은 애플리케이션을 사용하도록 설정했습니다.

기본 모델은 특정 도메인에서 탁월하지만 균일한 기능 집합이 부족합니다. 일부 모델은 특정 작업에서 더 낫고 동일한 작업에서도 일부 모델은 한 가지 방법으로 문제에 접근할 수 있고 다른 모델은 문제에 접근할 수 있습니다. 개발자는 올바른 작업 적합한 모델을 사용하여 이러한 다양성을 활용할 수 있습니다.

특정 다운스트림 작업의 성능을 향상시킵니다.
더 간단한 작업을 위해 보다 효율적인 모델을 사용합니다.
특정 작업에서 더 빠르게 실행할 수 있는 더 작은 모델을 사용합니다.
여러 모델을 구성하여 지능형 환경을 개발합니다.

기본 모델을 균일하게 사용하는 방법을 사용하면 개발자가 이식성을 희생하거나 기본 코드를 변경하지 않고도 이러한 모든 이점을 실현할 수 있습니다.

유추 SDK 지원

Azure AI 유추 패키지를 사용하면 Azure AI 모델 유추 API를 지원하는 모든 모델을 사용하고 이러한 모델 간에 쉽게 변경할 수 있습니다. Azure AI 유추 패키지는 Azure AI Foundry SDK의 일부입니다.

언어	문서조사	패키지	예제
C#	참조	nuGet(azure-ai-inference)	C# 예제
자바	참조	maven(azure-ai-inference)	java 예제
JavaScript	참조	@azure/ai-inference(npm)	javaScript 예제
파이썬	참조	azure-ai-inference(PyPi)	Python 예제

기능

다음 섹션에서는 API가 노출하는 몇 가지 기능에 대해 설명합니다.

형식

API는 개발자가 다음 형식에 대한 예측을 사용하는 방법을 나타냅니다.

정보 가져오기: 엔드포인트 아래에 배포된 모델에 대한 정보를 반환합니다.
텍스트 포함: 입력 텍스트를 나타내는 포함 벡터를 만듭니다.
채팅 완료: 지정된 채팅 대화에 대한 모델 응답을 만듭니다.
이미지 포함: 입력 텍스트와 이미지를 나타내는 포함 벡터를 만듭니다.

확장성

Azure AI 모델 유추 API는 모델이 구독할 수 있는 형식 및 매개 변수 집합을 지정합니다. 그러나 일부 모델에는 API가 나타내는 추가 기능이 있을 수 있습니다. 이러한 경우 API를 사용하면 개발자가 페이로드에 추가 매개 변수로 전달할 수 있습니다.

헤더 extra-parameters: pass-through설정하여 API는 알 수 없는 매개 변수를 기본 모델에 직접 전달하려고 시도합니다. 모델이 해당 매개 변수를 처리할 수 있으면 요청이 완료됩니다.

다음 예제에서는 Azure AI 모델 유추 API에 지정되지 않은 Mistral-Large에서 지원하는 매개 변수 safe_prompt 전달하는 요청을 보여줍니다.

요청

POST /chat/completions?api-version=2024-05-01-preview
Authorization: Bearer <bearer-token>
Content-Type: application/json
extra-parameters: pass-through

{
    "messages": [
    {
        "role": "system",
        "content": "You are a helpful assistant"
    },
    {
        "role": "user",
        "content": "Explain Riemann's conjecture in 1 paragraph"
    }
    ],
    "temperature": 0,
    "top_p": 1,
    "response_format": { "type": "text" },
    "safe_prompt": true
}

메모

extra-parameters 기본값은 페이로드에 추가 매개 변수가 표시되는 경우 오류를 반환하는 error. 또는 요청에 알 수 없는 매개 변수를 삭제하도록 extra-parameters: drop 설정할 수 있습니다. 모델이 지원하지 않지만 요청을 완료하려는 경우 추가 매개 변수를 사용하여 요청을 보내는 경우 이 기능을 사용합니다. 이 예제의 일반적인 예는 seed 매개 변수를 나타내는 것입니다.

서로 다른 기능 집합이 있는 모델

Azure AI 모델 유추 API는 일반적인 기능 집합을 나타내지만 각 모델은 구현 여부를 결정할 수 있습니다. 모델이 특정 매개 변수를 지원할 수 없는 경우 특정 오류가 반환됩니다.

다음 예제에서는 매개 변수 reponse_format 나타내고 JSON 형식으로 회신을 요청하는 채팅 완료 요청에 대한 응답을 보여 줍니다. 이 예제에서는 모델이 이러한 기능을 지원하지 않으므로 오류 422가 사용자에게 반환됩니다.

요청

POST /chat/completions?api-version=2024-05-01-preview
Authorization: Bearer <bearer-token>
Content-Type: application/json

{
    "messages": [
    {
        "role": "system",
        "content": "You are a helpful assistant"
    },
    {
        "role": "user",
        "content": "Explain Riemann's conjecture in 1 paragraph"
    }
    ],
    "temperature": 0,
    "top_p": 1,
    "response_format": { "type": "json_object" },
}

응답

{
    "status": 422,
    "code": "parameter_not_supported",
    "detail": {
        "loc": [ "body", "response_format" ],
        "input": "json_object"
    },
    "message": "One of the parameters contain invalid values."
}

팁

속성 details.loc 검사하여 잘못된 매개 변수의 위치를 파악하고 details.input 요청에서 전달된 값을 확인할 수 있습니다.

콘텐츠 안전성

Azure AI 모델 유추 API는 Azure AI Content Safety 지원합니다. Azure AI Content Safety를 사용하여 배포를 사용하는 경우 입력 및 출력은 유해한 콘텐츠의 출력을 감지하고 방지하기 위한 분류 모델의 앙상블을 통과합니다. 콘텐츠 필터링(미리 보기) 시스템은 입력 프롬프트와 출력 완성 모두에서 잠재적으로 유해한 콘텐츠의 특정 범주를 검색하고 조치를 취합니다.

다음 예제에서는 콘텐츠 안전을 트리거한 채팅 완료 요청에 대한 응답을 보여 줍니다.

요청

POST /chat/completions?api-version=2024-05-01-preview
Authorization: Bearer <bearer-token>
Content-Type: application/json

{
    "messages": [
    {
        "role": "system",
        "content": "You are a helpful assistant"
    },
    {
        "role": "user",
        "content": "Chopping tomatoes and cutting them into cubes or wedges are great ways to practice your knife skills."
    }
    ],
    "temperature": 0,
    "top_p": 1,
}

응답

{
    "status": 400,
    "code": "content_filter",
    "message": "The response was filtered",
    "param": "messages",
    "type": null
}

시작

Azure AI 모델 유추 API는 Azure AI Services 리소스에서 사용할 수 있습니다. Azure 구독에서 Azure AI 모델 유추 또는 서비스 인스턴스에 대한 리소스를 만들고 구성할있는 다른 Azure 제품과 동일한 방식으로 시작할 수 있습니다. 요구 사항이 다른 여러 팀이 있는 경우 필요에 따라 리소스를 만들고 독립적으로 구성할 수 있습니다.

Azure AI Services 리소스를 만든 후에는 API 호출을 시작하기 전에 모델을 배포해야 합니다. 기본적으로 사용할 수 있는 모델은 없으므로 시작할 모델을 제어할 수 있습니다. 자습서 Azure AI 모델 유추첫 번째 모델 배포 만들기를 참조하세요.

다음을 통해 공유

Azure AI 모델 유추 REST API 참조

혜택

유추 SDK 지원

기능

형식

확장성

서로 다른 기능 집합이 있는 모델

콘텐츠 안전성

시작

추가 리소스