Ollama API: Veelgemaakte fouten bij foutoplossing

Het 100k-contextvenster begrijpen

De eerste zin van elke sectie beantwoordt de vraag in de kop.

Een contextvenster van 100.000 tokens klinkt enorm, maar het verdeelt zich gelijkmatig over input-prompts en output-completions. Wanneer je een lang systeemprompt verstuurt samen met een uitgebreide gespreks geschiedenis, verbruik je die budget sneller dan je misschien verwacht. Veel ontwikkelaars veronderstellen dat de limiet alleen op de input van toepassing is, wat leidt tot afgekapt responses of stille fouten wanneer het model zijn plafond bereikt.

Overweeg een scenario waarin je een document van 50.000 tokens doorgeeft als context. Je hebt nog maar 50.000 tokens over voor de daadwerkelijke generatie. Als je dit saldo niet zorgvuldig beheert, onderbreekt het model de zin halverwege. Bewaak altijd het totale aantal tokens dat in elk verzoek wordt verzonden om onverwachte truncatie te vermijden.

Max Tokens vs. Standaard Uitvoergrootte

Elke sectie moet de vraag in de kop beantwoorden.

Tenzij je een limiet specificeert, hebben de meeste API's standaard een bescheiden uitvoerlengte, vaak rond de 2.048 tokens. Deze standaard is handig voor korte queries, maar rampzalig voor codegeneratie of langvormig schrijven. Als je wilt dat het model een volledig script of een gedetailleerde analyse produceert, moet je de parameter max_tokens expliciet instellen.

Deze waarde te hoog instellen kan ook van invloed zijn op latentie en kosten. Je betaalt voor elke gegenereerde token, nuttig of niet. Een pragmatische aanpak is het instellen van een redelijke bovengrens die past bij je use case, in plaats van het over te laten aan de standaardwaarde of een willekeurige oneindigheid.

Stream-SSE-chunks correct verwerken

Streaming vereist zorgvuldige afhandeling van Server-Sent Events om gegevensverlies te voorkomen.

Wanneer je streaming inschakelt, retourneert de API een reeks kleine brokken in plaats van een enkele volledige reactie. Elk brok bevat een tekstdelta, maar cruciale details zoals tokenverbruikstatistieken zijn vaak alleen aanwezig in het laatste brok. Als je te vroeg stopt met parseren, mis je de verbruiksgegevens die nodig zijn voor facturatie of het bijhouden van rate limits.

Streaming introduceert complexiteit in foutafhandeling. Een netwerkonderbreking kan achterblijven met gedeeltelijke tekst. Je hebt een robuuste parser nodig die de volledige bericht kan reconstrueren uit deze fragmenten. Dit is vooral belangrijk bij integratie met UI-componenten die tekst in realtime weergeven.

Fouten bij definitie van tools voor Function Calling

Function calling faalt wanneer toolschema's niet overeenkomen met de verwachtingen van het model.

Het model verwacht een specifieke JSON-structuur voor tool-definities. Als je verplichte velden weglaat of verkeerde typen gebruikt, kan het model de tool volledig negeren of een onjuiste respons teruggeven. Dit is een veelvoorkomend struikelblok voor ontwikkelaars die agents bouwen die met externe API's moeten communiceren.

Valideer je tool-schema altijd tegen de API-documentatie voordat je verzoeken verstuurt. Zelfs kleine afwijkingen, zoals het gebruik van een integer in plaats van een string voor een parameter, kunnen de functieaanroep breken. Het debuggen hiervan vereist het inspecteren van de ruwe JSON-response om te zien of het model überhaupt heeft geprobeerd de tool aan te roepen.

Problemen met responsformaat JSON-modus

De JSON-modus forceert het model om geldige JSON uit te voeren, maar het kan nog steeds hallucineren.

Wanneer je response_format instelt op json_object, is het model beperkt tot het uitvoeren van alleen JSON. Dit garandeert echter niet dat de inhoud semantisch correct is. Het model kan wel geldige JSON-syntax genereren, maar met verkeerde sleutels of ontbrekende velden. Je hebt nog steeds een parser nodig om de structuur te valideren voordat je de gegevens gebruikt.

Bovendien kan JSON-modus de creativiteit of flexibiliteit van het model soms verminderen. Als je prompt te complex is, kan het model moeite hebben om het verhaal in een starre JSON-structuur te passen. Gebruik deze modus voornamelijk voor het extraheren van gestructureerde gegevens of functie-argumenten waar consistentie belangrijker is dan nuance.

Rate Limiting en gelijktijdige verzoeken

Rate limits worden afgedwongen per API-sleutel, niet per gebruiker of IP-adres.

De meeste API's stellen een limiet aan requests per minuut en gelijktijdige verbindingen. Als je deze limieten overschrijdt, ontvang je een 429 Too Many Requests fout. Dit is kritiek voor applicaties die meerdere threads of processen starten om gebruikersverzoeken af te handelen. Een enkele key kan slechts een beperkt aantal parallelle requests af.

Om dit te beheren, implementeer je exponentiële backoff in je clientcode. Wacht een korte tijd voordat je opnieuw probeert wanneer je een 429-fout ontvangt. Dit voorkomt dat de server wordt overbelast en zorgt voor een soepelere gebruikerservaring. Controleer altijd de antwoordheaders op retry-after-waarden om je wachttijden te optimaliseren.

Gedrag bij vervanging API-sleutel

Het regenereren van een API-sleutel maakt de vorige sleutel onmiddellijk ongeldig.

Sommige platforms staan slechts één actieve sleutel per account toe. Als je een nieuwe sleutel genereert, stopt de oude sleutel onmiddellijk met werken. Dit kan uitval veroorzaken als je meerdere services of scripts hebt die de oude sleutel gebruiken. Werk altijd alle instanties van je sleutel bij voordat je deze draait.

Dit gedrag is ontworpen voor veiligheid, zodat een gelekte sleutel niet oneindig gebruikt kan worden. Dit vereist echter zorgvuldig beheer in gedistribueerde systemen. Gebruik omgevingsvariabelen of secret managers om je sleutel op te slaan, waardoor updates eenvoudiger en minder foutgevoelig zijn.

Limieten voor de grootte van het verzoeklichaam

Grote payloads kunnen de limiet van 8 MB voor de request body overschrijden.

Bij het verzenden van lange documenten of afbeeldingen gecodeerd als base64, kan de requestbody snel groeien. Als u de groottelimiet overschrijdt, wijst de server de request af met een 413 Payload Too Large-fout. Dit is een harde limiet die in veel gevallen niet kan worden verhoogd door uw abonnement te upgraden.

Om dit te vermijden, comprimeer je je input of split je grote documenten in kleinere brokken. Je kunt ook een efficiëntere coderingsmethode voor afbeeldingen gebruiken. Monitor altijd de grootte van je verzoeken, vooral bij media-rijke inhoud.