Ollama API: Řešení běžných chyb

Chápání kontextového okna o velikosti 100k

První věta každé sekce odpovídá na otázku v nadpisu.

Okno kontextu o velikosti 100 000 tokenů zní obrovsky, ale dělí se rovnoměrně mezi vstupní prompty a výstupní dokončení. Když pošlete dlouhý systémový prompt spolu s rozsáhlou historií konverzace, tuto rozpočtovou kapacitu vyčerpáte rychleji, než byste mohli čekat. Mnoho vývojářů předpokládá, že se limit vztahuje pouze na vstup, což vede k ořezaným odpovědím nebo tichým selháním, když model dosáhne svého stropu.

Zvažte scénář, kde předáte dokument o 50 000 tocenech jako kontext. Máte ještě 50 000 tokenů na skutečné generování. Pokud tento poměr nebudete pečlivě spravovat, model přestane uprostřed věty. Vždy monitorujte celkový počet tokenů odeslaných v každém požadavku, abyste předešli neočekávanému oříznutí.

Max Tokeny vs. Výchozí Délka Výstupu

Každá sekce musí odpovědět na otázku v nadpisu.

Pokud neurčíte limit, většina API výchozím způsobem nastavuje skromnou délku výstupu, často kolem 2 048 tokenů. Tento výchozí nastavení je užitečné pro krátké dotazy, ale katastrofální pro generování kódu nebo dlouhého psaní. Pokud potřebujete, aby model vygeneroval celý scénář nebo podrobnou analýzu, musíte explicitně nastavit parametr max_tokens.

Nastavení této hodnoty příliš vysoko může také ovlivnit latenci a náklady. Platíte za každý vygenerovaný token, ať už užitečný, nebo ne. Pragmatický přístup je nastavit rozumnou horní hranici, která odpovídá vašemu použití, spíše než nechat ji na výchozí hodnotě nebo libovolném nekonečnu.

Správné zvládání streamovacích částí SSE

Streamování vyžaduje pečlivé zpracování Server-Sent Events, aby nedošlo ke ztrátě dat.

Po povolení streamování API vrací řadu malých částí místo jedné kompletní odpovědi. Každá část obsahuje delta textu, ale klíčové detaily, jako jsou statistiky využití tokenů, jsou často přítomny pouze v poslední části. Pokud přestanete parsovat příliš brzy, přijdete o data o využití potřebná pro fakturaci nebo sledování limitů.

Streamování zavádí složitost v zpracování chyb. Přerušení sítě může ponechat částečný text. Potřebujete robustní parser, který dokáže rekonstruovat plnou zprávu z těchto fragmentů. To platí zejména při integraci s UI komponentami, které vykreslují text v reálném čase.

Chyby definice nástrojů při volání funkcí

Volání funkcí selže, když schémata nástrojů neodpovídají očekáváním modelu.

Model očekává specifickou strukturu JSON pro definice nástrojů. Pokud vynecháte povinná pole nebo použijete nesprávné typy, model může nástroj zcela ignorovat nebo vrátit chybnou odpověď. Toto je častý problém vývojářů vytvářejících agenty, kteří potřebují interagovat s externími API.

Vždy validujte schéma vašeho nástroje proti dokumentaci API před odesláním požadavků. I malé odchylky, jako použití celého čísla místo řetězce pro parametr, mohou rozbít volání funkce. Ladění tohoto vyžaduje inspekci surové JSON odpovědi, abyste viděli, zda model vůbec zkusil nástroj zavolat.

Problémy s formátem odpovědi v režimu JSON

Režim JSON vynucuje, aby model výstupoval platný JSON, ale stále může halucinovat.

Po nastavení response_format na json_object je model omezen na výstup pouze formátu JSON. To však nezaručuje, že obsah je sémanticky správný. Model může vygenerovat platnou syntaxi JSON, ale s nesprávnými klíči nebo chybějícími poli. Stále potřebujete parser k ověření struktury před použitím dat.

Dále může režim JSON někdy snížit kreativitu nebo flexibilitu modelu. Pokud je váš prompt příliš složitý, model může mít potíže s vložením příběhu do rigidní struktury JSON. Tento režim používejte primárně pro extrakci strukturovaných dat nebo argumenty funkcí, kde je konzistence důležitější než nuance.

Limitování rychlosti a souběžné požadavky

Limity rychlosti jsou vynucovány na základě klíče API, nikoli na základě uživatele nebo IP adresy.

Většina API ukládá limit na požadavky za minutu a souběžná připojení. Pokud tyto limity překročíte, obdržíte chybu 429 Too Many Requests. To je kritické pro aplikace, které vytvářejí více vláken nebo procesů pro zpracování požadavků uživatelů. Jeden klíč může zpracovat pouze omezený počet paralelních požadavků.

Pro správu této situace implementujte v kódu klienta exponenciální zpětné zpoždění. Při obdržení chyby 429 počkejte krátkou dobu před opakováním požadavku. Tím předejdete přetížení serveru a zajistíte plynulejší uživatelský zážitek. Vždy kontrolujte hlavičky odpovědi na hodnoty retry-after pro optimalizaci doby čekání.

Chování při náhradě klíče API

Regenerace API klíče okamžitě zneplatní předchozí.

Některé platformy umožňují pouze jeden aktivní klíč na účet. Pokud vygenerujete nový klíč, starý přestane fungovat okamžitě. To může způsobit výpadky, pokud máte více služeb nebo skriptů používajících starý klíč. Vždy aktualizujte všechny instance vašeho klíče před jeho rotací.

Toto chování je navrženo pro bezpečnost, což zajišťuje, že uniklý klíč nelze používat donekonečna. Vyžaduje však pečlivé řízení v distribuovaných systémech. Používejte proměnné prostředí nebo správce tajných klíčů k uložení vašeho klíče, což usnadňuje aktualizace a snižuje pravděpodobnost chyb.

Limity velikosti těla požadavku

Velká tělesa požadavků mohou překročit limit 8 MB.

Při odesílání dlouhých dokumentů nebo obrázků zakódovaných jako base64 může tělo požadavku rychle narůst. Pokud překročíte limit velikosti, server zamítne požadavek chybou 413 Payload Too Large. Toto je pevný limit, který nelze v mnoha případech zvýšit ani upgradem plánu.

Abychom se tomu vyhnuli, komprimujte svůj vstup nebo rozdělte velké dokumenty na menší části. Můžete také použít efektivnější kódování pro obrázky. Vždy monitorujte velikost vašich požadavků, zejména při práci s obsahem bohatým na média.