Ham Sağlayıcı Anahtarlarını Açığa Çıkarmadan Ortak LLM API'si Nasıl Oluşturulur

LLM erişimi için İş Ortağı API, sağlayıcı anahtarlarının etrafındaki ince bir paket olmamalıdır. İş ortakları, satıcılar veya müşteri uygulamalarının dil modellerine yetkilendirilmiş erişime ihtiyacı varsa platformun kendi kontrol düzlemine, ağ geçidine, politika katmanına, ölçüm ardışık düzenine ve operasyonel runbook'lara ihtiyacı vardır. Aksi takdirde, sağlayıcı düzeyinde faturalandırma, sağlayıcı düzeyinde sınırlar ve paylaşılan kimlik bilgileri, bir iş ortağı entegrasyonu ile çok pahalı bir olay arasındaki tek kontrol haline gelir.

Hedef açık: Siz yukarı akış sağlayıcı kimlik bilgilerini gizli tutarken, iş ortağına özel yetkileri uygularken, faturalandırılabilir kullanımı ölçerken ve iş ortaklarına güvenilir müşteriler oluşturmaları için yeterli şeffaflığı verirken, harici tarafların platformunuz aracılığıyla Yüksek Lisans yeteneklerini kullanmasına izin verin.

Referans Mimarisi

Pratik bir İş Ortağı API'nin iki ana bölümü vardır: bir kontrol düzlemi ve bir istek ağ geçidi.

Kontrol düzlemi iş ortağı kuruluşlarını, uygulamaları, ortamları, yetki verilen API anahtarları, model yetkilerini, ücret sınırı katmanlarını, harcama sınırlarını, faturalandırma şartlarını, web kancası uç noktalarını ve denetim kayıtlarını yönetir. Ticari ve operasyonel kuralların makine tarafından okunabilir politika haline geldiği yerdir.

İstek ağ geçidi iş ortağı trafiğini alır, yetki verilen anahtarın kimliğini doğrular, politikayı değerlendirir, kota uygular, seçilen model sağlayıcıya yönlendirir, kullanımı kaydeder ve iş ortağı tarafından görülebilen yanıt meta verilerini döndürür. Olgun kurumsal LLM API'de bu ağ geçidi aynı zamanda model yönlendirmenin, yeniden denemelerin, yük devretmenin, içerik kontrollerinin ve gözlemlenebilirliğin tutarlı bir şekilde uygulandığı yerdir.

Önemli sınır şudur: İş ortakları yalnızca platform tarafından verilen anahtarlarınızı alır. Hiçbir zaman ham sağlayıcı kimlik bilgilerini almazlar. Yukarı akış sağlayıcı anahtarları, platformunuzun gizli deposunda kalır ve yalnızca ağ geçidi veya arka uç çalışanları tarafından kullanılır.

Etrafında Oluşturulacak Gerçek Modeli

Aşağıdakiler herhangi bir dağıtıma ilişkin varsayımlar değil, genel platform ve bulut belgeleri tarafından desteklenen gerçeklerdir:

• Bazı LLM sağlayıcıları proje kapsamlı anahtarları, hizmet hesaplarını, proje düzeyinde model erişimini ve proje düzeyinde hız sınırlarını destekler.
• Çok kiracılı SaaS API'lerine yönelik bulut rehberliği, yanlışlıkla kiracılar arası erişimi azaltmak için genellikle politika yönetimi, politika kararı ve politika uygulamasını birbirinden ayırır.
• API ağ geçitleri ve SaaS kontrol düzlemleri, kiracıya özel kısıtlama ve hız, artış ve kota katmanları dahil olmak üzere kota kontrolleri uygulayabilir.
• Kullanıma dayalı SaaS faturalandırması, kiracı etkinliğinin toplanmasına, toplanmasına ve fatura kayıtlarıyla mutabakatının sağlanmasına bağlıdır.
• Idempotency anahtarları, durum değiştiren API isteklerini yinelenen yan etkiler oluşturmadan güvenli bir şekilde yeniden denemek için belgelenmiş bir kalıptır.
• Standartlaştırılmış hız sınırı yanıt başlıkları, müşterilerin sınırları, kalan ödeneği, sıfırlama zamanlamasını ve yeniden deneme davranışını anlamasına yardımcı olabilir.

Öneri, her iş ortağından her bir yukarı akış model sağlayıcısıyla doğrudan entegre olmasını istemek yerine, bu kalıpları, sahip olduğunuz iş ortaklarına yönelik bir Yüksek Lisans erişim katmanında birleştirmektir.

1. Adım: Kiracıyı ve Kimlik Modelini Tanımlayın

İş ortağı trafiğini yalnızca bir API anahtar dizesiyle tanımlamayın. Faturalandırma, kötüye kullanım incelemesi, kota hata ayıklaması ve destek araştırmaları sıklıkla farklı sorular sorduğundan, yararlı bir İş Ortağı API'nın ayrı tanımlayıcılara ihtiyacı vardır.

En azından şunun için tanımlayıcılar oluşturun:

• İş ortağı kuruluşu: sözleşmeli harici şirket.
• İş ortağı uygulaması: belirli bir entegrasyon, ürün, eklenti veya bayi uygulaması.
• Ortam: üretim, hazırlama, korumalı alan veya geliştirme.
• Son müşteri: sözleşmeye bağlı olarak izin verildiğinde ve teknik olarak mevcut olduğunda iş ortağının müşterisi, çalışma alanı, hesabı veya kiracısı.
• API anahtar: isteklerin kimliğini doğrulamak için kullanılan yetkilendirilmiş kimlik bilgisi.
• İstek Kimliği: ağ geçidiniz, sağlayıcı çağrılarınız, kullanım etkinlikleriniz ve destek günlükleriniz genelinde bir isteği izlemeye yönelik benzersiz bir tanımlayıcı.

Bu yapı, güvenliği ihlal edilmiş veya gürültülü bir entegrasyonun yalnızca "iş ortağı X trafiği" olarak tanımlanabileceği yaygın hata modunu önler. Ayrıca iş ortağının tüm işini devre dışı bırakmadan bir uygulamayı veya ortamı askıya almanıza da olanak tanır.

2. Adım: Yetki Verilen İş Ortağı Anahtarlarını Verin

İş ortağı anahtarları, bir e-tablodaki statik belirteçler değil, birinci sınıf platform nesneleri olmalıdır. Her anahtarın meta verileri ve politika bağlantıları olmalıdır:

• İş ortağı kuruluş kimliği
• Uygulama Kimliği
• Ortam
• İzin veriliyor API sohbet, yerleştirme, toplu iş veya resim oluşturma gibi yüzeyler
• İzin verilen model takma adları
• Uygun olduğu durumlarda bölge veya veri yerleşimi kısıtlamaları
• Ücret sınırı katmanı
• Harcama sınırı veya ön ödemeli bakiye kuralı
• Oluşturma zamanı, son kullanım zamanı, sahip ve rotasyon durumu

Mümkün olduğunda yalnızca karma oluşturma işlemi uygulanmış anahtar malzemesini depolayın, tüm gizli dizileri oluşturma sırasında yalnızca bir kez açığa çıkarın ve kesinti olmadan rotasyonu destekleyin. Pratik bir rotasyon modeli, her istek için hangi anahtarın kullanıldığını gösteren denetim günlükleriyle, kısa bir geçiş penceresi sırasında iki etkin anahtara izin verir.

3. Adım: Yetkileri Yönlendirmeden Ayırın

Bir iş ortağının bir modeli kullanma hakkı, şu anda desteklenen yönlendirme kodu tarafından ima edilmemelidir. Yetki kontrollerini açık ve sağlayıcı seçiminden ayrı tutun.

Örneğin, model: premium-reasoning talebi öncelikle bir politika kararı vermelidir:

• Bu iş ortağının model takma adını kullanmasına izin veriliyor mu?
• İş ortağı uygulamasının bu ortamda onu kullanmasına izin veriliyor mu?
• İstek izin verilen bölge veya veri sınırının içinde mi?
• Sözleşme etkin ve iyi durumda mı?
• İş ortağı harcama, kota ve kötüye kullanım eşiklerinin içinde mi?

Ancak bu karardan sonra yönlendirme, yukarı akış sağlayıcısını, sağlayıcı projesini, dağıtımı veya geri dönüş yolunu seçmelidir. Bu önemlidir çünkü model yönlendirme değişiklikleri operasyonel olarak sıktır. Yetki değişiklikleri bilinçli ve denetlenebilir olmalıdır.

4. Adım: Mevcut Bir İş Ortağı API Surface

İş ortaklarının, yukarı akış sağlayıcılarınız değişse bile istikrarlı davranışlara ihtiyacı vardır. Her sağlayıcı model adını doğrudan ifşa etmek yerine kendi model takma adlarınızı ve yetenek açıklamalarınızı kullanın.

Küçük bir örnek:

POST /v1/chat/completions
Authorization: Bearer partner_key_...
Idempotency-Key: job_01J7...
X-Partner-Customer-Id: customer_123

{
  "model": "standard-chat",
  "messages": [
    {"role": "user", "content": "Summarize this support thread."}
  ],
  "metadata": {
    "ticket_id": "T-44821",
    "workflow": "support_summary"
  }
}

Ortak standard-chat'ı ister. Ağ geçidiniz bu takma adı, yetkilendirme, kullanılabilirlik, fiyat, gecikme, bölge ve kalite kurallarına bağlı olarak geçerli onaylı sağlayıcı ve modelle eşleştirir.

Ancak tüm sağlayıcı farklılıklarını gizlemekten kaçının. İki model takma adı farklı bağlam pencerelerine, yapılandırılmış çıktı desteğine, araç çağırma davranışına, gecikme profillerine veya bölgesel kullanılabilirliğe sahipse bu farklılıkları açıkça belgeleyin. Soyutlama, entegrasyonu basitleştirmeli, sürpriz davranışlar yaratmamalıdır.

5. Adım: Sağlayıcı Aramalarından Önce Kotaları Uygulayın

Sağlayıcı sınırları yararlı güvenlik önlemleridir ancak iş ortağı düzeyinde yaptırımlar platformunuza aittir. Bir yukarı akış sağlayıcı projesi birçok ortağa hizmet verebilir veya bir ortağın farklı sözleşmelerle birden fazla uygulaması olabilir. Yalnızca sağlayıcı düzeyindeki ücret sınırlarına güvenmek, bu ayrımları net bir şekilde ifade edemez.

Yukarı yönlü aramalar yapmadan önce kota kontrolleri uygulayın:

• İş ortağı anahtarına göre dakika başına istek sayısı
• İş ortağı kuruluşuna göre dakika başına jeton sayısı
• Uygulamaya göre eşzamanlı istekler
• Günlük veya aylık faturalandırılabilir birim kotası
• Ön ödeme bakiyesi veya kredi eşiği
• Gerektiğinde son müşteri başına sınırlar

Eşzamanlı istekler için, istek kabul edilemediğinde açıkça reddedin. Eşzamansız ve toplu iş yükleri için sıraya kabulü yürütme kotasından ayrı olarak değerlendirin. Toplu yükleme kabul edilebilir ancak iş ortağı sınırlarına ulaşıldığında bireysel işler yine de ölçülmeli ve durdurulmalıdır.

6. Adım: Tahmin Edilebilir Hız Sınırı Sinyallerini Döndürün

Opak 429 Too Many Requests yanıtlar önlenebilir destek bildirimleri oluşturur. Başarılı ve kısıtlanmış yanıtlarda iş ortağının görebileceği kota sinyallerini döndür.

Yararlı bir yanıt şunları içerebilir:

RateLimit-Limit: 600;w=60
RateLimit-Remaining: 42
RateLimit-Reset: 17
Retry-After: 17
X-Request-Id: req_01J8...

Öneriler:

• Sınırların anahtar, uygulama, kuruluş, model veya uç nokta başına geçerli olup olmadığını belgeleyin.
• İstemcilerin işlem yapabileceği dönüş sıfırlama zamanlaması.
• Kısıtlanmış yanıtlar için Retry-After kullanın.
• Hata gövdelerini sabit ve makine tarafından okunabilir tutun.
• İş ortaklarının davranışta hata ayıklaması gerekmediği sürece, yukarı akış sağlayıcının dahili bilgilerini ifşa etmeyin.

Bu, iş ortağı istemcilerinin oluşturulmasını kolaylaştırır ve trafikte ani artışlar sırasında yeniden deneme fırtınalarını azaltır.

7. Adım: Faturalandırılabilir İş için Idempotency'yi kullanın

Durum veya faturalandırılabilir iş oluşturan tüm uç noktalar, bağımsız anahtarları desteklemelidir. Bu, özellikle eşzamansız oluşturma işleri, toplu gönderimler, kredi satın alımları, web kancasıyla tetiklenen yeniden denemeler ve uzun süren görevler için önemlidir.

Uygulama kuralı basittir: Bir iş ortağı aynı isteği, saklama penceresi içinde aynı önemsizlik anahtarıyla tekrarladığında, yinelenen çalışma oluşturmak yerine orijinal sonucu döndürün.

Son durumları açıkça belirtin:

• İdempotans kayıtları ne kadar süre saklanır
• İdempotency anahtarı hangi uç nokta ve iş ortağı anahtarının kapsamına alınmıştır
• Aynı anahtar farklı istek parametreleriyle yeniden kullanılırsa ne olur?
• Başarısız isteklerin önbelleğe alınıp alınmadığı
• Kısmen tamamlanmış toplu işlere yetersizlik nasıl uygulanır

Faturalandırılabilir LLM çalışmaları için, gereksiz hassas yük içeriğini saklamadan parametre uyuşmazlıklarını tespit etmek üzere yeterli miktarda istek parmak izi verisi depolayın.

8. Adım: Değiştirilemez Kullanım Olaylarını Yayımlayın

Sağlayıcı faturalarını iş ortağı faturalandırmasında doğruluk kaynağı olarak görmeyin. Sağlayıcı faturaları genellikle iş ortağı sözleşmelerinizi, biçimlendirme kurallarınızı, bayi katmanlarınızı, son müşteri kimliklerinizi veya anlaşmazlık iş akışınızı bilmez. Bunun yerine, her istek bir terminal durumuna ulaştığında değişmez bir kullanım olayı yayınlayın.

Bir kullanım etkinliği şunları içermelidir:

• İş ortağı kuruluş kimliği numarası
• Uygulama kimliği ve ortamı
• API anahtar kimliği, ham anahtar değil
• Sağlanmışsa ve izin veriliyorsa son müşteri kimliği
• İstek kimliği ve sağlayıcı korelasyon kimliği
• Model takma adı ve yukarı akış sağlayıcı modeli
• Giriş jetonları, çıkış jetonları, önbelleğe alınmış jetonlar veya diğer faturalandırılabilir birimler
• Mümkün olduğunda sağlayıcı maliyet esası
• İş ortağı faturalandırma birimi, fiyat artışı, kredi kullanımı veya sözleşme oranı
• Durum, hata sınıfı, gecikme ve yeniden deneme sayısı
• Zaman damgası ve şema sürümü

Bu etkinlikler; iş ortağı kontrol panellerini, faturalandırma dışa aktarımlarını, anormallik tespitini, kota sayaçlarını ve mutabakatı besler. Etkinlik akışını yalnızca ek olarak saklayın. Düzeltmeler sessiz düzenlemeler değil, düzenleme etkinlikleri olmalıdır.

9. Adım: Günlük Mutabakat Yapın

Ölçüm yalnızca uzlaştırıldığı takdirde faydalıdır. Kullanım etkinliklerinizi yukarı akış sağlayıcı kullanımı, sağlayıcı faturaları, kredi bakiyeleri ve iş ortağına yönelik faturalandırma kayıtlarıyla karşılaştıran günlük bir süreç oluşturun.

Mutabakat süreci şunları tanımlamalıdır:

• Ağ geçidiniz tarafından kabul edilen ancak terminal kullanım etkinlikleri eksik olan istekler
• Bir iş ortağı isteğiyle eşleştirilemeyen sağlayıcı kullanımı
• Sağlayıcı raporları ile ağ geçidi kayıtları arasındaki jeton sayısı farklılıkları
• Yanlış faturalandırılan yeniden denemeler
• Manuel krediler, geri ödemeler ve faturalandırma düzeltmeleri
• Taahhüt edilen harcamaya yaklaşan iş ortakları, ön ödemelerin tükenmesi veya olağandışı büyüme

Bu aynı zamanda finans, destek ve mühendisliğin de aynı kimliklere ihtiyaç duyduğu yerdir. Kontrol paneli, fatura satır öğesi, günlük etkinliği ve sağlayıcı kaydı birbirine bağlanamazsa anlaşmazlıklar manuel incelemelere dönüşür.

10. Adım: Operasyonel Runbook'lar Oluşturun

İş Ortağı API harici bir ürün yüzeyidir, dolayısıyla operasyonel davranışın olaylar meydana gelmeden önce planlanması gerekir. En azından şu durumlar için runbook'lar yazın:

• Güvenliği ihlal edilmiş iş ortağı anahtarı: bir anahtarı iptal edin veya askıya alın, iş ortağını bilgilendirin, denetim günlüklerini koruyun ve bir rotasyon yolu sağlayın.
• Kaçak kullanım: acil durum sınırları uygulayın, bir uygulamayı duraklatın veya daha sonraki kullanım için onay isteyin.
• Sağlayıcı kesintisi: onaylı bir sağlayıcıya yük devredin veya yeniden deneme kılavuzuyla birlikte kararlı bir hata döndürün.
• Kota tükenmesi: iş ortağının beklemesi, yükseltmesi, kredi satın alması veya trafiği azaltması gerekip gerekmediğini gösterir.
• Web kancası tekrarı: imzaları doğrulayın, yeterliliği kullanın ve etkinlik dağıtım girişimlerini izleyin.
• Faturalandırma düzeltmesi: düzenleme etkinlikleri oluşturun ve orijinal kullanım kayıtlarını koruyun.

Runbook'lar her eylemi kimin gerçekleştirebileceğini tanımlamalıdır. Bir anahtarın askıya alınması, ortak bir kuruluşun devre dışı bırakılmasından farklıdır. Kotayı yükseltmek sözleşmeyi değiştirmekten farklıdır. Acil durum kontrollerinin denetim yollarına ihtiyacı vardır.

Ödünleşmeler

İş Ortağı API ağ geçidi, gecikme ve operasyonel sorumluluk ekler. Bu, iş ortağı sözleşmesi düzeyinde kimlik bilgilerini, kotaları, yönlendirmeyi, faturalandırmayı ve görünürlüğü kontrol etmenin maliyetidir.

Katı kotalar marjları korur ve kötüye kullanımı azaltır, ancak seri davranış ve yeniden deneme kılavuzu kötü tasarlanmışsa gereksiz hatalara neden olabilir. Yararlı bir kota sisteminin hem kesin sınırları hem de belgelenmiş patlama davranışı vardır.

Ayrıntılı ölçüm, faturalandırma şeffaflığını ve destek sonuçlarını iyileştirir, ancak saklama, gizlilik ve mutabakat yükümlülüklerini artırır. Operasyonlar ve faturalandırma için gereken tanımlayıcıları toplayın ancak açık bir sözleşme ve uyumluluk temeli olmadığı sürece ham istem ve yanıt içeriğini fatura kayıtlarında depolamaktan kaçının.

Model soyutlaması iş ortağı entegrasyonlarını kolaylaştırır ancak aşırı soyutlama önemli farklılıkları gizleyebilir. İş ortaklarının sağlayıcı uygulamasının tüm ayrıntılarını bilmeleri gerekmez ancak bir model takma adının bağlam sınırlarını, çıktı biçimlerini, gecikme beklentilerini veya bölgesel kullanılabilirliği değiştirdiğini bilmeleri gerekir.

Uygulama Kontrol Listesi

• Sağlayıcı kimlik bilgilerini paylaşmak yerine platforma ait iş ortağı anahtarlarını yayınlayın.
• Her anahtarı iş ortağı, uygulama, ortam, yetkilendirme, kota ve faturalandırma kayıtlarıyla eşleyin.
• Yetkilendirme ve yetkilendirme kontrollerini yönlendirme mantığından ayrı tutun.
• Belgelenen özellikler ve sınırlara sahip kararlı model takma adlarını kullanın.
• Yukarı akış sağlayıcı aramalarından önce kota kontrolleri uygulayın.
• Hız sınırı başlıklarını ve makine tarafından okunabilen hataları döndürür.
• Durum veya faturalandırılabilir iş oluşturan uç noktalar için bağımsız anahtarlar gerektir.
• İstek tamamlandığında değişmez kullanım etkinlikleri yayınlayın.
• Kullanımın sağlayıcı kayıtları ve iş ortağı faturalarıyla mutabakatını yapın.
• Anahtar güvenliğinin ihlali, kaçak kullanım, sağlayıcı kesintisi, kota tükenmesi, web kancasının yeniden oynatılması ve faturalandırma düzeltmesine karşı runbook'ların bakımını yapın.

Uygulanabilir Sonuç

LLM erişimi için en güvenli İş Ortağı API, istekleri gizli kimlik bilgileriyle ileten bir proxy değildir. Kendi kimlik modeline, politika katmanına, kota uygulamasına, kullanım ölçere, mutabakat sürecine ve iş ortaklarına yönelik şeffaflığa sahip, yetki verilmiş bir erişim sistemidir.

Kontrol sınırlarıyla başlayın: iş ortağı anahtarları, açık yetkilendirmeler, çağrı öncesi kota kontrolleri, bağımsız durum değiştiren uç noktalar ve değiştirilemez kullanım etkinlikleri. Ardından operasyonel olgunluğu ekleyin: panolar, mutabakat, oran sınırı semantiği ve olay runbook'ları. Bu mimari, iş ortaklarının ham sağlayıcı anahtarları almadan Yüksek Lisans yeteneklerini geliştirmelerine olanak tanırken, platforma maliyet, kötüye kullanım, güvenilirlik ve faturalandırma anlaşmazlıklarını yönetmek için yeterli kontrol sağlar.

İlgili okumalar

• ekipler ve iş ortağı entegrasyonları için yönetilen API anahtarlar tasarlama