GPT-5 Responses API 웹 검색 도구 실험

OpenAI가 제공하는 GPT-5 모델의 Responses API에는 웹 검색 기능이 내장돼 있다. 다만 이 기능을 켜려면 특정 모델 식별자와 파라미터 구성이 필요하다는 사실을 실험으로 확인했다. 본 문서는 Google Colab 환경에서 수행한 API 호출 실험을 정리해, 모델명 선택에 따른 웹 검색 도구 사용 여부와 각 파라미터가 응답 생성에 미치는 영향을 기록했다.

실험 환경 구성

실험은 OpenAI Python 라이브러리로 진행했고, Google Colab의 userdata 기능으로 API 키를 환경 변수에 심어 인증했다.

import os
from google.colab import userdata
os.environ['OPENAI_API_KEY'] = userdata.get('OPENAI_API_KEY')

from openai import OpenAI
client = OpenAI()

이렇게 하면 API 키를 코드에 노출하지 않고 안전하게 관리할 수 있다. Colab에서 실험을 반복하기에도 효율이 좋았다.

GPT-5 모델을 사용한 웹 검색 실험

첫 번째 실험은 모델 식별자를 "gpt-5"로 지정하고 웹 검색 도구를 켠 상태로 API를 호출했다. 정상 작동했다.

response = client.responses.create(
  model="gpt-5",
  input=[{"role": "user", "content": "한국의 대표적인 DB 모니터링 솔루션 업체는?"}],
  tools=[{"type": "web_search", "search_context_size": "medium"}],
  text={"verbosity": "medium"},
  reasoning={"effort": "medium"},
)

print(response.output_text)

API 호출 결과는 다음처럼 업체명과 제품 정보까지 담아 돌아왔다.

대표적으로 아래 업체들이 많이 쓰입니다:
- 엑셈(Exem) – MaxGauge(맥스게이지)로 잘 알려진 DB 성능/모니터링 전문 솔루션을 제공. 클라우드 DB 통합 모니터링 제품도 보유.
- 셀파소프트 – Sherpa for Oracle/HANA 등 DB 성능 모니터링·사후 분석 솔루션 제공.
- 티맥스티베로(TmaxTibero) – 자사 DBMS용 성능 모니터링 솔루션 SysMasterDB 제공.
- 웨어밸리(Warevalley) – Orange 제품군으로 DB 운영·개발·성능 관리와 실시간 모니터링 기능 제공.

특정 DBMS나 환경(온프레미스/클라우드, Oracle·PostgreSQL 등)에 따라 권장 솔루션이 달라집니다.

모델이 웹 검색으로 실시간 정보를 끌어와 응답을 만들었다는 뜻이다. 학습된 지식에만 기대지 않고 최신 정보까지 참조한다는 얘기다.

파라미터 구성 방식 분석

실험에서 쓴 파라미터는 저마다 다른 방식으로 API 응답의 성격에 관여한다. 구성은 다음과 같다.

model 파라미터

"gpt-5"라는 식별자는 웹 검색 도구와 호환되는 API 전용 모델을 가리키고, 이 값이 있어야 웹 검색 기능을 쓸 수 있다.

tools 파라미터

웹 검색 도구는 다음과 같은 형식의 딕셔너리 배열로 지정된다.

tools=[{"type": "web_search", "search_context_size": "medium"}]

type 필드는 사용할 도구의 종류를 지정하며 "web_search" 값을 가지고, search_context_size는 검색 시 참조할 컨텍스트의 범위를 결정하는데 small, medium, large의 세 가지 옵션이 존재한다.

text 파라미터

응답 텍스트의 상세도를 제어하는 파라미터로, verbosity 필드로 low, medium, high 중 하나의 값을 설정할 수 있다.

text={"verbosity": "medium"}

실험에서는 medium 값을 썼는데, 너무 짧지도 너무 장황하지도 않은 균형 잡힌 응답이 나왔다.

reasoning 파라미터

모델이 응답을 생성하는 과정에서 투입하는 추론 노력의 정도를 조절하는 파라미터이다.

reasoning={"effort": "medium"}

effort 필드는 low, medium, high 중 하나다. 값이 높을수록 추론 과정이 길어져 응답 생성 시간도 늘어난다.

gpt-5-chat-latest 모델 실험과 오류 분석

두 번째 실험은 모델 식별자를 "gpt-5-chat-latest"로 바꾸고 같은 웹 검색 도구 구성으로 API를 호출했다. 결과는 예상과 달랐다.

response = client.responses.create(
  model="gpt-5-chat-latest",
  input=[{"role": "user", "content": "한국의 대표적인 DB 모니터링 솔루션 업체는?"}],
  tools=[{"type": "web_search", "search_context_size": "medium"}],
  text={"verbosity": "medium"},
  reasoning={"effort": "medium"},
)

이 API 호출은 실패했고, 다음 BadRequestError를 돌려줬다.

BadRequestError: Error code: 400 - {'error': {'message': "Hosted tool 'web_search_preview' is not supported with gpt-5-chat-latest.", 'type': 'invalid_request_error', 'param': 'tools', 'code': None}}

오류 메시지를 뜯어보면, gpt-5-chat-latest 모델은 web_search_preview라는 내부 식별자의 웹 검색 도구를 받아들이지 않는다. 파라미터 설정 문제로 보기는 어렵고, 모델 자체의 제약으로 봐야 한다. gpt-5-chat-latest는 ChatGPT 서비스가 쓰는 것과 같은 모델로 추정되며, API에서의 도구 호출 방식이 채팅 인터페이스와 다르게 짜여 있는 듯하다.

모델 간 기능 비교 결과

실험으로 확인한 두 모델의 차이는 다음과 같다.

모델명	웹 검색 도구 지원	주요 특징
gpt-5	지원됨	API 사용을 위해 설계된 모델로, 웹 검색 도구와의 완전한 호환성을 가짐
gpt-5-chat-latest	지원되지 않음	ChatGPT 서비스의 모델과 동일하며, API 환경에서 웹 검색 도구 사용 시 오류 발생

어떤 모델을 고르느냐에 따라 성능뿐 아니라 쓸 수 있는 기능의 범위까지 달라진다.

파라미터 변화에 따른 관찰 결과

search_context_size 파라미터는 검색 시 참조할 정보의 양을 정한다. small은 제한된 범위의 검색 결과를, medium은 중간 수준의 정보를, large는 광범위한 컨텍스트를 참조한다. 단순 사실 확인 질의에는 small이면 충분했지만, 여러 갈래의 정보를 요구하는 질의에서는 medium 이상이 더 폭넓은 답을 내놓았다.

verbosity 파라미터의 경우 low는 핵심 정보만 간결히 내놓았고, high는 배경 설명과 부연 정보까지 붙인 상세한 응답을 만들었다. medium은 두 극단 사이에서 균형을 잡아, 대부분 실험에서 적당한 정보 밀도를 유지했다.

reasoning effort 파라미터의 영향은 verbosity만큼 뚜렷하지 않았다. 단, high에서는 응답 생성 시간이 늘었고, 복잡한 추론이 필요한 질의에서 더 짜임새 있는 답이 나왔다. low는 빠른 응답을 앞세우며, 단순 정보 검색에서는 medium과 큰 차이가 없었다.

실험에서 발견한 사실

본 실험에서 GPT-5 Responses API의 웹 검색 기능은 모델 식별자에 따라 사용 여부가 갈리고, gpt-5 모델만 이 기능을 온전히 지원한다는 사실을 확인했다. gpt-5-chat-latest는 ChatGPT 인터페이스와 일관성을 맞추도록 설계된 듯한데, API에서 호스팅되는 도구와의 통합이 제한돼 있음을 알 수 있었다.

파라미터 구성은 응답의 성격을 세밀히 조정할 통로를 열어주지만, 각 파라미터가 실제 응답 생성에 미치는 영향의 정확한 메커니즘은 여전히 불투명하다. search_context_size, verbosity, reasoning effort의 상호작용이 최종 응답 품질에 어떻게 작용하는지는 앞으로 더 짜임새 있는 실험이 필요한 영역이다.

웹 검색 도구를 쓰는 API 호출은 학습 데이터에만 기대는 기존 언어 모델과 질적으로 다른 응답 패턴을 낸다. 실시간 정보가 필요한 애플리케이션을 만들 때 유용한 기능이다. 모델에 따라 기능 가용성이 곧장 결정되는 만큼, 개발 초기에 알맞은 모델 식별자를 고르는 것이 중요하다는 사실을 이번 실험으로 확인했다.