Ollama Python Kitaplığı: LLM’lere Yerelde Başlarken

Bulut LLM API’leri güçlüdür, ancak kullanım başına fiyatlandırma, hız sınırları ve verilerinizin nerede işlendiğine dair belirsizlik gibi ödünler içerir. Hassas verilerle çalışan veya yoğun denemeler yapan geliştiriciler için bu kısıtlar hızla sürtünme yaratabilir.

İşte bu noktada yerel-öncelikli yaklaşımlar öne çıkar. Ollama Python kitaplığı, büyük dil modellerini yerelde çalıştırmanıza ve onlarla temiz, Python’a özgü kodla etkileşime girmenize olanak tanıyarak bu sürtünmeyi ortadan kaldırır. Böylece performans, maliyet ve gizlilik üzerinde tam kontrol sağlarsınız.

Bu yazıda, generate() ile basit metin üretiminden araç çağırma ve görsel modellere kadar eksiksiz Ollama Python kitaplığı API’sini adım adım anlatacağım.

Ayrıca en yeni Ollama eğitimlerimize de göz atmanızı öneririm:

• Gemma 4 Eğitimi: Gradio ve Ollama ile Yerel Bir Yapay Zekâ Kodlama Aracısı Oluşturma
• Qwen 3.5 Küçük Modeller Eğitimi: Ollama ile Video’dan Oyuna Üretici
• OpenClaw’ı Ollama ile Kullanma: Yerel Bir Veri Analisti Oluşturma
• Claude Code’u Ollama Yerel Modelleriyle Kullanma

Python ile Ollama’yı Çalıştırmak İçin Önkoşullar

Başlamadan önce, cihazınızda aşağıdaki kurulumun olduğundan emin olun:

• Python 3.8 veya üzeri

• Ollama’nın web sitesinden indirilip kurulmuş ve çalışır durumda olması (ollama serve)

• En az bir modelin çekilmiş olması (ör. ollama pull llama3.2)

Bu önkoşullar önemlidir çünkü Python SDK’sı yalnızca bir istemcidir; gerçek çıkarım Ollama çalışma zamanında gerçekleşir. Çalışma zamanı kullanılamazsa veya uygun bir model yoksa çağrılar başarısız olur.

Sürüm tutarlılığı için Docker ile Ollama kullanmayı da düşünebilirsiniz.

Ollama Python Kitaplığı Nedir?

Ollama Python kitaplığı, Ollama REST API’sini basit ve Pythonik bir arayüze saran resmi SDK’dır. Başka bir deyişle, düşük seviyeli HTTP isteklerini ve JSON yüklerini yüksek seviyeli Python fonksiyonlarına dönüştürerek aktarım ayrıntıları yerine amaca odaklanmanızı sağlar.

Uygulamanız büyüdükçe bu soyutlama tekrarlayan istek oluşturmayı ortadan kaldırır, yanıtların nasıl işlendiğini standartlaştırır ve hata yönetimini tek bir yerde merkezileştirir.

Karşılaştırma için, ham bir istek şu şekilde görünebilir:

import requests

response = requests.post(
    "http://localhost:11434/api/generate",
    json={
        "model": "llama3.2",
        "prompt": "Explain recursion"
    }
)

Bu çalışır, ancak hızla ayrıntılı ve hataya açık hale gelir. SDK ile aynı görev şu şekle dönüşür:

import ollama

response = ollama.generate(
    model='llama3.2',
    prompt='Explain recursion'
)

Kitaplığın Ollama sunucusuyla nasıl iletişim kurduğu

Arka planda, her SDK çağrısı http://localhost:11434 adresindeki Ollama sunucusuna bir HTTP isteğine dönüşür. Python betiğiniz bir istemci gibi davranırken Ollama çalışma zamanı, modelleri barındıran ve yürüten bir sunucu görevi görür.

Bu ayrım önemlidir çünkü modeli özel bir hizmet olarak çalıştırmayı sağlar; bu da kaynak yönetimini (CPU/GPU) daha verimli hale getirir ve birden çok uygulamanın aynı model örneğini paylaşmasına imkân tanır.

Farklı bir makineye bağlanmanız gerekirse özel bir istemci yapılandırabilirsiniz:

from ollama import Client

client = Client(host='http://remote-server:11434')
response = client.generate(model='llama3.2', prompt='Hello')

Kitaplığın kurulumu ve yapılandırılması

Kurulum basittir ve minimum bağımlılık gerektirir:

pip install ollama

Kurulumdan sonra, mevcut modelleri listeleyerek bağlantıyı doğrulamak iyi bir uygulamadır. 

Bu, Python ortamınızın, SDK’nın ve Ollama çalışma zamanının doğru şekilde birbirine bağlı olduğunu teyit etmenize yardımcı olur.

Bunu yapmak için şu komutu çalıştırın:

import ollama

print(ollama.list())

generate() ile Metin Üretimi

generate() fonksiyonu durumsuz görevler için tasarlanmıştır; yani her istek, önceki etkileşimlere dair herhangi bir bellek olmadan bağımsız şekilde ele alınır. Bu da özetleme, yeniden yazma veya kod üretimi gibi görevler için idealdir.

Bağlam tutulmadığından, çıktı kalitesi tamamen istemin ne kadar açık yazıldığına bağlıdır.

Temel metin üretimi

Aşağıdaki örnek en basit iş akışını gösterir: bir istem gönderin, bir yanıt alın ve üretilen metni çıkarın.

import ollama

response = ollama.generate(
    model='llama3.2',
    prompt='Write a Python docstring for a function that calculates factorial'
)

print(response['response'])

Yanıtta ayrıca yürütme süresi ve token sayıları gibi meta veriler de bulunur; bunlar performansı optimize ederken faydalıdır.

Parametrelerle çıktıyı özelleştirme

Üretim davranışı, modelin token seçimini nasıl yaptığına yön veren örnekleme parametreleriyle ayarlanabilir.

Daha düşük temperature değerleri daha belirleyici çıktılar üretirken, daha yüksek değerler daha fazla değişkenlik katar. top_p ve num_predict gibi parametreleri kullanarak çıktı çeşitliliğini ve uzunluğunu daha da hassaslaştırabilirsiniz.

Kullanabileceğiniz bazı önemli parametreler şunlardır: 

İşte top_p, temperature ve num_predict parametrelerinin kullanımına bir örnek:

response = ollama.generate(
    model='llama3.2',
    prompt='Explain machine learning in one paragraph',
    options={
        'temperature': 0.2,
        'top_p': 0.9,
        'num_predict': 100
    }
)

chat() ile Sohbetler Oluşturma

generate()’in aksine, chat() API’si bir mesaj dizisiyle çalışarak durumsal etkileşimleri destekler. Bu, modelin birden çok tur boyunca bağlamı korumasına olanak tanır.

Her mesaj, konuşmayı yapılandırmaya yardımcı olan user, assistant veya system gibi bir role sahiptir.

Tek turlu sohbet istekleri

Tek turlu bir etkileşim bile daha karmaşık sohbetlerin temelini atan mesaj biçimini kullanır.

response = ollama.chat(
    model='llama3.2',
    messages=[
        {'role': 'user', 'content': 'Explain Python decorators'}
    ]
)

print(response['message']['content'])

Çok turlu bağlamı koruma

Bağlamı korumak için, her istekte tam konuşma geçmişini açıkça saklayıp yeniden gönderirsiniz. Bu, modelin neyi “hatırladığını” tamamen sizin kontrolünüze verir.

messages = [
    {'role': 'user', 'content': 'What is recursion?'}
]

response = ollama.chat(model='llama3.2', messages=messages)
messages.append(response['message'])

messages.append({'role': 'user', 'content': 'Give an example in Python'})
response = ollama.chat(model='llama3.2', messages=messages)

Davranışı şekillendirmek için sistem istemlerini kullanma

Bir sistem istemi, ton, kısıtlar veya rol gibi modelin davranışını baştan tanımlamak için kullanılır.

messages = [
    {'role': 'system', 'content': 'You are a strict Python code reviewer.'},
    {'role': 'user', 'content': 'Review this code: def add(a,b): return a+b'}
]

Ollama Python Kitaplığında Akış ve Async Desteği

Etkileşimli uygulamalarda, yanıt verebilirlik doğruluk kadar önemlidir. Ollama, performansı ve kullanıcı deneyimini iyileştirmek için hem akış hem de eşzamansız yürütmeyi destekler.

Gerçek zamanlı akış yanıtları

Akış, tam yanıtı beklemek yerine üretildikçe çıktıyı aşamalı olarak işlemenizi sağlar.

for chunk in ollama.chat(
    model='llama3.2',
    messages=[{'role': 'user', 'content': 'Write a story'}],
    stream=True
):
    print(chunk['message']['content'], end='', flush=True)

Async uygulamalar için AsyncClient kullanma

Eşzamansız yürütme, uygulamanızın engellemeden aynı anda birden fazla isteği işlemesine olanak tanır. Bunu uygulamak için asyncio Python kitaplığını kullanmanız gerekir.

Aşağıdaki örneğe bakalım:

import asyncio
from ollama import AsyncClient

async def main():
    client = AsyncClient()
    async for chunk in await client.chat(
        model='llama3.2',
        messages=[{'role': 'user', 'content': 'Explain async programming'}],
        stream=True
    ):
        print(chunk['message']['content'], end='')

asyncio.run(main())

Python’dan Ollama Modellerini Yönetme

Ollama SDK’sı, özellikle otomatikleştirilmiş ortamlarda kullanışlı olan, modelleri programatik olarak yönetmek için araçlar da sağlar.

Yerel modelleri listeleme ve inceleme

Kullanılabilir modellerin listesini alabilir ve boyut ile yapılandırma gibi özelliklerini inceleyebilirsiniz.

models = ollama.list()
print(models)

info = ollama.show('llama3.2')
print(info)

Modelleri programatik olarak çekme ve silme

Modeller Python içinden indirilebilir veya kaldırılabilir; bu da bağımlılıkları dinamik olarak yönetmeyi kolaylaştırır.

ollama.pull('llama3.2')
ollama.delete('llama3.2')

Ollama Python Kitaplığı ile Gömme Vektörleri (Embeddings) Üretme ve Kullanma

Gömme vektörleri, metni anlamsal içeriği yakalayan sayısal vektörler olarak temsil eder. Bu sayede metinleri birebir ifadeden ziyade benzerliğe göre karşılaştırabilirsiniz.

Metin gömme vektörleri oluşturma

Aşağıdaki örnek, arama veya kümeleme için kullanılabilecek bir vektör gösterimine dönüştürür.

response = ollama.embed(
    model='nomic-embed-text',
    input='Ollama is a local LLM runtime'
)

embedding = response['embeddings'][0]

Basit bir benzerlik araması oluşturma

Gömme vektörleri üretildikten sonra, benzerlik vektörler arasındaki açıyı karşılaştıran kosinüs benzerliği ile ölçülebilir.

İşte arama fonksiyonunun basit bir örneği:

import numpy as np

def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

Ollama Python Kitaplığında Araç Çağırma ve Yapılandırılmış Çıktı

Daha gelişmiş uygulamalar oluşturmak için modellerin sıklıkla harici fonksiyonlarla etkileşime geçmesi veya yapılandırılmış veri döndürmesi gerekir.

Python fonksiyonlarıyla araç çağırmayı uygulama

Araç çağırma, modelin kullanıcı niyetine göre önceden tanımlı Python fonksiyonlarını çağırmasına olanak tanır.

Böyle araçları kullanan bir fonksiyon oluşturalım:

def get_weather(city: str) -> str:
    """Get current weather for a city"""
    return f"Weather in {city} is sunny"
response = ollama.chat(
    model='llama3.2',
    messages=[{'role': 'user', 'content': 'What is the weather in Paris?'}],
    tools=[get_weather]
)

Yapılandırılmış JSON yanıtları alma

Yapılandırılmış çıktılar, yanıtların JSON gibi tutarlı ve makine tarafından okunabilir bir biçimde döndürülmesini sağlar.

response = ollama.chat(
    model='llama3.2',
    messages=[{'role': 'user', 'content': 'Review: Great product, 5 stars!'}],
    format='json'
)

İleri Düzey: Python’da Görsel Modeller ve Ollama Cloud

Ollama, daha gelişmiş kullanım senaryoları için çoklu modaliteye sahip modelleri ve bulut tabanlı çıkarımı destekler.

Görsel modellere görsel gönderme

Görsel modeller hem metni hem görselleri işleyebilir; bu da görsel betimleme ve görsel analiz gibi görevleri mümkün kılar.

response = ollama.chat(
    model='llama3.2-vision',
    messages=[{
        'role': 'user',
        'content': 'Describe this image',
        'images': ['image.jpg']
    }]
)

Bulut modellerini Python’dan çalıştırma

Yerelde çalışamayacak kadar büyük modeller için Ollama Cloud barındırılan çıkarım sunar. Ollama Cloud’a giriş yapmanız gerekir.

ollama signin

Oturum açtıktan sonra, bulutta barındırılan modellerle şu şekilde sohbet edebilirsiniz:

from ollama import Client
import os

ollama.chat(model='deepseek-v3.1:671b-cloud', messages=[...])

client = Client(
    host='https://ollama.com',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

En Yaygın Ollama Python Tuzaklarında Hata Yönetimi

Gerçek uygulamalar geliştirirken hataları açıkça ele almak sessiz hataları önlemeye yardımcı olur ve güvenilirliği artırır.

ResponseError istisnalarını ele alma

Ollama SDK’sı sunucu tarafı hataları için yapılandırılmış istisnalar yükseltir; bu da neyin ters gittiğini incelemenize olanak tanır.

import ollama

try:
    ollama.generate(model='unknown', prompt='test')
except ollama.ResponseError as e:
    print(e.status_code, e.error)

Bağlantı ve model sorunlarını hata ayıklama

Yaygın sorunlar arasında sunucunun çalışmaması, modellerin eksik olması, yetersiz bellek veya bağlam sınırlarının aşılması yer alır.

• Sunucu çalışmıyor: ollama serve ile başlatın

• Model bulunamadı: ollama pull çalıştırın

• Bellek yetersiz: Daha küçük modeller kullanın veya kuantizasyon uygulayın

• Bağlam sorunları: num_ctx değerini ayarlayın

num_ctx, modelin aynı anda “görebileceği” azami token sayısını kontrol eder; buna şunlar dahildir:

• isteminiz
• sistem talimatları
• sohbet geçmişi
• getirilen belgeler (RAG)
• ve modelin kendi oluşturduğu tokenlar 

Bu parametreyi yönetmek, LLM’in önceki içeriği (genellikle baştan) kesmesini veya önemli talimatları ya da verileri sessizce kaybetmesini önlemeye yardımcı olur.

Son Düşünceler

Ollama Python kitaplığı, basit metin üretiminden gömme vektörleri, araç çağırma ve çoklu modal girdiler gibi gelişmiş yeteneklere kadar yerel ve bulut LLM’lerle çalışmak için eksiksiz bir arayüz sunar. LLM’ler, yığınınızdaki diğer bileşenler gibi betik yazabileceğiniz, test edebileceğiniz ve ölçekleyebileceğiniz yerel bir hizmete dönüşür.

Ollama’yı kullanma deneyimlerimde, bulut LLM’leri kullanmak zorunda kalmadan elde bulundurulması iyi bir seçenek olduğunu hissettim. Örneğin, açık kaynak modelleri daha özgürce kullanabiliyorum. Siz de modeller arasında geçiş için daha fazla seçenek arıyorsanız, Ollama bunlara erişmek için iyi bir kapı aralıyor.

Becerilerinizi derinleştirmek isterseniz, Developing LLM Applications with LangChain kursumuzu almanızı veya Associate AI Engineer for Developers sertifikasını takip etmenizi öneririm.