Prompt Şablonları
Genel Bakış
Prompt Şablonları, tek bir kavramın iki parçasıdır:
- Şablon Kataloğu — adlandırılmış, yeniden kullanılabilir prompt kayıtlarının tutulduğu merkezi liste
- Prompt Şablonu politikası — bir AI Gateway'inin, istemcinin gönderdiği kısa bir takma adı (alias) kataloğun bir kaydına eşleyip isteği genişleten yapılandırması
İstemci, isteğinde tüm messages[] dizisini yazmak yerine yalnızca bir takma ad (ve varsa parametre değerleri) gönderir; gateway bunu, isteği LLM sağlayıcısına iletmeden önce gerçek prompt'a genişletir.
Prompt Şablonu; Prompt Süsleyici, RAG, tüm korumalar ve semantik önbellek politikalarından önce gelmelidir. Şablon, istemcinin gönderdiği kısa çağrıyı tam mesaj listesine genişletir; sonraki politikaların denetimi, önbellek anahtarı ve token sayımı bu genişletilmiş prompt üzerinden yapılmalıdır.
Politika listesini bu kurala aykırı bir sırayla kaydederseniz Apinizer sırayı kayıt anında otomatik olarak düzeltir ve neyi neden taşıdığını bir bilgi notuyla bildirir. Böylece Develop ekranında gördüğünüz sıra ile izleme ekranındaki gerçek çalışma sırası her zaman aynı kalır.
Şablon Kataloğu
Her katalog kaydı şu alanları taşır:
| Alan | Açıklama |
|---|---|
| Ad | İstemcinin (veya bir politikanın) bu kaydı seçmek için kullandığı referans anahtarı |
| Açıklama | Serbest metin |
| Mesajlar | Bir veya daha fazla {rol, içerik} çifti — rol system/user/assistant/developer/tool olabilir |
| Parametreler | Mesaj içeriğinde kullanılan {{parametreAdı}} yer tutucularının tanımı — ad, zorunlu mu, varsayılan değer |
| Kaynak | Built-in (salt okunur) veya özel (proje/kurulum tarafından oluşturulmuş) |
Kapsam
Her katalog kaydı üç seviyeden birinde yaşar:
- Built-in — kurulumla gelen, salt okunur kayıtlar
- Platform-paylaşımlı — sistem yöneticisi tarafından oluşturulan, tüm projelerin görebildiği kayıtlar
- Proje-özel — yalnızca ait olduğu projenin görebildiği kayıtlar
Bir Prompt Şablonu politikası, bu üç seviyenin birleşiminden (kendi projesi + platform-paylaşımlı + built-in) bir kayıt seçebilir.
{{parametre}} Sözdizimi
Mesaj içeriğinde {{parametreAdı}} yazdığınızda, bu bir parametre yer tutucusu olur — istemcinin istek gövdesinde gönderdiği değerle değiştirilir (aşağıya bakın). Parametreler listesinde ilgili adı Zorunlu olarak işaretleyebilir veya bir Varsayılan değer tanımlayabilirsiniz.
Kataloğdan seçilen bir bağlama, katalog kaydına bağlı kalır: şablonu düzenleyip kaydettiğinizde mesaj ve parametreleri o şablonu kullanan politikalara yansıtılır. Ayrıntılar ve bunu istemediğiniz durumun karşılığı için aşağıdaki bölüme bakın.
Bağlı ve Yerelleştirilmiş Bağlamalar
Bir Prompt Şablonu politikasındaki her bağlama iki durumdan birindedir; durum, bağlama satırındaki Kaynak sütununda görünür.
| Durum | Anlamı |
|---|---|
| Katalog bağlı | İçeriği katalog şablonu sahiplenir. Şablonu düzenleyip kaydettiğinizde mesaj ve parametreler bu bağlamaya yazılır, etkilenen dağıtımlar "yeniden yükleme gerekli" olarak işaretlenir. Bağlamanın mesaj/parametreleri politika ekranında salt-okunurdur. |
| Yerel | Katalogdan kopmuş bağımsız bir kopya. Katalog düzenlemeleri buraya ulaşmaz; mesaj ve parametrelerini politika ekranında serbestçe düzenleyebilirsiniz. |
Katalogdan yeni seçilen her bağlama katalog bağlı doğar. Bağlama satırının işlem menüsünden durumu değiştirebilirsiniz:
- Yerelleştir — bağı koparır. Mevcut içerik korunur, ama artık katalog güncellemelerini almaz ve düzenlenebilir hâle gelir. Tek bir yeri özelleştirmek istediğinizde bunu kullanın.
Alias ve açıklama her zaman bağlamaya özeldir — katalog güncellemesi bunlara asla dokunmaz.
Bir platform-paylaşımlı şablonu (sistem yöneticisi kaydı) tüm projeler seçebildiği için, o şablonun düzenlenmesi kurulumdaki her projede ona bağlı bağlamaları tazeler ve etkilenen dağıtımları "yeniden yükleme gerekli" yapar. Bu şablonu yalnızca sistem yöneticisi düzenleyebilir ve kaydetme öncesi gördüğü kullanım listesi kurulumun tamamını kapsar. Aynı şablonu bir proje ekranından görüntüleyen kullanıcı, kullanım listesinde yalnızca kendi projesindeki yerleri görür — diğer projelerin yapılandırması ona gösterilmez. Proje-özel şablonlarda hem güncelleme hem liste kendi projesiyle sınırlıdır.
Bu davranıştan önce eklenmiş bağlamalar katalog referansı taşımadığı için yerel sayılır ve kendiliğinden senkron olmazlar.
Yerelleştirme tek yönlüdür: yerel bir bağlamayı sonradan katalogla eşleştirme diye bir işlem yoktur. Bunun nedeni ada bakarak eşleştirmenin güvenilmez olmasıdır — alias düzenlenebilir olduğundan isim benzerliği yanlış şablona bağlama riski taşır. Bir bağlamanın katalogla senkron olmasını istiyorsanız onu silin ve katalogdan yeniden ekleyin; yeni bağlama katalog bağlı doğar.
Bir yapılandırmayı başka bir ortama aktardığınızda da bağlamalar yerel gelir, çünkü hedef ortamın katalog kayıtları farklıdır. Orada da senkron istiyorsanız aynı yolu izleyin: sil ve katalogdan yeniden ekle.
Şablonu Silmek ve Yeniden Adlandırmak
- Silme: Şablon bir yerde bağlı olarak kullanılıyorsa, silmeden önce nerelerde kullanıldığını gösteren bir uyarı çıkar. Onayladığınızda şablon silinir ve ona bağlı bağlamalar yerelleştirilir — içerikleri korunur, dağıtılmış hiçbir politika bozulmaz.
- Yeniden adlandırma: Bağlı bağlamaları etkilemez; onlar şablonu ada göre değil kimliğe göre izler ve alias'ları değişmez. Yalnızca eski adı doğrudan gönderen istemcilerin ve alias'ı eski addan türemiş yerel bağlamaların gözden geçirilmesi gerekir.
Şablon ekranındaki Kullananlar bölümü, o şablona bağlı tüm politikaları listeler.
Politika: İstemci İstek Formatı
İstemci, bir şablonu kullanmak istediğinde istek gövdesine iki alan ekler:
{
"template": "greeting",
"template_params": {"name": "Ada"}
}
- Şablon Alan Adı (varsayılan
template) — istemcinin takma adı gönderdiği alan - Parametreler Alan Adı (varsayılan
template_params) —{{parametre}}değerlerini taşıyan nesne
Gateway, template alanındaki takma adı politikadaki bağlamalarla eşleştirir, mesajları genişletir ve {{parametre}} yer tutucularını template_params içindeki değerlerle değiştirir:
// Gateway, LLM sağlayıcısına iletmeden önce "greeting" bağlamasının
// mesajlarını genişletir ve {{name}} yerine "Ada" koyar
Bir parametre değeri kendisi {{...}} içerse bile olduğu gibi (literal) yerleştirilir — asla ikinci kez genişletilmez. Bu, bilinçli bir prompt-injection savunmasıdır: bir parametre değeri yeni bir şablon referansı enjekte edemez.
Bilinmeyen Takma Ad Davranışı
İstemcinin gönderdiği takma ad, politikadaki hiçbir bağlamayla eşleşmezse:
| Seçenek | Davranış |
|---|---|
| Olduğu Gibi Geçir (varsayılan) | Gövde tamamen değiştirilmeden iletilir (template/template_params alanları dahil) |
| İsteği Engelle | Çözümlenemeyen bir referansı iletmek yerine istek reddedilir (HTTP 400) |
Eksik Parametre Davranışı
Eşleşen bağlamanın referans verdiği bir {{parametre}} için istemci değer göndermemişse:
| Seçenek | Davranış |
|---|---|
| İsteği Engelle (varsayılan) | İstek reddedilir (HTTP 400) |
| Boş Metin Yerleştir | Yer tutucu boş metinle değiştirilir |
| Varsayılan Değeri Kullan | Parametre tanımındaki varsayılan değer kullanılır (o da yoksa boş metin) |
Şablon Metninde Ortam ve Bağlam Değişkenleri
Şablon mesaj metni ve bir parametrenin varsayılan değeri, hem ${DEGISKEN_ADI} biçiminde ortam değişkeni hem de #{...} biçiminde bağlam değişkeni kabul eder. Önce değişkenler yerleştirilir, ardından {{parametre}} yer tutucuları doldurulur.
Bu sıra bilinçlidir ve bir güvenlik sınırıdır: çağıran tarafın gönderdiği parametre değeri değişken açısından hiçbir zaman taranmaz. Yalnızca operatörün yazdığı metin — şablon gövdesi ve katalogdaki varsayılan değerler — çözülür. Sıra tersine olsaydı, çağıran taraf değeri bir değişken referansı olan bir parametre gönderip gateway'in kendi ortam değerlerinden birini prompt'a yerleştirmesini sağlayabilirdi.
Birleştirme Modu
Genişletilmiş şablon mesajlarının, istemcinin kendi gönderdiği messages[] ile nasıl birleşeceği:
| Mod | Davranış |
|---|---|
| Değiştir (varsayılan) | İstemcinin kendi mesajları atılır, yalnızca genişletilmiş şablon mesajları kullanılır |
| Başa Ekle | Önce şablon mesajları, sonra istemcinin kendi mesajları |
| Sona Ekle | Önce istemcinin kendi mesajları, sonra şablon mesajları |
Şablon Alanlarını Temizleme
Genişletmeden Sonra Şablon Alanlarını Temizle varsayılan olarak açıktır: genişletme tamamlandıktan sonra template/template_params alanları gövdeden kaldırılır. Bunun kapatılması önerilmez — çoğu LLM sağlayıcısı, tanımadığı bir üst-düzey gövde alanını görünce isteği HTTP 400 ile reddeder.
Genişletilmiş İçerik Bütçesi
Genişletilmiş her mesajın toplam karakter sayısı, Genişletilmiş İçerik Bütçesi ile sınırlanır (varsayılan 32768 karakter).
Bütçe aşıldığında istek reddedilir (HTTP 400) — genişletme kısmen uygulanıp geri kalanı sessizce kesilmez, aynı Prompt Süsleyici'nin enjeksiyon bütçesi disiplini.
Çalışma Sırası
Bu politika, isteğin gateway'in diğer AI kontrollerine (korumalar, RAG bağlam ekleme, semantik önbellek, hız sınırlaması) ulaşmasından önce, ve aynı proxy'de bir Prompt Süsleyici politikası varsa ondan da önce çalışır — süsleyici blokları, bu politikanın genişlettiği mesaj listesine eklenir.
Yapılandırma
AI Gateway → RAG sayfasının Prompt Şablonları tab'ında yeni bir kayıt oluşturun: mesajları (rol + içerik) ve varsa {{parametre}} tanımlarını girin.
İlgili AI Gateway'inin politika listesine Prompt Şablonu politikasını ekleyin.
Kataloğdan bir veya daha fazla kayıt seçerek bir Alias (takma ad) atayın. Mesaj ve parametreler o anda politikaya kopyalanır ve bağlama katalog bağlı olur — şablonu sonradan düzenlediğinizde bu kopya da güncellenir.
Bilinmeyen Şablon Davranışı, Eksik Parametre Davranışı ve Birleştirme Modu'nu ihtiyacınıza göre ayarlayın.
Politikayı kaydettikten sonra Dağıt'a tıklayın — kayıt ile dağıtım ayrık adımlardır, otomatik dağıtım yapılmaz.