Utilizzo dell'API di ricerca Web di Ollama in Python

Costruisci agenti di ricerca AI con Python e Ollama

Indice

La libreria Python di Ollama ora include funzionalità native di ricerca web OLLama. Con poche righe di codice, puoi arricchire i tuoi LLM locali con informazioni in tempo reale dal web, riducendo le illusioni e migliorando l’accuratezza.

spazio digitale

Iniziare

Come installare la libreria Python Ollama per la ricerca web? Installa la versione 0.6.0 o superiore utilizzando pip install 'ollama>=0.6.0'. Questa versione include le funzioni web_search e web_fetch.

pip install 'ollama>=0.6.0'

Per gestire gli ambienti e i pacchetti Python, considera l’uso di uv, un veloce gestore dei pacchetti Python, o crea un ambiente virtuale utilizzando venv per isolare le tue dipendenze.

Crea una chiave API dal tuo account Ollama e impostala come variabile di ambiente:

export OLLAMA_API_KEY="your_api_key"

Su Windows PowerShell:

$env:OLLAMA_API_KEY = "your_api_key"

Ricerca Web Base

Il modo più semplice per cercare in rete con Ollama:

import ollama

# Ricerca web semplice
response = ollama.web_search("Cosa è Ollama?")
print(response)

Output:

results = [
    {
        "title": "Ollama",
        "url": "https://ollama.com/",
        "content": "I modelli cloud sono ora disponibili in Ollama. .."
    },
    {
        "title": "Cosa è Ollama? Funzionalità, Prezzi e Caso d'uso",
        "url": "https://www.walturn.com/insights/what-is-ollama",
        "content": "I nostri servizi. .."
    },
    {
        "title": "Guida completa a Ollama: Installazione, Utilizzo e Esempi di Codice",
        "url": "https://collabnix.com/complete-ollama-guide",
        "content": "Unisciti al nostro server Discord. .."
    }
]

Controllo del numero di risultati

import ollama

# Ottenere più risultati
response = ollama.web_search("ultime notizie sull'AI", max_results=10)

for result in response.results:
    print(f"📌 {result.title}")
    print(f"   {result.url}")
    print(f"   {result.content[:100]}. ..")
    print()

Recupero del contenuto completo della pagina

Qual è la differenza tra web_search e web_fetch in Python Ollama? web_search effettua una query su internet e restituisce diversi risultati di ricerca con titoli, URL e frammenti. web_fetch recupera il contenuto completo di un URL specifico, restituendo il titolo della pagina, il contenuto in formato markdown e i collegamenti. Il contenuto markdown restituito da web_fetch è perfetto per ulteriori elaborazioni—se hai bisogno di convertire l’HTML in markdown in altri contesti, consulta la nostra guida su convertire HTML in Markdown con Python.

from ollama import web_fetch

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

Output:

WebFetchResponse(
    title='Ollama',
    content='[Modelli cloud](https://ollama.com/blog/cloud-models) sono ora disponibili in Ollama\n\n**Chat & costruisci con modelli aperti**\n\n[Scarica](https://ollama.com/download) [Esplora modelli](https://ollama.com/models)\n\nDisponibile per macOS, Windows e Linux',
    links=['https://ollama.com/', 'https://ollama.com/models', 'https://github.com/ollama/ollama']
)

Combinare Ricerca e Recupero

Un modello comune è cercare prima, quindi recuperare il contenuto completo dai risultati rilevanti:

from ollama import web_search, web_fetch

# Cercare informazioni
search_results = web_search("nuove funzionalità di Ollama 2025")

# Recuperare il contenuto completo dal primo risultato
if search_results.results:
    first_url = search_results.results[0].url
    full_content = web_fetch(first_url)
    
    print(f"Titolo: {full_content.title}")
    print(f"Contenuto: {full_content.content[:500]}. ..")
    print(f"Collegamenti trovati: {len(full_content.links)}")

Costruire un Agente di Ricerca

Quali modelli Python funzionano meglio per gli agenti di ricerca Ollama? I modelli con forti capacità di utilizzo degli strumenti funzionano meglio, tra cui qwen3, gpt-oss e modelli cloud come qwen3:480b-cloud e deepseek-v3.1-cloud. Per casi d’uso più avanzati che richiedono output strutturati da questi modelli, consulta la nostra guida su LLM con Output Strutturato utilizzando Ollama e Qwen3.

Prima, scarica un modello capace:

ollama pull qwen3:4b

Agente di Ricerca Base

Ecco un agente di ricerca base che può decidere autonomamente quando cercare:

from ollama import chat, web_fetch, web_search

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

messages = [{'role': 'user', 'content': "qual è il nuovo motore di Ollama"}]

while True:
    response = chat(
        model='qwen3:4b',
        messages=messages,
        tools=[web_search, web_fetch],
        think=True
    )
    
    if response.message.thinking:
        print('🧠 Pensando:', response.message.thinking[:200], '. ..')
    
    if response.message.content:
        print('💬 Risposta:', response.message.content)
    
    messages.append(response.message)
    
    if response.message.tool_calls:
        print('🔧 Chiamate agli strumenti:', 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('📥 Risultato:', str(result)[:200], '. ..')
                # Tronca il risultato per adattarlo alle limitazioni di contesto
                messages.append({
                    'role': 'tool', 
                    'content': str(result)[:2000 * 4], 
                    'tool_name': tool_call.function.name
                })
            else:
                messages.append({
                    'role': 'tool', 
                    'content': f'Strumento {tool_call.function.name} non trovato', 
                    'tool_name': tool_call.function.name
                })
    else:
        break

Come gestire i risultati di ricerca web di grandi dimensioni in Python? Tronca i risultati per adattarli ai limiti del contesto. L’approccio consigliato è tagliare la stringa dei risultati a circa 8000 caratteri (2000 token × 4 caratteri) prima di passarla al modello.

Agente di Ricerca Avanzato con Gestione degli Errori

Ecco una versione migliorata con una gestione degli errori più efficace:

from ollama import chat, web_fetch, web_search
import json

class SearchAgent:
    def __init__(self, model: str = 'qwen3:4b'):
        self.model = model
        self.tools = {'web_search': web_search, 'web_fetch': web_fetch}
        self.messages = []
        self.max_iterations = 10
        
    def query(self, question: str) -> str:
        self.messages = [{'role': 'user', 'content': question}]
        
        for iteration in range(self.max_iterations):
            try:
                response = chat(
                    model=self.model,
                    messages=self.messages,
                    tools=[web_search, web_fetch],
                    think=True
                )
            except Exception as e:
                return f"Errore durante la chat: {e}"
            
            self.messages.append(response.message)
            
            # Se non ci sono chiamate agli strumenti, abbiamo una risposta finale
            if not response.message.tool_calls:
                return response.message.content or "Nessuna risposta generata"
            
            # Esegui le chiamate agli strumenti
            for tool_call in response.message.tool_calls:
                result = self._execute_tool(tool_call)
                self.messages.append({
                    'role': 'tool',
                    'content': result,
                    'tool_name': tool_call.function.name
                })
        
        return "Raggiunto il numero massimo di iterazioni senza una risposta finale"
    
    def _execute_tool(self, tool_call) -> str:
        func_name = tool_call.function.name
        args = tool_call.function.arguments
        
        if func_name not in self.tools:
            return f"Strumento sconosciuto: {func_name}"
        
        try:
            result = self.tools[func_name](**args)
            # Tronca per i limiti del contesto
            result_str = str(result)
            if len(result_str) > 8000:
                result_str = result_str[:8000] + "... [troncato]"
            return result_str
        except Exception as e:
            return f"Errore dello strumento: {e}"

# Utilizzo
agent = SearchAgent(model='qwen3:4b')
answer = agent.query("Quali sono le ultime funzionalità di Ollama?")
print(answer)

Ricerca Web Asincrona

Posso utilizzare la ricerca web Python Ollama con codice asincrono? Sì, la libreria Python Ollama supporta le operazioni asincrone. Utilizza AsyncClient per operazioni di ricerca e recupero non bloccanti in applicazioni asincrone. Per confronti di prestazioni tra Python e altre lingue in contesti serverless, consulta l’analisi di prestazioni AWS Lambda tra JavaScript, Python e Golang.

import asyncio
from ollama import AsyncClient

async def async_search():
    client = AsyncClient()
    
    # Esegui diverse ricerche contemporaneamente
    tasks = [
        client.web_search("funzionalità Ollama"),
        client.web_search("strumenti LLM locali"),
        client.web_search("agenti di ricerca AI"),
    ]
    
    results = await asyncio.gather(*tasks)
    
    for i, result in enumerate(results):
        print(f"Ricerca {i + 1}:")
        for r in result.results[:2]:
            print(f"  - {r.title}")
        print()

# Esegui ricerca asincrona
asyncio.run(async_search())

Agente di Ricerca Asincrono

import asyncio
from ollama import AsyncClient

async def async_research_agent(question: str):
    client = AsyncClient()
    messages = [{'role': 'user', 'content': question}]
    
    while True:
        response = await client.chat(
            model='qwen3:4b',
            messages=messages,
            tools=[client.web_search, client.web_fetch],
        )
        
        messages.append(response.message)
        
        if not response.message.tool_calls:
            return response.message.content
        
        # Esegui le chiamate agli strumenti contemporaneamente
        tool_tasks = []
        for tool_call in response.message.tool_calls:
            if tool_call.function.name == 'web_search':
                task = client.web_search(**tool_call.function.arguments)
            elif tool_call.function.name == 'web_fetch':
                task = client.web_fetch(**tool_call.function.arguments)
            else:
                continue
            tool_tasks.append((tool_call.function.name, task))
        
        # Raccogli i risultati
        for tool_name, task in tool_tasks:
            result = await task
            messages.append({
                'role': 'tool',
                'content': str(result)[:8000],
                'tool_name': tool_name
            })

# Esegui
answer = asyncio.run(async_research_agent("Cosa è nuovo in Python 3.13?"))
print(answer)

Lunghezza del Contesto e Prestazioni

Quale lunghezza del contesto devo impostare per gli agenti di ricerca Python? Imposta la lunghezza del contesto a circa 32000 token per un’adeguata prestazione. Gli agenti di ricerca funzionano meglio con la lunghezza completa del contesto poiché web_search e web_fetch possono restituire migliaia di token.

from ollama import chat, web_search

# Imposta un contesto più alto per compiti pesanti per la ricerca
response = chat(
    model='qwen3:4b',
    messages=[{'role': 'user', 'content': 'Ricerca le ultime sviluppi sull'AI'}],
    tools=[web_search],
    options={
        'num_ctx': 32768,  # 32K contesto
    }
)

Integrazione del Server MCP

Ollama fornisce un server MCP in Python che consente la ricerca web in qualsiasi client MCP. Per una guida completa sull’implementazione di server MCP in Python con funzionalità di ricerca e scraping, consulta la nostra guida dettagliata su Costruzione di Server MCP in Python.

Integrazione con Cline

Configura i server MCP nelle impostazioni di Cline:

Gestisci Server MCP → Configura Server MCP → Aggiungi:

{
  "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" }
    }
  }
}

Integrazione con Codex

Aggiungi a ~/.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" }

Creare il tuo Server MCP

#!/usr/bin/env python3
"""Server MCP semplice per la ricerca web di Ollama."""

import os
from mcp.server import Server
from mcp.types import Tool, TextContent
from ollama import web_search, web_fetch

app = Server("ollama-web-search")

@app.tool()
async def search_web(query: str, max_results: int = 5) -> str:
    """Cerca informazioni in rete."""
    results = web_search(query, max_results=max_results)
    
    output = []
    for r in results.results:
        output.append(f"**{r.title}**\n{r.url}\n{r.content}\n")
    
    return "\n---\n".join(output)

@app.tool()
async def fetch_page(url: str) -> str:
    """Recupera il contenuto completo di una pagina web."""
    result = web_fetch(url)
    return f"# {result.title}\n\n{result.content}"

if __name__ == "__main__":
    app.run()

Esempi Pratici

Questi esempi dimostrano applicazioni reali dell’API di ricerca web di Ollama. Puoi estendere questi modelli per costruire sistemi più complessi—ad esempio, combinando i risultati delle ricerche con generazione PDF in Python per creare report di ricerca.

Sommario delle Notizie

from ollama import chat, web_search

def summarize_news(topic: str) -> str:
    # Cerca le ultime notizie
    results = web_search(f"{topic} ultime notizie", max_results=5)
    
    # Formatta i risultati della ricerca per il modello
    news_content = "\n\n".join([
        f"**{r.title}**\n{r.content}"
        for r in results.results
    ])
    
    # Chiedi al modello di sommare
    response = chat(
        model='qwen3:4b',
        messages=[{
            'role': 'user',
            'content': f"Riassumi queste notizie su {topic}:\n\n{news_content}"
        }]
    )
    
    return response.message.content

summary = summarize_news("intelligenza artificiale")
print(summary)

Assistente di Ricerca

from ollama import chat, web_search, web_fetch
from dataclasses import dataclass

@dataclass
class ResearchResult:
    question: str
    sources: list
    answer: str

def research(question: str) -> ResearchResult:
    # Cerca informazioni rilevanti
    search_results = web_search(question, max_results=3)
    
    # Recupera il contenuto completo dai primi risultati
    sources = []
    full_content = []
    
    for result in search_results.results[:3]:
        try:
            page = web_fetch(result.url)
            sources.append(result.url)
            full_content.append(f"Fonte: {result.url}\n{page.content[:2000]}")
        except:
            continue
    
    # Genera una risposta completa
    context = "\n\n---\n\n".join(full_content)
    
    response = chat(
        model='qwen3:4b',
        messages=[{
            'role': 'user',
            'content': f"""Basandoti sui seguenti fonti, rispondi a questa domanda: {question}

Fonti:
{context}

Fornisci una risposta completa con citazioni dai fonti."""
        }]
    )
    
    return ResearchResult(
        question=question,
        sources=sources,
        answer=response.message.content
    )

# Utilizzo
result = research("Come funziona la nuova pianificazione dei modelli di Ollama?")
print(f"Domanda: {result.question}")
print(f"Fonti: {result.sources}")
print(f"Risposta: {result.answer}")

Modelli Consigliati

Modello Parametri Migliore Per
qwen3:4b 4B Ricerche locali rapide
qwen3 8B Agente generico
gpt-oss Vari Compiti di ricerca
qwen3:480b-cloud 480B Ragionamento complesso (cloud)
gpt-oss:120b-cloud 120B Ricerca lunga (cloud)
deepseek-v3.1-cloud - Analisi avanzata (cloud)

Linee Guida per il Miglior Utilizzo

  1. Troncare i Risultati: Tronca sempre i risultati web per adattarli ai limiti del contesto (~8000 caratteri)
  2. Gestione degli Errori: Avvolgi le chiamate agli strumenti in try/except per gestire gli errori di rete
  3. Limiti di Velocità: Rispetta i limiti di velocità dell’API di Ollama per la ricerca web
  4. Lunghezza del Contesto: Utilizza ~32000 token per gli agenti di ricerca
  5. Asincrono per la Scalabilità: Utilizza AsyncClient per operazioni parallele
  6. Test: Scrivi test unitari per i tuoi agenti di ricerca per garantire l’affidabilità
  7. Nozioni di Base su Python: Tieni sempre a portata di mano un foglio di calcolo Python per riferimenti rapidi sulla sintassi e i modelli comuni