Bir sohbet uygulamasında soruyu yazar, cevabı okursun. Peki Murad okulunun web sitesinin ders programıyla ilgili soruları cevaplamasını isterse ya da Leyla'nın bir gecede 5.000 anket cevabını ayırması gerekirse? Kimse 5.000 mesajı elle yapıştırmaz. Programlar dil modelleriyle bir API üzerinden konuşur: modeller aynıdır, yalnızca koddan çağrılır. Bu ders, programınla model arasında neyin gidip geldiğini, bunun ne kadara mal olduğunu ve bunu nasıl güvenle yapacağını gösteriyor. “Büyük dil modelleri nasıl çalışır” dersindeki fikirlere (tokenler, sıcaklık ve bağlam penceresi) ihtiyacın olacak.
API (uygulama programlama arayüzü)Tanım
Bir programın başka bir programdan hizmet istediği kurallar bütünü. Bir LLM API'si genellikle bir web hizmetidir: programın sağlayıcının sunucusuna JSON içeren bir HTTP isteği gönderir, sunucu modeli çalıştırır ve cevabı JSON olarak geri yollar.
Bir isteğin anatomisi
Her sağlayıcı alanları biraz farklı adlandırır; ama neredeyse her istekte aynı parçalar bulunur:
| Parça | Ne işe yarar | Örnek |
|---|---|---|
| Adres ve API anahtarı | Hizmetin adresi ve hesabını tanıtan gizli anahtar (bir başlıkta gönderilir) | https://api.example.com/v1/chat |
| Model | Hangi modelin cevap vereceği: büyük olanlar genellikle daha yetenekli ama daha yavaş ve pahalıdır | "model": "example-model" |
| Sistem istemi | Bütün sohbet için kurallar: rol, ton, biçim, sınırlar | “Sen bir öğretmensin. En fazla 3 cümleyle cevap ver.” |
| Mesajlar | Sohbet, her biri bir role sahip sıralar listesi olarak: user (kişi) veya assistant (modelin önceki cevapları) | {"role": "user", "content": "..."} |
| max tokens | Cevap uzunluğunun üst sınırı; ona ulaşılınca cevap kesilir | "max_tokens": 300 |
| Sıcaklık (temperature) | Rastgelelik: düşük → öngörülebilir, yüksek → daha çeşitli | Ayırma için 0–0,3, beyin fırtınası için 0,8 |
{
"text": "A token is a small piece of text, such as a short word or part of a word, that the model reads and writes.",
"stop_reason": "end_turn",
"usage": { "input_tokens": 27, "output_tokens": 24 }
}Yeni başlayanların çoğunu şaşırtan bir gerçek var: model önceki istekleri hatırlamaz. Her istek tek başınadır. Bir sohbet uygulaması yalnızca hatırlıyormuş gibi görünür, çünkü her yeni mesajda sohbetin tamamını (sistem istemini, önceki bütün soruları ve cevapları) yeniden gönderir. Bu yüzden uzun sohbetler giderek daha çok token harcar ve bağlam penceresi bir sohbetin ne kadar uzun olabileceğini sınırlar. (Bazı hizmetler geçmişi senin yerine saklayabilir; ama model onu yine de girdi olarak alır.)
Üçüncü soruyla ne gönderilir?
Problem
Murad'ın uygulamasının bir sistem istemi var ve kullanıcıyla şimdiye kadar iki soru ve iki cevap alışverişi oldu. Kullanıcı şimdi üçüncü soruyu soruyor. Programın neler gönderdiğini listele.
Çözümü gösterÇözümü gizle
Çözüm
2) user: 1. soru;
3) assistant: 1. cevap;
4) user: 2. soru;
5) assistant: 2. cevap;
6) user: 3. soru.
Toplam altı öğe; model 3. soruyu bütün geçmişi görerek cevaplar. Program yalnızca 3. soruyu gönderseydi model “o” ya da “bu” sözcüklerinin neyi kastettiğini bilemezdi.
Tokenler ve maliyet
Sağlayıcılar kullanımı tokenle ölçer; girdi (gönderdiğin her şey) ve çıktı (modelin yazdığı her şey) için ayrı ayrı. Çıktı tokenleri genellikle girdi tokenlerinden pahalıdır. Fiyatlar milyon token başına verilir, modeller arasında çok farklıdır ve sık değişir; aşağıdaki sayılar alıştırma için uydurulmuştur. Her zaman sağlayıcının güncel fiyat listesine bak.
Burada
- C
- bir isteğin maliyeti
- N₁
- girdi tokeni sayısı (sistem istemi + geçmiş + yeni mesaj)
- p₁
- bir girdi tokeninin fiyatı = milyon token fiyatı / 1.000.000
- N₂
- çıktı tokeni sayısı (cevap)
- p₂
- bir çıktı tokeninin fiyatı
Girdi ve çıktı ayrı sayılır; aylık maliyet = bir isteğin maliyeti × günlük istek sayısı × 30.
Maliyet hesabı (alıştırma fiyatları: milyon girdi tokeni 0,50 $, milyon çıktı tokeni 2,00 $)
Problem
1) 1.200 girdi ve 300 çıktı tokenli bir isteğin maliyeti nedir?
2) Bir uygulama günde 500 istek gönderiyor; her birinde 1.000 girdi ve 200 çıktı tokeni var. 30 günün maliyeti nedir?
3) Aynı uygulamada cevaplar iki kat uzuyor (400 çıktı tokeni). 30 günün maliyeti şimdi ne olur?
Çözümü gösterÇözümü gizle
Çözüm
2) Bir istek: 0,0005 + 0,0004 = 0,0009 $. Bir gün: 0,0009 · 500 = 0,45 $. 30 gün: 13,50 $.
3) Bir istek: 0,0005 + 0,0008 = 0,0013 $. 30 gün: 0,0013 · 500 · 30 = 19,50 $; yalnızca uzayan cevaplar maliyeti %44 artırdı. max tokens ve “kısa cevap ver” kuralı para kazandırır.
Tokenler neyin sığacağını da sınırlar: girdi ve çıktı birlikte modelin bağlam penceresine sığmalıdır. 100.000 tokenlik pencereye sahip bir modele 90.000 tokenlik bir belge gönderirsen cevap için en fazla 10.000 token kalır ve max tokens bu sınırın içinde olmalıdır. Aşağıdaki program uzun bir sohbetin neden pahalı olduğunu gösteriyor:
PRICE_IN = 0.50 / 1_000_000 # example price per input token (invented)
PRICE_OUT = 2.00 / 1_000_000 # example price per output token (invented)
system, question, answer = 300, 40, 160 # tokens in each part
history = 0
total_in = total_out = 0
for turn in range(1, 6):
tokens_in = system + history + question # the whole chat is sent again
total_in += tokens_in
total_out += answer
print(f"turn {turn}: input {tokens_in} tokens, output {answer} tokens")
history += question + answer
cost = total_in * PRICE_IN + total_out * PRICE_OUT
print(f"one chat: {total_in} in + {total_out} out = ${cost:.5f}")
print(f"1000 such chats: ${cost * 1000:.2f}")Beklenen çıktı
turn 1: input 340 tokens, output 160 tokens turn 2: input 540 tokens, output 160 tokens turn 3: input 740 tokens, output 160 tokens turn 4: input 940 tokens, output 160 tokens turn 5: input 1140 tokens, output 160 tokens one chat: 3700 in + 800 out = $0.00345 1000 such chats: $3.45
Akış, istek sınırları ve hatalar
Uzun bir cevap üretmek saniyeler sürer. Akışta (streaming) sunucu cevabı tokenler üretildikçe küçük parçalar hâlinde gönderir; kullanıcı boş ekrana bakmak yerine metnin hemen belirdiğini görür. Toplam süre aşağı yukarı aynıdır ama bekleme çok daha kısa hissedilir. Token sayıları genellikle akışın sonunda gelir ve program yarıda kopan bir akışa hazırlıklı olmalıdır.
Sağlayıcılar sunucularını istek sınırlarıyla (rate limits) korur: her hesap için dakikada (bazen günde) en fazla istek ve token sayısı. Sınır aşılınca sunucu 429 Too Many Requests HTTP durum koduyla cevap verir. Programın bu ve diğer hataları beklemelidir:
| Kod | Anlamı | Program ne yapmalı |
|---|---|---|
| 400 | Hatalı istek: yanlış bir alan veya bağlam penceresi için fazla uzun girdi | İsteği düzelt; tekrarlamak işe yaramaz |
| 401 / 403 | Anahtar yok, yanlış ya da iptal edilmiş veya izin yok | Anahtarı kontrol et; yeniden deneme |
| 429 | Dakikada çok fazla istek veya token | Bekle ve artan aralıklarla yeniden dene |
| 500 / 503 | Sunucuda sorun veya aşırı yük | Bekle ve yeniden dene; birkaç denemeden sonra vazgeç |
Üstel geri çekilme (exponential backoff)Tanım
Bir yeniden deneme stratejisi: her başarısız denemeden sonra program öncekinin iki katı kadar bekler (1 sn, 2 sn, 4 sn, 8 sn…) ve buna jitter denen küçük, rastgele bir ek süre ekler; böylece binlerce istemci aynı anda yeniden denemez.
Gönder
İsteği bir zaman aşımıyla (timeout) gönder ki program sonsuza kadar beklemesin.
Başarı
200 kodu: cevabı ve token sayılarını al.
Düzeltilmesi gereken hata
400, 401, 403: dur, hatayı kaydet ve bildir; yeniden denemek işe yaramaz.
Geçici hata
429, 500, 503: bekle (üstel geri çekilme + jitter) ve yeniden dene.
Sınırı bil
Birkaç denemeden sonra vazgeç ve kullanıcıya kibar bir mesaj göster: “Lütfen bir dakika sonra tekrar deneyin.”
import random
random.seed(1)
answers = [429, 429, 503, 200] # what a busy server replies, one per try
def call_api(attempt):
return answers[attempt] # a real program sends an HTTP request here
wait = 1.0
for attempt in range(5):
status = call_api(attempt)
if status == 200:
print(f"try {attempt + 1}: 200 OK, got the answer")
break
if status in (400, 401):
print(f"try {attempt + 1}: {status}, fix the request; retrying will not help")
break
pause = wait + random.uniform(0, 0.5) # exponential backoff + jitter
print(f"try {attempt + 1}: {status}, wait {pause:.2f} s and retry")
wait *= 2 # time.sleep(pause) in a real program
else:
print("giving up after 5 tries")Beklenen çıktı
try 1: 429, wait 1.07 s and retry try 2: 429, wait 2.42 s and retry try 3: 503, wait 4.38 s and retry try 4: 200 OK, got the answer
time.sleep(pause) çağırır; beklemeler jitter eklenerek 1 → 2 → 4 sn diye büyür.Anahtarlar, gizlilik ve veriler
Bir API anahtarı, faturana bağlı bir paroladır. Ona sahip olan herkes hizmeti senin adına kullanabilir ve ödeyen sen olursun. Sızan anahtarlar çabuk bulunur: otomatik botlar açık kod depolarını sürekli olarak gizli bilgi arayarak tarar.
- Anahtarı asla ön yüz (front-end) koduna koyma. Bir web sayfasının JavaScript'ini veya bir mobil uygulamanın kodunu her kullanıcı okuyabilir. Anahtar sunucuda (arka uçta) kalır; modeli sunucu çağırır ve yalnızca cevabı iletir.
- Anahtarı asla bir depoya, özellikle açık bir depoya kaydetme. Onu bir ortam değişkeninde veya bir gizli bilgi yöneticisinde tut;
.envgibi dosyaları.gitignore'a ekle. - Zararı sınırla: bir harcama sınırı koy, her proje için ayrı anahtar kullan ve her anahtara yalnızca gereken izinleri ver.
- Bir anahtar sızarsa onu hemen iptal et ve yenisini oluştur. Dosyayı depodan silmek yetmez: geçmiş onu saklar.
Anahtar kodun içinde
API_KEY = "my-secret-key-123" # visible to everyone who sees the codeAnahtar bir ortam değişkeninde
import os
API_KEY = os.environ["AI_API_KEY"] # set outside the codeAPI üzerinden gönderdiğin her şey sağlayıcının sunucularına gider. Bir uygulama kurmadan önce sağlayıcının veri kullanımı ve saklama politikasını oku: API verilerinin model eğitmek için kullanılıp kullanılamayacağını, isteklerin ne kadar süre ve nerede saklandığını (örneğin kötüye kullanım denetimi için). Politikalar sağlayıcıdan sağlayıcıya, hatta ücretsiz ve ücretli planlar arasında farklıdır ve değişir. Yalnızca görevin gerektirdiği verileri gönder, gereksiz adları ve numaraları çıkar, kullanıcılarına metinlerini bir yapay zekâ hizmetinin işlediğini söyle ve okulunun, şirketinin ve ülkenin kurallarına uy (örneğin AB'de GDPR).
Küçük bir program ve yapılandırılmış çıktı
İşte popüler requests kütüphanesiyle Python'da eksiksiz bir istek. Adres, model adı ve alan adları yer tutuculardır: gerçek sağlayıcılar kendi adlarını kullanır ve çoğunun isteği senin yerine kuran resmî bir kütüphanesi (SDK) vardır. Ama yapı her yerde aynıdır.
import os
import requests
API_URL = "https://api.example.com/v1/chat" # placeholder: your provider's address
API_KEY = os.environ["AI_API_KEY"] # the key lives outside the code
body = {
"model": "example-model",
"system": "You are a friendly tutor. Answer in one sentence.",
"messages": [{"role": "user", "content": "What is a token?"}],
"max_tokens": 100,
"temperature": 0.2,
}
headers = {"Authorization": f"Bearer {API_KEY}"}
response = requests.post(API_URL, json=body, headers=headers, timeout=30)
response.raise_for_status() # stops with an error on 4xx / 5xx
data = response.json()
print(data["text"])
print("stop reason:", data["stop_reason"])
print("tokens in/out:", data["usage"]["input_tokens"], data["usage"]["output_tokens"])Beklenen çıktı
A token is a small piece of text, such as a short word or part of a word, that the model reads and writes. stop reason: end_turn tokens in/out: 27 24
requests ve anahtar yok). Yukarıdaki çıktı, bir API'yi taklit eden yerel bir test sunucusundan alındı. Gerçekten kullanmadan önce AI_API_KEY ortam değişkenini kodun dışında tanımla.Bir programın düz yazıya değil alanlara ihtiyacı varsa şemalı JSON iste; “İleri düzey istem teknikleri” dersindeki gibi. Birçok API'de bunun için bir parametre vardır (çoğu zaman response format veya structured output diye adlandırılır); modeli verilen JSON şemasına uymaya zorlar. Program yine de sonucu kontrol etmelidir. Burada düşük sıcaklık da yardımcı olur, çünkü her seferinde aynı biçimi istersin.
Mini proje: bir ödev yardımcısının arka ucu
Problem
Leyla'nın sınıfı, öğrencilerin matematik soruları sorabileceği bir web sitesi istiyor. Arka ucu tasarla: ne gönderilir, hangi parametreler seçilir, anahtar ve maliyet nasıl yönetilir.
Çözümü gösterÇözümü gizle
Çözüm
Sistem istemi: “9–11. sınıflar için bir matematik öğretmenisin. İpucu ver ve yönlendirici sorular sor; yalnızca nihai cevabı verme. En fazla 150 kelime.”
Parametreler: max tokens 300, sıcaklık 0,3.
Geçmiş: maliyet ve bağlam küçük kalsın diye yalnızca son 6 turu gönder.
Hatalar: 429 ve 5xx için beklemeli yeniden deneme (en fazla 4 deneme), ardından “Lütfen bir dakika sonra tekrar deneyin”.
Maliyet: öğrenci başına günde 30 soru sınırı ve sağlayıcı ayarlarında aylık harcama sınırı.
Gizlilik: isteklerde ad veya e-posta yok; sayfada soruları bir yapay zekâ hizmetinin işlediğine dair bir not.
Alıştırma
Bir ödev yardımcısı uygulamasına günde 200 soru geliyor. Her istekte 900 girdi ve 300 çıktı tokeni var. Alıştırma fiyatlarıyla (milyon girdi tokeni 0,50 $, milyon çıktı tokeni 2,00 $) 30 günün maliyetini 2 ondalık basamakla yazdır (yalnızca sayıyı).
PRICE_IN = 0.50 / 1_000_000
PRICE_OUT = 2.00 / 1_000_000
per_day = 200
tokens_in, tokens_out = 900, 300
# cost of one request, then of 30 days; print it with 2 decimalsBeklenen çıktı
6.30
Unutma
- Bir API isteği sistem istemini, mesajları, model adını ve max tokens, sıcaklık gibi parametreleri taşır; cevap metni, durma nedenini ve token sayılarını içerir.
- Model önceki istekleri hatırlamaz: program geçmişi yeniden gönderir, bu yüzden uzun sohbetler giderek daha çok token harcar.
- Maliyet = girdi tokeni × girdi fiyatı + çıktı tokeni × çıktı fiyatı; fiyatlar milyon token başınadır ve değişir, kontrol et.
- Akış cevabı üretildikçe gösterir; 429 ve 5xx hatalarında üstel geri çekilmeyle yeniden denenir, 400 ve 401 ise düzeltilir.
- API anahtarı faturana bağlı bir paroladır: onu sunucuda, bir ortam değişkeninde tut; asla ön yüz kodunda veya bir depoda değil.
- Sağlayıcının veri kullanımı ve saklama politikasını oku ve yalnızca görevin gerektirdiği verileri gönder.