OpenAI Web Search

Responses 또는 Chat 엔드포인트로 웹을 검색하고 출처 인용을 처리합니다.

OpenAI Web Search는 해당 기능을 지원하는 모델이 답변 전에 웹을 검색하고 텍스트, 검색 호출 및 출처 인용을 응답으로 반환하도록 합니다. 뉴스, 날씨, 제품 업데이트 및 최신성이 중요한 쿼리에 적합합니다.

자체 데이터베이스나 업무 서비스의 데이터라면 내부 데이터를 공개 웹 검색에 전달하지 않고 Tool Calling으로 통제된 도구를 정의해야 합니다.

모델과 엔드포인트를 먼저 확인합니다

프로토콜에 Web Search 필드가 있어도 현재 계정의 모든 모델이 검색을 지원하는 것은 아닙니다. 먼저 모델 목록에서 모델과 프로토콜을 확인한 후 해당 API 레퍼런스를 참고합니다.

Responses 또는 Chat 선택

엔드포인트	활성화 방법	결과 위치
Responses	`tools`에 Web Search Tool 추가	`web_search_call` 및 Message Output Item
Chat Completions	`web_search_options` 사용	Assistant Message 및 `annotations`

Responses는 검색 호출, 답변 및 출처를 구분해야 하는 애플리케이션에 더 적합하고, Chat은 이미 메시지 구조를 사용하는 프로젝트에 적합합니다.

Responses로 웹 검색

curl 'https://api.agtcloud.cn/v1/responses' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "tools": [
      {
        "type": "web_search_preview",
        "search_context_size": "medium"
      }
    ],
    "input": "오늘 주목할 만한 기술 뉴스는 무엇인가요?"
  }'

모델은 질문에 따라 검색 여부를 결정할 수 있습니다. 검색이 수행되면 응답의 output에는 일반적으로 검색 호출 항목과 텍스트 메시지 항목이 함께 포함됩니다. 전체 Tool 타입은 Responses Reference를 확인합니다.

Chat Completions 사용

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "오늘 주목할 만한 기술 뉴스는 무엇인가요?"
      }
    ],
    "web_search_options": {
      "search_context_size": "medium"
    }
  }'

Chat 응답의 본문은 choices[].message.content에 있고, 응답이 구조화된 인용을 제공하면 choices[].message.annotations에 있습니다. 전체 필드는 Chat Completions Reference를 확인합니다.

답변 및 인용 읽기

{
  "output": [
    {
      "type": "web_search_call",
      "id": "ws_example",
      "status": "completed"
    },
    {
      "type": "message",
      "content": [
        {
          "type": "output_text",
          "text": "검색 결과에 따르면…",
          "annotations": [
            {
              "type": "url_citation",
              "url": "https://example.com/article",
              "title": "출처 제목"
            }
          ]
        }
      ]
    }
  ]
}

답변 텍스트만 저장해서는 안 됩니다. URL, 제목 및 인용과 텍스트 위치의 연결 관계를 보관하고 화면에 클릭 가능한 출처를 제공하며, 외부 링크에 안전한 새 탭 속성을 적용해야 합니다.

검색 범위 제한

모델과 엔드포인트가 지원하면 다음 검색 조건을 설정할 수 있습니다:

도메인 범위: 허용된 사이트에서만 검색하며 의료, 법규 또는 기업 지식 출처에 적합합니다.
사용자 위치: 국가, 도시, 지역 또는 시간대를 제공하여 지역에 맞는 결과를 얻습니다.
검색 컨텍스트 규모: 응답 품질, 지연 시간 및 사용량을 고려하여 적절한 범위를 선택합니다.
출처 목록: Responses는 지원되는 경우 본문에 최종 인용된 출처 외에도 검색 중 확인한 출처를 반환할 수 있습니다.

이 필드들의 위치는 Responses와 Chat에서 다르며 구체적인 이름과 제한은 해당 레퍼런스를 기준으로 합니다.

실패 및 대체 처리

현상	처리 방법
검색이 실행되지 않음	질문에 실시간 정보가 필요한지 판단하고 모델의 검색 지원을 확인합니다
답변은 있지만 인용이 없음	출처를 만들어내지 않고 표시할 인용이 반환되지 않았음을 알립니다
검색 실패	응답 오류에 따라 재시도, 검색 없는 답변 또는 나중에 다시 시도하도록 안내합니다
출처 간 상충	여러 출처와 갱신 시간을 표시하며 모델이 중요한 차이를 숨기도록 하지 않습니다
출처에 접근할 수 없음	제목과 원본 URL을 유지하고 현재 페이지를 열 수 없음을 알립니다

외부 웹페이지에는 잘못된 정보나 모델을 대상으로 한 악성 지시가 있을 수 있습니다. 검색 결과라는 이유로 자동으로 신뢰하거나 애플리케이션 권한을 우회하고 위험도가 높은 도구를 실행하도록 해서는 안 됩니다.

운영 전 확인 사항

모델과 프로토콜이 Web Search를 명시적으로 지원합니다.
답변, 검색 호출, 인용 및 출처 목록을 각각 해석합니다.
인용이 없을 때 가짜 링크를 생성하지 않습니다.
도메인과 위치 정보는 업무에 필요할 때만 보냅니다.
외부 콘텐츠가 Tool Calling의 권한 및 확인 절차를 우회하지 않습니다.
검색 실패, 시간 초과 및 결과 없음에 명확한 대체 처리가 있습니다.

요청이 실패하면 오류 및 문제 해결을 참고하고, 프로토콜 변경 전에 프로토콜 선택을 확인합니다.