3. 텍스트 생성(Text Generation)
2장 OpenAI API
이제 OpenAI API를 활용해 실제 프로그램을 만들어 봅시다. 여기서는 OpenAI의 다양한 모델과 기능을 이용해, 서비스나 애플리케이션에서 직접 쓸 수 있는 API를 실습 형태로 다룹니다.
OpenAI API를 이용하면 단순히 텍스트를 생성하는 것뿐만 아니라, 질문응답, 번역, 요약, 코딩지원 등 폭넓은 작업을 수행할 수 있습니다. 또한, JSON형식으로 데이터를 주고받을 수 있어, 다양한 애플리케이션과 쉽게 연동할 수 있습니다. 더 나아가, Reasoning기능을 활용하면 복잡한 논리적 사고나 심층적 추론 작업도 가능합니다.
이미지나 음성 데이터를 다루는 멀티모달 API도 지원되며, 이를 통해 다음과 같은 작업을 수행할 수 있습니다.
이미지 인식(Image Recognition)
이미지 생성(Image Generation)
음성합성(Text-to-Speech)
음성인식(Speech Recognition)
마지막으로 데이터분석이나 추천 시스템등에서 활용되는 임베딩(embedding)기술도 같이 배워봅시다.
텍스트 생성 (Text Generation)
OpenAI API키를 발급받아, 질문응답이나 번역 등 다양한 텍스트 생성 프로그램을 직접 구현하는 방법을 설명합니다.
⑴ 텍스트 생성이란?
텍스트 생성(Text Generation)은 AI모델이 입력된 프롬프트(문장이나 질문)에 다라 적절한 텍스트를 자동으로 만들어내는 기술입니다.
특히 OpenAI의 모델은 단순한 문장생성뿐만 아니라, 문맥을 이해하고 인간처럼 자연스럽게 문장을 완성하는데 강정을 가집니다. JSON형태로 데이터를 주고받을 수 있기 때문에 다양한 애플리케이션과의 연동도 손쉽습니다. 텍스트 생성 API를 활용하면 다음과 같은 작업을 수행할 수 있습니다.
문장생성(Text Writing)
질문응답(Q&A)
요약(Summarization)
번역(Translation)
코딩지원(Code Generation)
2025년 10월 기준, OpenAI에서 제공하는 주요 텍스트 생성용 모델은 아래와 같습니다.
gpt-5
gpt-5는 다양한 분야의 코딩, 추론(reasoning), 에이전트형 작업(Agentic Task)을 처리할 수 있는 가장 강력한 범용 모델입니다.
컨텍스트 윈도우: 400,000 토큰
최대 출력 토큰: 128,000 토큰
지식컷오프: 2024년 10월 1일
gpt-5-mini
gpt-5-mini는 GPT-5의 경량버전으로, 비용 효율성과 응답속도가 중요한 프로젝트에 적합합니다. 성능은 약간 제한되지만, 실험 및 반복 테스트용으로 많이 사용됩니다.
컨텍스트 윈도우: 400,000 토큰
최대 출력 토큰: 128,000 토큰
지식컷오프: 2024년 5월 31일
gpt-5-nano
gpt-5-nano는 가장 작은 모델로 경량환경(예: 모바일앱, 임베디드 시스템 등)이나 요약, 분류 등의 단순 태스크에 적합합니다.
컨텍스트 윈도우: 400,000 토큰
최대 출력 토큰: 128,000 토큰
지식컷오프: 2024년 5월 31일
gpt-5-chat-latest
gpt-5-chat-latest는 현재 ChatGPT에서 사용되고 있는 GPT-5의 최신 스냅샷 버전입니다. 이 모델은 안정성과 응답품질을 우선시하여 주기적으로 업데이트됩니다.
컨텍스트 윈도우: 400,000 토큰
최대 출력 토큰: 128,000 토큰
지식컷오프: 2024년 9월 30일
이 외에도 OpenAI에서는 다음과 같은 모델들이 제공되고 있습니다.
GPT 계열 모델: gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-4o, gpt-4o-mini
Reasoning(추론) 전용 모델: o4-mini, o3, o3-mini
참고로 2025년 2월에 발표된 GPT-4.5 모델은 기존 GPT-4계열보다 자연스러운 대화흐름과 인간 수준의 추론 능력을 개선한 것이 특징입니다. 이전보다 속도와 응답효율이 크게 향상되었으며, 비용구조 역시 합리적으로 조정되었습니다.
Text Generation - OpenAI API공식문서: https://platform.openai.com/docs/guides/text
컨텍스트 윈도우 (Context Window): 모델이 한번에 이해 및 처리할 수 있는 입력 텍스트의 최대 크기를 의미합니다. 즉, 사용자 입력(프롬프트)과 모델의 응답(출력)을 합친 전체 토큰수가 이 제한을 초과하면 이전 내용이 잘리거나 잊히게 됩니다.
최대 출력 토큰 (Max Output Token): 모델이 한번의 응답에서 최대로 생성할 수 있는 토큰 수를 의미합니다. 출력길이가 길수록 응답이 완전해지지만 처리시간과 비용도 늘어납니다.
지식컷오프(Knowledge Cutoff): 모델이 학습한 마지막 시점을 나타냅니다. 컷오프 이후의 정보는 기본적으로 포함되어 있지 않지만, 웹검색 기능이나 파인튜닝을 통해 최신 데이터를 반양할 수 있습니다.
토큰 수
토큰(Token)은 언어모델이 텍스트를 처리할 때 사용하는 가장 작은 단위입니다. 단어, 문장부호, 공백 등이 각각 토큰으로 계산됩니다. 예를 들어,
"Hello, world!"
이 문장은 약 3~4개 토큰으로 계산됩니다. 모델마다 토큰 분리 규칙이 다르기 때문에 실제 토큰 수는 약간 달라질 수 있습니다. OpenAI에서는 공식 Tokenizer 도구를 제공하고 있으며, 이 사이트에서 입력한 문장의 토큰수를 직접 확인할 수 있습니다.
Tokenizer - OpenAI: https://platform.openai.com/tokenizer
⑵ 텍스트 생성 모델의 입출력 구조
텍스트 생성 모델은 기본적으로 입력메시지(프롬프트)를 받고, 이에 대한 응답(출력텍스트)을 생성하는 구조로 되어 있습니다. OpenAI의 챗봇 API에서는 여러 개의 메시지를 하나의 메시지 리스트(Message List)형태로 입력합니다.
예시구조
이와 같이 입력하면, 모델은 대화문맥을 고려해 적절한 답변을 반환합니다. system은 모델의 성격이나 역할을 정의하고, user는 사용자 질문을 의미합니다. 대화형 애플리케이션을 만들 때는 이 구조가 핵심이 됩니다.
OpenAI의 텍스트 생성 모델은 하나의 메시지 리스트(Message List)를 입력받아 그에 대한 응답 메시지(Output List)를 출력하는 구조입니다. 이 메시지 리스트는 대화의 흐름을 기록하는 일종의 대화 히스토리이며, 리스트 안의 각 항목은 메시지(Message)객체로 구성되어 있습니다. 각 메시지는 role(역할)과 content(내용)의 두 가지 요소를 가집니다.
developer: 개발자 메시지
user: 사용자 메시지
assistant: 어시스턴트(모델) 메시지
developer 메시지
AI가 어떤 방식으로 응답할지, 즉, 모델의 말투나 응답 스타일을 지정하기 위한 설정 메시지입니다. 이전에는 "system 메시지"라고 불리기도 했습니다.
user 메시지
사용자가 실제로 모델에 입력하는 질문이나 요청을 의미합니다. 예를 들어, "서울 날씨 알려줘"와 같은 문장이 이에 해당합니다.
assistant 메시지
모델이 user의 요청에 따라 생성하는 답변을 의미합니다. 이 메시지를 저장해두면, 이후 대화문맥을 이어갈 수 있습니다.
보통 대화형 애플리케이션에서는 먼저 developer메시지로 모델의 톤이나 역할을 설정하고, 그 다음 user 메시지와 assistant 메시지를 주고받으며 대화형 세션을 유지합니다.
developer: 짧고 친근한 답변을 하는 어시스턴트
user: 한라산의 높이는 얼마입니까?
assistant: 한라산의 높이는 1950m입니다.
이처럼 메시지 리스트에 이전 대화이력을 포함시켜 두면, 모델이 맥락을 이해해 자연스럽고 일관된 멀티턴 대화를 이어갈 수 있습니다.
⑶ 텍스트 생성 모델의 이용요금
OpenAI의 텍스트 생성 모델은 사용한 모델 종류와 입출력 시 소비된 토큰수(Token Count)에 따라 요금이 책정됩니다. 요금은 입력토큰(Input Token)과 출력토큰(Output Token)이 각각 따로 계산되며, 모델별 단가가 다르기 때문에 사용시 주의가 필요합니다.
또한, GPT-5 계열 중 Reasoning 모델의 경우, 모델이 내부적으로 복잡한 사고과정을 거쳐 응답을 생성할 때, 추가로 Reasoning토큰이 발생합니다.
텍스트 생성 모델의 이용요금 (2025년 10월 기준)
캐싱된 입력이란, 이전에 처리된 입력 데이터를 재활용할 때 적용되는 할인요금입니다. 즉, 동일한 프롬프트를 반복적으로 호출하는 경우 비용이 대폭 절감됩니다. 이 기능은 'Prompt Caching"(프롬프트 캐시)이라 하며, 대규모 서비스 운영 시, 비용 최적화에 효과적입니다.
공식 비용에 대해서는 아래 사이트를 참고하여 최신 정보를 확인합니다.
공식 사이트: https://openai.com/ko-KR/api/pricing/
⑶ OpenAI API키 발급받기
Python 등 프로그래밍 언어에서 OpenAI API를 사용하려면, OpenAI 계정에 등록된 API키가 필요합니다. 이 API키는 OpenAI서버와 통신할 때, 인증용으로 사용되는 고유한 문자열입니다. 즉, 모델을 호출할 때 "이 사용자가 정식등록된 계정인지"를 확인하는 역할을 합니다.
① 브라우저에서 OpenAI API사이트 접속
브라우저에서 아래 OpenAI API페이지로 접속합니다.
관련 URL: https://openai.com/ko-KR/index/openai-api/
상단 메뉴에서 [Login] - [API 플랫폼]을 클릭하여 로그인합니다.
처음 로그인 시에는 조직(Organization) 이름을 입력한 뒤, 팀멤버 추가, 결제(카드 등록)등의 절차를 거쳐야 합니다.
② 조직이름 입력
개인 사용자의 경우,
조직명에는 본인이름이나 닉네임을 자유롭게 입력해도 됩니다. 단, 프로젝트를 외부에 공개하거나 공유 링크를 통해 다른 사람과 사용할 가능성이 있다면 혼동을 줄 수 있는 이름을 피하는 것이 좋습니다.
③ 팀멤버 추가
팀단위로 사용할 경우, 이 단계에서 이메일주소를 입력해서 동료를 추가할 수 있습니다. 개인 사용자라면 입력하지 않고 [Continue]버튼을 바로 클릭해도 됩니다.
④ OpenAI API키 생성
다음으로 API 키를 생성합니다. 기본 제공되는 프로젝트명과 키이름은 그대로 사용해도 문제는 없습니다. 버튼을 클릭하여 키를 생성하면 OpenAI서버와 통신할 때, 사용할 인증 토큰이 발급됩니다.
⑤ OpenAI API키 복사
생성된 API키는 반드시 복사해서 안전한 곳에 따로 보관해야 합니다. 이후에는 보안상 이유로 화면에 다시 표시되지 않으므로 잃어버리지 않도록 주의해야 합니다.
⑥ OpenAI API 크레딧 결제
OpenAI API를 사용하려면 일정금액의 크레딧(Credit)을 충전해야 합니다. 소액으로도 가능하기 때문에 작은 실습이라면 최소 금액만 결제해도 충분합니다.
이로써 OpenAI API키 발급절차는 마무리되었고 이제 발급된 API키를 확인하거나 새로 추가하는등의 관리는 대시보드에서 [Settings] - [API keys]메뉴를 선택합니다.
⑷ OpenAI API 사전준비
OpenAI API를 Python 코드에서 사용하기 전에 다음과 같은 기본 설정을 진행합니다.
① 새 Colab 노트북 열기
Google Colab환경에서 새 노트북을 생성합니다.
② openai 패키지 설치
Colab의 코드셀에 아래 명령어를 입력하여 최신 버전의 OpenAI 라이브러리를 설치합니다.
# 패키지 설치
!pip install -U openai
③ 환경변수 설정
Google Colab에서 발급받은 API키를 안전하게 사용하려면 API키를 직접 코드에 입력하지 않고 환경변수로 설정하는 것이 좋습니다.
Colab 왼쪽 � 아이콘 메뉴를 클릭하고 '보안 비밀'에서 "OPENAI_API_KEY" 이름을 입력하고 API키 값을 '값'에 입력합니다.
다음으로 코드에서 Colab환경변수에 저장된 키를 불러올 수 있습니다.
import os
from google.colab import userdata
# 환경 변수에서 OpenAI API 키 불러오기
os.environ["OPENAI_API_KEY"] = userdata.get("OPENAI_API_KEY")
④ 클라이언트 준비
이제 OpenAI API를 사용할 준비가 끝났습니다. 아래 코드를 실행해 클라이언트를 초기화합니다.
from openai import OpenAI
# 클라이언트 초기화
client = OpenAI()
⑸ 텍스트 생성 실행하기
여기서는 실제로 텍스트를 생성하는 프로그램을 실행해 봅시다.
① 메시지 리스트(Message List)준비
OpenAI 텍스트 생성 모델은 여러개의 메시지를 순서대로 전달하는 방식으로 동작합니다.
메시지는 role(역할)과 content(내용)으로 구성되며, developer, user, assistant의 3가지 역할이 있습니다. developer메시지는 선택사항입니다.
# 메시지 리스트 구성 예시
messages = [
{
"role": "developer",
"content": "짧고 친근한 문체로 응답하는 어시스턴트입니다.",
},
{
"role": "user",
"content": "서울의 오늘 날씨 어때?",
}
]
메시지리스트를 활용하면 이전 대화맥락을 유지할 수 있습니다. 여러번 요청을 하나의 대화로 연결할 수 있는 이유가 바로 이 구조입니다.
② 텍스트 생성
텍스트 생성을 실행하려면, client.responses.create() 메소드를 사용합니다. 이 함수에서는 model(모델ID)과 input(메시지리스트)를 지정해야 합니다. 여기서는 gpt-5모델을 예시로 사용합니다. 아래 코드를 실행하면 모델이 응답을 생성하고 결과를 response.output_text로 출력할 수 있습니다.
# 텍스트 생성 실행
response = client.responses.create(
model="gpt-5", # 모델 ID
input=messages # 메시지 리스트
)
print(response.output_text)
질문을 "한국에서 가장 높은 산은?"을 변경해서 실행하면 응답이 정확하게 나올 것입니다.
③ 토큰 수 확인
응답 객체의 response.usage 속성을 통해 입출력 토큰수를 확인할 수 있습니다.
print("입력 토큰 수:", response.usage.input_tokens)
print("출력 토큰 수:", response.usage.output_tokens)
print("총 토큰 수:", response.usage.total_tokens)
⑹ 텍스트 생성의 주요 작업(Task)
OpenAI의 텍스트 생성 API를 사용하면 여러가지 형태의 작업을 수행할 수 있습니다. (질문응답은 따로 다루기 때문에 생략함)
문장 생성(Text Writing)
소설, 기사, 보고서등 창의적 글쓰기나 설명문을 자동으로 작성하는 작업입니다.
① 메시지 리스트 준비
# 메시지 리스트 구성
messages = [
{
"role": "user",
"content": "사이버펑크 분위기의 소설 한 문단을 써주세요."
}
]
② 추론 실행 (Reasoning)
추론 작업은 모델이 문맥을 이해하고, 논리적으로 결론을 도출하는 형태의 텍스트 생성을 의미합니다.
모델실행
# 텍스트 생성 실행
response = client.responses.create(
model="gpt-5",
input=messages
)
print(response.output_text)
질문응답(Q&A)
챗봇 형태의 대화시스템에서 사용자의 질문에 정확한 정보를 바탕으로 답변하는 태스크입니다.
① 메시지 리스트 준비
# 메시지 리스트 구성
messages = [
{
"role": "user",
"content": "인공지능이란 무엇인가요?"
}
]
② 추론 실행 (Reasoning)
추론 작업은 모델이 문맥을 이해하고, 논리적으로 결론을 도출하는 형태의 텍스트 생성을 의미합니다.
# 추론 실행
response = client.responses.create(
model="gpt-5",
input=messages
)
print(response.output_text)
요약(Summarization)
긴 문장을 핵심만 추려 짧게 요약하는 태스크입니다. 회의록, 뉴스기사, 리포트 등에서 자주 사용됩니다.
① 메시지 리스트 준비
# 요약할 텍스트 입력
messages = [
{
"role": "user",
"content": "다음 내용을 세 문장으로 요약해 주세요. \
오늘은 인공지능의 역사와 발전 단계를 학습했습니다. \
기계학습, 딥러닝, 자연어처리 기술이 AI의 핵심이었습니다. \
또한 AI의 사회적 영향에 대해서도 논의했습니다."
}
]
② 추론 실행 (Reasoning)
response = client.responses.create(
model="gpt-5",
input=messages
)
print(response.output_text)
번역(Translation)
텍스트를 한 언어에서 다른 언어로 변환하는 작업입니다. 예를 들어, 한국어를 영어로 또는 일본어로 번역할 수 있습니다.
① 메시지 리스트 준비
# 메시지 리스트 구성
messages = [
{
"role": "user",
"content": "다음 문장을 영어로 번역해 주세요. 나는 고양이다."
}
]
② 추론 실행 (Reasoning)
# 모델 실행
response = client.responses.create(
model="gpt-5",
input=messages
)
print(response.output_text)
코딩(Coding)
프로그래밍과 관련된 코드생성, 수정 또는 버그수정등의 작업입니다. 예를 들어, "Hello, World!"를 출력하는 Python코드를 작성하도록 요청할 수 있습니다.
① 메시지 리스트 준비
# 메시지 리스트 구성
messages = [
{
"role": "user",
"content": "‘Hello World!’라고 출력하는 Python 코드를 작성해 주세요."
}
]
② 추론 실행 (Reasoning)
# 모델 실행
response = client.responses.create(
model="gpt-5",
input=messages
)
print(response.output_text)
스트리밍(Streaming)
스트리밍은 텍스트 생성 시, 결과 전체가 한꺼번에 출력될 때까지 기다리는 대신, 생성 도중의 일부 텍스트(청크, chunk)를 순차적으로 받아 실시간으로 표시하는 기능입니다. 기존 방식에서는 완성된 문장이 모두 생성될 때까지 대기해야 했지만, 스트리밍을 사용하면 생성 중인 텍스트가 순차적으로 출력되어 대화형 인터페이스의 응답시간을 크게 단축할 수 있습니다. 예로 코드 생성이나 실시간 답변이 필요한 챗봇환경에서 매우 유용합니다.
① 메시지 리스트 준비
messages = [
{
"role": "developer",
"content": "질문에 대답하는 AI 어시스턴트를 만들어주세요."
},
{
"role": "user",
"content": "오늘 서울 날씨 어때?"
}
]
② 추론 실행 (Reasoning)
client.responses.create()의 stream옵션에 True를 지정하면 생성 중 발생하는 이벤트를 순서대로 반환하는 제너레이터(generator)객체가 만들어집니다. 이를 통해 for루프 등을 이용해 이벤트마다 응답을 실시간으로 처리할 수 있습니다.
# 추론 실행
stream = client.responses.create(
model="gpt-5",
input=messages,
stream=True, # 스트리밍 기능 활성화
)
# 스트리밍 방식으로 출력
for event in stream:
print(event)
이벤트 타입
이벤트 객체의 type속성을 통해 어떤 종류의 이벤트인지 확인할 수 있습니다.
주요 이벤트 타입은 다음과 같습니다.
response.created: 모델응답 생성을 시작할 때 발생
response.output_text.delta: 텍스트가 추가로 생성될 때 발생
response.completed: 응답 생성이 완료되었을 때 발생
response.error: 오류가 발생했을 때 발생
③ 텍스트차이(Delta)의 출력
스트리밍 방식에서 생성 중 텍스트를 바로 출력하려면 이벤트 타입이 response.output_text.delta일 때만 출력하도록 코드를 작성합니다.
# 추론 실행
stream = client.responses.create(
model="gpt-5",
input=messages,
stream=True, # 스트리밍 기능 활성화
)
# 스트리밍된 텍스트의 실시간 출력
for event in stream:
if event.type == "response.output_text.delta":
print(event.delta, end="", flush=True)
이렇게 하면 모델이 단어를 생성할 때마다 콘솔에 바로 출력되어 응답이 실시간으로 완성되는 과정을 확인할 수 있습니다.
Streaming - OpenAI API
https://platform.openai.com/docs/api-reference/responses-streaming
대화 상태 관리
기본적으로 Responses API는 각 요청을 독립된 세션으로 처리합니다. 즉, 별다른 설정이 없으면 모델은 과거 대화 내용을 기억하지 않습니다. 따라서 여러 턴(turn)의 대화를 구현하려면 직접 대화 히스토리를 관리해야 합니다.
① 메시지 리스트 준비
아래는 과거 대화를 포함한 메시지리스트 예시입니다.
# 메시지 리스트 구성 (대화 히스토리 포함)
messages = [
{"role": "user", "content": "한국에서 가장 높은 산은 무엇입니까?"},
{"role": "assistant", "content": "한국에서 가장 높은 산은 한라산(1950m)입니다."},
{"role": "user", "content": "그 산의 위치를 알려주세요."},
]
② 추론 실행 (Reasoning)
response = client.responses.create(
model="gpt-5",
input=messages
)
print(response.output_text)
이 방식으로 이전 대화를 모두 메시지리스트에 포함시키면, 모델은 맥락(context)을 유지한 자연스러운 대화를 이어갈 수 있습니다.
previous_response_id로 대화이력 자동 이어받기
previous_response_id는 "이전 응답을 이어서 대화를 계속하기 위한 고유 식별자"입니다. 이를 사용하면 앞서 주고받은 대화의 문맥을 자동으로 이어받을 수 있으므로, 이전 메시지를 다시 전달할 필요가 없습니다.
① 첫번째 추론실행
# 첫 번째 추론 실행
response = client.responses.create(
model="gpt-5",
input=[{"role": "user", "content": "한국에서 가장 높은 산은 무엇인가요?"}],
)
print(response.output_text)
② previous_response_id로 대화 이어서 추론하기
# previous_response_id로 이전 대화 문맥을 이어받아 추론
second_response = client.responses.create(
model="gpt-5",
previous_response_id=response.id,
input=[{"role": "user", "content": "그 산은 어디에 있나요?"}],
)
print(second_response.output_text)
이처럼 previous_response_id를 활용하면, 매번 전체 대화 내역을 다시 전달하지 않아도 문맥이 자연스럽게 이어집니다. 또한, Reasoning모델이나 멀티턴 대화에서도 이 기능을 사용하면 대화의 응집력과 일관성을 유지할 수 있습니다.
구조화된 출력(Structured Output)
구조화된 출력은 모델이 생성하는 응답을 JSON 스키마형식에 따라 일관된 데이터 형태로 반환하도록 설정하는 기능입니다. 이 기능을 활용하면 모델이 텍스트가 아닌 정확한 JSON 객체를 직접 생성하도록 지시할 수 있어, 이후 프로그램에서 데이터를 자동으로 파싱하기 쉽습니다.
OpenAI API지원 스키마 목록: https://platform.openai.com/docs/guides/structured-outputs#supported-schemas
① 메시지 리스트 준비
# 메시지 리스트 구성
messages = [
{"role": "developer", "content": "이벤트 정보를 JSON 형식으로 출력하세요."},
{"role": "user", "content": "홍길동과 김구의 회의 일정을 캘린더에 추가해주세요."}
]
② JSON 스키마 준비
아래는 JSON으로 회의 일정을 출력하기 위한 예시 스키마입니다.
name (string), date (string), participants (array) 항목을 갖는 구조를 정의했습니다.
# JSON 스키마 정의
schema = {
"format": {
"type": "json_schema",
"name": "calendar_event",
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"date": {"type": "string"},
"participants": {"type": "array", "items": {"type": "string"}}
},
"required": ["name", "date", "participants"],
"additionalProperties": False
},
"strict": True
}
}
③ 추론 실행
client.responses.create()함수의 text인자에 JSON스키마를 지정합니다. 이렇게 하면 모델이 반드시 해당 구조에 맞는 JSON데이터를 생성하게 됩니다.
# 추론 실행
response = client.responses.create(
model="gpt-5",
input=messages,
text=schema
)
print(response.output_text)
프롬프트 캐시(Prompt Cache)
프롬프트 캐시는 최근 사용한 입력토큰을 재활용하여 API요청 속도를 높이고 비용을 절감하는 기능입니다. 개발 중 반복 테스트를 수행할 때, 동일한 입력 텍스트를 여러번 사용할 경우 특히 유용합니다. 이 기능은 OpenAI 모델의 응답대기시간(latency)을 줄이는데 도움을 주며, 반복적인 분석이나 검증을 수행할 때도 활용할 수 있습니다.
프롬프트 캐시는 128토큰 단위로 자동 저장되며, 동일한 프롬프트를 다시 보낼 경우 자동으로 캐시된 데이터를 재사용합니다. 결과적으로 약 50~60%의 처리속도 개선이 가능합니다.
① 참조용 텍스트 준비
여기서는 1024토큰 규모의 텍스트 파일을 예시로 사용합니다. Colab환경에 업로드한 뒤 아래 코드로 파일내용을 읽어옵니다.
# 참조 텍스트 파일 읽기
with open("LittleRedRidingHood.txt", "r", encoding="utf-8") as file:
target_text = file.read()
print(target_text)
② 메시지 리스트 준비
messages = [
{
"role": "developer",
"content": [{"type": "input_text", "text": target_text}]
},
{
"role": "user",
"content": [{"type": "input_text", "text": "질문: 주인공의 이름이 뭐야?"}]
}
]
③ 추론 실행
prompt_cache_key를 지정하면 이 키를 기반으로 입력 프롬프트가 캐시(저장)되어 다음 요청시 재사용됩니다. 즉, 동일한 입력 내용을 반복 실행할 때, 속도가 빨라지고 토큰 사용량이 줄어듭니다.
2025년 10월 기준으로 GPT-5부터 이 기능이 지원됩니다. 아래 예시는 prompt_cache_key를 "my-cache-key-123"으로 지정했습니다.
# 추론 실행
response = client.responses.create(
model="gpt-5",
input=messages, # 메시지 리스트
prompt_cache_key="my-cache-key-123" # 프롬프트 캐시 키
)
print(response.output_text)
토큰수 확인
아래 코드는 입력/출력/총 토큰 수를 확인하는 예시입니다. 특히 cached_tokens는 캐시에서 재사용된 토큰수를 의미합니다.
print("입력 토큰 수:", response.usage.input_tokens)
print("캐시된 토큰 수:", response.usage.input_tokens_details.cached_tokens)
print("출력 토큰 수:", response.usage.output_tokens)
print("총 토큰 수:", response.usage.total_tokens)
④ 메시지 리스트 준비(후속요청용)
앞서 사용한 메시지와 동일한 prompt_cache_key를 유지한 상태에서 새로운 대화 내용을 추가할 수도 있습니다. 아래는 이전 텍스트를 유지하면서 다른 질문을 던지는 예시입니다.
messages = [
{
"role": "developer",
"content": [{"type": "input_text", "text": target_text}]
},
{
"role": "user",
"content": [{"type": "input_text", "text": "이번엔 주제와 결말을 요약해줘."}]
}
]
이 프롬프트 캐시 기능을 활용하면 대규모 텍스트를 반복처리하는 프로젝트(문서분석, 소설요약, 데이터검증 등)에서 API응답 속도를 크게 단축시킬 수 있습니다.
⑤ 추론 실행
response.usage.input_tokens_details.cached_tokens를 사용하면 캐시된(재사용된) 토큰수를 확인할 수 있습니다.
# 추론 실행
response = client.responses.create(
model="gpt-5", # 모델 ID
input=messages, # 메시지 리스트
prompt_cache_key="my-cache-key-123" # 프롬프트 캐시 키
)
print(response.output_text)
토큰 수 확인
아래 코드는 입력/출력/총 토큰 수를 출력하며, 특히 cached_tokens값이 캐시에서 재사용된 토큰 갯수를 나타냅니다.
print("입력 토큰 수:", response.usage.input_tokens)
print("캐시된 토큰 수:", response.usage.input_tokens_details.cached_tokens)
print("출력 토큰 수:", response.usage.output_tokens)
print("총 토큰 수:", response.usage.total_tokens)
이처럼 이전에 사용했던 프롬프트 일부가 캐시로 재활용되어 불필요한 토큰 계산이 줄어든 것을 확인할 수 있습니다. 대규모 텍스트를 다루는 프로젝트에서 상당한 비용절감 효과를 가져옵니다.
[참고] Completions API와 Chat Completions API, Responses API
OpenAI의 텍스트 생성 API는 Completions API → Chat Completions API → Responses API순으로 발전해왔습니다.
Completions API는 초창기 모델과 직접 텍스트를 주고받는 구조였습니다.
Chat Completions API는 2023년 3월에 도입되어 '역할(role) + 메시지(message)'형태의 대화 구조를 채택했습니다. GPT모델 중 97%이상이 이 형식으로 이전되었습니다.
2025년 현재, OpenAI는 이를 통합한 새로운 방식의 Responses API를 제공하고 있습니다.
이 Responses API는 단순한 채팅 응답뿐 아니라, 이미지, 음성, 데이터분석 등 다양한 생성 기능을 하나의 엔드포인트에서 처리할 수 있습니다.
이 강좌의 코드 예시는 모두 최신 Responses API를 기반으로 작성되어 있습니다.
관련 Colab노트북: https://colab.research.google.com/drive/1-sOKei4AzuQFVPuA3x3IpAcYfyXQaLSg?usp=sharing
©2024-2025 MDRULES.dev, Hand-crafted & made with Jaewoo Kim.
이메일문의: jaewoo@mdrules.dev
AI 에이전트 개발, 컨텍스트 엔지니어링 교육 컨설팅, 바이브코딩 강의 문의: https://bit.ly/4kjk5OB
- 01 1. GPT-5란?
- 02 2. Python 개발환경 준비
- 최신글 03 3. 텍스트 생성(Text Generation)
- 04 4화가 곧 발행될 예정입니다. 2025년 12월 17일 수요일 발행 예정
