Utiliser l'API de recherche web d'Ollama en Python

Construisez des agents de recherche IA avec Python et Ollama

Sommaire

La bibliothèque Python d’Ollama inclut désormais des capacités natives de recherche web Ollama. Avec quelques lignes de code, vous pouvez enrichir vos modèles locaux de LLM avec des informations en temps réel provenant du web, réduisant ainsi les hallucinations et améliorant la précision.

espace numérique

Démarrage

Comment installer la bibliothèque Python Ollama pour la recherche web ? Installez la version 0.6.0 ou plus élevée en utilisant pip install 'ollama>=0.6.0'. Cette version inclut les fonctions web_search et web_fetch.

pip install 'ollama>=0.6.0'

Pour gérer les environnements et les packages Python, envisagez d’utiliser uv, un gestionnaire rapide de packages Python, ou configurez un environnement virtuel à l’aide de venv pour isoler vos dépendances.

Créez une clé API à partir de votre compte Ollama et définissez-la comme variable d’environnement :

export OLLAMA_API_KEY="your_api_key"

Sur Windows PowerShell :

$env:OLLAMA_API_KEY = "your_api_key"

Recherche Web de Base

La manière la plus simple de rechercher sur le web avec Ollama :

import ollama

# Recherche web simple
response = ollama.web_search("Qu'est-ce que Ollama ?")
print(response)

Sortie :

results = [
    {
        "title": "Ollama",
        "url": "https://ollama.com/",
        "content": "Les modèles cloud sont désormais disponibles dans Ollama. .."
    },
    {
        "title": "Qu'est-ce que Ollama ? Fonctionnalités, tarification et cas d'utilisation",
        "url": "https://www.walturn.com/insights/what-is-ollama",
        "content": "Nos services. .."
    },
    {
        "title": "Guide complet d'Ollama : Installation, utilisation et exemples de code",
        "url": "https://collabnix.com/complete-ollama-guide",
        "content": "Rejoignez notre serveur Discord. .."
    }
]

Contrôle du Nombre de Résultats

import ollama

# Obtenir plus de résultats
response = ollama.web_search("dernières nouvelles en IA", max_results=10)

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

Récupération du Contenu d’une Page Web

Quelle est la différence entre web_search et web_fetch dans la bibliothèque Python Ollama ? web_search interroge l’internet et retourne plusieurs résultats de recherche avec des titres, des URLs et des extraits. web_fetch récupère le contenu complet d’une URL spécifique, retournant le titre de la page, le contenu en markdown et les liens. Le contenu en markdown retourné par web_fetch est parfait pour un traitement ultérieur — si vous avez besoin de convertir du HTML en markdown dans d’autres contextes, consultez notre guide sur la conversion du HTML en markdown avec Python.

from ollama import web_fetch

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

Sortie :

WebFetchResponse(
    title='Ollama',
    content='[Modèles cloud](https://ollama.com/blog/cloud-models) sont désormais disponibles dans Ollama\n\n**Chat & build avec des modèles ouverts**\n\n[Télécharger](https://ollama.com/download) [Explorer les modèles](https://ollama.com/models)\n\nDisponible pour macOS, Windows et Linux',
    links=['https://ollama.com/', 'https://ollama.com/models', 'https://github.com/ollama/ollama']
)

Combiner Recherche et Récupération

Un modèle courant consiste à rechercher d’abord, puis à récupérer le contenu complet à partir des résultats pertinents :

from ollama import web_search, web_fetch

# Rechercher des informations
search_results = web_search("nouvelles fonctionnalités d'Ollama 2025")

# Récupérer le contenu complet à partir du premier résultat
if search_results.results:
    first_url = search_results.results[0].url
    full_content = web_fetch(first_url)
    
    print(f"Titre: {full_content.title}")
    print(f"Contenu: {full_content.content[:500]}. ..")
    print(f"Liens trouvés: {len(full_content.links)}")

Créer un Agent de Recherche

Quels modèles Python fonctionnent le mieux pour les agents de recherche Ollama ? Les modèles avec des capacités fortes d’utilisation d’outils fonctionnent le mieux, notamment qwen3, gpt-oss et des modèles cloud comme qwen3:480b-cloud et deepseek-v3.1-cloud. Pour des cas d’utilisation plus avancés nécessitant des sorties structurées de ces modèles, consultez notre guide sur LLMs avec sortie structurée à l’aide d’Ollama et de Qwen3.

Tout d’abord, tirez un modèle capable :

ollama pull qwen3:4b

Agent de Recherche Simple

Voici un agent de recherche de base capable de décider seul quand effectuer une recherche :

from ollama import chat, web_fetch, web_search

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

messages = [{'role': 'user', 'content': "quelle est la nouvelle engine d'Ollama"}]

while True:
    response = chat(
        model='qwen3:4b',
        messages=messages,
        tools=[web_search, web_fetch],
        think=True
    )
    
    if response.message.thinking:
        print('🧠 Réflexion:', response.message.thinking[:200], '. ..')
    
    if response.message.content:
        print('💬 Réponse:', response.message.content)
    
    messages.append(response.message)
    
    if response.message.tool_calls:
        print('🔧 Appels d'outils:', 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('📥 Résultat:', str(result)[:200], '. ..')
                # Tronquer le résultat pour les limites de contexte
                messages.append({
                    'role': 'tool', 
                    'content': str(result)[:2000 * 4], 
                    'tool_name': tool_call.function.name
                })
            else:
                messages.append({
                    'role': 'tool', 
                    'content': f'Outil {tool_call.function.name} non trouvé', 
                    'tool_name': tool_call.function.name
                })
    else:
        break

Comment gérer les résultats de recherche web volumineux en Python ? Tronquer les résultats pour s’adapter aux limites de contexte. L’approche recommandée consiste à couper la chaîne de résultat à environ 8000 caractères (2000 tokens × 4 caractères) avant de la transmettre au modèle.

Agent de Recherche Avancé avec Gestion des Erreurs

Voici une version améliorée avec une meilleure gestion des erreurs :

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"Erreur lors de la discussion : {e}"
            
            self.messages.append(response.message)
            
            # Si aucun appel d'outil, nous avons une réponse finale
            if not response.message.tool_calls:
                return response.message.content or "Aucune réponse générée"
            
            # Exécuter les appels d'outils
            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 "Nombre maximal d'itérations atteint sans réponse 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"Outil inconnu : {func_name}"
        
        try:
            result = self.tools[func_name](**args)
            # Tronquer pour les limites de contexte
            result_str = str(result)
            if len(result_str) > 8000:
                result_str = result_str[:8000] + "... [tronqué]"
            return result_str
        except Exception as e:
            return f"Erreur de l'outil : {e}"

# Utilisation
agent = SearchAgent(model='qwen3:4b')
answer = agent.query("Quelles sont les dernières fonctionnalités d'Ollama ?")
print(answer)

Recherche Web Asynchrone

Puis-je utiliser la recherche web Python d’Ollama avec du code asynchrone ? Oui, la bibliothèque Python Ollama prend en charge les opérations asynchrones. Utilisez AsyncClient pour des recherches et des récupérations web non bloquantes dans les applications asynchrones. Pour des comparaisons de performance entre Python et d’autres langages dans des contextes sans serveur, consultez notre analyse de la performance d’AWS Lambda entre JavaScript, Python et Golang.

import asyncio
from ollama import AsyncClient

async def async_search():
    client = AsyncClient()
    
    # Effectuer plusieurs recherches en parallèle
    tasks = [
        client.web_search("fonctionnalités d'Ollama"),
        client.web_search("outils locaux LLM"),
        client.web_search("agents de recherche IA"),
    ]
    
    results = await asyncio.gather(*tasks)
    
    for i, result in enumerate(results):
        print(f"Recherche {i + 1}:")
        for r in result.results[:2]:
            print(f"  - {r.title}")
        print()

# Exécuter la recherche asynchrone
asyncio.run(async_search())

Agent de Recherche Asynchrone

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
        
        # Exécuter les appels d'outils en parallèle
        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))
        
        # Récupérer les résultats
        for tool_name, task in tool_tasks:
            result = await task
            messages.append({
                'role': 'tool',
                'content': str(result)[:8000],
                'tool_name': tool_name
            })

# Exécuter
answer = asyncio.run(async_research_agent("Qu'est-ce de neuf dans Python 3.13 ?"))
print(answer)

Longueur de Contexte et Performance

Quelle longueur de contexte dois-je définir pour les agents de recherche Python ? Définissez la longueur de contexte à environ 32000 tokens pour une performance raisonnable. Les agents de recherche fonctionnent le mieux avec une longueur de contexte complète, car web_search et web_fetch peuvent retourner des milliers de tokens.

from ollama import chat, web_search

# Définir un contexte plus long pour les tâches de recherche
response = chat(
    model='qwen3:4b',
    messages=[{'role': 'user', 'content': 'Rechercher les dernières développements en IA'}],
    tools=[web_search],
    options={
        'num_ctx': 32768,  # 32K contexte
    }
)

Intégration du Serveur MCP

Ollama fournit un serveur Python MCP qui permet la recherche web depuis tout client MCP. Pour un guide complet sur la création de serveurs MCP en Python avec des capacités de recherche et de scraping, consultez notre tutoriel détaillé sur la création de serveurs MCP en Python.

Intégration avec Cline

Configurez les serveurs MCP dans les paramètres Cline :

Gérer les serveurs MCP → Configurer les serveurs MCP → Ajouter :

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

Intégration avec Codex

Ajoutez à ~/.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" }

Créer votre propre serveur MCP

#!/usr/bin/env python3
"""Serveur MCP simple pour la recherche web d'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:
    """Rechercher sur le web des informations."""
    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:
    """Récupérer le contenu complet d'une page web."""
    result = web_fetch(url)
    return f"# {result.title}\n\n{result.content}"

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

Exemples Pratiques

Ces exemples démontrent des applications réelles de l’API de recherche web d’Ollama. Vous pouvez étendre ces modèles pour créer des systèmes plus complexes — par exemple, combiner les résultats de recherche avec la génération de PDF en Python pour créer des rapports de recherche.

Résumé des Actualités

from ollama import chat, web_search

def summarize_news(topic: str) -> str:
    # Rechercher des actualités récentes
    results = web_search(f"{topic} dernières nouvelles", max_results=5)
    
    # Formater les résultats de recherche pour le modèle
    news_content = "\n\n".join([
        f"**{r.title}**\n{r.content}"
        for r in results.results
    ])
    
    # Demander au modèle de résumer
    response = chat(
        model='qwen3:4b',
        messages=[{
            'role': 'user',
            'content': f"Résumez ces éléments d'actualité sur {topic}:\n\n{news_content}"
        }]
    )
    
    return response.message.content

summary = summarize_news("intelligence artificielle")
print(summary)

Assistant de Recherche

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:
    # Rechercher des informations pertinentes
    search_results = web_search(question, max_results=3)
    
    # Récupérer le contenu complet des sources principales
    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
    
    # Générer une réponse complète
    context = "\n\n---\n\n".join(full_content)
    
    response = chat(
        model='qwen3:4b',
        messages=[{
            'role': 'user',
            'content': f"""Sur la base des sources suivantes, répondez à cette question : {question}

Sources :
{context}

Fournissez une réponse complète avec des citations des sources."""
        }]
    )
    
    return ResearchResult(
        question=question,
        sources=sources,
        answer=response.message.content
    )

# Utilisation
result = research("Comment fonctionne le nouveau planification des modèles d'Ollama ?")
print(f"Question: {result.question}")
print(f"Sources: {result.sources}")
print(f"Réponse: {result.answer}")

Modèles Recommandés

Modèle Paramètres Meilleur pour
qwen3:4b 4B Recherches locales rapides
qwen3 8B Agent généraliste
gpt-oss Variés Tâches de recherche
qwen3:480b-cloud 480B Raisonnement complexe (cloud)
gpt-oss:120b-cloud 120B Recherche longue forme (cloud)
deepseek-v3.1-cloud - Analyse avancée (cloud)

Bonnes Pratiques

  1. Tronquer les Résultats : Tronquez toujours les résultats web pour s’adapter aux limites de contexte (~8000 caractères)
  2. Gestion des Erreurs : Entourez les appels d’outils avec try/except pour les échecs réseau
  3. Limitation de Débit : Respectez les limites de débit de l’API Ollama pour la recherche web
  4. Longueur de Contexte : Utilisez ~32000 tokens pour les agents de recherche
  5. Asynchrone pour l’Échelle : Utilisez AsyncClient pour les opérations concurrentes
  6. Tests : Écrivez des tests unitaires pour vos agents de recherche afin d’assurer leur fiabilité
  7. Bases de Python : Gardez une fiche de rappel Python à portée de main pour des références rapides sur la syntaxe et les schémas courants

Liens Utiles