Yerel LLM'leri API Olarak Kullanma Rehberi

Dizüstü bilgisayarınız, OpenAI uyumlu bir uç noktanın arkasında 70B parametreli yerel bir modele hizmet edebilir. Uygulama kodunda çoğu zaman yalnızca base_url değişir; istemci, istek gövdesi ve test akışı aynı kalır. Bu yaklaşım çevrimdışı geliştirme, token başına sıfıra yakın çalışma maliyeti ve düzenlenmiş veriler için yerel bir yürütme yolu sağlar. Aşağıda Ollama, vLLM ve llama.cpp ile yerel LLM API kurulumunu, istemciyi bu API’ye yönlendirmeyi ve aynı akışı Apidog ile test etmeyi adım adım uygulayacağız.

Apidog'u bugün deneyin

TL;DR

Yerel bir LLM API’si çalıştırmak için en pratik seçenekler:

• Ollama: Dizüstü bilgisayar ve tek geliştirici akışları için en kolay başlangıç.
• vLLM: GPU’lu geliştirme kümeleri ve yüksek eşzamanlılık için uygun.
• llama.cpp: GGUF, düşük bellek bütçesi ve donanım kontrolü için esnek seçenek.

OpenAI uyumlu bir istemcide hedefi değiştirmek çoğu zaman şu kadar basittir:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",
)

Böylece aynı kod yerelde Llama 3.3, DeepSeek V4 veya Qwen 3.6 gibi modelleri çağırabilir. Apidog’da BASE_URL ve API_KEY değişkenleriyle yerel ve barındırılan ortamları aynı test senaryosunda çalıştırabilirsiniz.

Giriş

Yerel LLM API yığını kısa sürede araştırma denemelerinden günlük geliştirme ortamına dönüştü. Apple, M3 Max üzerinde 128 GB birleşik bellek sundu. Ollama haftalık büyük indirme hacimlerine ulaştı. vLLM, GitHub’da geniş bir kullanıcı tabanı kazandı.

API geliştiricileri açısından asıl kırılma noktası şu: büyük çalışma zamanlarının çoğu artık OpenAI’nin /v1/chat/completions biçimini destekliyor. Yani iki ayrı istemci yolu yazmanız gerekmez. Aynı SDK çağrısı, yalnızca ortam değişkenine göre localhost veya api.openai.com adresine gider.

Apidog’daki mevcut istek şablonlarınız https://api.openai.com/v1/chat/completions adresini işaret ediyorsa, temel URL değişkenini değiştirip aynı JSON sözleşmesini yerel model üzerinde doğrulayabilirsiniz. Yeni şema, yeni kimlik doğrulama akışı veya ayrı test projesi gerekmez. Zaten özellik başına API harcamasını takip ediyorsanız, yerel modeli barındırılan modelle karşılaştırıp gecikme ve maliyet farkını aynı test akışında ölçebilirsiniz.

Bu rehberde şunları kuracağız:

1. Yerel çalışma zamanı seçimi
2. OpenAI uyumlu uç noktanın açılması
3. Python ve JavaScript istemcilerinin yapılandırılması
4. Apidog ile yerel/barındırılan ortam testleri
5. Niceleme, GPU dışı yükleme ve yaygın hatalar
6. Maliyet-gecikme karşılaştırması

Daha geniş model seçenekleri için En İyi Yerel LLM'ler 2026 rehberine bakabilirsiniz.

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

Bir LLM çağıran uygulama geliştiriyorsanız, yalnızca üretim ortamında değil, uçakta, konferans Wi-Fi’ında veya *.openai.com trafiğini engelleyen müşteri ağlarında da hata ayıklamanız gerekir. Yerel LLM API’si, ağ bağımlılığı olmadan üretime benzer bir geliştirme hedefi sağlar.

Başlıca kazanımlar:

• Gizlilik: Hasta notları, sözleşmeler, hesap hareketleri veya hassas müşteri verileri makineden çıkmadan işlenebilir.
• Maliyet kontrolü: Geliştirme ve regresyon testlerinde token maliyeti azaltılır.
• Tekrarlanabilirlik: Yerel model dosyası sabittir; barındırılan model sürümleri gibi sessizce değişmez.
• Mevcut araçlarla uyumluluk: OpenAI uyumlu API sayesinde SDK, test aracı ve CI akışı aynı kalır.

Yerel model, her üretim iş yükü için doğru cevap değildir. Kullanıcıya açık düşük gecikmeli ürünlerde barındırılan model daha mantıklı olabilir. Ancak geliştirme, test, veri gizliliği ve offline akışlar için yerel uç nokta güçlü bir alternatiftir.

OpenAI uyumlu uç nokta sunan çalışma zamanları

Yerel LLM çalıştırmak için çalışma zamanını kullanım senaryosuna göre seçin.

Çalışma zamanı	En uygun kullanım	Varsayılan API
Ollama	Dizüstü bilgisayar, demo, tek geliştirici	http://localhost:11434/v1
vLLM	GPU kümesi, yüksek verim, eşzamanlı istekler	http://localhost:8000/v1
llama.cpp	GGUF, düşük bellek, donanım kontrolü	Yapılandırılabilir port

Ollama ile yerel LLM API kurma

Ollama, en hızlı başlangıç seçeneğidir. Tek bir CLI ile model indirir, çalıştırır ve OpenAI uyumlu HTTP sunucusu açar.

macOS üzerinde kurulum:

brew install ollama
ollama serve &
ollama pull llama3.3:70b-instruct-q4_K_M
ollama run llama3.3:70b-instruct-q4_K_M

Sunucu çalıştıktan sonra OpenAI uyumlu temel URL:

http://localhost:11434/v1

Hızlı doğrulama için:

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ollama" \
  -d '{
    "model": "llama3.3:70b-instruct-q4_K_M",
    "messages": [
      { "role": "user", "content": "Sadece OK kelimesiyle yanıtla." }
    ]
  }'

Ollama; tek kullanıcılı geliştirme, demolar ve CI duman testleri için iyi bir varsayılandır.

vLLM ile yüksek verimli yerel API kurma

vLLM, üretim düzeyinde verim için tasarlanmıştır. PagedAttention ve sürekli toplu işlem sayesinde eşzamanlı isteklerde basit çalıştırıcılardan daha yüksek throughput sağlayabilir.

Kurulum ve servis başlatma:

pip install vllm

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

Temel URL:

http://localhost:8000/v1

vLLM, CUDA GPU veya desteklenen AMD ROCm kartları gerektirir. Apple Silicon dizüstüler için doğru seçim değildir; paylaşılan geliştirme kümeleri ve yüksek eşzamanlı test ortamları için uygundur.

llama.cpp ile GGUF model sunma

llama.cpp, GGUF ekosistemindeki en esnek çalışma zamanlarından biridir. Raspberry Pi’den çoklu GPU makinelerine kadar geniş donanım aralığında çalışabilir.

Metal destekli macOS derlemesi ve sunucu başlatma:

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

Burada:

• -m: GGUF model dosyası
• --port: HTTP portu
• -c: bağlam uzunluğu
• -ngl: GPU’ya aktarılacak katman sayısı

-ngl 99, mümkün olduğunca çok katmanı GPU’ya taşımayı hedefler. VRAM yetersizse bu değeri düşürmeniz gerekir.

llama.cpp, özellikle şu durumlarda uygundur:

• Modeli sınırlı VRAM’e sığdırmanız gerekiyorsa
• GGUF niceleme seviyelerini doğrudan kontrol etmek istiyorsanız
• Egzotik veya düşük güçlü donanım üzerinde test yapıyorsanız

LM Studio ve Jan gibi araçlar da llama.cpp’yi GUI ile sarar ve yapılandırılabilir portta OpenAI uyumlu endpoint sunar. Terminal kullanmak istemeyen ekip üyeleri için pratik olabilir.

Uç noktanın çalıştığını Python ile doğrulayın

Ollama örneği için minimum test:

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)

OK görüyorsanız şu üç şey eşleşmiştir:

1. Çalışma zamanı aktif
2. Port doğru
3. OpenAI SDK sözleşmesi çalışıyor

Artık aynı endpoint’i test aracınıza ve uygulama kodunuza bağlayabilirsiniz.

Yerel LLM’nizi Apidog ile test edin

Yerel API’nin faydalı olması için üretimde kullandığınız test akışıyla aynı şekilde çağrılabilmesi gerekir. Apidog’da bunu ortam değişkenleriyle çözebilirsiniz.

1. Local ortamı oluşturun

Apidog projenizde yeni bir ortam oluşturun:

Ortam adı: Local
BASE_URL: http://localhost:11434/v1
API_KEY: ollama

2. Production ortamını oluşturun

Mevcut OpenAI ortamınızı klonlayın veya yeni bir ortam oluşturun:

Ortam adı: Production
BASE_URL: https://api.openai.com/v1
API_KEY: <barındırılan API anahtarınız>

3. İstek URL’sini değişkenleştirin

Sabit URL yerine:

https://api.openai.com/v1/chat/completions

şunu kullanın:

{{BASE_URL}}/chat/completions

Authorization başlığını da değişkenleştirin:

Authorization: Bearer {{API_KEY}}

4. Örnek istek gövdesi ekleyin

{
  "model": "llama3.3:70b-instruct-q4_K_M",
  "messages": [
    {
      "role": "system",
      "content": "Kısa ve teknik yanıt veren bir asistansın."
    },
    {
      "role": "user",
      "content": "Sadece OK kelimesiyle yanıtla."
    }
  ],
  "temperature": 0
}

Production ortamında model adını barındırılan sağlayıcınıza göre değiştirmeniz gerekebilir.

5. Senaryo testi oluşturun

Apidog’da aynı isteği kullanan bir senaryo testi oluşturun ve şu doğrulamaları ekleyin:

• choices[0].message.role == "assistant"
• choices[0].message.content boş değil
• usage.total_tokens > 0

Bu senaryoyu önce Local, sonra Production ortamında çalıştırın. İki ortamda da sözleşme doğrulanıyorsa, uygulama tarafında endpoint değiştirmek güvenli hale gelir.

Aynı desen, çok adımlı API’leri çağıran yapay zeka ajanlarını test etmeye de uygulanabilir.

Uygulama kodunda ortam bazlı istemci seçimi

Python tarafında hedefi tek fonksiyonla seçebilirsiniz:

import os
from openai import OpenAI

def get_client():
    if os.getenv("ENV") == "local":
        return OpenAI(
            base_url=os.getenv("LOCAL_LLM_BASE_URL", "http://localhost:11434/v1"),
            api_key=os.getenv("LOCAL_LLM_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)

Çalıştırma:

ENV=local \
MODEL=llama3.3:70b-instruct-q4_K_M \
python app.py

Production için:

ENV=production \
OPENAI_API_KEY=sk-... \
MODEL=<production-model> \
python app.py

JavaScript istemcisi

Node.js tarafında aynı yaklaşım:

import OpenAI from "openai";

const isLocal = process.env.ENV === "local";

const client = new OpenAI({
  baseURL: isLocal
    ? process.env.LOCAL_LLM_BASE_URL || "http://localhost:11434/v1"
    : "https://api.openai.com/v1",
  apiKey: isLocal
    ? process.env.LOCAL_LLM_API_KEY || "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);

Bu yapı sayesinde kodda sağlayıcıya özel dallanma azaltılır. Hedef yalnızca ortam değişkenleriyle değişir.

CI akışına bağlama

Yerel ve barındırılan sözleşmenin bozulmadığını CI’da da doğrulamak isteyebilirsiniz.

Pratik desen:

1. Apidog’da koleksiyon/senaryo oluşturun.
2. Local ve Production ortamlarını tanımlayın.
3. Koleksiyonu CLI ile çalıştırılabilir hale getirin.
4. GitHub Actions veya Jenkins içinde senaryoyu çalıştırın.
5. Doğrulama hatasında build’i başarısız yapın.

Örnek GitHub Actions akışı:

name: API contract tests

on:
  pull_request:
  push:
    branches: [main]

jobs:
  api-tests:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Run Apidog scenarios
        run: |
          apidog run ./apidog-collection.json --env Production

QA ekipleri aynı yaklaşımı mevcut API test boru hatlarına bağlayabilir.

Gelişmiş teknikler ve profesyonel ipuçları

Niceleme seviyesini doğru seçin

Niceleme, büyük bir modeli dizüstü bilgisayara sığdıran ana kaldıraçtır. GGUF formatı ağırlıkları farklı bit seviyelerinde saklayabilir.

Pratik seçim tablosu:

Seviye	Kullanım
Q8	Daha yüksek kalite, daha fazla RAM/VRAM
Q5_K_M	Kalite ve bellek arasında güvenli denge
Q4_K_M	Sohbet ve genel geliştirme için iyi varsayılan
Q2_K	Maksimum bellek tasarrufu, kalite riski daha yüksek

Sohbet ve genel test için Q4_K_M genellikle iyi başlangıçtır. Kod üretimi veya muhakeme gerektiren işlerde daha yüksek bit seviyeleri tercih edilebilir.

GPU dışı yüklemeyi ayarlayın

llama.cpp’de -ngl, Ollama’da ilgili GPU seçenekleri kaç katmanın GPU’ya taşınacağını belirler.

Genel kural:

• VRAM izin verdiği kadar çok katmanı GPU’ya taşıyın.
• CPU’ya dönen her katman throughput’u düşürür.
• Bellek hatası alırsanız -ngl değerini azaltın.

Örnek:

./llama-server -m model.gguf -ngl 40

mmap’i açık bırakın

llama.cpp ve Ollama’da bellek eşleme (mmap) varsayılan olarak açıktır. Modelin tamamını başlangıçta RAM’e almak yerine işletim sisteminin sayfalama yapmasına izin verir.

Genellikle açık bırakın. Sadece katı bellek sınırları olan container ortamlarında ayrıca test edin.

vLLM’de toplu işlemden yararlanın

vLLM’nin güçlü olduğu alan eşzamanlı isteklerdir. Birden çok isteği GPU üzerinde gruplandırarak throughput’u artırır.

Örnek parametre:

vllm serve meta-llama/Llama-3.3-70B-Instruct \
  --max-num-seqs 64

Daha güçlü donanımlarda bu değer artırılabilir.

Akışlı yanıt kullanın

Algılanan gecikmeyi azaltmak için streaming açın.

Python örneği:

stream = client.chat.completions.create(
    model="llama3.3:70b-instruct-q4_K_M",
    messages=[
        {"role": "user", "content": "Kısa bir açıklama yaz."}
    ],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="")

Kullanıcı arayüzünde ilk token’ın hızlı görünmesi, toplam tamamlama süresi aynı kalsa bile deneyimi iyileştirir.

Ollama Modelfile kullanın

Sistem prompt’unu, sıcaklığı ve durma dizilerini uygulama koduna gömmek yerine Modelfile’a taşıyabilirsiniz.

Örnek Modelfile:

FROM llama3.3:70b-instruct-q4_K_M

SYSTEM """
Kısa, teknik ve JSON uyumlu yanıtlar veren bir asistansın.
"""

PARAMETER temperature 0
PARAMETER stop "<END>"

Model oluşturma:

ollama create my-assistant -f Modelfile

Sonra istemcide:

model="my-assistant"

kullanabilirsiniz.

Yaygın hatalar

Kaçınmanız gereken pratik hatalar:

• Üretim kodunda http://localhost:11434 değerini sabit kodlamak
• base_url ve api_key değerlerini ortam değişkenine taşımamak
• Yerel modelin uzun ve kontrolsüz çıktı üretmesini engellemek için max_tokens veya stop sequence kullanmamak
• Ollama ve başka bir çalışma zamanını aynı portta çalıştırmak
• Authorization başlığını atlamak
• Q4 niceleme ile en yüksek barındırılan model kalitesini beklemek
• Local ve Production ortamlarında farklı test gövdeleri kullanmak

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

Aşağıdaki tablo, yerel için 128 GB birleşik belleğe sahip bir M3 Max ve barındırılan uç noktalar için genel fiyatlandırma varsayımıyla verilmiştir. İlk token’a kadar geçen süre (TTFT), toplu işlem olmadan 1.024 token’lık istemde soğuk ölçüm olarak ele alınmıştır.

Model	Yerel TTFT	Yerel verim	Barındırılan eşdeğeri	Barındırılan fiyat	Barındırılan TTFT
Llama 3.3 70B Q4_K_M	1.2 s	12 token/s	GPT-5.5 Instant	1M başına 5$ / 30$	200 ms
DeepSeek V4 67B Q4_K_M	1.4 s	10 token/s	DeepSeek-Chat barındırılan	1M başına 0.55$ / 2.20$	280 ms
Qwen 3.6 32B Q5_K_M	0.7 s	28 token/s	Qwen-Max barındırılan	1M başına 1.60$ / 6.40$	240 ms
Gemma 4 27B Q4_K_M	0.5 s	35 token/s	Gemini 3 Flash	1M başına 0.35$ / 1.05$	180 ms

Pratik yorum:

• Barındırılan modeller genellikle gecikmede kazanır.
• Yerel modeller geliştirme ve yüksek hacimli testte maliyet avantajı sağlar.
• Gizlilik gereksinimi varsa yerel model ilk tercihe dönüşebilir.
• Kullanıcıya açık üretimde, veri sınıflandırması izin veriyorsa barındırılan model daha uygun olabilir.

İyi bir uygulama deseni:

1. Geliştirme döngüsünde yerel model kullanın.
2. Staging ortamında barındırılan modele geçin.
3. CI’da her iki hedefi de test edin.
4. Apidog’da aynı senaryoyu yalnızca ortam değiştirerek çalıştırın.

Model bazlı daha derin rehberler için DeepSeek V4 yerel olarak nasıl çalıştırılır ve DeepSeek V4 kullanım kılavuzu yazılarına bakabilirsiniz.

Gerçek dünya kullanım örnekleri

Fintech uyumluluk ekibi

Singapur’daki bir fintech uyumluluk ekibi, mühendislerin dizüstü bilgisayarlarında Ollama ile şüpheli faaliyet raporları taslakları oluşturur. İstemler hesap numaraları ve işlem desenleri içerdiği için yerel ortamda kalır. Üretimde aynı istemin düzenlenmiş sürümü barındırılan uç noktaya gönderilir. Apidog senaryoları, düzenleme adımının her istekte çalıştığını doğrular.

Oyun stüdyosu

Stockholm’deki bir oyun stüdyosu, tasarım stajyerlerine yerel Qwen 3.6 örneğiyle prompt mühendisliği eğitimi verir. Akış çevrimdışıdır ve oyun hikayesi üçüncü taraflara gönderilmez. Aynı proje production’da Gemini 3 Flash’a karşı çalışır. Üretim bağlantısı için Gemini 3 Flash API kılavuzunu yeniden kullanırlar.

Sağlık girişimi

Bir sağlık girişimi, müşterinin hastane ağı içinde kiralık A100 üzerinde vLLM çalıştırır. Endpoint genel DNS’e açılmaz. Entegrasyon testleri aynı VLAN’daki Jenkins ajanından, geliştirmede kullanılan OpenAI SDK sözleşmesine karşı çalışır. Aynı kod, üç dağıtım hedefi ve tek senaryo paketiyle yönetilir.

Sonuç

Yerel LLM API yığını artık geliştirme akışına doğrudan eklenebilecek kadar olgun. İstemcinizi, testlerinizi veya CI’nizi baştan yazmadan barındırılan uç noktadan yerel modele geçebilirsiniz.

Uygulanabilir özet:

1. Dizüstü bilgisayar için Ollama, GPU kümesi için vLLM, düşük bellek ve GGUF kontrolü için llama.cpp seçin.
2. OpenAI uyumlu endpoint’i açın.
3. base_url ve api_key değerlerini ortam değişkenlerine taşıyın.
4. Apidog’da Local ve Production ortamları oluşturun.
5. Aynı senaryo testini iki ortamda da çalıştırın.
6. Gecikme, maliyet ve veri sınıflandırmasına göre hedef seçin.

Başlamak için bir ortamı http://localhost:11434/v1 adresine yönlendirin ve aynı isteği Apidog içinde hem yerel hem production hedefte çalıştırın. Henüz model seçmediyseniz En İyi Yerel LLM'ler 2026 ile başlayabilir, ajan tabanlı akışları test etmek için Yapay Zeka Ajanları API'si Nasıl Test Edilir yazısını okuyabilirsiniz.