Ollama Python Kütüphanesi: LLM’leri Yerelde Kullanmaya Başlama

Bulut LLM API’leri güçlüdür, ancak bazı ödünlerle gelir: kullanım başına fiyatlandırma, oran sınırlamaları ve verilerinizin nerede işlendiğine dair sürekli belirsizlik. Hassas verilerle çalışan veya yoğun şekilde deney yapan geliştiriciler için bu kısıtlar hızla sürtünmeye dönüşebilir.

İşte bu noktada yerel-öncelikli yaklaşımlar öne çıkar. Ollama Python kütüphanesi, 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. Bu da performans, maliyet ve gizlilik üzerinde tam denetim sağlar.

Bu yazıda, generate() ile basit metin üretiminden araç çağırma ve görsel modellere kadar Ollama Python kütüphanesi API’sini baştan sona anlatacağım.

Ayrıca diğer güncel Ollama eğitimlerimize de göz atmanızı öneririm:

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

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

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

• Python 3.8 veya üzeri

• Ollama’nın web sitesinden indirilmiş, kurulmuş ve çalışıyor 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 Kütüphanesi Nedir?

Ollama Python kütüphanesi, 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ürür; böylece aktarım ayrıntılarından çok amaca odaklanabilirsiniz.

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

Karşılaştırma için, ham bir istek şöyle 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 uzayıp hata yapmaya açık hale gelir. SDK ile aynı görev şöyle olur:

import ollama

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

Kütüphanenin 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 gibi davranır.

Bu ayrım önemlidir çünkü modelin adanmış bir hizmet olarak çalışmasına olanak tanır; kaynak yönetimini (CPU/GPU) daha verimli kılar ve birden çok uygulamanın aynı model örneğini paylaşmasını sağlar.

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')

Kütüphaneyi kurma ve yapılandırma

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 bağlandığını doğrulamanıza yardımcı olur.

Bunu yapmak için aşağıdakini çalıştırın:

import ollama

print(ollama.list())

generate() Kullanarak Metin Üretme

generate() fonksiyonu, her isteğin önceki etkileşimleri hatırlamadan bağımsız işlendiği durumsuz görevler için tasarlanmıştır. Bu, özetleme, yeniden yazma veya kod üretimi gibi görevler için idealdir.

Bağlam tutulmadığından, çıktı kalitesi tamamen istemin ne kadar net 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ıt ayrıca performans optimizasyonunda yararlı olan yürütme süresi ve token sayıları gibi üst veriler de içerir.

Parametrelerle çıktıyı özelleştirme

Üretim davranışı, modelin token seçimini nasıl yaptığına etki eden örnekleme parametreleri ile ayarlanabilir.

Daha düşük temperature değerleri daha belirleyici çıktılar üretirken, daha yüksek değerler daha fazla çeşitlilik katar. Çıktı çeşitliliğini ve uzunluğunu daha da iyileştirmek için top_p ve num_predict gibi parametreleri kullanabilirsiniz.

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() Kullanarak Sohbetler Oluşturma

generate()’ın aksine, chat() API’si bir mesaj dizisiyle çalışarak durumlu etkileşimleri destekler. Bu, modelin birden fazla 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 turluk sohbet istekleri

Tek turluk bir etkileşim bile, daha karmaşık sohbetler için temel oluşturan 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 konuşma geçmişinin tamamını açıkça saklar ve yeniden gönderirsiniz. Bu, modelin neyi hatırladığı üzerinde size tam kontrol sağlar.

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 system istemlerini kullanma

Bir system istemi, modelin ton, kısıtlar veya rol gibi davranışını en 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 Kütüphanesinde Akış ve Async Desteği

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

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

Akış, tam yanıtı beklemek yerine çıktıyı üretilirken kademeli olarak işlemenize olanak tanır.

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şzamanlı olmayan yürütme, uygulamanızın engellenmeden aynı anda birden fazla isteği işlemesine olanak tanır. Bunu uygulamak için asyncio Python kütüphanesini kullanmanız gerekir.

Aşağıda bir ö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 yararlı olan, modelleri programlı 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’dan doğrudan 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 Kütüphanesi ile Gömme Vektörleri Oluşturma ve Kullanma

Gömme vektörleri, metni anlamsal anlamı yakalayan sayısal vektörler olarak temsil eder. Bu, metinleri birebir ifadeden ziyade benzerliğe göre karşılaştırmanıza olanak tanır.

Metin gömme vektörleri oluşturma

Aşağıdaki örnek, arama veya kümeleme için kullanılabilecek bir vektör temsiline metni 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ı kurma

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 Kütüphanesinde 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 JSON gibi yapılandırılmış veriler döndürmesi gerekir.

Python fonksiyonlarıyla araç çağırma 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 modlu modelleri ve bulut tabanlı çıkarımı destekler.

Görsel modellere görüntü gönderme

Görsel modeller hem metni hem de görüntüleri işleyebilir; bu da görüntü açıklaması 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']
    }]
)

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

Yerelde çalıştırılamayan daha büyük modeller için Ollama Cloud barındırılan çıkarım sunar.

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

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ın önüne geçer 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 yanlış 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ı, eksik modeller, 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 niceleme yapı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; şunlar dahil:

• isteminiz
• system talimatları
• sohbet geçmişi
• alınan belgeler (RAG)
• ve modelin kendi ürettiği 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 kütüphanesi, basit metin üretiminden gömme vektörleri, araç çağırma ve çoklu modlu 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.

Kendi Ollama deneyimimde, bulut LLM’leri kullanmak zorunda kalmadan iyi bir seçenek olduğunu hissettim. Örneğin, açık kaynak modelleri daha özgürce kullanabiliyorum. Siz de modeller arasında daha fazla seçenekle geçiş yapmak istiyorsanız, Ollama bunların tümüne erişmek için iyi bir kapı aralıyor.

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