웹 검색(Web search)

Ollama의 웹 검색 API를 쓰면 모델에 최신 정보를 더해 환각(hallucination)을 줄이고 답변의 정확도를 높일 수 있어요. 웹 검색은 REST API로 제공되며, Python·JavaScript 라이브러리에는 더 깊은 도구 통합이 들어 있어요. 이를 통해 OpenAI의 gpt-oss 같은 모델도 장기 리서치 작업을 수행할 수 있습니다.

출처: 공식문서

인증

웹 검색 API에 접근하려면 API 키를 생성해야 합니다. 무료 Ollama 계정이 필요해요.

웹 검색 API

단일 쿼리에 대한 웹 검색을 수행하고 관련 결과를 반환합니다.

요청

POST https://ollama.com/api/web_search

  • query (string, 필수) — 검색 쿼리 문자열
  • max_results (integer, 선택) — 반환할 최대 결과 수 (기본 5, 최대 10)

응답

다음을 포함하는 객체를 반환합니다:

  • results (array) — 검색 결과 객체 배열. 각 객체는 다음을 포함:
    • title (string) — 웹 페이지 제목
    • url (string) — 웹 페이지 URL
    • content (string) — 웹 페이지의 관련 콘텐츠 스니펫

예시

OLLAMA_API_KEY를 설정하거나 Authorization 헤더에 넘겨야 합니다.

cURL 요청

curl https://ollama.com/api/web_search \
  --header "Authorization: Bearer ***" \
	-d '{
	  "query":"what is ollama?"
	}'

응답

{
  "results": [
    {
      "title": "Ollama",
      "url": "https://ollama.com/",
      "content": "Cloud models are now available..."
    }
  ]
}

Python 라이브러리

import ollama
response = ollama.web_search("What is Ollama?")
print(response)

더 많은 Python 예시는 ollama-python 예시에서 확인하세요.

JavaScript 라이브러리

import { Ollama } from "ollama";

const client = new Ollama();
const results = await client.webSearch("what is ollama?");
console.log(JSON.stringify(results, null, 2));

더 많은 JavaScript 예시는 ollama-js 예시에서 확인하세요.

웹 페치 API

URL로 단일 웹 페이지를 가져와 그 콘텐츠를 반환합니다.

요청

POST https://ollama.com/api/web_fetch

  • url (string, 필수) — 가져올 URL

응답

다음을 포함하는 객체를 반환합니다:

  • title (string) — 웹 페이지 제목
  • content (string) — 웹 페이지의 주요 콘텐츠
  • links (array) — 페이지에서 찾은 링크 배열

예시

cURL 요청

curl --request POST \
  --url https://ollama.com/api/web_fetch \
  --header "Authorization: Bearer ***" \
  --header 'Content-Type: application/json' \
  --data '{
      "url": "ollama.com"
  }'

Python SDK

from ollama import web_fetch

result = web_fetch('https://ollama.com')
print(result)

JavaScript SDK

import { Ollama } from "ollama";

const client = new Ollama();
const fetchResult = await client.webFetch("https://ollama.com");
console.log(JSON.stringify(fetchResult, null, 2));

검색 에이전트 만들기

Ollama의 웹 검색 API를 도구로 사용해 미니 검색 에이전트를 만들어 볼게요. 이 예시는 알리바바의 Qwen 3 모델(4B 파라미터)을 사용합니다.

ollama pull qwen3:4b

from ollama import chat, web_fetch, web_search

available_tools = {'web_search': web_search, 'web_fetch': web_fetch}

messages = [{'role': 'user', 'content': "what is ollama's new engine"}]

while True:
  response = chat(
    model='qwen3:4b',
    messages=messages,
    tools=[web_search, web_fetch],
    think=True
    )
  if response.message.thinking:
    print('Thinking: ', response.message.thinking)
  if response.message.content:
    print('Content: ', response.message.content)
  messages.append(response.message)
  if response.message.tool_calls:
    print('Tool calls: ', response.message.tool_calls)
    for tool_call in response.message.tool_calls:
      function_to_call = available_tools.get(tool_call.function.name)
      if function_to_call:
        args = tool_call.function.arguments
        result = function_to_call(**args)
        print('Result: ', str(result)[:200]+'...')
        # Result is truncated for limited context lengths
        messages.append({'role': 'tool', 'content': str(result)[:2000 * 4], 'tool_name': tool_call.function.name})
      else:
        messages.append({'role': 'tool', 'content': f'Tool {tool_call.function.name} not found', 'tool_name': tool_call.function.name})
  else:
    break

컨텍스트 길이와 에이전트

웹 검색 결과는 수천 개의 토큰을 반환할 수 있어요. 모델의 컨텍스트 길이를 최소 ~32000 토큰으로 늘리는 것을 권장합니다. 검색 에이전트는 전체 컨텍스트 길이에서 가장 잘 동작하며, Ollama 클라우드 모델은 전체 컨텍스트 길이로 실행됩니다.

MCP 서버

Python MCP 서버를 통해 어떤 MCP 클라이언트에서도 웹 검색을 활성화할 수 있어요.

Cline

Ollama 웹 검색은 MCP 서버 설정을 통해 Cline에 쉽게 통합할 수 있습니다.

Manage MCP Servers > Configure MCP Servers에서 다음 설정을 추가하세요:

{
  "mcpServers": {
    "web_search_and_fetch": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "path/to/web-search-mcp.py"],
      "env": { "OLLAMA_API_KEY": "your_api_key_here" }
    }
  }
}

Codex

Ollama는 OpenAI의 Codex 도구와 잘 동작합니다. ~/.codex/config.toml에 다음 설정을 추가하세요:

[mcp_servers.web_search]
command = "uv"
args = ["run", "path/to/web-search-mcp.py"]
env = { "OLLAMA_API_KEY" = "your_api_key_here" }

Goose

Ollama는 MCP 기능을 통해 Goose와 통합할 수 있습니다.

기타 통합

Ollama는 API 직접 통합, Python/JavaScript 라이브러리, OpenAI 호환 API, MCP 서버 통합을 통해 대부분의 도구에 연결될 수 있어요.

더 알아보기 (Learn more)