Connectez Ollama à Observagent.

1. Préparer Python et Ollama

Exécutez ces vérifications sur votre ordinateur Windows :

python --version
ollama list

Si Python n'est pas trouvé, essayez py --version. Si aucune commande ne fonctionne, installez Python, puis fermez et rouvrez PowerShell :

winget install --exact --id Python.Python.3.13 --source winget

Si winget n'est pas disponible, utilisez l'installeur Windows depuis python.org. Activez Add Python to PATH si proposé. Après avoir rouvert PowerShell, vérifiez python --version ; utilisez py pour la commande initiale de création d'environnement si seul ce lanceur fonctionne.

Ouvrez l'application Ollama et vérifiez que le serveur écoute :

Invoke-RestMethod "http://127.0.0.1:11434/api/version"

Attendez-vous à un numéro de version. Si la connexion échoue, démarrez Ollama avant de continuer. Si vous utilisez ollama serve manuellement, gardez-le dans un terminal séparé sans le paramètre OLLAMA_HOST du proxy.

2. Obtenir le dépôt du proxy et créer un environnement

Clonez le dépôt du proxy Observagent Ollama, ou utilisez l'option Download ZIP de GitHub et extrayez-le. Le dépôt inclut le proxy, les dépendances figées, les tests hors ligne, le vérificateur de livraison, la licence, et le guide de configuration complet.

Set-Location $HOME
git clone https://github.com/Observagent/observagent-ollama-proxy.git
Set-Location "$HOME\observagent-ollama-proxy"
python -m venv .venv

Exécutez chaque commande d'installation séparément. Le dernier nom de paquet est un nom complet unique ; n'insérez pas de retour à la ligne à l'intérieur. Appeler directement le Python de l'environnement rend l'activation optionnelle.

.\.venv\Scripts\python.exe -m pip install fastapi uvicorn httpx
.\.venv\Scripts\python.exe -m pip install opentelemetry-sdk
.\.venv\Scripts\python.exe -m pip install opentelemetry-exporter-otlp-proto-http

Autrement, installez les dépendances figées depuis le fichier du dépôt :

.\.venv\Scripts\python.exe -m pip install -r requirements.txt

Vous pouvez activer avec .\.venv\Scripts\Activate.ps1 et utiliser python, mais toutes les commandes restantes fonctionnent sans activation. Si l'activation est bloquée par la politique d'exécution, utilisez les commandes directes ci-dessous ; aucun changement de politique n'est nécessaire.

3. Créer ou sélectionner un projet Observagent

Connectez-vous à votre tableau de bord Observagent. Ouvrez Settings / Projects, créez un projet Ollama ou sélectionnez-en un existant, activez Journaux, Métriques, et Traces, et activez la surveillance. Choisissez Connect source, puis Generate / replace project key. Copiez la clé complète lorsqu'elle s'affiche ; elle nécessite la permission telemetry:write.

Un projet Ollama séparé peut rendre sa télémétrie plus facile à identifier et filtrer.

Si vous remplacez une clé de projet, mettez à jour chaque émetteur qui utilisait la clé précédente.

Si la création de clé de projet n'est pas disponible, contactez votre administrateur Observagent ou canal de support. N'utilisez pas votre mot de passe de tableau de bord ou une clé de fournisseur de modèle.

4. Configurer la fenêtre 1 et démarrer le proxy

Exécutez ces commandes dans la même fenêtre PowerShell qui démarrera le proxy. Entrez votre point de terminaison réel à l'invite, tel que https://dashboard.observagent.cloud/v1/traces pour ce déploiement. Utilisez l'URL complète /v1/traces, pas le site marketing ou l'URL de documentation.

Set-Location "$HOME\observagent-ollama-proxy"
$env:OTEL_EXPORTER_OTLP_TRACES_ENDPOINT = Read-Host "Full backend trace URL ending in /v1/traces"
$env:OBSERVAGENT_API_KEY = (Read-Host "Paste the complete raw Observagent project API key").Trim()
$env:OBSERVAGENT_SESSION_ID = "ollama-cli-test"

Fournissez la clé de projet complète à OBSERVAGENT_API_KEY ; un préfixe de clé raccourci ne peut pas authentifier les requêtes. N'incluez pas Authorization=Bearer, %20, de guillemets, ou un # en tête. Le proxy dérive les points de terminaison de journaux et métriques depuis le point de terminaison de traces. Vous pouvez les remplacer avec OTEL_EXPORTER_OTLP_LOGS_ENDPOINT et OTEL_EXPORTER_OTLP_METRICS_ENDPOINT. Les trois exportateurs utilisent la même clé API de projet.

Vérifiez que les paramètres existent sans afficher la clé :

Write-Host "Endpoint:" $env:OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
Write-Host "API key configured:" (-not [string]::IsNullOrWhiteSpace($env:OBSERVAGENT_API_KEY))

Exécutez les tests hors ligne, puis démarrez le proxy :

.\.venv\Scripts\python.exe test_ollama_proxy.py
.\.venv\Scripts\python.exe -m uvicorn ollama_proxy:app --host 127.0.0.1 --port 11435

Attendez-vous à ce que la vérification de la clé API retourne True, puis Application startup complete et Uvicorn running on http://127.0.0.1:11435. Laissez cette fenêtre ouverte. Les paramètres sont locaux à ce processus PowerShell et disparaissent lorsque vous le fermez. Les variables définies dans un autre terminal ou un fichier .env non chargé ne configurent pas le proxy.

5. Connecter la fenêtre 2 et générer de l'activité

Ouvrez une seconde fenêtre PowerShell sur le même ordinateur :

$env:OLLAMA_HOST = "http://127.0.0.1:11435"
ollama list

Choisissez un nom de modèle installé dans la liste :

$model = Read-Host "Installed model name from ollama list"
ollama run $model

Envoyez une invite, par exemple : Explain telemetry in two sentences. Laissez la réponse se terminer. OLLAMA_HOST s'applique au CLI dans cette fenêtre ; gardez le vrai serveur Ollama sur 11434. Les requêtes d'autres fenêtres qui contournent le proxy ne sont pas capturées.

Les autres clients HTTP Ollama doivent aussi cibler le proxy sur http://127.0.0.1:11435. Utilisez le paramètre d'URL de base Ollama documenté du client lorsqu'il n'honore pas OLLAMA_HOST.

Si le client produit une réponse de modèle mais que la fenêtre 1 ne montre aucun POST /api/chat, le client a contourné le proxy et s'est probablement connecté directement au port 11434.

6. Vérifier les journaux, métriques et traces dans Observagent

Basculez vers la fenêtre 1 avec Alt+Tab ou sélectionnez son onglet de terminal. Après une réponse terminée, attendez-vous à ollama.request.completed: input=... output=...; logs, metrics and trace queued for export. Queued signifie mis en tampon pour l'export, pas un stockage backend confirmé.

Dans le tableau de bord, connectez-vous avec le compte associé à la clé. Ouvrez Données de télémétrie, choisissez All sources et All available, sélectionnez Logs ou All, effacez les anciens filtres, et actualisez. Recherchez agent:ollama-cli ou event:ollama.request.completed. Inspectez les attributs originaux d'un journal pour voir le modèle, input_token_count, output_token_count, et les durées.

Vérifiez les journaux, métriques et traces séparément. Les métriques incluent ollama.request.count, ollama.request.duration, et ollama.token.count lorsque l'usage est disponible. L'arrivée d'un signal ne prouve pas que les autres ont été stockés.

Les événements de journal sont ollama.request.completed, ollama.request.failed, et ollama.request.incomplete. Les erreurs avant connexion produisent un journal de requête échouée. Il n'y a pas de journaux pour les vérifications de santé ou les requêtes de liste de modèles. Les versions antérieures du proxy ne gérant que les traces n'envoient pas de journaux ; remplacez le script et redémarrez pour utiliser cette version.

7. Diagnostiquer la livraison directement

Dans la fenêtre 1, appuyez sur Ctrl+C pour arrêter le proxy tout en conservant ses paramètres d'environnement. Exécutez le fichier de diagnostic fourni pour envoyer un journal, une métrique et une trace synthétiques avec la session ollama-delivery-test :

.\.venv\Scripts\python.exe verify_delivery.py

Ceci crée des enregistrements de test. Attendez-vous à HTTP 200 et count: 1 pour chaque signal. Cela confirme la livraison authentifiée pour la clé configurée indépendamment d'Ollama. Un test réussi ne prouve pas que les exports automatiques du proxy fonctionnent ; redémarrez le proxy et générez une autre vraie requête pour vérifier cela aussi.

Pour tester uniquement le routage et l'autorisation sans stocker d'enregistrements, utilisez le mode lot vide :

.\.venv\Scripts\python.exe verify_delivery.py --empty

Attendez-vous à count: 0. HTTP 200 avec du HTML n'est pas une confirmation d'ingestion. HTTP 401 signifie que la clé brute complète n'a pas été acceptée ; générez une nouvelle clé de projet et copiez-la exactement. Le préfixe seul ne peut jamais authentifier. HTTP 403 signifie que la clé ou le projet n'est pas autorisé à envoyer ce signal. Un 404 indique généralement un chemin incorrect. Une erreur de délai ou TLS nécessite une vérification de connectivité, de domaine, ou de certificat. Gardez la vérification de certificat activée.

Si le test stocke des enregistrements mais qu'ils sont absents de l'historique du projet, vérifiez le projet de la clé, le compte connecté, les filtres, et si le site web et l'URL d'ingestion se réfèrent au même déploiement. Ne régénérez pas les clés de manière répétée pour diagnostiquer un problème d'affichage.

8. Changer les clés, redémarrer, ou arrêter la collecte

Pour acheminer de nouvelles données vers un projet différent, arrêtez le proxy dans la fenêtre 1 avec Ctrl+C, puis mettez à jour la clé et redémarrez :

$env:OBSERVAGENT_API_KEY = Read-Host "Paste the new project API key"
.\.venv\Scripts\python.exe -m uvicorn ollama_proxy:app --host 127.0.0.1 --port 11435

Pour démarrer dans une nouvelle fenêtre PowerShell, répétez les paramètres de point de terminaison, clé, et session de l'étape 4. Ne collez pas de clés dans des chats, captures d'écran, fichiers commités, ou documentation publique.

Pour contourner le proxy, quittez la session Ollama interactive et exécutez ceci dans la fenêtre 2 avant de démarrer une autre session CLI :

Remove-Item Env:OLLAMA_HOST -ErrorAction SilentlyContinue

Appuyez sur Ctrl+C dans la fenêtre 1 pour arrêter le proxy et vider les exports en attente lors d'un arrêt normal. Arrêter la collecte ne supprime pas les enregistrements déjà stockés.

Dépanner la configuration locale

• Python n'a pas été trouvé : installez Python, rouvrez PowerShell, et vérifiez python ou py avant de créer l'environnement. L'activation ne peut pas fonctionner jusqu'à ce que la création de l'environnement réussisse.
• Requirement invalide se terminant par otlp- : le nom du paquet a été scindé. Exécutez la ligne d'installation complète opentelemetry-exporter-otlp-proto-http de l'étape 2.
• Définissez OTEL_EXPORTER_OTLP_TRACES_ENDPOINT et OBSERVAGENT_API_KEY d'abord : une ou les deux variables manquent dans la fenêtre qui démarre le proxy. Exécutez à nouveau l'étape 4 là-bas. Un point de terminaison vide dans un autre terminal ne dit rien sur le processus du proxy.
• Les vérifications booléennes d'environnement retournent false : retirez tout # en tête de l'affectation et exécutez-la dans la même fenêtre PowerShell qui démarre le processus concerné. Un fichier .env n'est pas automatiquement chargé par ce proxy.
• Adresse déjà utilisée sur 11435 : une autre instance du proxy est peut-être encore en cours d'exécution. Retournez à sa fenêtre et arrêtez-la avant de redémarrer.
• Impossible d'atteindre Ollama sur 11434 : démarrez l'application Ollama. Ne démarrez pas le serveur Ollama en utilisant l'adresse du proxy de la fenêtre CLI.
• Le proxy ne reçoit aucune requête : configurez le client avec $env:OLLAMA_HOST = "http://127.0.0.1:11435" ou son option explicite d'URL de base Ollama. Un rapport local prouve que l'inférence s'est terminée, pas que le proxy l'a vue.
• L'export retourne 401 : exécutez d'abord verify_delivery.py. Confirmez que OBSERVAGENT_API_KEY contient la clé brute complète, pas le préfixe ou un en-tête Authorization=Bearer%20.... Révoquez toute clé collée dans le code source, journaux, captures d'écran, historique de shell, ou messages de support.
• Seuls certains signaux arrivent : téléchargez la dernière version du proxy depuis GitHub, redémarrez-le, activez Journaux, Métriques, et Traces pour le projet, et envoyez une nouvelle requête.
• La télémétrie arrive mais un total du tableau de bord reste inchangé : confirmez que la vue et les filtres sélectionnés incluent les événements Ollama récents.
• PowerShell reste à l'invite >> après un bloc Python collé : appuyez sur Ctrl+C. Un marqueur de fermeture de here-string doit commencer à la colonne un et les imports Python ne doivent pas être scindés incorrectement. Utilisez verify_delivery.py plutôt que de coller un here-string Python multiligne.

Escalader un problème de connexion non résolu

Si une clé nouvellement générée échoue toujours à verify_delivery.py, contactez votre administrateur Observagent ou canal de support. Partagez uniquement l'horodatage de la requête, le nom d'hôte du point de terminaison, le statut HTTP, le nom du projet, et le préfixe de clé non secret. Ne partagez jamais la clé brute complète. La configuration serveur, la validation de compte, et les diagnostics de stockage appartiennent au manuel opérateur privé et sont intentionnellement exclus de ce guide public.

Fichiers et référence

• ollama_proxy.py : service de transmission local et exportateurs groupés de journaux, métriques et traces.
• requirements.txt : dépendances d'exécution.
• test_ollama_proxy.py : vérifications de régression hors ligne.
• verify_delivery.py : vérifications directes de livraison synthétique ou en lot vide.
• README.md : ce guide de configuration et de dépannage.

Ollama rapporte l'usage dans la réponse en flux finale ; voir la documentation d'usage Ollama. Voir le guide d'intégration Observagent Ollama pour le parcours public.