Azure Container Apps의 서버리스 코드 인터프리터 세션
Azure Container Apps 동적 세션은 코드 인터프리터에 대한 빠르고 확장성 있는 액세스를 제공합니다. 각 코드 해석기 세션은 Hyper-V 경계로 완전히 격리되며 신뢰할 수 없는 코드를 실행하도록 설계되었습니다.
코드 해석기 세션에 사용
코드 해석기 세션은 다음과 같이 잠재적으로 악의적이거나 호스트 시스템이나 다른 사용자에게 해를 끼칠 수 있는 코드를 실행해야 하는 시나리오에 이상적입니다.
- LLM(대규모 언어 모델)에 의해 생성된 코드입니다.
- 웹 또는 SaaS 애플리케이션에서 최종 사용자가 제출한 코드입니다.
LangChain, LlamaIndex 또는 Semantic Kernel과 같은 널리 사용되는 LLM 프레임워크의 경우 도구 및 플러그 인을 사용하여 AI 앱을 코드 해석기 세션과 통합할 수 있습니다.
애플리케이션은 REST API를 사용하여 코드 해석기 세션과 통합할 수도 있습니다. API를 사용하면 세션에서 코드를 실행하고 결과를 검색할 수 있습니다. 세션에 파일을 업로드하고 다운로드할 수도 있습니다. 실행 가능한 코드 파일 또는 코드에서 처리할 수 있는 데이터 파일을 업로드하고 다운로드할 수 있습니다.
기본 제공 코드 인터프리터 세션은 인프라나 컨테이너를 관리할 필요 없이 가장 일반적인 코드 실행 시나리오를 지원합니다. 코드 실행 환경을 완전히 제어해야 하거나 격리된 샌드박스가 필요한 다른 시나리오가 있는 경우 사용자 지정 코드 인터프리터 세션을 사용할 수 있습니다.
코드 해석기 세션 풀
코드 해석기 세션을 사용하려면 코드 해석기 세션에 대한 구성을 정의하는 세션 풀이라는 Azure 리소스가 필요합니다. 세션 풀에서는 최대 동시 세션 수, 세션이 종료되기 전까지 유휴 상태로 있을 수 있는 시간 등의 설정을 지정할 수 있습니다.
Azure Portal, Azure CLI 또는 Azure Resource Manager 템플릿을 사용하여 세션 풀을 만들 수 있습니다. 세션 풀을 만든 후 풀의 관리 API 엔드포인트를 사용하여 세션 내에서 코드를 관리하고 실행할 수 있습니다.
Azure CLI를 사용하여 세션 풀 만들기
Azure CLI를 사용하여 코드 해석기 세션 풀을 만들려면 다음 명령을 사용하여 최신 버전의 Azure CLI와 Azure Container Apps 확장이 있는지 확인합니다.
# Upgrade the Azure CLI
az upgrade
# Install or upgrade the Azure Container Apps extension
az extension add --name containerapp --upgrade --allow-preview true -y
풀을 만들려면 az containerapps sessionpool create 명령을 사용합니다. 다음 예에서는 my-session-pool이라는 Python 코드 해석기 세션 풀을 만듭니다. 명령을 실행하기 전에 <RESOURCE_GROUP>을 리소스 그룹 이름으로 바꿔야 합니다.
az containerapp sessionpool create \
--name my-session-pool \
--resource-group <RESOURCE_GROUP> \
--location westus2 \
--container-type PythonLTS \
--max-sessions 100 \
--cooldown-period 300 \
--network-status EgressDisabled
세션 풀을 만들 때 다음 설정을 정의할 수 있습니다.
| 설정 | 설명 |
|---|---|
--container-type |
사용할 코드 해석기의 형식입니다.
PythonLTS 값만 지원됩니다. |
--max-sessions |
동시에 허용되는 할당 세션의 최대 수입니다. 최댓값은 600입니다. |
--cooldown-period |
종료되기 전에 허용되는 유휴 시간(초)입니다. 유휴 기간은 세션의 API가 호출될 때마다 다시 설정됩니다. 허용되는 범위는 300에서 3600 사이입니다. |
--network-status |
세션에서 아웃바운드 네트워크 트래픽이 허용되는지 여부를 지정합니다. 유효한 값은 EgressDisabled(기본값)와 EgressEnabled입니다. |
Important
송신을 사용하도록 설정하면 세션에서 실행되는 코드가 인터넷에 액세스할 수 있습니다. 코드가 서비스 거부 공격과 같은 악의적인 작업을 수행하는 데 사용될 수 있으므로 코드를 신뢰할 수 없는 경우 주의해야 합니다.
Azure CLI를 사용하여 풀 관리 API 엔드포인트 가져오기
LLM 프레임워크 통합을 통해 코드 해석기 세션을 사용하거나 관리 API 엔드포인트를 직접 호출하려면 풀의 관리 API 엔드포인트가 필요합니다. 엔드포인트는 https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME> 형식입니다.
세션 풀에 대한 관리 API 엔드포인트를 검색하려면 az containerapps sessionpool show 명령을 사용합니다. 명령을 실행하기 전에 <RESOURCE_GROUP>을 리소스 그룹 이름으로 바꿔야 합니다.
az containerapp sessionpool show \
--name my-session-pool \
--resource-group <RESOURCE_GROUP> \
--query 'properties.poolManagementEndpoint' -o tsv
세션에서 코드 실행
세션 풀을 만든 후 애플리케이션은 LLM 프레임워크와의 통합을 사용하거나 풀의 관리 API 엔드포인트를 직접 사용하여 풀의 세션과 상호 작용할 수 있습니다.
세션 식별자
Important
세션 식별자는 보안 프로세스를 사용하여 해당 값을 관리해야 하는 중요한 정보입니다. 이 프로세스의 일부로 애플리케이션은 각 사용자 또는 테넌트가 자신의 세션에만 액세스할 수 있도록 해야 합니다. 세션에 대한 액세스를 보호하지 못하면 사용자의 세션에 저장된 데이터에 대한 오용 또는 무단 액세스가 발생할 수 있습니다. 자세한 내용은 세션 식별자를 참조하세요.
풀의 세션과 상호 작용할 때 세션 식별자를 사용하여 각 세션을 참조하세요. 세션 식별자는 세션 풀 내에서 고유하게 정의하는 문자열입니다. 웹 애플리케이션을 빌드하는 경우 사용자 ID를 사용할 수 있습니다. 챗봇을 빌드하는 경우 대화 ID를 사용할 수 있습니다.
해당 식별자를 사용하여 실행 중인 세션이 있으면 해당 세션이 재사용됩니다. 해당 식별자를 사용하여 실행 중인 세션이 없으면 새 세션이 자동으로 만들어집니다.
세션 식별자에 대해 자세히 알아보려면 세션 개요를 참조하세요.
인증
인증은 Microsoft Entra(이전의 Azure Active Directory) 토큰을 사용하여 처리됩니다. 유효한 Microsoft Entra 토큰은 세션 풀의 Azure ContainerApps 세션 실행자 및 기여자 역할에 속하는 ID에 의해 만들어집니다.
LLM 프레임워크 통합을 사용하는 경우 프레임워크가 토큰 생성 및 관리를 자동으로 처리합니다. 세션 풀에서 필요한 역할 할당이 포함된 관리 ID로 애플리케이션이 구성되어 있는지 확인합니다.
풀의 관리 API 엔드포인트를 직접 사용하는 경우 토큰을 생성하고 이를 HTTP 요청의 Authorization 헤더에 포함해야 합니다. 이전에 언급한 역할 할당 외에도 토큰에는 값이 https://dynamicsessions.io인 대상 그룹(aud) 클레임이 포함되어야 합니다.
자세한 내용은 인증을 참조하세요.
LLM 프레임워크 통합
세션 풀 관리 API를 직접 사용하는 대신 다음 LLM 프레임워크는 코드 해석기 세션과의 통합을 제공합니다.
| 프레임워크 | Package(패키지) | 자습서 |
|---|---|---|
| LangChain | Python: langchain-azure-dynamic-sessions |
자습서 |
| LlamaIndex | Python: llama-index-tools-azure-code-interpreter |
자습서 |
| 의미 체계 커널 | Python: semantic-kernel(버전 0.9.8-b1 이상) |
자습서 |
관리 API 엔드포인트
LLM 프레임워크 통합을 사용하지 않는 경우 관리 API 엔드포인트를 사용하여 세션 풀과 직접 상호 작용할 수 있습니다.
풀의 세션을 관리하는 데 다음 엔드포인트를 사용할 수 있습니다.
| 엔드포인트 경로 | 메서드 | 설명 |
|---|---|---|
code/execute |
POST |
세션에서 코드를 실행합니다. |
files/upload |
POST |
세션에 파일을 업로드합니다. |
files/content/{filename} |
GET |
세션에서 파일을 다운로드합니다. |
files |
GET |
세션의 파일을 나열합니다. |
풀의 관리 API 엔드포인트를 엔드포인트 경로와 연결하여 각 엔드포인트에 대한 전체 URL을 빌드합니다. 쿼리 문자열에는 세션 식별자가 포함된 identifier 매개 변수와 값이 2024-02-02-preview인 api-version 매개 변수가 포함되어야 합니다.
예: https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/code/execute?api-version=2024-02-02-preview&identifier=<IDENTIFIER>
세션에서 코드 실행
세션에서 코드를 실행하려면 요청 본문에서 실행할 코드와 함께 POST 요청을 code/execute 엔드포인트로 보냅니다. 이 예에서는 Python에서 "Hello, world!"를 인쇄합니다.
요청을 보내기 전에 <> 대괄호 사이의 자리 표시자를 세션 풀 및 세션 식별자에 대한 적절한 값으로 바꿉니다.
POST https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/code/execute?api-version=2024-02-02-preview&identifier=<SESSION_ID>
Content-Type: application/json
Authorization: Bearer <token>
{
"properties": {
"codeInputType": "inline",
"executionType": "synchronous",
"code": "print('Hello, world!')"
}
}
세션을 재사용하려면 후속 요청에서 동일한 세션 식별자를 지정합니다.
세션에 파일 업로드
세션에 파일을 업로드하려면 멀티파트 양식 데이터 요청의 uploadFile 엔드포인트에 POST 요청을 보냅니다. 요청 본문에 파일 데이터를 포함합니다. 파일에는 파일 이름이 포함되어야 합니다.
업로드된 파일은 /mnt/data 디렉터리 아래 세션의 파일 시스템에 저장됩니다.
요청을 보내기 전에 <> 대괄호 사이의 자리 표시자를 요청과 관련된 값으로 바꿉니다.
POST https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files/upload?api-version=2024-02-02-preview&identifier=<SESSION_ID>
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Authorization: Bearer <token>
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="<FILE_NAME_AND_EXTENSION>"
Content-Type: application/octet-stream
(data)
------WebKitFormBoundary7MA4YWxkTrZu0gW--
참고 항목
파일 업로드 제한은 .입니다 128MB. 이 값이 초과되면 HTTP 413 반환될 수 있습니다.
세션에서 파일 다운로드
세션의 /mnt/data 디렉터리에서 파일을 다운로드하려면 file/content/{filename} 엔드포인트에 GET 요청을 보냅니다. 응답에는 파일 데이터가 포함됩니다.
요청을 보내기 전에 <> 대괄호 사이의 자리 표시자를 요청과 관련된 값으로 바꿉니다.
GET https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files/content/<FILE_NAME_AND_EXTENSION>?api-version=2024-02-02-preview&identifier=<SESSION_ID>
Authorization: Bearer <TOKEN>
세션의 파일 나열
세션의 /mnt/data 디렉터리에 있는 파일을 나열하려면 files 엔드포인트에 GET 요청을 보냅니다.
요청을 보내기 전에 <> 대괄호 사이의 자리 표시자를 요청과 관련된 값으로 바꿉니다.
GET https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files?api-version=2024-02-02-preview&identifier=<SESSION_ID>
Authorization: Bearer <TOKEN>
응답에는 세션의 파일 목록이 포함됩니다.
다음 목록은 세션 콘텐츠 요청에서 기대할 수 있는 응답 형식의 샘플을 보여 줍니다.
{
"$id": "1",
"value": [
{
"$id": "2",
"properties": {
"$id": "3",
"filename": "test1.txt",
"size": 16,
"lastModifiedTime": "2024-05-02T07:21:07.9922617Z"
}
},
{
"$id": "4",
"properties": {
"$id": "5",
"filename": "test2.txt",
"size": 17,
"lastModifiedTime": "2024-05-02T07:21:08.8802793Z"
}
}
]
}
사전 설치된 패키지
Python 코드 해석기 세션에는 NumPy, Pandas 및 scikit-learn과 같은 자주 사용되는 Python 패키지가 포함되어 있습니다.
사전 설치된 패키지 목록을 출력하려면 다음 코드를 사용하여 code/execute 엔드포인트를 호출합니다.
요청을 보내기 전에 <> 대괄호 사이의 자리 표시자를 요청과 관련된 값으로 바꿉니다.
POST https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/identifier/<SESSION_ID>/code/execute?api-version=2024-02-02-preview&identifier=<SESSION_ID>
Content-Type: application/json
Authorization: Bearer <TOKEN>
{
"properties": {
"codeInputType": "inline",
"executionType": "synchronous",
"code": "import pkg_resources\n[(d.project_name, d.version) for d in pkg_resources.working_set]"
}
}
로깅
코드 인터프리터 세션은 직접 로깅을 지원하지 않습니다. 세션과 상호 작용하는 애플리케이션은 세션 풀 관리 API 및 해당 응답에 요청을 기록할 수 있습니다.
결제
코드 인터프리터 세션은 각 세션의 기간에 따라 요금이 청구됩니다. 자세한 내용은 청구를 참조하세요.