엔드포인트 및 SDK 선택
Microsoft Foundry는 생성 AI 채팅 애플리케이션을 개발할 수 있는 유연성을 제공합니다. 개발을 시작하기 전에 사용 가능한 옵션과 사용할 옵션을 결정하는 방법을 이해하는 것이 중요합니다. 애플리케이션 개발을 위한 몇 가지 고려 사항은 다음과 같습니다.
- 엔드포인트: Microsoft Foundry 프로젝트는 클라이언트 애플리케이션에서 모델 배포와 같은 프로젝트 자산에 연결하고 사용하는 데 사용할 수 있는 두 개의 엔드포인트를 제공합니다. 각 프로젝트에는 프로젝트 엔드포인트 와 Azure OpenAI 엔드포인트가 모두 있습니다.
- 클라이언트 SDK: 선택한 엔드포인트에 따라 Microsoft Foundry SDK 또는 OpenAI SDK 를 사용하여 생성 AI 채팅 애플리케이션을 개발할 수 있습니다. 두 SDK 모두 모델에 프롬프트를 제출할 수 있는 OpenAI API 호환 클라이언트 개체를 지원하지만 각 SDK에서 사용할 수 있는 특정 기능에는 몇 가지 차이점이 있습니다.
- 인증: 사용하기로 선택한 엔드포인트 및 SDK에 따라 자산에 대한 액세스 권한을 부여하기 위해 Foundry에서 클라이언트 애플리케이션을 인증할 수 있는 여러 가지 방법이 있습니다. 일반적으로 프로덕션 애플리케이션은 특정 ID의 컨텍스트에서 애플리케이션을 실행해야 하는 Microsoft Entra ID 인증을 사용해야 합니다. 그러나 일부 시나리오에서는 키 기반 또는 토큰 기반 인증을 사용할 수도 있습니다.
- 채팅 API: OpenAI 클라이언트 API는 ChatCompletions 및 응답이라는 두 가지 채팅 API를 지원 합니다. 응답 API는 대부분의 새로운 개발 프로젝트에 권장되지만 ChatCompletions API는 여러 생성 AI 모델 및 플랫폼에서 잘 설정되고 호환됩니다.
먼저 사용 가능한 엔드포인트, 클라이언트 SDK 및 인증 방법을 고려해 보겠습니다. 나중에 응답 및 ChatCompletions API를 살펴보겠습니다.
프로젝트 엔드포인트와 함께 Foundry SDK 사용
Microsoft Foundry SDK는 REST API 및 언어별 클라이언트 라이브러리를 통해 프로젝트의 리소스에 프로그래밍 방식으로 액세스할 수 있도록 합니다. 포함:
비고
이 모듈에서는 일반적인 작업에 Python 코드 예제를 사용합니다. 기본 설정 언어의 동등한 코드에 대한 언어별 SDK 설명서를 참조할 수 있습니다. 각 SDK는 독립적으로 개발 및 유지 관리되므로 일부 기능은 구현의 다른 단계에 있을 수 있습니다.
SDK 설치
Python에서 Azure AI Projects 라이브러리를 사용하려면 PyPI의 azure-ai-projects 패키지를 지원 패키지와 함께 설치합니다.
pip install azure-ai-projects azure-identity openai
비고
Foundry SDK를 사용하여 채팅 애플리케이션을 개발하는 경우 OpenAI SDK 패키지를 가져와야 합니다. Foundry SDK의 채팅 클라이언트 기능은 OpenAI SDK에서 파생됩니다.
프로젝트 엔드포인트에 연결
각 Foundry 프로젝트에는 Foundry 포털의 프로젝트 개요 페이지에서 찾을 수 있는 고유한 엔드포인트가 있습니다.
project 엔드포인트는 다음 형식을 따릅니다.
https://{resource-name}.services.ai.azure.com/api/projects/<project-name>
이 엔드포인트를 사용하여 AIProjectClient 개체를 만듭니다.
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
project_endpoint = "https://{resource-name}.services.ai.azure.com/api/projects/<project-name>"
project_client = AIProjectClient(
credential=DefaultAzureCredential(),
endpoint=project_endpoint
)
비고
이 코드는 기본 Azure 자격 증명을 사용하여 인증합니다. 이 인증을 사용하려면 azure-identity 패키지를 설치해야 합니다(앞의 설치 명령에 표시됨).
팁 (조언)
프로젝트에 성공적으로 액세스하려면 코드는 인증된 Azure 세션에서 실행되어야 합니다. 예를 들어 코드를 실행하기 전에 Azure CLI az login 명령을 사용하여 로그인할 수 있습니다.
프로젝트 클라이언트(AIProjectClient)는 OpenAI에 해당하는 항목이 없는 Foundry 네이티브 작업에 대한 액세스를 제공합니다. project 클라이언트를 사용하여 다음을 수행합니다.
- 리소스 연결 검색
- 프로젝트 구성에 액세스
- 추적 사용 설정
- 데이터 세트 및 인덱스 관리
채팅 클라이언트 만들기
Foundry 프로젝트에서 모델과 채팅하려면 OpenAI 호환 클라이언트 개체가 필요합니다. 다음과 같이 프로젝트 클라이언트의 get_openai_client() 메서드를 사용하여 가져올 수 있습니다.
openai_client = project_client.get_openai_client(api_version="2024-10-21")
그런 다음 이 채팅 클라이언트 개체를 사용하여 모델에 프롬프트를 제출하고 응답을 반환할 수 있습니다.
Azure OpenAI 엔드포인트에서 OpenAI SDK 사용
OpenAI SDK는 OpenAI API를 호출하기 위한 공식 클라이언트 라이브러리입니다. HTTP 요청, 인증, 재시도 및 응답 구문 분석을 처리합니다. SDK는 동일한 패턴을 사용하여 OpenAI 호스팅 모델, Azure OpenAI 배포 및 Foundry 모델에서 작동합니다.
SDK 설치
Python에서 OpenAI 라이브러리를 사용하려면 지원 패키지와 함께 PyPI에서 openai 패키지를 설치합니다.
pip install openai azure-identity
비고
토큰 기반 인증을 사용하여 Microsoft Entra ID 자격 증명을 사용하여 엔드포인트에 연결하려는 경우 azure ID 패키지가 필요합니다.
Azure OpenAI 엔드포인트에 연결
각 Foundry 프로젝트에는 Foundry 포털의 프로젝트 개요 페이지에서 찾을 수 있는 Azure OpenAI 엔드포인트가 포함되어 있습니다 https://ai.azure.com.
Azure OpenAI 엔드포인트는 다음 형식을 따릅니다.
https://{resource-name}.openai.azure.com/openai/v1
엔드포인트 및 Azure 자격 증명을 사용하여 OpenAI 클라이언트를 만듭니다.
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
token_provider = get_bearer_token_provider(
DefaultAzureCredential(), "https://ai.azure.com/.default"
)
openai_client = OpenAI(
base_url = "https://{resource-name}.openai.azure.com/openai/v1/",
api_key=token_provider,
)
Microsoft Entra ID(권장) 외에도 API 키 또는 환경 변수를 사용하여 인증할 수 있습니다.
API 키 인증:
import os
from openai import OpenAI
openai_client = OpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
base_url="https://{resource-name}.openai.azure.com/openai/v1/"
)
중요합니다
주의해서 API 키를 사용합니다. Azure Key Vault에 안전하게 저장하고 코드에 직접 포함하지 않습니다.
환경 변수:
변수를 OPENAI_BASE_URL 설정하고 OPENAI_API_KEY 환경 지정하는 경우 클라이언트는 변수를 자동으로 사용합니다.
from openai import OpenAI
openai_client = OpenAI() # Uses environment variables
인증을 선택하는 방법에 관계없이 OpenAI 클라이언트는 모델 유추 작업을 처리합니다. 다음 용도로 사용합니다.
- 응답 API를 사용하여 응답 생성
- 채팅 완료 및 이미지 생성
- Foundry의 직접 모델 접근(비 Azure OpenAI 모델)
AzureOpenAI 클라이언트 개체 사용
일반적으로 OpenAI 클라이언트 개체를 사용하여 Azure OpenAI v1 엔드포인트를 통해 모델과 채팅해야 합니다. 그러나 특정 버전의 Azure OpenAI API에서 기능을 사용해야 하는 경우 AzureOpenAI 클라이언트 개체를 만드는 옵션도 있습니다. AzureOpenAI 클라이언트 개체를 만들려면 다음과 같이 API 버전 및 Azure 엔드포인트를 지정해야 합니다.
import os
from openai import AzureOpenAI
openai_client = AzureOpenAI(
azure_endpoint = "https://{resource-name}.openai.azure.com"
api_key=os.getenv("AZURE_OPENAI_KEY"),
api_version="2024-10-21",
)
Foundry SDK와 OpenAI SDK 중에서 선택
Microsoft Foundry는 AI 애플리케이션을 빌드하기 위한 두 가지 방법을 지원합니다. 각 용도는 서로 다르며 각 용도를 사용하는 시기를 이해하면 올바른 솔루션을 빌드하는 데 도움이 됩니다.
Foundry SDK를 사용하는 경우
애플리케이션에 Foundry 관련 기능이 필요한 경우 Foundry SDK를 사용합니다.
- Foundry 에이전트 서비스를 통한 AI 에이전트 구축 및 관리
- 도구 호출 및 승인 워크플로
- AI 응답 테스트 및 유효성 검사를 위한 클라우드 평가
- 애플리케이션 동작 모니터링에 대한 추적 및 관찰 가능성
- Foundry 직접 모델(모델 카탈로그를 통해 제공되는 비-Azure OpenAI 모델)
- 프로젝트 메타데이터, 연결 및 거버넌스 기능
에이전트, 평가 또는 Foundry 관련 기능을 사용하여 앱을 빌드할 때 Foundry SDK를 권장합니다.
OpenAI SDK를 사용하는 경우
OpenAI API와의 최대 호환성이 필요한 경우 OpenAI SDK를 사용합니다.
- 기존 코드 및 도구에 대한 전체 OpenAI API 호환성
- OpenAI와 Azure OpenAI 배포 간의 이식성
- 채팅 완료, 응답 및 이미지 Api
- Foundry 관련 개념에 대한 최소 종속성
OpenAI SDK는 기존 OpenAI 코드가 최소한의 변경으로 작동하도록 하는 모델 유추 워크로드에 적합합니다. 그러나 이 방법은 에이전트 또는 평가와 같은 Foundry 관련 기능을 제공하지 않습니다.
Microsoft Foundry는 AI 애플리케이션을 빌드하는 방법을 유연하게 제공합니다. 에이전트, 평가, 추적 및 연결과 AIProjectClient 같은 프로젝트 수준 기능이 필요한 경우 Foundry SDK를 사용합니다. OpenAI 호환성을 최대로 사용하는 간단한 모델 유추가 필요한 경우 OpenAI SDK를 사용합니다. 두 SDK 모두 Foundry 프로젝트 엔드포인트에서 작동하므로 애플리케이션에서 필요에 따라 결합할 수 있습니다. 프로젝트 기능용 Foundry SDK와 모델 유추를 위한 OpenAI SDK와 같은 애플리케이션에서 두 SDK를 함께 사용할 수도 있습니다.