Ollama API-foutoplossingsgids

De structuur van het ollama API-eindpunt begrijpen

De ollama endpoint volgt een strikt RESTful patroon dat de structuur van de OpenAI API nabootst. U interacteert ermee door POST-verzoeken te sturen naar /v1/chat/completions en het opvragen van beschikbare modellen via GET /v1/models. Deze standaardisatie stelt u in staat om onderliggende modellen te verwisselen zonder uw clientcode te herschrijven.

Veel ontwikkelaars gaan ervan uit dat het endpoint embeddings of beeldgeneratie standaard ondersteunt. Dat doet het niet. Onze gehoste service biedt bijvoorbeeld alleen tekstcompleties met één uncensored model. Controleer altijd de GET /v1/models response om precies te zien welke mogelijkheden worden blootgesteld. Als je een lijst met modellen ziet, controleer dan hun IDs voordat je verzoeken verstuurt.

Wanneer u een lokale instantie gebruikt, draait het endpoint meestal op http://localhost:11434. Voor cloudproviders gebruik je een aangepaste base URL. Zorg dat je HTTP-client headers correct afhandelt, vooral Content-Type: application/json. Een ontbrekende header veroorzaakt vaak stille fouten die op modelfouten lijken.

Belangrijkste structurele elementen:

• model: De string-id voor de specifieke LLM.
• messages: Een array van role-gebaseerde contentobjecten.
• stream: Een boolean vlag die Server-Sent Events (SSE) inschakelt.

Waarom je ollama API-aanroepen kunnen falen

API-aanroepen falen meestal door onjuiste base URLs, verlopen sleutels of slecht gevormde JSON-payloads. De meest voorkomende fout is een 401 Unauthorized-antwoord, wat betekent dat je API-sleutel ontbreekt of ongeldig is. Een ander veelvoorkomend probleem is een 404 Not Found, wat aangeeft dat het eindpunt het opgevraagde pad of model-ID niet ondersteunt.

Controleer je request body zorgvuldig. Als je een parameter verstuurt die het eindpunt niet ondersteunt, zoals modalities voor een tekstmodel kan de server het verzoek afwijzen. Onze service ondersteunt bijvoorbeeld geen beeldinput. Het verzenden hiervan resulteert in een directe fout.

Time-outs veroorzaken ook fouten. Als je lokale Ollama-instantie inactief is, kan het model uit VRAM worden geladen. De eerste request na een koude start kan enkele seconden duren. Stel een ruime timeout in je HTTP-client in om voortijdige verbreekkingen te voorkomen.

Veelvoorkomende foutcodes:

• 400: Bad Request (ongeldige JSON of ongeldige parameters).
• 401: Niet geautoriseerd (ongeldige of ontbrekende API-sleutel).
• 429: Te veel verzoeken (rate limit overschreden).
• 500: Internal Server Error (model laadfout).

Ongecensureerde ollama-modellen correct configureren

Ongeschoolde modellen vereisen vaak specifieke parameters om zich naar verwachting te gedragen. Het primaire verschil ligt in de system prompt. Je moet het model expliciet instrueren om standaardweigeringen te omzeilen. Zonder een sterke system prompt kan het model terugvallen op standaard veiligheidsgedrag.

Ons endpoint gebruikt de model ID uncensored. Je verzendt verzoeken naar deze ID, en de server behandelt de onderliggende modelselectie. Dit abstrahiert de complexiteit van het beheren van modelversies. Je hoeft niet te weten of de onderliggende architectuur op Llama of Mistral is gebaseerd.

Pas de temperature parameter om creativiteit te beheersen. Een waarde van 0,7 is een goed startpunt voor gebalanceerde reacties. Hogere waarden verhogen de willekeurigheid, wat nuttig is voor creatief schrijven, maar kan de feitelijke nauwkeurigheid verminderen. Lagere waarden maken de uitvoer deterministischer.

Configuratie tips:

• Gebruik top_p naast temperature voor meer controle.
• Instellen stop sequenties om oneindige lussen te voorkomen.
• Voeg altijd een system bericht voor roldefinitie.

Streamen en tokenlimieten verwerken

Streamingresponsen retourneren gegevens in chunks via Server-Sent Events (SSE). Elke chunk bevat een gedeeltelijke voltooiing. Je moet deze chunks samenvoegen om de volledige respons te krijgen. Onze dienst bevat tokengebruiksstatistieken in de laatste chunk, zodat je kosten in realtime kunt bijhouden.

Tokenlimieten zijn cruciaal voor lange gesprekken. Ons endpoint ondersteunt een contextvenster van 100.000 tokens, zowel prompt als completion samen. De maximale output per request is echter 16.000 tokens. Als je max_tokens niet instelt, is de limiet 2.048 tokens. max_tokens, de standaardwaarde is 2.048 tokens. Dit kan lange antwoorden onverwacht afkappen.

Bij streaming, verwerk netwerkonderbrekingen soepel. Als de verbinding verbroken is, kunt u hervatten vanaf het laatst ontvangen chunk als de server dit ondersteunt. Anders moet u misschien de hele request opnieuw proberen. Houd altijd de usage veld in het laatste chunk om verrassingen bij de facturatie te voorkomen.

Beste praktijken voor streaming:

• Parseer SSE-gebeurtenissen correct, negeer lege regels.
• Accumuleer chunks in geheugen of een buffer.
• Controleer de usage object in de laatste chunk voor tokenaantallen.

Facturatiefouten en Token-rekenkunde

Facturatiefouten ontstaan vaak door een onjuist begrip van hoe tokens worden geteld. Tokens worden in rekening gebracht voor zowel input (prompt) als output (completion). Onze prijzen zijn $0.15 per 1M inputtokens en $0.50 per 1M outputtokens. Fouten en weigeringen zijn gratis, wat de kosten voor debugging verlaagt.

Tokenizers mapperen niet altijd 1:1 met tekens. Een enkel woord kan meerdere tokens zijn. Als je kosten schat op basis van tekenaantal, onderschat je mogelijk de rekening. Gebruik een betrouwbare tokenizer-bibliotheek in je client om nauwkeurige tellingen te krijgen voordat je aanvragen verzendt.

Credit vervalt niet. Als je met crypto stort, blijft het saldo beschikbaar totdat je het gebruikt. Dit is handig voor langetermijnprojecten. Houd er echter rekening mee dat elke request tokens van je saldo verbruikt. Als je saldo laag is, kunnen volgende requests falen.

Factureringstips:

• Volg tokengebruik in elke respons.
• Stel meldingen in voor lage balansdrempels.
• Gebruik max_tokens om potentiële kosten te beperken.

Beveiligings- en poortscanningproblemen

Lokale Ollama-eindpunten worden vaak standaard aan het netwerk blootgesteld. Dit maakt ze kwetsbaar voor portscanners die op zoek zijn naar gratis rekenkracht. Als je poort 11434 blootstelt zonder authenticatie, kan iedereen je GPU-resources gebruiken. Dit kan leiden tot hoge elektriciteitsrekeningen en langzame prestaties.

Beveilig je eindpunt door de standaardpoort te wijzigen of een reverse proxy met authenticatie te gebruiken. Onze gehoste service neemt de beveiliging voor zijn rekening, dus je hoeft je geen zorgen te maken over poortblootstelling. Je hoeft alleen je API-sleutel privé te houden.

Gebruik voor lokale setup een firewall om de toegang te beperken tot vertrouwde IP-adressen. Je kunt ook tokengebaseerde authenticatie inschakelen in het configuratiebestand van Ollama. Dit voorkomt dat ongeautoriseerde gebruikers verzoeken uitvoeren.

Stappen voor beveiliging:

• Wijzig de standaardpoort als je dit aan het internet blootstelt.
• Gebruik een reverse proxy met HTTPS en auth.
• Monitor uw netwerkverkeer op ongebruikelijke activiteit.

Lokaal vs Cloud ollama API Gebruik

Lokaal gebruik geeft je volledige controle over gegevensprivacy en modelselectie. Je kunt meerdere modellen tegelijkertijd draaien en er direct tussen schakelen. Je bent echter verantwoordelijk voor hardwareonderhoud, updates en beveiliging. Cloudgebruik verplaatst deze verantwoordelijkheden naar de aanbieder.

Onze clouddienst biedt een ongefilterd model dat geoptimaliseerd is voor onbeperkte inhoudsgeneratie. Je krijgt direct toegang zonder grote modelbestanden te hoeven downloaden. Het nadeel is dat je gegevens via onze servers lopen. Voor gevoelige gegevens kan lokaal opslaan de voorkeur hebben.

Cloudservices hebben vaak een hogere latentie door netwerkroundtrips. Lokale instanties hebben bijna nul latentie als de GPU snel genoeg is. Lokale instanties vereisen echter aanzienlijk VRAM. Als je GPU het geheugen uitgaat, kan het model naar de CPU wisselen, wat de reactietijden drastisch verlaagt.

Vergelijking:

• Lokaal: Privacy, controle, hardware-afhankelijkheid.
• Cloud: Gemak, schaalbaarheid, gegevensoverdracht.

Veelgemaakte fouten aan de clientkant

Ontwikkelaars vergeten vaak om om te gaan met rate limits. Onze service staat 300 verzoeken per minuut per sleutel toe. Als je dit overschrijdt, ontvang je een 429-fout. Implementeer exponentiële backoff in je client om deze fouten soepel af te handelen.

Een andere fout is het niet instellen van de stream parameter correct. Als u streaming verwacht maar niet stream: true, wacht je tot de volledige respons is ontvangen voordat je data ontvangt. Dit kan je app langzaam laten aanvoeren.

JSON-modusfouten komen ook vaak voor. Als je response_format: {type: "json_object"}, het model moet geldige JSON retourneren. Als het dat niet doet, faalt je parser. Voeg foutafhandeling toe om JSON-parseringsfouten op te vangen en opnieuw te proberen.

Checklist:

• Implementeer rate limit-handling.
• Instellen stream: true voor realtime updates.
• JSON-output valideren bij gebruik van JSON-modus.