Ollama API hibaelhárítási útmutató

Az ollama API végpont struktúrájának meggtása

A ollama endpoint szigorú RESTful mintát követ, amely tükrözi az OpenAI API struktúráját. Ezzel úgy kommunikál, hogy POST kéréseket küld /v1/chat/completions és az elérhető modellek lekérdezése a GET /v1/models. Ez a szabványosítás lehetővé teszi, hogy cserélje a háttérmodelleket ügyfélkód-átírás nélkül.

Sok fejlesztő azt feltételezi, hogy az endpoint alapértelmezetten támogatja az embeddingeket vagy a képgenerálást. Nem. Szolgáltatóink például csak szövegkiegészítéseket szolgálunk ki egyetlen uncensored modellel. Mindig ellenőrizze a GET /v1/models választ, hogy pontosan lásd, mely képességek vannak kitéve. Ha modellsort látsz, ellenőrizd az azonosítóikat a kérések küldése előtt.

Helyi példány használatakor az endpoint általában a http://localhost:11434. Felhőszolgáltatók esetén egy egyéni alap URL-t fogsz használni. Győződj meg róla, hogy az HTTP kliensed helyesen kezeli a fejléceket, különösen Content-Type: application/json. Egy hiányzó fejléc gyakran csendes hibákat okoz, amelyek modellhibának tűnnek.

Főbb szerkezeti elemek:

• modelA specifikus LLM azonosító karakterlánc.
• messages: Szerep alapú tartalomobjektumok tömbje.
• stream: Egy logikai flag, amely engedélyezi a Server-Sent Events (SSE) használatát.

Miért hibázhatnak az ollama API-hívások

Az API hívások általában hibára futnak helytelen base URL-ek, lejárt kulcsok vagy hibás JSON payloadok miatt. A leggyakoribb hiba a 401 Unauthorized válasz, ami azt jelenti, hogy az API kulcsa hiányzik vagy érvénytelen. Egy másik gyakori probléma a 404 Not Found, ami azt jelzi, hogy a végpont nem támogatja a kért elérési utat vagy modell azonosítót.

Ellenőrizze a request body-t. Ha egy olyan paramétert küld, amelyet az endpoint nem támogat, mint például modalities egy tisztán szöveges modell esetén a szerver elutasíthatja a kérést. Szolgáltatásunk például nem támogatja a bemeneti képeket. Küldése azonnali hibát eredményez.

Az időtúllépések szintén hibákat okoznak. Ha a helyi Ollama példány tétlen, az eltávolíthatja a modellt a VRAM-ból. Az első kérés egy hideg indítás után több másodpercet is igénybe vehet. Állítson be egy bő időtúllépést az HTTP ügyfélben az idő előtti lekapcsolás elkerülése érdekében.

Gyakori hibakódok:

• 400: Hibás kérés (hibás JSON vagy érvénytelen paraméterek).
• 401Hitelesítetlen (érvénytelen vagy hiányzó API kulcs).
• 429Túl sok kérés (sebességkorlát túllépve).
• 500: Belső kiszolgálóhiba (modell betöltési hiba).

Az uncensored ollama modellek helyes konfigurálása

Az uncensored modellek gyakran specifikus paramétereket igényelnek a várt viseléshez. A fő különbség a system prompt. Explicit módon utasítania kell a modellt a standard visszautalások megkerülésére. Erős rendszer prompt nélkül a modell visszatérhet a alapértelmezett biztonsági viselkedéshez.

A végpont a következő modell azonosítót használja uncensored. Kéréseket küldesz erre az azonosítóhoz, és a szerver kezeli az alapmodell-választást. Ez elrejti a modellverziók kezelésének komplexitását. Nem kell tudnod, hogy az alaparchitektúra Llama-alapú vagy Mistral-alapú-e.

Állítsa be a temperature paramétert a kreativitás kontrollálására. Egy 0,7-es érték jó kiindulási pont a kiegyensúlyozott válaszokhoz. A magasabb értékek növelik a véletlenszerűséget, ami hasznos lehet kreatív íráshoz, de csökkentheti a ténybeli pontosságot. Az alacsonyabb értékek determinisztikusabbá teszik a kimenetet.

Konfigurációs tippek:

• Használat top_p mellett temperature jobb vezérléshez.
• Beállítás stop szekvenciák a végtelen hurok megelőzésére.
• Mindig tartalmazzon egy system üzenat a szerep meghatározásához.

Streamelés és tokenkorlátok kezelése

A streamelő válaszok Server-Sent Events (SSE) segítségével darabokban adják vissza az adatokat. Minden darab egy részleges kiegészítést tartalmaz. Ezeket a darabokat össze kell állítania a teljes válasz megszerzéséhez. Szolgáltatásunk token-használati statisztikákat tartalmaz az utolsó darabban, így valós időben nyomon követheti a költségeket.

A tokenkorlátok kritikusak a hosszú beszélgetésekhez. Endpointunk 100 000 tokenes kontextusablakot támogat, amely a promptot és a kiegészítést együtt foglalja magában. A kérésenkénti maximális kimenet azonban 16 000 token. Ha nem állítod be max_tokens, az alapértelmezett érték 2 048 token. Ez váratlanul levághatja a hosszú válaszokat.

Streamelés közben kezelje gracefully a hálózati megszakításokat. Ha a kapcsolat megszakad, a szerver támogatása esetén a legutóbbi kapott töredéktől folytathatja. Ellenkező esetben az egész kérést újra kell indítania. Mindig figyelje a usage field in the final chunk to avoid billing surprises.

Streamelés legjobb gyakorlatok:

• SSE események helyes elemzése, az üres sorok figyelmen kívül hagyásával.
• Halmozd a darabokat a memóriában vagy egy pufferben.
• Ellenőrizze a usage object az utolsó darabban a token számokért.

Számlázási Hibák és Token Aritmetika

A számlázási hibák gyakran abból adódnak, hogy nem értik meg, hogyan számolják a tokeneket. A tokenekért a bemeneti (prompt) és a kimeneti (completion) részek után is fizetni kell. Az áraink $0.15 per 1M bemeneti token és $0.50 per 1M kimeneti token. A hibák és a visszautasítások ingyenesek, ami csökkenti a hibakeresés költségeit.

A tokenizátorok nem mindig 1:1-es leképezést adnak karakterekre. Egyetlen szó több token lehet. Ha a költségeket karakter számlálás alapján becsüli, alábecsülheti a számlát. Használjon megbízható tokenizátor könyvtárat az ügyfélnél a pontos számlázás érdekében a kérések küldése előtt.

A hitel nem jár le. Ha kriptóval töltesz fel, az egyenled addig megmarad, amíg fel nem használod. Ez hasznos hosszú távú projektekhez. Vegyél azonban tudomást arról, hogy minden kérés tokeneket fogyaszt az egyenledből. Ha az egyenled alacsony, a későbbi kérések sikertelenek lehetnek.

Számlázási tippek:

• Token használat nyomon követése minden válaszban.
• Állítson be értesítéseket az alacsony egyenleg küszöbértékekre.
• Használat max_tokens a lehetséges költségek korlátozásához.

Biztonsági és portfeltárási problémák

A helyi Ollama végpontok gyakran alapértelmezetten ki vannak téve a hálózatnak. Ez sebezhetővé teszi őket port szkennelőkkel szemben, amelyek ingyenes számítási erőforrásokat keresnek. Ha kiexponálja a 11434-es portot hitelesítés nélkül, bárki használhatja a GPU erőforrásait. Ez magas elektromossági számlákhoz és lassú teljesítményhez vezethet.

Biztonságosítsd a végpontodat az alapértelmezett port megváltoztatásával vagy egy hitelesítéssel rendelkező reverse proxy használatával. A hosztolt szolgáltatásunk kezeli a biztonságot, így nem kell aggódnod a port kitettsége miatt. Csak azt kell biztosítanod, hogy az API kulcsod privát maradjon.

Helyi beállításokhoz használj tűzfalat a hozzáférés korlátozására megbízható IP-címekre. Engedélyezheted a token alapú hitelesítést is az Ollama konfigurációs fájljában. Ez megakadályozza, hogy jogosulatlan felhasználók küldjenek kéréseket.

Biztonsági lépések:

• Módosítsa az alapértelmezett portot, ha az internetre teszi.
• Használjon reverse proxyt HTTPS és auth támogatással.
• Kövesse nyomon a hálózati forgalmat a szokatlan tevékenységek szempontjából.

Helyi vs Felhő Ollama API Használat

A helyi használat teljes ellenőrzést ad az adatvédelem és a modellválasztás felett. Több modellt is futtathatsz egyszerre, és azonnal válthatsz közöttük. Azonban te felelsz a hardver karbantartásáért, frissítésekért és biztonságtól. A felhőalapú használat áthárítja ezeket a felelősségeket a szolgáltatóra.

A felhőszolgáltatásunk egy uncensored modellt kínál, amely a korlátok nélküli tartalomgenerálásra van optimalizálva. Azonnali hozzáférést kap anélkül, hogy letöltenie kellene a nagy modellfájlokat. A kompromisszum az, hogy az adatai áthaladnak a szervereinkön. Érzékeny adatok esetén a helyi telepítés előnyösebb lehet.

A felhőszolgáltatások gyakran magasabb késleltetéssel rendelkeznek a hálózati körutak miatt. A helyi példányok közel nullás késleltetéssel rendelkeznek, ha a GPU elég gyors. A helyi példányok azonban jelentős VRAM-ot igényelnek. Ha a GPU lejár a memóriából, a modell átválthat CPU-ra, ami drasztikusan lelassítja a válaszokat.

Összehasonlítás:

• Helyi: Adatvédelem, vezérlés, hardverfüggőség.
• Felhő: Kényelem, skálázhatóság, adatátvitel.

Gyakori kliens oldali hibák

A fejlesztők gyakran elfelejtik kezelni a sebességkorlátokat. Szolgáltatásunk percenként 300 kérést tesz lehetőles kulcsonként. Ha ezt túllépi, 429-es hibát kap. Implementáljon exponenciális backoffot az ügyfélobjektumban ezeknek a hibáknak a kegyes kezelésére.

Egy másik hiba a stream parameter correctly. If you expect streaming but do not set stream: true, várnia kell a teljes válaszra, mielőtt bármilyen adatot kapna. Ez lassúnak éreztetheti az alkalmazását.

A JSON mód hibái is gyakoriak. Ha beállítja response_format: {type: "json_object"}, a modellnek érvényes JSON-t kell visszaadnia. Ha nem, a parser összeomlik. Adjon hozzá hibakezelést a JSON elemzési hibák fogadásához és újrapróbálkozásához.

Ellenőrzőlista:

• Implementáljon sebességkorlátozás-kezelést.
• Beállítás stream: true a valós idejű frissítésekhez.
• JSON kimenet validálása JSON mód használatakor.