Apa artinya OpenAI-Compatible untuk sebuah API?

Jawaban singkat

Ketika penyedia mengatakan API-nya openai-compatible, itu berarti ia menerima permintaan HTTP yang sama yang dikirimkan oleh pustaka klien OpenAI dan mengembalikan respons dalam bentuk yang sama. Anda mempertahankan kode Anda, mengubah base URL dan kuncinya, dan panggilan dikirim ke server yang berbeda.

Itulah seluruh janji. Ini adalah pernyataan tentang antarmuka, seperti mengatakan dua charger menggunakan colokan yang sama. Label ini tidak memberi tahu Anda apa yang ada di ujung kabel lainnya. Model, aturan keselamatannya, harganya, dan batasnya semuanya ditentukan oleh penyedia, dan semuanya berbeda.

Apa yang sebenarnya dicakup oleh label ini

Dalam praktiknya, kompatibilitas OpenAI adalah daftar pendek hal-hal konkret. Jika sebuah penyedia mendukung semuanya, sebagian besar kode klien berjalan tanpa perubahan.

• Path. Permintaan chat dikirim ke POST /v1/chat/completions dan daftar model berasal dari GET /v1/models.
• Autentikasi. Kunci dikirimkan dalam header Authorization: Bearer.
• Badan permintaan. String model, array messages objek dengan role dan content, serta bidang sampling opsional seperti temperature, top_p, stop dan seed.
• Badan respons. Array choices dengan pesan asisten, finish_reason, dan objek usage dengan hitungan token.
• Streaming. Dengan stream: true server mengirim Server-Sent Events, masing-masing membawa delta JSON kecil, diakhiri dengan penanda akhir.
• Fitur opsional. Pemanggilan alat, mode JSON, dan bidang serupa, di mana penyedia memilih untuk mendukungnya.

Karena begitu banyak alat ditulis untuk bekerja dengan format ini, format ini menjadi target umum. Editor, kerangka kerja agen, antarmuka roleplay, dan skrip biasa semuanya memungkinkan Anda memasukkan base URL kustom, dan itu adalah satu-satunya yang mereka butuhkan.

Mengapa satu format menjadi target umum

Format chat completions menyebar karena sederhana dan hadir lebih awal. Penulis alat yang mendukungnya sekali dapat menjangkau banyak backend, dan penulis backend yang mendukungnya sekali dapat menjangkau banyak alat. Itu adalah kesepakatan yang baik untuk kedua belah pihak, sehingga formatnya bertahan, bahkan di antara layanan yang tidak ada hubungannya dengan perusahaan yang merancangnya.

Bagi Anda sebagai pengembang, ini memiliki makna praktis. Kode Anda tidak memerlukan integrasi berbeda untuk setiap penyedia. Anda dapat memindahkan prototipe di antara endpoint pada sore hari, membandingkan dua model dengan prompt yang sama, atau mempertahankan penyedia kedua sebagai cadangan ketika yang pertama lambat. Biaya untuk mengubah pikiran Anda rendah, dan itu membuatnya lebih mudah untuk mencoba layanan baru tanpa berkomitmen padanya.

Sisi sebaliknya adalah bahwa permukaan bersama menyembunyikan perbedaan nyata. Karena penggantian sangat mudah, tergoda untuk mengasumsikan bahwa segala sesuatu di balik URL setara. Itu tidak demikian, dan bagian-bagian di bawah ini menunjukkan di mana kesenjangan biasanya muncul.

Apa yang tidak dijelaskan label ini

Di sinilah orang-orang terkejut. Label ini melewatkan segala sesuatu yang menentukan apakah API berguna untuk pekerjaan Anda.

Model di baliknya

Endpoint yang kompatibel dapat melayani model apa pun. Beberapa melayani model open-weight, beberapa mengarahkan ke beberapa vendor, beberapa membungkus model milik sendiri. Kompatibilitas tidak berarti layanan dijalankan oleh OpenAI, dan tidak berarti model berperilaku seperti milik mereka. Nama model yang Anda masukkan di model hanyalah string yang ditentukan oleh penyedia.

Perilaku penolakan

Aturan konten milik model dan penyedia, bukan protokol. Dua API yang kompatibel dapat menjawab prompt yang sama dengan cara yang berlawanan. Jika kasus penggunaan Anda adalah fiksi, roleplay, atau konten dewasa yang sah lainnya, periksa apa yang dikatakan penyedia tentang penolakan sebelum Anda menghubungkan apa pun.

Kedalaman fitur

Beberapa penyedia hanya mengimplementasikan chat. Yang lain menambahkan alat, mode JSON, probabilitas log, atau endpoint tambahan. Klien yang mengirim bidang yang diabaikan server tidak selalu melempar error/exception, sehingga ketidakcocokan diam mungkin terjadi.

Batas, harga, dan kesalahan

Batas laju, panjang konteks, ukuran badan maksimum, dan harga per token adalah pilihan penyedia. Badan kesalahan juga berbeda dalam detail meskipun kode status HTTP cocok, sehingga logika retry harus didasarkan pada kode status dan header, bukan pada teks pesan.

Tes kompatibilitas cepat

Anda dapat memverifikasi penyedia dalam beberapa menit dengan tiga permintaan. Ganti kuncinya dengan kunci Anda sendiri. Contoh ini menggunakan base URL situs ini.

Copycurl https://api.kimicode.top/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

curl https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Reply with the word ready."}]
  }'

Panggilan pertama memverifikasi kunci dan mencantumkan ID model. Panggilan kedua memeriksa format chat. Kemudian uji bagian yang dibutuhkan aplikasi Anda: tambahkan "stream": true dan perhatikan potongan inkremental, kirimkan array tools jika Anda menggunakan pemanggilan fungsi, dan atur response_format ke {"type":"json_object"} jika Anda memerlukan output yang dapat diparsing.

Picu juga kesalahan secara sengaja, seperti kunci yang buruk. Anda ingin melihat status HTTP yang bersih dan badan kesalahan JSON yang dapat ditangani oleh klien Anda.

Panggilan yang sama di Node

SDK JavaScript mengambil dua nilai yang sama. Berikut adalah panggilan streaming, yang merupakan bentuk yang paling banyak digunakan oleh antarmuka chat.

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.kimicode.top/v1",
  apiKey: process.env.API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  stream: true,
  messages: [{ role: "user", content: "Name three uses of SSE." }],
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

Jika ini mencetak teks kata demi kata, jalur streaming berfungsi dari awal hingga akhir. Loop yang sama berfungsi terhadap penyedia yang kompatibel mana pun, yang merupakan poin utama dari format ini.

Bagaimana tampilan pengalihan dalam kode

Dengan SDK Python resmi, perubahannya adalah dua argumen konstruktor. Sisa program Anda tetap seperti sebelumnya.

Copyfrom openai import OpenAI

client = OpenAI(
    base_url="https://api.kimicode.top/v1",
    api_key="YOUR_API_KEY",
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Summarize SSE in one sentence."}],
)
print(resp.choices[0].message.content)

SDK Node adalah ide yang sama dengan opsi baseURL dan apiKey. Banyak alat membaca OPENAI_BASE_URL dan OPENAI_API_KEY dari lingkungan, sehingga Anda kadang-kadang dapat beralih tanpa menyentuh kode sama sekali.

Ingat untuk mengubah string model juga. Permintaan yang menyebutkan model yang tidak di-host oleh server baru akan gagal, dan itu adalah kesalahan pertama yang paling umum.

Di mana API situs ini cocok

Layanan ini adalah API teks saja yang mengikuti format OpenAI. Ini menjalankan satu model open-weight, dioperasikan oleh penyedia independen dan disesuaikan untuk menjawab tanpa penolakan konten untuk penggunaan dewasa yang sah. Ini bukan API resmi dari vendor model mana pun dan tidak mengarahkan di antara vendor. ID modelnya adalah uncensored.

Ini mendukung streaming melalui SSE dengan penggunaan yang dilaporkan di akhir, pemanggilan alat, mode JSON, dan meneruskan temperature, top_p, stop, seed dan penalti. Jendela konteks adalah 100.000 token untuk prompt dan penyelesaian bersama-sama. Ini tidak menghasilkan gambar atau audio, dan tidak menawarkan embedding atau fine-tuning. Satu aturan tetap: tidak ada konten seksual yang melibatkan anak di bawah umur.

Penagihan bersifat prabayar dan terukur: $0,15 per 1 juta token input dan $0,50 per 1 juta token output, tanpa langganan. Anda dapat melihat angka-angka tersebut di halaman harga, dan dokumentasi menjelaskan permintaan pertama. Jika Anda ingin mencobanya tanpa membayar, akun baru dapat mengklaim kredit uji coba senilai $0,50 dengan satu klik di halaman kunci API.

Jebakan kompatibilitas umum

1. URL dasar yang salah. URL harus berakhir di /v1. Klien menambahkan /chat/completions sendiri, sehingga menambahkannya ke URL dasar akan menghasilkan 404.
2. Parameter yang tidak didukung. Jika sebuah library mengirimkan bidang yang tidak dikenal oleh server, periksa apakah bidang tersebut ditolak atau diabaikan secara diam-diam, lalu hapus bidang tersebut.
3. Streaming dan konkurensi. Permintaan streaming memegang slot konkurensi hingga streaming berakhir. Jika aplikasi Anda membuka banyak streaming, Anda dapat mengalami 429 dengan kode concurrency meskipun hitungan per menit Anda rendah.
4. Ulangi permintaan saat 429. Anggap 429 sebagai sinyal untuk menunggu. Saat header Retry-After ada, hormati header tersebut.
5. Penghitungan token. Jangan mengasumsikan tokenizer penyedia lain cocok. Baca objek usage dalam respons untuk mendapatkan angka yang menjadi dasar penagihan Anda.

Tidak ada yang sulit diperbaiki setelah Anda tahu cara mencarinya, dan sebagian besar masalah ini hanya memerlukan pembacaan pesan kesalahan pertama dengan cermat.

Panduan lainnya

• OpenCode dengan API Kompatibel OpenAI: Pengaturan
• Alternatif Kimicode: API LLM Terhosting Tanpa Sensor
• API LLM Tanpa Sensor: Integrasi & Harga Kompatibel OpenAI