Ollama API: Felsökning vanliga misstag

Förstå 100k kontextfönstret

Den första meningen i varje avsnitt svarar på frågan i dess rubrik.

Ett kontextfönster på 100 000 token låter enormt, men det delas lika mellan indataprompter och utdataslutföranden. När du skickar en lång systemprompt tillsammans med en omfattande konversationshistorik förbrukar du den budgeten snabbare än du kanske tror. Många utvecklare antar att gränsen endast gäller för indata, vilket leder till avklippta svar eller tysta fel när modellen når sin takgräns.

Överväg ett scenario där du skickar ett dokument på 50 000 token som kontext. Du har bara 50 000 token kvar för den faktiska genereringen. Om du inte hanterar denna balans noggrant kommer modellen att klippa av mitt i meningen. Övervaka alltid det totala tokenantalet som skickas i varje begäran för att undvika oväntad trunkering.

Max tokens vs. standard utdatalängd

Varje avsnitt måste besvara frågan i dess rubrik.

Om du inte anger en gräns, använder de flesta API:n som standard en blygsam utdatalängd, ofta runt 2 048 tokens. Denna standard är användbar för korta frågor men katastrofal för kodgenerering eller långt skrivande. Om du behöver att modellen producerar ett fullständigt manus eller en detaljerad analys måste du explicit ange parametern max_tokens.

Att ställa in detta värde för högt kan också påverka latens och kostnad. Du betalar för varje token som genereras, oavsett om den är användbar eller inte. En pragmatisk approach är att sätta en rimlig övre gräns som matchar ditt användningsfall, snarare än att lämna det till standardvärdet eller en godtycklig oändlighet.

Korrekt hantering av strömnings-SSE-chunker

Strömning kräver noggrann hantering av Server-Sent Events för att undvika dataförlust.

När du aktiverar strömning returnerar API:et en serie små bitar snarare än ett enda komplett svar. Varje bit innehåller en textdelta, men viktiga detaljer som tokenanvändningsstatistik finns ofta bara i den sista biten. Om du slutar parsa för tidigt missar du den användningsdata som behövs för fakturering eller spårning av hastighetsbegränsningar.

Strömning introducerar komplexitet i felhantering. Ett nätverksavbrott kan lämna dig med delvis text. Du behöver en robust parser som kan rekonstruera hela meddelandet från dessa fragment. Detta är särskilt sant när du integrerar med UI-komponenter som renderar text i realtid.

Fel vid definition av verktyg för funktionsanrop

Funktionsanrop misslyckas när verktygsscheman inte matchar modellens förväntningar.

Modellen förväntar sig en specifik JSON-struktur för verktygsdefinitioner. Om du utelämnar obligatoriska fält eller använder felaktiga typer kan modellen ignorera verktyget helt eller returnera ett felaktigt svar. Detta är ett vanligt problem för utvecklare som bygger agenter som behöver interagera med externa API:er.

Validera alltid ditt verktygsschema mot API-dokumentationen innan du skickar förfrågningar. Även små avvikelser, som att använda ett heltal istället för en sträng för en parameter, kan bryta funktionskallet. Att felsöka detta kräver att du inspekterar det råa JSON-svaret för att se om modellen försökte anropa verktyget överhuvudtaget.

JSON-läge-svarsformatproblem

JSON-läget tvingar modellen att returnera giltig JSON, men den kan fortfarande hallucinera.

När du ställer in response_format till json_object är modellen begränsad att endast outputa JSON. Detta garanterar dock inte att innehållet är semantiskt korrekt. Modellen kan producera giltig JSON-syntax men med fel nycklar eller saknade fält. Du behöver fortfarande en parser för att validera strukturen innan du använder datan.

Dessutom kan JSON-läget ibland minska modellens kreativitet eller flexibilitet. Om din prompt är för komplex kan modellen ha svårt att få in berättelsen i en stel JSON-struktur. Använd detta läge främst för extrahering av strukturerad data eller funktionsargument där konsekvens är viktigare än nyans.

Begäransgräns och samtidiga begäranden

Rate limits är upprätthållna per API-nyckel, inte per användare eller IP-adress.

De flesta API:n sätter en gräns för förfrågningar per minut och parallella anslutningar. Om du överskrider dessa gränser får du ett felmeddelande 429 Too Many Requests. Detta är kritiskt för applikationer som skapar flera trådar eller processer för att hantera användarbegäranden. En enda nyckel kan bara hantera ett begränsat antal parallella förfrågningar.

För att hantera detta bör du implementera exponentiell backoff i din klientkod. När du får ett 429-fel bör du vänta en kort stund innan du försöker igen. Detta förhindrar att servern överbelastas och säkerställer en smidigare användarupplevelse. Kontrollera alltid svarshuvudena för retry-after-värden för att optimera dina väntetider.

API Key Replacement Behavior

Regenerering av en API-nyckel ogiltigförklarar den tidigare omedelbart.

Vissa plattformar tillåter bara en aktiv nyckel per konto. Om du genererar en ny nyckel slutar den gamla att fungera omedelbart. Detta kan orsaka driftstopp om du har flera tjänster eller skript som använder den gamla nyckeln. Uppdatera alltid alla instanser av din nyckel innan du roterar den.

Detta beteende är utformat för säkerhet, vilket säkerställer att en läckt nyckel inte kan användas oändligt. Det kräver dock noggrann hantering i distribuerade system. Använd miljövariabler eller hemlighetshanterare för att lagra din nyckel, vilket gör uppdateringar enklare och mindre felkänsliga.

Begränsningar för begärans kroppsstorlek

Stora payloads kan överskrida gränsen för begärans kropp på 8 MB.

När du skickar långa dokument eller bilder kodade som base64 kan begärans kropp växa snabbt. Om du överskrider storleksgränsen kommer servern att avvisa begäran med ett 413 Payload Too Large-fel. Detta är en hård gräns som inte kan höjas genom att uppgradera ditt abonnemang i många fall.

För att undvika detta, komprimera din input eller dela upp stora dokument i mindre bitar. Du kan också använda en mer effektiv kodningsmetod för bilder. Övervaka alltid storleken på dina förfrågningar, särskilt när du hanterar medierikt innehåll.