Azure Functions에서 Python 오류 문제 해결

  • 아티클

이 문서에서는 Azure Functions에서 Python 함수의 오류 문제를 해결하는 데 도움이 되는 정보를 제공합니다. 이 문서는 v1 및 v2 프로그래밍 모델을 모두 지원합니다. 문서 맨 위에 있는 선택기에서 사용할 모델을 선택합니다.

참고 항목

Python v2 프로그래밍 모델은 4.x 함수 런타임에서만 지원됩니다. 자세한 내용은 Azure Functions 런타임 버전 개요를 참조하세요.

다음은 Python 함수의 일반적인 문제에 대한 문제 해결 섹션입니다.

특히 v2 모델의 경우 일부 알려진 문제 및 해결 방법은 다음과 같습니다.

Python Functions에 대한 일반적인 문제 해결 가이드는 다음과 같습니다.

문제 해결: ModuleNotFoundError

이 섹션은 Python 함수 앱에서 모듈 관련 오류를 해결하는 데 도움이 됩니다. 이러한 오류는 일반적으로 다음과 같은 Azure Functions 오류 메시지를 생성합니다.

예외: ModuleNotFoundError: 'module_name'이라는 모듈이 없습니다.

이 오류는 Python 함수 앱에서 Python 모듈을 로드하지 못하는 경우 발생합니다. 이 오류의 근본 원인은 다음과 같은 문제 중 하나입니다.

프로젝트 파일 보기

문제의 실제 원인을 확인하려면 함수 앱에서 실행되는 Python 프로젝트 파일을 가져와야 합니다. 로컬 컴퓨터에 프로젝트 파일이 없는 경우 다음 방법 중 하나로 가져올 수 있습니다.

  • 함수 앱에 WEBSITE_RUN_FROM_PACKAGE 앱 설정이 있고 해당 값이 URL인 경우 해당 URL을 복사하여 브라우저에 붙여넣어 파일을 다운로드합니다.
  • 함수 앱의 WEBSITE_RUN_FROM_PACKAGE가 1로 설정된 경우 https://<app-name>.scm.azurewebsites.net/api/vfs/data/SitePackages로 이동하여 최신 href URL에서 파일을 다운로드합니다.
  • 함수 앱에 위의 앱 설정 중 하나가 없는 경우 https://<app-name>.scm.azurewebsites.net/api/settings로 이동하여 SCM_RUN_FROM_PACKAGE에서 URL을 찾습니다. URL을 복사하여 브라우저에 붙여넣어 파일을 다운로드합니다.
  • 제안으로 문제가 해결되면 https://<app-name>.scm.azurewebsites.net/DebugConsole로 이동하여 /home/site/wwwroot에서 콘텐츠를 확인합니다.

이 문서의 나머지 부분은 함수 앱의 콘텐츠를 검사하고 근본 원인을 파악하고 특정 문제를 해결하여 이 오류의 잠재적 원인을 해결하는 데 도움이 됩니다.

ModuleNotFoundError 진단

이 섹션에서는 모듈 관련 오류의 잠재적 근본 원인을 자세히 설명합니다. 가능한 근본 원인을 파악한 후 관련된 완화 방법으로 이동할 수 있습니다.

패키지를 찾을 수 없습니다.

.python_packages/lib/python3.6/site-packages/<package-name> 또는 .python_packages/lib/site-packages/<package-name>로 이동합니다. 파일 경로가 없으면 이 누락 경로가 근본 원인일 수 있습니다.

배포 중에 타사 또는 오래된 도구를 사용하면 이 문제가 발생할 수 있습니다.

이 문제를 완화하려면 원격 빌드 사용 또는 네이티브 종속성 빌드를 참조하세요.

적절한 Linux 휠을 사용하는 패키지가 해결되지 않았습니다.

.python_packages/lib/python3.6/site-packages/<package-name>-<version>-dist-info 또는 .python_packages/lib/site-packages/<package-name>-<version>-dist-info로 이동합니다. 자주 사용하는 텍스트 편집기를 사용하여 휠 파일을 열고 태그: 섹션을 확인합니다. 이 문제는 태그 값에 linux가 포함되어 있지 않은 것일 수 있습니다.

Python 함수는 Azure의 Linux에서만 실행됩니다. 함수 런타임 v2.x는 Debian Stretch에서 실행되고 v3.x 런타임은 Debian Buster에서 실행됩니다. 아티팩트에는 올바른 Linux 이진 파일이 포함되어야 합니다. 핵심 도구, 타사 또는 오래된 도구에서 --build local 플래그를 사용하면 이전 이진 파일이 사용될 수 있습니다.

이 문제를 완화하려면 원격 빌드 사용 또는 네이티브 종속성 빌드를 참조하세요.

패키지가 Python 인터프리터 버전과 호환되지 않습니다.

.python_packages/lib/python3.6/site-packages/<package-name>-<version>-dist-info 또는 .python_packages/lib/site-packages/<package-name>-<version>-dist-info로 이동합니다. 텍스트 편집기에서 메타데이터 파일을 열고 분류자: 섹션을 확인합니다. 섹션에 Python :: 3, Python :: 3.6, Python :: 3.7, Python :: 3.8 또는 Python :: 3.9가 포함되지 않은 경우 패키지 버전이 너무 오래 되었거나 패키지가 이미 유지 관리되지 않는 것입니다.

Azure Portal에서 함수 앱의 Python 버전을 확인할 수 있습니다. 함수 앱의 개요 리소스 페이지로 이동하여 런타임 버전을 찾습니다. 런타임 버전은 Azure Functions 런타임 버전 개요에 설명된 대로 Python 버전을 지원합니다.

문제를 완화하려면 패키지를 최신 버전으로 업데이트 또는 패키지를 해당 항목으로 바꾸기를 참조하세요.

패키지가 다른 패키지와 충돌합니다.

패키지가 적절한 Linux 휠로 올바르게 해결되었음을 확인한 경우 다른 패키지와 충돌이 있을 수 있습니다. 특정 패키지에서는 PyPi 설명서에 호환되지 않는 모듈이 명시될 수 있습니다. 예를 들어, azure 4.0.0에서 다음 문을 찾습니다.

이 패키지는 azure-storage와 호환되지 않습니다. azure-storage를 설치했거나 azure 1.x/2.x를 설치하고 azure-storage를 제거하지 않은 경우, 먼저 azure-storage를 제거해야 합니다.

https://pypi.org/project/<package-name>/<package-version>에서 패키지 버전에 대한 설명서를 찾을 수 있습니다.

문제를 완화하려면 패키지를 최신 버전으로 업데이트 또는 패키지를 해당 항목으로 바꾸기를 참조하세요.

패키지가 Windows 및 macOS 플랫폼만 지원합니다.

텍스트 편집기를 사용하여 requirements.txt를 열고 https://pypi.org/project/<package-name>에서 패키지를 확인합니다. 일부 패키지는 Windows 및 macOS 플랫폼에서만 실행됩니다. 예를 들어 pywin32는 Windows에서만 실행됩니다.

로컬 개발에 Windows 또는 macOS를 사용하는 경우 Module Not Found 오류가 발생하지 않을 수 있습니다. 단, 런타임 시 Linux를 사용하는 Azure Functions에서 패키지를 가져오지 못합니다. 이 문제는 프로젝트를 초기화하는 동안 pip freeze를 사용하여 Windows 또는 macOS 컴퓨터에서 가상 환경을 requirements.txt로 내보내는 경우에 발생할 수 있습니다.

문제를 완화하려면 패키지를 해당 항목으로 바꾸기 또는 수작업 requirements.txt를 참조하세요.

ModuleNotFoundError 완화

모듈 관련 문제에 대한 잠재적 완화 방법은 다음과 같습니다. 이전에 언급한 진단을 사용하여 이러한 완화 방법을 확인하고 시도해 보세요.

원격 빌드 사용

원격 빌드를 사용하도록 설정했는지 확인합니다. 확인하는 방법은 배포 방법에 따라 달라집니다.

Visual Studio Code에 대한 Azure Functions 확장의 최신 버전이 설치되어 있는지 확인합니다. .vscode/settings.json 파일이 있고 "azureFunctions.scmDoBuildDuringDeployment": true 설정이 포함되어 있는지 확인합니다. 그렇지 않은 경우 파일을 만들고 azureFunctions.scmDoBuildDuringDeployment 설정을 사용하도록 설정한 다음, 프로젝트를 다시 배포합니다.

네이티브 종속성 빌드

Docker 및 Azure Functions Core Tools가 모두 최신 버전으로 설치되어 있는지 확인합니다. 로컬 함수 프로젝트 폴더로 이동하고 배포에 func azure functionapp publish <app-name> --build-native-deps를 사용합니다.

패키지를 최신 버전으로 업데이트

최신 패키지 버전의 https://pypi.org/project/<package-name>에서 분류자: 섹션을 확인합니다. 패키지는 OS Independent이거나, 운영 체제에서 POSIX 또는 POSIX :: Linux와 호환되어야 합니다. 또한 프로그래밍 언어에는 Python :: 3, Python :: 3.6, Python :: 3.7, Python :: 3.8 또는 Python :: 3.9가 포함되어야 합니다.

이러한 패키지 항목이 올바른 경우 requirements.txt의 줄 <package-name>~=<latest-version>을 변경하여 패키지를 최신 버전으로 업데이트할 수 있습니다.

수작업 requirements.txt

일부 개발자는 pip freeze > requirements.txt를 사용하여 개발 환경에 대한 Python 패키지 목록을 생성합니다. 이 편의성은 대부분의 경우에 작동하긴 하지만, Windows 또는 macOS에서 로컬로 함수를 개발하지만 Linux에서 실행되는 함수 앱에 게시하는 것처럼 플랫폼 간 배포 시나리오에서는 문제가 있을 수 있습니다. 이 시나리오에서 pip freeze는 로컬 개발 환경에 대한 예기치 않은 운영 체제별 종속성을 제공할 수 있습니다. 이러한 종속성은 Linux에서 실행될 때 Python 함수 앱을 중단시킬 수 있습니다.

모범 사례는 프로젝트 소스 코드의 각 .py 파일에서 import 문을 확인한 다음, requirements.txt 파일의 해당 모듈만 체크 인하는 것입니다. 이 방법을 사용하면 다른 운영 체제에서 패키지 문제를 제대로 처리할 수 있습니다.

패키지를 해당 항목으로 바꾸기

먼저 https://pypi.org/project/<package-name>에서 최신 버전의 패키지를 확인합니다. 이 패키지에는 일반적으로 자체 GitHub 페이지가 있습니다. GitHub의 문제 섹션으로 이동하여 문제가 해결되었는지 확인합니다. 해결된 경우 패키지를 최신 버전으로 업데이트합니다.

경우에 따라 패키지가 Python 표준 라이브러리(예: pathlib)에 통합될 수 있습니다. 통합되어 있는 경우 Azure Functions(Python 3.6, Python 3.7, Python 3.8 및 Python 3.9)에서 특정 Python 배포를 제공하기 때문에 requirements.txt 파일의 패키지를 제거해야 합니다.

그러나 문제가 해결되지 않았고 마감일이 된 경우 프로젝트에 대한 유사한 패키지를 찾기 위해 몇 가지 연구를 수행하는 것이 좋습니다. 일반적으로 Python 커뮤니티에서는 사용할 수 있는 다양한 유사한 라이브러리를 제공합니다.

종속성 격리 플래그 사용 안 함

애플리케이션 설정 PYTHON_ISOLATE_WORKER_DEPENDENCIES를 0 값으로 설정합니다.

문제 해결: 'cygrpc'를 가져올 수 없음

이 섹션은 Python 함수 앱에서 'cygrpc' 관련 오류를 해결하는 데 도움이 됩니다. 이러한 오류는 일반적으로 다음과 같은 Azure Functions 오류 메시지를 생성합니다.

'grpc._cython'에서 이름 'cygrpc'를 가져올 수 없음

해당 오류는 Python 함수 앱이 적절한 Python 인터프리터를 시작하지 못하는 경우에 발생합니다. 이 오류의 근본 원인은 다음과 같은 문제 중 하나입니다.

'cygrpc' 참조 오류 진단

cygrpc를 참조하는 오류에는 여러 가지 가능한 원인이 있으며 이에 대해서는 이 섹션에 자세히 설명되어 있습니다.

Python 인터프리터가 OS 아키텍처와 일치하지 않음

이 불일치는 64비트 운영 체제에 32비트 Python 인터프리터가 설치되어 발생할 수 있습니다.

x64 운영 체제에서 실행하는 경우 Python 버전 3.6, 3.7, 3.8 또는 3.9 인터프리터가 64비트 버전에도 있는지 확인합니다.

다음 명령을 수행하여 Python 인터프리터 비트 수를 확인할 수 있습니다.

PowerShell의 Windows에서 py -c 'import platform; print(platform.architecture()[0])'를 실행합니다.

Unix와 유사한 셸에서 python3 -c 'import platform; print(platform.architecture()[0])'를 실행합니다.

Python 인터프리터 비트 수와 운영 체제 아키텍처가 일치하지 않는 경우 Python Software Foundation에서 적절한 Python 인터프리터를 다운로드합니다.

Azure Functions Python Worker가 Python 인터프리터를 지원하지 않음

Azure Functions Python 작업자는 특정 Python 버전만 지원합니다.

Python 인터프리터가 Windows의 py --version 또는 Unix와 유사한 시스템에서 python3 --version으로 예상 버전과 일치하는지 확인합니다. 반환 결과가 지원되는 Python 버전 중 하나인지 확인합니다.

Python 인터프리터 버전이 Azure Functions 요구 사항을 충족하지 않는 경우 대신 Python Software Foundation에서 Functions가 지원하는 Python 인터프리터 버전을 다운로드합니다.

문제 해결: 코드 137로 종료된 Python

코드 137 오류는 일반적으로 Python 함수 앱의 메모리 부족 문제로 인해 발생합니다. 그 결과 다음과 같은 Azure Functions 오류 메시지가 표시됩니다.

Microsoft.Azure.WebJobs.Script.Workers.WorkerProcessExitException: Python이 코드 137로 종료됨

해당 오류는 SIGKILL 신호를 사용하여 운영 체제에서 Python 함수 앱을 강제로 종료하는 경우에 발생합니다. 해당 신호는 일반적으로 Python 프로세스의 메모리 부족 오류를 나타냅니다. Azure Functions 플랫폼에는 제한을 초과하는 모든 함수 앱을 종료하는 서비스 제한이 있습니다.

함수 앱의 메모리 병목 현상을 분석하려면 로컬 개발 환경의 Python 함수 앱 프로필을 참조하세요.

문제 해결: 코드 139로 종료된 Python

이 섹션은 Python 함수 앱에서 구분 오류를 해결하는 데 도움이 됩니다. 이러한 오류는 일반적으로 다음과 같은 Azure Functions 오류 메시지를 생성합니다.

Microsoft.Azure.WebJobs.Script.Workers.WorkerProcessExitException: Python이 코드 139로 종료됨

해당 오류는 SIGSEGV 신호를 사용하여 운영 체제에서 Python 함수 앱을 강제로 종료하는 경우에 발생합니다. 해당 신호는 메모리 구분 위반을 나타내며, 이는 제한된 메모리 영역에서 예기치 않게 읽거나 쓰는 동안 발생할 수 있습니다. 다음 섹션에서는 일반적인 근본 원인의 목록을 제공합니다.

타사 패키지로부터의 회귀

함수 앱의 requirements.txt 파일에서 고정 해제된 패키지는 Azure에 배포할 때마다 최신 버전으로 업그레이드됩니다. 패키지 업데이트로 인해 잠재적으로 앱에 영향을 미치는 회귀가 발생할 수 있습니다. 이러한 문제를 복구하려면 가져오기 문을 주석으로 처리하거나, 패키지 참조를 사용하지 않도록 설정하거나, requirements.txt에서 패키지를 이전 버전에 고정합니다.

잘못된 형식의 .pkl 파일에서 언피클링

함수 앱이 Python 피클 라이브러리를 사용하여 .pkl 파일에서 Python 개체를 로드하는 경우 파일에 잘못된 형식의 바이트 문자열 또는 유효하지 않은 주소 참조가 포함되어 있을 수 있습니다. 해당 문제를 복구하려면 pickle.load() 함수를 주석으로 처리하세요.

Pyodbc 연결 충돌

함수 앱이 많이 사용되는 ODBC 데이터베이스 드라이버인 pyodbc를 사용하는 경우 단일 함수 앱 내에서 여러 연결을 열 수 있습니다. 해당 문제를 방지하려면 싱글톤 패턴을 사용하고 함수 앱에서 하나의 pyodbc 연결만 사용하는지 확인합니다.

동기화 트리거 실패

오류 Sync triggers failed는 몇 가지 문제로 인해 발생할 수 있습니다. 한 가지 잠재적인 원인은 App Service 요금제에서 함수를 실행할 때 고객 정의 종속성과 Python 기본 제공 모듈 간의 충돌입니다. 자세한 내용은 패키지 관리를 참조하세요.

문제 해결: 파일 또는 어셈블리를 로드할 수 없음

v2 프로그래밍 모델을 사용하여 로컬로 실행할 때 이 오류가 나타날 수 있습니다. 이 오류는 예정된 릴리스에서 해결될 알려진 문제로 인해 발생합니다.

다음은 이 오류에 대한 예 메시지입니다.

DurableTask.Netherite.AzureFunctions: 파일 또는 어셈블리 'Microsoft.Azure.WebJobs.Extensions.DurableTask, Version=2.0.0.0, Culture=neutral, PublicKeyToken=014045d636e89289'를 로드할 수 없음
시스템은 지정된 파일을 찾을 수 없습니다.

확장 번들이 캐시되는 방식에 문제가 있어서 오류가 발생합니다. 문제를 해결하려면 --verbose와 함께 이 명령을 실행하여 자세한 내용을 확인합니다.

func host start --verbose

Loaded extension <> 다음에 Loading startup extension <>과 같은 확장 로드 로그가 표시되면 이 캐싱 문제가 발생할 가능성이 높습니다.

이 문제를 해결하려면:

  1. 다음을 실행하여 .azure-functions-core-tools 경로를 찾습니다.

    func GetExtensionBundlePath

  2. .azure-functions-core-tools 디렉터리를 삭제합니다.

    rm -r <insert path>/.azure-functions-core-tools

Core Tools를 다시 실행하면 캐시 디렉터리가 다시 만들어집니다.

문제 해결: Azure Storage 연결을 확인할 수 없음

이 오류는 로컬 출력에서 다음 메시지로 표시될 수 있습니다.

"Microsoft.Azure.WebJobs.Extensions.DurableTask: 'Storage'라는 Azure Storage 연결을 확인할 수 없습니다.
값은 Null일 수 없습니다. (매개 변수 'provider')

이 오류는 번들에서 로컬로 확장을 로드하는 방식의 결과입니다. 이 오류를 해결하려면 다음 동작 중 하나를 수행합니다.

  • Azurite와 같은 스토리지 에뮬레이터를 사용합니다. 이 옵션은 함수 애플리케이션에서 스토리지 계정을 사용할 계획이 없을 때 유용합니다.

  • 스토리지 계정을 만들고 localsettings.json 파일의 AzureWebJobsStorage 환경 변수에 연결 문자열을 추가합니다. 스토리지 계정 트리거를 사용하거나 애플리케이션과 바인딩하는 경우 또는 기존 스토리지 계정이 있는 경우 이 옵션을 사용합니다. 시작하려면 스토리지 계정 만들기를 참조하세요.

배포 후 Functions을 찾을 수 없음

성공적인 배포 이후 호스트에서 Python 함수를 찾을 수 없게 만드는 몇 가지 일반적인 빌드 문제가 있습니다.

  • 빌드 단계에서 패키지가 올바르게 복원되도록 하려면 에이전트 풀이 Ubuntu에서 실행되고 있어야 합니다. 배포 템플릿에 빌드 및 배포를 위한 Ubuntu 환경이 필요한지 확인합니다.

  • 함수 앱이 원본 리포지토리의 루트에 없는 경우 pip install 단계가 .python-packages 폴더를 만들 올바른 위치를 참조하는지 확인합니다. 다음 명령 예와 같이 이 위치는 대/소문자를 구분합니다.

    pip install --target="./FunctionApp1/.python_packages/lib/site-packages" -r ./FunctionApp1/requirements.txt

  • 템플릿은 /home/site/wwwroot에 로드할 수 있는 배포 패키지를 생성해야 합니다. Azure Pipelines에서는 ArchiveFiles 작업을 통해 이 작업이 수행됩니다.

Azure Portal의 개발 문제

Azure Portal을 사용할 때 다음과 같은 알려진 문제와 해결 방법을 고려합니다.

  • 포털에서 함수 코드를 작성하는 데에는 일반적인 제한 사항이 있습니다. 자세한 내용은 Azure Portal의 개발 제한을 참조하세요.
  • 포털의 함수 앱에서 함수를 삭제하려면 파일 자체에서 함수 코드를 제거합니다. Python v2 프로그래밍 모델을 사용하는 경우 삭제 단추가 함수를 제거하는 데 작동하지 않습니다.
  • 포털에서 함수를 만들 때 개발을 위해 다른 도구를 사용하라는 권고를 받을 수도 있습니다. 구문 오류가 검색된 경우를 포함하여 포털에서 코드를 편집할 수 없는 몇 가지 시나리오가 있습니다. 이러한 시나리오에서는 Visual Studio Code 또는 Azure Functions Core Tools를 사용하여 Functions 코드를 개발하고 게시합니다.

다음 단계

문제를 해결할 수 없는 경우 Azure Functions 팀에 문의하세요.

해결되지 않은 문제 보고