웹 검색

웹 검색 (Web Search)

litellm과 함께 웹 검색을 사용해요.

기능	상세
지원 엔드포인트	- /chat/completions - /responses - /images/generations (Gemini 이미지 모델 전용)
지원 프로바이더	`openai`, `xai`, `vertex_ai`, `anthropic`, `gemini`, `perplexity`
LiteLLM 비용 추적	✅ 지원
LiteLLM 버전	v1.71.0+

어떤 검색 엔진이 사용되나?

각 프로바이더는 자체 검색 백엔드를 사용합니다:

프로바이더	검색 엔진	비고
OpenAI (`gpt-5-search-api`, `gpt-4o-search-preview`, `gpt-4o-mini-search-preview`)	OpenAI의 내부 검색	실시간 웹 데이터
xAI (`grok-3`)	xAI의 검색 + X/Twitter	실시간 소셜 미디어 데이터
Google AI/Vertex (`gemini-2.0-flash`)	Google Search	실제 Google 검색 결과 사용
Anthropic (`claude-3-5-sonnet`)	Anthropic의 웹 검색	실시간 웹 데이터
Perplexity	Perplexity의 검색 엔진	AI 기반 검색 및 추론

web_search_options — OpenAI의 경우 전용 검색 모델만 web_search_options 파라미터를 지원합니다: gpt-4o-search-preview, gpt-4o-mini-search-preview, gpt-5-search-api. gpt-5.6-terra 나 gpt-5.6-luna 같은 일반 모델은 web_search_options 를 지원하지 않아요.

web_search_options — 검색 모델(예: gpt-4o-search-preview)은 web_search_options 파라미터 없이도 자동으로 웹을 검색합니다. 다음과 같은 경우 web_search_options 를 사용하세요: search_context_size("low", "medium", "high") 조정, 지역화된 결과를 위한 user_location 지정.

Anthropic 웹 검색 모델: 웹 검색을 지원하는 Claude 모델: claude-3-5-sonnet-latest, claude-3-5-sonnet-20241022, claude-3-5-haiku-latest, claude-3-5-haiku-20241022, claude-3-7-sonnet-20250219.

OpenAI 웹 검색: 두 가지 접근 방식

OpenAI는 엔드포인트와 모델에 따라 두 가지 방식의 웹 검색을 제공합니다:

접근 방식	엔드포인트	모델	활성화 방법
Search Models	`/chat/completions`	`gpt-5-search-api`, `gpt-4o-search-preview`, `gpt-4o-mini-search-preview`	`web_search_options` 파라미터 전달
Web Search Tool	`/responses`	`gpt-5`, `gpt-4.1`, `gpt-4o` 및 기타 일반 모델	`web_search_preview` 도구 전달

gpt-5-search-api 같은 검색 모델은 web_search_options 파라미터 없이도 자동으로 웹을 검색합니다. 지역화된 결과를 위해 search_context_size("low", "medium", "high")를 설정하거나 user_location 을 지정하려면 web_search_options 를 사용하세요.

출처: 문서

본문

/chat/completions (litellm.completion)

빠른 시작

SDK
PROXY

from litellm import completion

response = completion(
    model="openai/gpt-5-search-api",
    messages=[
        {
            "role": "user",
            "content": "What was a positive news story from today?",
        }
    ],
    web_search_options={
        "search_context_size": "medium"  # Options: "low", "medium", "high"
    }
)

config.yaml 설정

model_list:
  # OpenAI search models
  - model_name: gpt-5-search-api
    litellm_params:
      model: openai/gpt-5-search-api
      api_key: os.environ/OPENAI_API_KEY

  - model_name: gpt-4o-search-preview
    litellm_params:
      model: openai/gpt-4o-search-preview
      api_key: os.environ/OPENAI_API_KEY

  # xAI
  - model_name: grok-3
    litellm_params:
      model: xai/grok-3
      api_key: os.environ/XAI_API_KEY

  # Anthropic
  - model_name: claude-sonnet-5
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY

  # VertexAI
  - model_name: gemini-2-flash
    litellm_params:
      model: gemini-3.8-flash
      vertex_project: your-project-id
      vertex_location: us-central1

  # Google AI Studio
  - model_name: gemini-2-flash-studio
    litellm_params:
      model: gemini/gemini-3.8-flash
      api_key: os.environ/GOOGLE_API_KEY

프록시 시작

litellm --config /path/to/config.yaml

테스트!

from openai import OpenAI

# Point to your proxy server
client = OpenAI(
    api_key="sk-<your-litellm-api-key>",
    base_url="http://0.0.0.0:4000"
)

response = client.chat.completions.create(
    model="gpt-5-search-api",  # or any other web search enabled model
    messages=[
        {
            "role": "user",
            "content": "What was a positive news story from today?"
        }
    ],
    extra_body={
        "web_search_options": {
            "search_context_size": "medium"
        }
    }
)

검색 컨텍스트 크기

SDK
PROXY

# OpenAI (using web_search_options)
from litellm import completion
# Customize search context size
response = completion(
    model="openai/gpt-5-search-api",
    messages=[
        {"role": "user", "content": "What was a positive news story from today?",}
    ],
    web_search_options={
        "search_context_size": "low"  # Options: "low", "medium" (default), "high"
    }
)

# xAI (using web_search_options)
from litellm import completion
# Customize search context size for xAI
response = completion(
    model="xai/grok-3",
    messages=[
        {"role": "user", "content": "What was a positive news story from today?",}
    ],
    web_search_options={
        "search_context_size": "high"  # Options: "low", "medium" (default), "high"
    }
)

# Anthropic (using web_search_options)
from litellm import completion
# Customize search context size for Anthropic
response = completion(
    model="anthropic/claude-sonnet-5",
    messages=[
        {"role": "user", "content": "What was a positive news story from today?",}
    ],
    web_search_options={
        "search_context_size": "medium",  # Options: "low", "medium" (default), "high"
        "user_location": {
            "type": "approximate",
            "approximate": {
                "city": "San Francisco",
            },
        },
    }
)

# VertexAI/Gemini (using web_search_options)
from litellm import completion
# Customize search context size for Gemini
response = completion(
    model="gemini-3.8-flash",
    messages=[
        {"role": "user", "content": "What was a positive news story from today?",}
    ],
    web_search_options={
        "search_context_size": "low"  # Options: "low", "medium" (default), "high"
    }
)

# Gemini image generation (using web_search_options on /images/generations)
from litellm import image_generation
response = image_generation(
    model="gemini/gemini-3.1-flash-image-preview",
    prompt="Generate an image of the latest iPhone design",
    web_search_options={},
)

vertex_ai/gemini-3.1-flash-image-preview 및 다른 Gemini 이미지 모델에서 동작합니다.

PROXY 사용법:

from openai import OpenAI

# Point to your proxy server
client = OpenAI(
    api_key="sk-<your-litellm-api-key>",
    base_url="http://0.0.0.0:4000"
)

# Customize search context size
response = client.chat.completions.create(
    model="grok-3",  # works with any web search enabled model
    messages=[
        {
            "role": "user",
            "content": "What was a positive news story from today?"
        }
    ],
    web_search_options={
        "search_context_size": "low"  # Options: "low", "medium" (default), "high"
    }
)

/responses (litellm.responses)

gpt-5.6-terra, gpt-5.6-luna 같은 모델과 함께 web_search_preview 도구를 사용하세요.

검색 전용 모델(gpt-5-search-api, gpt-4o-search-preview)은 /responses 엔드포인트를 지원하지 않습니다. 대신 /chat/completions + web_search_options 와 함께 사용하세요 (위 참고).

빠른 시작

SDK
PROXY

from litellm import responses

response = responses(
    model="openai/gpt-5.6-terra",
    input="What is the capital of France?",
    tools=[{
        "type": "web_search_preview"  # enables web search with default medium context size
    }]
)

config.yaml 설정

model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEY

  - model_name: gpt-5.6-luna
    litellm_params:
      model: openai/gpt-5.6-luna
      api_key: os.environ/OPENAI_API_KEY

프록시 시작

litellm --config /path/to/config.yaml

테스트!

from openai import OpenAI

# Point to your proxy server
client = OpenAI(
    api_key="sk-<your-litellm-api-key>",
    base_url="http://0.0.0.0:4000"
)

response = client.responses.create(
    model="gpt-5.6-terra",
    tools=[{
        "type": "web_search_preview"
    }],
    input="What is the capital of France?",
)

print(response.output_text)

검색 컨텍스트 크기

SDK
PROXY

from litellm import responses

# Customize search context size
response = responses(
    model="openai/gpt-5.6-terra",
    input="What is the capital of France?",
    tools=[{
        "type": "web_search_preview",
        "search_context_size": "low"  # Options: "low", "medium" (default), "high"
    }]
)

from openai import OpenAI

# Point to your proxy server
client = OpenAI(
    api_key="sk-<your-litellm-api-key>",
    base_url="http://0.0.0.0:4000"
)

# Customize search context size
response = client.responses.create(
    model="gpt-5.6-terra",
    tools=[{
        "type": "web_search_preview",
        "search_context_size": "low"  # Options: "low", "medium" (default), "high"
    }],
    input="What is the capital of France?",
)

print(response.output_text)

config.yaml에서 웹 검색 구성

프록시 config 파일에서 기본 웹 검색 옵션을 직접 설정할 수 있어요:

기본 웹 검색
커스텀 검색 컨텍스트

model_list:
  # Enable web search by default for all requests to this model
  - model_name: grok-3
    litellm_params:
      model: xai/grok-3
      api_key: os.environ/XAI_API_KEY
      web_search_options: {}  # Enables web search with default settings

고급

LiteLLM의 라우터를 구성해 WebSearch를 지원하지 않는 모델을 선택적으로 뺄 수 있어요. 예:

- model_name: gpt-5.6-terra
  litellm_params:
    model: openai/gpt-5.6-terra
- model_name: gpt-5.6-terra
  litellm_params:
    model: azure/gpt-5.6-terra
    api_base: "x.openai.azure.com/"
    api_version: 2025-03-01-preview
  model_info:
    supports_web_search: False    # ← KEY CHANGE!

이 예시에서 LiteLLM은 여전히 두 배포 모두에 LLM 요청을 라우팅하지만, WebSearch에 대해서는 OpenAI로만 라우팅합니다.

model_list:
  # Set custom web search context size
  - model_name: grok-3
    litellm_params:
      model: xai/grok-3
      api_key: os.environ/XAI_API_KEY
      web_search_options:
        search_context_size: "high"  # Options: "low", "medium", "high"
  
  # OpenAI search model with custom context size
  - model_name: gpt-5-search-api
    litellm_params:
      model: openai/gpt-5-search-api
      api_key: os.environ/OPENAI_API_KEY
      web_search_options:
        search_context_size: "low"

  # Gemini with medium context (default)
  - model_name: gemini-2-flash
    litellm_params:
      model: gemini-3.8-flash
      vertex_project: your-project-id
      vertex_location: us-central1
      web_search_options:
        search_context_size: "medium"

참고: config에 web_search_options 가 설정되면 그 모델의 모든 요청에 적용됩니다. 사용자는 API 요청에 web_search_options 를 전달해 이 설정을 여전히 오버라이드할 수 있어요.

모델이 웹 검색을 지원하는지 확인

SDK
PROXY

litellm.supports_web_search(model="model_name") -> 모델이 웹 검색을 수행할 수 있으면 True 반환

# Check OpenAI models
assert litellm.supports_web_search(model="openai/gpt-5-search-api") == True
assert litellm.supports_web_search(model="openai/gpt-4o-search-preview") == True
# Check xAI models
assert litellm.supports_web_search(model="xai/grok-3") == True
# Check Anthropic models
assert litellm.supports_web_search(model="anthropic/claude-sonnet-5") == True
# Check VertexAI models
assert litellm.supports_web_search(model="gemini-3.8-flash") == True
# Check Google AI Studio models
assert litellm.supports_web_search(model="gemini/gemini-3.8-flash") == True

config.yaml에 모델 정의

model_list:
  # OpenAI
  - model_name: gpt-5-search-api
    litellm_params:
      model: openai/gpt-5-search-api
      api_key: os.environ/OPENAI_API_KEY
    model_info:
      supports_web_search: True

  - model_name: gpt-4o-search-preview
    litellm_params:
      model: openai/gpt-4o-search-preview
      api_key: os.environ/OPENAI_API_KEY
    model_info:
      supports_web_search: True

  # xAI
  - model_name: grok-3
    litellm_params:
      model: xai/grok-3
      api_key: os.environ/XAI_API_KEY
    model_info:
      supports_web_search: True
  
  # Anthropic
  - model_name: claude-sonnet-5
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY
    model_info:
      supports_web_search: True
  
  # VertexAI
  - model_name: gemini-2-flash
    litellm_params:
      model: gemini-3.8-flash
      vertex_project: your-project-id
      vertex_location: us-central1
    model_info:
      supports_web_search: True
  
  # Google AI Studio
  - model_name: gemini-2-flash-studio
    litellm_params:
      model: gemini/gemini-3.8-flash
      api_key: os.environ/GOOGLE_API_KEY
    model_info:
      supports_web_search: True

proxy server 실행 후 /model_group/info 호출로 웹 검색 지원 확인:

curl -X 'GET' \
  'http://localhost:4000/model_group/info' \
  -H 'accept: application/json' \
  -H "x-api-key: ***"

웹 검색 비용 추적

LiteLLM은 프로바이더별 청구 모델에 기반해 웹 검색 비용을 자동으로 추적합니다. 비용은 표준 토큰 기반 가격 위에 추가됩니다.

프로바이더가 웹 검색비를 부과하는 방식

프로바이더	청구 단위	동작 방식
Gemini 3.x (3-flash, 3-pro, 3.1-*)	검색 쿼리당	각 내부 검색 쿼리가 개별 청구됨. 하나의 프롬프트가 여러 쿼리를 유발할 수 있음
Gemini 2.x (2.0-flash, 2.5-flash, 2.5-pro)	grounded prompt당	내부에서 실행되는 쿼리 수와 무관하게 grounding을 사용하는 API 호출당 고정 요금
OpenAI (gpt-4o-search, gpt-5-search)	검색 컨텍스트 크기당	`search_context_size`(`low`, `medium`, `high`)에 따라 비용이 달라짐
Anthropic (Claude with web search)	검색 요청당	웹 검색 도구 호출당 고정 비용
Perplexity (sonar, sonar-pro)	검색 컨텍스트 크기당	`search_context_size` 에 따라 비용이 달라짐

가격 구성

웹 검색 비용은 model_prices_and_context_window.json 에서 두 필드로 정의됩니다:

search_context_cost_per_query : 청구 가능 단위당 비용 (검색 컨텍스트 크기 티어당).
web_search_billing_unit (Gemini 모델): "per_query" (각 검색 쿼리가 개별 청구) 또는 "per_prompt" (기본; 검색을 사용하는 API 호출당 고정 요금).

{
    "gemini/gemini-3.8-flash": {
        "web_search_billing_unit": "per_query",
        "search_context_cost_per_query": {
            "search_context_size_low": 0.014,
            "search_context_size_medium": 0.014,
            "search_context_size_high": 0.014
        }
    },
    "gemini/gemini-2.5-flash": {
        "search_context_cost_per_query": {
            "search_context_size_low": 0.035,
            "search_context_size_medium": 0.035,
            "search_context_size_high": 0.035
        }
    }
}

web_search_billing_unit 이 없는 모델은 기본 "per_prompt" 로 동작합니다: 모델이 실행하는 내부 쿼리 수와 무관하게 웹 검색을 사용하는 API 호출당 고정 요금 하나.

proxy config에서 model_info 로 이를 오버라이드할 수 있습니다:

model_list:
  - model_name: gemini-3.8-flash
    litellm_params:
      model: gemini/gemini-3.8-flash
    model_info:
      web_search_billing_unit: per_query
      search_context_cost_per_query:
        search_context_size_low: 0.014
        search_context_size_medium: 0.014
        search_context_size_high: 0.014

LiteLLM이 검색 사용량을 추적하는 방식

웹 검색 요청 수는 usage.prompt_tokens_details.web_search_requests 에 저장됩니다. LiteLLM은 이를 각 프로바이더의 응답에서 추출합니다:

Gemini: 응답의 groundingMetadata.webSearchQueries 에서 추출. Gemini 2.x는 1로 클램프 (per-prompt 청구).
OpenAI: usage metadata에 직접 보고.
Anthropic: server_tool_use.web_search_requests 를 통해 보고.
xAI: 응답의 num_sources_used 에서 매핑.

response = litellm.completion(
    model="gemini/gemini-3.8-flash",
    messages=[{"role": "user", "content": "Latest tech news?"}],
    web_search_options={"search_context_size": "medium"},
)

# Check web search usage
print(response.usage.prompt_tokens_details.web_search_requests)  # e.g., 3

# Get total cost (includes token cost + web search cost)
cost = litellm.completion_cost(completion_response=response)
print(f"Total cost: ${cost}")

웹 검색

웹 검색 (Web Search)

어떤 검색 엔진이 사용되나?

OpenAI 웹 검색: 두 가지 접근 방식

본문

/chat/completions (litellm.completion)

빠른 시작

검색 컨텍스트 크기

/responses (litellm.responses)

빠른 시작

검색 컨텍스트 크기

config.yaml에서 웹 검색 구성

고급

모델이 웹 검색을 지원하는지 확인

웹 검색 비용 추적

프로바이더가 웹 검색비를 부과하는 방식

가격 구성

LiteLLM이 검색 사용량을 추적하는 방식

더 알아보기 (Learn more)