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 호출은 학습 데이터에만 의존하는 기존의 언어 모델과는 질적으로 다른 응답 패턴을 보이며, 실시간 정보를 요구하는 애플리케이션 구축에 있어 유용한 기능으로 판단된다. 다만 모델 선택이 기능 가용성에 직접적인 영향을 미치므로, 개발 초기 단계에서 적절한 모델 식별자를 선택하는 것이 중요하다는 점을 이번 실험을 통해 확인할 수 있었다.