OpenAI API Best Practices: Frontend Geliştirme Rehberi

## OpenAI API Temelleri ve Frontend Mimarisi Modern web uygulamalarında yapay zeka entegrasyonu, kullanıcı deneyimini kökten değiştirmektedir. **OpenAI API**, geliştiricilere GPT-4, DALL-E ve Whisper gibi güçlü modelleri uygulamalarına dahil etme imkanı tanır. Ancak, bu modellerin frontend ekosistemine entegrasyonu, klasik API kullanımlarından farklı zorluklar barındırır. Özellikle gecikme süreleri (latency), token maliyetleri ve veri güvenliği, mimari tasarımın merkezinde yer almalıdır. Frontend geliştiriciler için en kritik kural şudur: **OpenAI API anahtarları asla istemci tarafında (client-side) saklanmamalıdır.** Tüm istekler, bir ara katman (middleware) veya backend proxy üzerinden iletilmelidir. Bu yaklaşım, hem güvenliği sağlar hem de API yanıtlarını manipüle etmenize olanak tanır. ## Kurulum ve Güvenli Entegrasyon Stratejileri Bir frontend projesinde OpenAI API kullanmaya başlamadan önce, güvenli bir ortam oluşturmak şarttır. İster React, ister Vue veya Next.js kullanın, API anahtarınızı `.env` dosyalarında saklamalı ve sunucu tarafında işleme almalısınız. ### Kod Örneği 1: Next.js API Route ile Güvenli Proxy Oluşturma ```javascript // pages/api/chat.js import { Configuration, OpenAIApi } from "openai"; const configuration = new Configuration({ apiKey: process.env.OPENAI_API_KEY, }); const openai = new OpenAIApi(configuration); export default async function handler(req, res) { if (req.method !== 'POST') return res.status(405).end(); try { const completion = await openai.createChatCompletion({ model: "gpt-4", messages: req.body.messages, }); res.status(200).json(completion.data); } catch (error) { res.status(500).json({ error: error.message }); } } ``` ## Streaming (Akış) Mekanizması ve Kullanıcı Deneyimi LLM (Large Language Model) yanıtları bazen 30 saniyeyi bulabilir. Kullanıcıyı bekletmek yerine, yanıtın üretildiği anda ekrana yansıtılmasını sağlayan **Streaming** özelliği kullanılmalıdır. Bu, algılanan performansı (perceived performance) önemli ölçüde artırır. ### Kod Örneği 2: Server-Sent Events (SSE) ile Yanıt Akışını Yönetme ```javascript // Frontend tarafında akışın okunması const response = await fetch('/api/chat', { method: 'POST', body: JSON.stringify({ prompt: "Merhaba!" }), }); const reader = response.body.getReader(); const decoder = new TextDecoder(); while (true) { const { done, value } = await reader.read(); if (done) break; const chunk = decoder.decode(value); console.log("Gelen veri parçası:", chunk); // State güncelleme mantığı burada çalışır } ``` ## Gelişmiş Prompt Engineering Teknikleri Frontend katmanında kullanıcı girdilerini doğrudan API'ye göndermek yerine, bu girdileri belirli şablonlarla sarmalamak (wrapping) sonuç kalitesini artırır. **System Prompt** kullanımı, modelin kişiliğini ve sınırlarını belirlemede hayati rol oynar. | Teknik | Açıklama | Frontend Uygulaması | | :--- | :--- | :--- | | **Few-Shot Prompting** | Örneklerle öğretme | Input öncesine 2-3 örnek ekleme | | **Chain of Thought** | Adım adım düşünme | Modelden mantık yürütmesini isteme | | **System Role** | Rol tanımlama | API isteğine 'system' mesajı ekleme | ### Kod Örneği 3: Sistem Rolü ve Context Yönetimi ```javascript const messages = [ { role: "system", content: "Sen profesyonel bir yazılım mimarısın. Yanıtlarını teknik ve kısa tut." }, { role: "user", content: "Microservices mimarisi nedir?" } ]; // API'ye gönderilecek veri yapısı ``` ## Function Calling: Uygulamanızı Dış Dünyaya Bağlayın OpenAI modelleri artık belirli fonksiyonları çağırma yeteneğine sahiptir. Bu, frontend tarafında dinamik UI bileşenleri oluşturmak veya gerçek zamanlı veri çekmek için kullanılır. ### Kod Örneği 4: Function Calling Tanımlama ```javascript const functions = [{ name: "get_weather", description: "Belirli bir konumun hava durumunu getir", parameters: { type: "object", properties: { location: { type: "string", description: "Şehir ismi" }, unit: { type: "string", enum: ["celsius", "fahrenheit"] }, }, required: ["location"], }, }]; ``` ## Token Yönetimi ve Maliyet Optimizasyonu Her istek bir maliyet doğurur. Frontend tarafında gereksiz uzunluktaki geçmiş mesajları (history) temizlemek, hem performansı artırır hem de bütçeyi korur. **Rolling window** tekniği ile sadece son N mesajın gönderilmesi sağlanmalıdır. ### Kod Örneği 5: Mesaj Geçmişini Sınırlandırma (Rolling Window) ```javascript const manageContext = (messages, maxTokens = 5) => { if (messages.length > maxTokens) { return [messages[0], ...messages.slice(-maxTokens)]; } return messages; }; ``` ## Hata Yönetimi ve Dayanıklılık (Resilience) API limitlerine takılma (Rate limiting) veya sunucu hataları durumunda uygulamanın çökmemesi gerekir. **Exponential Backoff** stratejisi ile hatalı istekler belirli aralıklarla tekrar denenmelidir. ### Kod Örneği 6: Axios ile Retry Mekanizması ```javascript import axios from 'axios'; import axiosRetry from 'axios-retry'; const client = axios.create(); axiosRetry(client, { retries: 3, retryDelay: axiosRetry.exponentialDelay, retryCondition: (error) => error.response.status === 429 }); ``` ## Performans ve Önbellekleme (Caching) Stratejileri Benzer sorulara aynı yanıtları vermek için frontend tarafında veya Redis gibi bir katmanda önbellekleme yapılmalıdır. Bu, hem yanıt süresini milisaniyelere indirir hem de API maliyetini sıfırlar. ### Kod Örneği 7: Basit Bir LocalStorage Cache Mekanizması ```javascript const getAIResponse = async (prompt) => { const cached = localStorage.getItem(btoa(prompt)); if (cached) return JSON.parse(cached); const response = await fetchAI(prompt); localStorage.setItem(btoa(prompt), JSON.stringify(response)); return response; }; ``` ## Frontend'de Vision ve Image API Kullanımı GPT-4 Vision ve DALL-E 3 entegrasyonları, görsel veri işleme yeteneği sunar. Frontend tarafında dosya yükleme işlemlerinde görsellerin boyutlandırılması (resizing), token kullanımını optimize eder. ### Kod Örneği 8: DALL-E 3 ile Görsel Oluşturma İsteği ```javascript const generateImage = async (prompt) => { const response = await openai.createImage({ model: "dall-e-3", prompt: prompt, n: 1, size: "1024x1024", }); return response.data.data[0].url; }; ``` ### Kod Örneği 9: Vision API için Base64 Hazırlama ```javascript const encodeImage = (file) => { return new Promise((resolve) => { const reader = new FileReader(); reader.onloadend = () => resolve(reader.result); reader.readAsDataURL(file); }); }; ``` ## Güvenlik Protokolleri ve Veri Gizliliği Kullanıcıdan alınan verilerin (PII - Personally Identifiable Information) temizlenmesi gerekebilir. Ayrıca, API yanıtlarının manipüle edilip edilmediğini kontrol etmek için frontend tarafında sanitization işlemleri uygulanmalıdır. ### Kod Örneği 10: Markdown Yanıtlarını Güvenli Render Etme ```javascript import DOMPurify from 'dompurify'; import { marked } from 'marked'; const SafeMarkdown = ({ content }) => { const html = marked.parse(content); const cleanHtml = DOMPurify.sanitize(html); return