---
ai_assisted: true
title: "GPT-5 Responses API 웹 검색 도구 실험"
description: "GPT-5 Responses API 웹 검색 도구의 모델별 동작"
pubDate: 2026-05-16T03:43:29+09:00
category: "AI"
subcategory: "Model"
tags: ["AI", "GPT-5", "API", "web search", "OpenAI", "tutorial"]
published: true
---

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

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

## 실험 환경 구성

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

```python
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를 호출했다. 정상 작동했다.

```python
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 파라미터
웹 검색 도구는 다음과 같은 형식의 딕셔너리 배열로 지정된다.
```python
tools=[{"type": "web_search", "search_context_size": "medium"}]
```
type 필드는 사용할 도구의 종류를 지정하며 "web_search" 값을 가지고, search_context_size는 검색 시 참조할 컨텍스트의 범위를 결정하는데 small, medium, large의 세 가지 옵션이 존재한다.

### text 파라미터
응답 텍스트의 상세도를 제어하는 파라미터로, verbosity 필드로 low, medium, high 중 하나의 값을 설정할 수 있다.
```python
text={"verbosity": "medium"}
```
실험에서는 medium 값을 썼는데, 너무 짧지도 너무 장황하지도 않은 균형 잡힌 응답이 나왔다.

### reasoning 파라미터
모델이 응답을 생성하는 과정에서 투입하는 추론 노력의 정도를 조절하는 파라미터이다.
```python
reasoning={"effort": "medium"}
```
effort 필드는 low, medium, high 중 하나다. 값이 높을수록 추론 과정이 길어져 응답 생성 시간도 늘어난다.

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

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

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