OpenAI Web Search 툴 활용 가이드

OpenAI 모델의 웹 검색 방식

OpenAI 모델에서는 세 가지 방식으로 웹 검색 기능을 제공합니다. 빠른 정보를 원할 때는 간단히 검색 결과만 전달받는 '비추론형' 검색을 이용할 수 있고, 복잡한 정보 탐색이 필요할 때는 모델이 자체적으로 검색을 관리하고 결과를 분석하는 '에이전트 기반(reasoning)' 검색을 사용할 수 있습니다. 깊이 있는 연구가 필요하다면 수백 개의 출처를 분석하는 '딥 리서치' 모드도 지원됩니다.

웹 검색 연동하는 방법

API를 통해 웹 검색 툴을 모델 요청에 포함하면 됩니다. 다음과 같이 설정할 수 있습니다:

from openai import OpenAI
client = OpenAI()
response = client.responses.create(
  model="gpt-5",
  tools=[{"type": "web_search"}],
  input="오늘의 긍정적인 뉴스 알려줘"
)
print(response.output_text)

JavaScript와 curl, C# 환경에서도 유사한 방식으로 연동할 수 있습니다.

검색 결과와 출처 표시

웹 검색을 통해 얻는 응답에는 '검색 실행 내역'과 실제 답변이 함께 포함됩니다. 답변 부에는 정보의 출처(URL, 제목, 위치 등)가 주석(annotation)으로 붙어서, 사용자에게 명확히 어떤 정보가 인용됐는지 알려줍니다. 이러한 인용 링크는 서비스 화면에서도 눈에 띄게, 그리고 클릭할 수 있게 제공하는 것이 필수입니다.

도메인 필터 기능

특정 도메인이나 기관(예: WHO, FDA) 사이트만 검색하고 싶을 때는 '도메인 필터'를 사용할 수 있습니다. API 요청 시 최대 20개까지 허용 도메인을 넣고, 프로토콜(https://)은 빼고 적으면 됩니다.

# 주요 의료기관만 검색 예시
tools=[{
  "type": "web_search",
  "filters": {
    "allowed_domains": [
      "pubmed.ncbi.nlm.nih.gov", "clinicaltrials.gov", "www.who.int"
    ]
  }
}]

전체 검색 소스 열람하기

일반적으로 모델은 가장 적합한 몇 개 출처만 인라인 인용하지만, 더 많은 참고 URL 전체 목록을 보고 싶다면 sources 필드를 요청에 포함하세요. 실시간 스포츠, 날씨, 금융 등 외부 피드(예: oai-sports)도 별도로 표시됩니다.

지역 기반 검색 결과 최적화

사용자 위치에 따라 더 맞춤형 정보를 제공할 수 있습니다. API 요청에 국가, 도시, 지역, 타임존을 적어주면 검색 결과가 지리적으로 최적화되어 나옵니다. 특히 지역 서비스 추천 등에 유용하게 활용할 수 있습니다.

tools=[{
  "type": "web_search",
  "user_location": {
    "type": "approximate",
    "country": "KR",
    "city": "Seoul",
    "region": "Seoul"
  }
}]

지원 모델 및 제한사항

웹 검색 기능은 Responses API 및 일부 특화된 모델(gpt-4o-search-preview, gpt-5 등)에서 제공되지만, 모든 모델에서 가능한 것은 아닙니다. 예를 들어, gpt-5의 '최소 추론' 모드 등 일부 환경에서는 지원되지 않습니다. 각 모델별 요금제나 문맥 길이 제한도 참고해야 합니다.

운영 및 UI 주의점

웹에서 얻은 정보를 사용자에게 제공할 때는 반드시 인용 URL을 명확하게, 사용자가 클릭해 직접 확인할 수 있게 제공해야 한다는 점을 기억하세요.

활용 팁

스타트업 서비스에 최신 정보, 지역 맞춤 서비스, 권위기관 정보만을 안전하게 제공하고 싶을 때 OpenAI의 웹 검색 툴은 손쉽게 확장 가능한 옵션이 될 수 있습니다. 코드 및 필터링 설정만 수정하면 원하는 대로 결과를 받을 수 있어, 빠른 서비스 개선에도 도움이 됩니다.

출처 및 참고 : Web search - OpenAI API