Ollama API Troubleshooting Guide

Înțelegerea structurii endpoint-ului API Ollama

The ollama endpoint urmează un model RESTful strict care se potrivește cu structura API-ului OpenAI. Interacționezi cu acesta trimitând cereri POST la /v1/chat/completions și interogarea modelelor disponibile prin GET /v1/models. Această standardizare vă permite să înlocuiți modelele de bază fără a rescrie codul clientului.

Mulți dezvoltatori presupun că endpoint-ul suportă implicit embeddings sau generare de imagini. Nu face acest lucru. Serviciul nostru găzduit, de exemplu, servește doar completări de text cu un singur model uncensored. Verifică întotdeauna GET /v1/models răspuns pentru a vedea exact ce capabilități sunt expuse. Dacă vezi o listă de modele, verifică ID-urile lor înainte de a trimite cereri.

Când folosești o instanță locală, endpoint-ul rulează de obicei pe http://localhost:11434Pentru furnizorii de cloud, vei folosi un URL de bază personalizat. Asigură-te că clientul tău HTTP gestionează corect antetele, în special Content-Type: application/json. Un antet lipsă provoacă adesea eșecuri silențioase care arată ca erori de model.

Elemente structurale cheie:

• model: Identificatorul șir pentru LLM-ul specific.
• messages: Un array de obiecte de conținut bazate pe roluri.
• stream: Un indicator boolean care activează Server-Sent Events (SSE).

De ce apelurile tale API ollama s-ar putea să eșueze

Erorile apelurilor API apar de obicei din cauza URL-urilor de bază incorecte, a cheilor expirate sau a payload-urilor JSON malformed. Cea mai frecventă eroare este răspunsul 401 Unauthorized, care indică faptul că cheia API lipsește sau este invalidă. O altă problemă frecventă este 404 Not Found, care semnalează că endpoint-ul nu suportă calea sau ID-ul modelului solicitat.

Verificați cu atenție corpul solicitării. Dacă trimiteți un parametru pe care endpoint-ul nu îl acceptă, cum ar fi modalities pentru un model doar text, serverul poate respinge cererea. Serviciul nostru, de exemplu, nu suportă input imagine. Trimiterea acestuia rezultă într-o eroare imediată.

Timeout-urile de rețea pot cauza, de asemenea, eșecuri. Dacă instanța locală Ollama este inactivă, este posibil să descarce modelul din VRAM. Prima cerere după un cold start poate dura câteva secunde. Setați un timeout generos în clientul HTTP pentru a evita deconectările premature.

Coduri de eroare comune:

• 400: Bad Request (JSON malformed sau parametri invalizi).
• 401: Neautorizat (cheie API invalidă sau lipsă).
• 429: Prea multe Cereri (limita de rată depășită).
• 500: Internal Server Error (eșec la încărcarea modelului).

Configurarea corectă a modelelor ollama fără cenzură

Modelele nedeplasate necesită adesea parametri specifici pentru a se comporta așa cum se așteaptă. Diferența principală constă în system prompt. Trebuie să instruiți explicit modelul să ocolească refuzurile standard. Fără un prompt de sistem puternic, modelul poate reveni la comportamentele implicite de siguranță.

Endpoint-ul nostru utilizează model ID uncensored.Trimite solicitări către acest ID, iar serverul gestionează selecția modelului underlying. Acest lucru abstractizează complexitatea gestionării versiunilor de modele. Nu trebuie să știi dacă arhitectura underlying este bazată pe Llama sau Mistral.

Ajustează temperature parametrul pentru a controla creativitatea. O valoare de 0.7 este un punct de plecare bun pentru răspunsuri echilibrate. Valorile mai mari cresc aleatorietatea, ceea ce este util pentru scrierea creativă, dar poate reduce acuratețea factuală. Valorile mai mici fac ieșirea mai deterministă.

Sfaturi de configurare:

• Utilizare top_p alături temperature pentru un control mai bun.
• Setează stop secvențe pentru a preveni buclele infinite.
• Include întotdeauna un system mesaj pentru definirea rolului.

Gestionarea streaming-ului și a limitelor de tokeni

Răspunsurile în flux returnează date în fragmente prin Evenimente trimise de server (SSE). Fiecare fragment conține o completare parțială. Trebuie să asamblați aceste fragmente pentru a obține răspunsul complet. Serviciul nostru include statisticile de utilizare a tokenilor în fragmentul final, permițându-vă să urmăriți costurile în timp real.

Limitele de tokeni sunt critice pentru conversațiile lungi. Endpoint-ul nostru suportă o fereastră de context de 100.000 de tokeni, combinând atât promptul, cât și completarea. Totuși, ieșirea maximă pe cerere este de 16.000 de tokeni. Dacă nu setezi max_tokens, valoarea implicită este de 2.048 de tokeni. Acest lucru poate trunca răspunsurile lungi neașteptat.

Când transmiteți în flux, gestionați întreruperile de rețea în mod elegant. Dacă conexiunea se întrerupe, puteți relua de la ultimul fragment primit, dacă serverul suportă acest lucru. În caz contrar, poate fi necesară reîncercarea întregii solicitări. Monitorizați întotdeauna usage câmp în fragmentul final pentru a evita surprizele de facturare.

Cele mai bune practici pentru streaming:

• Analizați corect evenimentele SSE, ignorând liniile goale.
• Acumulează bucățile în memorie sau într-un buffer.
• Verificați usage object în ultimul fragment pentru numărul de token-uri.

Erori de facturare și aritmetică tokeni

Erorile de facturare provin adesea din neînțelegerea modului în care sunt numărate tokenurile. Tokenurile sunt facturate atât pentru input (prompt), cât și pentru output (completare). Tarifele noastre sunt de 0,15 $ per 1M tokenuri de input și 0,50 $ per 1M tokenuri de output. Erorile și refuzurile sunt gratuite, ceea ce reduce costurile pentru depanare.

Tokenizatoarele nu mapează întotdeauna 1:1 cu caracterele. Un singur cuvânt poate fi mai multe tokeni. Dacă estimezi costurile pe baza numărului de caractere, ai putea subestima factura. Folosește o bibliotecă de tokenizare fiabilă în clientul tău pentru a obține numărători precise înainte de a trimite solicitări.

Creditul nu expiră. Dacă alimentezi cu crypto, soldul rămâne disponibil până când îl folosești. Acest lucru este util pentru proiecte pe termen lung. Totuși, ține cont că fiecare cerere consumă tokeni din soldul tău. Dacă soldul este scăzut, cererile ulterioare pot eșua.

Sfaturi de facturare:

• Urmărește utilizarea tokenilor în fiecare răspuns.
• Configurează alerte pentru praguri de sold scăzut.
• Utilizare max_tokens pentru a limita costurile potențiale.

Probleme de securitate și scanare a porturilor

Endpoint-urile Ollama locale sunt adesea expuse rețelei în mod implicit. Acest lucru le face vulnerabile la scanner-e de porturi care caută computație gratuită. Dacă expui portul 11434 fără autentificare, oricine îți poate folosi resursele GPU. Acest lucru poate duce la facturi mari de electricitate și performanță redusă.

Securizați-vă endpoint-ul schimbând portul implicit sau utilizând un proxy invers cu autentificare. Serviciul nostru găzduit se ocupă de securitate pentru dvs., așa că nu trebuie să vă îngrijorați de expunerea porturilor. Trebuie doar să păstrați cheia API privată.

Pentru configurările locale, folosește un firewall pentru a restricționa accesul la adrese IP de încredere. Poți activa, de asemenea, autentificarea bazată pe token în fișierul de configurare Ollama. Acest lucru previne ca utilizatorii neautorizați să facă cereri.

Pași de securitate:

• Schimbă portul implicit dacă expui către internet.
• Folosește un proxy invers cu HTTPS și autentificare.
• Monitorizați traficul de rețea pentru activități neobișnuite.

Utilizare API ollama Local vs Cloud

Utilizarea locală îți oferă control total asupra confidențialității datelor și a selecției modelelor. Poți rula mai multe modele simultan și poți comuta între ele instantaneu. Cu toate acestea, ești responsabil de întreținerea hardware-ului, actualizări și securitate. Utilizarea cloud externalizează aceste responsabilități către furnizor.

Serviciul nostru cloud oferă un model uncensored optimizat pentru generarea de conținut nelimitat. Aveți acces instantaneu fără a descărca fișiere mari de modele. Compromisul este că datele dumneavoastră trec prin serverele noastre. Pentru date sensibile, o soluție locală ar putea fi preferabilă.

Serviciile cloud au adesea latență mai mare din cauza round-trip-urilor de rețea. Instanțele locale au o latență aproape zero dacă GPU este suficient de rapid. Totuși, instanțele locale necesită VRAM semnificativ. Dacă GPU-ul rămâne fără memorie, modelul poate face swap pe CPU, încetinind drastic răspunsurile.

Comparare:

• Local: Confidențialitate, control, dependență de hardware.
• Cloud: Conveniență, scalabilitate, transfer de date.

Erori comune de client

Dezvoltatorii uită adesea să gestioneze limitele de rată. Serviciul nostru permite 300 de cereri pe minut per cheie. Dacă depășești această limită, vei primi o eroare 429. Implementează un backoff exponențial în clientul tău pentru a gestiona aceste erori cu grijă.

O altă greșeală este ne-setarea stream parametru corect. Dacă te aștepți la streaming, dar nu setezi stream: true, vei aștepta întregul răspuns înainte de a primi orice date. Acest lucru poate face ca aplicația ta să pară lentă.

Erorile de mod JSON sunt, de asemenea, comune. Dacă setezi response_format: {type: "json_object"}, modelul trebuie să returneze JSON valid. Dacă nu o face, parserul dumneavoastră va eșua. Adăugați gestionarea erorilor pentru a prinde și reîncerca erorile de analiză JSON.

Listă de verificare:

• Implementați gestionarea limitelor de rată.
• Setează stream: true pentru actualizări în timp real.
• Validează ieșirea JSON când se utilizează modul JSON.