Przewodnik rozwiązywania problemów API Ollama

Zrozumienie struktury punktu końcowego API Ollama

The ollama endpoint zgodnie z ścisłym wzorcem RESTful, który odzwierciedla strukturę API OpenAI. Wchodzisz w interakcję z nim, wysyłając żądania POST do /v1/chat/completions i wyszukaj dostępne modele poprzez GET /v1/models. Ta standaryzacja pozwala na wymianę podstawowych modeli bez przepisywania kodu klienta.

Wielu programistów zakłada, że punkt końcowy obsługuje domyślnie osadzanie (embeddings) lub generowanie obrazów. Nie obsługuje. Nasza usługa hostowana, na przykład, obsługuje tylko uzupełnienia tekstu za pomocą jednego modelu bez cenzury. Zawsze sprawdzaj GET /v1/models odpowiedź, aby dokładnie zobaczyć, jakie możliwości są udostępnione. Jeśli widzisz listę modeli, zweryfikuj ich identyfikatory przed wysłaniem żądań.

Podczas używania lokalnej instancji punkt końcowy zazwyczaj działa na http://localhost:11434. Dla dostawców chmurowych użyjesz niestandardowego adresu bazowego. Upewnij się, że Twój klient HTTP poprawnie obsługuje nagłówki, w tym Content-Type: application/json. Brakujący nagłówek często powoduje ciche awarie, które wyglądają jak błędy modelu.

Elementy strukturalne klucza:

• model: Identyfikator ciągu znaków dla konkretnego LLM.
• messages: Tablica obiektów treści opartych na rolach.
• stream: Flag boolean włączający Server-Sent Events (SSE).

Dlaczego Twoje wywołania API ollama mogą zawieść

Wywołania API zwykle kończą się niepowodzeniem z powodu nieprawidłowych URL bazowych, wygasłych kluczy lub niepoprawnych ładunków JSON. Najczęstszym błędem jest odpowiedź 401 Unauthorized, co oznacza, że Twój klucz API jest nieprawidłowy lub go brakuje. Innym częstym problemem jest 404 Not Found, co oznacza, że endpoint nie obsługuje żądanej ścieżki lub ID modelu.

Sprawdź dokładnie ciało żądania. Jeśli wyślesz parametr, który endpoint nie obsługuje, taki jak modalities dla modelu tylko tekstowego, serwer może odrzucić żądanie. Nasza usługa, na przykład, nie obsługuje wejścia obrazu. Jego wysłanie powoduje natychmiastowy błąd.

Przekroczenia czasu również powodują awarie. Jeśli Twoja lokalna instancja Ollama jest bezczynna, może ona zdjąć model z VRAM. Pierwsze żądanie po zimnym starcie może zająć kilka sekund. Ustaw wystarczająco długi timeout w kliencie HTTP, aby uniknąć przedwczesnych rozłączeń.

Typowe kody błędów:

• 400: Bad Request (niepoprawny JSON lub nieprawidłowe parametry).
• 401: Nieautoryzowany (nieprawidłowy lub brakujący klucz API).
• 429: Zbyt wiele Żądań (przekroczono limit szybkości).
• 500: Internal Server Error (niepowodzenie ładowania modelu).

Prawidłowe konfigurowanie modeli ollama bez cenzury

Modele bez cenzury często wymagają specyficznych parametrów, aby zachowywać się zgodnie z oczekiwaniami. Główna różnica polega na system prompt. Musisz wyraźnie poinstruować model, aby zignorował standardowe ograniczenia. Bez silnego promptu systemowego model może powrócić do domyślnych zachowań bezpieczeństwa.

Nasz punkt końcowy używa identyfikatora modelu uncensored. Wysyłasz żądania do tego ID, a serwer obsługuje wybór modelu w tle. Abstrahuje to złożoność zarządzania wersjami modeli. Nie musisz wiedzieć, czy architektura w tle oparta jest na Llama czy Mistral.

Dostosuj temperature parametr do kontrolowania kreatywności. Wartość 0,7 jest dobrym punktem wyjścia dla zrównoważonych odpowiedzi. Wyższe wartości zwiększają losowość, co jest przydatne w pisaniu twórczym, ale może zmniejszyć dokładność faktograficzną. Niższe wartości sprawiają, że wyjście jest bardziej deterministyczne.

Wskazówki konfiguracji:

• Użyj top_p obok temperature dla lepszego kontroli.
• Ustaw stop sekwencji, aby zapobiec nieskończonym pętlom.
• Zawsze dołączaj system wiadomość dla definicji roli.

Obsługa strumieniowania i limitów tokenów

Odpowiedzi strumieniowe zwracają dane w fragmentach za pomocą zdarzeń wysyłanych przez serwer (SSE). Każdy fragment zawiera częściowe uzupełnienie. Musisz złożyć te fragmenty, aby uzyskać pełną odpowiedź. Nasza usługa zawiera statystyki użycia tokenów w ostatnim fragmencie, pozwalając Ci śledzić koszty w czasie rzeczywistym.

Limity tokenów są krytyczne dla długich rozmów. Nasze endpoint obsługuje okno kontekstowe 100,000 tokenów, łącząc zarówno prompt, jak i uzupełnienie. Jednak maksymalne wyjście na żądanie to 16,000 tokenów. Jeśli nie ustawisz max_tokens, domyślnie to 2 048 tokenów. Może to niespodziewanie uciąć długie odpowiedzi.

Podczas strumieniowania obsługuj przerwania sieciowe w sposób elegancki. Jeśli połączenie zostanie zerwane, możesz wznowić od ostatniego otrzymanego fragmentu, jeśli serwer to obsługuje. W przeciwnym razie może być konieczne ponowne wysłanie całego żądania. Zawsze monitoruj usage pole w ostatnim fragmencie, aby uniknąć niespodzianek rachunkowych.

Najlepsze praktyki strumieniowania:

• Poprawne parsowanie zdarzeń SSE, ignorując puste linie.
• Agreguj fragmenty w pamięci lub buforze.
• Sprawdź usage obiekt w ostatnim cząstkowym pakiecie po liczby tokenów.

Błędy rozliczeniowe i arytmetyka tokenów

Błędy rozliczeniowe często wynikają z nieporozumienia dotyczącego liczenia tokenów. Tokeny są naliczane zarówno za input (prompt), jak i output (completion). Nasze ceny to $0.15 za 1M tokenów input i $0.50 za 1M tokenów output. Błędy i odrzucenia są darmowe, co zmniejsza koszty podczas debugowania.

Tokenizatory nie zawsze mapują 1:1 z znakami. Jedno słowo może być wieloma tokenami. Jeśli oszacujesz koszty na podstawie liczby znaków, możesz zaniżyć rachunek. Użyj niezawodnej biblioteki tokenizatorów w swoim kliencie, aby uzyskać dokładne liczniki przed wysłaniem żądań.

Kredyt nie wygasa. Jeśli doładujesz go kryptowalutą, saldo pozostanie aktywne, aż go wykorzystasz. Jest to przydatne w długoterminowych projektach. Pamiętaj jednak, że każde żądanie pobiera tokeny z Twojego salda. Jeśli saldo jest niskie, kolejne żądania mogą zostać odrzucone.

Porady dotyczące rozliczeń:

• Śledź użycie tokenów w każdej odpowiedzi.
• Ustaw alerty dla niskich progów salda.
• Użyj max_tokens ograniczenia potencjalnych kosztów.

Problemy z bezpieczeństwem i skanowaniem portów

Lokalne endpointy Ollama są często wystawione do sieci domyślnie. Sprawia to, że są podatne na skanery portów szukające darmowych mocy obliczeniowych. Jeśli wystawisz port 11434 bez uwierzytelniania, każdy może korzystać z Twoich zasobów GPU. Może to prowadzić do wysokich rachunków za prąd i wolnego działania.

Zabezpiecz swój punkt końcowy, zmieniając domyślny port lub używając reverse proxy z uwierzytelnianiem. Nasza usługa hostowana zajmuje się bezpieczeństwem za Ciebie, więc nie musisz martwić się o ekspozycję portu. Musisz tylko pilnować prywatności swojego klucza API.

W konfiguracjach lokalnych użyj zapory sieciowej, aby ograniczyć dostęp do zaufanych adresów IP. Możesz również włączyć uwierzytelnianie oparte na tokenach w pliku konfiguracyjnym Ollama. Zapobiega to nieautoryzowanym żądaniom ze strony użytkowników.

Kroki bezpieczeństwa:

• Zmień domyślny port, jeśli udostępniasz do internetu.
• Użyj odwrotnego proxy z HTTPS i uwierzytelnianiem.
• Monitoruj ruch sieciowy pod kątem nietypowej aktywności.

Lokalne vs Chmura użycie API ollama

Użycie lokalne daje Ci pełną kontrolę nad prywatnością danych i wyborem modelu. Możesz uruchamiać wiele modeli jednocześnie i przełączać się między nimi natychmiast. Odpowiadasz jednak za konserwację sprzętu, aktualizacje i bezpieczeństwo. Użycie w chmurze przenosi te obowiązki na dostawcę.

Nasza usługa chmurowa oferuje model uncensored zoptymalizowany pod kątem generowania nieograniczonej treści. Otrzymujesz natychmiastowy dostęp bez pobierania dużych plików modeli. Kompromis polega na tym, że Twoje dane przechodzą przez nasze serwery. W przypadku wrażliwych danych lokalna instalacja może być preferowana.

Usługi chmurowe często mają wyższe opóźnienia ze względu na podróże sieciowe. Lokalne instancje mają opóźnienia bliskie zeru, jeśli GPU jest wystarczająco szybkie. Jednak lokalne instancje wymagają znacznej pamięci VRAM. Jeśli Twoja karta graficzna zabraknie pamięci, model może przełączyć się na CPU, co drastycznie spowalnia odpowiedzi.

Porównanie:

• Lokalne: Prywatność, kontrola, zależność od sprzętu.
• Chmura: Wygodność, skalowalność, transfer danych.

Typowe błędy po stronie klienta

Programiści często zapominają obsłużyć limity szybkości. Nasza usługa pozwala na 300 żądań na minutę na klucz. Jeśli ten limit przekroczysz, otrzymasz błąd 429. Zaimplementuj wykładnicze backoff w swoim kliencie, aby obsłużyć te błędy w sposób elegancki.

Kolejnym błędem jest nieustawienie stream parameter poprawnie. Jeśli oczekujesz strumieniowania, ale nie ustawisz stream: true, będziesz czekać na całą odpowiedź przed otrzymaniem jakichkolwiek danych. Może to sprawić, że Twoja aplikacja będzie działać wolno.

Błędy trybu JSON są również powszechne. Jeśli ustawisz response_format: {type: "json_object"}, model musi zwrócić poprawny JSON. Jeśli nie, Twój parser ulegnie awarii. Dodaj obsługę błędów, aby przechwytywać i ponawiać próby parsowania JSON.

Lista kontrolna:

• Wdroż obsługę limitów szybkości.
• Ustaw stream: true dla aktualizacji w czasie rzeczywistym.
• Zweryfikuj wyjście JSON przy użyciu trybu JSON.