Laravel ile Ollama Paketi Geliştirme: Kapsamlı Rehber
Yapay zeka teknolojileri hızla gelişirken, geliştiriciler de bu gücü kendi uygulamalarına entegre etmenin yollarını arıyor. Büyük Dil Modelleri (LLM’ler) alanında yaşanan devrim niteliğindeki gelişmeler, pek çok kapıyı aralasa da, bulut tabanlı çözümlerin maliyeti ve veri gizliliği endişeleri alternatif arayışlarını beraberinde getiriyor. İşte tam bu noktada, yerel olarak LLM’leri çalıştırabilen açık kaynaklı bir platform olan Ollama devreye giriyor. Bu makalede, PHP’nin popüler çatısı Laravel ile Ollama entegrasyonunu nasıl sağlayacağınızı, sıfırdan bir Laravel paketi geliştirerek adım adım öğreneceksiniz. Kendi uygulamalarınızda güçlü yapay zeka yeteneklerini yerel ve güvenli bir şekilde kullanmak için gerekli tüm adımları ve ipuçlarını bu kapsamlı rehberde bulacaksınız.
Son yıllarda yapay zeka dünyasında çığır açan Büyük Dil Modelleri (Large Language Models – LLM’ler), doğal dil işleme yetenekleriyle metin oluşturma, özetleme, çeviri ve karmaşık soruları yanıtlama gibi birçok alanda etkileyici sonuçlar sunmaktadır. OpenAI’nin GPT serisi veya Google’ın Gemini gibi modelleri, bu alandaki en bilinen örneklerdendir. Ancak, bu modellerin çoğu bulut tabanlı hizmetler aracılığıyla sunulur. Bu durum, veri gizliliği, maliyet ve erişim hızı gibi konularda bazı kısıtlamaları beraberinde getirir. İşte burada Ollama devreye giriyor.
Ollama, açık kaynaklı bir platform olup, çeşitli LLM’leri kendi bilgisayarınızda veya sunucunuzda, yani yerel olarak çalıştırmanıza olanak tanır. Docker gibi bir sanallaştırma deneyimi sunarak, popüler modelleri (örneğin Llama 2, Mistral, Gemma) kolayca indirip kurmanızı ve bir API aracılığıyla bunlarla etkileşim kurmanızı sağlar. Bu yaklaşımın en büyük avantajlarından biri, verilerinizin şirketinizin veya kişisel kontrolünüz altında kalmasıdır. Hassas bilgileri üçüncü taraf bulut sağlayıcılarına göndermek zorunda kalmazsınız, bu da özellikle finans, sağlık veya yasal sektörlerde çalışan kurumlar için kritik bir öneme sahiptir. Ayrıca, internet bağlantısı kesildiğinde bile LLM’leri kullanmaya devam edebilir, bulut maliyetlerinden tasarruf edebilirsiniz. Örneğin, bir üretim bandında anlık hata tespiti yapan bir kamera sistemi, görüntü işleme sonuçlarını yerel bir LLM’e göndererek doğal dilde açıklama alabilir. Bu senaryoda internet bağımlılığı ciddi bir kesinti riski oluştururken, Ollama ile tamamen bağımsız bir çözüm sunulabilir. Yerel çalışma yeteneği aynı zamanda gecikmeyi (latency) önemli ölçüde azaltarak daha hızlı yanıt süreleri sağlar, bu da gerçek zamanlı uygulamalar için büyük bir avantajdır. Örneğin, canlı bir müşteri destek sohbet robotunda her saniye önemlidir ve Ollama, bulut servislerinin getireceği ekstra gecikmeyi ortadan kaldırır. Tüm bu nedenlerle, geliştiricilerin Ollama gibi yerel LLM çalıştırma çözümlerine olan ilgisi giderek artmaktadır ve bu gücü Laravel gibi modern bir web çatısına entegre etmek, birçok yenilikçi uygulamanın kapısını aralayabilir.
Laravel Paketi Geliştirmeye Nasıl Başlanır? Temeller
Laravel, PHP ekosistemindeki en güçlü ve esnek çerçevelerden biridir. Kapsamlı özellik setine ek olarak, paket sistemi sayesinde uygulama geliştiricileri, ortak işlevleri modüler ve yeniden kullanılabilir bileşenler halinde ayırabilirler. Ollama entegrasyonu gibi belirli bir görevi yerine getirecek bir paket oluşturmak, hem kod tekrarını önler hem de gelecekteki projelerde aynı işlevselliği kolayca kullanmanızı sağlar. Öncelikle, yeni bir paket oluşturma sürecini ele alalım.
Bir Laravel paketi aslında bir Composer paketidir. Dolayısıyla, işe bir Composer projesi başlatarak başlayacağız. Paketinizi ana Laravel uygulamanızdan ayrı bir dizinde, örneğin packages/vendor-name/package-name şeklinde konumlandırmanız en iyi uygulamadır. İlk adım olarak, paketin kök dizininde composer init komutunu çalıştırarak bir composer.json dosyası oluşturmalıyız:
cd packages/yazaradi/ollama-paketi
composer init
Bu komut, size paket adı (örneğin yazaradi/ollama-paketi), açıklama, yazar gibi bilgileri soracaktır. En önemli kısım ise "PSR-4 autoloading" ayarıdır. Burada paketin ana dizinini ve karşılık gelen PHP namespace'ini belirtmeniz gerekir. Genellikle src/ dizinini ve YazarAdi\OllamaPaketi\ namespace'ini kullanırız.
{
"name": "yazaradi/ollama-paketi",
"description": "Laravel uygulamaları için Ollama entegrasyonu.",
"type": "library",
"license": "MIT",
"autoload": {
"psr-4": {
"YazarAdi\\OllamaPaketi\\": "src/"
}
},
"authors": [
{
"name": "Adınız Soyadınız",
"email": "email@example.com"
}
],
"require": {
"php": "^8.2",
"illuminate/support": "^10.0 || ^11.0",
"guzzlehttp/guzzle": "^7.0"
},
"require-dev": {
"orchestra/testbench": "^8.0 || ^9.0",
"phpunit/phpunit": "^10.0 || ^11.0"
},
"extra": {
"laravel": {
"providers": [
"YazarAdi\\OllamaPaketi\\OllamaPaketiServiceProvider"
]
}
},
"minimum-stability": "dev",
"prefer-stable": true
}
Yukarıdaki composer.json dosyası, paketin temel bağımlılıklarını (illuminate/support ve guzzlehttp/guzzle gibi) ve geliştirme bağımlılıklarını (orchestra/testbench gibi test araçları) tanımlar. Ayrıca, Laravel'in paketinizi otomatik olarak keşfetmesini sağlayan extra.laravel.providers bölümüne dikkat edin. Burada paketin ana servis sağlayıcısını tanımlıyoruz. Bir servis sağlayıcı (Service Provider), paketinizi Laravel çerçevesiyle entegre eden temel bileşendir. Bağımlılıkları kaydetme, yapılandırma dosyalarını yayınlama, rotaları tanımlama ve hatta paket komutlarını kaydetme gibi görevleri üstlenir. src dizini altında OllamaPaketiServiceProvider.php adında bir dosya oluşturarak başlayabiliriz:
namespace YazarAdi\OllamaPaketi;
use Illuminate\Support\ServiceProvider;
class OllamaPaketiServiceProvider extends ServiceProvider
{
/**
* Paket servislerini kaydet.
*
* @return void
*/
public function register(): void
{
$this->mergeConfigFrom(__DIR__.'/../config/ollama.php', 'ollama');
$this->app->singleton('ollama', function ($app) {
$config = $app['config']->get('ollama');
return new OllamaClient($config['base_url'], $config['api_key'] ?? null);
});
}
/**
* Uygulama servislerini önyükle.
*
* @return void
*/
public function boot(): void
{
$this->publishes([
__DIR__.'/../config/ollama.php' => config_path('ollama.php'),
], 'ollama-config');
}
}
register() metodu içinde, paketin yapılandırma dosyasını birleştiriyor ve OllamaClient sınıfımızın bir singleton örneğini Laravel'in hizmet kapsayıcısına bağlıyoruz. Bu sayede, uygulamanızın herhangi bir yerinden app('ollama') veya bağımlılık enjeksiyonu yoluyla bu istemciye erişebileceksiniz. boot() metodu ise, paketin yapılandırma dosyasının (config/ollama.php) kullanıcı uygulamasına yayınlanmasını sağlar. Bu sayede kullanıcılar, paketin davranışını kendi ihtiyaçlarına göre özelleştirebilirler. config dizini altında ollama.php adında basit bir yapılandırma dosyası oluşturmayı da unutmayın:
env('OLLAMA_BASE_URL', 'http://localhost:11434/api'),
'api_key' => env('OLLAMA_API_KEY'), // Eğer Ollama için bir anahtar gerekirse
'timeout' => env('OLLAMA_TIMEOUT', 60),
'verify_ssl' => env('OLLAMA_VERIFY_SSL', false),
];
Bu temel yapı, Laravel uygulamanızda Ollama ile iletişim kuracak bir paket için sağlam bir temel oluşturur. Artık Composer'ın otoloading mekanizmasını güncellemek için paketin kök dizininde (packages/yazaradi/ollama-paketi) composer dump-autoload komutunu çalıştırabiliriz. Ana Laravel projenizde paketi kullanmak içinse, composer.json dosyanızın repositories bölümüne paketinizi ekleyip require etmeniz yeterlidir:
// Ana Laravel projesi composer.json
{
"repositories": [
{
"type": "path",
"url": "packages/yazaradi/ollama-paketi",
"options": {
"symlink": true
}
}
],
"require": {
"php": "^8.2",
// ... diğer bağımlılıklar
"yazaradi/ollama-paketi": "@dev"
}
}
Daha sonra ana Laravel projenizin dizininde composer update komutunu çalıştırarak paketi yükleyebilirsiniz. Bu sayede, Laravel'in otomatik paket keşif özelliği sayesinde servis sağlayıcınız otomatik olarak kaydedilecek ve paketinizi kullanmaya başlayabileceksiniz.
Ollama API İstemcisi Nasıl Oluşturulur? HTTP İstemci ve İstekler
Bir Laravel paketi içinde Ollama ile etkileşime geçmenin kalbi, Ollama'nın RESTful API'sine istek gönderecek bir HTTP istemcisidir. Laravel, güçlü ve kullanımı kolay bir HTTP istemcisi olan Guzzle üzerine kurulu kendi Illuminate\Http\Client\Factory sınıfını sunar. Bu, harici API'lerle entegrasyonu oldukça basit hale getirir. Ollama, belirli bir portta (varsayılan olarak 11434) çalışır ve JSON tabanlı istekler bekler. Temel olarak, metin oluşturma (generate), sohbet (chat) ve vektör gömme (embeddings) gibi işlevler için farklı uç noktalara sahiptir.
Öncelikle, paketimiz içinde Ollama API'si ile iletişim kuracak ana sınıfı, src/OllamaClient.php dosyasını oluşturalım. Bu sınıf, Laravel'in HTTP istemcisini kullanarak Ollama API'sine istekleri sarmalayacaktır. Servis sağlayıcıda bu sınıfı zaten singleton olarak bağladığımız için, bu istemciye kolayca erişebileceğiz.
namespace YazarAdi\OllamaPaketi;
use Illuminate\Http\Client\PendingRequest;
use Illuminate\Support\Facades\Http;
use YazarAdi\OllamaPaketi\Exceptions\OllamaClientException;
class OllamaClient
{
protected PendingRequest $httpClient;
protected ?string $apiKey; // Ollama'nın gelecekte API anahtarı kullanması ihtimaline karşılık
public function __construct(string $baseUrl, ?string $apiKey = null, int $timeout = 60, bool $verifySsl = false)
{
$this->apiKey = $apiKey;
$this->httpClient = Http::baseUrl($baseUrl)
->timeout($timeout)
->withOptions(['verify' => $verifySsl]);
if ($this->apiKey) {
$this->httpClient->withToken($this->apiKey); // Eğer Ollama API anahtarı kullanırsa
}
}
/**
* Belirtilen bir model ile metin oluşturur.
*
* @param string $model
* @param string $prompt
* @param array $options
* @return array
* @throws OllamaClientException
*/
public function generate(string $model, string $prompt, array $options = []): array
{
$payload = [
'model' => $model,
'prompt' => $prompt,
'stream' => false, // İlk etapta stream'i devre dışı bırakalım
'options' => $options,
];
try {
$response = $this->httpClient->post('generate', $payload);
if ($response->successful()) {
return $response->json();
}
throw new OllamaClientException(
'Ollama generate isteği başarısız oldu: ' . $response->status() . ' - ' . $response->body(),
$response->status()
);
} catch (\Throwable $e) {
throw new OllamaClientException('Ollama generate isteği sırasında bir hata oluştu: ' . $e->getMessage(), 0, $e);
}
}
/**
* Sohbet tamamlama (chat completion) isteği gönderir.
*
* @param string $model
* @param array $messages
* @param array $options
* @return array
* @throws OllamaClientException
*/
public function chat(string $model, array $messages, array $options = []): array
{
$payload = [
'model' => $model,
'messages' => $messages,
'stream' => false,
'options' => $options,
];
try {
$response = $this->httpClient->post('chat', $payload);
if ($response->successful()) {
return $response->json();
}
throw new OllamaClientException(
'Ollama chat isteği başarısız oldu: ' . $response->status() . ' - ' . $response->body(),
$response->status()
);
} catch (\Throwable $e) {
throw new OllamaClientException('Ollama chat isteği sırasında bir hata oluştu: ' . $e->getMessage(), 0, $e);
}
}
/**
* Belirtilen metin için embedding (vektör gömme) oluşturur.
*
* @param string $model
* @param string $prompt
* @param array $options
* @return array
* @throws OllamaClientException
*/
public function embeddings(string $model, string $prompt, array $options = []): array
{
$payload = [
'model' => $model,
'prompt' => $prompt,
'options' => $options,
];
try {
$response = $this->httpClient->post('embeddings', $payload);
if ($response->successful()) {
return $response->json();
}
throw new OllamaClientException(
'Ollama embeddings isteği başarısız oldu: ' . $response->status() . ' - ' . $response->body(),
$response->status()
);
} catch (\Throwable $e) {
throw new OllamaClientException('Ollama embeddings isteği sırasında bir hata oluştu: ' . $e->getMessage(), 0, $e);
}
}
}
Bu OllamaClient sınıfı, Ollama API'sinin temel fonksiyonlarını sarmalar: metin oluşturma (/api/generate), sohbet tamamlama (/api/chat) ve metin gömme (/api/embeddings). Constructor'da, Ollama sunucusunun temel URL'sini (genellikle http://localhost:11434/api), zaman aşımı süresini ve SSL doğrulama ayarını alarak Laravel HTTP istemcisini yapılandırıyoruz. Her metot (generate, chat, embeddings), ilgili Ollama API uç noktasına bir POST isteği gönderir. Gerekli parametreleri (model adı, prompt/mesajlar, seçenekler) bir payload olarak iletir. Özellikle, Ollama API'sinin yanıtı JSON formatında olduğu için $response->json() metodunu kullanarak doğrudan PHP dizisine dönüştürüyoruz. Başarılı olmayan (4xx veya 5xx) yanıtlar veya ağ hataları durumunda ise özel bir OllamaClientException fırlatarak hata yönetimini merkezi hale getiriyoruz. Bu, uygulamanızın Ollama ile ilgili sorunları daha temiz bir şekilde ele almasını sağlar. src/Exceptions/OllamaClientException.php dosyasını da şu şekilde oluşturabiliriz:
namespace YazarAdi\OllamaPaketi\Exceptions;
use Exception;
class OllamaClientException extends Exception
{
// Özel hata mesajları veya durum kodları eklenebilir.
}
Bu yapı sayesinde, paketimiz artık Ollama ile temel düzeyde iletişim kurabilir ve ana Laravel uygulamamızda bu işlevleri kullanabiliriz. İstemci sınıfımızın esnekliği sayesinde, Ollama'nın sunduğu farklı modelleri ve onların özel parametrelerini kolayca destekleyebiliriz. Örneğin, bir chat isteği gönderirken, LLM'in geçmiş konuşmaları hatırlamasını sağlayan bir mesaj dizisi (messages array) gönderebiliriz. Bu, daha bağlamsal ve tutarlı yanıtlar elde etmemizi sağlar. Bir sonraki bölümde, bu istemciyi bir servis katmanına nasıl entegre edeceğimizi ve uygulamanızın içinden nasıl daha kolay erişilebilir hale getireceğimizi inceleyeceğiz.
Paket İçinde Ollama Fonksiyonelliği Nasıl Kapsüllenir?
OllamaClient sınıfımız, Ollama API'si ile doğrudan iletişim kurmaktan sorumludur, ancak Laravel uygulamanızın iş mantığı katmanında doğrudan bu istemciyi kullanmak her zaman en temiz yaklaşım olmayabilir. Uygulama geliştiricilerin daha yüksek seviyeli, model odaklı veya görev odaklı arayüzler aracılığıyla Ollama yeteneklerine erişmelerini sağlamak, paketin kullanımını daha sezgisel hale getirir ve gelecekteki değişikliklere karşı daha dirençli olmasını sağlar. Bu nedenle, OllamaClient'ı sarmalayacak ve iş mantığını kapsülleyecek bir ana "yönetici" veya "servis" sınıfı oluşturmak iyi bir fikirdir.
Paketimiz içinde, örneğin src/OllamaManager.php adında bir sınıf oluşturabiliriz. Bu sınıf, OllamaClient örneğini constructor'ında bağımlılık olarak alacak ve uygulamanın belirli iş akışlarına yönelik daha anlamlı metotlar sunacaktır. Bu yaklaşım, Facade deseniyle birlikte kullanıldığında, paketinize erişimi son derece kolaylaştıracaktır.
namespace YazarAdi\OllamaPaketi;
use YazarAdi\OllamaPaketi\Exceptions\OllamaClientException;
class OllamaManager
{
protected OllamaClient $client;
protected string $defaultModel;
public function __construct(OllamaClient $client, string $defaultModel = 'llama2')
{
$this->client = $client;
$this->defaultModel = $defaultModel;
}
/**
* Metin oluşturma işlemi yapar.
*
* @param string $prompt
* @param string|null $model
* @param array $options
* @return string
* @throws OllamaClientException
*/
public function generateText(string $prompt, ?string $model = null, array $options = []): string
{
$usedModel = $model ?? $this->defaultModel;
$response = $this->client->generate($usedModel, $prompt, $options);
// Ollama'dan gelen yanıtın yapısına göre uygun alanı döndürün.
// Genellikle 'response' veya 'content' anahtarı altında bulunur.
return $response['response'] ?? $response['content'] ?? '';
}
/**
* Sohbet tamamlama işlemi yapar.
*
* @param array $messages [{ role: 'user', content: '...' }]
* @param string|null $model
* @param array $options
* @return array
* @throws OllamaClientException
*/
public function chatCompletion(array $messages, ?string $model = null, array $options = []): array
{
$usedModel = $model ?? $this->defaultModel;
$response = $this->client->chat($usedModel, $messages, $options);
// Ollama'dan gelen chat yanıtının yapısına göre uygun alanı döndürün.
// Genellikle son mesajın 'content' alanıdır.
if (isset($response['message']['content'])) {
return $response['message'];
}
return $response; // Tam yanıtı döndürmek daha esnek olabilir
}
/**
* Metin için embedding (vektör gömme) oluşturur.
*
* @param string $text
* @param string|null $model
* @param array $options
* @return array
* @throws OllamaClientException
*/
public function embedText(string $text, ?string $model = null, array $options = []): array
{
$usedModel = $model ?? $this->defaultModel;
$response = $this->client->embeddings($usedModel, $text, $options);
return $response['embedding'] ?? [];
}
/**
* Varsayılan modeli değiştirir.
*
* @param string $model
* @return $this
*/
public function setDefaultModel(string $model): self
{
$this->defaultModel = $model;
return $this;
}
/**
* Temeldeki OllamaClient örneğine doğrudan erişim sağlar.
*
* @return OllamaClient
*/
public function getClient(): OllamaClient
{
return $this->client;
}
}
OllamaManager sınıfı, OllamaClient'ı constructor'ında alarak bir bağımlılık enjeksiyonu örneği sunar. Ayrıca, varsayılan bir LLM modelini de kabul ederek, her istekte modeli belirtme zorunluluğunu ortadan kaldırır. generateText, chatCompletion ve embedText gibi metotlar, OllamaClient'ın metotlarını çağırır ancak gelen yanıtları daha kullanıcı dostu bir formata dönüştürür. Örneğin, generateText metodu sadece oluşturulan metin içeriğini döndürür, böylece uygulamanın diğer kısımları ham API yanıtının detaylarıyla uğraşmak zorunda kalmaz. Bu kapsülleme, paketin kullanımını basitleştirir ve uygulamanızın iş mantığını Ollama API'sinin spesifik detaylarından soyutlar.
Bu OllamaManager'ı Laravel'in hizmet kapsayıcısına bağlamak için OllamaPaketiServiceProvider sınıfımızı güncelleyelim:
namespace YazarAdi\OllamaPaketi;
use Illuminate\Support\ServiceProvider;
class OllamaPaketiServiceProvider extends ServiceProvider
{
public function register(): void
{
$this->mergeConfigFrom(__DIR__.'/../config/ollama.php', 'ollama');
// OllamaClient'ı hizmet kapsayıcısına bağlama
$this->app->singleton(OllamaClient::class, function ($app) {
$config = $app['config']->get('ollama');
return new OllamaClient(
$config['base_url'],
$config['api_key'] ?? null,
$config['timeout'] ?? 60,
$config['verify_ssl'] ?? false
);
});
// OllamaManager'ı hizmet kapsayıcısına bağlama, OllamaClient'ı bağımlılık olarak enjekte etme
$this->app->singleton('ollama', function ($app) {
$config = $app['config']->get('ollama');
return new OllamaManager(
$app->make(OllamaClient::class),
$config['default_model'] ?? 'llama2'
);
});
}
public function boot(): void
{
$this->publishes([
__DIR__.'/../config/ollama.php' => config_path('ollama.php'),
], 'ollama-config');
}
}
Yapılandırma dosyamıza (config/ollama.php) varsayılan model için bir giriş eklemeyi unutmayın:
// config/ollama.php
return [
'base_url' => env('OLLAMA_BASE_URL', 'http://localhost:11434/api'),
'api_key' => env('OLLAMA_API_KEY'),
'timeout' => env('OLLAMA_TIMEOUT', 60),
'verify_ssl' => env('OLLAMA_VERIFY_SSL', false),
'default_model' => env('OLLAMA_DEFAULT_MODEL', 'llama2'),
];
Son olarak, paketinize daha kolay ve statik erişim sağlamak için bir Laravel Facade oluşturabiliriz. src/Facades/Ollama.php adında bir dosya oluşturarak bunu yapabiliriz:
namespace YazarAdi\OllamaPaketi\Facades;
use Illuminate\Support\Facades\Facade;
/**
* @method static string generateText(string $prompt, ?string $model = null, array $options = [])
* @method static array chatCompletion(array $messages, ?string $model = null, array $options = [])
* @method static array embedText(string $text, ?string $model = null, array $options = [])
* @method static \YazarAdi\OllamaPaketi\OllamaManager setDefaultModel(string $model)
* @method static \YazarAdi\OllamaPaketi\OllamaClient getClient()
*
* @see \YazarAdi\OllamaPaketi\OllamaManager
*/
class Ollama extends Facade
{
protected static function getFacadeAccessor(): string
{
return 'ollama';
}
}
Bu Facade, OllamaManager sınıfına statik metotlar aracılığıyla erişim sağlar. Laravel uygulamanızın config/app.php dosyasındaki aliases dizisine paketinizi eklediğinizde (veya Laravel 5.5+ ile otomatik keşif sayesinde), doğrudan Ollama::generateText('...') şeklinde kullanabileceksiniz. Bu katmanlama, paketinizi hem güçlü hem de kullanımı kolay hale getirirken, iş mantığınızı API detaylarından ayırır. Bu esneklik, paketinizi farklı Ollama API değişikliklerine veya yeni LLM özelliklerine daha kolay uyarlamanıza olanak tanır. Artık ana Laravel uygulamanızda bu paketi kullanmaya hazırsınız!
Laravel Uygulamanızda Ollama Paketini Nasıl Kullanırsınız?
Paketimiz hazırlandığına göre, şimdi sıra onu bir Laravel uygulamasında nasıl kullanacağımızı öğrenmeye geldi. Bu bölüm, paketin kurulumu, yapılandırılması ve çeşitli gerçek dünya senaryolarında nasıl entegre edileceğine dair adım adım rehberlik edecektir.
Kurulum ve Temel Yapılandırma
Daha önce belirtildiği gibi, paketinizi Composer üzerinden projenize dahil ettikten sonra (Composer'ın repositories kısmını kullanarak yerel paketler için veya gelecekte Packagist'e yayınladığınızda doğrudan), ilk adım yapılandırma dosyasını yayınlamaktır. Bu, Laravel uygulamanızın config dizinine paketin ollama.php yapılandırma dosyasını kopyalar ve böylece ayarları projenize özel olarak özelleştirebilirsiniz.
php artisan vendor:publish --tag=ollama-config
Bu komut, config/ollama.php dosyasını oluşturacaktır. Bu dosyada, Ollama sunucunuzun temel URL'sini ve varsayılan modeli ayarlayabilirsiniz. Genellikle bu ayarları .env dosyanızda tutmak ve yapılandırma dosyasında env() helper'ı ile çekmek en iyi uygulamadır:
OLLAMA_BASE_URL="http://localhost:11434/api"
OLLAMA_DEFAULT_MODEL="llama2"
OLLAMA_TIMEOUT=120
OLLAMA_VERIFY_SSL=false
# OLLAMA_API_KEY="your_ollama_api_key_if_needed"
Unutmayın, bu ayarları değiştirdikten sonra Laravel'in yapılandırma önbelleğini temizlemeniz gerekebilir:
php artisan config:clear
Basit Bir Kullanım Örneği: Metin Oluşturma
Paketiniz hazır ve yapılandırıldığında, Ollama Facade'ını kullanarak çeşitli Ollama işlevlerine kolayca erişebilirsiniz. Örneğin, bir metin oluşturma işlemi için Controller veya Artisan komutunuzda aşağıdaki gibi kullanabilirsiniz:
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use YazarAdi\OllamaPaketi\Facades\Ollama;
use YazarAdi\OllamaPaketi\Exceptions\OllamaClientException;
class AiController extends Controller
{
public function generateStory(Request $request)
{
$prompt = $request->input('prompt', 'Uzayda kaybolan bir kedinin hikayesini yaz.');
$model = $request->input('model', 'mistral'); // Kullanıcı farklı bir model seçebilir
try {
$story = Ollama::generateText($prompt, $model, [
'temperature' => 0.7, // Yaratıcılık derecesi
'num_predict' => 500 // Maksimum token sayısı
]);
return response()->json(['success' => true, 'story' => $story]);
} catch (OllamaClientException $e) {
// Ollama API'sından dönen hatayı yakala ve uygun şekilde ele al
return response()->json(['success' => false, 'message' => $e->getMessage()], 500);
} catch (\Exception $e) {
// Diğer beklenmedik hataları yakala
return response()->json(['success' => false, 'message' => 'Bir hata oluştu: ' . $e->getMessage()], 500);
}
}
}
Bu örnekte, bir HTTP isteği ile gelen prompt ve model bilgilerini alıyor, Ollama::generateText() metodunu çağırarak Ollama'dan bir hikaye oluşturmasını istiyoruz. Ayrıca, temperature ve num_predict gibi model parametrelerini de üçüncü bir bağımsız değişken olarak iletiyoruz. Bu, LLM'in davranışını daha detaylı kontrol etmenizi sağlar. Ollama istemcisinden gelebilecek olası hataları (örneğin, sunucunun kapalı olması veya modelin bulunamaması gibi) yakalamak için try-catch bloklarını kullanmak kritik öneme sahiptir.
Gerçek Dünya Senaryosu: Gelişmiş Bir Chatbot Entegrasyonu
Bir e-ticaret sitesinde müşteri hizmetleri için gelişmiş bir chatbot entegrasyonu düşünebiliriz. Bu chatbot, kullanıcının sorularını doğal dilde anlayıp yanıtlayabilir. Ollama'nın chat API'si bu senaryo için idealdir.
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Session;
use YazarAdi\OllamaPaketi\Facades\Ollama;
use YazarAdi\OllamaPaketi\Exceptions\OllamaClientException;
class ChatbotController extends Controller
{
private const CHAT_HISTORY_KEY = 'ollama_chat_history';
public function sendMessage(Request $request)
{
$userMessage = $request->input('message');
$model = Ollama::setDefaultModel('llama2:7b'); // Veya kullanıcının seçtiği model
// Sohbet geçmişini al veya boş başlat
$history = Session::get(self::CHAT_HISTORY_KEY, []);
// Kullanıcının mesajını geçmişe ekle
$history[] = ['role' => 'user', 'content' => $userMessage];
try {
// Ollama'ya sohbet geçmişi ile birlikte mesajları gönder
$response = Ollama::chatCompletion($history, null, [
'temperature' => 0.6,
'top_p' => 0.9,
]);
$ollamaResponseContent = $response['content'] ?? 'Üzgünüm, sorunuzu anlayamadım.';
// Ollama'nın yanıtını geçmişe ekle
$history[] = ['role' => 'assistant', 'content' => $ollamaResponseContent];
// Güncellenmiş geçmişi oturuma kaydet
Session::put(self::CHAT_HISTORY_KEY, $history);
return response()->json(['success' => true, 'reply' => $ollamaResponseContent, 'history' => $history]);
} catch (OllamaClientException $e) {
return response()->json(['success' => false, 'message' => 'AI ile iletişim hatası: ' . $e->getMessage()], 500);
} catch (\Exception $e) {
return response()->json(['success' => false, 'message' => 'Beklenmedik bir hata oluştu: ' . $e->getMessage()], 500);
}
}
public function getChatHistory()
{
return response()->json(['history' => Session::get(self::CHAT_HISTORY_KEY, [])]);
}
public function clearChatHistory()
{
Session::forget(self::CHAT_HISTORY_KEY);
return response()->json(['message' => 'Sohbet geçmişi temizlendi.']);
}
}
Bu chatbot örneği, Laravel'in oturum (Session) mekanizmasını kullanarak sohbet geçmişini tutar. Her yeni mesaj geldiğinde, tüm geçmişi Ollama'ya gönderir, böylece LLM konuşmanın bağlamını koruyabilir. Bu, daha tutarlı ve akıcı bir sohbet deneyimi sağlar. setDefaultModel ile anlık olarak kullanılacak modeli değiştirebiliriz. Müşteri destek sistemleri, eğitim platformları veya içerik oluşturma araçları gibi birçok alanda bu tür bir entegrasyon büyük faydalar sağlayabilir. Bu örnek, paketin temel fonksiyonelliğini gerçek bir uygulamanın ihtiyaçlarına göre nasıl uyarlayabileceğinizi göstermektedir. Paketin esnekliği sayesinde, Ollama'nın sunduğu tüm yetenekleri Laravel uygulamanızın kalbine yerleştirebilirsiniz.
Ollama Entegrasyonunda İleri Düzey Konular ve Optimizasyonlar Nelerdir?
Ollama paketinizin temel işlevselliğini oluşturdunuz ve Laravel uygulamanıza entegre ettiniz. Ancak, daha büyük ölçekli veya performans odaklı projelerde, paketinizi daha güçlü ve dayanıklı hale getirmek için bazı ileri düzey konuları ve optimizasyon stratejilerini göz önünde bulundurmanız gerekir. Bu konular arasında veri akışı (streaming), önbellekleme (caching), güvenlik, test süreçleri ve hatta mobil uyumlu çıktıların yönetimi yer almaktadır.
Veri Akışı (Streaming) ve Eşzamansız İşlemler
Büyük dil modellerinden yanıtlar bazen birkaç saniye sürebilir. Kullanıcı deneyimini iyileştirmek için, yanıtın tamamını beklemek yerine metnin parça parça akışını sağlamak (streaming) önemlidir. Ollama API'si stream: true parametresiyle bu özelliği destekler. Laravel'in HTTP istemcisi, Guzzle'ın eşzamansız yeteneklerini kullanarak akışlı yanıtları işleyebilir. OllamaClient sınıfımızda generate veya chat metotlarını akışlı yanıtlara destek verecek şekilde güncelleyebiliriz:
// src/OllamaClient.php içindeki generate metodu örneği (stream için güncellenmiş)
public function generateStream(string $model, string $prompt, array $options = []): \Generator
{
$payload = [
'model' => $model,
'prompt' => $prompt,
'stream' => true, // Streaming'i etkinleştir
'options' => $options,
];
try {
$response = $this->httpClient->withOptions([
'stream' => true // Guzzle'a akışlı yanıt beklenildiğini bildir
])->post('generate', $payload);
// Yanıtın akışını satır satır oku
foreach ($response->toPsrResponse()->getBody() as $chunk) {
$data = json_decode($chunk, true);
if (json_last_error() === JSON_ERROR_NONE) {
yield $data; // Her JSON objesini döndür
}
}
} catch (\Throwable $e) {
throw new OllamaClientException('Ollama stream generate isteği sırasında hata: ' . $e->getMessage(), 0, $e);
}
}
Bu generateStream metodu, PHP'nin Generator özelliğini kullanarak her bir yanıt parçasını (chunk) döndürür. Laravel kontrolcünüzde bu generator'ı kullanarak anlık yanıtları istemciye (örneğin, bir SSE - Server-Sent Events bağlantısı üzerinden) gönderebilirsiniz. Bu, kullanıcı arayüzünüzün LLM yanıtı geldikçe güncellenmesini sağlar, tıpkı ChatGPT gibi sohbet uygulamalarında olduğu gibi. Eşzamansız işlemleri desteklemek, özellikle kullanıcı arayüzü ile etkileşimli çalışan uygulamalarda performansı ve kullanıcı memnuniyetini artırır. Laravel'in queue (kuyruk) sistemi, arka planda uzun süreli LLM işlemlerini yürütmek için de kullanılabilir, böylece HTTP isteği kilitlenmez.
Önbellekleme (Caching) Stratejileri
Belirli Ollama istekleri (özellikle sıkça sorulan sorulara verilen yanıtlar veya sabit metin gömmeleri) aynı sonucu tekrar tekrar döndürebilir. Bu tür istekler için önbellekleme kullanmak, hem LLM'e yapılan gereksiz çağrıları azaltır hem de yanıt sürelerini hızlandırır. Laravel'in güçlü önbellekleme sürücüleri (Redis, Memcached, File vb.) bu amaçla kullanılabilir.
// OllamaManager sınıfında örnek bir önbellekleme entegrasyonu
use Illuminate\Support\Facades\Cache;
public function generateTextWithCache(string $prompt, ?string $model = null, array $options = []): string
{
$cacheKey = 'ollama_generate_' . md5($prompt . json_encode($options) . ($model ?? $this->defaultModel));
return Cache::remember($cacheKey, now()->addHours(24), function () use ($prompt, $model, $options) {
return $this->generateText($prompt, $model, $options);
});
}
Bu örnek, aynı prompt ve seçeneklerle yapılan istekler için 24 saatlik bir önbellek süresi belirler. Eğer önbellekte bir yanıt bulunursa, Ollama API'sine hiç istek yapılmaz. Bu, özellikle maliyetli veya zaman alıcı işlemler için büyük bir optimizasyon sağlar. Hangi isteklerin önbelleğe alınacağına, verinin güncelliği gereksinimine göre karar vermeniz önemlidir.
Güvenlik: API Anahtarları ve Yetkilendirme
Ollama yerel olarak çalışsa da, API'sine dışarıdan erişim sağlanabilir. Eğer Ollama sunucunuz internete açık bir ortamdaysa, yetkisiz erişimi engellemek için güvenlik önlemleri almanız şarttır. Şu anda Ollama'nın kendisi güçlü bir API anahtarı veya kimlik doğrulama mekanizması sunmamaktadır; ancak, API erişimini sunucu seviyesinde bir proxy (örneğin Nginx) ile kısıtlayabilir veya Laravel paketinizi kullanarak kendi yetkilendirme katmanınızı oluşturabilirsiniz. Örneğin, Laravel'in Middleware'leri aracılığıyla gelen isteklerin belirli bir API anahtarı içerdiğini doğrulayabilirsiniz. Bu anahtar, Laravel uygulamanızdan Ollama sunucusuna yapılan her istekte bir HTTP başlığı olarak eklenebilir. Ayrıca, Laravel paketi, Ollama sunucusuyla iletişim kurarken SSL/TLS kullanacak şekilde yapılandırılmalıdır (verify_ssl ayarı). Bu, iletişimin şifrelenmesini ve dinlenmesini önler.
Test Süreçleri: Unit ve Feature Testleri
Paketinizin beklenen şekilde çalıştığından emin olmak için kapsamlı testler yazmak hayati öneme sahiptir. Laravel paketleri genellikle Orchestra Testbench ile test edilir. Bu, paketinizi minimum bir Laravel uygulaması içinde test etmenizi sağlar. OllamaClient gibi dış API'lerle etkileşime giren sınıflar için, gerçek API çağrılarını yapmadan test etmek amacıyla HTTP istemcisini taklit etmeniz (mocking) gerekir. Laravel'in Http::fake() özelliği, bu işlemi oldukça basitleştirir.
// tests/Feature/OllamaClientTest.php örneği
use YazarAdi\OllamaPaketi\OllamaClient;
use Illuminate\Support\Facades\Http;
use Orchestra\Testbench\TestCase;
class OllamaClientTest extends TestCase
{
/** @test */
public function it_can_generate_text_successfully()
{
Http::fake([
'localhost:11434/api/generate' => Http::response([
'model' => 'llama2',
'created_at' => '2023-01-01T00:00:00Z',
'response' => 'Merhaba, ben bir test yanıtıyım.',
'done' => true,
], 200),
]);
$client = new OllamaClient('http://localhost:11434/api');
$response = $client->generate('llama2', 'Merhaba dünya');
$this->assertEquals('Merhaba, ben bir test yanıtıyım.', $response['response']);
}
}
Bu test örneği, Http::fake() kullanarak Ollama API'sine yapılan bir generate isteğini taklit eder. Gerçek bir HTTP çağrısı yapılmadan, istemcinin yanıtı doğru şekilde işleyip işlemediğini kontrol edebiliriz. Bu yaklaşım, testlerin hızlı ve tutarlı çalışmasını sağlar.
Mobil Uyumlu HTML Çıktısı Düşünceleri
Eğer Ollama paketiniz, doğrudan veya dolaylı olarak kullanıcı arayüzüne yönelik HTML içeriği üretiyorsa (örneğin, bir yönetim paneli widget'ı veya bir chatbot arayüzü), bu çıktıların mobil cihazlarda da iyi görünmesini sağlamak önemlidir. Modern web geliştirme pratikleri, duyarlı tasarım (responsive design) prensiplerini benimser. Bu, CSS Media Queries kullanarak ekran boyutuna göre farklı stiller uygulayarak başarılır. Paketin kendisi genellikle doğrudan HTML üretmese de, Laravel uygulamanızın genel görünüm ve hissini etkileyen blade bileşenleri veya View Composer'lar sağlayabilir. İşte basit bir duyarlı CSS örneği:
/* resources/assets/css/ollama-widget.css (örneğin) */
.ollama-card {
border: 1px solid #e2e8f0;
border-radius: 0.5rem;
padding: 1rem;
margin-bottom: 1rem;
background-color: #fff;
box-shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.06);
}
.ollama-card-title {
font-size: 1.25rem;
font-weight: bold;
color: #2d3748;
margin-bottom: 0.75rem;
}
/* Mobil cihazlar için stil ayarları */
@media (max-width: 768px) {
.ollama-card {
padding: 0.75rem;
margin-bottom: 0.75rem;
border-radius: 0.25rem;
}
.ollama-card-title {
font-size: 1rem;
margin-bottom: 0.5rem;
}
}
/* Küçük cihazlar için ek ayarlar */
@media (max-width: 480px) {
.ollama-card {
padding: 0.5rem;
}
.ollama-card-title {
font-size: 0.9rem;
}
}
Eğer paketiniz bir Blade bileşeni sunuyorsa, bu CSS dosyalarını kendi ServiceProvider'ınızdan yayınlayabilir ve uygulama tarafından kullanılmasını sağlayabilirsiniz. Örneğin, boot() metodunda $this->publishes([__DIR__.'/../resources/assets' => public_path('vendor/yazaradi/ollama')], 'ollama-assets'); komutuyla CSS dosyalarını yayınlayabilirsiniz. Böylece, paketinize ait tüm kullanıcı arayüzü bileşenleri otomatik olarak duyarlı hale gelecektir. Duyarlı tasarım, kullanıcılarınızın herhangi bir cihazdan uygulamanıza eriştiğinde sorunsuz bir deneyim yaşamasını garantiler.
Bu ileri düzey konuları dikkate alarak, Ollama Laravel paketinizi sadece işlevsel değil, aynı zamanda performanslı, güvenli, test edilebilir ve kullanıcı dostu hale getirebilirsiniz. Bu, paketinizi geniş bir kullanım alanına yaygınlaştırmak için anahtar niteliğindedir.
Sonuç: Yerel Yapay Zeka Gücünü Laravel'e Taşıyın
Bu kapsamlı rehber boyunca, açık kaynaklı Ollama platformunun gücünü Laravel uygulamalarınızla nasıl birleştirebileceğinizi adım adım öğrendiniz. Yerel Büyük Dil Modellerini çalıştırma yeteneği sunan Ollama, geliştiricilere bulut tabanlı çözümlerin getirdiği maliyet, veri gizliliği ve gecikme endişelerini ortadan kaldıran cazip bir alternatif sunmaktadır. Kendi Laravel paketinizi oluşturarak, Ollama'nın sunduğu metin oluşturma, sohbet tamamlama ve metin gömme gibi gelişmiş yapay zeka özelliklerini Laravel ekosistemine entegre etmenin temel prensiplerini keşfettik. Composer ile paket yapısı oluşturmaktan, Laravel'in HTTP istemcisini kullanarak Ollama API'si ile iletişim kurmaya, servis sağlayıcıları ve Facade'lar aracılığıyla paketinizi uygulamanızda kolayca erişilebilir kılmaya kadar tüm süreçleri ele aldık.
Paket geliştirme sürecinde, hem iş mantığını API detaylarından soyutlamak hem de kodu daha modüler hale getirmek için OllamaClient ve OllamaManager sınıflarını nasıl katmanlandıracağımızı gördük. Gerçek dünya senaryolarıyla, örneğin bir chatbot entegrasyonuyla, bu paketin potansiyel kullanım alanlarını somutlaştırdık. Ayrıca, streaming ile gerçek zamanlı yanıtlar alma, önbellekleme ile performansı artırma, güvenlik önlemleri alma ve test süreçlerini uygulama gibi ileri düzey konulara değinerek paketinizi daha güçlü ve dayanıklı hale getirme yollarını inceledik. Mobil uyumlu HTML çıktıları üretme konusundaki düşünceler, paketinizi kullanıcı arayüzüne yönelik bileşenler sunması durumunda nasıl duyarlı hale getirebileceğinizi gösterdi.
Ollama'nın yerel LLM çalıştırma yeteneği, Laravel'in geliştirici dostu yapısıyla birleştiğinde, sonsuz yaratıcı ve pratik uygulama fırsatları sunar. İçerik otomasyonundan akıllı müşteri destek sistemlerine, veri analizinden kişiselleştirilmiş öğrenme deneyimlerine kadar birçok alanda çığır açıcı projeler geliştirebilirsiniz. Kendi kontrolünüzdeki yapay zeka gücüyle, hem esnek hem de maliyet etkin çözümler üretebilir, veri gizliliği endişelerini minimize edebilirsiniz. Bu rehberin, Laravel ve Ollama ile yapay zeka yolculuğunuza ilham vermesini ve sizi kendi yenilikçi çözümlerinizi geliştirmeye teşvik etmesini umuyoruz. Gelecek, yerel yapay zeka ile daha da kişiselleştirilebilir ve verimli uygulamalar inşa etme fırsatları sunuyor.
Sıkça Sorulan Sorular (SSS)
S1: Ollama paketini kullanmak için hangi gereksinimler var?
C1: Ollama paketini kullanmak için öncelikle yerel makinenizde veya sunucunuzda Ollama uygulamasının kurulu ve çalışıyor olması gerekir. Ayrıca, Laravel uygulamanızın PHP 8.2 veya üzeri bir sürüme sahip olması ve Composer ile paket bağımlılıklarının yönetilmesi gerekmektedir. Yüklü bir LLM modeli (örneğin llama2 veya mistral) Ollama üzerinde çalışır durumda olmalıdır.
S2: Farklı LLM'leri paket içinde nasıl yönetebilirim?
C2: Paket, Ollama'nın desteklediği herhangi bir modeli kullanmanıza olanak tanır. config/ollama.php dosyasındaki default_model ayarını değiştirerek varsayılan modeli belirleyebilirsiniz. Ayrıca, Ollama::generateText('prompt', 'yeni-model') veya Ollama::chatCompletion(messages, 'yeni-model') gibi metotlarda ikinci parametre olarak doğrudan model adını belirterek anlık olarak farklı bir model kullanabilirsiniz.
S3: Paket performansı nasıl optimize edilir?
C3: Performansı optimize etmek için birkaç yol vardır:
- Önbellekleme: Sıkça tekrar eden veya statik yanıtlar için Laravel'in önbellekleme sistemini kullanın.
- Streaming: Uzun yanıtlar için veri akışı (streaming) özelliğini kullanarak kullanıcı deneyimini iyileştirin.
- Eşzamansız İşlemler/Kuyruklar: Uzun süreli LLM işlemlerini Laravel kuyruk sistemine (queues) atarak ana HTTP isteğini serbest bırakın.
- Model Seçimi: Daha küçük ve daha hızlı modelleri tercih edin veya belirli görevler için optimize edilmiş modelleri kullanın.
S4: Streaming özelliği ne işe yarar ve nasıl kullanılır?
C4: Streaming özelliği, Büyük Dil Modellerinden gelen yanıtların tamamını beklemek yerine, metnin parça parça (chunk by chunk) akmasını sağlar. Bu, özellikle sohbet robotları gibi etkileşimli uygulamalarda kullanıcıya daha hızlı geri bildirim sunarak bekleme süresi algısını azaltır. Paketinizde, OllamaClient içindeki generateStream gibi bir metot oluşturarak ve PHP'nin Generator'larını kullanarak bu özelliği etkinleştirebilirsiniz. İstemci tarafında ise genellikle Server-Sent Events (SSE) veya WebSockets ile bu akışı dinleyerek kullanıcı arayüzünü güncelleyebilirsiniz.
S5: Kendi özel modellerimi paketle entegre edebilir miyim?
C5: Evet, Ollama'nın en büyük avantajlarından biri, kendi özelleştirilmiş veya ince ayarlı modellerinizi (fine-tuned models) kolayca içe aktarmanıza ve çalıştırmanıza izin vermesidir. Kendi modelinizi Ollama'ya ekledikten sonra, tıpkı standart modeller gibi, bu paketi kullanarak modelinizin adını belirterek doğrudan onunla etkileşim kurabilirsiniz. Paket, Ollama API'sinin genel yapısına dayandığı için, hangi modelin kullanıldığı konusunda esneklik sunar.