Ollama API-felsökningsguide

Ollama API-endpunktens struktur

The ollama endpoint följer ett strikt RESTful-mönster som speglar OpenAI API-strukturen. Du interagerar med det genom att skicka POST-begäranden till /v1/chat/completions och fråga efter tillgängliga modeller via GET /v1/models. Denna standardisering gör att du kan byta underliggande modeller utan att skriva om klientkoden.

Många utvecklare antar att slutpunkten stöder inbäddningar eller bildgenerering som standard. Det gör den inte. Vårt värdade tjänst, till exempel, serverar endast textkompletteringar med en enda uncensored-modell. Kontrollera alltid GET /v1/models svar för att se exakt vilka funktioner som exponeras. Om du ser en lista över modeller, verifiera deras ID:n innan du skickar begäranden.

När du använder en lokal instans körs slutpunkten vanligtvis på http://localhost:11434. För molnleverantörer använder du en anpassad bas-URL. Säkerställ att din HTTP-klient hanterar rubriker korrekt, särskilt Content-Type: application/json. En saknad header orsakar ofta tysta fel som ser ut som modellfel.

Strukturella element:

• model: Strängidentifieraren för den specifika LLM:n.
• messages: En matris med rollbaserade innehållsobjekt.
• stream: En boolesk flagga som aktiverar Server-Sent Events (SSE).

Varför dina ollama-API-anrop kan misslyckas

API-anrop misslyckas vanligtvis på grund av felaktiga bas-URL:er, utgångna nycklar eller felaktiga JSON-payloads. Det vanligaste felet är ett 401 Unauthorized-svar, vilket betyder att din API-nyckel saknas eller är ogiltig. Ett annat vanligt problem är ett 404 Not Found-fel, vilket indikerar att slutpunkten inte stiger den begärda sökvägen eller modell-ID:t.

Kontrollera din begärans kropp noggrant. Om du skickar en parameter som ändpunkten inte stöder, såsom modalities för en textendast modell kan servern avvisa begäran. Vår tjänst stöder till exempel inte bildinmatning. Att skicka den resulterar i ett omedelbart fel.

Tidsöverstegningar kan också orsaka fel. Om din lokala Ollama-instans är inaktiv kan den ladda ner modellen från VRAM. Den första förfrågan efter en kallstart kan ta flera sekunder. Ställ in en generös tidsgräns i din HTTP-klient för att undvika förtida frånkopplingar.

Vanliga felkoder:

• 400: Bad Request (ogiltig JSON eller ogiltiga parametrar).
• 401: Obehörig (ogiltig eller saknad API-nyckel).
• 429: För många begäranden (gränsöverskridning för begäranden).
• 500: Internt serverfel (modulladdningsfel).

Konfigurera obegränsade ollama-modeller korrekt

Oucensurerade modeller kräver ofta specifika parametrar för att bete sig som förväntat. Den primära skillnaden ligger i system prompt. Du måste uttryckligen instruera modellen att kringgå standardavvisningar. Utan en stark systemprompt kan modellen återgå till standard säkerhetsbeteenden.

Vår endpoint använder model ID:t uncensored. Du skickar begäranden till detta ID, och servern hanterar underliggande modellval. Detta abstraherar bort komplexiteten med att hantera modellversioner. Du behöver inte veta om den underliggande arkitekturen baseras på Llama eller Mistral.

Justera temperature parametern för att kontrollera kreativiteten. Ett värde på 0,7 är en bra utgångspunkt för balanserade svar. Högre värken ökar slumpmässigheten, vilket är användbart för kreativt skrivande men kan minska den faktiska noggrannheten. Lägre värden gör utdatan mer deterministisk.

Konfigurationstips:

• Använd top_p bredvid temperature för bättre kontroll.
• Ställ in stop sekvenser för att förhindra oändliga loopar.
• Inkludera alltid en system meddelande för rolldefinition.

Hantering av strömning och tokenbegränsningar

Streaming-responder returnerar data i delar via Server-Sent Events (SSE). Varje del innehåller en ofullständig slutförande. Du måste montera ihop dessa delar för att få hela svaret. Vår tjänst inkluderar tokenanvändningsstatistik i den sista delen, vilket gör att du kan spåra kostnader i realtid.

Tokengränser är kritiska för långa konversationer. Vår endpoint stöder en kontextruta på 100 000 tokens, vilket kombinerar både prompt och slutförande. Den maximala utdatan per begäran är dock 16 000 tokens. Om du inte anger max_tokens, standardvärdet är 2 048 tokens. Detta kan klippa av långa svar oväntat.

När du strömmar, hantera nätverksavbrott på ett elegant sätt. Om anslutningen bryts kan du återuppta från den sista mottagna biten om servern stöder det. Annars kan du behöva försöka om hela begäran. Överviga alltid den usage field in the final chunk to avoid billing surprises.

Bästa praxis för strömning:

• Parsera SSE-händelser korrekt och ignorerar tomma rader.
• Ackumulera bitar i minne eller en buffert.
• Kontrollera usage objekt i den sista chunken för tokenantal.

Faktureringsfel och tokenaritmetik

Faktureringsfel beror ofta på missförstånd kring hur tokens räknas. Tokens debiteras för både inmatning (prompt) och utmatning (komplettering). Vårt pris är $0,15 per 1M inmatningstokens och $0,50 per 1M utmatningstokens. Fel och avslag är kostnadsfria, vilket minskar kostnaderna för felsökning.

Tokenisatorer avbildar inte alltid 1:1 mot tecken. Ett enda ord kan vara flera tokens. Om du uppskattar kostnader baserat på teckenantal kan du underskatta fakturan. Använd en tillförlitlig tokeniseringsbibliotek i din klient för att få exakta antal innan du skickar begäranden.

Kredit löper inte ut. Om du fyller på med krypto förblir balansen tillgänglig tills du använder den. Detta är användbart för långsiktiga projekt. Var dock medveten om att varje begäran förbrukar tokens från din balans. Om din balans är låg kan efterföljande begäran misslyckas.

Fakturerings tips:

• Spåra tokenförbrukning i varje respons.
• Skapa varningar för låga saldon.
• Använd max_tokens för att begränsa potentiella kostnader.

Säkerhets- och portscanningproblem

Lokala Ollama-slutpunkter exponeras ofta för nätverket som standard. Detta gör dem sårbara för portscannrar som letar efter gratis beräkningskraft. Om du exponerar port 11434 utan autentisering kan vem som helst använda dina GPU-resurser. Detta kan leda till höga elräkningar och långsam prestanda.

Säkra din slutpunkt genom att ändra standardporten eller använda en reverse proxy med autentisering. Vår hostade tjänst hanterar säkerheten åt dig, så du behöver inte oroa dig för portexponering. Du behöver bara hålla din API-nyckel privat.

För lokala installationer, använd en brandvägg för att begränsa åtkomst till betrodda IP-adresser. Du kan också aktivera tokenbaserad autentisering i Ollamas konfigurationsfil. Detta förhindrar att obehöriga användare gör förfrågningar.

Säkerhetssteg:

• Ändra standardporten om du exponerar för internet.
• Använd en omvänd proxy med HTTPS och auth.
• Övervaka din nätverkstrafik för onormal aktivitet.

Lokal mot Moln ollama API-användning

Lokal användning ger dig full kontroll över dataintegritet och modellval. Du kan köra flera modeller samtidigt och växla mellan dem omedelbart. Du är dock ansvarig för hårdvarunderhåll, uppdateringar och säkerhet. Molnanvändning avlastar dessa ansvar till leverantören.

Vår molntjänst erbjuder en uncensored-modell som är optimerad för osorterad innehållsgenerering. Du får omedelbar åtkomst utan att ladda ner stora modelfiler. Nackdelen är att din data passerar genom våra servrar. För känslig data kan lokal körning vara att föredra.

Molntjänster har ofta högre latens på grund av nätverksrundresor. Lokala instanser har nästan noll latens om GPU:n är snabb nog. Lokala instanser kräver dock betydande VRAM. Om ditt GPU tar slut på minne kan modellen byta till CPU, vilket sänker svarstiden avsevärt.

Jämförelse:

• Lokal: Integritet, kontroll, hårdvaruberoende.
• Moln: Bekvämlighet, skalbarhet, dataöverföring.

Vanliga klientfel

Utvecklare glömmer ofta att hantera hastighetsbegränsningar. Vår tjänst tillåter 300 förfrågningar per minut per nyckel. Om du överskrider detta får du ett 429-fel. Implementera exponentiell backoff i din klient för att hantera dessa fel på ett smidigt sätt.

Ett annat misstag är att inte ställa in stream parameter korrekt. Om du förväntar dig strömning men inte ställer in stream: true, kommer du att vänta på hela svaret innan du tar emot någon data. Detta kan få din app att kännas långsam.

JSON-lägesfel är också vanliga. Om du ställer in response_format: {type: "json_object"}, måste modellen returnera giltig JSON. Om den inte gör det kommer din parser att misslyckas. Lägg till felhantering för att fånga och försöka om JSON-parsering vid fel.

Checklista:

• Implementera hantering av hastighetsbegränsning.
• Ställ in stream: true för realtidsuppdateringar.
• Validera JSON-utdata vid användning av JSON-läge.