RomanNum3ral
/
AI-For-Beginners
mirror of https://github.com/microsoft/AI-For-Beginners.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
AI-For-Beginners/translations/ko/troubleshoot.md

8.5 KiB
Raw Blame History

AI-For-Beginners 문제 해결 가이드

이 가이드는 AI-For-Beginners 저장소를 사용하거나 기여하는 동안 발생할 수 있는 일반적인 문제를 해결하는 데 도움을 줍니다. 각 문제는 배경, 증상, 설명, 단계별 해결 방법을 포함합니다.

목차

일반적인 문제

1. 저장소가 제대로 클론되지 않음

배경: 클론은 저장소를 로컬 머신으로 복사하는 과정입니다.

증상:

  • 오류: fatal: repository not found
  • 오류: Permission denied (publickey)

가능한 원인:

  • 잘못된 저장소 URL
  • 권한 부족
  • SSH 키가 설정되지 않음

해결 방법:

  1. 저장소 URL 확인하기
    HTTPS URL을 사용하세요: 
    git clone https://github.com/microsoft/AI-For-Beginners.git
  2. SSH가 실패하면 HTTPS로 전환하기
    Permission denied (publickey) 오류가 발생하면 SSH 대신 위의 HTTPS 링크를 사용하세요.
  3. SSH 키 설정하기 (선택 사항)
    SSH를 사용하려면 GitHub의 SSH 가이드를 따르세요.

설치 문제

2. Python 환경 문제

배경: 이 저장소는 Python과 다양한 라이브러리에 의존합니다.

증상:

  • 오류: ModuleNotFoundError: No module named '<package>'
  • 스크립트나 노트북 실행 시 Import 오류

가능한 원인:

  • 종속성이 설치되지 않음
  • 잘못된 Python 버전

해결 방법:

  1. 가상 환경 설정하기 
    python -m venv venv
source venv/bin/activate   # On Windows: venv\Scripts\activate
  2. 종속성 설치하기 
    pip install -r requirements.txt
  3. Python 버전 확인하기
    Python 3.7 이상을 사용하세요. 
    python --version

3. Jupyter가 설치되지 않음

배경: 노트북은 핵심 학습 자료입니다.

증상:

  • 오류: jupyter: command not found
  • 노트북 실행 실패

가능한 원인:

  • Jupyter가 설치되지 않음

해결 방법:

  1. Jupyter Notebook 설치하기 
    pip install notebook
    또는 Anaconda를 사용하는 경우: 
    conda install notebook
  2. Jupyter Notebook 시작하기 
    jupyter notebook

4. 종속성 버전 충돌

배경: 패키지 버전이 맞지 않으면 프로젝트가 중단될 수 있습니다.

증상:

  • 호환되지 않는 버전에 대한 오류 또는 경고

가능한 원인:

  • 오래된 또는 충돌하는 Python 패키지

해결 방법:

  1. 깨끗한 환경에서 설치하기
    기존 venv/conda 환경을 삭제하고 새로 생성하세요.
  2. 정확한 버전 사용하기
    항상 다음을 실행하세요: 
    pip install -r requirements.txt
    실패할 경우 README에 설명된 대로 누락된 패키지를 수동으로 설치하세요.

구성 문제

5. 환경 변수가 설정되지 않음

배경: 일부 모듈은 키, 토큰 또는 구성 설정이 필요합니다.

증상:

  • 오류: KeyError 또는 누락된 구성에 대한 경고

가능한 원인:

  • 필요한 환경 변수가 설정되지 않음

해결 방법:

  1. .env.example 또는 유사한 파일 확인하기
  2. .env 파일 생성 후 필요한 값 채우기
  3. 환경 변수를 설정한 후 터미널 또는 IDE 다시 로드하기

노트북 실행 문제

6. 노트북이 열리지 않거나 실행되지 않음

배경: Jupyter 노트북은 적절한 설정이 필요합니다.

증상:

  • 노트북 실행 실패
  • 브라우저가 자동으로 열리지 않음

가능한 원인:

  • Jupyter가 설치되지 않음
  • 브라우저 구성 문제

해결 방법:

  1. Jupyter 설치하기 (위 설치 문제 참조)
  2. 노트북을 수동으로 열기
    • 터미널에서 URL을 복사하여 브라우저에 붙여넣기 (예: http://localhost:8888/?token=...).

7. 커널이 충돌하거나 멈춤

배경: 노트북 커널은 리소스 제한 또는 코드 오류로 인해 충돌할 수 있습니다.

증상:

  • 커널이 반복적으로 종료되거나 재시작됨
  • 메모리 부족 오류

가능한 원인:

  • 대규모 데이터셋
  • 호환되지 않는 코드 또는 패키지

해결 방법:

  1. 커널 재시작하기
    Jupyter에서 "Restart Kernel" 버튼을 사용하세요.
  2. 메모리 사용량 확인하기
    사용하지 않는 애플리케이션 닫기.
  3. 클라우드 플랫폼에서 노트북 실행하기
    Google Colab 또는 Azure Notebooks 사용.

성능 문제

8. 노트북 실행 속도가 느림

배경: 일부 AI 작업은 많은 메모리와 CPU를 필요로 합니다.

증상:

  • 실행 속도가 느림
  • 노트북 팬 소음 증가

가능한 원인:

  • 대규모 데이터셋 또는 모델
  • 제한된 시스템 리소스

해결 방법:

  1. 클라우드 플랫폼 사용하기
    • 노트북을 Colab 또는 Azure Notebooks에 업로드.
  2. 데이터셋 크기 줄이기
    • 연습용 샘플 데이터를 사용하세요.
  3. 불필요한 프로그램 닫기
    • 시스템 RAM 확보.

교재 웹사이트 문제

9. 챕터가 로드되지 않음

배경: 온라인 교재는 강의와 챕터를 표시합니다.

증상:

  • 특정 챕터(예: Transformers/BERT)가 누락되거나 열리지 않음

알려진 문제:

  • Issue #303: “18 Transformers. BERT. 교재 웹사이트에서 열리지 않음.” 파일 이름 오류(READMEtransformers.md 대신 README.md)로 인해 발생.

해결 방법:

  1. 파일 이름 변경 오류 확인하기
    기여자인 경우 챕터 파일 이름이 README.md인지 확인하세요.
  2. 누락된 파일 보고하기
    챕터 이름과 오류 세부 정보를 포함하여 GitHub 이슈를 열기.

기여 관련 문제

10. PR이 승인되지 않거나 빌드 실패

배경: 기여는 테스트를 통과하고 가이드라인을 따라야 합니다.

증상:

  • Pull Request가 거부됨
  • CI/CD 파이프라인 오류

가능한 원인:

  • 테스트 실패
  • 코딩 표준을 따르지 않음

해결 방법:

  1. 기여 가이드라인 읽기
  2. 푸시 전에 로컬에서 테스트 실행하기
  3. Linting 규칙 또는 포맷 요구사항 확인하기

FAQ

특정 모듈에 대한 도움은 어디서 찾을 수 있나요?

  • 각 모듈은 일반적으로 자체 README를 가지고 있습니다. 설정 및 사용 팁은 거기서 시작하세요.

버그를 보고하거나 기능을 요청하려면 어떻게 해야 하나요?

여기에 나열되지 않은 문제에 대해 도움을 요청할 수 있나요?

  • 가능합니다! 기존 이슈를 먼저 검색하고, 문제가 발견되지 않으면 새 이슈를 생성하세요.

도움 받기

  • 이슈 확인: GitHub Issues
  • 질문하기: GitHub Discussions를 사용하거나 이슈를 열기.
  • 커뮤니티: 채팅/포럼 옵션은 저장소 링크에서 확인하세요.

최종 업데이트: 2025-09-20

면책 조항:
이 문서는 AI 번역 서비스 Co-op Translator를 사용하여 번역되었습니다. 정확성을 위해 최선을 다하고 있으나, 자동 번역에는 오류나 부정확성이 포함될 수 있습니다. 원본 문서의 원어 버전을 신뢰할 수 있는 권위 있는 자료로 간주해야 합니다. 중요한 정보의 경우, 전문적인 인간 번역을 권장합니다. 이 번역 사용으로 인해 발생하는 오해나 잘못된 해석에 대해 당사는 책임을 지지 않습니다.