Azure AI Model Inference REST API reference

Azure AI 모델 추론은 기초 모델에 대한 공통 기능 집합을 제공하는 API로, 개발자가 다양한 모델 집합에서 예측값을 일관되고 일관되게 소비할 수 있도록 활용할 수 있습니다. 개발자들은 Azure AI Foundry 포털에 배포된 다양한 모델과 대화할 수 있으며, 사용 중인 기본 코드를 변경하지 않고도 가능합니다.

혜택

언어 모델과 같은 기초 모델은 최근 몇 년간 놀라운 발전을 이루었습니다. 이러한 발전은 자연어 처리와 컴퓨터 비전 등 다양한 분야를 혁신했으며, 챗봇, 가상 비서, 언어 번역 서비스와 같은 응용 분야를 가능하게 했습니다.

기초 모델은 특정 영역에서 뛰어나지만, 통일된 역량 집합은 부족합니다. 어떤 모델은 특정 작업에 더 뛰어나고, 같은 과제 내에서 어떤 모델은 한 가지 방식으로 문제를 다루고 다른 어떤 방식으로는 다룰 수 있습니다. 개발자들은 적절한 모델과 적합한 업무를 통해 다음과 같은 이점을 얻을 수 있습니다:

특정 하위 작업에서 성과를 개선하세요.
더 단순한 작업에 더 효율적인 모델을 사용하세요.
특정 작업에 더 빠르게 동작할 수 있는 작은 모델을 사용하세요.
여러 모델을 구성하여 지능적인 경험을 개발하세요.

기초 모델을 통일하게 소비하는 방식을 갖추면, 개발자는 이식성을 희생하거나 기본 코드를 변경하지 않고도 이러한 모든 이점을 실현할 수 있습니다.

추론 SDK 지원

Azure AI 추론 패키지는 Azure AI 모델 추론 API를 지원하는 모든 모델을 사용할 수 있게 해주며, 이들 사이에서 쉽게 변경할 수 있습니다. Azure AI 추론 패키지는 Azure AI Foundry SDK의 일부입니다.

Language	문서	Package	예제
C#	참조	azure-ai-inference(NuGet)	C# 예제
Java	참조	azure-ai-inference(Maven)	Java 예제
JavaScript	참조	@azure/ai-inference(npm)	JavaScript 예제
Python	참조	azure-ai-inference(PyPi)	Python 예제

Capabilities

다음 섹션에서는 API가 노출하는 일부 기능을 설명합니다:

Modalities

API는 개발자가 다음 모달리티에 대한 예측을 어떻게 활용할 수 있는지를 나타냅니다:

정보 얻기: 엔드포인트 하에 배포된 모델에 대한 정보를 반환합니다.
텍스트 임베딩: 입력 텍스트를 나타내는 임베딩 벡터를 생성합니다.
채팅 완료: 주어진 채팅 대화에 대한 모델 응답을 생성합니다.
이미지 임베딩: 입력된 텍스트와 이미지를 나타내는 임베딩 벡터를 생성합니다.

Extensibility

Azure AI 모델 추론 API는 모델이 구독할 수 있는 모달리티와 매개변수 집합을 지정합니다. 하지만 일부 모델은 API가 나타내는 것보다 더 많은 기능을 가질 수 있습니다. 이 경우 API는 개발자가 페이로드에 추가 매개변수로 전달할 수 있도록 허용합니다.

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

다음 예시는 Mistral-Large가 지원하는 매개변수 safe_prompt를 전달하는 요청을 보여주는데, 이는 Azure AI 모델 추론 API에 명시되어 있지 않습니다.

요청

POST /chat/completions?api-version=2025-04-01
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=2025-04-01
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."
}

Tip

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

콘텐츠 안전성

Azure AI 모델 추론 API는 Azure AI 콘텐츠 보안를 지원합니다. Azure AI 콘텐츠 보안가 활성화된 배포를 사용할 때, 입력과 출력은 유해 콘텐츠 출력을 감지하고 방지하기 위한 분류 모델 집합을 거칩니다. 콘텐츠 필터링(미리보기) 시스템은 입력 프롬프트와 출력 완료 모두에서 잠재적으로 유해한 특정 콘텐츠 카테고리를 감지하고 조치를 취합니다.

다음 예시는 콘텐츠 안전이 발동된 채팅 완료 요청에 대한 응답을 보여줍니다.

요청

POST /chat/completions?api-version=2025-04-01
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 제품과 마찬가지로 AI 모델 추론 또는 서비스 인스턴스Azure를 Azure 구독 내에서 생성하고 구성할 수 있습니다. 필요한 만큼 자원을 만들고 여러 팀이 요구사항을 가질 경우 독립적으로 구성할 수 있습니다.

Azure AI 서비스 리소스를 생성한 후에는 API 호출을 시작하기 전에 모델을 배포해야 합니다. 기본적으로 모델이 없기 때문에 어떤 모델부터 시작할지 조절할 수 있습니다. 튜토리얼 AI 모델 추론에서 첫 모델 배포 Azure 만들기를 참고하세요.

Last updated on 2026-06-12