Büyük dil modelleri ve ilk API isteğin

Bu dersle yedinci bloğa, yapay zekâya giriyorsun. Şimdiye kadar yazdığın her programın kuralını sen koydun. Bu blokta kuralını senin yazmadığın bir programla çalışacaksın: bir büyük dil modeli. Ona metin göndereceksin, o da sana metin üretecek.

Önce bu modellerin içeride ne yaptığını kendi yazacağın oyuncak bir modelle göreceksin. Sonra Anthropic'in Claude modeline TypeScript'ten ilk isteğini atacak, cevabı akış olarak alacak ve faturanın nasıl hesaplandığını öğreneceksin.

#Dil modeli ne yapar? Sonraki parçayı tahmin eder

Claude ya da ChatGPT ile konuştuysan şunu merak etmişsindir: bu program cevabı bir veritabanından mı buluyor, yoksa insan gibi mi düşünüyor? İkisi de değil. Bir dil modelinin yaptığı iş şaşırtıcı derecede tek tip: metnin devamında hangi parçanın gelmesinin en olası olduğunu tahmin etmek.

Telefonunda "Maça" yazınca klavye "geliyorum", "girdim" gibi öneriler çıkarır, çünkü hangi sözcüğün hangisini sık izlediğini öğrenmiştir. Büyük dil modeli bu fikrin dev bir hâlidir: kitaplar, siteler ve kodlar gibi çok büyük miktarda metinle eğitilmiş, bir parçadan sonra ne geleceğini çok iyi tahmin eden bir program.

Model tek bir parça seçer, onu metnin sonuna ekler, sonra uzamış metne bakıp bir sonrakini tahmin eder. Uzun bir cevap, bu döngünün yüzlerce kez dönmesiyle oluşur. Claude'un cevabının ekrana parça parça akması da bu yüzden: model gerçekten de parça parça üretiyor.

#Oyuncak bir dil modeli

Bu fikri kendi elinle kurmak, onu okumaktan çok daha iyi öğretir. Bu derste bütün dosyalar C:\kod\yapay-zeka klasöründe. Klasörü oluştur (mkdir C:\kod\yapay-zeka), VS Code'da File → Open Folder ile aç ve oyuncak-model.ts adında bir dosya oluştur. Modelin "eğitim verisi" dört cümle olacak:

1const metinler = [2    "Garen Demacia için savaşır",3    "Lux Demacia için büyü yapar",4    "Ahri Ionia için büyü yapar",5    "Yasuo Ionia için kılıç sallar"6]7 8// Eğitim: her sözcükten sonra hangi sözcüğün kaç kez geldiğini say9const sayim: Record<string, Record<string, number>> = {}10for (const metin of metinler) {11    const sozcukler = metin.split(" ")12    for (let i = 0; i < sozcukler.length - 1; i++) {13        const simdiki = sozcukler[i]14        const sonraki = sozcukler[i + 1]15        if (!sayim[simdiki]) {16            sayim[simdiki] = {}17        }18        sayim[simdiki][sonraki] = (sayim[simdiki][sonraki] ?? 0) + 119    }20}21 22console.log(sayim["için"])23console.log(sayim["Demacia"])

{ 'savaşır': 1, 'büyü': 2, 'kılıç': 1 }{ 'için': 2 }

Record<string, number>, anahtarları metin, değerleri sayı olan bir obje tipidir. sayim iç içe bir obje: her sözcüğün altında, ondan sonra gelen sözcüklerin kaç kez geldiği duruyor. Çıktıyı oku: "için"den sonra dört kez bir şey gelmiş, ikisinde "büyü", birer kez de "savaşır" ve "kılıç". Bu tablo, oyuncak modelin bütün "bilgisi". (Türkçe harfli anahtarları Node tırnak içinde yazar; bu yalnızca yazım biçimi.)

Şimdi bu tabloyla metin üretelim. Son iki console.log satırını sil, yerine şunu yaz:

22// Adayların içinden en sık geleni seç23function enOlasi(adaylar: Record<string, number>): string {24    let secilen = ""25    let enCok = 026    for (const [sozcuk, kac] of Object.entries(adaylar)) {27        if (kac > enCok) {28            secilen = sozcuk29            enCok = kac30        }31    }32    return secilen33}34 35// İlk sözcükten başla, devamı kalmayana dek bir sonrakini ekle36function uret(ilkSozcuk: string): string {37    const sozcukler = [ilkSozcuk]38    let son = ilkSozcuk39    while (sayim[son]) {40        son = enOlasi(sayim[son])41        sozcukler.push(son)42    }43    return sozcukler.join(" ")44}45 46console.log(uret("Lux"))47console.log(uret("Ahri"))48console.log(uret("Garen"))49console.log(uret("Yasuo"))

Lux Demacia için büyü yaparAhri Ionia için büyü yaparGaren Demacia için büyü yaparYasuo Ionia için büyü yapar

uret fonksiyonu, Şekil 47.1'deki döngünün ta kendisi: son sözcüğe bak, en sık gelen devamı seç, ekle, tekrarla. İlk iki cümle doğru.

Son ikisine dikkatle bak: Garen büyü yapmaz, kılıcıyla savaşır; Yasuo da büyücü değil. Model bu iki cümleyi hiç görmedi; "için"den sonra en sık "büyü" geldiği için her şampiyona büyü yaptırdı. Cümleler akıcı, dilbilgisi kusursuz ve yanlış. Birazdan bu durumun adını koyacağız.

Gerçek bir dil modeli bundan çok daha güçlüdür. Sözcük yerine daha küçük parçalarla çalışır, yalnız son sözcüğe değil önceki metnin tamamına bakar ve tahmini bir sayım tablosundan değil, eğitimde ayarlanmış milyarlarca sayıdan oluşan bir sinir ağından alır. Ama temel döngü aynı: tahmin et, ekle, tekrarla.

#Token: modelin gördüğü parçalar

Model ne harfleri ne de sözcükleri doğrudan görür. Metin önce token denen parçalara bölünür. Bir token bazen bütün bir sözcük, bazen sözcüğün bir kısmı, bazen bir noktalama işaretidir. Model okurken de yazarken de token token ilerler; oyuncak modelinin sözcük sözcük ilerlemesi gibi.

Neden umursamalısın? Çünkü bu derste göreceğin üç şey token ile ölçülür:

• Fiyat: Claude'a gönderdiğin ve ondan aldığın her token ücretlendirilir.
• Sınır: Modelin bir seferde görebileceği metin token sayısıyla sınırlıdır (sıradaki bölüm).
• Süre: Cevap token token üretildiği için uzun cevap daha uzun sürer.

Bir metnin kaç token tuttuğunu gözle bilemezsin. Sayı metnin içeriğine ve modelin bölme kurallarına göre değişir: belgelere göre aynı metin, Claude'un yeni modellerinde eski modellere göre yaklaşık yüzde 30 daha fazla token tutuyor. Bir fikir vermesi için belgedeki bir örnek: "You are a scientist" sistem talimatı ile "Hello, Claude" mesajı, Claude Opus 5.5'te toplam 14 girdi token'ı sayılıyor. Kesin sayıyı iki yerden öğrenirsin: her cevabın usage alanından ve isteği göndermeden önce saymaya yarayan ücretsiz countTokens uç noktasından.

#Bağlam penceresi: modelin görebildiği alan

Model bir cevap üretirken neye bakabilir? Yalnız o istekte gönderdiğin şeylere: sistem talimatı, mesajlar ve o an ürettiği cevabın kendisi. Bunların toplamının sığması gereken alana bağlam penceresi denir. Claude Opus 5.5, Sonnet 5.5 ve Haiku 5.5'te bu pencere 1 milyon token; tek bir cevap en çok 128 bin token olabilir.

Bunun iki önemli sonucu var:

1. Model seni hatırlamaz. Her istek ayrıdır. İkinci isteğe birincinin metnini koymazsan model onu hiç görmemiş olur. Claude.ai gibi sohbet uygulamaları her mesajda önceki konuşmayı yeniden gönderir; kendi uygulamanda bu işi senin kodun yapacak (Ders 48).
2. Büyük pencere "her şeyi koy" demek değil. Belgeler, bağlamdaki token sayısı arttıkça modelin doğruluğunun ve bir şeyi hatırlama başarısının düştüğünü söylüyor. Gerekeni koy, gereksizi koyma.

Şekildeki iki kural pencere taşınca ne olduğunu söylüyor: girdi sığmazsa istek 400 ile reddedilir, cevap sınıra dayanırsa yarıda kesilir. Bu derste o sınıra yaklaşmayacaksın; bütün bir kitabı modele vermeye kalktığında karşına çıkar.

#Sıcaklık: ne kadar zar atılsın?

Oyuncak modelin her çalıştırmada aynı cümleleri kurdu, çünkü her adımda en sık geleni seçti. Gerçek modeller her adımda adayların olasılıklarını hesaplar ve bu listeden bir seçim yapar. Seçimin ne kadar maceracı olacağını belirleyen ayara sıcaklık denir.

Bunu oyuncak modelinde dene. Dosyanın sonuna, olasılığı kadar şans veren ikinci bir seçici ekle. Fikir bir torba: her sözcük için, kaç kez geldiyse o kadar bilet at; sonra torbadan rastgele bir bilet çek. "için"den sonra "büyü"nün iki bileti, "savaşır" ile "kılıç"ın birer bileti olur.

51// Torbaya her sözcükten, kaç kez geldiyse o kadar bilet at; rastgele birini çek52function rastgeleSec(adaylar: Record<string, number>): string {53    const torba: string[] = []54    for (const [sozcuk, kac] of Object.entries(adaylar)) {55        for (let i = 0; i < kac; i++) {56            torba.push(sozcuk)57        }58    }59    return torba[Math.floor(Math.random() * torba.length)]60}61 62function uretZarla(ilkSozcuk: string): string {63    const sozcukler = [ilkSozcuk]64    let son = ilkSozcuk65    while (sayim[son]) {66        son = rastgeleSec(sayim[son])67        sozcukler.push(son)68    }69    return sozcukler.join(" ")70}71 72console.log("Zarla üretilenler:")73console.log(uretZarla("Garen"))74console.log(uretZarla("Garen"))75console.log(uretZarla("Garen"))

Lux Demacia için büyü yaparAhri Ionia için büyü yaparGaren Demacia için büyü yaparYasuo Ionia için büyü yaparZarla üretilenler:Garen Demacia için büyü yaparGaren Demacia için savaşırGaren Demacia için kılıç sallar

uretZarla, uret'in neredeyse aynısı; tek fark vurgulu satırda: enOlasi yerine rastgeleSec. Programı birkaç kez çalıştır, son üç satır çoğu zaman değişir. Bazen doğru cümleyi (savaşır), bazen yanlışlarını kurar.

enOlasi sıcaklığı sıfıra çekilmiş bir model gibidir: her seferinde en sık geleni seçer. rastgeleSec ise sayımın verdiği olasılıkları olduğu gibi kullanır: "büyü" dört biletin ikisini tuttuğu için yüzde 50, "savaşır" ve "kılıç" yüzde 25 şansla gelir. Sıcaklığın 1 olduğu durum budur.

Sıcaklık 1'in altına indikçe sık gelenin şansı büyür, üstüne çıktıkça şanslar birbirine yaklaşır. Genel kural:

• Düşük sıcaklık: model neredeyse her zaman en olası parçayı seçer. Cevaplar tutarlıdır ama tekrarcıdır.
• Yüksek sıcaklık: daha az olası parçalara da şans verilir. Cevaplar çeşitlenir ama konudan sapma ve saçmalama riski artar.

Bir gerçeği baştan bil: Claude'un yeni modellerinde sıcaklığı sen değiştiremezsin. Opus 5.5, Sonnet 5.5 ve Haiku 5.5 sıcaklığı varsayılan değerinde, yani 1'de tutar: sonraki parçayı, torbadaki gibi, hesapladıkları olasılıklara göre seçerler. İsteğe temperature alanını başka bir değerle eklersen istek 400 hatasıyla reddedilir. Daha eski modellerde (ör. hâlâ kullanılabilen Haiku 4.5) 0 ile 1 arasında bir değer verebilirsin; başka şirketlerin API'lerinde de bu ayarla karşılaşacaksın.

Kavramın asıl dersi şu: aynı soruya her seferinde biraz farklı cevap gelmesi bir hata değil, seçim adımının doğası. Belgelere göre sıcaklığı 0 yapmak bile birebir aynı cevabı hiçbir zaman garanti etmedi. Tutarlı biçimde cevap almayı Ders 48'de öğreneceksin.

#Halüsinasyon ve modelin sınırları

Oyuncak modelinin "Garen Demacia için büyü yapar" demesini hatırla. Model yalan söylemedi; yalnızca kalıplara göre en olası devamı seçti ve olası görünen her şey doğru değildi. Dil modelinin gerçekte olmayan bir bilgiyi akıcı ve kendinden emin bir dille üretmesine halüsinasyon denir. Büyük modellerde bu çok daha seyrektir ama ortadan kalkmış değildir. Gerçek dünyadan üç örnek:

• 2023, New York: Bir avukat dava dilekçesi için ChatGPT'den emsal karar istedi. Model mahkeme adları ve tarihlerle altı karar sıraladı; hiçbiri gerçek değildi. Mahkeme (Mata v. Avianca davası) avukatlara 5.000 dolar para cezası verdi.
• 2023, Google Bard tanıtımı: Google'ın sohbet modeli, tanıtım ilanında Güneş Sistemi dışındaki bir gezegenin ilk fotoğrafını James Webb Uzay Teleskobu'nun çektiğini söyledi; o fotoğraf 2004'te başka bir teleskopla çekilmişti. Hatanın haberlere çıktığı gün şirketin borsa değeri yaklaşık 100 milyar dolar düştü.
• 2024, Kanada: Air Canada'nın sohbet botu, yakını ölen bir yolcuya indirimli bilet farkını uçuştan sonra da geri isteyebileceğini söyledi; şirketin kuralı böyle değildi. Uyuşmazlığa bakan kurul, botun sözünden şirketi sorumlu tuttu ve farkı ödetti.

Neden olur? Model eğitimde "doğru" cümleyi değil, olası cümleyi üretmeyi öğrenir. Çoğu zaman olası olan doğrudur. Ama nadir bir bilgi, eğitimden sonra olmuş bir olay ya da hiç var olmayan bir şey sorulduğunda, olası görünen bir uydurmayı da aynı kendinden emin tonla yazabilir. Model (sen araç vermedikçe) internete ya da bir veritabanına bakmaz; her şeyi eğitimde gördüğü kalıplardan üretir.

#API anahtarı almak ve saklamak

Claude, Anthropic'in sunucularında çalışır. Ona Ders 24'te Data Dragon'a yaptığın gibi bir HTTP isteği gönderirsin; farkı, bu hizmetin ücretli olması. Sunucunun her istekte "bu isteği kim gönderiyor, faturayı kime yazayım?" sorusuna cevap alması gerekir. Cevap, isteğin bir başlığında taşınan API anahtarıdır; Ders 26'daki Authorization başlığının işini görür. Anahtarı ele geçiren senin adına, senin paranla istek atar.

#Console'dan anahtar almak

Anahtarlar Claude Console'da oluşturulur. Console, sohbet ettiğin claude.ai'den ayrı bir sitedir ve API kullanımı sohbet planından ayrı faturalanır (bazı ücretli planlar her ay bir miktar API kredisi içerir).

#.env ve .gitignore

Anahtar asla kodun içine yazılmaz. Ders 29'daki düzeni kur ve sırayı bozma: önce .gitignore, sonra .env. Böylece .env dosyası bir an bile Git'in göreceği bir yerde durmaz.

1node_modules2.env

1ANTHROPIC_API_KEY=sk-ant-api03-buraya-kendi-anahtarin

Değişkenin adı tam olarak ANTHROPIC_API_KEY olmalı: SDK anahtarı kendiliğinden bu addan okur. Değeri tırnaksız ve boşluksuz yapıştır. Programı da her seferinde node --env-file=.env dosya.ts ile çalıştıracaksın.

#Anahtar tarayıcıya girmez

Ders 44'teki kuralı hatırla: tarayıcıda çalışan koda giren her şey, sayfayı açan herkesin bilgisayarına iner. Bunu sahte bir anahtarla denedik: Ders 40'taki gibi bir Vite projesinde .env'e VITE_ANTHROPIC_API_KEY=sk-ant-api03-SAHTE-ANAHTAR-123 yazdık, bir bileşende import.meta.env.VITE_ANTHROPIC_API_KEY ile okuduk ve npm run build ile derledik. Sonra derlenen dosyalarda sk-ant aradık (findstr /m aranan metnin geçtiği dosyaların adını yazar):

PS C:\kod\vite-deneme> findstr /m "sk-ant" dist\assets\*.jsdist\assets\index-B5rposho.js

O dosya, sayfayı açan herkesin tarayıcısına inen dosya. İçinde anahtar olduğu gibi duruyordu:

Kl=new Ul({apiKey:`sk-ant-api03-SAHTE-ANAHTAR-123`})

Next.js'teki NEXT_PUBLIC_ önekli değişkenler de böyle derlenen dosyaya yazılır. Sayfayı açan biri F12 ile Network ya da Sources sekmesine bakıp anahtarı kopyalayabilir. Doğru düzen, Ders 30'daki ara sunucu fikridir: tarayıcı yalnız senin sunucuna soru gönderir; anahtarı bilen ve Claude'a istek atan, sunucudaki koddur (bir Route Handler ya da Server Action).

SDK de seni bu hatadan korumaya çalışır: tarayıcıda çalıştırılmaya kalkılınca hata verir.

It looks like you're running in a browser-like environment. This is disabled by default, as it risks exposing your secret API credentials to attackers.If you understand the risks and have appropriate mitigations in place,you can set the `dangerouslyAllowBrowser` option to `true`, e.g., new Anthropic({ apiKey, dangerouslyAllowBrowser: true });

#Anahtar GitHub'a girmez

GitHub herkese açık depolarda sızmış anahtarları tarar; Anthropic de bu taramanın ortağıdır. Açık bir depoya Claude anahtarı gönderirsen anahtar kendiliğinden devre dışı bırakılır ve sana e-posta gelir. Buna güvenme; gizli depolar, ekran görüntüleri ve Discord mesajları bu taramaya girmez.

Bir anahtarın sızdığından şüphelenirsen Ders 29'daki kuralı uygula: Console'da Settings → API keys sayfasında anahtarı bul ve Delete ile sil (Disable yalnız geçici olarak kapatır, sonradan yeniden açılabilir), yeni anahtar oluştur ve .env'i güncelle. Git geçmişinden silmek yetmez; dışarı çıkmış anahtar yanmış sayılır.

#SDK ile ilk mesaj

Claude'a fetch ile de istek atabilirsin; Ders 30'da dış API'lere böyle bağlandın. Bir isteğin aslında neye benzediğine bak:

POST https://api.anthropic.com/v1/messagesx-api-key: sk-ant-api03-...anthropic-version: 2023-06-01content-type: application/json {"model":"claude-opus-5-5","max_tokens":1000,"messages":[{"role":"user","content":"..."}]}

Başlıkları her seferinde doğru yazmak, gelen JSON'u tiplerle okumak, geçici hatalarda yeniden denemek, akışı parçalara ayırmak... Bunların hepsini senin yerine yapan hazır bir paket var: Anthropic'in resmî SDK'sı.

#Projeyi kurmak

C:\kod\yapay-zeka klasöründe VS Code'un terminalini aç. Projeyi Ders 14'teki gibi başlat, SDK'yı kur, TypeScript'i ve Node tiplerini geliştirme bağımlılığı olarak ekle:

PS C:\kod\yapay-zeka> npm init -yWrote to C:\kod\yapay-zeka\package.json:...PS C:\kod\yapay-zeka> npm pkg set type=modulePS C:\kod\yapay-zeka> npm install @anthropic-ai/sdk added 7 packages, and audited 8 packages in 7s found 0 vulnerabilitiesPS C:\kod\yapay-zeka> npm install -D typescript @types/node@24 added 4 packages, and audited 12 packages in 2s found 0 vulnerabilities

@types/node@24, Ders 39'daki gibi Node 24'ün tip tanımlarını getirir. Bu ders hazırlanırken kurulan sürümler SDK için 0.133.0, TypeScript için 7.0.2 idi; package.json'da sende daha yeni sayılar görebilirsin. Tip denetimi için klasöre bir tsconfig.json ekle ve denetimi bir kez çalıştır:

1{2    "compilerOptions": {3        "target": "esnext",4        "module": "nodenext",5        "types": ["node"],6        "strict": true,7        "noEmit": true,8        "skipLibCheck": true9    }10}

PS C:\kod\yapay-zeka> npx tsc --noEmitPS C:\kod\yapay-zeka> 

"types": ["node"] Node'a özgü adları (process gibi) tanıtır; "noEmit": true "yalnız denetle, dosya üretme" demektir; "skipLibCheck": true ise node_modules içindeki tip dosyalarını yeniden denetleyip zaman kaybetmeyi önler. Kodu Node doğrudan çalıştırır, npx tsc --noEmit yalnızca tiplerini denetler (Ders 39).

#İlk istek

ilk-mesaj.ts dosyasını oluştur ve yaz:

1import Anthropic from "@anthropic-ai/sdk"2 3const client = new Anthropic()4 5const mesaj = await client.messages.create({6    model: "claude-opus-5-5",7    max_tokens: 1000,8    messages: [9        { role: "user", content: "Ahri oynamaya yeni başlayan birine tek cümlelik bir taktik ver." }10    ]11})12 13for (const blok of mesaj.content) {14    if (blok.type === "text") {15        console.log(blok.text)16    }17}18console.log("Girdi token:", mesaj.usage.input_tokens)19console.log("Çıktı token:", mesaj.usage.output_tokens)

Önce tipleri denetle, sonra anahtarı .env'den okuyarak çalıştır:

PS C:\kod\yapay-zeka> npx tsc --noEmitPS C:\kod\yapay-zeka> node --env-file=.env ilk-mesaj.tsÖnce E ile büyüle; tutarsa Q ve W ile vur, ıskalarsan geri çekil.Girdi token: 31Çıktı token: 48# Cevap ve sayılar örnektir; sende farklı olur.

Satır satır:

• new Anthropic() bir istemci (client) oluşturur. Anahtarı vermedin, çünkü SDK onu kendiliğinden ANTHROPIC_API_KEY ortam değişkeninden okur. Adı belgelerdeki gibi client koyduk; istediğin adı verebilirsin.
• model: cevabı hangi modelin vereceği. claude-opus-5-5, Claude Opus 5.5'in kimliğidir; harfi harfine yazılmalı.
• max_tokens: cevaba izin verdiğin en çok token. Bir sınırdır, hedef değil; model işi bitince daha önce durur. Yeni modellerin cevaptan önceki düşünmesi de bu sınırdan yer.
• messages: konuşma. Her mesajın bir role'ü (kim konuşuyor) ve bir content'i (ne dedi) var. İlk mesaj hep "user", yani sensin.
• await: istek ağda gidip geldiği için Promise döner (Ders 15); "type": "module" sayesinde dosyanın en üstünde await kullanabiliyorsun.

#Cevabın içi

mesaj değişkenine gelen obje, API'nin gönderdiği JSON'un tiplerle sarılmış hâlidir. Kısaltılmış bir örnek:

{    "model": "claude-opus-5-5",    "id": "msg_013mHbppMPd2PrVJzGMZPt2D",    "type": "message",    "role": "assistant",    "content": [        {            "type": "text",            "text": "Önce E ile büyüle; tutarsa Q ve W ile vur, ıskalarsan geri çekil."        }    ],    "stop_reason": "end_turn",    "stop_sequence": null,    "stop_details": null,    "usage": {        "input_tokens": 31,        "output_tokens": 48    }}

• role: "assistant": bu mesajı model yazdı. Konuşmayı sürdürmek istersen bu mesajı messages dizisine ekleyip yeni sorunu arkasına koyarsın (Ders 48).
• content bir dizi, çünkü cevap birden çok bloktan oluşabilir. Bu derste yalnız "text" bloklarıyla ilgileniyoruz. Opus 5.5 zor bir soruda cevaplamadan önce düşünür; o zaman dizinin başında type: "thinking" olan bir blok da görürsün. Bu bloğun metni varsayılan olarak boş gelir, ama düşünme token'ları output_tokens'a eklenir ve ücretlendirilir. Basit sorularda model hiç düşünmeyebilir.
• stop_reason modelin neden durduğunu söyler: "end_turn" işini bitirdi, "max_tokens" senin koyduğun sınıra takıldı ve cevap yarıda kaldı, "model_context_window_exceeded" bağlam penceresi doldu, "refusal" güvenlik sebebiyle cevap vermeyi reddetti.
• usage faturanın temelidir: input_tokens gönderdiğin, output_tokens modelin ürettiği token sayısı.

Kodda neden blok.type === "text" diye sorduğumuzu merak ettiysen, kısayolu dene:

PS C:\kod\yapay-zeka> npx tsc --noEmitilk-mesaj.ts:13:30 - error TS2339: Property 'text' does not exist on type 'ContentBlock'.  Property 'text' does not exist on type 'BashCodeExecutionToolResultBlock'. 13 console.log(mesaj.content[0].text)                                ~~~~ Found 1 error in ilk-mesaj.ts:13

PS C:\kod\yapay-zeka> node ilk-mesaj.tsfile:///C:/kod/yapay-zeka/node_modules/@anthropic-ai/sdk/client.mjs:338            throw new Error('Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted');                  ^ Error: Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted    at Anthropic.validateHeaders (file:///C:/kod/yapay-zeka/node_modules/@anthropic-ai/sdk/client.mjs:338:19)    ...    at async file:///C:/kod/yapay-zeka/ilk-mesaj.ts:5:15 Node.js v24.20.0

PS C:\kod> node --env-file=.env yapay-zeka\ilk-mesaj.tsC:\Program Files\nodejs\node.exe: .env: not found

PS C:\kod\yapay-zeka> npx tsc --noEmitilk-mesaj.ts:5:44 - error TS2769: No overload matches this call.  The last overload gave the following error.    Property 'max_tokens' is missing in type '{ model: "claude-opus-5-5"; messages: { role: "user"; content: string; }[]; }' but required in type 'MessageCreateParamsBase'....Found 1 error in ilk-mesaj.ts:5

#Sistem talimatı: maçtan önceki brifing

İlk isteğinde modelin nasıl cevap vereceğine hiç karışmadın. Bir uygulamada ise modelin rolünü, dilini, uzunluğunu sen belirlersin. Bunun yeri sistem talimatıdır: kullanıcının mesajlarından ayrı duran, bütün konuşma boyunca geçerli kurallar. Modele gönderdiğin metnin tamamına ise istem denir.

ilk-mesaj.ts dosyasını koc.ts adıyla kopyala, system alanını ekle (vurgulu satır) ve soruyu değiştir. Token satırlarını bu kez sildik, cevabın kendisine odaklanalım:

1import Anthropic from "@anthropic-ai/sdk"2 3const client = new Anthropic()4 5const mesaj = await client.messages.create({6    model: "claude-opus-5-5",7    max_tokens: 2000,8    system: "Sen sabırlı bir LoL koçusun. Türkçe cevap ver ve en fazla üç cümle yaz.",9    messages: [10        { role: "user", content: "Koridorda rakibim beni hep erken öldürüyor. Ne yapmalıyım?" }11    ]12})13 14for (const blok of mesaj.content) {15    if (blok.type === "text") {16        console.log(blok.text)17    }18}

İlk dakikalarda minyonlarının arkasında kal ve yalnız son vuruşa odaklan; rakip yeteneklerini harcamadan saldırıya geçme. Ormancısını haritada göremiyorsan kuleye yakın oyna. Altıncı seviyeye kadar sabırlı ol, güçlenince karşılık ver.

Sistem talimatını silip aynı soruyu sorarsan model büyük ihtimalle başlıklı, maddeli ve çok daha uzun bir cevap yazar. Talimat cevabın biçimini değiştirdi; kısa cevap ayrıca daha az çıktı token'ı, yani daha az para demek. İyi bir sistem talimatı kısa ve somuttur: rol, dil, uzunluk, biçim. Kullanıcıdan gelen metni sistem talimatının içine yapıştırma; o alan senin kurallarına ayrılmıştır. İyi istemin parçalarını ve bu kuralın sebebini Ders 48'de ayrıntılı göreceksin.

#Cevabı akış olarak almak

Uzun bir cevabın üretilmesi saniyeler sürebilir. messages.create bütün cevap bitene kadar bekler; kullanıcı da o süre boyunca boş bir ekrana bakar. Claude.ai'de cevabın yazılır gibi akmasının sebebi akıştır (Ders 27'de gördüğün akışla aynı fikir: veri tek seferde değil, parça parça gelir): model her parçayı ürettiği anda sana yollar.

Akışın bir faydası daha var: belgeler, büyük bir max_tokens ile akışsız istek göndermemeni söylüyor; bazı ağlar uzun süre sessiz kalan bağlantıları koparabilir. koc.ts'i akis.ts adıyla kopyala ve isteği akışa çevir:

1import Anthropic from "@anthropic-ai/sdk"2 3const client = new Anthropic()4 5const akis = client.messages.stream({6    model: "claude-opus-5-5",7    max_tokens: 2000,8    system: "Sen sabırlı bir LoL koçusun. Türkçe cevap ver ve en fazla üç cümle yaz.",9    messages: [10        { role: "user", content: "Koridorda rakibim beni hep erken öldürüyor. Ne yapmalıyım?" }11    ]12})13 14akis.on("text", (parca) => {15    process.stdout.write(parca)16})17 18const sonMesaj = await akis.finalMessage()19console.log()20console.log("Durma sebebi:", sonMesaj.stop_reason)21console.log("Token:", sonMesaj.usage.input_tokens, "girdi,", sonMesaj.usage.output_tokens, "çıktı")

İlk dakikalarda minyonlarının arkasında kal ve yalnız son vuruşa odaklan; rakip yeteneklerini harcamadan saldırıya geçme. Ormancısını haritada göremiyorsan kuleye yakın oyna. Altıncı seviyeye kadar sabırlı ol, güçlenince karşılık ver.Durma sebebi: end_turnToken: 64 girdi, 97 çıktı

Üç yeni şey var:

• client.messages.stream(...) isteği akış olarak açar. await yok, çünkü hemen bir akış objesi döner; cevap arkadan gelir.
• akis.on("text", ...) her yeni metin parçasında çalışacak bir fonksiyon kaydeder. Ders 22'deki addEventListener gibi bir olay dinleyicisi. console.log her seferinde alt satıra geçerdi; process.stdout.write ise yazdığını aynı satırda bırakır, böylece parçalar yan yana dizilir.
• await akis.finalMessage() akış bitene kadar bekler ve sana messages.create'in döndürdüğü objenin aynısını verir. stop_reason ve usage gibi bilgileri buradan okursun. Hemen ardındaki boş console.log() imleci yeni satıra indirir.

Perde arkasında SDK, HTTP cevabını açık tutar ve sunucunun art arda gönderdiği olayları (server-sent events) okur. Belgelerdeki kısa bir örnek akış böyle görünür; SDK bunları senin için çözüp text olayına çevirir:

event: message_startdata: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], ...}} event: content_block_startdata: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}} event: content_block_deltadata: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Hello"}} event: content_block_deltadata: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "!"}} event: content_block_stopdata: {"type": "content_block_stop", "index": 0} event: message_deltadata: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence":null}, "usage": {"output_tokens": 15}} event: message_stopdata: {"type": "message_stop"}

content_block_delta olaylarındaki text değerleri senin parca değişkenine gelen metinlerdir. Akışın arasında, içinde metin taşımayan ping olayları da gelebilir; SDK onları senin yerine atlar.

#Hatalar ve yeniden deneme

API'nin hata kodları Ders 26'da öğrendiğin durum kodlarıdır; Anthropic her birine ayrıca bir tür adı verir:

İyi haber: SDK geçici hataları (bağlantı kopması, 429, 5xx) kendisi iki kez daha dener, her denemede biraz daha uzun bekler ve sunucu retry-after gönderdiyse ona uyar. Ders 30'da elle yazdığın yeniden deneme döngüsü burada hazır geliyor. Deneme sayısını istemciyi oluştururken değiştirebilirsin: new Anthropic({ maxRetries: 4 }). 0 yazarsan hiç denemez.

Yeniden denemenin işe yaramadığı hatalarda programın çökmesin, kullanıcıya anlaşılır bir şey söylesin. SDK her durum kodu için ayrı bir hata sınıfı verir; onları Ders 16'daki gibi instanceof ile, en özelden en genele doğru ayır. hatalar.ts dosyasını oluştur:

1import Anthropic from "@anthropic-ai/sdk"2 3const client = new Anthropic()4 5try {6    const mesaj = await client.messages.create({7        model: "claude-opus-5-5",8        max_tokens: 1000,9        messages: [{ role: "user", content: "Merhaba" }]10    })11    for (const blok of mesaj.content) {12        if (blok.type === "text") {13            console.log(blok.text)14        }15    }16} catch (hata) {17    if (hata instanceof Anthropic.AuthenticationError) {18        console.log("Anahtar geçersiz: .env dosyasındaki ANTHROPIC_API_KEY değerine bak.")19    } else if (hata instanceof Anthropic.RateLimitError) {20        console.log("Hız sınırına takıldın: biraz bekleyip yeniden dene.")21    } else if (hata instanceof Anthropic.APIError) {22        console.log(`API hatası: ${hata.status} ${hata.type}`)23    } else {24        throw hata25    }26}

Anthropic.APIError bütün API hatalarının atasıdır; status alanında durum kodu, type alanında tür adı durur. Son else dalı, tanımadığın hataları yutmamak için onları yeniden fırlatır (Ders 13). Bilerek dene: .env'deki anahtarın son harfini değiştir ve çalıştır. Geçersiz anahtar her seferinde 401 aldığı için çıktın bu olur:

PS C:\kod\yapay-zeka> node --env-file=.env hatalar.tsAnahtar geçersiz: .env dosyasındaki ANTHROPIC_API_KEY değerine bak.

Sonra anahtarı düzeltmeyi unutma. Hatayı yakalamasaydın Node ne yazardı, aşağıdaki kartlarda var. Kartlardaki çıktıları gerçek API'ye istek atmadan, API'nin bu durumlarda döndürdüğü hata gövdelerini taklit eden yerel bir deneme sunucusuyla ürettik; Görev 5'te böyle bir sunucuyu sen de yazacaksın. İstek kimliği (req_...) sende farklı olur.

file:///C:/kod/yapay-zeka/node_modules/@anthropic-ai/sdk/core/error.mjs:45            return new AuthenticationError(status, error, message, headers, type);                   ^ AuthenticationError: 401 {"type":"error","error":{"type":"authentication_error","message":"invalid x-api-key"},"request_id":"req_011CSHoEeqs5C35K2UUqR7Fy"}    at APIError.generate (file:///C:/kod/yapay-zeka/node_modules/@anthropic-ai/sdk/core/error.mjs:45:20)    ...    at async file:///C:/kod/yapay-zeka/ilk-mesaj.ts:5:15 {  status: 401,  ...  type: 'authentication_error'} Node.js v24.20.0

NotFoundError: 404 {"type":"error","error":{"type":"not_found_error","message":"model: claude-opus-5.5"},"request_id":"req_011CSHoEeqs5C35K2UUqR7Fy"}    at APIError.generate (file:///C:/kod/yapay-zeka/node_modules/@anthropic-ai/sdk/core/error.mjs:51:20)    ...

InternalServerError: 529 {"type":"error","error":{"type":"overloaded_error","message":"Overloaded"},"request_id":"req_011CSHoEeqs5C35K2UUqR7Fy"}    at APIError.generate (file:///C:/kod/yapay-zeka/node_modules/@anthropic-ai/sdk/core/error.mjs:63:20)    ...

#Maliyet ve model seçimi

API'nin faturası iki kalemden oluşur: gönderdiğin token'lar girdi fiyatından, modelin ürettiği token'lar çıktı fiyatından ücretlendirilir. Fiyatlar bir milyon token başına, dolar olarak verilir. 12 Ekim 2026 itibarıyla Anthropic'in resmî fiyat sayfasındaki temel fiyatlar:

Haiku 5.5'in fiyatı, isteğin girdisi 100.000 token'ı aşınca 0,50 $ girdi ve 2,50 $ çıktıya yükselir; diğer üç model 1 milyon token'lık pencerenin tamamında aynı fiyatı uygular. Fiyatlar değişebilir; uygulamanı yayına almadan önce fiyat sayfasına yeniden bak.

Tablodan iki şey hemen göze çarpıyor. Birincisi, çıktı girdiden beş kat pahalı: uzun cevaplar faturayı uzun sorulardan daha hızlı büyütür. Bu yüzden "en fazla üç cümle" gibi bir sistem talimatı paradan da tasarruf ettirir. İkincisi, modeller arasındaki fark büyük: Opus 5.5, Haiku 5.5'in kırk katı, Fable 5.1 ise yüz katı fiyatında. Hesabı koda dökelim. maliyet.ts dosyasını oluştur:

1type Fiyat = { girdi: number, cikti: number }2 3// 1 milyon token başına dolar (resmî fiyat sayfası, 12 Ekim 2026)4const fiyatlar: Record<string, Fiyat> = {5    "claude-opus-5-5": { girdi: 4, cikti: 20 },6    "claude-sonnet-5-5": { girdi: 2, cikti: 10 },7    "claude-haiku-5-5": { girdi: 0.1, cikti: 0.5 }8}9 10function maliyet(model: string, girdiToken: number, ciktiToken: number): number {11    const fiyat = fiyatlar[model]12    return (girdiToken * fiyat.girdi + ciktiToken * fiyat.cikti) / 100000013}14 15// Koç botu: her soruda 1.200 girdi, 300 çıktı token'ı; günde 1.000 soru16for (const model of Object.keys(fiyatlar)) {17    const tekSoru = maliyet(model, 1200, 300)18    const aylik = tekSoru * 1000 * 3019    console.log(`${model}: soru başına ${tekSoru.toFixed(5)} dolar, ayda ${aylik.toFixed(2)} dolar`)20}

claude-opus-5-5: soru başına 0.01080 dolar, ayda 324.00 dolarclaude-sonnet-5-5: soru başına 0.00540 dolar, ayda 162.00 dolarclaude-haiku-5-5: soru başına 0.00027 dolar, ayda 8.10 dolar

Tek bir soru kuruşlar tutuyor; denemelerin seni zorlamaz. Ama aynı uygulama günde bin soruyla ayda 8 dolar da tutabilir, 324 dolar da. Gerçek sayıları tahmin etme, ölç: her cevabın usage alanındaki input_tokens ve output_tokens değerlerini bu fonksiyona ver. Opus 5.5'te düşünme token'ları output_tokens'ın içindedir; zor sorularda bu sayı cevabın uzunluğundan büyük çıkabilir.

Hangi modeli seçeceğine alışkanlık değil, işin zorluğu karar verir. 10–20 gerçek örnek soru topla, önce ucuz bir modelle dene; cevaplar yetmiyorsa bir üst modelle aynı örnekleri karşılaştır ve farkın parasına değip değmediğine bak. Bu dersin örneklerinde Opus 5.5 kullandık; Anthropic'in belgelerindeki örneklerin çoğu da bu modeli kullanıyor. Kendi denemelerinde model alanını claude-haiku-5-5 yapıp cevapları ve faturayı karşılaştırabilirsin; karar senin.

#Görevler

Görevleri C:\kod\yapay-zeka klasöründe, her biri için yeni bir dosyada yap. API'ye istek atan görevler birkaç kuruş tutar; çıktıları örnektir. Önce kendin dene, takılırsan ipuçlarını sırayla aç.

- ...- ...- ...Durma sebebi: end_turnToken: 70 girdi, 120 çıktı

1import Anthropic from "@anthropic-ai/sdk"2 3const client = new Anthropic()4 5const mesaj = await client.messages.create({6    model: "claude-opus-5-5",7    max_tokens: 2000,8    system: "Sen bir TFT koçusun. Türkçe cevap ver. En fazla üç madde yaz ve her madde \"- \" ile başlasın.",9    messages: [10        { role: "user", content: "Altın biriktirmek mi, sürekli dükkânı yenilemek mi?" }11    ]12})13 14for (const blok of mesaj.content) {15    if (blok.type === "text") {16        console.log(blok.text)17    }18}19console.log("Durma sebebi:", mesaj.stop_reason)20console.log("Token:", mesaj.usage.input_tokens, "girdi,", mesaj.usage.output_tokens, "çıktı")

- Erken oyunda güçlü birimlerin varsa altın biriktir; her 10 altın, tur sonunda 1 altın faiz getirir.- Canın hızla düşüyorsa faizi bırak ve dükkânı yenileyerek takımını güçlendir.- 50 altına ulaştığında fazlasını harcayabilirsin; faiz 5 altında durur.Durma sebebi: end_turnToken: 71 girdi, 118 çıktı

claude-opus-5-5: ayda 144.00 dolar, sığmazclaude-sonnet-5-5: ayda 72.00 dolar, sığarclaude-haiku-5-5: ayda 3.60 dolar, sığarFiyatı bilinmeyen model: claude-sonet-5-5

1type Fiyat = { girdi: number, cikti: number }2 3const fiyatlar: Record<string, Fiyat> = {4    "claude-opus-5-5": { girdi: 4, cikti: 20 },5    "claude-sonnet-5-5": { girdi: 2, cikti: 10 },6    "claude-haiku-5-5": { girdi: 0.1, cikti: 0.5 }7}8 9function aylikMaliyet(model: string, girdi: number, cikti: number, gunlukIstek: number): number {10    const fiyat = fiyatlar[model]11    if (!fiyat) {12        throw new Error(`Fiyatı bilinmeyen model: ${model}`)13    }14    const tekIstek = (girdi * fiyat.girdi + cikti * fiyat.cikti) / 100000015    const tutar = tekIstek * gunlukIstek * 3016    return Math.round(tutar * 100) / 10017}18 19const butce = 7220for (const model of Object.keys(fiyatlar)) {21    const tutar = aylikMaliyet(model, 3000, 600, 200)22    let durum = "sığmaz"23    if (tutar <= butce) {24        durum = "sığar"25    }26    console.log(`${model}: ayda ${tutar.toFixed(2)} dolar, ${durum}`)27}28 29try {30    aylikMaliyet("claude-sonet-5-5", 3000, 600, 200)31} catch (hata) {32    if (hata instanceof Error) {33        console.log(hata.message)34    }35}

claude-opus-5-5: ayda 144.00 dolar, sığmazclaude-sonnet-5-5: ayda 72.00 dolar, sığarclaude-haiku-5-5: ayda 3.60 dolar, sığarFiyatı bilinmeyen model: claude-sonet-5-5

0 girdi, 0 çıktı: 0 dolar100000 girdi, 1000 çıktı: 0.0105 dolar100001 girdi, 1000 çıktı: 0.0525005 dolarTek token fazlası faturayı 5 katına çıkardı.

1function haikuMaliyet(girdi: number, cikti: number): number {2    let girdiFiyati = 0.13    let ciktiFiyati = 0.54    if (girdi > 100000) {5        girdiFiyati = 0.56        ciktiFiyati = 2.57    }8    return (girdi * girdiFiyati + cikti * ciktiFiyati) / 10000009}10 11console.log(`0 girdi, 0 çıktı: ${haikuMaliyet(0, 0)} dolar`)12console.log(`100000 girdi, 1000 çıktı: ${haikuMaliyet(100000, 1000)} dolar`)13console.log(`100001 girdi, 1000 çıktı: ${haikuMaliyet(100001, 1000)} dolar`)14const oran = haikuMaliyet(100001, 1000) / haikuMaliyet(100000, 1000)15console.log(`Tek token fazlası faturayı ${Math.round(oran)} katına çıkardı.`)

0 girdi, 0 çıktı: 0 dolar100000 girdi, 1000 çıktı: 0.0105 dolar100001 girdi, 1000 çıktı: 0.0525005 dolarTek token fazlası faturayı 5 katına çıkardı.

1import Anthropic from "@anthropic-ai/sdk"2 3const client = new Anthropic()4let parcaSayisi = 05let karakterSayisi = 06 7const akis = client.messages.stream({8    model: "claude-opus-5-5",9    max_tokens: 300,10    messages: [{ role: "user", content: "TFT'de altın ve faiz nasıl yönetilir? Ayrıntılı anlat." }]11})12 13akis.on("text", (parca) => {14    parcaSayisi++15    karakterSayisi += parca.length16    process.stdout.write(parca)17})18 19const sonMesaj = await akis.finalMessage()20console.log()21console.log(`${parcaSayisi} parça, ${karakterSayisi} karakter geldi.`)22if (sonMesaj.stop_reason === "max_tokens") {23    console.log("Uyarı: cevap max_tokens sınırına takılıp yarıda kesildi.")24}

TFT'de ekonomi, faiz sistemi üzerine kuruludur. Her tur sonunda elindeki her 10 altın için 1 altın faiz alırsın ve bu en çok 5 altına kadar çıkar......Kritik bir eşikteysen birkaç tur faizden vazgeçip36 parça, 702 karakter geldi.Uyarı: cevap max_tokens sınırına takılıp yarıda kesildi.

1import http from "node:http"2 3const HATA_SAYISI = 24let istekSayisi = 05 6const sunucu = http.createServer((req, res) => {7    istekSayisi++8    console.log(`${istekSayisi}. istek: ${req.method} ${req.url}`)9 10    if (istekSayisi <= HATA_SAYISI) {11        res.writeHead(529, { "Content-Type": "application/json" })12        res.end(JSON.stringify({ type: "error", error: { type: "overloaded_error", message: "Overloaded" } }))13        return14    }15 16    res.writeHead(200, { "Content-Type": "application/json" })17    res.end(JSON.stringify({18        id: "msg_sahte",19        type: "message",20        role: "assistant",21        model: "claude-opus-5-5",22        content: [{ type: "text", text: "Sahte sunucudan selam!" }],23        stop_reason: "end_turn",24        stop_sequence: null,25        usage: { input_tokens: 10, output_tokens: 5 }26    }))27})28 29sunucu.listen(3047, () => {30    console.log("Sahte Claude hazır")31})

1import Anthropic from "@anthropic-ai/sdk"2 3const client = new Anthropic({4    apiKey: "sahte-anahtar",5    baseURL: "http://localhost:3047"6})7 8const baslangic = Date.now()9const mesaj = await client.messages.create({10    model: "claude-opus-5-5",11    max_tokens: 100,12    messages: [{ role: "user", content: "Merhaba" }]13})14 15for (const blok of mesaj.content) {16    if (blok.type === "text") {17        console.log(blok.text)18    }19}20console.log(`Geçen süre: ${Date.now() - baslangic} ms`)

Sahte Claude hazır1. istek: POST /v1/messages2. istek: POST /v1/messages3. istek: POST /v1/messages

Sahte sunucudan selam!Geçen süre: 1442 ms

#Kendini sına

Error: Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted    at Anthropic.validateHeaders (file:///C:/kod/yapay-zeka/node_modules/@anthropic-ai/sdk/client.mjs:338:19)

#Kayıt noktası

yapay-zeka yeni bir proje klasörü; önce git init. Commit'ten önce git status ile .env dosyasının listede olmadığını gözünle gör: .gitignore işini yapıyorsa orada görünmez.

Bir sonraki derste modelden tutarlı sonuç almayı öğreneceksin: iyi bir istemin parçaları, örnekli istem ve cevabı programının güvenle kullanabileceği, doğrulanmış JSON olarak almak.