README.md

AS.1.1 Python 실습 프로젝트 환경 구성 가이드

이 문서는 이 프로젝트를 실행하기 위한 Python 개발 환경을 uv로 구성하는 단계별 안내입니다. uv는 Python 버전 관리, 가상 환경 생성, 패키지 설치를 빠르게 처리해 주는 Python 패키지 및 프로젝트 관리 도구입니다.

1. uv 설치하기

Windows PowerShell

PowerShell을 열고 아래 명령을 실행합니다.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

설치가 끝난 뒤 터미널을 새로 열고 설치 여부를 확인합니다.

uv --version

2. 프로젝트 폴더로 이동하기

터미널에서 이 프로젝트 폴더로 이동합니다.

cd C:\Users\ai4nu\2026-ai-tech\AS.1.1

다른 위치에 프로젝트를 내려받았다면, 본인의 프로젝트 경로로 이동하면 됩니다.

3. uv init으로 프로젝트 초기화하기

새 프로젝트를 처음 만든다면 uv init으로 Python 프로젝트 기본 파일을 생성합니다.

새 폴더를 만들면서 초기화하기

uv init AS.1.1 --python 3.12
cd AS.1.1

이미 만든 폴더에서 초기화하기

이미 프로젝트 폴더 안에 들어와 있다면 아래 명령을 실행합니다.

uv init . --python 3.12

uv init은 보통 다음 파일을 생성하거나 갱신합니다.

• pyproject.toml: 프로젝트 이름, Python 버전, 의존성 정보를 관리하는 설정 파일
• .python-version: 프로젝트에서 사용할 Python 버전 정보
• README.md: 프로젝트 설명 문서
• main.py: 기본 실행 예제 파일

이 저장소처럼 이미 pyproject.toml이 있는 프로젝트를 내려받은 경우에는 uv init을 다시 실행하지 않아도 됩니다. 이때는 다음 단계의 Python 설치 확인과 uv sync만 진행하면 됩니다.

4. Python 3.12 설치 확인하기

이 프로젝트는 pyproject.toml에서 Python 3.12 이상을 요구합니다.

uv python list

Python 3.12가 없다면 아래 명령으로 설치할 수 있습니다.

uv python install 3.12

5. uv sync로 프로젝트 환경 동기화하기

프로젝트 루트에서 아래 명령을 실행합니다.

uv sync --python 3.12

uv sync는 현재 프로젝트의 pyproject.toml과 uv.lock을 기준으로 .venv 가상 환경을 동기화합니다.

이 명령은 다음 작업을 한 번에 처리합니다.

• .venv 가상 환경이 없으면 자동 생성
• pyproject.toml에 정의된 의존성 확인
• uv.lock 잠금 파일 기준으로 패키지 버전 동기화
• uv.lock이 없거나 갱신이 필요하면 잠금 파일 생성 또는 업데이트
• 현재 프로젝트를 실행 가능한 환경으로 설치

앞으로 이 프로젝트에서는 단계별 requirements.txt 파일을 사용하지 않고, 루트의 pyproject.toml과 uv.lock을 기준으로 환경을 관리합니다.

6. 가상 환경 활성화하기

uv run을 사용하면 가상 환경을 직접 활성화하지 않아도 명령을 실행할 수 있습니다. 그래도 터미널에서 python 명령을 계속 직접 사용할 예정이라면 아래처럼 활성화합니다.

Windows PowerShell

.venv\Scripts\Activate.ps1

PowerShell 실행 정책 때문에 활성화가 막히면, 현재 터미널 세션에서만 정책을 완화한 뒤 다시 활성화합니다.

Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned
.venv\Scripts\Activate.ps1

활성화되면 터미널 프롬프트 앞에 (.venv)가 표시됩니다.

7. 프로젝트 의존성 설치하기

의존성 설치는 5단계의 uv sync로 이미 완료됩니다. 이후 패키지를 추가하거나 제거할 때도 uv 명령을 사용합니다.

uv add package-name
uv remove package-name

패키지를 추가하면 pyproject.toml의 dependencies 목록에 의존성이 기록되고, uv.lock에는 실제로 설치할 정확한 버전 정보가 기록됩니다.

필요한 패키지 추가하기

uv add openai python-dotenv pydantic requests

특정 버전 이상 설치하기

특정 버전 또는 그 이상의 버전이 필요하면 >= 조건을 붙입니다. PowerShell에서는 버전 조건을 따옴표로 감싸는 것이 안전합니다.

uv add "openai>=2.26.0"
uv add "pydantic>=2.11.0" "python-dotenv>=1.2.2"

이렇게 추가하면 pyproject.toml에는 아래와 같은 형태로 기록됩니다.

dependencies = [
	"openai>=2.26.0",
	"pydantic>=2.11.0",
	"python-dotenv>=1.2.2",
]

특정 버전으로 고정하기

정확히 특정 버전만 사용해야 한다면 == 조건을 사용합니다.

uv add "openai==2.26.0"

패키지 제거하기

uv remove package-name

설치되는 주요 패키지는 다음과 같습니다.

• openai: OpenAI API 사용
• python-dotenv: .env 파일의 환경 변수 로드
• pydantic: 구조화된 데이터 검증
• requests: HTTP 요청 처리
• pillow: 이미지 처리
• sounddevice: 오디오 입출력
• websocket-client: WebSocket 클라이언트 통신
• websockets: WebSocket 통신
• numpy: 수치 연산
• jupyter: Jupyter Notebook 실행

8. OpenAI API와 GitHub Copilot 준비하기

이 프로젝트의 OpenAI 예제를 실행하려면 OpenAI Platform 계정, 결제용 크레딧, API 키가 필요합니다. 추가로 VS Code에서 GitHub Copilot Free를 사용하려면 GitHub 계정으로 Copilot을 활성화하면 됩니다.

8-1. OpenAI API Platform 가입하기

1. 브라우저에서 https://platform.openai.com/login 페이지를 엽니다.
2. 처음 사용하는 경우 이메일 주소를 입력한 뒤 Continue를 선택합니다.
3. 또는 Continue with Google, Continue with Apple, Continue with Microsoft, Continue with phone 중 원하는 로그인 방식을 선택합니다.
4. 처음 가입하는 경우 이름, 계정 정보, 본인 확인 절차를 순서대로 완료합니다.
5. 가입이 끝나면 OpenAI Platform 대시보드로 이동해 API 사용 준비를 진행합니다.

로그인이 이미 되어 있다면 같은 페이지에서 바로 OpenAI Platform으로 들어갈 수 있습니다.

8-2. Credit balance 추가하기

1. OpenAI Platform에 로그인한 뒤 https://platform.openai.com/settings/organization/billing/overview 페이지로 이동합니다.
2. 조직(Organization)이 여러 개라면 현재 실습에 사용할 조직이 맞는지 먼저 확인합니다.
3. Billing 화면에서 Add to credit balance 또는 유사한 충전 버튼을 선택합니다.
4. 결제할 금액을 입력하고 카드 등 결제 수단을 등록하거나 선택합니다.
5. 결제를 완료한 뒤 Billing 화면에서 크레딧 잔액이 반영되었는지 확인합니다.

크레딧이 없으면 API 호출 시 결제 한도 또는 사용량 관련 오류가 발생할 수 있습니다.

8-3. Secret key 생성하기

1. OpenAI Platform에 로그인한 뒤 https://platform.openai.com/settings/organization/api-keys 페이지로 이동합니다.
2. API 키를 만들 조직이 맞는지 확인합니다.
3. Create new secret key 버튼을 선택합니다.
4. 키 이름을 입력하라는 화면이 나오면 실습용 이름 예를 들어 as-1-1-local처럼 구분하기 쉬운 이름을 입력합니다.
5. 생성 직후 표시되는 secret key 값을 한 번만 확인하고 안전한 곳에 보관합니다.

생성된 secret key는 다시 전체 값을 조회할 수 없는 경우가 많으므로, 바로 복사해 .env 파일에 넣는 것이 가장 안전합니다.

8-4. GitHub Copilot Free Plan 가입하기

1. 브라우저에서 https://github.com/features/copilot 페이지를 엽니다.
2. Free 플랜 영역의 Get started 버튼을 선택합니다.
3. GitHub 계정이 없다면 먼저 GitHub 회원가입을 진행하고, 계정이 있다면 로그인합니다.
4. Copilot 사용 약관이나 초기 설정 화면이 나오면 안내에 따라 활성화를 완료합니다.
5. VS Code에서 GitHub 계정으로 로그인한 뒤 GitHub Copilot 또는 GitHub Copilot Chat 확장을 사용하면 Free 플랜 범위 안에서 기능을 사용할 수 있습니다.

GitHub Copilot Free는 일반적으로 신용카드 없이 시작할 수 있지만, 월별 사용량 제한과 제공 모델 범위가 있으므로 플랜 안내를 함께 확인하는 것이 좋습니다.

9. 환경 변수 파일 준비하기

OpenAI API를 사용하는 예제는 API 키가 필요할 수 있습니다. 프로젝트 루트에 .env 파일을 만들고 아래처럼 값을 입력합니다.

OPENAI_API_KEY=your_api_key_here

your_api_key_here는 본인의 실제 API 키로 바꿉니다. .env 파일에는 민감한 정보가 들어가므로 Git에 커밋하지 않도록 주의합니다.

10. Google Colab에서 노트북 실행하기

이 프로젝트의 모든 .ipynb 노트북은 Google Colab에서도 실행할 수 있도록 첫 부분에 Colab 준비 셀이 포함되어 있습니다. Colab에서는 로컬 .venv나 uv sync를 사용하지 않고, 노트북의 첫 코드 셀이 필요한 Python 패키지를 현재 Colab 런타임에 자동으로 설치합니다.

Colab에서 실행하는 기본 흐름은 다음과 같습니다.

1. 실행할 .ipynb 파일을 Google Colab에서 엽니다.
2. Colab 왼쪽의 열쇠 아이콘 또는 Tools > Secrets에서 OPENAI_API_KEY를 추가합니다.
3. Secrets 사용이 어렵다면 첫 코드 셀이 실행될 때 API 키를 직접 입력합니다.
4. 첫 코드 셀을 먼저 실행해 패키지 설치와 API 키 준비를 마칩니다.
5. 이후 셀을 순서대로 실행합니다.

07.embeddings_firesearch_retrieval의 03.retrieval과 04.responses_rag 노트북은 벡터 스토어 설정 파일을 사용합니다. Colab에서 이 두 노트북을 실행할 때는 같은 런타임에서 02.files_vector_stores/files_vector_stores_v2.ipynb를 먼저 실행해 vector_store_config_v2.json을 만든 뒤 진행합니다.

Colab Secrets에 저장할 값은 아래 이름을 사용합니다.

OPENAI_API_KEY=your_api_key_here

노트북은 API 키를 화면에 출력하지 않고 준비 완료 여부만 표시합니다. 로컬 환경에서는 기존처럼 프로젝트 루트의 .env 파일을 읽고, Colab 환경에서는 Secrets 또는 수동 입력 값을 환경 변수로 등록합니다.

11. 설치 확인하기

아래 명령으로 Python이 가상 환경을 사용하고 있는지 확인합니다.

uv run python --version
uv run python -c "import openai, pydantic, dotenv; print('environment ready')"

environment ready가 출력되면 기본 환경 구성이 완료된 것입니다.

12. 실습 폴더 확인하기

각 실습 주제는 아래 폴더에 정리되어 있습니다.

• 01.text_generation: 텍스트 생성
• 02.function_calling: 함수 호출(Function Calling)
• 03.structured_output: 구조화된 출력(Structured Output)
• 04.web_search: 웹 검색(Web Search)
• 05.image: 이미지 처리 및 생성
• 06.audio: 오디오 처리
• 07.embeddings_firesearch_retrieval: 임베딩(Embeddings) 및 검색 기반 검색(Retrieval)

각 폴더의 README.md를 열어 해당 실습 안내를 확인하세요.

자주 사용하는 명령

패키지 추가

uv add package-name

예를 들어 jupyter를 추가하거나 특정 버전 이상을 설치하려면 다음처럼 실행합니다.

uv add jupyter
uv add "jupyter>=1.1.1"

현재 설치된 패키지 확인

uv pip list

가상 환경을 활성화하지 않고 명령 실행

uv run python --version
uv run jupyter notebook

가상 환경 비활성화

deactivate