d01 - 01. text_generation - 01. responses_api_v2

01. Responses API 기본 소개 v2

이 노트북은 OpenAI Responses API를 호출해 텍스트를 생성합니다. 교육생은 client.responses.create(...) 안에 어떤 매개변수가 들어가는지, 응답 객체에서 어떤 필드를 읽는지 바로 확인할 수 있습니다.

학습 목표:

1. OpenAI() 클라이언트 생성 흐름을 이해합니다.
2. client.responses.create()의 핵심 매개변수인 model, instructions, input, max_output_tokens를 직접 확인합니다.
3. response.output_text, response.id, response.model, response.usage를 직접 출력합니다.

# Colab 또는 로컬 노트북 실행 환경을 구분하기 위해 sys를 가져옵니다.
import sys
# 패키지 설치 명령을 현재 Python 커널에서 실행하기 위해 subprocess를 가져옵니다.
import subprocess
# 패키지 설치 여부를 확인하기 위해 importlib.util을 가져옵니다.
import importlib.util
# 환경 변수에서 API 키를 읽고 설정하기 위해 os를 가져옵니다.
import os
# API 키를 화면에 노출하지 않고 입력받기 위해 getpass를 가져옵니다.
import getpass
# .env 파일 위치를 다루기 위해 pathlib의 Path를 가져옵니다.
from pathlib import Path

# google.colab 모듈이 있으면 현재 런타임이 Google Colab이라고 판단합니다.
IN_COLAB = "google.colab" in sys.modules
# 노트북에서 사용하는 import 이름과 pip 패키지 이름을 짝지어 둡니다.
REQUIRED_PACKAGES = {
    "openai": "openai>=2.26.0",
    "dotenv": "python-dotenv>=1.2.2",
    "pydantic": "pydantic>=2.11.0",
    "PIL": "pillow>=12.1.1",
    "requests": "requests>=2.32.5",
    "numpy": "numpy>=2.3.3",
    "websockets": "websockets>=15.0.1",
    "websocket": "websocket-client>=1.8.0",
    "nest_asyncio": "nest-asyncio>=1.6.0",
}

# 현재 커널에서 import할 수 없는 패키지만 설치하는 함수입니다.
def ensure_package(import_name: str, package_name: str) -> None:
    # 이미 import 가능한 패키지는 설치를 건너뜁니다.
    if importlib.util.find_spec(import_name) is not None:
        # 설치가 필요 없음을 호출자에게 조용히 알리고 돌아갑니다.
        return
    # Colab에서는 현재 노트북 커널의 Python에 패키지를 설치해야 합니다.
    subprocess.check_call([sys.executable, "-m", "pip", "install", "-q", package_name])

# Colab 기본 런타임에는 일부 OpenAI 실습 패키지가 없을 수 있으므로 먼저 준비합니다.
if IN_COLAB:
    # 실습 전체에서 필요한 패키지를 하나씩 확인하고 부족한 것만 설치합니다.
    for import_name, package_name in REQUIRED_PACKAGES.items():
        # 누락된 패키지를 현재 Colab 런타임에 설치합니다.
        ensure_package(import_name, package_name)

# 패키지 설치 이후 .env 로딩 기능을 사용할 수 있도록 load_dotenv를 가져옵니다.
from dotenv import load_dotenv

# 현재 작업 폴더의 .env 파일이 있으면 로컬 실행처럼 환경 변수로 올립니다.
load_dotenv(Path.cwd() / ".env")
# OPENAI_API_KEY가 이미 있으면 그대로 사용하고, 없으면 Colab Secrets 또는 입력으로 보완합니다.
if not os.getenv("OPENAI_API_KEY"):
    # Colab Secrets에서 OPENAI_API_KEY를 읽어 볼 변수를 준비합니다.
    secret_key = None
    # Colab이 아닌 로컬 환경에서는 google.colab import가 실패할 수 있으므로 예외를 허용합니다.
    try:
        # Colab Secrets의 userdata API를 가져옵니다.
        from google.colab import userdata
        # Secrets에 저장된 OPENAI_API_KEY 값을 읽습니다.
        secret_key = userdata.get("OPENAI_API_KEY")
    except Exception:
        # Colab Secrets를 사용할 수 없으면 이후 수동 입력 단계로 넘어갑니다.
        secret_key = None
    # Secrets에서 키를 찾았다면 현재 런타임 환경 변수로 설정합니다.
    if secret_key:
        # OpenAI SDK가 자동으로 읽을 수 있도록 표준 환경 변수 이름에 저장합니다.
        os.environ["OPENAI_API_KEY"] = secret_key
    else:
        # 키가 없으면 노트북 실행자가 직접 입력하도록 요청합니다.
        entered_key = getpass.getpass("OPENAI_API_KEY를 입력하세요: ").strip()
        # 빈 문자열이 아닌 값을 입력한 경우에만 환경 변수로 등록합니다.
        if entered_key:
            # OpenAI SDK가 자동으로 읽을 수 있도록 표준 환경 변수 이름에 저장합니다.
            os.environ["OPENAI_API_KEY"] = entered_key

# API 키가 끝까지 없으면 다음 OpenAI API 호출이 실패하므로 명확한 오류를 냅니다.
if not os.getenv("OPENAI_API_KEY"):
    # Colab에서는 Secrets 또는 입력, 로컬에서는 .env 또는 환경 변수를 설정해야 함을 알려 줍니다.
    raise RuntimeError("OPENAI_API_KEY가 없습니다. Colab Secrets, 수동 입력, 또는 .env 파일로 설정해 주세요.")

# 이후 셀에서 Colab 여부를 참고할 수 있도록 간단히 출력합니다.
print(f"개발환경: {'Colab' if IN_COLAB else '로컬'}")
# API 키를 직접 출력하지 않고 준비 완료 여부만 알려 줍니다.
print("OPENAI_API_KEY 준비 완료")

 

1단계. 최소 실행 환경 준비

이 단계에서는 API 호출에 필요한 기본 준비를 합니다. import, .env 로드, OpenAI() 클라이언트 생성, output 폴더 생성을 차례대로 확인합니다.

아래 셀에서 특히 client = OpenAI() 줄을 확인하세요. 이후 모든 API 호출은 이 client 객체에서 시작됩니다.

 

# 운영체제 환경 변수와 .env 값을 읽기 위해 os를 사용합니다.
import os
# JSON 메타데이터를 파일로 저장하기 위해 json을 사용합니다.
import json
# 실행 시간을 비교하는 예제에서 사용할 시간 측정 모듈입니다.
import time
# 노트북 실행 위치와 output 폴더 경로를 안전하게 다루기 위한 Path입니다.
from pathlib import Path

# .env 파일에 저장된 OPENAI_API_KEY를 현재 Python 환경으로 불러옵니다.
from dotenv import load_dotenv
# OpenAI API를 직접 호출하기 위한 공식 SDK 클라이언트입니다.
from openai import OpenAI

# 현재 노트북이 워크스페이스 루트에서 실행되는지, 01.text_generation 폴더에서 실행되는지 확인합니다.
CURRENT_DIR = Path.cwd().resolve()
# 워크스페이스 루트에서 실행 중이면 01.text_generation 폴더를 실습 루트로 사용합니다.
if (CURRENT_DIR / "01.text_generation").exists():
    TEXT_GENERATION_DIR = CURRENT_DIR / "01.text_generation"
# 이미 01.text_generation 폴더 안에서 실행 중이면 현재 폴더를 실습 루트로 사용합니다.
else:
    TEXT_GENERATION_DIR = CURRENT_DIR

# 워크스페이스 루트는 01.text_generation 폴더의 부모 폴더입니다.
WORKSPACE_ROOT = TEXT_GENERATION_DIR.parent
# 실행 결과를 저장할 output 폴더 경로입니다.
OUTPUT_DIR = TEXT_GENERATION_DIR / "output"
# output 폴더가 없으면 새로 만들고, 이미 있으면 그대로 둡니다.
OUTPUT_DIR.mkdir(parents=True, exist_ok=True)

# 워크스페이스 루트의 .env 파일을 읽습니다.
load_dotenv(WORKSPACE_ROOT / ".env")

# OpenAI API 키가 설정되어 있는지 먼저 확인합니다.
if not os.getenv("OPENAI_API_KEY"):
    raise RuntimeError("OPENAI_API_KEY가 없습니다. 워크스페이스 루트의 .env 파일을 확인해 주세요.")

# OpenAI API를 호출할 클라이언트를 생성합니다. 이 줄이 모든 API 호출의 출발점입니다.
client = OpenAI()

# 이후 셀에서 저장 경로를 확인할 수 있도록 출력합니다.
print(f"실습 폴더: {TEXT_GENERATION_DIR}")
print(f"결과 저장 폴더: {OUTPUT_DIR}")

실습 폴더: C:\Users\ai4nu\2026-ai-tech\AS.1.1_0601\01.text_generation
결과 저장 폴더: C:\Users\ai4nu\2026-ai-tech\AS.1.1_0601\01.text_generation\output

 

2단계. 요청에 사용할 값 준비하기

API 호출 전에 모델명, 지시문, 사용자 입력을 변수로 정리합니다. 변수로 분리해 두면 어떤 값이 API 요청에 들어가는지 한눈에 볼 수 있습니다.

# .env에 OPENAI_RESPONSES_MODEL이 있으면 그 값을 사용하고, 없으면 기본 모델을 사용합니다.
RESPONSES_MODEL = os.getenv("OPENAI_RESPONSES_MODEL", "gpt-4.1-mini")

# instructions는 모델의 역할, 말투, 출력 기준을 정하는 상위 지시입니다.
INSTRUCTIONS = "당신은 사내 교육 담당자입니다. 초급 교육생이 바로 이해할 수 있는 쉬운 한국어로 답변하세요."

# input은 실제 사용자 요청입니다.
PROMPT = "신입사원 교육 안내 메시지를 작성해 주세요. 조건: 1) 5문장, 2) 문장은 짧고 명확하게, 3) 마지막 문장은 준비물 점검을 강조."

# 요청 전에 어떤 값이 들어가는지 확인합니다.
print(f"요청 모델: {RESPONSES_MODEL}")
print(f"지시문: {INSTRUCTIONS}")
print(f"프롬프트: {PROMPT}")

요청 모델: gpt-4.1-mini
지시문: 당신은 사내 교육 담당자입니다. 초급 교육생이 바로 이해할 수 있는 쉬운 한국어로 답변하세요.
프롬프트: 신입사원 교육 안내 메시지를 작성해 주세요. 조건: 1) 5문장, 2) 문장은 짧고 명확하게, 3) 마지막 문장은 준비물 점검을 강조.

 

3단계. Responses API 직접 호출하기

아래 셀이 핵심입니다. client.responses.create(...) 괄호 안의 각 줄이 API 요청 매개변수입니다.

# Responses API 호출 시작 시간을 기록합니다.
started = time.perf_counter()

# Responses API를 직접 호출합니다.
response = client.responses.create(
    # 어떤 모델에 요청할지 지정합니다.
    model=RESPONSES_MODEL,
    # 모델의 역할과 답변 스타일을 지정합니다.
    instructions=INSTRUCTIONS,
    # 실제 사용자 요청 본문입니다.
    input=PROMPT,
    # 출력이 너무 길어지지 않도록 최대 출력 토큰 수를 지정합니다.
    max_output_tokens=240,
)

# API 호출에 걸린 시간을 계산합니다.
elapsed = time.perf_counter() - started

# Responses API는 최종 텍스트를 output_text 속성으로 쉽게 제공합니다.
output_text = response.output_text

# 생성된 텍스트를 출력합니다.
print("[생성 텍스트]")
print(output_text)

# 응답 객체에서 확인할 수 있는 주요 필드를 직접 출력합니다.
print()
print("[응답 정보]")
print(f"response.id: {response.id}")
print(f"response.model: {response.model}")
print(f"response.status: {response.status}")
print(f"실행 시간: {elapsed:.4f}초")
print(f"response.usage: {response.usage}")

[생성 텍스트]
안녕하세요, 신입사원 여러분. 다음 주부터 교육이 시작됩니다. 교육은 오전 9시에 시작합니다. 열심히 참여해 주세요. 준비물 꼭 챙겨 오세요.

[응답 정보]
response.id: resp_0bbb1686e776e223006a1c471ade3c8199be0183c5a432e53d
response.model: gpt-4.1-mini-2025-04-14
response.status: completed
실행 시간: 1.4161초
response.usage: ResponseUsage(input_tokens=87, input_tokens_details=InputTokensDetails(cached_tokens=0), output_tokens=43, output_tokens_details=OutputTokensDetails(reasoning_tokens=0), total_tokens=130)

 

 

4단계. 결과 저장하기

실행 결과를 텍스트 파일과 JSON 파일로 저장합니다. 생성된 텍스트와 실행 메타데이터를 나누어 기록합니다.

# 텍스트 결과를 저장할 파일 경로입니다.
text_path = OUTPUT_DIR / "01_responses_api_v2_output.txt"
# 실행 정보를 저장할 JSON 파일 경로입니다.
metadata_path = OUTPUT_DIR / "01_responses_api_v2_meta.json"

# 생성된 텍스트를 파일로 저장합니다.
text_path.write_text(output_text + "\\n", encoding="utf-8")

# usage 객체는 model_dump()로 dict처럼 저장할 수 있는 형태로 바꿉니다.
usage = response.usage.model_dump() if response.usage else {}

# 메타데이터는 나중에 실행 조건을 다시 확인하기 위한 기록입니다.
metadata = {
    "example": "01.responses_api_v2",
    "requested_model": RESPONSES_MODEL,
    "actual_model": response.model,
    "response_id": response.id,
    "status": response.status,
    "elapsed_seconds": round(elapsed, 4),
    "usage": usage,
    "output_path": str(text_path),
}

# JSON 파일로 메타데이터를 저장합니다.
metadata_path.write_text(json.dumps(metadata, ensure_ascii=False, indent=2) + "\\n", encoding="utf-8")

# 저장 위치를 출력합니다.
print(f"텍스트 저장: {text_path}")
print(f"메타데이터 저장: {metadata_path}")

텍스트 저장: C:\Users\ai4nu\2026-ai-tech\AS.1.1_0601\01.text_generation\output\01_responses_api_v2_output.txt
메타데이터 저장: C:\Users\ai4nu\2026-ai-tech\AS.1.1_0601\01.text_generation\output\01_responses_api_v2_meta.json