OpenAI Web Search API 소개

1. 글을 작성하게 된 계기

최근 4일 전 OpenAI에서 BUILT-IN TOOLS라는 새로운 기능을 소개했었다.



나는 그중에서도 Web search 기능을 좀 더 자세하게 알아보고

기존의 gpt-4o 나 gpt-4o-mini 모델과의 가격을 비교해보려고 한다. 



그리고 Responses라는 개념이 나오게 되었는데 Chat Completions와 어떻게 다른지 살펴보자.

2. OpenAI Web Search API 소개

Web Search API를 제공하는 모델은 2가지이다.

- gpt-4o-search-preview
- gpt-4o-mini-search-preview

사용방법은 아래와 같다.

from openai import OpenAI
client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-4o-search-preview",
    web_search_options={},
    messages=[
        {
            "role": "user",
            "content": "What was a positive news story from today?",
        }
    ],
)

print(completion.choices[0].message.content)

# 예시결과

[
  {
    "type": "web_search_call",
    "id": "ws_67c9fa0502748190b7dd390736892e100be649c1a5ff9609",
    "status": "completed"
  },
  {
    "id": "msg_67c9fa077e288190af08fdffda2e34f20be649c1a5ff9609",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "On March 6, 2025, several news...",
        "annotations": [
          {
            "type": "url_citation",
            "start_index": 2606,
            "end_index": 2758,
            "url": "https://...",
            "title": "Title..."
          }
        ]
      }
    ]
  }
]

• 웹 검색 활성화:
  • Responses API에서 tools 배열에 web_search_preview 추가하여 사용 가능
  • 모델이 자동으로 웹 검색을 수행할지 결정
• 웹 검색 강제 실행:
  • tool_choice 설정 {type: "web_search_preview"} 사용 가능
  • 더 낮은 지연 시간과 일관된 결과 제공
• 출력 및 인용:
  • web_search_call ID 포함
  • message.content[0].text에 결과 저장
  • message.content[0].annotations에 인용된 URL 포함
  • 인용된 출처(링크)는 UI에서 명확하고 클릭 가능해야 함
• 사용자 위치 지정:
  • user_location 매개변수 사용
  • 국가(ISO 코드), 도시, 지역, 시간대(IANA 표준) 설정 가능
• 검색 컨텍스트 크기 조절 (search_context_size):
  • high: 가장 풍부한 정보, 높은 비용, 느린 응답
  • medium (기본값): 균형 잡힌 성능
  • low: 빠른 응답, 낮은 비용, 제한된 정보
• 제한 사항:
  • 데이터 보존 및 거주 제한 없음
  • gpt-4o-search-preview 및 gpt-4o-mini-search-preview 모델은 일부 API 매개변수만 지원
  • Responses API에서 웹 검색 도구는 모델과 동일한 계층적 속도 제한 적용

3. 기존 모델과의 가격 비교

기존의 모델은 1M 토큰으로 했다면

web search의 경우에는 요청에 따라 비용을 부가하는 형태이다.

현재 나와있는 요금의 경우에는 천 번 요청했을 때의 가격이 나와있다.

https://platform.openai.com/docs/pricing#web-search

 

https://platform.openai.com/docs/pricing#web-search

4. Responses vs. Chat Completions

Responses API와 Chat Completions API 두 개 모두 OpenAI의 모델에서 사용할 수 있는 방법이다.

이번에 새로 나온 Responses API는 Chat Completions 보다 에이전트적인 작업을 수행할 수 있다고 설명하며,

추후 모델이 발전됨에 따라 Responses API가 기반이 된다고 설명한다.



그래서 혹시 이제 개발을 시작하거나 프로덕트를 고려하는 새로운 사용자라면

처음부터 Responses API를 만드는 것을 추천한다고 말하고 있다.



그럼 이제 Completeions API는 끝?

아니다. 그래도 Completions API는 계속 지원한다고 한다.

Chat Completions API는 업계 표준으로 사용되며 OpenAI에서도 계속 지원한다고 말하고 있다.



그럼 왜 Responses API를 써야 돼?

상태 관리가 쉽다고 말하고 있다.

# Chat Completions API

from openai import OpenAI
client = OpenAI()

completion = client.chat.completions.create(
  model="gpt-4o",
  messages=[
      {
          "role": "user",
          "content": "Write a one-sentence bedtime story about a unicorn."
      }
  ]
)

print(completion.choices[0].message.content)

# Responses API

from openai import OpenAI
client = OpenAI()

response = client.responses.create(
  model="gpt-4o",
  input=[
      {
          "role": "user",
          "content": "Write a one-sentence bedtime story about a unicorn."
      }
  ]
)

print(response.output_text)

코드만 봐도 다르며 output 아래와 같이 다른 형태를 보인다.

• 출력 형식: Responses API는 output을 반환, Chat Completions API는 choices 배열을 반환
• 구조화 출력: Responses API에서는 text.format 사용 (response_format 대신)
• 함수 호출 차이: 요청 및 응답 형식이 다름 (자세한 내용은 함수 호출 가이드 참고)
• 추론 설정: reasoning.effort 사용 (Chat Completions의 reasoning_effort와 차이)
• SDK 차이: Responses SDK에는 output_text 헬퍼 있음 (Chat Completions SDK에는 없음)
• 대화 상태 관리: Responses는 previous_response_id 제공, Chat Completions은 직접 관리 필요
• 응답 저장: Responses는 기본 저장, Chat Completions은 신규 계정에서 기본 저장 (비활성화는 store: false)

자세한 내용은 아래 있는 출처를 참고하자.

참고로: previous_response_id는 opeani api가 달라도 유효하며 사용했을 때 계속해서 input token이 늘어나는 것 같은데 이걸 어떻게 효과적으로 줄일지는 고민해야 될 것 같다.그런 점에서는 Chat Completions로 그때그때 히스토리를 추가하는 게 좋을 것 같기도 한데..

# Chat Completions API

[
  {
      "index": 0,
      "message": {
          "role": "assistant",
          "content": "Under the soft glow of the moon, Luna the unicorn danced through fields of twinkling stardust, leaving trails of dreams for every child asleep.",
          "refusal": null
      },
      "logprobs": null,
      "finish_reason": "stop"
  }
]

# Responses API

[
  {
      "id": "msg_67b73f697ba4819183a15cc17d011509",
      "type": "message",
      "role": "assistant",
      "content": [
          {
              "type": "output_text",
              "text": "Under the soft glow of the moon, Luna the unicorn danced through fields of twinkling stardust, leaving trails of dreams for every child asleep.",
              "annotations": []
          }
      ]
  }
]

5. 출처

 

 

https://platform.openai.com/docs/pricing#web-search

https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat