Tak-Çalıştır OpenAI Uyumlu API — İki Satırda Geçiş

unbleep, OpenAI uyumlu bir API'dir; pratikte bu, geçişin iki satırdan ibaret olduğu ve yeni bir bağımlılık gerektirmediği anlamına gelir. Resmi SDK'yı, yeniden deneme mantığınızı, streaming döngünüzü, token muhasebenizi ve hata işleyicilerinizi olduğu gibi tutarsınız. Değişen şey, isteklerin nereye gittiği ve onları hangi anahtarın doğruladığıdır. Bu yazı önce değişimi, ardından haberiniz yoksa bir şeyleri bozacak kadar farklı olan dört noktayı ele alıyor.

OpenAI uyumlu API'ye iki satırda geçiş

python

import os

from openai import OpenAI

client = OpenAI(
    base_url="https://unbleep.ai/v1",
    api_key=os.environ["UNBLEEP_API_KEY"],
)

resp = client.chat.completions.create(
    model="unbleep",
    messages=[{"role": "user", "content": "Summarise this incident report."}],
)
print(resp.choices[0].message.content)

Koda hiç dokunmamayı tercih ederseniz, SDK her iki değeri de ortam değişkenlerinden okur; dolayısıyla bir yapılandırma değişikliği yeterlidir:

bash

export OPENAI_BASE_URL="https://unbleep.ai/v1"
export OPENAI_API_KEY="ub_live_9f2c..."

Aynı ikili, SDK'nın üzerine inşa edilmiş ekosistemin büyük kısmını da kapsar — LangChain, LlamaIndex, Instructor, Vercel AI SDK, base URL ayarı sunan her şey. Anahtarlar, sızıntılar gizli anahtar tarayıcıları (secret scanner) tarafından hemen fark edilsin diye ön ekli gelir: ub_live_ ve ub_test_, ikisi de aynı ön ödemeli krediden, aynı token başı ücretle faturalandırılır. Test anahtarı, daha düşük tavanı olan — hesabın 60'ı yerine dakikada 15 istek — ayrı, iptal edilebilir bir kimlik bilgisidir; ücretsiz bir katman değildir. İkisini de sunucu tarafında tutun.

GET /v1/models çalışır; dolayısıyla bir açılır menüyü doldurmak için modelleri listeleyen araçların özel bir muameleye ihtiyacı yoktur.

Model seçimi

Üç katman. Tarihli id'ler — unbleep-250811, unbleep-high-250811, unbleep-mini-250811 — takma ad (alias) olarak kabul edilir, ancak bugün çıplak id ile aynı derlemeye çözümlenirler ve yanıt, çıplak id'yi geri bildirir. Onları bir tekrarlanabilirlik garantisi olarak değil, ileriye dönük uyumlu bir yazım olarak görün; bir değerlendirmenin tekrarlanabilir olması gerekiyorsa model id'sini değil, çıktıları kaydedin.

| Model | Bağlam | Fiyat giriş / çıkış, 1M başına | Notlar | | --- | --- | --- | --- | | unbleep | 256K | $3.00 / $3.00 | Varsayılan. Akıl yürütme katmanı. | | unbleep-high | 1M* | $5.00 / $5.00 | En büyük işler. Akıl yürütme katmanı. | | unbleep-mini | 32K | $1.00 / $1.00 | Ucuz ve hızlı. Doğrudan yanıtlar, akıl yürütme izi yok. |

*İstek gövdesi 2.000.000 bayt ile sınırlıdır — kabaca 500k token — bu yüzden tek bir çağrı 1M'lik pencereyi fiilen dolduramaz; daha büyük her şey 413 payload_too_large ile geri döner.

unbleep-mini'deki 32K tavanı, 128K bağlamlı bir modelden geçenleri yakalayan tavandır: daha önce sığan bir prompt artık reddedilir. Maliyete göre yönlendiriyorsanız, uzunluğa göre de yönlendirin.

python

def pick_model(prompt_chars: int) -> str:
    """~4 chars/token is a deliberate under-estimate; leave room for the completion."""
    est_tokens = prompt_chars // 4
    if est_tokens < 24_000:
        return "unbleep-mini"
    return "unbleep" if est_tokens < 200_000 else "unbleep-high"

Streaming

stream=True verin ve standart Server-Sent Events alın: her olay bir delta taşıyan bir chat.completion.chunk'tır ve akış, düz bir data: [DONE] ile sonlanır. Mevcut döngünüz değişmeden çalışır.

bash

curl -N https://unbleep.ai/v1/chat/completions \
  -H "Authorization: Bearer $UNBLEEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "unbleep",
    "messages": [{"role": "user", "content": "Explain the residual stream."}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

Token sayılarını isteseniz de istemeseniz de alırsınız: unbleep arka uçtan kullanım bilgisini (usage) her zaman ister ve iletir; onu çıkışta yalnızca açık bir stream_options: {"include_usage": false} kaldırır. Her iki durumda da akış, choices dizisi boş olan tek bir son parçayla (chunk) biter — vazgeçmediyseniz dolu usage nesnesini taşıyarak — aşağıdaki döngünün ona dokunmadan önce choices'ı kontrol etmesinin nedeni de budur.

reasoning_content alanı

Şemaya yapılan tek gerçek ekleme bu. unbleep ve unbleep-high yanıt vermeden önce düşünür ve bu düşünce zinciri, mesaj (streaming olmayan) ya da delta (streaming) üzerinde content'in kardeşi olan reasoning_content alanında döner. Yukarı akış arka uçları buna reasoning mi yoksa reasoning_content mi denmesi konusunda anlaşamıyor; API bunu reasoning_content olarak normalleştirir, böylece yalnızca tek bir şekille uğraşırsınız.

OpenAI şemasının parçası olmadığı için SDK'nın tip tanımlarında (type stubs) yer almaz. Yanıt modelleri ek alanlara izin verir, dolayısıyla öznitelik erişimi çalışma zamanında çalışır — ama izi olmayan bir mini yanıtı hata fırlatmasın diye getattr ile okuyun:

python

import sys

stream = client.chat.completions.create(
    model="unbleep",
    messages=[{"role": "user", "content": "Why did this detection rule misfire?"}],
    stream=True,
    stream_options={"include_usage": True},
)

usage = None
for chunk in stream:
    if not chunk.choices:          # final usage-only chunk
        usage = chunk.usage
        continue
    delta = chunk.choices[0].delta
    thought = getattr(delta, "reasoning_content", None)
    if thought:                    # trace to stderr, answer to stdout
        sys.stderr.write(thought)
    if delta.content:
        sys.stdout.write(delta.content)

if usage:
    details = usage.completion_tokens_details
    print(f"\nreasoning tokens: {getattr(details, 'reasoning_tokens', 0)}")

Üç pratik sonuç:

Akıl yürütme token'ları çıktı token'ıdır. completion_tokens içinde görünürler ve çıktı ücretiyle faturalandırılırlar. usage.completion_tokens_details.reasoning_tokens, faturanın ne kadarının düşünmeye gittiğini söyler.
max_tokens'ı da tüketirler. Akıl yürütme katmanında sıkı bir limit tamamen ize harcanabilir; size kesilmiş bir yanıt ya da boş bir content kalır. Her ikisi için de bütçe ayırın ya da düşünmeyi kapatın.
İhtiyacınız yoksa kapatın. Kısa ya da yüksek hacimli çağrılar için extra_body üzerinden "thinking": false gönderin. reasoning_effort da aynen geçer.

python

resp = client.chat.completions.create(
    model="unbleep",
    messages=[{"role": "user", "content": "phishing or benign?"}],
    max_tokens=4,
    extra_body={"thinking": False},   # spend the budget on the answer, not the trace
)

reasoning_content'i asla sonraki bir tura asistan içeriği olarak geri beslemeyin. O, sohbet geçmişi değil tanılama çıktısıdır ve yeniden oynatılması bir sonraki yanıtın kalitesini düşürür.

Hatalar ve iki gerçek tuzak

Hatalar OpenAI zarfını kullanır — {"error": {"type", "code", "message"}} — dolayısıyla mevcut except bloklarınız çalışmaya devam eder. Durum kodları beklediğiniz gibi eşlenir: 401 geçersiz anahtar, 422 policy: strict tarafından engellendi, 429 hız sınırı, 5xx yeniden denenebilir yukarı akış hatası.

Muhtemelen daha önce hiç ele almadığınız durum kodu 402, kredi bitti. Hesaplar ön ödemelidir; dolayısıyla aşım da yok, fatura da yok — bakiye yükleyene kadar istekler yalnızca durur. OpenAI kota tükenmesini 429 ile bildirir; bu da naif geçiş yolunda geri çekilme (backoff) mantığınızın bir 402'yi sonsuza kadar yeniden denemesi demektir. Onu nihai kabul edin ve üzerine uyarı kurun.

İkinci tuzak: system_fingerprint döndürülmez. Sunum yapan arka ucu tanımladığı için diğer sağlayıcı alanlarıyla birlikte ayıklanır. Bir önbelleği ya da tekrarlanabilirlik kontrolünü ona göre anahtarlıyorsanız kendi sürüm işaretçinize ihtiyacınız olacak: tarihli model id'leri dondurulmuş anlık görüntüler değil, güncel derlemenin takma adlarıdır; dolayısıyla arka uç değiştiğinde size haber vermezler.

Hız sınırları her yanıtta başlık (header) olarak geri gelir — x-ratelimit-limit-requests, x-ratelimit-remaining-requests, x-ratelimit-reset-requests — böylece bir toplu iş, tavanı ona çarparak keşfetmek yerine istek hızını kendisi ayarlayabilir. Başlıkların tarif etmediği ikinci bir tavan daha var: hesap başına aynı anda en fazla 8 açık istek; dokuzuncusu too_many_concurrent_requests koduyla 429 döner. Streaming bir çağrı, akış bitene kadar yerini tutar; bu yüzden kendi worker havuzunuzu 8 ile sınırlayın.

Neye yönlendirdiğinizi bilin

Açıkça söylemekte fayda var: bu uç noktanın arkasındaki modeller abliterated modellerdir; yani reddetme davranışları ağırlık düzeyinde kaldırılmıştır. Amaç da bu — bu, reddetmenin bir ölçüm hatası olduğu güvenlik araştırması, red-teaming ve değerlendirme işlerine yönelik bir geliştirici API'sidir. Bu aynı zamanda, kötü bir prompt'u yakalayacak olağan koruma bariyerlerinin orada olmadığı anlamına da gelir; bu yüzden çıktılardan sorumlu bir insan bulundurun ve kabul edilebilir kullanım politikasını okuyun. Yasalara uygun kullanım sizin sorumluluğunuzdadır.

Bir API anahtarı alın — geçiş gerçekten iki satır.