자습서: 1부 - Microsoft Foundry SDK를 사용하여 RAG(사용자 지정 지식 검색) 앱을 빌드하는 프로젝트 및 개발 환경 설정

이 자습서에서는 Microsoft Foundry SDK(및 기타 라이브러리)를 사용하여 Contoso Trek이라는 소매 회사의 채팅 앱을 빌드, 구성 및 평가합니다. 사용자의 소매 회사는 야외 캠핑 장비 및 의류를 전문으로 취급합니다. 채팅 앱은 사용자의 제품과 서비스에 관한 질문에 답해야 합니다. 예를 들어, 채팅 앱은 "어떤 텐트가 가장 방수가 잘 되나요?", 또는 "추운 날씨에 사용하기 가장 좋은 침낭은 무엇인가요?"와 같은 질문에 대답할 수 있습니다.

이 자습서는 3부로 구성된 자습서 중 제1부입니다. 이 1부에서는 2부에서 코드를 작성하고 3부에서 채팅 앱을 평가할 준비가 됩니다. 이 부분에서는 다음을 수행합니다.

프로젝트 만들기
Azure AI 검색 인덱스 만들기
Azure CLI 설치 및 로그인
Python 및 패키지 설치
프로젝트에 모델 배포
환경 변수 구성

다른 자습서 또는 빠른 시작을 완료한 경우 이 자습서에 필요한 리소스 중 일부를 이미 만들었을 수 있습니다. 그렇다면 여기에서 해당 단계를 건너뛸 수 있습니다.

이 자습서는 3부로 구성된 자습서 중 제1부입니다.

필수 조건

비고

이 자습서에서는 허브 기반 프로젝트를 사용합니다. 여기에 표시된 단계와 코드는 Foundry 프로젝트에서 작동하지 않습니다. 자세한 내용은 프로젝트 유형을 참조하세요.

활성 구독이 있는 Azure 계정. 계정이 없으면 무료 계정을 만듭니다.

허브 기반 프로젝트 만들기

Microsoft Foundry에서 허브 기반 프로젝트를 만들려면 다음 단계를 수행합니다.

Microsoft Foundry에 로그인합니다. New Foundry 토글이 꺼져 있는지 확인합니다. 이러한 단계는 Foundry(클래식)를 참조합니다.
다음에 수행할 작업은 현재 위치에 따라 달라집니다.
- 기존 프로젝트가 없는 경우: 빠른 시작: Microsoft Foundry 시작의 단계에 따라 첫 번째 프로젝트를 만듭니다.
- 프로젝트에 있다면: 프로젝트 탐색 경로를 선택한 다음, 새 리소스 만들기를 선택합니다.
- 프로젝트에 참여하지 않은 경우: 오른쪽 상단에서 새로 만들기를 선택하여 새 Foundry 프로젝트를 만듭니다.
AI 허브 리소스를 선택한 다음, 다음을 선택합니다.
프로젝트의 이름을 입력합니다.
허브가 있는 경우 가장 최근에 사용한 허브가 선택된 상태로 표시됩니다.
- 두 개 이상의 허브에 액세스할 수 있는 경우 드롭다운에서 다른 허브를 선택할 수 있습니다.
- 새 허브를 만들려면 새 허브 만들기를 선택하고 이름을 입력합니다.
허브가 없는 경우 기본 허브가 만들어집니다.
선택하고생성합니다.

모델 배포

RAG 기반 채팅 앱을 빌드하려면 Azure OpenAI 채팅 모델(gpt-4o-mini)과 Azure OpenAI 포함 모델(text-embedding-ada-002)의 두 가지 모델이 필요합니다. 각 모델에 대해 이 단계 집합을 사용하여 Foundry 프로젝트에 이러한 모델을 배포합니다.

다음 단계에서는 Foundry 포털 모델 카탈로그에서 실시간 엔드포인트에 모델을 배포합니다.

팁 (조언)

Microsoft Foundry 포털에서 왼쪽 창을 사용자 지정할 수 있으므로 이러한 단계에 표시된 것과 다른 항목이 표시될 수 있습니다. 원하는 항목이 표시되지 않으면 왼쪽 창 아래쪽에 있는 ... 더 보기를 선택하십시오.

왼쪽 창에서 모델 카탈로그를 선택합니다.
모델 목록에서 gpt-4o-mini 모델을 선택합니다. 검색 창을 사용하여 찾을 수 있습니다.
모델 세부 정보 페이지에서 이 모델 사용을 선택합니다.
기본 배포 이름을 그대로 둡니다. 배포를 선택합니다. 또는 해당 지역에서 모델을 사용할 수 없는 경우 다른 지역이 선택되어 프로젝트에 연결됩니다. 이 경우 연결을 선택하고 배포합니다.

gpt-4o-mini를 배포한 후 단계를 반복하여 text-embedding-ada-002 모델을 배포합니다.

Azure AI 검색 서비스 만들기

이 애플리케이션의 목표는 사용자 지정 데이터에 모델 응답을 근거로 하는 것입니다. 검색 인덱스는 사용자의 질문을 기반으로 관련 문서를 검색하는 데 사용됩니다.

검색 인덱스를 만들려면 Azure AI 검색 서비스 및 연결이 필요합니다.

비고

Azure AI Search 서비스 및 후속 검색 인덱스를 만드는 데에는 관련 비용이 발생합니다. 만들기 페이지에서 Azure AI 검색 서비스의 가격 책정 및 가격 책정 계층에 대한 세부 정보를 확인하여 리소스를 만들기 전에 비용을 확인할 수 있습니다. 이 자습서에서는 기본 이상의 가격 책정 계층을 사용하는 것이 좋습니다.

Azure AI 검색 서비스가 이미 있는 경우 다음 섹션으로 건너뛸 수 있습니다.

그렇지 않으면 Azure Portal을 사용하여 Azure AI 검색 서비스를 만들 수 있습니다.

팁 (조언)

이 단계는 이 자습서 시리즈에서 Azure Portal을 사용하는 유일한 시간입니다. 나머지 작업은 Foundry 포털 또는 로컬 개발 환경에서 수행됩니다.

Azure Portal에서 Azure AI 검색 서비스를 만듭니다.
리소스 그룹 및 인스턴스 세부 정보를 선택합니다. 이 페이지에서 가격 책정 및 가격 책정 계층에 대한 세부 정보를 확인할 수 있습니다.
마법사를 계속 진행하고 검토 + 할당을 선택하여 리소스를 만듭니다.
예상 비용을 포함하여 Azure AI 검색 서비스의 세부 정보를 확인합니다.
만들기를 선택하여 Azure AI 검색 서비스를 만듭니다.

프로젝트에 Azure AI 검색 연결

프로젝트에 Azure AI Search 연결이 이미 있는 경우 Azure CLI 설치로 건너뛰고 로그인할 수 있습니다.

Foundry 포털에서 Azure AI Search 연결된 리소스를 확인합니다.

Foundry에서 프로젝트로 이동하여 왼쪽 창에서 관리 센터를 선택합니다.
연결된 리소스 섹션에서 Azure AI Search 유형의 연결이 있는지 확인합니다.
Azure AI Search 연결이 있는 경우 다음 섹션으로 건너뛸 수 있습니다.
그렇지 않으면 새 연결을 선택한 다음 Azure AI 검색을 선택합니다.
옵션에서 Azure AI 검색 서비스를 찾아 연결 추가를 선택합니다.
인증에 API 키를 사용합니다.

중요합니다

API 키 옵션은 프로덕션에 권장되지 않습니다. 권장되는 Microsoft Entra ID 인증 옵션을 선택하고 사용하려면 Azure AI Search 서비스에 대한 액세스 제어도 구성해야 합니다. 사용자 계정에 검색 인덱스 데이터 기여자 및 Search Service 기여자 역할을 할당합니다. 자세한 내용은 Foundry 포털에서 역할 및 역할 기반 액세스 제어 를 사용하여 Azure AI Search에 연결을 참조하세요.
연결 추가를 선택합니다.

새 Python 환경 만들기

선택한 IDE에서 프로젝트에 대한 새 폴더를 만듭니다. 해당 폴더에서 터미널 창을 엽니다.

먼저 새 Python 환경을 만들어야 합니다. 전역 Python 설치에 패키지를 설치하지 마세요. Python 패키지를 설치할 때 항상 가상 환경 또는 conda 환경을 사용해야 합니다. 그렇지 않으면 Python의 전역 설치가 중단될 수 있습니다.

필요한 경우 Python을 설치합니다.

Python 3.10 이상을 사용하는 것이 좋지만 Python 3.9 이상이 필요합니다. 적합한 버전의 Python이 설치되어 있지 않은 경우 운영 체제에 Python을 설치하는 가장 쉬운 방법은 VS Code Python 자습서 의 지침을 따르세요.

가상 환경 만들기

Python 3.10 이상이 이미 설치된 경우 다음 명령을 사용하여 가상 환경을 만듭니다.

py -3 -m venv .venv
.venv\scripts\activate

python3 -m venv .venv
source .venv/bin/activate

python3 -m venv .venv
source .venv/bin/activate

Python 환경을 활성화한다는 것은 명령줄에서 python 또는 pip을(를) 실행할 때, 애플리케이션의 .venv 폴더에 포함된 Python 인터프리터를 사용한다는 것을 의미합니다.

비고

deactivate 명령을 사용하여 Python 가상 환경을 종료하고 나중에 필요할 때 다시 활성화할 수 있습니다.

패키지 설치

필요한 패키지를 설치합니다.

먼저 프로젝트 폴더에 requirements.txt 파일을 만듭니다. 파일에 다음 패키지를 추가합니다.

azure-ai-projects==1.0.0b10
azure-ai-inference[prompts]
azure-identity
azure-search-documents
pandas
python-dotenv
opentelemetry-api

필요한 패키지를 설치합니다.
```
pip install -r requirements.txt
```

도우미 스크립트 만들기

작업에 사용할 폴더를 만듭니다. 이 폴더에 config.py 파일을 만듭니다. 이 도우미 스크립트는 자습서 시리즈의 다음 두 부분에서 사용됩니다. 다음 코드를 추가합니다.

# ruff: noqa: ANN201, ANN001

import os
import sys
import pathlib
import logging
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.inference.tracing import AIInferenceInstrumentor

# load environment variables from the .env file
from dotenv import load_dotenv

load_dotenv()

# Set "./assets" as the path where assets are stored, resolving the absolute path:
ASSET_PATH = pathlib.Path(__file__).parent.resolve() / "assets"

# Configure an root app logger that prints info level logs to stdout
logger = logging.getLogger("app")
logger.setLevel(logging.INFO)
logger.addHandler(logging.StreamHandler(stream=sys.stdout))


# Returns a module-specific logger, inheriting from the root app logger
def get_logger(module_name):
    return logging.getLogger(f"app.{module_name}")


# Enable instrumentation and logging of telemetry to the project
def enable_telemetry(log_to_project: bool = False):
    AIInferenceInstrumentor().instrument()

    # enable logging message contents
    os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "true"

    if log_to_project:
        from azure.monitor.opentelemetry import configure_azure_monitor

        project = AIProjectClient.from_connection_string(
            conn_str=os.environ["AIPROJECT_CONNECTION_STRING"], credential=DefaultAzureCredential()
        )
        tracing_link = f"https://ai.azure.com/tracing?wsid=/subscriptions/{project.scope['subscription_id']}/resourceGroups/{project.scope['resource_group_name']}/providers/Microsoft.MachineLearningServices/workspaces/{project.scope['project_name']}"
        application_insights_connection_string = project.telemetry.get_connection_string()
        if not application_insights_connection_string:
            logger.warning(
                "No application insights configured, telemetry will not be logged to project. Add application insights at:"
            )
            logger.warning(tracing_link)

            return

        configure_azure_monitor(connection_string=application_insights_connection_string)
        logger.info("Enabled telemetry logging to project, view traces at:")
        logger.info(tracing_link)

비고

이 스크립트는 아직 azure.monitor.opentelemetry설치하지 않은 패키지도 사용합니다. 자습서 시리즈의 다음 부분에서 이 패키지를 설치합니다.

환경 변수 구성

코드에서 Microsoft Foundry Models에서 Azure OpenAI를 호출하려면 프로젝트 연결 문자열이 필요합니다. 이 빠른 시작에서는 애플리케이션에서 읽을 수 있는 .env 환경 변수가 포함된 파일인 파일에 이 값을 저장합니다.

.env 파일을 만들고 다음 코드를 붙여넣습니다.

AIPROJECT_CONNECTION_STRING=<your-connection-string>
AISEARCH_INDEX_NAME="example-index"
EMBEDDINGS_MODEL="text-embedding-ada-002"
INTENT_MAPPING_MODEL="gpt-4o-mini"
CHAT_MODEL="gpt-4o-mini"
EVALUATION_MODEL="gpt-4o-mini"

Foundry 플레이그라운드 퀵스타트에서 생성한 Foundry 프로젝트에서 연결 문자열을 찾습니다. 프로젝트를 연 다음 개요 페이지에서 연결 문자열 찾습니다. 연결 문자열 복사하여 파일에 붙여넣습니다.env.
아직 검색 인덱스가 없으면 AISEARCH_INDEX_NAME에 "example-index" 값을 유지합니다. 이 자습서의 2부에서는 이 이름을 사용하여 인덱스 만들기를 수행합니다. 이전에 대신 사용할 검색 인덱을 만든 경우 해당 검색 인덱스의 이름과 일치하도록 값을 업데이트합니다.
모델을 배포할 때 모델의 이름을 변경한 경우 파일의 값을 .env 사용한 이름과 일치하도록 업데이트합니다.

팁 (조언)

VS Code에서 작업하는 경우 파일의 변경 내용을 .env 저장한 후 터미널 창을 닫고 다시 엽니다.

경고

당신의 .env가 .gitignore 파일에 있는지 확인하여 실수로 그 파일을 git 리포지토리에 커밋하지 않도록 하세요.

Azure CLI를 설치하고 로컬 개발 환경에서 로그인하면 사용자 자격 증명을 사용하여 Microsoft Foundry Models에서의 Azure OpenAI를 호출할 수 있습니다.

대부분의 경우 다음 명령을 사용하여 터미널에서 Azure CLI를 설치할 수 있습니다.

winget install -e --id Microsoft.AzureCLI

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

brew update && brew install azure-cli

특정 운영 체제나 설정에서 이러한 명령이 작동하지 않는 경우 Azure CLI 설치 방법 지침을 따를 수 있습니다.

Azure CLI를 설치한 후 az login 명령을 사용하여 로그인하고 브라우저를 사용하여 로그인합니다.

az login

또는 디바이스 코드를 사용하여 브라우저를 통해 수동으로 로그인할 수 있습니다.

az login --use-device-code

이제 로그인했으므로 여기에서 Python 스크립트를 실행하려면 이 터미널 창을 열어 둡니다.

리소스 정리

불필요한 Azure 비용이 발생하지 않도록 하려면 이 자습서에서 만든 리소스가 더 이상 필요하지 않은 경우 삭제해야 합니다. 리소스를 관리하려면 Azure Portal을 사용하면 됩니다.

하지만 이 자습서 시리즈의 다음 부분에서 채팅 앱을 빌드하려면 아직 삭제하지 마세요.

다음 단계

이 자습서에서는 Azure AI SDK를 사용하여 사용자 지정 채팅 앱을 빌드하는 데 필요한 모든 것을 설정합니다. 이 자습서 시리즈의 다음 부분에서는 사용자 지정 앱을 빌드합니다.

2부: Azure AI SDK를 사용하여 사용자 지정 채팅 앱 빌드

피드백

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

Last updated on 2025-11-18

다음을 통해 공유

자습서: 1부 - Microsoft Foundry SDK를 사용하여 RAG(사용자 지정 지식 검색) 앱을 빌드하는 프로젝트 및 개발 환경 설정

필수 조건

허브 기반 프로젝트 만들기

모델 배포

Azure AI 검색 서비스 만들기

프로젝트에 Azure AI 검색 연결

새 Python 환경 만들기

필요한 경우 Python을 설치합니다.

가상 환경 만들기

패키지 설치

도우미 스크립트 만들기

환경 변수 구성

Azure CLI 설치 및 로그인

리소스 정리

다음 단계

피드백

추가 리소스