Foundry 리소스는 모델, 에이전트 및 도구에 대한 통합 액세스를 제공합니다. 이 문서에서는 시나리오에 사용할 SDK 및 엔드포인트를 설명합니다.
| SDK | 용도는 무엇인가 | 엔드포인트 |
|---|---|---|
| Foundry SDK | Foundry 전용 기능으로, OpenAI 호환 인터페이스를 제공합니다. 응답 API(채팅 완료 아님)를 통해 Foundry 직접 모델에 대한 액세스를 포함합니다. | https://<resource-name>.services.ai.azure.com/api/projects/<project-name> |
| OpenAI SDK | 전체 OpenAI API 화면이 있는 최신 OpenAI SDK 모델 및 기능 채팅 완료 API를 통해 사용할 수 있는 Foundry 직접 모델(응답 아님). | https://<resource-name>.openai.azure.com/openai/v1 |
| Foundry 도구 SDK들 | 미리 빌드된 솔루션(비전, 음성, 콘텐츠 안전 등). | 도구별 엔드포인트(서비스에 따라 다름) |
| 에이전트 프레임워크 | 코드에서의 다중 에이전트 조정 클라우드에 구애받지 않습니다. | Foundry SDK를 통해 프로젝트 엔드포인트를 사용합니다. |
SDK를 선택합니다.
- 에이전트, 평가 또는 Foundry 관련 기능을 사용하여 앱을 빌드할 때 Foundry SDK 사용
- 최대 OpenAI 호환성이 필요한 경우 또는 채팅 완료를 통해 Foundry 직접 모델을 사용하는 경우 OpenAI SDK 사용
- 특정 AI 서비스(비전, 음성, 언어 등)로 작업할 때 Foundry 도구 SDK 사용
- 코드에서 다중 에이전트 시스템을 빌드할 때 에이전트 프레임워크 사용(로컬 오케스트레이션)
비고
리소스 종류: Foundry 리소스는 이전에 나열된 모든 엔드포인트를 제공합니다. Azure OpenAI 리소스는 엔드포인트만 /openai/v1 제공합니다.
인증: 여기서 샘플은 Microsoft Entra ID(DefaultAzureCredential)를 사용합니다. API 키는 /openai/v1에서 작동합니다. 토큰 공급자 대신 키를 api_key 전달합니다.
필수 조건
-
활성 구독이 있는 Azure 계정. 계정이 없는 경우 평가판 구독을 포함하는 무료 Azure 계정을 만듭니다.
다음 Azure RBAC 역할 중 하나를 사용하여 Foundry 리소스를 만들고 관리합니다.
- Azure AI 사용자 (개발을 위한 최소 권한 역할)
- Azure AI Project Manager (Foundry 프로젝트 관리용)
- 기여자 또는 소유자 (구독 수준 권한의 경우)
각 역할의 권한에 대한 자세한 내용은 Microsoft Foundry에 대한 역할 기반 액세스 제어를 참조하세요.
개발 환경 준비에 설명된 대로 필요한 언어 런타임, 전역 도구 및 VS Code 확장을 설치합니다.
중요합니다
시작하기 전에 개발 환경이 준비되었는지 확인합니다.
이 문서에서는 SDK 설치, 인증 및 샘플 코드 실행과 같은 시나리오별 단계에 중점을 둡니다.
필수 구성 요소 확인
계속하기 전에 다음을 확인하십시오.
- [ ] Azure 구독이 활성 상태입니다.
az account show - [ ] 필요한 RBAC 역할이 있습니다. Azure portal → Foundry 리소스 → 액세스 제어(IAM)를 확인하십시오.
- [ ] 설치된 언어 런타임:
- Python:
python --version(≥3.8) - Node.js:
node --version(≥18) - .NET:
dotnet --version(≥6.0) - Java:
java --version(≥11)
- Python:
Foundry SDK
Foundry SDK는 가장 인기 있는 Foundry 기능에 대한 액세스를 제공하는 단일 프로젝트 엔드포인트에 연결합니다.
https://<resource-name>.services.ai.azure.com/api/projects/<project-name>
비고
조직에서 사용자 지정 하위 도메인을 사용하는 경우 엔드포인트 URL의 <resource-name>을 <your-custom-subdomain>으로 교체합니다.
이 방법은 애플리케이션 구성을 간소화합니다. 여러 엔드포인트를 관리하는 대신 하나를 구성합니다.
SDK 설치
비고
SDK 버전: 2.x 미리 보기 SDK는 새 Foundry 포털 및 API를 대상으로 합니다. 1.x GA SDK는 Foundry 클래식을 대상으로 합니다. 팔로우하는 샘플이 설치된 패키지와 일치하는지 확인합니다.
| SDK 버전 | 포털 버전 | 상태 | Python 패키지 |
|---|---|---|---|
| 2.x(미리 보기) | Foundry(신규) | Preview | azure-ai-projects>=2.0.0b1 --pre |
| 1.x(GA) | 파운드리 클래식 | 안정 | azure-ai-projects==1.0.0 |
Python용 Azure AI Projects 클라이언트 라이브러리는 단일 프로젝트 엔드포인트에 연결하여 여러 클라이언트 라이브러리를 함께 사용할 수 있는 통합 라이브러리입니다.
이러한 명령을 실행하여 Foundry 프로젝트에 대한 미리 보기 패키지를 설치합니다.
pip install --pre azure-ai-projects
pip install azure-identity openai
| SDK 버전 | 포털 버전 | 상태 | Java 패키지 |
|---|---|---|---|
| 1.0.0-beta.3 1.0.0-beta.1 |
Foundry(신규) | Preview | azure-ai-projectsazure-ai-agents |
| SDK 버전 | 포털 버전 | 상태 | JavaScript 패키지 |
|---|---|---|---|
| 2.0.0-beta.4(미리 보기) | Foundry(신규) | Preview | @azure/ai-projects 'prerelease' |
| 1.0.1 | 파운드리 클래식 | 안정 | @azure/ai-projects |
| SDK 버전 | 포털 버전 | 상태 | .NET 패키지 |
|---|---|---|---|
| 1.2.0-beta.5(미리 보기) | Foundry(신규) | Preview | Azure.AI.ProjectsAzure.AI.Projects.Openai |
| 1.x(GA) | 파운드리 클래식 | 안정 | Azure.AI.Projects |
Java용 Azure AI Projects 클라이언트 라이브러리(미리 보기)는 단일 프로젝트 엔드포인트에 연결하여 여러 클라이언트 라이브러리를 함께 사용할 수 있는 통합 라이브러리입니다.
중요합니다
이 문서에 표시된 항목(미리 보기)은 현재 퍼블릭 미리 보기에서 확인할 수 있습니다. 이 미리 보기는 서비스 수준 계약 없이 제공되며, 프로덕션 워크로드에는 권장되지 않습니다. 특정 기능이 지원되지 않거나 기능이 제한될 수 있습니다. 자세한 내용은 Microsoft Azure Preview에 대한 추가 사용 약관을 참조하세요.
Foundry 프로젝트의 설치에 이러한 패키지를 추가합니다.
package com.azure.ai.agents;
import com.azure.core.util.Configuration;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;
JavaScript용 Azure AI Projects 클라이언트 라이브러리는 단일 프로젝트 엔드포인트에 연결하여 여러 클라이언트 라이브러리를 함께 사용할 수 있는 통합 라이브러리입니다.
이 명령을 실행하여 Foundry 프로젝트에 대한 미리 보기 JavaScript 패키지를 설치합니다.
npm install @azure/ai-projects@beta @azure/identity dotenv
.NET용 Azure AI Projects 클라이언트 라이브러리는 단일 프로젝트 엔드포인트에 연결하여 여러 클라이언트 라이브러리를 함께 사용할 수 있는 통합 라이브러리입니다.
이 명령을 실행하여 Azure.AI.Projects 패키지를 .NET 프로젝트에 추가합니다.
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.AI.Projects.OpenAI --prerelease
dotnet add package Azure.Identity
Foundry SDK 사용
Foundry와 OpenAI에는 서로 다른 API 셰이프가 있으므로 SDK는 두 가지 클라이언트 형식을 노출합니다.
- 프로젝트 클라이언트 – OpenAI에 해당하는 항목이 없는 Foundry 네이티브 작업에 사용합니다. 예: 연결 나열, 프로젝트 속성 검색, 추적 사용
-
OpenAI 호환 클라이언트 – OpenAI 개념을 기반으로 하는 Foundry 기능에 사용합니다. 응답 API, 에이전트, 평가 및 미세 조정은 모두 OpenAI 스타일 요청/응답 패턴을 사용합니다. 또한 이 클라이언트는 Foundry 직접 모델(Foundry에서 호스트되는 비Azure-OpenAI 모델)에 대한 액세스 권한을 제공합니다. 프로젝트 엔드포인트는
/openai경로에서 이 트래픽을 처리합니다.
대부분의 앱은 두 클라이언트를 모두 사용합니다. 설치 및 구성에 프로젝트 클라이언트를 사용한 다음 에이전트, 평가 및 호출 모델(Foundry 직접 모델 포함)을 실행하기 위해 OpenAI 호환 클라이언트를 사용합니다.
프로젝트 클라이언트 만들기:
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
project_client = AIProjectClient(
endpoint="https://<resource-name>.services.ai.azure.com/api/projects/<project-name>",
credential=DefaultAzureCredential())
프로젝트에서 OpenAI 호환 클라이언트를 만듭니다.
with project_client.get_openai_client() as openai_client:
response = openai_client.responses.create(
model="gpt-5.2",
input="What is the size of France in square miles?",
)
print(f"Response output: {response.output_text}")
예상 출력:
Response output: France has an area of approximately 213,011 square miles (551,695 square kilometers).
프로젝트 클라이언트 만들기:
import com.azure.ai.projects.ProjectsClient;
import com.azure.ai.projects.ProjectsClientBuilder;
import com.azure.identity.DefaultAzureCredentialBuilder;
String endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
ProjectsClient projectClient = new ProjectsClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.endpoint(endpoint)
.buildClient();
```**Create and use an OpenAI-compatible client from your project:**
```java
OpenAIClient openAIClient = projectClient.getOpenAIClient();
프로젝트 클라이언트 만들기:
import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import "dotenv/config";
const projectEndpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
const deploymentName = "gpt-5.2";
const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());
프로젝트에서 OpenAI 호환 클라이언트를 만듭니다.
const openAIClient = await project.getOpenAIClient();
const response = await openAIClient.responses.create({
model: deploymentName,
input: "What is the size of France in square miles?",
});
console.log(`Response output: ${response.output_text}`);
프로젝트 클라이언트 만들기:
using Azure.AI.Projects.OpenAI;
using Azure.Identity;
using OpenAI.Responses;
string endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
AIProjectClient projectClient = new(
endpoint: new Uri(endpoint),
tokenProvider: new DefaultAzureCredential());
프로젝트에서 OpenAI 호환 클라이언트를 만듭니다.
#pragma warning disable OPENAI001
OpenAIResponseClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForModel("gpt-5.2");
OpenAIResponse response = responseClient.CreateResponse("What is the speed of light?");
Console.WriteLine(response.GetOutputText());
#pragma warning restore OPENAI001
Foundry SDK로 수행할 수 있는 작업
- Azure OpenAI를 포함한 Foundry 모델 액세스
- Foundry 에이전트 서비스 사용
- 클라우드 평가 실행
- 앱 추적 사용
- 모델 미세 조정
- Foundry 도구, 로컬 오케스트레이션 등에 대한 엔드포인트 및 키 가져오기
문제 해결
인증 오류
표시되는 DefaultAzureCredential failed to retrieve a token경우:
Azure CLI가 인증되었는지 확인합니다.
az account show az login # if not logged inRBAC 역할 할당 확인:
- Foundry 프로젝트에서 Azure AI 사용자 역할이 최소한 있는지 확인하십시오.
- Azure 역할 할당 참조
프로덕션에서 관리 ID의 경우:
- 관리 ID에 적절한 역할이 할당되었는지 확인
- 관리 ID 구성 참조
엔드포인트 구성 오류
"Connection refused 또는 404 Not Found가 표시되면 다음을 수행하세요."
- 리소스 및 프로젝트 이름이 실제 배포와 일치하는지 확인
-
엔드포인트 URL의 형식을 확인하세요:
https://<resource-name>.services.ai.azure.com/api/projects/<project-name> -
사용자 지정 하위 도메인의 경우: 사용자 지정 하위 도메인으로 바꾸기
<resource-name>
SDK 버전 불일치
코드 샘플이 AttributeError 또는 ModuleNotFoundError로 실패하는 경우:
-
SDK 버전 확인:
pip show azure-ai-projects # Python npm list @azure/ai-projects # JavaScript dotnet list package # .NET - 모니커 맞춤 확인: 2.x SDK에는 Foundry 포털이 필요하고, 1.x SDK에는 Foundry 클래식이 필요합니다.
- 올바른 버전 플래그를 사용하여 다시 설치: 위의 각 언어 섹션에서 설치 명령을 참조하세요.
OpenAI SDK
전체 OpenAI API 화면과 최대 클라이언트 호환성을 원하는 경우 OpenAI SDK를 사용합니다. 이 엔드포인트는 응답 API를 통해 Azure OpenAI 모델 및 Foundry 직접 모델에 대한 액세스를 제공합니다. 에이전트 및 평가와 같은 Foundry 관련 기능에 대한 액세스는 제공하지 않습니다.
다음 코드 조각은 Azure OpenAI /openai/v1 엔드포인트를 직접 사용하는 방법을 보여줍니다.
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
token_provider = get_bearer_token_provider(
DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
)
client = OpenAI(
base_url = "https://<resource-name>.openai.azure.com/openai/v1/",
api_key=token_provider,
)
response = client.responses.create(
model="model_deployment_name",
input= "What is the size of France in square miles?"
)
print(response.model_dump_json(indent=2))
예상 출력:
{
"id": "resp_abc123",
"object": "response",
"created": 1234567890,
"model": "gpt-5.2",
"output_text": "France has an area of approximately 213,011 square miles (551,695 square kilometers)."
}
자세한 내용은 Azure OpenAI 지원 프로그래밍 언어를 참조하세요.
중요합니다
이 문서에 표시된 항목(미리 보기)은 현재 퍼블릭 미리 보기에서 확인할 수 있습니다. 이 미리 보기는 서비스 수준 계약 없이 제공되며, 프로덕션 워크로드에는 권장되지 않습니다. 특정 기능이 지원되지 않거나 기능이 제한될 수 있습니다. 자세한 내용은 Microsoft Azure Preview에 대한 추가 사용 약관을 참조하세요.
다음 코드 조각은 Azure OpenAI /openai/v1 엔드포인트를 직접 사용하는 방법을 보여줍니다.
import com.azure.identity.AuthenticationUtil;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.credential.BearerTokenCredential;
import java.util.function.Supplier;
DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
String endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
String deploymentName = "gpt-5.2";
Supplier<String> bearerTokenSupplier = AuthenticationUtil.getBearerTokenSupplier(
tokenCredential, "https://cognitiveservices.azure.com/.default");
OpenAIClient openAIClient = OpenAIOkHttpClient.builder()
.baseUrl(endpoint)
.credential(BearerTokenCredential.create(bearerTokenSupplier))
.build();
ResponseCreateParams responseCreateParams = ResponseCreateParams.builder()
.input("What is the speed of light?")
.model(deploymentName)
.build();
Response response = openAIClient.responses().create(responseCreateParams);
System.out.println("Response output: " + response.getOutputText());
OpenAI SDK 사용에 대한 자세한 내용은 Azure OpenAI 지원 프로그래밍 언어를 참조하세요.
const endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
const scope = "https://cognitiveservices.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(new DefaultAzureCredential(), scope);
const client = new OpenAI({ baseURL: endpoint, apiKey: azureADTokenProvider });
const response = await client.responses.create({
model: deploymentName,
input: "What is the size of France in square miles?",
});
console.log(`Response output: ${response.output_text}`);
OpenAI SDK 사용에 대한 자세한 내용은 Azure OpenAI 지원 프로그래밍 언어를 참조하세요.
- OpenAI 패키지 설치: 이 명령을 실행하여 .NET 프로젝트에 OpenAI 클라이언트 라이브러리를 추가합니다.
dotnet add package OpenAI ```When it succeeds, the .NET CLI confirms that it installed the `OpenAI` package. This snippet configures `DefaultAzureCredential`, builds `OpenAIClientOptions`, and creates a `ResponseClient` for the Azure OpenAI v1 endpoint. ```csharp using Azure.Identity; using Azure.Core; using OpenAI; using System; using System.ClientModel.Primitives; #pragma warning disable OPENAI001 const string directModelEndpoint = "https://<resource-name>.openai.azure.com/openai/v1/"; const string deploymentName = "gpt-5.2"; BearerTokenPolicy tokenPolicy = new( new DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"); OpenAIResponseClient client = new( model: deploymentName, authenticationPolicy: tokenPolicy, // To use Entra // credential: new ApiKeyCredential("<YOUR-AZURE-OPENAI-API-KEY>") // To use APIKEY options: new OpenAIClientOptions() { Endpoint = new($"{directModelEndpoint}"), }); ResponseCreationOptions options = new ResponseCreationOptions { Temperature = (float)0.7, }; OpenAIResponse modelDirectResponse = client.CreateResponse( [ ResponseItem.CreateUserMessageItem("What is the size of France in square miles?"), ], options); Console.WriteLine($"[ASSISTANT]: {modelDirectResponse.GetOutputText()}"); #pragma warning restore OPENAI001 // The ResponseClient lets you interact with models and services in your project.
OpenAI SDK 사용에 대한 자세한 내용은 Azure OpenAI 지원 프로그래밍 언어를 참조하세요.
로컬 오케스트레이션에 에이전트 프레임워크 사용
Microsoft Agent Framework는 클라우드 공급자에 구애받지 않은 인터페이스를 사용하여 코드에서 다중 에이전트 시스템(예: .NET 및 Python)을 빌드하기 위한 오픈 소스 SDK입니다.
에이전트를 로컬로 정의하고 오케스트레이션하려는 경우 에이전트 프레임워크를 사용합니다. 이러한 에이전트가 Foundry 모델에 대해 실행되도록 하거나 Agent Framework가 Foundry에서 호스트되는 에이전트를 오케스트레이션하도록 하려는 경우 Foundry SDK와 페어링합니다.
자세한 내용은 Microsoft 에이전트 프레임워크 개요를 참조하세요.
펀드리 도구 SDKs
Foundry 도구(이전의 Azure AI Services)는 전용 SDK를 사용하는 미리 빌드된 지점 솔루션입니다. Foundry 도구를 사용하려면 다음 엔드포인트를 사용합니다.
어떤 엔드포인트를 사용해야 하나요?
필요에 따라 엔드포인트를 선택합니다.
Azure AI Services 엔드포인트를 사용하여 Computer Vision, 콘텐츠 안전, 문서 인텔리전스, 언어, 번역 및 토큰 파운드리 도구에 액세스합니다.
Foundry 도구 끝점: https://<your-resource-name>.cognitiveservices.azure.com/
비고
엔드포인트는 리소스 이름 또는 사용자 지정 하위 도메인을 사용합니다. 조직에서 사용자 지정 하위 도메인을 설정한 경우 모든 엔드포인트 예제로 your-resource-name 대체 your-custom-subdomain 합니다.
Speech 및 Translation Foundry 도구의 경우 다음 표의 엔드포인트를 사용합니다. 자리 표시자를 리소스 정보로 대체합니다.
음성 엔드포인트
| 주조 도구 | 엔드포인트 |
|---|---|
| 음성 텍스트 변환(표준) | https://<YOUR-RESOURCE-REGION>.stt.speech.microsoft.com |
| 음성 합성 (신경망 기반) | https://<YOUR-RESOURCE-REGION>.tts.speech.microsoft.com |
| Custom Voice | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
번역 엔드포인트
| 주조 도구 | 엔드포인트 |
|---|---|
| 텍스트 번역 | https://api.cognitive.microsofttranslator.com/ |
| 문서 번역 | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
다음 섹션에는 Foundry 도구 SDK에 대한 빠른 시작 링크 및 참조 정보가 포함되어 있습니다.
