Azure AI Foundry 모델의 엔드포인트

2025-09-28

Azure AI Foundry Models를 사용하면 단일 엔드포인트와 자격 증명 집합을 통해 주요 모델 공급자의 가장 강력한 모델에 액세스할 수 있습니다. 이 기능을 사용하면 코드를 변경하지 않고도 모델 간에 전환하고 애플리케이션에서 모델을 사용할 수 있습니다.

이 문서에서는 Azure AI Foundry 서비스(이전 명칭: Azure AI 서비스)가 모델을 구성하는 방법과 유추 엔드포인트를 사용하여 해당 모델에 액세스하는 방법을 설명합니다.

배포

Azure AI Foundry는 배포를 사용하여 모델을 사용 가능하게 만듭니다. 배포는 모델에 이름을 지정하고 특정 구성을 설정합니다. 요청에서 배포 이름을 사용하여 모델에 액세스할 수 있습니다.

배포에는 다음이 포함됩니다.

모델 이름
모델 버전
프로비전 또는 용량 형식¹
콘텐츠 필터링 구성¹
속도 제한 구성¹

¹ 이러한 구성은 선택한 모델에 따라 변경될 수 있습니다.

Azure AI Foundry 리소스에는 여러 모델 배포가 있을 수 있습니다. 모델 배포 시 수행된 유추에 대해서만 비용을 지불합니다. 배포는 Azure 리소스이므로 Azure 정책이 적용됩니다.

배포 만들기에 대한 자세한 내용은 모델 배포 추가 및 구성을 참조하세요.

엔드포인트

Azure AI Foundry 서비스는 수행하려는 작업 형식에 따라 여러 엔드포인트를 제공합니다.

Azure AI 유추 엔드포인트
Azure OpenAI 유추 엔드포인트

Azure AI 유추 엔드포인트

일반적으로 https://<resource-name>.services.ai.azure.com/models 형식인 Azure AI 유추 엔드포인트를 사용하면 동일한 인증 및 스키마를 사용하는 단일 엔드포인트를 사용하여 리소스에 배포된 모델에 대한 유추를 생성할 수 있습니다. 모든 Foundry Models가 이 기능을 지원합니다. 이 엔드포인트는 다음 형식을 지원하는 Azure AI 모델 유추 API를 따릅니다.

텍스트 포함
이미지 포함
채팅 완료

Routing

유추 엔드포인트는 요청의 name 매개 변수를 배포 이름과 일치시켜 특정 배포에 대한 요청을 라우팅합니다. 이 설정은 배포가 특정 구성에서 모델의 별칭으로 작동한다는 것을 의미합니다. 이러한 유연성 덕분에 필요에 따라 다른 구성으로 서비스에 모델을 여러 번 배포할 수 있습니다.

예를 들어, Mistral-large라는 이름의 배포를 만들면 다음과 같이 해당 배포를 호출할 수 있습니다.

pip와 같은 패키지 관리 시스템을 사용하여 azure-ai-inference 패키지를 설치합니다.

pip install azure-ai-inference

그런 다음 패키지를 사용하여 모델을 활용할 수 있습니다. 다음 예는 채팅 완성을 활용하는 클라이언트를 생성하는 방법을 보여 줍니다.

import os
from azure.ai.inference import ChatCompletionsClient
from azure.core.credentials import AzureKeyCredential

client = ChatCompletionsClient(
    endpoint="https://<resource>.services.ai.azure.com/models",
    credential=AzureKeyCredential(os.environ["AZURE_INFERENCE_CREDENTIAL"]),
)

시작하려면 샘플을 살펴보고 API 참조 설명서를 참조하세요.

npm을 사용하여 @azure-rest/ai-inference 패키지를 설치합니다.

npm install @azure-rest/ai-inference

그런 다음 패키지를 사용하여 모델을 활용할 수 있습니다. 다음 예는 채팅 완성을 활용하는 클라이언트를 생성하는 방법을 보여 줍니다.

import ModelClient from "@azure-rest/ai-inference";
import { isUnexpected } from "@azure-rest/ai-inference";
import { AzureKeyCredential } from "@azure/core-auth";

const client = new ModelClient(
    "https://<resource>.services.ai.azure.com/models", 
    new AzureKeyCredential(process.env.AZURE_INFERENCE_CREDENTIAL)
);

시작하려면 샘플을 살펴보고 API 참조 설명서를 참조하세요.

다음 명령을 사용하여 Azure AI 유추 라이브러리를 설치합니다.

dotnet add package Azure.AI.Inference --prerelease

다음 네임스페이스를 가져옵니다.

using Azure;
using Azure.Identity;
using Azure.AI.Inference;

그런 다음 패키지를 사용하여 모델을 활용할 수 있습니다. 다음 예는 채팅 완성을 활용하는 클라이언트를 생성하는 방법을 보여 줍니다.

ChatCompletionsClient client = new ChatCompletionsClient(
    new Uri("https://<resource>.services.ai.azure.com/models"),
    new AzureKeyCredential(Environment.GetEnvironmentVariable("AZURE_INFERENCE_CREDENTIAL"))
);

시작하려면 샘플을 살펴보고 API 참조 설명서를 참조하세요.

프로젝트에 패키지를 추가합니다.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-inference</artifactId>
    <version>1.0.0-beta.1</version>
</dependency>

그런 다음 패키지를 사용하여 모델을 활용할 수 있습니다. 다음 예는 채팅 완성을 활용하는 클라이언트를 생성하는 방법을 보여 줍니다.

ChatCompletionsClient client = new ChatCompletionsClientBuilder()
    .credential(new AzureKeyCredential("{key}"))
    .endpoint("https://<resource>.services.ai.azure.com/models")
    .buildClient();

시작하려면 샘플을 살펴보고 API 참조 설명서를 참조하세요.

참조 섹션을 사용하여 API 디자인 및 사용할 수 있는 매개 변수를 살펴봅니다. 예를 들어 채팅 완료에 대한 참조 섹션에서는 경로를 /chat/completions 사용하여 채팅 형식의 지침에 따라 예측을 생성하는 방법을 자세히 설명합니다. 경로 /models 는 URL의 루트에 포함됩니다.

요청

POST https://<resource>.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
api-key: <api-key>
Content-Type: application/json

채팅 모델의 경우 다음과 같이 요청을 만들 수 있습니다.

from azure.ai.inference.models import SystemMessage, UserMessage

response = client.complete(
    messages=[
        SystemMessage(content="You are a helpful assistant."),
        UserMessage(content="Explain Riemann's conjecture in 1 paragraph"),
    ],
    model="mistral-large"
)

print(response.choices[0].message.content)

var messages = [
    { role: "system", content: "You are a helpful assistant" },
    { role: "user", content: "Explain Riemann's conjecture in 1 paragraph" },
];

var response = await client.path("/chat/completions").post({
    body: {
        messages: messages,
        model: "mistral-large"
    }
});

console.log(response.body.choices[0].message.content)

requestOptions = new ChatCompletionsOptions()
{
    Messages = {
        new ChatRequestSystemMessage("You are a helpful assistant."),
        new ChatRequestUserMessage("Explain Riemann's conjecture in 1 paragraph")
    },
    Model = "mistral-large"
};

response = client.Complete(requestOptions);
Console.WriteLine($"Response: {response.Value.Content}");

List<ChatRequestMessage> chatMessages = new ArrayList<>();
chatMessages.add(new ChatRequestSystemMessage("You are a helpful assistant"));
chatMessages.add(new ChatRequestUserMessage("Explain Riemann's conjecture in 1 paragraph"));

ChatCompletions chatCompletions = client.complete(new ChatCompletionsOptions(chatMessages));

for (ChatChoice choice : chatCompletions.getChoices()) {
    ChatResponseMessage message = choice.getMessage();
    System.out.println("Response:" + message.getContent());
}

요청

POST https://<resource>.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
api-key: <api-key>
Content-Type: application/json

{
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant"
        },
        {
            "role": "user",
            "content": "Explain Riemann's conjecture in 1 paragraph"
        }
    ],
    "model": "mistral-large"
}

모델 배포와 일치하지 않는 모델 이름을 지정하면 모델이 존재하지 않는다는 오류가 발생합니다. 모델 배포를 만들어 사용자에게 제공되는 모델을 제어할 수 있습니다. 자세한 내용은 모델 배포 추가 및 구성을 참조하세요.

Azure OpenAI 유추 엔드포인트

Azure OpenAI API는 OpenAI 모델의 전체 기능을 노출하고 도우미, 스레드, 파일 및 일괄 처리 유추와 같은 더 많은 기능을 지원합니다. 이 경로를 통해 OpenAI가 아닌 모델에 액세스할 수도 있습니다.

Azure OpenAI 엔드포인트는 일반적으로 https://<resource-name>.openai.azure.com 형식이며 배포 수준에서 작동하며 각 배포에는 고유한 연결 URL이 있습니다. 하지만 동일한 인증 메커니즘을 사용하여 배포를 사용할 수 있습니다. 자세한 내용은 Azure OpenAI API 참조 페이지를 참조하세요.

각 배포에는 Azure OpenAI 기준 URL과 경로 /deployments/<model-deployment-name>을 연결하여 형성된 URL이 있습니다.

pip와 같은 패키지 관리 시스템을 사용하여 openai 패키지를 설치합니다.

pip install openai --upgrade

그런 다음 패키지를 사용하여 모델을 활용할 수 있습니다. 다음 예는 채팅 완성을 활용하는 클라이언트를 생성하는 방법을 보여 줍니다.

import os
from openai import AzureOpenAI
    
client = AzureOpenAI(
    azure_endpoint = "https://<resource>.services.ai.azure.com"
    api_key=os.getenv("AZURE_INFERENCE_CREDENTIAL"),  
    api_version="2024-10-21",
)

npm을 사용하여 openai 패키지를 설치합니다.

npm install openai

그런 다음 패키지를 사용하여 모델을 활용할 수 있습니다. 다음 예는 채팅 완성을 활용하는 클라이언트를 생성하는 방법을 보여 줍니다.

import { AzureKeyCredential } from "@azure/openai";

const endpoint = "https://<resource>.services.ai.azure.com";
const apiKey = new AzureKeyCredential(process.env.AZURE_INFERENCE_CREDENTIAL);
const apiVersion = "2024-10-21"

const client = new AzureOpenAI({ 
    endpoint, 
    apiKey, 
    apiVersion, 
    "deepseek-v3-0324"
});

여기서 deepseek-v3-0324는 Azure AI Foundry 리소스의 모델 배포 이름입니다.

다음 명령으로 OpenAI 라이브러리를 설치합니다.

dotnet add package Azure.AI.OpenAI --prerelease

패키지를 사용하여 모델을 사용할 수 있습니다. 다음 예는 채팅 완성을 활용하는 클라이언트를 생성하는 방법을 보여 줍니다.

AzureOpenAIClient client = new(
    new Uri("https://<resource>.services.ai.azure.com"),
    new ApiKeyCredential(Environment.GetEnvironmentVariable("AZURE_INFERENCE_CREDENTIAL"))
);

프로젝트에 패키지를 추가합니다.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-openai</artifactId>
    <version>1.0.0-beta.16</version>
</dependency>

그런 다음 패키지를 사용하여 모델을 활용할 수 있습니다. 다음 예는 채팅 완성을 활용하는 클라이언트를 생성하는 방법을 보여 줍니다.

OpenAIClient client = new OpenAIClientBuilder()
    .credential(new AzureKeyCredential("{key}"))
    .endpoint("https://<resource>.services.ai.azure.com")
    .buildClient();

참조 섹션을 사용하여 API 디자인 및 사용할 수 있는 매개 변수를 살펴봅니다. 예를 들어 채팅 완성에 대한 참조 섹션에서는 /chat/completions 경로를 사용하여 채팅 형식 지침에 따라 예측을 생성하는 방법을 자세히 설명합니다.

요청

POST https://<resource>.services.ai.azure.com/openai/deployments/deepseek-v3-0324/chat/completions?api-version=2024-10-21
api-key: <api-key>
Content-Type: application/json

여기서 deepseek-v3-0324는 Azure AI Foundry 리소스의 모델 배포 이름입니다.

response = client.chat.completions.create(
    model="deepseek-v3-0324", # Replace with your model dpeloyment name.
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain Riemann's conjecture in 1 paragraph"}
    ]
)

print(response.model_dump_json(indent=2)

var messages = [
    { role: "system", content: "You are a helpful assistant" },
    { role: "user", content: "Explain Riemann's conjecture in 1 paragraph" },
];

const response = await client.chat.completions.create({ messages, model: "deepseek-v3-0324" });

console.log(response.choices[0].message.content)

ChatCompletion response = chatClient.CompleteChat(
    [
        new SystemChatMessage("You are a helpful assistant."),
        new UserChatMessage("Explain Riemann's conjecture in 1 paragraph"),
    ]);

Console.WriteLine($"{response.Role}: {response.Content[0].Text}");

List<ChatRequestMessage> chatMessages = new ArrayList<>();
chatMessages.add(new ChatRequestSystemMessage("You are a helpful assistant"));
chatMessages.add(new ChatRequestUserMessage("Explain Riemann's conjecture in 1 paragraph"));

ChatCompletions chatCompletions = client.getChatCompletions("deepseek-v3-0324",
    new ChatCompletionsOptions(chatMessages));

System.out.printf("Model ID=%s is created at %s.%n", chatCompletions.getId(), chatCompletions.getCreatedAt());
for (ChatChoice choice : chatCompletions.getChoices()) {
    ChatResponseMessage message = choice.getMessage();
    System.out.printf("Index: %d, Chat Role: %s.%n", choice.getIndex(), message.getRole());
    System.out.println("Message:");
    System.out.println(message.getContent());
}

여기서 deepseek-v3-0324는 Azure AI Foundry 리소스의 모델 배포 이름입니다.

요청

POST https://<resource>.services.ai.azure.com/openai/deployments/deepseek-v3-0324/chat/completions?api-version=2024-10-21
api-key: <api-key>
Content-Type: application/json

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

여기서 deepseek-v3-0324는 Azure AI Foundry 리소스의 모델 배포 이름입니다.

Azure OpenAI 엔드포인트를 사용하는 방법에 대한 자세한 내용은 Azure AI Foundry Models 설명서의 Azure OpenAI를 참조하세요.

키 없는 인증

Azure AI 서비스의 Azure AI Foundry Models에 배포된 모델은 Microsoft Entra ID를 사용하여 키 없는 권한 부여를 지원합니다. 키 없는 권한 부여는 보안을 강화하고, 사용자 환경을 간소화하며, 운영상의 복잡성을 줄이고, 최신 개발에 대한 강력한 준수 지원을 제공합니다. 이를 통해 키 없는 권한 부여는 안전하고 확장성 있는 ID 관리 솔루션을 도입하는 조직에 강력한 선택이 됩니다.

키 없는 인증을 사용하려면 리소스를 구성하고 사용자에게 유추 수행 권한을 부여합니다. 리소스를 구성하고 액세스 권한을 부여한 후 다음과 같이 인증합니다.

pip와 azure-ai-inference 같은 패키지 관리자를 사용하여 패키지를 설치합니다.

pip install azure-ai-inference

그런 다음 패키지를 사용하여 모델을 사용합니다. 다음 예제에서는 Microsoft Entra ID를 사용하여 채팅 완료를 사용하는 클라이언트를 만드는 방법을 보여 줍니다.

import os
from azure.ai.inference import ChatCompletionsClient
from azure.identity import DefaultAzureCredential

client = ChatCompletionsClient(
    endpoint="https://<resource>.services.ai.azure.com/models",
    credential=DefaultAzureCredential(),
    credential_scopes=["https://cognitiveservices.azure.com/.default"],
)

npm을 사용하여 @azure-rest/ai-inference 패키지를 설치합니다.

npm install @azure-rest/ai-inference

import ModelClient from "@azure-rest/ai-inference";
import { isUnexpected } from "@azure-rest/ai-inference";
import { DefaultAzureCredential } from "@azure/identity";

const clientOptions = { credentials: { "https://cognitiveservices.azure.com" } };

const client = new ModelClient(
    "https://<resource>.services.ai.azure.com/models", 
    new DefaultAzureCredential(),
    clientOptions,
);

다음 명령을 사용하여 Azure AI 유추 라이브러리를 설치합니다.

dotnet add package Azure.AI.Inference --prerelease

Azure.Identity 패키지를 설치합니다.

dotnet add package Azure.Identity

다음 네임스페이스를 가져옵니다.

using Azure;
using Azure.Identity;
using Azure.AI.Inference;

TokenCredential credential = new DefaultAzureCredential();
AzureAIInferenceClientOptions clientOptions = new AzureAIInferenceClientOptions();
BearerTokenAuthenticationPolicy tokenPolicy = new BearerTokenAuthenticationPolicy(credential, new string[] { "https://cognitiveservices.azure.com/.default" });
clientOptions.AddPolicy(tokenPolicy, HttpPipelinePosition.PerRetry);

ChatCompletionsClient client = new ChatCompletionsClient(
    new Uri("https://<resource>.services.ai.azure.com/models"),
    credential,
    clientOptions.
);

프로젝트에 패키지를 추가합니다.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-inference</artifactId>
    <version>1.0.0-beta.4</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.15.3</version>
</dependency>

그런 다음 패키지를 사용하여 모델을 사용합니다. 다음 예는 채팅 완성을 활용하는 클라이언트를 생성하는 방법을 보여 줍니다.

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ChatCompletionsClient client = new ChatCompletionsClientBuilder()
    .credential(defaultCredential)
    .endpoint("https://<resource>.services.ai.azure.com/models")
    .buildClient();

샘플을 탐색하고 API 참조 설명서를 읽어 시작합니다.

참조 섹션을 사용하여 API 디자인을 탐색하고 사용할 수 있는 매개 변수를 확인합니다. 헤더 Authorization에 인증 토큰을 나타냅니다. 예를 들어 채팅 완료에 대한 참조 섹션에서는 경로를 /chat/completions 사용하여 채팅 형식의 지침에 따라 예측을 생성하는 방법을 자세히 설명합니다. 경로 /models 는 URL의 루트에 포함됩니다.

요청

POST https://<resource>.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
Authorization: Bearer <bearer-token>
Content-Type: application/json

토큰은 범위 https://cognitiveservices.azure.com/.default와 함께 발급되어야 합니다.

테스트를 위해 사용자 계정에 유효한 토큰을 가져오는 가장 쉬운 방법은 Azure CLI를 사용하는 것입니다. 콘솔에서 다음 Azure CLI 명령을 실행합니다.

az account get-access-token --resource https://cognitiveservices.azure.com --query "accessToken" --output tsv

제한점

Foundry Models 엔드포인트와 함께 Azure OpenAI Batch를 사용할 수 없습니다. Azure OpenAI 설명서의 Batch API 지원에 설명된 대로 전용 배포 URL을 사용해야 합니다.
실시간 API는 유추 엔드포인트에서 지원되지 않습니다. 전용 배포 URL을 사용합니다.

피드백

이 페이지가 도움이 되었나요?

다음을 통해 공유

Azure AI Foundry 모델의 엔드포인트

배포

엔드포인트

Azure AI 유추 엔드포인트

Routing

Azure OpenAI 유추 엔드포인트

키 없는 인증

제한점

관련 콘텐츠

피드백

추가 리소스