Utilizzo dell'API di ricerca web di Ollama in Python

Crea agenti di ricerca AI con Python e Ollama

Indice

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

spazio digitale

Guida Iniziale

Come si installa la libreria Python di 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 la gestione degli ambienti e dei pacchetti Python, valuta l’utilizzo di uv, un veloce gestore di pacchetti Python, oppure configura un ambiente virtuale utilizzando venv per mantenere le tue dipendenze isolate.

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

export OLLAMA_API_KEY="your_api_key"

In Windows PowerShell:

$env:OLLAMA_API_KEY = "your_api_key"

Ricerca Web Base

Il modo più semplice per cercare sul web con Ollama:

import ollama

# Semplice ricerca web
response = ollama.web_search("What is Ollama?")
print(response)

Output:

results = [
    {
        "title": "Ollama",
        "url": "https://ollama.com/",
        "content": "Cloud models are now available in Ollama..."
    },
    {
        "title": "What is Ollama? Features, Pricing, and Use Cases",
        "url": "https://www.walturn.com/insights/what-is-ollama",
        "content": "Our services..."
    },
    {
        "title": "Complete Ollama Guide: Installation, Usage & Code Examples",
        "url": "https://collabnix.com/complete-ollama-guide",
        "content": "Join our Discord Server..."
    }
]

Controllo del Numero di Risultati

import ollama

# Ottieni più risultati
response = ollama.web_search("latest AI news", 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 Intero della Pagina

Qual è la differenza tra web_search e web_fetch in Ollama Python? web_search interroga Internet e restituisce più risultati di ricerca con titoli, URL e snippet. web_fetch recupera il contenuto completo di un URL specifico, restituendo il titolo della pagina, il contenuto in markdown e i link. Il contenuto markdown restituito da web_fetch è perfetto per ulteriori elaborazioni: se hai bisogno di convertire HTML in markdown in altri contesti, consulta la nostra guida sulla conversione da HTML a Markdown con Python.

from ollama import web_fetch

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

Output:

WebFetchResponse(
    title='Ollama',
    content='[Cloud models](https://ollama.com/blog/cloud-models) are now available in Ollama\n\n**Chat & build with open models**\n\n[Download](https://ollama.com/download) [Explore models](https://ollama.com/models)\n\nAvailable for macOS, Windows, and Linux',
    links=['https://ollama.com/', 'https://ollama.com/models', 'https://github.com/ollama/ollama']
)

Combinare Ricerca e Recupero

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

from ollama import web_search, web_fetch

# Cerca informazioni
search_results = web_search("Ollama new features 2025")

# Recupera 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"Title: {full_content.title}")
    print(f"Content: {full_content.content[:500]}...")
    print(f"Links found: {len(full_content.links)}")

Creazione di 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, inclusi qwen3, gpt-oss e i 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 sugli LLM con output strutturato utilizzando Ollama e Qwen3. Una volta che gli strumenti o la modalità JSON restituiscono payload che intendi fidarti, la validazione dell’output strutturato LLM in Python che resiste copre l’analisi, i controlli Pydantic, i retry e i test sul lato applicazione.

Innanzitutto, scarica un modello capace:

ollama pull qwen3:4b

Agente di Ricerca Semplice

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

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[:200], '...')
    
    if response.message.content:
        print('💬 Response:', 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], '...')
                # Truncare il risultato per lunghezze di contesto limitate
                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

Come gestisco i grandi risultati di ricerca web 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 passarli al modello.

Agente di Ricerca Avanzato con Gestione degli Errori

Ecco una versione migliorata con una migliore gestione degli errori:

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"Error during 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 "No response generated"
            
            # 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 "Max iterations reached without final answer"
    
    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"Unknown tool: {func_name}"
        
        try:
            result = self.tools[func_name](**args)
            # Troncare per i limiti del contesto
            result_str = str(result)
            if len(result_str) > 8000:
                result_str = result_str[:8000] + "... [truncated]"
            return result_str
        except Exception as e:
            return f"Tool error: {e}"

# Utilizzo
agent = SearchAgent(model='qwen3:4b')
answer = agent.query("What are the latest features in Ollama?")
print(answer)

Ricerca Web Asincrona

Posso usare la ricerca web Python di Ollama con codice asincrono? Sì, la libreria Python di Ollama supporta le operazioni asincrone. Usa AsyncClient per operazioni di ricerca e recupero web non bloccanti in applicazioni asincrone.

import asyncio
from ollama import AsyncClient

async def async_search():
    client = AsyncClient()
    
    # Esegui più ricerche in parallelo
    tasks = [
        client.web_search("Ollama features"),
        client.web_search("local LLM tools"),
        client.web_search("AI search agents"),
    ]
    
    results = await asyncio.gather(*tasks)
    
    for i, result in enumerate(results):
        print(f"Search {i + 1}:")
        for r in result.results[:2]:
            print(f"  - {r.title}")
        print()

# Esegui la 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 in modo concorrente
        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("What's new in Python 3.13?"))
print(answer)

Lunghezza del Contesto e Prestazioni

Quale lunghezza del contesto dovrei impostare per gli agenti di ricerca Python? Imposta la lunghezza del contesto a circa 32000 token per prestazioni ragionevoli. 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 i task pesanti in ricerca
response = chat(
    model='qwen3:4b',
    messages=[{'role': 'user', 'content': 'Research the latest AI developments'}],
    tools=[web_search],
    options={
        'num_ctx': 32768,  # 32K contesto
    }
)

Integrazione con Server MCP

Ollama fornisce un server MCP Python che abilita la ricerca web in qualsiasi client MCP. Per una guida completa sulla creazione di server MCP in Python con capacità di ricerca web e scraping, consulta il nostro tutorial dettagliato sulla Creazione di Server MCP in Python.

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

Creazione del Proprio Server MCP

#!/usr/bin/env python3
"""Simple MCP server for Ollama web search."""

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:
    """Search the web for information."""
    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:
    """Fetch the full content of a web page."""
    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 pattern per costruire sistemi più complessi: ad esempio, combinando i risultati della ricerca con la generazione PDF in Python per creare rapporti di ricerca.

Sintetizzatore di Notizie

from ollama import chat, web_search

def summarize_news(topic: str) -> str:
    # Cerca notizie recenti
    results = web_search(f"{topic} latest news", 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 fare una sintesi
    response = chat(
        model='qwen3:4b',
        messages=[{
            'role': 'user',
            'content': f"Summarize these news items about {topic}:\n\n{news_content}"
        }]
    )
    
    return response.message.content

summary = summarize_news("artificial intelligence")
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 dalle prime fonti
    sources = []
    full_content = []
    
    for result in search_results.results[:3]:
        try:
            page = web_fetch(result.url)
            sources.append(result.url)
            full_content.append(f"Source: {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"""Based on the following sources, answer this question: {question}

Sources:
{context}

Provide a comprehensive answer with citations to the sources."""
        }]
    )
    
    return ResearchResult(
        question=question,
        sources=sources,
        answer=response.message.content
    )

# Utilizzo
result = research("How does Ollama's new model scheduling work?")
print(f"Question: {result.question}")
print(f"Sources: {result.sources}")
print(f"Answer: {result.answer}")

Modelli Raccomandati

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

Best Practice

  1. Troncamento dei 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 i guasti di rete
  3. Limiti di Frequenza: Rispetta i limiti di frequenza API di Ollama per la ricerca web
  4. Lunghezza del Contesto: Usa ~32000 token per gli agenti di ricerca
  5. Asincrono per la Scala: Usa AsyncClient per operazioni concorrenti
  6. Test: Scrivi test unitari per i tuoi agenti di ricerca per garantirne l’affidabilità
  7. Basi di Python: Tieni a portata di mano una scheda rapida Python per un riferimento rapido su sintassi e pattern comuni

Iscriviti

Ricevi nuovi articoli su sistemi, infrastruttura e ingegneria AI.