API Kompatibel OpenAI Ollama: Akses, Harga, Integrasi, dan Panduan Produksi

API Kompatibel OpenAI Ollama: Akses, Harga, Integrasi, dan Panduan Produksi

API kompatibel OpenAI Ollama memungkinkan aplikasi mempertahankan bentuk SDK OpenAI yang familier sambil mengirim permintaan ke server Ollama lokal atau langsung ke Ollama Cloud. Hal ini berguna, tetapi bukan jaminan kesetaraan fitur satu banding satu: Ollama mendokumentasikan dukungan untuk sebagian API OpenAI, dan beberapa kemampuan bergantung pada endpoint serta model yang Anda pilih.

Panduan ini menunjukkan cara mengakses antarmuka ini, mengonfigurasinya dalam aplikasi Python atau JavaScript yang sudah ada, memahami biaya cloud dibandingkan lokal, serta menerapkan batasan produksi yang nyata di sekelilingnya.

Jawaban singkat: gunakan http://localhost:11434/v1/ untuk server Ollama lokal dan kunci API placeholder yang diperlukan oleh SDK tetapi diabaikan oleh Ollama. Gunakan https://ollama.com/v1 beserta OLLAMA_API_KEY untuk akses cloud langsung. Validasi endpoint dan model yang tepat sebelum mengandalkan perilaku streaming, vision, tools, output terstruktur, atau Responses API.

Apa arti “kompatibel dengan OpenAI” untuk Ollama?

Ini adalah lapisan integrasi klien OpenAI, bukan API yang dihosting OpenAI. Ini memungkinkan Anda mengarahkan klien yang kompatibel ke URL dasar Ollama dan menggunakan rute yang didukung seperti chat completions, embeddings, penemuan model, serta permintaan Responses non-stateful.

Referensi kompatibilitas Ollama adalah sumber kebenaran untuk subset yang didukung. Secara khusus:

• /v1/chat/completions mendukung fitur termasuk streaming, mode JSON, vision, tools, output yang dapat direproduksi, logprobs, dan kontrol yang hanya berlaku untuk model yang kompatibel.
• /v1/embeddings mendukung input string dan array.
• /v1/models dan /v1/models/{model} mendukung penemuan model, tetapi beberapa field yang dikembalikan memiliki makna khusus Ollama.
• POST /v1/responses tersedia, tetapi bersifat non-stateful: jangan mengandalkan previous_response_id atau conversation.

Lihat referensi kompatibilitas OpenAI Ollama terbaru sebelum mengaktifkan kemampuan di produksi. “Kompatibel” sebaiknya diperlakukan sebagai alasan untuk menggunakan kembali klien dan bentuk permintaan Anda—bukan alasan untuk melewati pengujian fitur.

Akses API kompatibel OpenAI Ollama: lokal versus cloud

Pilihan implementasi paling sederhana adalah apakah inferensi berjalan di mesin Anda sendiri atau mengakses endpoint cloud Ollama.

Pembagian ini didokumentasikan dalam pengantar API dan panduan autentikasi Ollama. Panggilan cloud langsung memerlukan kunci API. Panggilan lokal tidak memerlukannya.

Penyiapan lokal

Instal Ollama, lalu pull model yang ingin Anda gunakan. Dokumentasi Ollama menunjukkan pola umum berikut:

ollama pull gpt-oss:20b
ollama serve

Sekarang validasi bahwa endpoint lokal dapat menampilkan daftar model:

curl http://localhost:11434/v1/models

Jika koneksi tersebut gagal, selesaikan masalah server lokal sebelum mengubah kode aplikasi. Migrasi klien jauh lebih mudah di-debug ketika URL dasar API dan inventaris model sudah berfungsi secara independen.

Penyiapan cloud langsung

Untuk penggunaan cloud langsung, buat kunci API di akun Ollama Anda dan letakkan dalam variabel lingkungan:

export OLLAMA_API_KEY="replace-with-your-key"

URL dasar cloud adalah https://ollama.com/v1. Ollama mendokumentasikan bahwa API hosted-nya menggunakan Authorization: Bearer; jangan letakkan kunci berumur panjang dalam kode browser, repositori, atau file konfigurasi sisi klien.

Integrasikan API kompatibel OpenAI Ollama dengan SDK OpenAI

Titik migrasinya adalah konfigurasi klien. Pertahankan pesan aplikasi dan penanganan error di balik antarmuka Anda sendiri, lalu tukar hanya URL dasar, kunci, dan konfigurasi model.

Python: server lokal

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1/",
    api_key="ollama",  # required by the SDK; ignored by the local server
)

response = client.chat.completions.create(
    model="gpt-oss:20b",
    messages=[
        {"role": "user", "content": "Summarize the production risks of exposing a local API."}
    ],
)

print(response.choices[0].message.content)

Endpoint lokal tidak mengautentikasi permintaan. Kunci placeholder hanya ada karena klien OpenAI mengharapkan sebuah nilai; kunci tersebut tidak melindungi server lokal.

Python: cloud langsung

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://ollama.com/v1",
    api_key=os.environ["OLLAMA_API_KEY"],
)

response = client.chat.completions.create(
    model="gemma4:31b",
    messages=[
        {"role": "user", "content": "Give one sentence on safe API key storage."}
    ],
)

print(response.choices[0].message.content)

Bentuk kodenya sengaja dibuat serupa. Namun, perbedaan operasionalnya tidak serupa: panggilan cloud langsung bergantung pada kunci API dan model cloud yang dipilih; panggilan lokal bergantung pada model yang telah di-pull serta sumber daya yang tersedia pada host.

JavaScript: pertahankan endpoint agar dapat dikonfigurasi

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.OLLAMA_BASE_URL ?? "http://localhost:11434/v1/",
  apiKey: process.env.OLLAMA_API_KEY ?? "ollama",
});

const completion = await client.chat.completions.create({
  model: process.env.OLLAMA_MODEL ?? "gpt-oss:20b",
  messages: [{ role: "user", content: "Return a concise health-check message." }],
});

console.log(completion.choices[0].message.content);

Tetapkan variabel lingkungan untuk setiap deployment:

# Local
OLLAMA_BASE_URL=http://localhost:11434/v1/
OLLAMA_API_KEY=ollama
OLLAMA_MODEL=gpt-oss:20b

# Direct cloud
OLLAMA_BASE_URL=https://ollama.com/v1
OLLAMA_API_KEY=replace-with-your-key
OLLAMA_MODEL=gemma4:31b

Konfigurasi ini membuat perubahan rute atau model di kemudian hari menjadi eksplisit dan dapat ditinjau. Konfigurasi ini juga mencegah base URL khusus lingkungan menjadi perilaku aplikasi yang tersembunyi.

Matriks kompatibilitas: apa yang harus diuji sebelum diluncurkan

API kompatibel OpenAI Ollama paling berguna ketika Anda menjadikan kompatibilitas sebagai rencana pengujian, bukan asumsi.

Dua detail yang sering mengejutkan tim:

1. Status berada di aplikasi Anda. Aplikasi Anda harus menyimpan pesan atau status percakapan yang dibutuhkannya, alih-alih mengharapkan perilaku Responses berstatus dari Ollama.
2. Nama model bukan jaminan kapabilitas. Permintaan dapat menggunakan endpoint yang kompatibel tetapi tetap gagal memberikan kualitas atau perilaku tool yang dibutuhkan alur kerja. Uji model, ukuran prompt, batas output, dan tools secara bersamaan.

Jika integrasi yang ada melakukan hard-code pada nama model OpenAI default, Ollama mendokumentasikan ollama cp sebagai cara untuk membuat alias model lokal sementara. Gunakan ini hanya sebagai shim kompatibilitas yang disengaja, dokumentasikan alias tersebut, dan hapus setelah konfigurasi Anda eksplisit.

Harga Ollama: TCO lokal versus tarif token cloud

Harga untuk API kompatibel OpenAI Ollama bergantung pada rutenya.

Inferensi lokal bukan tagihan token—tetapi bukan tanpa biaya

Menjalankan model lokal tidak menghasilkan tagihan cloud Ollama per token. Namun, hal itu menciptakan profil biaya operasional:

• Kapasitas GPU atau CPU, RAM/VRAM, penyimpanan, dan depresiasi mesin
• Listrik dan pendinginan
• Waktu pull model dan penyimpanan image
• Perencanaan kapasitas, pemantauan, patching, dan respons insiden
• Biaya peluang untuk menjaga model tetap hangat bagi permintaan berlatensi rendah

Bagi satu developer, ini bisa menjadi pertukaran yang sangat baik. Untuk produk dengan trafik yang melonjak-lonjak atau beberapa model, hitung pemanfaatan perangkat keras dan upaya keandalan di samping biaya inferensi mentah.

Harga cloud langsung dipublikasikan per juta token

Halaman harga langsung Ollama mencantumkan tarif cloud per satu juta token, termasuk harga terpisah untuk input, input yang di-cache, dan output. Contoh di bawah ini diperiksa pada 22 Oktober 2026; gunakan daftar harga langsung untuk keputusan pengadaan dan penerapan.

Halaman harga Ollama juga menjelaskan harga di luar jam sibuk untuk entri yang memenuhi syarat. Jangan menyusun anggaran hanya berdasarkan label model: gunakan baris harga yang berlaku untuk rute, model, dan waktu aktual.

Estimasi bulanan yang praktis adalah:

monthly_cloud_cost =
  (input_tokens / 1,000,000 × input_rate)
+ (cached_input_tokens / 1,000,000 × cached_input_rate)
+ (output_tokens / 1,000,000 × output_rate)

Misalnya, pada tarif gpt-oss:20b yang dipublikasikan di atas, 1 juta token input tanpa cache ditambah 250.000 token output diperkirakan sebesar $0.145 sebelum perubahan harga atau kredit khusus akun. Gunakan telemetri token yang teramati, bukan perkiraan panjang chat, untuk proyeksi produksi.

Panduan produksi: amankan server lokal sebelum mengeksposnya

Aturan produksi terpenting untuk API kompatibel OpenAI Ollama itu sederhana: server Ollama lokal tidak memiliki autentikasi secara default.

Secara default, Ollama melakukan binding ke 127.0.0.1:11434. Dokumentasinya menunjukkan bahwa OLLAMA_HOST dapat mengubah alamat binding, dan proxy seperti Nginx dapat meneruskan trafik ke server. Ini adalah opsi implementasi—bukan autentikasi. Jika Anda memindahkan layanan melampaui localhost, terapkan kontrol yang disengaja di sekelilingnya.

Daftar periksa produksi

1. Pertahankan binding loopback default kecuali Anda memiliki jalur akses yang ditentukan. Jangan mengekspos port 11434 secara langsung ke internet.
2. Terapkan TLS dan autentikasi di edge. Gunakan reverse proxy, jaringan privat, identitas layanan, dan otorisasi per klien yang sesuai dengan lingkungan Anda. Kunci SDK OpenAI tiruan bukanlah kontrol akses.
3. Izinkan origin browser secara ketat. Ollama mendokumentasikan OLLAMA_ORIGINS untuk origin tambahan yang diizinkan. Tambahkan hanya origin aplikasi web atau ekstensi tepat yang memerlukan akses; jangan mengubahnya menjadi bypass lintas origin menyeluruh.
4. Gunakan daftar izin model. Perlakukan model yang diminta sebagai input yang Anda validasi. Pemanggil produksi seharusnya tidak dapat menarik model sembarang atau memilih model yang belum ditinjau.
5. Tetapkan kebijakan antrean dan tangani kelebihan beban. Ollama mendokumentasikan bahwa server yang kelebihan beban dapat mengembalikan HTTP 503 dan menyediakan OLLAMA_MAX_QUEUE. Gunakan percobaan ulang terbatas dengan backoff eksponensial dan jitter, lalu tampilkan kegagalan yang terkendali kepada pemanggil.
6. Rencanakan kapasitas VRAM dan konkurensi secara bersamaan. OLLAMA_NUM_PARALLEL meningkatkan paralelisme per model, tetapi kebutuhan memori bertambah bersamanya. OLLAMA_MAX_LOADED_MODELS dan OLLAMA_KEEP_ALIVE menentukan seberapa agresif model menggunakan memori.
7. Instrumentasikan jalur yang penting. Lacak latensi, waktu antrean, HTTP 503, inventaris model aktif, ukuran permintaan, putusnya stream, kesalahan pemanggilan tool, serta tekanan memori GPU/CPU. ollama ps membantu memverifikasi tempat model yang dimuat berjalan.
8. Uji restart dan cold start. Model lokal mungkin memerlukan waktu pemuatan setelah penerapan atau pengeluaran dari memori. Lakukan simulasi beban, rollback, dan timeout sebelum API mendukung alur kerja yang berhadapan dengan pelanggan.
9. Jauhkan rahasia dari klien. Untuk mode cloud, simpan OLLAMA_API_KEY dalam pengelola rahasia sisi server atau lingkungan runtime yang terlindungi—bukan dalam bundle frontend.
10. Sematkan rangkaian pengujian penerimaan, bukan hanya versi dependensi. Jalankan ulang pengujian chat, streaming, tool, JSON, vision, dan status respons setiap kali Anda meningkatkan Ollama, mengganti model, atau mengubah lapisan routing.

FAQ Ollama mendokumentasikan alamat binding, konfigurasi CORS, perilaku antrean, pengaturan konkurensi, serta kontrol lokal/cloud yang mendasari rekomendasi ini.

Jalur peluncuran yang lebih aman

Gunakan urutan ini untuk aplikasi yang dimulai secara lokal dan mungkin nantinya menggunakan model yang dihosting:

1. Buktikan endpoint lokal. Tarik satu model, buat daftar model, dan kirim penyelesaian chat non-streaming.
2. Stabilkan konfigurasi klien OpenAI. Jadikan URL dasar, kunci API, dan variabel lingkungan model—bukan nilai literal yang tersebar di seluruh basis kode.
3. Buat suite kompatibilitas. Sertakan output JSON, streaming, setiap skema alat, input visi jika relevan, perilaku timeout, dan permintaan yang malformed.
4. Lakukan uji beban pada host. Catat latensi, kedalaman antrean, VRAM/RAM, dan titik saat respons 503 mulai terjadi.
5. Tambahkan edge terautentikasi sebelum akses jarak jauh. Jaga Ollama tetap privat di belakang layanan aplikasi atau proxy tepercaya.
6. Evaluasi mode cloud secara terpisah. Gunakan kunci cloud khusus, model yang diizinkan, peringatan anggaran, dan kasus uji yang mencakup keterbatasan Responses khusus cloud.
7. Pisahkan pilihan penyedia dari logika bisnis. Jika produk perlu membandingkan model yang di-hosting atau menambahkan rute fallback, pertahankan kontrak klien OpenAI di balik adaptor kecil.

Untuk langkah terakhir, checklist migrasi gateway API yang kompatibel dengan OpenAI dapat membantu Anda memisahkan integrasi klien dari pemilihan penyedia model. Jika Anda ingin mengevaluasi beberapa penyedia yang di-hosting tanpa menambahkan pola klien baru untuk masing-masing, lihat panduan cepat Flatkey API dan panduan untuk menentukan kapan gateway API AI berguna.

Kesalahan umum dengan API kompatibel OpenAI Ollama

Memperlakukan server localhost seperti layanan yang diamankan

Permintaan lokal mungkin berfungsi karena proses berada di mesin yang sama, bukan karena akses diautentikasi. Begitu alamat bind, tunnel, proxy, atau port container berubah, tinjau kembali identitas, kebijakan jaringan, TLS, dan pencatatan audit.

Mengasumsikan paritas fitur OpenAI

Ollama secara eksplisit mendukung subset dari API OpenAI. Bangun pemeriksaan kapabilitas ke dalam CI dan uji semantiknya—bukan hanya respons 200. Definisi alat yang dapat diurai secara lokal mungkin berperilaku berbeda setelah pertukaran model.

Menggunakan label harga cloud sebagai anggaran

Tarif input, input yang di-cache, dan output dapat sangat berbeda. Catat field token, hitung biaya efektif per tugas yang berhasil, dan periksa kembali halaman harga sebelum menetapkan anggaran tetap.

Meningkatkan paralelisme tanpa model memori

Lebih banyak permintaan paralel dapat meningkatkan kebutuhan konteks dan memori. Pantau tekanan host nyata dengan prompt yang representatif sebelum mengubah pengaturan konkurensi.

Memberikan kunci cloud kepada browser

Panggilan langsung dari browser ke cloud membuat rotasi kunci, pengendalian anggaran, dan pencegahan penyalahgunaan jauh lebih sulit. Simpan kunci cloud di backend tepercaya dan ekspos hanya operasi yang dibutuhkan aplikasi Anda.

FAQ

Apakah API kompatibel OpenAI Ollama sama dengan API OpenAI?

Tidak. Lapisan kompatibilitas Ollama mendukung subset terdokumentasi dari API OpenAI agar klien yang kompatibel dapat terhubung ke Ollama. Konfirmasikan endpoint dan field individual dalam referensi kompatibilitas Ollama sebelum menganggap suatu fitur dapat dipindahkan.

Apakah API Ollama lokal memerlukan kunci API?

Tidak. Ollama menyatakan bahwa API lokal tidak memerlukan autentikasi. Nilai api_key="ollama" dalam contoh SDK adalah persyaratan klien yang tidak kosong, bukan kredensial. Pertahankan server lokal di localhost atau tambahkan kontrol nyata sebelum mengeksposnya dari jarak jauh.

Apakah Ollama Cloud memerlukan kunci API?

Ya. Akses cloud langsung ke https://ollama.com/v1 memerlukan kunci API yang diteruskan sebagai token Bearer. Simpan di sisi server.

Dapatkah saya menggunakan /v1/responses?

Ya, untuk permintaan Responses non-stateful. Jangan mengandalkan previous_response_id atau conversation. Dokumentasi cloud juga menyebutkan keterbatasan seputar pencarian web bawaan dan pemutaran ulang panggilan alat kustom/freeform.

Apakah API kompatibel OpenAI Ollama gratis?

Inferensi lokal tidak memiliki biaya cloud Ollama per token, tetapi Anda tetap membayar perangkat keras dan operasi yang Anda jalankan. Inferensi cloud langsung menggunakan harga per token yang dipublikasikan dan kredit akun.

Kapan saya sebaiknya menggunakan gateway?

Gunakan Ollama langsung ketika rute lokal/cloud memenuhi kebutuhan model, privasi, dan operasional beban kerja. Pertimbangkan gateway ketika produk Anda memerlukan integrasi yang konsisten di beberapa penyedia yang di-hosting, alur kerja evaluasi model, atau jalur fallback terpisah. Mulailah dengan keputusan API AI terpadu yang jelas, lalu pertahankan adaptor klien tingkat aplikasi yang sama.

Kesimpulan

API kompatibel OpenAI Ollama memberi developer cara praktis untuk menggunakan kembali SDK OpenAI dengan model yang dilayani secara lokal atau cloud. Implementasi yang aman bukan sekadar perubahan URL dasar: ini mencakup matriks kapabilitas yang teruji, model biaya lokal versus cloud yang jelas, batas deployment lokal yang privat, serta rencana teruji beban untuk antrean dan memori model.

Mulailah secara lokal jika Anda memerlukan kendali dan mampu mengoperasikan perangkat kerasnya. Gunakan cloud langsung jika Anda menginginkan inferensi terhosting melalui bentuk klien yang sama. Dalam kedua kasus, pertahankan agar pilihan endpoint dapat dikonfigurasi dan pastikan setiap fitur yang didukung layak mendapat tempat dalam rangkaian pengujian produksi Anda.