API geçidi geçiş kılavuzu: OpenAI ve OpenRouter'dan sansürsüz API'ye geçiş

API geçidi ile özel sansürsüz model arasındaki fark nedir

Önce kavramları netleştirin, aksi takdirde geçiş sırasında yanlış yöne kaymak kolaydır. Yaygın API yönlendirme istasyonları, temelde büyük şirketlerin çağrı kotasını satmak veya birleştirmektir; size OpenAI ile uyumlu bir uç nokta sunar ve aynı SDK ile farklı modellere geçiş yapmanızı sağlar. Erişim ve ödeme sorununu çözer: tek bir giriş noktası, tek bir fatura. Ancak model aynı kalır; orijinal içerik politikası değişmez. Reddedilmesi gereken konular yine reddedilir; bir yönlendirme adresi değiştirmek bunu değiştirmez.

Özel sansürsüz model ise tamamen farklı bir konudur. Başkalarının modelini iletmez; bağımsız olarak sağlanan bir modeldir. Yasal yetişkin içeriği, kurgusal içerik ve tartışmalı konular reddedilmez. Wu Xianzhi API yalnızca bir model sunar: model adı uncensored'dir. Arayüzü OpenAI formatıyla uyumludur, bu nedenle geçiş maliyeti düşüktür. Ancak net sınırları vardır: yalnızca metin yapar; görsel, ses, vektör ve ince ayarı desteklemez. Küçük yaşlılarla ilgili cinsel içerik, kurgusal olsa bile engellenir ve 403 hatası döndürür.

Bu nedenle geçişten önce kendinize sorun: Karşılaştığınız sorun "uygulama istikrarsızlığı veya yüksek fiyat" mu, yoksa "modelin yasal isteklerinizi sürekli reddetmesi" mi? İkinci durum söz konusuysa geçit değiştirmek pek anlam ifade etmez; özel sansürsüz API'ye geçmek sorunu çözer. Birçok ekip her iki yapıyı da birlikte kullanır: Genel görevler için eski uç noktayı kullanmaya devam eder, sansürsüz çıktı gerektiren istekleri ise bu uç noktaya yönlendirir. Detayları aşağıda bulabilirsiniz.

OpenAI veya OpenRouter'dan geçişte değiştirilecek üç yer

Daha önce OpenAI resmi API'sini, OpenRouter gibi birleştirici bir hizmeti veya bir API geçidini kullanmış olsanız da, OpenAI uyumlu bir SDK kullanıyorsanız değiştirmeniz gereken yalnızca üç şey vardır: base_url değerini https://api.wuxianzhiapi.com/v1 olarak değiştirin; api_key değerini /get-api-key/ adresinden aldığınız gizli anahtar ile değiştirin; model değerini uncensored olarak ayarlayın. Başka model seçeneği yoktur; GET /v1/models endpoint'inde yalnızca bu model yer alır.

复制import os
from openai import OpenAI

messages = [{"role": "user", "content": "你好"}]

# 迁移前（示意）：
# client = OpenAI(api_key=os.environ["OLD_API_KEY"], base_url="旧地址")
# resp = client.chat.completions.create(model="旧模型名", messages=messages)

# 迁移后：只动 base_url、api_key、model 这三处
client = OpenAI(
    base_url="https://api.wuxianzhiapi.com/v1",
    api_key=os.environ["WUXIANZHI_API_KEY"],
)
resp = client.chat.completions.create(model="uncensored", messages=messages, max_tokens=100)
print(resp.choices[0].message.content)

Node.js için de aynı şekilde, new OpenAI({...}) içindeki baseURL ve apiKey değerlerini değiştirin. Projenizde doğrudan HTTP istekleri kullanıyorsanız, istek adresini https://api.wuxianzhiapi.com/v1/chat/completions olarak değiştirin ve istek başlığını Authorization: Bearer <API anahtarı> olarak koruyun. Tam Python, Node.js ve cURL örnekleri için kod örnekleri sayfasına bakın.

复制curl https://api.wuxianzhiapi.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WUXIANZHI_API_KEY" \
  -d '{"model":"uncensored","messages":[{"role":"user","content":"你好"}],"max_tokens":50}'

Parametre karşılaştırması: Hangileri kullanılır, hangileri kullanılmaz

Aşağıdaki tablo geçiş sırasında en sık karşılaşılan alanları inceler. Kural şudur: Sohbetle ilgili olan ve OpenAI formatının temel alanları sorunsuz kullanılabilir; "başka modeller veya çok modlu yetenekler" ile ilgili özellikler burada yer almaz.

Eski kullanım şekli	Burada nasıl ele alınır
model (çeşitli gpt modelleri)	uncensored olarak değiştirilmelidir
messages (system / user / assistant / tool)	Format aynıdır; doğrudan kullanın
max_tokens	Varsayılan 2048, maksimum 32.000; aşım durumunda 400 hatası döndürülür
stream: true	Desteklenir; sona bir kullanım bloğu eklenir
tools / tool_choice	Desteklenir; OpenAI formatındadır
Bağlam penceresi uzunluğu	İstem ve çıktı toplamı 100.000 token
İstek gövdesi boyutu	8 MB'ı geçmemelidir
Hız limiti	Her anahtar için dakikada 300 istek
Vektör embeddings	Desteklenmez
Görsel oluşturma / görsel tanıma, ses, video	Desteklenmez; yalnızca metin işler
İnce ayar (fine-tuning)	Desteklenmiyor
Birden fazla model arasında geçiş yapın	Sadece bir model var, geçiş yapılabilecek bir liste yok

Tabloda listelenmeyen diğer isteğe bağlı alanlar için, bunların orijinal üretici yöntemine göre varsayılan olarak çalışacağını kabul etmeyin. En güvenli yaklaşım, davranışın beklentilere uygunluğunu doğrulayana kadar bunları test ortamında ayrı ayrı çalıştırmaktır. Hangi alanların desteklendiğine dair kesin bilgi API dokümantasyonu'na bakın.

Yoksa yetenekler nasıl? Vektör, görsel ve ses için alternatif yaklaşımlar

Eğer mevcut projeniz hem sohbet hem de vektör araması kullanıyorsa, geçiş yaparken "her şeyi aynı anda değiştir" yaklaşımından kaçının. Biz sadece metin tabanlı sohbet sağlıyoruz, bu nedenle bilgi tabanı araması veya anlamsal benzerlik tespiti gibi vektör (embeddings) ile ilgili kodlarınızı mevcut vektör servisinizde kullanmaya devam etmeniz veya kendi vektör çözümünüzü dağıtmanız gerekir. Sohbet kısmını buraya taşıyın, arama kısmını olduğu gibi bırakın; bu iki taraf birbirini etkilemez ve en kolay ayrıştırma yöntemidir.

Görseller ve ses için de durum aynıdır. Ürününüz "metin + görsel" formatındaysa, metin üretimi için burayı kullanın, görseller için mevcut görsel API'nizi kullanmaya devam edin. Sesli okuma gerekiyorsa, metin üretildikten sonra mevcut ses servisinize yönlendirin. "Metin üret" adımı ayrı bir fonksiyon olarak ayrıldığında, diğer yetenekleri nasıl birleştirirseniz birleştirin, yapılan değişiklik çok az olacaktır.

Başka bir durumda kodunuzda farklı görevler için birden fazla model kullanıyordur: ucuz model sınıflandırma için, pahalı model içerik üretimi için. Burada yalnızca bir model vardır; sınıflandırma görevini de bu model yapacaktır. İyi haber, giriş birim fiyatının 1 milyon token başına $0,25 olmasıdır. Sınıflandırma gibi kısa çıktı gerektiren görevlerin maliyeti düşüktür. max_tokens değerini küçük tutarak maliyeti neredeyse ihmal edilebilir seviyeye indirebilirsiniz. Fiyat detayları için fiyatlandırma sayfası sayfasına bakın.

Paralel çalıştırma: Ortam değişkenleriyle iki API arasında geçiş yapın

Geçiş yaparken en büyük korku "tek seferde her şeyi değiştir" yaklaşımıdır. Daha güvenli bir yaklaşım, kodunuza ince bir sarmalayıcı (wrapper) katmanı eklemek ve ortam değişkenleri ile hangi API'nin kullanılacağını belirlemektir. Bu sayede trafiğin veya işlevlerin sadece küçük bir kısmını yeni API'ye yönlendirebilir, bir sorun çıkarsa tek bir değişkeni değiştirerek geri dönebilirsiniz. Her iki API de OpenAI uyumlu format kullandığından sarmalayıcı kodu oldukça basittir.

复制import os
from openai import OpenAI

PROVIDERS = {
    "old": {
        "base_url": os.environ.get("OLD_BASE_URL", ""),
        "api_key": os.environ.get("OLD_API_KEY", ""),
        "model": os.environ.get("OLD_MODEL", ""),
    },
    "wuxianzhi": {
        "base_url": "https://api.wuxianzhiapi.com/v1",
        "api_key": os.environ.get("WUXIANZHI_API_KEY", ""),
        "model": "uncensored",
    },
}

def get_client(name=None):
    name = name or os.environ.get("LLM_PROVIDER", "old")
    cfg = PROVIDERS[name]
    return OpenAI(base_url=cfg["base_url"], api_key=cfg["api_key"]), cfg["model"]

def chat(messages, provider=None, **kwargs):
    client, model = get_client(provider)
    return client.chat.completions.create(model=model, messages=messages, **kwargs)

# 通用任务走旧接口，需要无审查输出的请求显式指定新接口
resp = chat([{"role": "user", "content": "写一个黑色幽默的短故事"}],
            provider="wuxianzhi", max_tokens=800)
print(resp.choices[0].message.content)

Geçiş granülerliği üç düzeyde yapılabilir: ortam bazlı (test ortamında önce geçiş), işlev bazlı (sadece yaratıcı API'ler getirilir) veya kullanıcı bazlı (belirli hesaplar kademeli olarak alınır). Herhangi bir düzeyde, günlüklerde kaydedilen provider alanını bırakmanız önerilir; böylece farklılıklar ortaya çıktığında karşılaştırma yaparak sorunu ayıklayabilirsiniz. Sohbet geçmişinin de standart messages dizisi olarak kaydedilmesi önerilir; bu sayede aynı konuşma iki taraf arasında kesintisiz devam edebilir.

Geçiş kontrol listesi

Canlıya almadan önce aşağıdaki sırayı takip ederek kontrol listenizi tamamlayın, böylece hiçbir adım atlanmaz:

1. /get-api-key/ adresinde kaydolun, anahtarınızı alın ve doğrulama için $0,50 deneme bakiyesini (7 gün geçerli) kullanın; önceden bakiye yüklemenize gerek yoktur.
2. curl /v1/models komutunu kullanarak anahtarınızın geçerli olduğunu ve ağ bağlantısının kurulduğunu doğrulayın.
3. base_url, api_key ve model değerlerini ortam değişkenleriyle yönetin; anahtarları kod deposuna yüklemeyin.
4. Kodunuzda sabit yazılmış model adlarını, max_tokens değerlerini ve embeddings çağrılarını tarayın.
5. Akış kodunu kontrol edin; son choices öğesinin boş olduğu kullanım bloğunu destekleyin.
6. 429 ve 503 hataları için üssel geri çekilme (exponential backoff) ile yeniden deneme mekanizması ekleyin; 402 ve 403 hataları için açıklayıcı hata mesajı gösterme dalları oluşturun.
7. Gerçek istemlerinizi kullanarak bir regresyon testi çalıştırın; özellikle daha önce reddedilen istemlerin şimdi doğru şekilde çalışıp çalışmadığına odaklanın.
8. Önce trafiğin küçük bir yüzdesini yeni API'ye yönlendirin; kullanım ve gecikme sürelerini karşılaştırın, sorun yoksa trafiği artırın.
9. Ürününüzün yetişkin kullanıcılara yönelik olduğunu ve kullanım amacının yasal olduğunu onaylayın; bu, bu API'yi kullanmanın temel şartıdır.

Geçiş sırasında sık karşılaşılan hatalar

Model adının unutulması. Eski kodlardaki gpt modelleri veya birleştirici platformlardaki model yolları doğrudan gönderildiğinde yanlış yanıt alırsınız. Model adını global olarak arayın ve gönderilen son değerin uncensored olduğundan emin olun.

max_tokens sınırı aşıldı. Bazı projelerde modelin daha uzun yazması için max_tokens değeri 32000 veya daha yüksek ayarlanmıştır; burada tek istek için maksimum değer 32.000'dir ve aşım durumunda 400 hatası döndürülür. Ayrıca, isteme eklenen max_tokens değeri 100.000 token'ı geçemez; uzun girdi isteklerinde çıktı üst sınırını buna göre düşürün.

Akış kullanım bloğu. Akış bitmeden önce sunucu otomatik olarak usage içeren bir blok ekler; bu bloğun choices öğesi boş bir dizidir. Eğer kodunuz chunk.choices[0] ile doğrudan değer almaya çalışıyorsa son adımda hata alırsınız. Bazı eski kodlar ayrıca kullanım için stream_options parametresi gönderir; burada buna gerek yoktur.

Sansürsüzlüğü sınırsızlık sanmak. Yasal yetişkin içerikleri, kurgu ve tartışmalı konular reddedilmez; ancak reşit olmayanlarla ilgili cinsel içerikler (kurgusal ve rol yapma dahil) her zaman engellenir ve 403 content_blocked hatası döndürülür. Ürün sahipleri yetişkin kullanıcı erişimini kendi başlarına yönetmelidir.

Bakiye ve deneme süresi sona erdi. Deneme kredisi 7 gün sonra geçerliliğini yitirir; bakiye bittiğinde 402 hatası ve no_credit hata kodu döndürülür. Bu hatayı uygulamanızda kullanıcıya anlaşılır bir uyarıya çevirin; genel bir "hizmet hatası" mesajı yerine belirtin. İlgili senaryo tasarımları için uygulama senaryoları makalesine bakabilirsiniz.