Průvodce řešením potíží Ollama API

Chápání struktury koncového bodu API Ollama

The ollama endpoint následuje přísný RESTful vzor, který odráží strukturu API OpenAI. S interagujete odesíláním POST požadavků na /v1/chat/completions a dotazování se na dostupné modely přes GET /v1/models. Tato standardizace vám umožňuje vyměnit základní modely bez přepisování kódu klienta.

Mnoho vývojářů předpokládá, že endpoint podporuje vnořená data (embeddings) nebo generování obrázků ve výchozím nastavení. Nedělá. Naše hostovaná služba například poskytuje pouze textová dokončení s jedním modelem bez omezení. Vždy zkontrolujte GET /v1/models odpověď a přesně zjistěte, které kapacity jsou vystaveny. Pokud vidíte seznam modelů, ověřte jejich ID před odesláním požadavků.

Při používání lokální instance endpoint obvykle běží na http://localhost:11434. Pro cloudové poskytovatele použijete vlastní základní URL. Ujistěte se, že váš HTTP klient správně zpracovává hlavičky, zejména Content-Type: application/json. Chybějící hlavička často způsobuje tiché selhání, která vypadají jako chyby modelu.

Strukturní prvky klíče:

• model: Řetězcový identifikátor konkrétního LLM.
• messages: Pole objektů obsahu založených na rolích.
• stream: Logická hodnota povolující Server-Sent Events (SSE).

Proč mohou selhat vaše volání API ollama

Volání API obvykle selžou kvůli nesprávným base URL, vypršeným klíčům nebo neplatným JSON payloadům. Nejčastější chybou je odpověď 401 Unauthorized, což znamená, že váš API klíč chybí nebo je neplatný. Další častý problém je 404 Not Found, což naznačuje, že endpoint nepodporuje požadovanou cestu nebo ID modelu.

Pečlivě zkontrolujte tělo žádosti. Pokud odešlete parametr, který endpoint nepodporuje, například modalities pro model pouze pro text, server může požadavek odmítnout. Naše služba například nepodporuje vstup obrázků. Jeho odeslání vede k okamžité chybě.

Časy vypršení také způsobují selhání. Pokud je vaše místní instance Ollama nečinná, může model uvolnit z VRAM. První požadavek po studeném startu může trvat několik sekund. Nastavte v HTTP klientovi dostatečný časový limit, abyste předešli předčasnému odpojení.

Běžné kódy chyb:

• 400: Bad Request (neplatný JSON nebo neplatné parametry).
• 401: Neoprávněno (neplatný nebo chybějící API klíč).
• 429: Příliš mnoho požadavků (překročen limit).
• 500: Internal Server Error (selhání načítání modelu).

Správná konfigurace uncensored modelů ollama

Nekorigované modely často vyžadují specifické parametry pro chování podle očekávání. Hlavní rozdíl spočívá v system prompt. Musíte explicitně instrukovat model, aby obešel standardní odmítnutí. Bez silného systémového promptu se model může vrátit k výchozím bezpečnostním chováním.

Náš endpoint používá ID modelu uncensored. Posíláte požadavky na toto ID a server řeší výběr podkladového modelu. To abstrahuje složitost správy verzí modelů. Nemusíte vědět, zda je podkladová architektura založena na Llamě nebo Mistralu.

Upravte temperature parameter pro ovládání kreativity. Hodnota 0,7 je dobrým výchozím bodem pro vyvážené odpovědi. Vyšší hodnoty zvyšují náhodnost, což je užitečné pro kreativní psaní, ale může snížit faktickou přesnost. Nižší hodnoty činí výstup více deterministickým.

Tipy pro konfiguraci:

• Použít top_p vedle temperature pro lepší kontrolu.
• Nastavit stop sekvence pro prevenci nekonečných smyček.
• Vždy zahrňte system zpráva pro definici role.

Zvládání streamování a limitů tokenů

Streamované odpovědi vrací data v blocích prostřednictvím událostí Server-Sent Events (SSE). Každý blok obsahuje částečné dokončení. Musíte tyto bloky skládat, abyste získali celou odpověď. Naše služba zahrnuje statistiky využití tokenů v posledním bloku, což vám umožňuje sledovat náklady v reálném čase.

Omezení tokenů jsou kritická pro dlouhé konverzace. Naše endpoint podporuje okno kontextu o velikosti 100 000 tokenů, které zahrnuje jak prompt, tak dokončení. Maximální výstup na požadavek je však 16 000 tokenů. Pokud nezadáte max_tokens, výchozí hodnota je 2 048 tokenů. To může neočekávaně oříznout dlouhé odpovědi.

Při streamování zpracovávejte přerušení sítě hladce. Pokud se připojení přeruší, můžete pokračovat od posledního přijatého chunku, pokud to server podporuje. V opačném případě budete možná musit zopakovat celý požadavek. Vždy monitorujte usage pole v posledním chunku, abyste předešli překvapením při fakturaci.

Nejlepší praktiky streamování:

• Správné parsování událostí SSE, ignorování prázdných řádků.
• Akumulujte části do paměti nebo do vyrovnávací paměti.
• Zkontrolujte usage object v posledním chunku pro počty tokenů.

Chyby fakturování a aritmetika tokenů

Chyby při fakturaci často pramení z nepochopení způsobu počítání tokenů. Tokeny se účtují jak za vstup (prompt), tak za výstup (completion). Naše ceny jsou 0,15 $ za 1M vstupních tokenů a 0,50 $ za 1M výstupních tokenů. Chyby a odmítnutí jsou zdarma, což snižuje náklady při ladění.

Tokenizéry nepřevádějí vždy 1:1 na znaky. Jedno slovo může být více tokenů. Pokud odhadujete náklady na základě počtu znaků, můžete si účty podcenit. Použijte spolehlivou knihovnu tokenizéru ve vašem klientovi pro získání přesných počtů před odesláním požadavků.

Kredit nevyprší. Pokud si dobijete kryptoměnami, zůstatek zůstává k dispozici, dokud ho nepoužijete. To je užitečné pro dlouhodobé projekty. Mějte však na paměti, že každý požadavek spotřebuje tokeny z vašeho zůstatku. Pokud je váš zůstatek nízký, další požadavky mohou selhat.

Tipy pro fakturaci:

• Sledujte využití tokenů v každé odpovědi.
• Nastavte upozornění na nízké prahové hodnoty zůstatku.
• Použít max_tokens k omezení potenciálních nákladů.

Problémy s bezpečností a skenováním portů

Lokální endpointy Ollama jsou často implicitně vystaveny síti. To je činí zranitelnými vůči skenerům portů hledajícím bezplatný výpočetní výkon. Pokud vystavíte port 11434 bez ověření, může kdokoli využít vaše GPU zdroje. To může vést k vysokým účtům za elektřinu a zpomalení výkonu.

Zabezpečte svůj endpoint změnou výchozího portu nebo použitím reverzního proxy serveru s autentizací. Naše hostovaná služba řeší za vás bezpečnost, takže nemusíte řešit vystavení portu. Stačí, když budete svůj API klíč udržovat v soukromí.

Pro lokální nastavení použijte firewall k omezení přístupu na důvěryhodné IP adresy. Do konfiguračního souboru Ollamy můžete také povolit autentizaci na základě tokenů. To zabrání neoprávněným uživatelům odesílat požadavky.

Kroky zabezpečení:

• Změňte výchozí port, pokud vystavujete službu internetu.
• Použijte reverse proxy s HTTPS a auth.
• Sledujte síťový provoz na neobvyklou aktivitu.

Lokální vs Cloud ollama API Použití

Lokální použití vám dává plnou kontrolu nad soukromím dat a výběrem modelu. Můžete běžet více modelů současně a okamžitě mezi nimi přepínat. Odpovídáte však za údržbu hardwaru, aktualizace a bezpečnost. Cloud použití přenáší tyto odpovědnosti na poskytovatele.

Naše cloudová služba nabízí model bez cenzury optimalizovaný pro generování neomezeného obsahu. Získáte okamžitý přístup bez stahování velkých souborů modelu. Nevýhodou je, že vaše data procházejí našimi servery. Pro citlivá data může být lokální řešení vhodnější.

Cloudové služby mají často vyšší latenci kvůli síťovým okruhům. Lokální instance mají téměř nulovou latenci, pokud je GPU dostatečně rychlé. Lokální instance však vyžadují významné množství VRAM. Pokud GPU dojde paměť, model může přepnout na CPU, což výrazně zpomalí odpovědi.

Srovnání:

• Lokální: Soukromí, kontrola, závislost na hardwaru.
• Cloud: Pohodlí, škálovatelnost, přenos dat.

Běžné chyby na straně klienta

Vývojáři často zapomínají řešit limity rychlosti. Naše služba umožňuje 300 požadavků za minutu na klíč. Pokud tento limit překročíte, obdržíte chybu 429. Implementujte exponenciální backoff ve vašem klientovi, abyste tyto chyby řešili elegantně.

Další chybou je nenastavení stream parameter správně. Pokud očekáváte streamování, ale nenastavíte stream: true, budete čekat na celou odpověď před přijetím jakýchkoli dat. To může způsobit, že vaše aplikace bude působit pomalu.

Chyby režimu JSON jsou také běžné. Pokud nastavíte response_format: {type: "json_object"}, model musí vrátit platné JSON. Pokud tak neučiní, váš parser selže. Přidejte zpracování chyb pro zachycení a opakování pokusů o parsování JSON.

Kontrolní seznam:

• Implementujte zpracování limitů rychlosti.
• Nastavit stream: true pro aktualizace v reálném čase.
• Ověřte výstup JSON při použití režimu JSON.