Guide de dépannage de l'API Ollama

Comprendre la structure des points de terminaison de l'API Ollama

Le ollama endpoint suit un schéma RESTful strict qui reflète la structure de l'API OpenAI. Vous interagissez avec elle en envoyant des requêtes POST à /v1/chat/completions et interroger les modèles disponibles via GET /v1/models. Cette standardisation vous permet de changer de modèles sous-jacents sans réécrire le code de votre client.

De nombreux développeurs supposent que le point de terminaison prend en charge les embeddings ou la génération d'images par défaut. Ce n'est pas le cas. Notre service hébergé, par exemple, ne fournit que des compléments de texte avec un seul modèle uncensored. Vérifiez toujours le GET /v1/models réponse pour voir exactement quelles capacités sont exposées. Si vous voyez une liste de modèles, vérifiez leurs ID avant d'envoyer des requêtes.

Lors de l'utilisation d'une instance locale, le point de terminaison s'exécute généralement sur http://localhost:11434. Pour les fournisseurs de cloud, vous utiliserez une URL de base personnalisée. Assurez-vous que votre client HTTP gère correctement les en-têtes, en particulier Content-Type: application/json. Un en-tête manquant provoque souvent des échecs silencieux qui ressemblent à des erreurs de modèle.

Éléments structurels clés :

• model: L'identifiant de chaîne pour le LLM spécifique.
• messages: Un tableau d'objets de contenu basés sur les rôles.
• stream: Un indicateur booléen activant les événements envoyés par le serveur (SSE).

Pourquoi vos appels API ollama peuvent échouer

Les appels API échouent généralement en raison d'URL de base incorrectes, de clés expirées ou de charges utiles JSON mal formées. L'erreur la plus courante est une réponse 401 Unauthorized, ce qui signifie que votre clé API est manquante ou invalide. Un autre problème fréquent est un 404 Not Found, indiquant que le point de terminaison ne prend pas en charge le chemin ou l'ID de modèle demandé.

Vérifiez soigneusement le corps de votre requête. Si vous envoyez un paramètre que le point de terminaison ne prend pas en charge, tel que modalities pour un modèle uniquement textuel, le serveur peut rejeter la demande. Notre service, par exemple, ne prend pas en charge l'entrée d'image. L'envoi d'une image entraîne une erreur immédiate.

Les timeouts réseau causent également des échecs. Si votre instance Ollama locale est inactive, elle peut décharger le modèle de la VRAM. La première requête après un démarrage à froid peut prendre plusieurs secondes. Définissez un timeout généreux dans votre client HTTP pour éviter les déconnexions prématurées.

Codes d'erreur courants :

• 400: Bad Request (JSON malformé ou paramètres invalides).
• 401: Non autorisé (clé API invalide ou manquante).
• 429: Trop de demandes (limite de taux dépassée).
• 500: Internal Server Error (échec du chargement du modèle).

Configuration correcte des modèles ollama sans censure

Les modèles sans filtre nécessitent souvent des paramètres spécifiques pour se comporter comme prévu. La principale différence réside dans le system prompt. Vous devez explicitement indiquer au modèle de contourner les refus standards. Sans une instruction système forte, le modèle peut revenir à ses comportements de sécurité par défaut.

Notre point de terminaison utilise l'identifiant de modèle uncensored. Vous envoyez des requêtes à cet ID, et le serveur gère la sélection du modèle sous-jacent. Cela abstrait la complexité de la gestion des versions de modèles. Vous n'avez pas besoin de savoir si l'architecture sous-jacente est basée sur Llama ou Mistral.

Ajustez le temperature le paramètre pour contrôler la créativité. Une valeur de 0,7 est un bon point de départ pour des réponses équilibrées. Des valeurs plus élevées augmentent l'aléatoire, ce qui est utile pour l'écriture créative mais peut réduire la précision factuelle. Des valeurs plus basses rendent la sortie plus déterministe.

Conseils de configuration :

• Utiliser top_p À côté de temperature pour un meilleur contrôle.
• Définir stop séquences pour éviter les boucles infinies.
• Incluez toujours un system message pour la définition du rôle.

Gestion du streaming et des limites de tokens

Les réponses en streaming renvoient des données sous forme de fragments via les Server-Sent Events (SSE). Chaque fragment contient une complétion partielle. Vous devez assembler ces fragments pour obtenir la réponse complète. Notre service inclut les statistiques d'utilisation des jetons dans le dernier fragment, vous permettant de suivre les coûts en temps réel.

Les limites de tokens sont critiques pour les longues conversations. Notre point de terminaison prend en charge une fenêtre de contexte de 100 000 tokens, combinant à la fois l'invite et la complétion. Cependant, la sortie maximale par requête est de 16 000 tokens. Si vous ne définissez pas max_tokens, la valeur par défaut est de 2 048 tokens. Cela peut tronquer les réponses longues de manière inattendue.

En streaming, gérez les interruptions réseau de manière élégante. Si la connexion tombe, vous pouvez reprendre depuis le dernier chunk reçu si le serveur le prend en charge. Sinon, vous devrez peut-être réessayer la requête entière. Surveillez toujours le usage field in the final chunk to avoid billing surprises.

Meilleures pratiques de streaming :

• Analysez correctement les événements SSE, en ignorant les lignes vides.
• Accumulez les morceaux en mémoire ou dans un tampon.
• Vérifiez le usage objet dans le dernier chunk pour les comptes de jetons.

Erreurs de facturation et arithmétique des jetons

Les erreurs de facturation proviennent souvent d'une mécompréhension du comptage des jetons. Les jetons sont facturés pour l'entrée (prompt) et la sortie (complétion). Nos tarifs sont de 0,15 $ par 1M de jetons d'entrée et de 0,50 $ par 1M de jetons de sortie. Les erreurs et les refus sont gratuits, ce qui réduit les coûts de débogage.

Les tokenizers ne mappent pas toujours 1:1 avec les caractères. Un seul mot peut être plusieurs tokens. Si vous estimez les coûts en fonction du nombre de caractères, vous risquez de sous-estimer la facture. Utilisez une bibliothèque de tokenizer fiable dans votre client pour obtenir des comptes précis avant d'envoyer des requêtes.

Le crédit n'expire pas. Si vous rechargez en crypto, le solde reste disponible jusqu'à son utilisation. Cela est utile pour les projets à long terme. Cependant, sachez que chaque requête consomme des tokens de votre solde. Si votre solde est faible, les requêtes suivantes peuvent échouer.

Conseils de facturation :

• Suivez l'utilisation des tokens dans chaque réponse.
• Mettez en place des alertes pour les seuils de solde bas.
• Utiliser max_tokens pour plafonner les coûts potentiels.

Problèmes de sécurité et de balayage de ports

Les points de terminaison Ollama locaux sont souvent exposés au réseau par défaut. Cela les rend vulnérables aux scanners de ports à la recherche de calcul gratuit. Si vous exposez le port 11434 sans authentification, n'importe qui peut utiliser vos ressources GPU. Cela peut entraîner des factures d'électricité élevées et des performances lentes.

Sécurisez votre point de terminaison en modifiant le port par défaut ou en utilisant un proxy inverse avec authentification. Notre service hébergé gère la sécurité pour vous, vous n'avez donc pas à vous soucier de l'exposition des ports. Vous devez simplement garder votre clé API privée.

Pour les configurations locales, utilisez un pare-feu pour restreindre l'accès aux adresses IP de confiance. Vous pouvez également activer l'authentification par jeton dans le fichier de configuration d'Ollama. Cela empêche les utilisateurs non autorisés d'effectuer des requêtes.

Étapes de sécurité :

• Modifiez le port par défaut si vous l'exposez à Internet.
• Utilisez un proxy inverse avec HTTPS et auth.
• Surveillez votre trafic réseau pour détecter toute activité inhabituelle.

Utilisation API ollama Local vs Cloud

L'utilisation locale vous donne un contrôle total sur la confidentialité des données et la sélection des modèles. Vous pouvez exécuter plusieurs modèles simultanément et passer de l'un à l'autre instantanément. Cependant, vous êtes responsable de la maintenance du matériel, des mises à jour et de la sécurité. L'utilisation cloud décharge ces responsabilités vers le fournisseur.

Notre service cloud propose un modèle sans censure optimisé pour la génération de contenu non restreint. Vous bénéficiez d'un accès instantané sans télécharger de gros fichiers de modèle. L'inconvénient est que vos données transitent par nos serveurs. Pour les données sensibles, une solution locale pourrait être préférable.

Les services cloud ont souvent une latence plus élevée en raison des allers-retours réseau. Les instances locales ont une latence quasi nulle si le GPU est suffisamment rapide. Cependant, les instances locales nécessitent une VRAM importante. Si votre GPU manque de mémoire, le modèle peut basculer vers le CPU, ce qui ralentit considérablement les réponses.

Comparaison :

• Local : Confidentialité, contrôle, dépendance matérielle.
• Cloud : Commodité, évolutivité, transfert de données.

Erreurs courantes côté client

Les développeurs oublient souvent de gérer les limites de débit. Notre service autorise 300 requêtes par minute par clé. Si vous dépassez cette limite, vous recevrez une erreur 429. Implémentez une rétrogradation exponentielle dans votre client pour gérer ces erreurs avec élégance.

Une autre erreur est de ne pas définir le stream parameter correctement. Si vous attendez du streaming mais ne définissez pas stream: true, vous attendrez la réponse entière avant de recevoir des données. Cela peut rendre votre application lente.

Les erreurs de mode JSON sont également courantes. Si vous définissez response_format: {type: "json_object"}, le modèle doit retourner du JSON valide. Si ce n'est pas le cas, votre analyseur échouera. Ajoutez une gestion des erreurs pour intercepter et réessayer l'analyse des erreurs JSON.

Liste de contrôle :

• Implémentez la gestion des limites de débit.
• Définir stream: true pour les mises à jour en temps réel.
• Valider la sortie JSON lors de l'utilisation du mode JSON.