자습서: Azure Container Apps와 함께 LlamaIndex의 코드 인터프리터 세션 사용

LlamaIndex는 컨텍스트 LLM(증강 언어 모델) 애플리케이션을 빌드하기 위한 강력한 프레임워크입니다. LlamaIndex를 사용하여 AI 에이전트를 빌드하면 LLM이 사용자 입력을 해석하고 응답을 생성합니다. AI 에이전트는 응답을 생성하기 위해 수학적, 상징적 추론을 수행해야 할 때 종종 어려움을 겪습니다. Azure Container Apps 동적 세션을 LlamaIndex와 통합하면 특수 작업을 수행하는 데 사용할 수 있는 코드 인터프리터를 에이전트에 제공할 수 있습니다.

이 자습서에서는 웹 API에서 LlamaIndex AI 에이전트를 실행하는 방법을 알아봅니다. API는 사용자 입력을 받아들이고 AI 에이전트가 생성한 응답을 반환합니다. 에이전트는 동적 세션에서 코드 인터프리터를 사용하여 계산을 수행합니다.

필수 조건

• 활성 구독이 있는 Azure 계정.
  • GitHub 계정이 없는 경우 무료로 만들 수 있습니다.
• Azure CLI를 설치합니다.
• Git
• Python 3.10 이상

Azure 리소스 만들기

이 빠른 시작의 샘플 앱은 Azure OpenAI의 LLM을 사용합니다. 또한 Azure Container Apps 세션을 사용하여 LLM에서 생성된 코드를 실행합니다.

1. Azure CLI를 최신 버전으로 업데이트합니다.

    az upgrade
   

2. Azure Container Apps 확장이 이미 설치되어 있는 경우 제거하고 세션에 대한 명령이 포함된 Azure Container Apps 확장의 미리 보기 버전을 설치합니다.

   az extension remove --name containerapp
   az extension add \
       --name containerapp \
       --allow-preview true -y
   

3. Azure에 로그인:

   az login
   

4. 이 빠른 시작에서 사용되는 변수를 설정합니다.

   RESOURCE_GROUP_NAME=aca-sessions-tutorial
   AZURE_OPENAI_LOCATION=swedencentral
   AZURE_OPENAI_NAME=<UNIQUE_OPEN_AI_NAME>
   SESSION_POOL_LOCATION=eastasia
   SESSION_POOL_NAME=code-interpreter-pool
   

   Azure OpenAI 계정을 만들려면 <UNIQUE_OPEN_AI_NAME>을 고유한 이름으로 바꿉니다.

5. 리소스 그룹 만들기:

   az group create --name $RESOURCE_GROUP_NAME --location $SESSION_POOL_LOCATION
   

6. Azure OpenAI 계정을 만듭니다.

   az cognitiveservices account create \
       --name $AZURE_OPENAI_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --location $AZURE_OPENAI_LOCATION \
       --kind OpenAI \
       --sku s0 \
       --custom-domain $AZURE_OPENAI_NAME
   

7. Azure OpenAI 계정에서 gpt-35-turbo라는 GPT 3.5 Turbo 모델 배포를 만듭니다.

   az cognitiveservices account deployment create \
       --resource-group $RESOURCE_GROUP_NAME \
       --name $AZURE_OPENAI_NAME \
       --deployment-name gpt-35-turbo \
       --model-name gpt-35-turbo \
       --model-version "1106" \
       --model-format OpenAI \
       --sku-capacity "100" \
       --sku-name "Standard"
   

8. 코드 인터프리터 세션 풀을 만듭니다.

   az containerapp sessionpool create \
       --name $SESSION_POOL_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --location $SESSION_POOL_LOCATION \
       --max-sessions 100 \
       --container-type PythonLTS \
       --cooldown-period 300
   

로컬로 샘플 앱 실행

Azure Container Apps에 앱을 배포하기 전에 로컬로 실행하여 테스트할 수 있습니다.

앱 복제

1. Azure Container Apps 세션 샘플 리포지토리를 복제합니다.

   git clone https://github.com/Azure-Samples/container-apps-dynamic-sessions-samples.git
   

2. 샘플 앱을 포함하는 디렉터리로 변경합니다.

   cd container-apps-dynamic-sessions-samples/llamaindex-python-webapi
   

앱 구성

1. Python 가상 환경을 만들고 활성화합니다.

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

   다른 버전을 사용하는 경우 명령에서 Python 버전을 변경합니다. Python 3.10 이상을 사용하는 것이 좋습니다.

   참고 항목

   Windows를 사용하는 경우 .venv/bin/activate를 .venv\Scripts\activate로 바꿉니다.

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

   python -m pip install -r requirements.txt
   

3. 앱을 실행하려면 환경 변수를 구성해야 합니다.

   1. Azure OpenAI 계정 엔드포인트를 검색합니다.

      az cognitiveservices account show \
          --name $AZURE_OPENAI_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query properties.endpoint \
          --output tsv
      

   2. Azure Container Apps 세션 풀 관리 엔드포인트를 검색합니다.

      az containerapp sessionpool show \
          --name $SESSION_POOL_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query properties.poolManagementEndpoint \
          --output tsv
      

   3. 샘플 앱 디렉터리의 루트(main.py와 동일한 위치)에 .env 파일을 만듭니다. 파일에 다음 내용을 추가합니다.

      AZURE_OPENAI_ENDPOINT=<AZURE_OPENAI_ENDPOINT>
      POOL_MANAGEMENT_ENDPOINT=<SESSION_POOL_MANAGEMENT_ENDPOINT>
      

      <AZURE_OPENAI_ENDPOINT>를 Azure OpenAI 계정 엔드포인트로 바꾸고 <SESSION_POOL_MANAGEMENT_ENDPOINT>를 세션 풀 관리 엔드포인트로 바꿉니다.

4. 앱은 DefaultAzureCredential을 사용하여 Azure 서비스에 인증합니다. 로컬 컴퓨터에서는 현재 Azure CLI 로그인 자격 증명을 사용합니다. 앱이 모델 엔드포인트에 액세스하려면 Azure OpenAI 계정에 대한 Cognitive Services OpenAI 사용자 역할과 앱의 세션 풀에 대한 Azure ContainerApps 세션 실행기 역할을 자신에게 부여해야 합니다. 세션 풀에 액세스합니다.

   1. Azure CLI 사용자 이름을 검색합니다.

      az account show --query user.name --output tsv
      

   2. 다음 명령을 실행하여 Azure OpenAI 계정 리소스 ID를 검색합니다.

      az cognitiveservices account show --name $AZURE_OPENAI_NAME --resource-group $RESOURCE_GROUP_NAME --query id --output tsv
      

   3. Azure OpenAI 계정의 Azure CLI 사용자에게 Cognitive Services OpenAI 사용자 역할을 할당합니다.

      az role assignment create --role "Cognitive Services OpenAI User" --assignee <CLI_USERNAME> --scope <AZURE_OPENAI_RESOURCE_ID>
      

      <CLI_USERNAME>을 Azure CLI 사용자 이름으로 바꾸고, <AZURE_OPENAI_RESOURCE_ID>를 Azure OpenAI 계정 리소스 ID로 바꿉니다.

   4. 세션 풀 리소스 ID를 검색하려면 다음 명령을 실행합니다.

      az containerapp sessionpool show --name $SESSION_POOL_NAME --resource-group $RESOURCE_GROUP_NAME --query id --output tsv
      

   5. 해당 ID를 사용하여 세션 풀의 Azure CLI 사용자에게 Azure ContainerApps 세션 실행기 역할을 할당합니다.

      az role assignment create \
          --role "Azure ContainerApps Session Executor" \
          --assignee <CLI_USERNAME> \
          --scope <SESSION_POOL_RESOURCE_ID>
      

      <CLI_USERNAME>을 Azure CLI 사용자 이름으로 바꾸고, <SESSION_POOL_RESOURCE_ID>를 세션 풀 리소스 ID로 바꿉니다.

앱 실행

샘플 앱을 실행하기 전에 편집기에서 main.py를 열고 코드를 검토합니다. 앱은 FastAPI를 사용하여 쿼리 문자열에서 사용자 메시지를 수락하는 웹 API를 만듭니다.

다음 코드 줄은 AzureCodeInterpreterToolSpec을 인스턴스화하고 LlamaIndex 에이전트에 제공합니다.

code_interpreter_tool = AzureCodeInterpreterToolSpec(
    pool_management_endpoint=pool_management_endpoint,
)
agent = ReActAgent.from_tools(code_interpreter_tool.to_tool_list(), llm=llm, verbose=True)

계산을 수행해야 하는 경우 에이전트는 AzureCodeInterpreterToolSpec의 코드 인터프리터를 사용하여 코드를 실행합니다. 코드는 세션 풀의 세션에서 실행됩니다. 기본적으로 도구를 인스턴스화하면 임의 세션 식별자가 생성됩니다. 에이전트가 동일한 도구를 사용하여 여러 Python 코드 조각을 실행하는 경우 동일한 세션을 사용합니다. 각 최종 사용자가 고유한 세션을 갖도록 하려면 각 사용자마다 별도의 에이전트와 도구를 사용합니다.

AzureCodeInterpreterToolSpec은 llama-index-tools-azure-code-interpreter 패키지에서 사용할 수 있습니다.

1. 샘플 앱 실행:

   fastapi dev main.py
   

2. 브라우저를 열고 http://localhost:8000/docs로 이동합니다. 샘플 앱의 Swagger UI가 표시됩니다.

3. /chat 엔드포인트를 확장하고 시도를 선택합니다.

4. message 필드에 What time is it right now?를 입력하고 실행을 선택합니다.

   에이전트는 현재 시간으로 응답합니다. 터미널에서 현재 시간을 가져오고 코드 인터프리터 세션에서 실행하기 위해 에이전트가 생성한 Python 코드를 보여 주는 로그를 볼 수 있습니다.

5. 앱을 중지하려면 터미널에 Ctrl+C를 입력합니다.

선택 사항: Azure Container Apps에 샘플 앱 배포

FastAPI 앱을 Azure Container Apps에 배포하려면 컨테이너 이미지를 만들고 이를 컨테이너 레지스트리에 푸시해야 합니다. 그런 다음 이미지를 Azure Container Apps에 배포할 수 있습니다. az containerapp up 명령은 이러한 단계를 단일 명령으로 결합합니다.

그런 다음 앱에 대한 관리 ID를 구성하고 Azure OpenAI 및 세션 풀에 액세스할 수 있는 적절한 역할을 할당해야 합니다.

1. Container Apps 환경 및 앱 이름에 대한 변수를 설정합니다.

   ENVIRONMENT_NAME=aca-sessions-tutorial-env
   CONTAINER_APP_NAME=chat-api
   

2. Azure Container Apps에 앱을 빌드하고 배포합니다.

   az containerapp up \
       --name $CONTAINER_APP_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --location $SESSION_POOL_LOCATION \
       --environment $ENVIRONMENT_NAME \
       --env-vars "AZURE_OPENAI_ENDPOINT=<OPEN_AI_ENDPOINT>" "POOL_MANAGEMENT_ENDPOINT=<SESSION_POOL_MANAGEMENT_ENDPOINT>" \
       --source .
   

   <OPEN_AI_ENDPOINT>를 Azure OpenAI 계정 엔드포인트로 바꾸고 <SESSION_POOL_MANAGEMENT_ENDPOINT>를 세션 풀 관리 엔드포인트로 바꿉니다.

3. 앱에 대해 시스템 할당 관리 ID를 사용하도록 설정합니다.

   az containerapp identity assign \
       --name $CONTAINER_APP_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --system-assigned
   

4. 앱이 Azure OpenAI 및 세션 풀에 액세스하려면 관리 ID에 적절한 역할을 할당해야 합니다.

   1. 관리 ID의 주체 ID를 검색합니다.

      az containerapp show \
          --name $CONTAINER_APP_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query identity.principalId \
          --output tsv
      

   2. 세션 풀 리소스 ID를 검색합니다.

      az containerapp sessionpool show \
          --name $SESSION_POOL_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query id \
          --output tsv
      

   3. 세션 풀의 관리 ID에 Azure ContainerApps Session Executor 및 Contributor 역할을 할당합니다.

      다음 명령을 실행하기 전에 <PRINCIPAL_ID> 및 <SESSION_POOL_RESOURCE_ID>를 이전 단계에서 검색한 값으로 바꿉니다.

      az role assignment create \
          --role "Azure ContainerApps Session Executor" \
          --assignee <PRINCIPAL_ID> \
          --scope <SESSION_POOL_RESOURCE_ID>
      
      az role assignment create \
          --role "Contributor" \
          --assignee <PRINCIPAL_ID> \
          --scope <SESSION_POOL_RESOURCE_ID>
      

   4. Azure OpenAI 계정 리소스 ID를 검색합니다.

      az cognitiveservices account show \
          --name $AZURE_OPENAI_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query id \
          --output tsv
      

   5. Azure OpenAI 계정의 Cognitive Services OpenAI User 역할에 관리 ID를 할당합니다.

      다음 명령을 실행하기 전에 <PRINCIPAL_ID> 및 <AZURE_OPENAI_RESOURCE_ID>를 이전 단계에서 검색한 값으로 바꿉니다.

      az role assignment create \
          --role "Cognitive Services OpenAI User" \
          --assignee <PRINCIPAL_ID> \
          --scope <AZURE_OPENAI_RESOURCE_ID>
      

5. 앱의 FQDN(정규화된 도메인 이름)을 검색합니다.

   az containerapp show \
       --name $CONTAINER_APP_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --query properties.configuration.ingress.fqdn \
       --output tsv
   

6. 배포된 앱을 테스트하려면 브라우저를 열어 https://<FQDN>/docs로 이동합니다.

리소스 정리

리소스 작업이 완료되면 요금이 발생하지 않도록 삭제할 수 있습니다.

az group delete --name $RESOURCE_GROUP_NAME --yes --no-wait

다음 단계

코드 인터프리터 세션