Ollama API: Fejlfinding af almindelige fejl

Forståelse af 100k kontekstvinduet

Den første sætning i hvert afsnit besvarer spørgsmålet i overskriften.

Et kontekstvindue på 100.000 tokens lyder enormt, men det fordeles lige mellem input-prompt og output-completion. Når du sender et langt systemprompt sammen med en lang samtalehistorik, forbruger du denne budget hurtigere, end du måske forventer. Mange udviklere antager, at grænsen kun gælder for input, hvilket fører til afkortede svar eller stille fejl, når modellen rammer sin grænse.

Overvej et scenarie, hvor du sender et dokument på 50.000 tokens som kontekst. Du har kun 50.000 tokens tilbage til den faktiske generering. Hvis du ikke styrer denne balance omhyggeligt, vil modellen afbryde midt i en sætning. Overvåg altid det samlede token-antal sendt i hvert request for at undgå uventet forkortelse.

Max Tokens vs. Default Output Length

Hvert afsnit skal besvare spørgsmålet i sin overskrift.

Medmindre du angiver en grænse, indstiller de fleste APIs standardmæssigt til en beskedn outputlængde, ofte omkring 2.048 tokens. Denne standard er nyttig til korte forespørgsler, men katastrofal til kodegenerering eller langform-skrivning. Hvis du har brug for, at modellen skal producere et manuskript eller en detaljeret analyse, skal du eksplicit indstille max_tokens-parameteren.

Indstilling af denne værdi for højt kan også påvirke latens og omkostninger. Du betaler for hvert token, der genereres, uanset om det er nyttigt eller ej. En pragmatisk tilgang er at indstille en rimelig øvre grænse, der matcher dit brugsscenarie, frem for at lade det være standard eller en vilkårlig uendelighed.

Håndtering af streaming-SSE-chunker korrekt

Streaming kræver omhyggelig håndtering af Server-Sent Events for at undgå tab af data.

Når du aktiverer streaming, returnerer API’et en række små chunks i stedet for et enkelt komplet svar. Hver chunk indeholder et tekstdelta, men vigtige detaljer som tokenbrugsstatistik er ofte kun til stede i den sidste chunk. Hvis du stopper med at parse for tidligt, går du glip af de brugsdata, der er nødvendige til fakturering eller sporing af rate-limits.

Streaming introducerer kompleksitet i fejlhåndtering. Et netværksafbrydelse kan efterlade dig med delvis tekst. Du har brug for en robust parser, der kan rekonstruere den fulde besked fra disse fragmenter. Dette er særligt vigtigt, når du integrerer med UI-komponenter, der render tekst i realtid.

Fejl i definition af værktøjer til Function Calling

Funktionkald fejler, når værktøjsskemaer ikke matcher modellens forventninger.

Modellen forventer en specifik JSON-struktur til værktigsdefinitioner. Hvis du udelader obligatoriske felter eller bruger forkerte typer, kan modellen ignorere værktøjet helt eller returnere en fejlbehæftet respons. Dette er et almindeligt problem for udviklere, der bygger agenter, der skal interagere med eksterne API'er.

Valider dit værktøjsskema mod API-dokumentationen, før du sender anmodninger. Selv små afvigelser, som at bruge et heltal i stedet for en streng til en parameter, kan bryde funktionskaldet. Fejlsøgning af dette kræver inspektion af den rå JSON-svar for at se, om modellen forsøgte at kalde værktøjet overhovedet.

JSON-tilstand svarformatproblemer

JSON-mode tvinger modellen til at outputte gyldig JSON, men den kan stadig hallucinere.

Når du indstiller response_format til json_object, er modellen begrænset til kun at outputte JSON. Dette garanterer dog ikke, at indholdet er semantisk korrekt. Modellen kan producere gyldig JSON-syntax, men med forkerte nøgler eller manglende felter. Du har stadig brug for en parser til at validere strukturen, før du bruger dataene.

Derudover kan JSON-tilstand nogle gange reducere modellens kreativitet eller fleksibilitet. Hvis dit prompt er for komplekst, kan modellen have svært ved at tilpasse fortællingen til en stiv JSON-struktur. Brug denne tilstand primært til udtrækning af strukturerede data eller funktionsargumenter, hvor konsistens er vigtigere end nuancer.

Rate Limiting og Samtidige Anmodninger

Ratebegrænsninger håndhæves per API-nøgle, ikke per bruger eller IP-adresse.

De fleste APIs pålægger en grænse for anmodninger per minut og samtidige forbindelser. Hvis du overskrider disse grænser, modtager du en 429 Too Many Requests-fejl. Dette er kritisk for applikationer, der opretter flere tråde eller processer til at håndtere brugeranmodninger. En enkelt nøgle kan kun håndtere et begrænset antal parallelle anmodninger.

For at håndtere dette skal du implementere eksponentiel backoff i din klientkode. Når du modtager en 429-fejl, skal du vente et kort øjeblik, før du prøver igen. Dette forhindrer, at serveren overbelastes, og sikrer en mere jævn brugeroplevelse. Tjek altid responsheaderne for retry-after-værdier for at optimere dine ventetider.

API Key Replacement Behavior

Regenerering af en API-nøgle ugyldiggør den forrige øjeblikkeligt.

Nogle platforme tillader kun én aktiv nøgle pr. konto. Hvis du genererer en ny nøgle, holder den gamle nøgle op med at virke øjeblikkeligt. Dette kan forårsage nedbrud, hvis du har flere tjenester eller scripts, der bruger den gamle nøgle. Opdater altid alle forekomster af din nøgle, før du roterer den.

Denne adfærd er designet til sikkerhed, hvilket sikrer, at en lækket nøgle ikke kan bruges uendeligt. Det kræver dog omhyggelig styring i distribuerede systemer. Brug miljøvariabler eller hemmelighedsadministratorer til at gemme din nøgle, hvilket gør opdateringer lettere og mindre fejlfølsomme.

Størrelsesbegrænsninger for forespørgselskrop

Store payloads kan overstige grænsen på 8 MB for request-body.

Når du sender lange dokumenter eller billeder kodet som base64, kan request-bodyn vokse hurtigt. Hvis du overskrider størrelsesgrænsen, vil serveren afvise requestet med en 413 Payload Too Large-fejl. Dette er en hard grænse, der ikke kan øges ved at opgradere din plan i mange tilfælde.

For at undgå dette skal du komprimere din input eller opdele store dokumenter i mindre chunks. Du kan også bruge en mere effektiv kodningsmetode til billeder. Overvåg altid størrelsen af dine requests, især når du arbejder med medie-rigt indhold.