API için OpenAI Uyumlu Olmak Ne Anlama Gelir?

Kısa cevap

Bir sağlayıcı API'sinin openai-uyumlu olduğunu söylediğinde, OpenAI istemci kütüphanelerinin gönderdiği aynı HTTP isteklerini kabul ettiği ve aynı yapıda yanıtlar döndürdüğü anlamına gelir. Kodunuzu korursunuz, base URL'yi ve anahtarı değiştirirsiniz ve çağrı farklı bir sunucuya gider.

Bu tüm vaatdir. Arayüz hakkında bir ifadedir, tıpkı iki şarj aletinin aynı fişi kullandığını söylemek gibidir. Kablonun diğer ucunda ne olduğunu söylemez. Model, güvenlik kuralları, fiyatı ve limitleri tümüyle sağlayıcı tarafından belirlenir ve büyük farklılıklar gösterir.

Etiket aslında neyi kapsar

Pratikte OpenAI uyumluluğu somut bir liste anlamına gelir. Bir sağlayıcı bunların tümünü destekliyorsa, istemci kodu çoğunlukla değişmeden çalışır.

• Yollar. Sohbet istekleri POST /v1/chat/completions adresine gider ve model listesi GET /v1/models adresinden gelir.
• Kimlik doğrulama. Anahtar bir Authorization: Bearer başlığında taşınır.
• İstek gövdesi. Bir model dizesi, role ve content içeren nesnelerden oluşan bir messages dizisi ve isteğe bağlı temperature, top_p, stop ve seed gibi örnekleme alanları.
• Yanıt gövdesi. Yardımcı mesajı içeren bir choices dizisi, bir finish_reason ve token sayıları içeren bir usage nesnesi.
• Akış. stream: true ile sunucu Sunucu Gönderilen Olaylar (SSE) gönderir; her biri küçük bir JSON delta'sı taşır ve bir son işaretle biter.
• İsteğe bağlı özellikler. Araç çağırma, JSON modu ve benzeri alanlar; sağlayıcı bunları desteklemeyi seçer.

Bu format için çok fazla araç yazıldığı için ortak bir hedef haline geldi. Editörler, ajan çerçeveleri, rol yapma arayüzleri ve basit betikler size özel bir base URL girmenize olanak tanır ve bu tek ihtiyaçlarıdır.

Neden bir format ortak hedef haline geldi

Sohbet tamamlama formatı basitliği ve erken gelmesi nedeniyle yayıldı. Bunu destekleyen bir araç yazarı bir kez destekleyerek birçok arka uca ulaşabilir; bir arka uç yazarı da bir kez destekleyerek birçok araca ulaşabilir. Bu her iki taraf için de iyi bir anlaşmadır, bu nedenle format yapısını tasarlayan şirketten bağımsız hizmetler arasında bile yerleşti.

Siz bir geliştirici olarak bunun pratik bir anlamı vardır. Kodunuzun her sağlayıcı için farklı bir entegrasyona ihtiyacı yoktur. Bir prototipi bir öğleden sonra uç noktalar arasında taşıyabilir, aynı istemlerle iki modeli karşılaştırabilir veya ilk yavaş olduğunda ikinci bir sağlayıcıyı yedek olarak tutabilirsiniz. Fikrinizi değiştirmenin maliyeti düşüktür ve bu da yeni bir hizmeti taahhüt etmeden denemeyi kolaylaştırır.

Yüzeyin ortak olması gerçek farklılıkları gizler. Geçiş çok kolay olduğu için, URL'nin arkasındaki her şeyin eşdeğer olduğunu varsamak cazip olabilir. Değildir ve aşağıdaki bölümler boşlukların genellikle nerede ortaya çıktığını gösterir.

Etiket size ne söylemez

İnsanların şaşırdığı yer burasıdır. Etiket API'nin işiniz için kullanışlı olup olmadığını belirleyen her şeyi dışarıda bırakır.

Arkadaki model

Uyumlu bir uç nokta herhangi bir modeli sunabilir. Bazıları açık ağırlıklı modelleri sunar, bazıları birkaç tedarikçiye yönlendirme yapar, bazıları özel bir modeli sarar. Uyumluluk, hizmetin OpenAI tarafından işletildiği anlamına gelmez ve modelin onlarınkiler gibi davrandığı anlamına gelmez. model içinde ilettiğiniz model adı, sağlayıcının tanımladığı bir dizedir.

Reddetme davranışı

İçerik kuralları modele ve sağlayıcıya aittir, protokole değil. İki uyumlu API aynı isteğe karşıt şekillerde yanıt verebilir. Kullanım durumunuz kurgu, rol yapma veya başka yasal yetişkin içeriği ise, herhangi bir şeyi bağlamadan önce sağlayıcının reddetmeler hakkında ne söylediğini kontrol edin.

Özellik derinliği

Bazı sağlayıcılar yalnızca sohbeti uygular. Diğerleri araçları, JSON modunu, log olasılıklarını veya ek uç noktaları ekler. Sunucunun yok saydığı bir alan gönderen bir istemci her zaman gürültülü bir şekilde başarısız olmayabilir, bu nedenle sessiz bir eşleşmezlik mümkündür.

Limitler, fiyatlandırma ve hatalar

Hız limitleri, bağlam penceresi uzunluğu, maksimum gövde boyutu ve token başına fiyat tümü sağlayıcı tercihleridir. Hata gövdeleri HTTP durum kodları eşleşse bile detaylarda farklılık gösterir, bu nedenle yeniden deneme mantığı durum kodlarına ve başlıklara göre baz alınmalıdır, mesaj metnine göre değil.

Hızlı bir uyumluluk testi

Bir sağlayıcıyı üç istekle birkaç dakikada doğrulayabilirsiniz. Anahtarı kendi anahtarınızla değiştirin. Bu örnek bu sitenin base URL'sini kullanır.

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."}]
  }'

İlk çağrı anahtarı doğrular ve model kimliklerini listeler. İkinci çağrı sohbet yapısını kontrol eder. Ardından uygulamanızın bağlı olduğu kısımları test edin: "stream": true ekleyin ve artımlı parçaları izleyin, fonksiyon çağırma kullanıyorsanız bir tools dizisi geçirin ve ayrıştırılabilir çıktıya ihtiyacınız varsa response_format alanını {"type":"json_object"} olarak ayarlayın.

Ayrıca kasıtlı bir hata tetikleyin, örneğin kötü bir anahtar. Temel bir HTTP durum kodu ve istemcinizin işleyebileceği bir JSON hata gövdesi görmek istersiniz.

Node ile aynı çağrı

JavaScript SDK'sı aynı iki değeri alır. İşte çoğu sohbet arayüzünün kullandığı bir akış çağrısı.

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 ?? "");
}

Bu metni kelime kelime yazdırıyorsa, akış yolu uçtan uca çalışır. Aynı döngü herhangi bir uyumlu sağlayıcıda çalışır; bu formatın tüm noktası budur.

Kodda geçiş nasıl görünür

Resmi Python SDK ile değişiklik iki yapıcı argümanıdır. Programınızın geri kalanı olduğu gibi kalır.

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)

Node SDK, baseURL ve apiKey seçenekleriyle aynı mantığı izler. Birçok araç, ortam değişkenlerinden OPENAI_BASE_URL ve OPENAI_API_KEY değerlerini okur; bu nedenle kodu değiştirmeden de geçiş yapabilirsiniz.

Model dizesini de değiştirmeyi unutmayın. Yeni sunucunun barındırmadığı bir modeli adlandıran bir istek başarısız olur ve bu en yaygın ilk hatadır.

Bu sitenin API'si nereye uyuyor

Bu hizmet, OpenAI biçimini takip eden barındırılmış, yalnızca metin içeren bir API'dir. Bağımsız bir sağlayıcı tarafından işletilen ve yasal yetişkin kullanımı için içerik reddi olmadan yanıt verecek şekilde ayarlanmış tek bir açık ağırlıklı modeli çalıştırır. Herhangi bir model tedarikçisinin resmi API'si değildir ve tedarikçiler arasında yönlendirme yapmaz. Model kimliği uncensored'dir.

SSE üzerinden akış desteği sunar ve kullanım bilgilerini sonradan bildirir; fonksiyon çağırma, JSON modu destekler; temperature, top_p, stop, seed ve ceza parametrelerini doğrudan geçirir. Bağlam penceresi, istem ve tamamlama birlikte 100,000 token kapasitesine sahiptir. Görsel veya ses üretmez; embedding veya ince ayama (fine-tuning) sunmaz. Tek sabit kural şudur: reşit olmayanlarla ilgili cinsel içerik yoktur.

Faturalandırma ön ödemeli ve ölçümlüdür: 1M giriş token başına $0,15 ve 1M çıktı token başına $0,50, abonelik yoktur. Sayıları fiyatlandırma sayfasında görebilirsiniz ve belgeler ilk isteği adım adım gösterir. Ödemeden denemek isterseniz, yeni hesaplar API anahtarı sayfasında tek tıkla $0,50 deneme kredisi talep edebilir.

Yaygın uyumluluk sorunları

1. Yanlış base URL. URL /v1 ile bitmelidir. İstemciler /chat/completions eklemesini kendileri yapar; base URL'ye eklerseniz 404 hatası alırsınız.
2. Desteklenmeyen parametreler. Bir kütüphane sunucunun tanımadığı bir alan gönderirse, bunun reddedilip reddedilmediğini veya sessizce atlanıp atlanmadığını kontrol edin ve ardından kaldırın.
3. Akış ve eşzamanlılık. Akışlı bir istek, akış bitene kadar bir eşzamanlılık slotunu meşgul tutar. Uygulamanız çok sayıda akış açarsa, dakika başına sayınız düşük olsa bile concurrency koduyla 429 hatası alabilirsiniz.
4. 429 durumunda yeniden dene. 429'u bir bekleme sinyali olarak kabul edin. Retry-After başlığı mevcut olduğunda, ona saygı gösterin.
5. Token sayımı. Başka bir sağlayıcının tokeniser'ının eşleşeceğini varsaymayın. Ücretlendirildiğiniz sayılar için yanıtta bulunan usage nesnesini okuyun.

Bunların hiçbiri, aramayı nasıl yapacağınızı bildikten sonra düzeltmek kolaydır ve çoğu ilk hata mesajını dikkatlice okumaya dayanır.

Daha fazla kılavuz

• OpenCode ile OpenAI Uyumlu API: Kurulum
• Kimicode Alternatifi: Sansürsüz Barındırılan LLM API
• Sansürsüz LLM API: OpenAI Uyumlu Entegrasyon ve Fiyatlandırma