Panduan Pemecahan Masalah API Ollama

Memahami Struktur Endpoint API Ollama

The ollama endpoint mengikuti pola RESTful ketat yang mencerminkan struktur API OpenAI. Anda berinteraksi dengannya dengan mengirim permintaan POST ke /v1/chat/completions dan query model yang tersedia melalui GET /v1/modelsStandarisasi ini memungkinkan Anda mengganti model dasar tanpa menulis ulang kode klien.

Banyak pengembang mengasumsikan bahwa endpoint mendukung embedding atau pembuatan gambar secara default. Tidak. Layanan yang kami host, misalnya, hanya melayani penyelesaian teks dengan satu model tanpa sensor. Selalu periksa GET /v1/models respons untuk melihat persis kemampuan apa yang tersedia. Jika Anda melihat daftar model, verifikasi ID mereka sebelum mengirim permintaan.

Saat menggunakan instans lokal, titik akhir biasanya berjalan di http://localhost:11434. Untuk penyedia cloud, Anda akan menggunakan URL dasar kustom. Pastikan klien HTTP Anda menangani header dengan benar, terutama Content-Type: application/json. Header yang hilang sering menyebabkan kegagalan diam yang terlihat seperti kesalahan model.

Elemen struktural kunci:

• model: Pengidentifikasi string untuk LLM spesifik.
• messages: Array objek konten berbasis peran.
• stream: Flag boolean yang mengaktifkan Server-Sent Events (SSE).

Mengapa Panggilan API ollama Anda Mungkin Gagal

Panggilan API biasanya gagal karena URL base yang salah, kunci yang kedaluwarsa, atau payload JSON yang tidak valid. Kesalahan paling umum adalah respons 401 Unauthorized, yang berarti kunci API Anda hilang atau tidak valid. Masalah sering lainnya adalah 404 Not Found, yang menunjukkan endpoint tidak mendukung jalur atau ID model yang diminta.

Periksa tubuh permintaan Anda dengan cermat. Jika Anda mengirim parameter yang tidak didukung oleh endpoint, seperti modalities untuk model hanya teks, server mungkin menolak permintaan. Layanan kami, misalnya, tidak mendukung input gambar. Mengirimnya menghasilkan kesalahan segera.

Waktu tunggu jaringan juga menyebabkan kegagalan. Jika instance Ollama lokal Anda tidak aktif, model mungkin dibebankan dari VRAM. Permintaan pertama setelah startup dingin dapat memakan waktu beberapa detik. Tetapkan waktu tunggu yang murah hati di klien HTTP Anda untuk menghindari pemutusan prematur.

Kode kesalahan umum:

• 400: Bad Request (JSON tidak valid atau parameter tidak valid).
• 401: Tidak Sah (kunci API tidak valid atau hilang).
• 429: Terlalu Banyak Permintaan (batas laju terlampaui).
• 500: Internal Server Error (kegagalan pemuatan model).

Mengkonfigurasi Model ollama Tanpa Sensor dengan Benar

Model tanpa sensor sering kali memerlukan parameter tertentu agar berperilaku sesuai harapan. Perbedaan utamanya terletak pada system prompt. Anda harus secara eksplisit menginstruksikan model untuk melewati penolakan standar. Tanpa system prompt yang kuat, model mungkin kembali ke perilaku keamanan default.

Endpoint kami menggunakan ID model uncensored. Anda mengirim permintaan ke ID ini, dan server menangani pemilihan model di bawahnya. Ini mengabstraksi kompleksitas mengelola versi model. Anda tidak perlu mengetahui apakah arsitektur dasarnya berbasis Llama atau Mistral.

Sesuaikan temperature parameter untuk mengontrol kreativitas. Nilai 0,7 adalah titik awal yang baik untuk respons seimbang. Nilai yang lebih tinggi meningkatkan keacakan, yang berguna untuk penulisan kreatif tetapi mungkin mengurangi akurasi faktual. Nilai yang lebih rendah membuat output lebih deterministik.

Tips konfigurasi:

• Gunakan top_p sebelah temperature untuk kontrol yang lebih baik.
• Atur stop urutan untuk mencegah loop tak hingga.
• Selalu sertakan sebuah system pesan untuk definisi peran.

Menangani Streaming dan Batas Token

Respons streaming mengembalikan data dalam bagian-bagian melalui Server-Sent Events (SSE). Setiap bagian berisi penyelesaian parsial. Anda harus merakit bagian-bagian ini untuk mendapatkan respons lengkap. Layanan kami mencakup statistik penggunaan token di bagian terakhir, memungkinkan Anda melacak biaya secara real-time.

Batas token sangat penting untuk percakapan panjang. Titik akhir kami mendukung jendela konteks 100.000 token, menggabungkan prompt dan penyelesaian. Namun, output maksimum per permintaan adalah 16.000 token. Jika Anda tidak mengatur max_tokens, nilai defaultnya adalah 2.048 token. Ini dapat memotong jawaban panjang secara tidak terduga.

Saat streaming, tangguhkan gangguan jaringan dengan baik. Jika koneksi terputus, Anda dapat melanjutkan dari potongan terakhir yang diterima jika server mendukungnya. Jika tidak, Anda mungkin perlu mencoba ulang seluruh permintaan. Selalu pantau usage field in the final chunk to avoid billing surprises.

Praktik terbaik streaming:

• Parse event SSE dengan benar, mengabaikan baris kosong.
• Akumulasi potongan dalam memori atau buffer.
• Periksa usage object dalam chunk terakhir untuk jumlah token.

Kesalahan Penagihan dan Aritmetika Token

Kesalahan penagihan sering kali berasal dari kesalahpahaman tentang cara token dihitung. Token dibebankan untuk input (prompt) dan output (completion). Harga kami adalah $0.15 per 1M token input dan $0.50 per 1M token output. Kesalahan dan penolakan gratis, yang mengurangi biaya untuk debugging.

Tokenizer tidak selalu memetakan 1:1 dengan karakter. Satu kata bisa menjadi beberapa token. Jika Anda memperkirakan biaya berdasarkan jumlah karakter, Anda mungkin meremehkan tagihan. Gunakan library tokenizer yang andal di klien Anda untuk mendapatkan hitungan yang akurat sebelum mengirim permintaan.

Kredit tidak kadaluarsa. Jika Anda mengisi dengan crypto, saldo tetap ada hingga Anda menggunakannya. Ini berguna untuk proyek jangka panjang. Namun, perlu diingat bahwa setiap permintaan mengonsumsi token dari saldo Anda. Jika saldo Anda rendah, permintaan selanjutnya mungkin gagal.

Tips penagihan:

• Lacak penggunaan token di setiap respons.
• Siapkan peringatan untuk ambang batas saldo rendah.
• Gunakan max_tokens untuk membatasi biaya potensial.

Masalah Keamanan dan Pemindaian Port

Endpoint Ollama Lokal sering terbuka ke jaringan secara default. Ini membuatnya rentan terhadap pemindai port yang mencari komputasi gratis. Jika Anda membuka port 11434 tanpa autentikasi, siapa saja dapat menggunakan sumber daya GPU Anda. Ini dapat menyebabkan tagihan listrik tinggi dan kinerja lambat.

Amankan endpoint Anda dengan mengubah port default atau menggunakan proxy terbalik dengan autentikasi. Layanan terhosting kami menangani keamanan untuk Anda, sehingga Anda tidak perlu khawatir tentang paparan port. Anda hanya perlu menjaga kunci API Anda tetap privat.

Untuk pengaturan lokal, gunakan firewall untuk membatasi akses ke alamat IP tepercaya. Anda juga dapat mengaktifkan autentikasi berbasis token dalam file konfigurasi Ollama. Ini mencegah pengguna yang tidak berwenang membuat permintaan.

Langkah keamanan:

• Ubah port default jika mengekspos ke internet.
• Gunakan proxy terbalik dengan HTTPS dan autentikasi.
• Pantau lalu lintas jaringan Anda untuk aktivitas yang mencurigakan.

Penggunaan API Ollama Lokal vs Cloud

Penggunaan lokal memberi Anda kontrol penuh atas privasi data dan pemilihan model. Anda dapat menjalankan beberapa model secara bersamaan dan beralih di antaranya secara instan. Namun, Anda bertanggung jawab atas pemeliharaan perangkat keras, pembaruan, dan keamanan. Penggunaan cloud membebankan tanggung jawab ini kepada penyedia.

Layanan cloud kami menawarkan model uncensored yang dioptimalkan untuk generasi konten tanpa batasan. Anda mendapatkan akses instan tanpa mengunduh file model besar. Kerugiannya adalah data Anda melewati server kami. Untuk data sensitif, lokal mungkin lebih disukai.

Layanan cloud sering memiliki latensi lebih tinggi karena putaran jaringan. Instance lokal memiliki latensi hampir nol jika GPU cukup cepat. Namun, instance lokal memerlukan VRAM yang signifikan. Jika GPU Anda kehabisan memori, model mungkin akan swap ke CPU, yang secara drastis memperlambat respons.

Perbandingan:

• Lokal: Privasi, kendali, ketergantungan perangkat keras.
• Cloud: Kenyamanan, skalabilitas, transfer data.

Kesalahan Sisi Klien Umum

Pengembang sering lupa menangani batas laju. Layanan kami mengizinkan 300 permintaan per menit per kunci. Jika Anda melebihi ini, Anda akan menerima error 429. Terapkan backoff eksponensial di klien Anda untuk menangani error ini dengan lancar.

Kesalahan lain adalah tidak mengatur stream parameter dengan benar. Jika Anda mengharapkan streaming tetapi tidak mengatur stream: true, Anda akan menunggu seluruh respons sebelum menerima data apa pun. Ini dapat membuat aplikasi Anda terasa lambat.

Kesalahan mode JSON juga umum. Jika Anda mengatur response_format: {type: "json_object"}, model harus mengembalikan JSON yang valid. Jika tidak, parser Anda akan gagal. Tambahkan penanganan kesalahan untuk menangkap dan mencoba ulang kesalahan parsing JSON.

Daftar periksa:

• Implementasikan penanganan batas laju.
• Atur stream: true untuk pembaruan waktu nyata.
• Validasi output JSON saat menggunakan mode JSON.