Búsqueda web con la API de Ollama

Para qué sirve la búsqueda web en Ollama

Los modelos se entrenan con datos hasta una fecha determinada y no tienen acceso directo a internet. Para preguntas sobre noticias, documentación reciente o datos en tiempo real necesitas una fuente externa. La API de búsqueda web de Ollama permite hacer búsquedas y obtener contenido de páginas, y usar ese resultado como contexto para el modelo o como herramienta que el propio modelo puede invocar mediante tool calling. Así reduces alucinaciones y mejoras la precisión cuando la respuesta depende de información actual.

El servicio de búsqueda web está alojado en Ollama Cloud (no en tu servidor local). Por tanto necesitas una cuenta en Ollama y una API key para autenticarte. Sin API key las peticiones a estos endpoints serán rechazadas.

La búsqueda web es un complemento al modelo local o en la nube: el modelo sigue ejecutándose donde lo tengas configurado, y solo las llamadas a web_search y web_fetch van al servicio de Ollama en internet.

flowchart LR
    A["Consulta del usuario"] --> B["web_search<br/>búsqueda web"]
    B --> C["Resultados<br/>título, URL, contenido"]
    C --> D["Inyectar como contexto<br/>en /api/chat"]
    C --> E["web_fetch<br/>contenido completo de URL"]
    E --> D
    D --> F["Modelo genera respuesta<br/>con datos actualizados"]

Autenticación y endpoints

La documentación actual expone dos endpoints bajo el dominio de Ollama (por ejemplo https://ollama.com):

• POST https://ollama.com/api/web_search: búsqueda por consulta. Parámetros: query (string, obligatorio) y opcionalmente max_results (entero, por defecto 5, máximo 10). Devuelve una lista de resultados con title, url y content (snippet).
• POST https://ollama.com/api/web_fetch: obtención del contenido de una URL. Parámetro url (string, obligatorio). Devuelve title, content y links de la página.

Debes enviar la API key en la cabecera Authorization: Bearer TU_API_KEY o tener configurada la variable de entorno OLLAMA_API_KEY si la librería la usa por defecto. Puedes crear y gestionar API keys desde la configuración de tu cuenta en el sitio de Ollama.

Ejemplo con curl para búsqueda:

curl https://ollama.com/api/web_search \
  --header "Authorization: Bearer $OLLAMA_API_KEY" \
  -d '{"query": "qué es Ollama"}'

La respuesta es un objeto JSON con un array results, y cada elemento suele incluir title, url y content.

Uso desde Python y JavaScript

En Python, con una versión reciente de la librería ollama, puedes llamar a ollama.web_search(query) y ollama.web_fetch(url) sin construir la petición HTTP a mano. La librería usa la API key del entorno o la que configures.

import ollama

resultados = ollama.web_search("Qué es Ollama")
for r in resultados.get("results", []):
  print(r.get("title"), r.get("url"))

pagina = ollama.web_fetch("https://ollama.com")
print(pagina.get("title"), pagina.get("content")[:200])

En JavaScript (con el cliente oficial), se usan métodos como client.webSearch(query) y client.webFetch(url):

import { Ollama } from 'ollama'

const client = new Ollama()
const resultados = await client.webSearch('qué es Ollama')
console.log(resultados.results)

const pagina = await client.webFetch('https://ollama.com')
console.log(pagina.title, pagina.content)

Con eso ya puedes hacer búsquedas o cargar páginas y pasar el texto como contexto en los mensajes de /api/chat para que el modelo responda con esa información.

Usar web search como herramienta (tool calling)

Para que el modelo decida cuándo buscar y qué consultas hacer, puedes exponer web_search y web_fetch como tools en una conversación. El modelo devuelve tool_calls con el nombre de la función y los argumentos (por ejemplo query o url). Tú ejecutas la llamada real a la API, añades el resultado como mensaje con rol tool y vuelves a llamar a chat. Así construyes un agente de búsqueda que puede hacer varias consultas o leer páginas antes de responder.

En la documentación de Ollama hay ejemplos en Python que registran web_search y web_fetch como herramientas, pasan tools=[web_search, web_fetch] (o el equivalente con nombres y schemas) y en un bucle procesan response.message.tool_calls, llaman a la función correspondiente y añaden el resultado a messages hasta que la respuesta no incluya más tool calls. Es recomendable usar un modelo que soporte thinking y tool calling (por ejemplo Qwen 3) y un contexto amplio (por ejemplo 32k tokens o más), porque los resultados de búsqueda pueden ser largos.

Los resultados de web_search y web_fetch pueden ocupar muchos tokens. Si los recortas para caber en contexto, hazlo de forma que no se pierda la información esencial. En agentes largos, gestionar bien el tamaño del historial es importante.

Resumen práctico

• web_search(query, max_results?): obtienes una lista de resultados con título, URL y contenido resumido. Ideal para "buscar y luego pasar al modelo".
• web_fetch(url): obtienes el contenido de una sola URL. Útil cuando ya tienes el enlace (por ejemplo de un resultado de web_search).
• Autenticación: API key en cabecera Authorization: Bearer ... o en OLLAMA_API_KEY.
• Integración: uso directo en código (Python/JS) o como tools en /api/chat para que el modelo invoque búsqueda y fetch cuando lo necesite.

Si quieres que el modelo tenga siempre información actualizada en ciertos temas, combinar la API de búsqueda web con tool calling y, si aplica, thinking te permite construir asistentes que consultan internet y responden con datos recientes.