Yerel LLM'leri API Olarak Kullanma Rehberi

Dizüstü bilgisayarınız, üretime sunduğunuz OpenAI benzeri uç noktanın arkasında 70B parametreli bir modele hizmet edebilir. Tek bir temel URL'yi değiştirerek kodunuz çalışmaya devam eder. Bu tek değişiklik, çevrimdışı geliştirmeyi, sıfır token başına maliyeti ve düzenlenmiş veriler için özel bir yolu mümkün kılar; bu nedenle Hacker News, "Yerel Yapay Zeka norm olmalı" başlıklı yazıyı bir günde 633'ten 1.760 puana yükseltti. Aşağıdaki bölüm, bir çalışma zamanı seçmeyi, uç noktayı açığa çıkarmayı, istemcinizi ona yönlendirmeyi ve barındırılan bir modelde herhangi bir değişikliği tanıtmadan önce tüm akışı Apidog ile test etmeyi göstermektedir.

TL;DR

Dizüstü bilgisayarınızda Ollama, vLLM veya llama.cpp ile yerel bir LLM API'si çalıştırabilirsiniz ve bunların her biri OpenAI uyumlu bir REST uç noktası sunar. Mevcut OpenAI istemcinizdeki `base_url`'i `http://localhost:11434/v1` olarak değiştirin ve aynı kod, yeniden yazmaya gerek kalmadan Llama 3.3, DeepSeek V4 veya Qwen 3.6 üzerinde çalışır. Senaryo testlerinizin yerel ve barındırılan ortamlar arasında aynı kalması için tüm akışı Apidog'dan yönetin.

Giriş

Yerel LLM API yığını, on sekiz ay içinde araştırma oyuncağından günlük sürücüye dönüştü. Apple, M3 Max üzerinde 128 GB birleşik bellek gönderdi. Ollama, haftalık bir milyon indirmeye ulaştı. vLLM, 30.000 GitHub yıldızı sınırını aştı. Ancak en büyük değişim sosyaldi. Her büyük çalışma zamanı artık OpenAI'nin `/v1/chat/completions` şeklini konuşuyor. Artık iki istemci yolu sürdürmüyorsunuz. Aynı SDK çağrısı, tek bir ortam değişkenine bağlı olarak localhost veya `api.openai.com` adresini vuruyor.

Bu, API geliştiricileri için önemlidir çünkü mevcut araçlarınız çalışmaya devam eder. Apidog'daki istek şablonlarınız `https://api.openai.com/v1/chat/completions` adresini işaret eder. Temel URL değişkenini değiştirin, Gönder'e basın ve kendi GPU'nuzda çalışan bir modelden aynı JSON'u geri alırsınız. Yeni şema yok. Yeni kimlik doğrulama akışı yok. Zaten özellik başına API harcamasını takip ediyorsanız, yerel bir modeli barındırılan bir modele karşı A/B test edebilir ve gecikme artarken maliyet çizgisinin düştüğünü görebilirsiniz.

Bu kılavuz, çalışma zamanı seçimi, sunucu kurulumu, istemci kablolaması, senaryo testi, niceleme değiş tokuşları ve dört güncel model için maliyet-gecikme tablosunu ele almaktadır. Kod örnekleri, macOS 15.4 ve Ubuntu 24.04 üzerinde Ollama 0.6 ve vLLM 0.7 ile test edilmiştir. Daha geniş seçenekler yelpazesi için En İyi Yerel LLM'ler 2026'ya bakın. Her iddianın harici referansları aşağıdadır.

API geliştiricileri için yerel LLM'ler neden mantıklı?

Bir LLM'yi çağıran kod gönderiyorsunuz. Ayrıca bu kodu uçakta, kötü Wi-Fi olan konferanslarda ve `*.openai.com` adresine giden trafiği engelleyen müşteri ağlarında da hata ayıklıyorsunuz. Yerel bir LLM API'si size ağ bağımlılığı olmadan üretimi yansıtan bir geliştirme ortamı sunar.

Gizlilik hikayesi en yüksek sesli olanıdır. HIPAA, GDPR ve AB Yapay Zeka Yasası, hasta notları, sözleşmeler veya biyometrik tanımlayıcılar içerdiği anda istemleri kullanıcı verileri olarak ele alır. Bu yükü barındırılan bir uç noktaya göndermek, belgelemeniz, denetlemeniz ve yenilemeniz gereken bir veri işlemci ilişkisi yaratır. Donanımınızdan asla ayrılmayan bir model, bu evrak işlerini tamamen atlar. Avrupa Veri Koruma Kurulu'nun 2024 yapay zeka işleme rehberliği, cihaz üzerinde çıkarımın, Madde 44 kapsamındaki çoğu sınır ötesi transfer yükümlülüğünü ortadan kaldırdığını belirtmektedir.

Maliyet diğer yönde bileşik hale gelir. Günde 50 milyon istem token'ı GPT-5.5 Instant üzerinden çalıştıran bir ekip, milyon token başına 5 dolardan yaklaşık günde 250 dolar öder. 4.500 dolarlık bir M3 Max stüdyosundaki aynı hacim, elektriği hesaba katmadan, on sekiz günlük tam kullanımdan sonra sıfıra amorti olur. Bu sayıların dökümünü GPT-5.5 Instant Nasıl Kullanılır bölümünde okuyabilir ve aynı aritmetiği kendi iş yükünüze uygulayabilirsiniz.

Üçüncü neden determinizmdir. Barındırılan modeller ağırlıkları sizin haberiniz olmadan değiştirir. OpenAI'nin model kullanımdan kaldırma sayfası, son on iki ayda on bir anlık görüntü emekliliğini listeler. Yerel bir model, diskte bir dosyadır. Bugün ve üç yıl sonra aynı logitleri üretir. Bu istikrar, regresyon paketiniz LLM çıktısına bağlı olduğunda önemlidir. OpenAI uyumlu uç nokta oyunu değiştirdi çünkü bu istikrar için artık bir entegrasyon vergisi ödemiyorsunuz. Zaten kullandığınız SDK çalışır.

OpenAI uyumlu uç noktaları sunan üç çalışma zamanı

2026'da dört çalışma zamanı yerel LLM API alanına hakimdir. Üçü OpenAI uyumlu bir REST sunucusunu doğrudan gönderir. Dördüncüsü, llama.cpp, `llama-server` ikilisinin bir parçası olarak birini gönderir. Popülerliğe göre değil, iş yüküne göre seçin.

Ollama

Ollama, en kolay başlangıç noktasıdır. Tek bir ikili, tek bir CLI, 11434 numaralı bağlantı noktasında tek bir HTTP sunucusu. Tek bir makinede tek bir model çalıştıran geliştiricileri hedefler ve model indirmelerini, GGUF nicelemesini ve istem şablonlarını sizin için halleder.

## macOS'a yükle
brew install ollama
ollama serve &
ollama pull llama3.3:70b-instruct-q4_K_M
ollama run llama3.3:70b-instruct-q4_K_M

`ollama serve` çalıştıktan sonra, OpenAI uyumlu uç nokta `http://localhost:11434/v1` adresinde bulunur. Sohbeti, yerleştirmeleri ve akışı destekler. 70B Q4_K_M modeli ile M3 Max'te verim tavanı saniyede yaklaşık 12 token'dır. Daha küçük modeller saniyede 80 ila 120 token'a ulaşır. Ollama, tek kullanıcılı geliştirme, demolar ve CI çalıştırıcıları için doğru seçimdir.

vLLM

vLLM, üretim düzeyinde bir seçenektir. Verimi basit çalıştırıcılardan iki ila dört kat daha yüksek itmek için PagedAttention ve sürekli toplu işlem kullanır. Varsayılan olarak 8000 numaralı bağlantı noktasında hizmet verir ve `/v1` adresinde OpenAI uyumlu bir API sunar. Mimari detaylarını aşağıdaki Kwon ve diğerlerinin SOSP 2023 referansındaki vLLM makalesinde okuyabilirsiniz.

pip install vllm
vllm serve meta-llama/Llama-3.3-70B-Instruct \
  --port 8000 \
  --gpu-memory-utilization 0.9 \
  --max-model-len 8192

Tek bir H100 üzerinde vLLM, eşzamanlı isteklerde Llama 3.3 70B'ye saniyede yaklaşık 2.400 token hızında hizmet verir. Bir CUDA GPU veya yeni bir AMD ROCm kartına ihtiyaç duyar ve Apple Silicon üzerinde çalışmaz, bu da onu dizüstü bilgisayarlar için yanlış, paylaşılan geliştirme kümeleri için doğru seçim yapar.

llama.cpp

llama.cpp, GGUF ekosistemini başlatan C++ çalışma zamanıdır. Raspberry Pi 5'ten çift RTX-5090 rig'lerine kadar her yerde çalışır. `llama-server` ikilisi, `/v1/chat/completions` adresinde OpenAI şeklini konuşur.

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp && make -j LLAMA_METAL=1
./llama-server -m models/llama-3.3-70b-q4_k_m.gguf \
  --port 8080 --host 0.0.0.0 -c 8192 -ngl 99

`-ngl 99` bayrağı tüm katmanları GPU'ya aktarır. llama.cpp size niceleme, toplu işlem ve bellek eşleme üzerinde en fazla kontrolü sağlar. Bir modeli 16 GB VRAM'e sığdırmanız veya egzotik donanımı test etmeniz gerektiğinde doğru seçimdir.

LM Studio ve Jan, llama.cpp'yi bir GUI içinde sarar ve ayrıca yapılandırılabilir bir bağlantı noktasında bir OpenAI uç noktası sunar. Ekibinizdeki terminale dokunmadan istemleri test etmesi gereken teknik olmayan kullanıcılar için faydalıdırlar.

Uç noktanın çalıştığını kontrol eden basit bir Python kodu:

from openai import OpenAI
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
resp = client.chat.completions.create(
    model="llama3.3:70b-instruct-q4_K_M",
    messages=[{"role": "user", "content": "Sadece OK kelimesiyle yanıtla."}],
)
print(resp.choices[0].message.content)

Eğer `OK` görürseniz, çalışma zamanı, bağlantı noktası ve SDK sözleşmesi hepsi eşleşir. Uç noktayı araçlarınıza bağlamaya hazırsınız.

Yerel LLM'nizi Apidog ile test edin

Yerel bir LLM API'si, test paketiniz üretime vurduğu gibi ona da vurabiliyorsa kullanışlıdır. Apidog bunu istek şablonundaki ortam değişkenleriyle halleder, bu da tek bir projenin her iki hedefi de kapsadığı anlamına gelir.

Akışın beş adımı vardır.

1. Apidog projenizi açın ve `Local` adında yeni bir ortam oluşturun. `BASE_URL` değişkenine `http://localhost:11434/v1` değerini ekleyin. `API_KEY` değişkenine `ollama` değerini ekleyin. Kaydedin.
2. Mevcut OpenAI ortamınızı klonlayın, adını `Production` olarak değiştirin, `BASE_URL`'i `https://api.openai.com/v1` ve `API_KEY`'i barındırılan anahtarınız olarak tutun.
3. Bir sohbet uç noktasını çağıran herhangi bir istekte, sabit kodlanmış ana bilgisayarı `{{BASE_URL}}` ile ve yetkilendirme başlığını `Bearer {{API_KEY}}` ile değiştirin. İstek URL'si `{{BASE_URL}}/chat/completions` olur.
4. İsteği başlatan, `choices[0].message.role == "assistant"` olduğunu doğrulayan, `choices[0].message.content`'in boş olmadığını doğrulayan ve `usage.total_tokens > 0` olduğunu doğrulayan bir senaryo testi oluşturun. Senaryoyu kaydedin.
5. Senaryoyu `Local` ortamında çalıştırın. Ortam açılır menüsünü `Production` olarak değiştirin. Tekrar çalıştırın. Doğrulamalar ikisi için de başarılı olmalıdır.

Aynı senaryo, çalışma zamanı yükseltmeleri için bir duman testi olarak da işlev görür. Yeni bir etikette `ollama pull` işleminden sonra `Local` senaryosunu tekrar çalıştırın. Yanıt şekli değişirse, herhangi bir uygulama kodu yeni ağırlıklara dokunmadan önce bunu yakalarsınız. Bu desen, çok adımlı API'leri çağıran yapay zeka ajanlarını test etmeye kadar uzanır.

Programatik kullanım için OpenAI Python SDK, tek bir anahtar kelime argümanıyla hedefleri değiştirir:

import os
from openai import OpenAI

def get_client():
    if os.getenv("ENV") == "local":
        return OpenAI(
            base_url="http://localhost:11434/v1",
            api_key="ollama",
        )
    return OpenAI(api_key=os.environ["OPENAI_API_KEY"])

client = get_client()
response = client.chat.completions.create(
    model=os.getenv("MODEL", "llama3.3:70b-instruct-q4_K_M"),
    messages=[
        {"role": "system", "content": "Sadece JSON yanıtlayan bir asistansın."},
        {"role": "user", "content": "{\"status\": \"ok\"} döndür."},
    ],
    response_format={"type": "json_object"},
)
print(response.choices[0].message.content)

JavaScript şekli bunu yansıtır:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.ENV === "local"
    ? "http://localhost:11434/v1"
    : "https://api.openai.com/v1",
  apiKey: process.env.ENV === "local" ? "ollama" : process.env.OPENAI_API_KEY,
});

const resp = await client.chat.completions.create({
  model: process.env.MODEL || "llama3.3:70b-instruct-q4_K_M",
  messages: [{ role: "user", content: "Merhaba de." }],
});
console.log(resp.choices[0].message.content);

Apidog'un senaryo çalıştırıcısını, projeyi bir `apidog-cli` koleksiyonu olarak dışa aktararak ve GitHub Actions'da `apidog run` çağrısı yaparak CI'nize bağlayın. Çalıştırıcı, doğrulama hatasında sıfır olmayan bir çıkış kodu döndürür, bu da yerel veya barındırılan bir sözleşme değiştiği anda derlemeyi başarısız kılar. QA mühendisleri, aynı akışı mevcut API test boru hatlarına bağlayabilir.

Gelişmiş teknikler ve profesyonel ipuçları

Niceleme, 70B bir modelin dizüstü bilgisayarınıza sığıp sığmayacağını belirleyen kaldıraçtır. GGUF formatı, ağırlıkları parametre başına 8, 6, 5, 4, 3 veya 2 bit olarak saklar. Q4_K_M bir nedenden dolayı varsayılandır. MMLU kıyaslama testinde FP16'ya göre %0,6 puan kaybeder ve 70B bir modeli 140 GB'tan 40 GB'a küçültür. Q8 sizi FP16'dan %0,1 puan içinde tutar ancak disk ve RAM ayak izini iki katına çıkarır. Q2_K alanı tasarrufu sağlar ancak uzun bağlamlı herhangi bir görevde karmaşıklık isabeti görülebilir. Sohbet için Q4_K_M'yi, kod üretimi için Q8'i ve RAM'iniz varsa ve bir güvenlik marjı istiyorsanız Q5_K_M'yi seçin.

llama.cpp'deki `-ngl` bayrağı veya Ollama'daki `num_gpu` seçeneği aracılığıyla GPU dışı yükleme, GPU'da kaç dönüştürücü katmanının bulunduğunu kontrol eder. VRAM'iniz izin verdiği kadar yüksek ayarlayın. CPU'ya geri dönen her katman, verimi yaklaşık yüzde 30 düşürür. 24 GB'lık bir kartta 70B Q4 modeli 80 katmanın 40'ına sığar. 48 GB'ta tüm yığını sığdırabilirsiniz.

Bellek eşleme (`mmap`), llama.cpp ve Ollama'da varsayılan olarak açıktır. Başlangıçta tam modeli tahsis etmek yerine, işletim sisteminin ağırlıkları talep üzerine sayfalara ayırmasına izin verir. Katı bellek sınırları olan bir kapsayıcıda çalışmadığınız sürece açık bırakın. `mmap` kapalıyken ilk token gecikmesi yaklaşık 200 ms düşer ancak RAM kullanımı iki katına çıkar.

Toplu işlem, vLLM'nin süper gücüdür. 32 eşzamanlı istek gönderin ve vLLM bunları tek bir GPU geçişinde gruplandırır. Verim, GPU'nun hesaplama tavanına yakın doğrusal olarak ölçeklenir. Paylaşılan CPU belleğine sahip dizüstü bilgisayarlar için `--max-num-seqs 64` ve H100 sınıfı donanım için `--max-num-seqs 256` ayarlayın.

Akışlı yanıtlar, algılanan gecikmeyi yarıya indirir. OpenAI SDK'sında `stream=True` olarak ayarlayın ve sunucu token'ları üretilirken boşaltır. İlk bayt, tamamlama için beklemek yerine 200 ila 500 ms içinde gelir. Bu kılavuzdaki her çalışma zamanı bunu destekler.

Ollama'nın Modelfile'ı, sistem istemi, sıcaklık ve durma dizilerini adlandırılmış bir modele yerleştirmenizi sağlar, böylece uygulama kodunuz temiz kalır. `ollama create my-assistant -f Modelfile` komutunu bir kez çalıştırın ve istemciniz her istekte sistem istemini tekrarlamak yerine `my-assistant`'ı işaret eder.

Yaygın hatalar

• Üretim kodunda `http://localhost:11434` değerini sabit kodlamak. Bir ortam değişkeni kullanın.
• Yerel modellerin `max_tokens`'ı zorunlu kılmadığını unutmak. Mutlulukla 4.096 token'lık bir saçmalık üreteceklerdir. Bir durma dizisi ayarlayın.
• Ollama ve başka bir çalışma zamanını aynı bağlantı noktasında çalıştırmak. Her ikisi de varsayılan olarak temiz bağlantı noktalarına sahiptir, ancak özel bağlantı noktaları sessizce çakışır.
• `Authorization` başlığını atlamak. Ollama bunu yoksayar, ancak `--api-key` ile vLLM, kimliği doğrulanmamış istekleri 401 ile reddedecektir.
• Bir Q4 modeli yükleyip matematikte GPT-5.5 kalitesi beklemek. Niceleme, muhakemeyi en hızlı şekilde aşındırır.

Yerel ve barındırılan: maliyet ve gecikme matematiği

Aşağıdaki sayılar, yerel için 128 GB birleşik belleğe sahip bir M3 Max ve barındırılan uç noktalar için mevcut genel fiyatlandırmayı varsaymaktadır. İlk token'a kadar geçen süre (TTFT), toplu işlem olmadan, 1.024 token'lık bir istemde soğuk olarak ölçülür.

Barındırılan sütun, gecikmede her zaman kazanır. Yerel sütun, günde yaklaşık 10 milyon token'ı aştığınız anda maliyette kazanır ve ilk istekten itibaren gizlilikte kazanır. Geliştirme için neredeyse her zaman yerel istersiniz. Kullanıcıya yönelik üretim için ise, veri sınıflandırmanız bunu yasaklamadığı sürece neredeyse her zaman barındırılan istersiniz.

Pratik bir desen: iç geliştirme döngüsü sırasında yerel olarak çalışın, aşamada barındırılan olana geçin, CI'da her iki hedefi de yeşil tutun. Yukarıdaki bölümdeki Apidog senaryo testleri, tek bir ortam geçişiyle bu deseni destekler. Bireysel modeller üzerinde daha derin karşılaştırmalar için DeepSeek V4 yerel olarak nasıl çalıştırılır ve orijinal DeepSeek V4 kullanım kılavuzuna bakın.

Gerçek dünya kullanım örnekleri

Singapur'daki bir fintech uyumluluk ekibi, mühendislerin dizüstü bilgisayarlarında Ollama kullanarak şüpheli faaliyet raporları taslağı hazırlıyor. İstemler, MAS kuralları uyarınca ülke dışına çıkamayacak hesap numaraları ve işlem desenleri içeriyor. Üretimde kullandıkları barındırılan uç nokta, aynı istemin düzenlenmiş bir sürümünü alıyor. Apidog senaryoları, düzenleyicinin localhost'tan ayrılmadan önce her istekte çalıştığını doğruluyor.

Stockholm'deki bir oyun stüdyosu, yerel bir Qwen 3.6 örneğiyle tasarım stajyerlerine istem mühendisliği eğitimi veriyor. Ücretsiz, çevrimdışı ve bir sonraki oyunun hikayesini üçüncü bir tarafa sızdırması imkansız. Aynı proje, tek bir ortam değişkeni değişikliğiyle üretimde Gemini 3 Flash'a karşı gönderiliyor. Üretim bağlantısı için Gemini 3 Flash API kılavuzunu yeniden kullanıyorlar.

Bir sağlık girişimi, müşterinin hastane ağı içinde kiralık bir A100 üzerinde vLLM çalıştırıyor. Uç nokta asla genel DNS'i görmüyor. Entegrasyon testleri, aynı VLAN'daki bir Jenkins aracısından, yerel olarak kullandıkları aynı OpenAI SDK'sına karşı çalışıyor. Aynı kod, üç dağıtım hedefi, tek bir senaryo paketi.

Sonuç

Yerel LLM API yığını hızla olgunlaştı. İstemcinizi, testlerinizi veya CI'nizi yeniden yazmadan istemlerinizi barındırılan bir uç noktadan taşıyabilirsiniz. Bunu gerçeğe dönüştüren beş adım:

• Dizüstü bilgisayarlar için Ollama'yı, paylaşılan geliştirme kümeleri için vLLM'yi, dar bellek bütçeleri için llama.cpp'yi seçin.
• OpenAI uyumlu uç noktayı açığa çıkarın ve tek satırlık bir curl ile doğrulayın.
• `base_url` ve `api_key`'yi ortam değişkenlerine taşıyın, böylece aynı kod yerel ve barındırılanı vurur.
• Her iki ortamda da aynı şekilde çalışan Apidog'da senaryo testleri oluşturun.
• Maliyet-gecikme tablosunu izleyin ve iş yükü başına doğru hedefi seçin.

HN'in "Yerel Yapay Zeka norm olmalı" sinyalini 1.700 puanın üzerine iten şey, bu olgunluğun bir sonucudur. API yüzeyi istikrar kazandıktan sonra, her geliştirme aracı buna uyum sağladı. Apidog'u indirin ve döngünün ne kadar hızlı kapandığını görmek için bir ortamı `http://localhost:11434/v1` adresine yönlendirin. Henüz bir model seçmediyseniz, En İyi Yerel LLM'ler 2026 ile başlayın ve bu uç noktalardan herhangi birinin üzerinde ajans tabanlı akışları test etme konusunda daha derinlemesine bilgi edinmek isterseniz, Yapay Zeka Ajanları API'si Nasıl Test Edilir başlıklı yazıyı okuyun.