LLM API'leri nasıl çalışır

Bir program dil modelini çağırdığında neler olur: istek ve mesajlar, max tokens ve sıcaklık, tokenler ve maliyet, akış, istek sınırları ve hatalar, yapılandırılmış çıktı, API anahtarlarının ve verilerin korunması.

  • İleri
  • 22 dk
  • 12 soru
  • Ders 11 / 16

Bu derste öğreneceklerin

  • Bir API isteğinin parçalarını açıklamak: sistem istemi, mesajlar, max tokens, sıcaklık
  • Bir uygulamanın token kullanımını ve maliyetini tahmin etmek, uzun sohbetlerin neden daha pahalı olduğunu açıklamak
  • Akışı, istek sınırlarını ve hataları yeniden denemeler ve bekleme ile yönetmek
  • API anahtarlarını gizli tutmak, gizlilik ve veri saklama kurallarına uymak

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çaNe 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
ModelHangi modelin cevap vereceği: büyük olanlar genellikle daha yetenekli ama daha yavaş ve pahalıdır"model": "example-model"
Sistem istemiBütün sohbet için kurallar: rol, ton, biçim, sınırlar“Sen bir öğretmensin. En fazla 3 cümleyle cevap ver.”
MesajlarSohbet, her biri bir role sahip sıralar listesi olarak: user (kişi) veya assistant (modelin önceki cevapları){"role": "user", "content": "..."}
max tokensCevap 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şitliAyırma için 0–0,3, beyin fırtınası için 0,8
Alanların tam adlarını ve izin verilen değerleri sağlayıcının belgeleri gösterir.
JSON
{
  "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 }
}
Örnek bir cevap. Metnin yanında modelin neden durduğunu (bitirdi mi, yoksa max tokens sınırına mı ulaştı) ve kaç token kullanıldığını söyler; ödediğin de tam olarak budur.

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

1) sistem istemi;
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.

Okumaya devam etmek için ücretsiz kaydol

Dersin geri kalan bölümleri, test ve notlar Educora hesabıyla açılır. Kayıt bir dakika sürer; ilerlemen tüm cihazlarında saklanır.

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.

C = N₁ · p₁ + N₂ · p₂

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

1) C = 1.200 · 0,0000005 + 300 · 0,000002 = 0,0006 + 0,0006 = 0,0012 $.
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:

Python
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
Sohbetin tamamı yeniden gönderildiği için girdi her turda büyür: beşinci sorunun girdi tokeni birincinin üç katından fazladır. Fiyatlar alıştırma için uydurulmuştur.

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:

KodAnlamıProgram ne yapmalı
400Hatalı istek: yanlış bir alan veya bağlam penceresi için fazla uzun girdiİsteği düzelt; tekrarlamak işe yaramaz
401 / 403Anahtar yok, yanlış ya da iptal edilmiş veya izin yokAnahtarı kontrol et; yeniden deneme
429Dakikada çok fazla istek veya tokenBekle ve artan aralıklarla yeniden dene
500 / 503Sunucuda sorun veya aşırı yükBekle 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.

  1. Gönder

    İsteği bir zaman aşımıyla (timeout) gönder ki program sonsuza kadar beklemesin.

  2. Başarı

    200 kodu: cevabı ve token sayılarını al.

  3. Düzeltilmesi gereken hata

    400, 401, 403: dur, hatayı kaydet ve bildir; yeniden denemek işe yaramaz.

  4. Geçici hata

    429, 500, 503: bekle (üstel geri çekilme + jitter) ve yeniden dene.

  5. Sınırı bil

    Birkaç denemeden sonra vazgeç ve kullanıcıya kibar bir mesaj göster: “Lütfen bir dakika sonra tekrar deneyin.”

Python
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
Bir benzetim: gerçek sunucu yerine cevaplar bir listede duruyor. Gerçek bir program isteği gönderir ve 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; .env gibi 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 code

Anahtar bir ortam değişkeninde

import os

API_KEY = os.environ["AI_API_KEY"]  # set outside the code
Ortam değişkenini terminalde veya barındırma ayarlarında tanımla; kod onu yalnızca okur.

API ü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.

Python
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
Örnek amaçlıdır: tarayıcıda çalışmaz (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

Mimari: tarayıcı → Leyla'nın sunucusu → yapay zekâ API'si. Anahtar yalnızca sunucuda, bir ortam değişkeninde durur.
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ı).

Alıştırma · Python
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 decimals
Beklenen çı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.
Bu derste bir hata ya da yanlışlık mı gördün?

Kendini test et

12 soru. Her doğru cevap XP kazandırır.

Soru 1 / 12

Soru 1 / 12. Bir API isteğindeki sistem istemi ne içerir?