OpenAI Chat Completions API: Özellikler ve Kullanım Rehberi

Yapay zekâ destekli bir uygulama geliştirmek, yalnızca bir modelin yanıt üretmesini sağlamakla sınırlı değildir. Konuşmaları yönetmek, yanıtları yönlendirmek ve her şeyi uygulamanıza bağlamak için de güvenilir bir yönteme ihtiyacınız vardır. OpenAI Chat Completions API, yapay zekânın mesajları nasıl ele alacağını ve yanıtları nasıl oluşturacağını geliştiricilerin kontrol etmesini sağlayarak bunu mümkün kılar. Nasıl çalıştığını ve kendi projelerinizde nasıl kullanacağınızı anlamak istiyorsanız, bu makale bilmeniz gereken her şeyi açıklayacaktır.

OpenAI Chat Completions API, geliştiricilerin OpenAI'nin dil modellerini uygulamalara ve hizmetlere entegre etmesini sağlar. Bir mesaj dizisine göre yanıtlar üretir; konuşma, soru yanıtlama, içerik oluşturma ve metin analizi gibi görevleri destekler.

Chat Completions desteklenmeye devam ediyor. OpenAI, yeni projeler için Responses API'yi öneriyor. Bu rehber, mesaj biçimini, istek parametrelerini ve uyumlu SDK'larla kullanımını açıklamak için Chat Completions'a odaklanır.

Metin prompt alan eski Completions uç noktasının (/v1/completions) aksine, Chat Completions yapılandırılmış bir mesaj listesi kabul eder. Her mesajda, modelin talimatları ve konuşma bağlamını yorumlamasına yardımcı olan developer, user veya assistant gibi bir rol bulunur. Desteklenen roller ve içerik türleri, seçilen modele bağlıdır.

Geliştiriciler, API'yi aşağıdakiler de dâhil olmak üzere çeşitli yapay zekâ destekli özellikler oluşturmak için kullanabilir:

• Konuşma tabanlı uygulamalar: Kullanıcı mesajlarına yanıt veren yapay zekâ sohbet botları, sanal asistanlar ve müşteri destek sistemleri oluşturun.

• İçerik oluşturma: Makaleler, ürün açıklamaları, e-postalar, özetler ve diğer yazılı içerikleri oluşturun.

• Metin analizi: Metinleri sınıflandırın, bilgi çıkarın, duygu analizi yapın ve belgelerdeki kilit noktaları belirleyin.

• Kodlama desteği: Kod parçacıkları oluşturun, programlama kavramlarını açıklayın ve geliştiricilerin hataları gidermesine yardımcı olun.

• Dil işleme: Metinleri farklı diller arasında çevirin, yeniden yazın, sadeleştirin ve düzeltin.

API, dil modellerini mevcut yazılımlarla bağlamak için esnek bir yol sunarak geliştiricilerin kendi dil modellerini geliştirmeden ve barındırmadan yapay zekâ tarafından oluşturulan yanıtları uygulamalarına eklemesine olanak tanır.

Chat Completions API, istek-yanıt iş akışını izler. Bir uygulama, model tanımlayıcısı ve mesaj listesi içeren bir isteği API uç noktasına gönderir. Seçilen model girdiyi işler ve oluşturulmuş bir yanıt döndürür.

Temel iş akışı aşağıdaki adımları içerir:

1. Konuşmayı hazırlayın: Uygulama, kullanıcının girdisini toplar ve bir mesaj listesi hâlinde düzenler. Bağlam sağlamak için önceki konuşma mesajları da eklenebilir.

2. API isteği gönderin: Uygulama, seçilen model ve mesaj listesiyle birlikte https://api.openai.com/v1/chat/completions adresine POST isteği gönderir. İsteklerde Authorization: Bearer <API_KEY> başlığı kullanılır. Python SDK'sındaki client.chat.completions.create() yöntemi, bu istek yapısını ve kimlik doğrulamayı yönetir.

3. Girdiyi işleyin: Model mesajları yorumlar, rollerini ve içeriklerini dikkate alır; sağlanan bağlam ve parametrelere göre bir yanıt üretir.

4. Yanıtı alın: Akışsız bir istek, oluşturulan tamamlamayı ve meta verileri içeren bir JSON yanıtı döndürür. Akış etkinleştirildiğinde API, uygulamanın ulaştıkça işlediği bir dizi sunucu tarafından gönderilen olay (SSE) iletir.

5. Çıktıyı görüntüleyin veya işleyin: Uygulama, oluşturulan mesajı çıkarır ve kullanıcıya gösterir ya da başka bir uygulama bileşenine aktarır.

İş akışı, OpenAI Chat Completions API'nin istek ve yanıt modeline dayanır.

Chat Completions API'yi etkili bir şekilde kullanmak için geliştiricilerin başlıca istek parametrelerini ve bunların model davranışını nasıl etkilediğini anlaması gerekir.

model parametresi, isteği hangi dil modelinin işleyeceğini belirtir. Farklı modeller farklı yetenekler, yanıt hızları, muhakeme performansı ve fiyatlandırma sunabilir.

Geliştiriciler, görevin karmaşıklığına, beklenen yanıt kalitesine, gecikme gereksinimlerine ve bütçeye göre bir model seçmelidir.

messages parametresi, konuşma mesajlarından oluşan bir dizi içerir. Her mesaj genellikle role ve content alanlarını kapsar.

Yaygın roller şunlardır:

Modelinizin desteklediği talimat rolünü seçin; aynı talimatlar için hem system hem de developer mesajlarını göndermeniz gerekmez. Turlar arasında bağlamı korumak için her isteğe ilgili konuşma geçmişini ekleyin. Uyumlu sağlayıcılar farklı rolleri destekleyebilir; bu nedenle bir entegrasyonu uyarlarken kendi model belgelerini izleyin.

Bunu destekleyen modellerde ve yapılandırmalarda temperature, örnekleme rastgeleliğini kontrol eder. API referansı, varsayılanı 1 olan 0 ila 2 aralığını tanımlar. Özel bir değer ayarlamadan önce seçilen modelin parametre desteğini kontrol edin.

• Düşük sıcaklık: Daha odaklı ve öngörülebilir yanıtlar üretir; bu da onu sınıflandırma, bilgi çıkarma ve yapılandırılmış görevler için kullanışlı kılar.

• Yüksek sıcaklık: Oluşturulan metinde daha fazla çeşitliliğe olanak tanır; bu, beyin fırtınası ve yaratıcı yazım için yararlı olabilir.

Bazı muhakeme yapılandırmaları özel temperature veya top_p değerlerini kabul etmez. Bu yapılandırmalarda bu örnekleme parametrelerini kullanmayın; bunun yerine muhakeme çabası ve çıktı sınırları gibi desteklenen denetimleri kullanın.

Desteklendiği durumlarda top_p, çekirdek örnekleme yoluyla token seçimini kontrol eder. Aday token'ları belirlemek için kullanılan kümülatif olasılık eşiğini ayarlar.

Örneğin 0.1 değeri, modelin kümülatif olasılık kütlesinin en yüksek %10'u içindeki token'ları dikkate aldığı anlamına gelir. Daha düşük değerler genellikle daha odaklı çıktı üretirken, daha yüksek değerler daha fazla çeşitliliğe izin verir.

OpenAI, her ikisini aynı anda değiştirmek yerine temperature veya top_p değerlerinden birinin ayarlanmasını önerir.

max_completion_tokens parametresi, uygun olduğunda muhakeme token'ları da dahil olmak üzere modelin bir yanıtta üretebileceği maksimum token sayısını belirler.

Uygun bir sınır belirlemek, geliştiricilerin çıktı uzunluğunu kontrol etmesine ve token tüketimini yönetmesine yardımcı olur. Model, yanıtını tamamlamadan bu sınıra ulaşırsa tamamlama length bitiş nedeni ile sona erebilir.

stream parametresi, API'nin oluşturulan yanıtı tek seferde mi yoksa üretilirken aşamalı olarak mı döndüreceğini belirler.

• false: Oluşturma tamamlandıktan sonra yanıtın tamamını döndürür.

• true: Yanıt verilerini sunucu tarafından gönderilen olaylar (SSE) aracılığıyla uygulamaya aktarır.

Akış, kullanıcıların tüm çıktıyı beklemek yerine yanıtların aşamalı olarak belirdiğini görmesinin yararlı olduğu sohbet arayüzleri ve uygulamalar için kullanışlıdır.

response_format parametresi, desteklenen modellerde çıktı biçimini seçer. Varsayılan biçim metindir. type değerini json_object olarak ayarlamak, geçerli JSON üreten ancak belirli bir şemayı zorunlu kılmayan JSON modunu etkinleştirir. Mesajlara JSON döndürme talimatı ekleyin.

Öngörülebilir alanlar ve veri türleri için, uyumlu bir modelde type: "json_schema" ve strict: true ile JSON Schema tabanlı Yapılandırılmış Çıktılar'ı kullanın. Katı modda yalnızca JSON Schema'nın desteklenen alt kümesi kullanılabilir. Sonucu işlemeden önce ret yanıtı veya kesilmiş bir yanıt olup olmadığını kontrol edin. Yapılandırma ayrıntıları için Yapılandırılmış Çıktılar kılavuzuna bakın.

tool_choice parametresi, model Chat Completions aracılığıyla araç çağrısını desteklediğinde araç seçimini kontrol eder. Destek hem modele hem de modelin muhakeme yapılandırmasına bağlıdır; bazı yeni modeller araç kullanımı için Responses API gerektirir. Bir isteğe araç eklemeden önce bu gereksinimleri kontrol edin.

Yaygın ayarlar şunlardır:

• none: Modelin araç çağırmasını engeller.

• auto: Modelin kullanılabilir bir aracı çağırıp çağırmayacağına karar vermesine izin verir.

• required: Modelin bir veya daha fazla araç çağırmasını gerektirir.

Bu özellik, bir uygulamanın modelin ürettiği kararları harici işlevlere, veritabanlarına ve hizmetlere bağlamasına olanak tanıyan işlev çağrısını destekler. İstenen işlevi yürütmek ve sonucunu modele döndürmek uygulamanın sorumluluğundadır.

Parametre tanımları ve model uyumluluğu gereksinimleri için Chat Completions API referansını kullanın. Aşağıdaki Python örneği, araçlar olmadan temel bir metin isteği kullanır.

Geliştiriciler Chat Completions API'ye HTTP istekleri veya resmî bir SDK aracılığıyla erişebilir. Aşağıdaki örnekte, konuşma tabanlı bir istek göndermek ve oluşturulan yanıtı almak için Python kullanılır.

1. Adım: API anahtarı alın

OpenAI API platformunda bir API anahtarı oluşturun; hesabınızın seçilen modele erişebildiğinden ve yeterli API kredisine veya faturalandırma kapasitesine sahip olduğundan emin olun. Anahtarı uygulamanın kaynak kodu yerine bir ortam değişkeninde saklayın. macOS veya Linux'ta şunu çalıştırın:

YOUR_API_KEY yerine kendi anahtarınızı yazın. Windows'ta aynı OPENAI_API_KEY değişkenini kabuğunuzda veya sistem ortamında ayarlayın.

2. Adım: OpenAI Python SDK'sını yükleyin

Resmî Python kitaplığını pip kullanarak yükleyin:

3. Adım: API istemcisini başlatın

SDK'yı içe aktarın ve istemciyi başlatın. OpenAI(), 1. Adımda ayarlanan OPENAI_API_KEY ortam değişkenini otomatik olarak okur.

4. Adım: Sohbet tamamlama isteği gönderin

client.chat.completions.create() yöntemini bir model ve mesaj listesiyle çağırın. Bu örnekte, düşük muhakeme çabası ve toplam 4.096 token üretim sınırıyla gpt-6-astra kullanılır. Bu model hesabınız için kullanılamıyorsa Chat Completions'ı destekleyen bir model seçin ve parametreleri belgelerine uygun şekilde ayarlayın.

Bu örnekte:

• model, yanıtı oluşturmak için kullanılan dil modelini belirtir.

• messages, talimatları ve kullanıcı girdisini sağlar.

• reasoning_effort, bu parametreyi destekleyen modeller için muhakeme çabasını belirler.

• max_completion_tokens, muhakeme token'ları da dahil olmak üzere oluşturulan token'ların sayısını sınırlar. Belirli miktarda görünür metni garanti etmez.

• response.choices[0].message.content, asistanın yanıtını çıkarır.

API yanıtını işleyin

Bu akışsız istek için API, tamamlama ve istek meta verilerini içeren JSON döndürür. Python SDK bunu bir ChatCompletion nesnesine ayrıştırır; bu nedenle örnekte response.choices[0].message.content gibi öznitelikler üzerinden alanlara erişilir.

Önemli yanıt alanları şunlardır:

finish_reason alanı, geliştiricilerin bir üretimin nasıl sona erdiğini anlamasına yardımcı olabilir. Yaygın değerler arasında stop, length ve tool_calls bulunur.

Geliştiriciler, API maliyetlerini tahmin etmek ve uygulama kullanımını optimize etmek için yararlı olan giriş ve çıkış token tüketimini izlemek üzere usage alanını da inceleyebilir.

Bu örnek, temel bir metin yanıtını gösterir. Akış, yapılandırılmış çıktı veya araçlar eklerken hem istek hem de yanıt işleme mantığını seçilen modele ve uç noktaya göre güncelleyin.

OpenAI Chat Completions API alternatiflerini araştıran geliştiriciler için Kimi API, Moonshot AI'nin büyük dil modellerine OpenAI uyumlu bir API biçimiyle erişim sağlar.

Kimi; Chat Completions, Responses ve Messages arayüzleri sunar. Aşağıdaki örnek, yukarıda tanıtılan SDK iş akışını yeniden kullanabilmeniz için OpenAI uyumlu Chat Completions uç noktasını kullanır. Bir Kimi API anahtarı yapılandırın, Kimi temel URL'sini ayarlayın ve desteklenen bir model seçin. Model parametreleri, mesaj rolleri ve araç desteği için Kimi'nin kendi belgelerini izleyin.

1. Adım: Kimi API anahtarı alın

Kimi API platformuna kaydolun ve geliştirici konsolunda bir API anahtarı oluşturun. İlk isteğinizi yapmadan önce bakiyenizi, model erişiminizi ve hesap hız sınırlarını kontrol edin.

Kimi anahtarını ayrı bir ortam değişkeninde saklayın. macOS veya Linux'ta şunu çalıştırın:

YOUR_KIMI_API_KEY değerini kendi Kimi anahtarınızla değiştirin. Windows'ta aynı KIMI_API_KEY değişkenini ortamınızda ayarlayın.

2. Adım: OpenAI Python SDK'yi yükleyin

SDK henüz yüklü değilse şunu çalıştırın:

3. Adım: Kimi API istemcisini yapılandırın

Kimi temel URL'sini ve 1. Adımda ayarlanan KIMI_API_KEY değişkenini kullanarak ayrı bir kimi_client oluşturun. Anahtarı os.environ ile okumak, eksik bir ortam değişkeninin hata olarak hemen görünmesini sağlar.

4. Adım: Chat Completions isteği gönderin

Kimi istemcisiyle aynı SDK yöntemini kullanın. Bu istek kimi-k3 modelini seçer, yönergeler için Kimi'nin desteklediği system rolünü kullanır ve akışsız bir metin yanıtı döndürür.

• Farklı iş yükleri için model seçenekleri: Kimi K3.1 Pro; karmaşık akıl yürütmeyi, uzun soluklu kodlamayı ve bilgi çalışmasını destekler. Highspeed sürümü, aynı model özellikleriyle daha hızlı çıktı sunar. Yukarıdaki örnek Kimi K3 kullanır; kullanılabilirlik ve geçiş yönergeleri için güncel model listesini kontrol edin.

• OpenAI API uyumluluğu: OpenAI Chat Completions biçimine aşina geliştiriciler, Kimi modellerini entegre ederken benzer bir istek yapısını ve desteklenen SDK iş akışlarını yeniden kullanabilir.

• Çok turlu konuşmalar: Geliştiriciler, bağlama duyarlı konuşmaları, sanal asistanları ve etkileşimli uygulamaları desteklemek için mesaj geçmişleri sağlayabilir.

• Akış ve işlev çağırma: API, akışlı yanıtları ve araç çağırma iş akışlarını destekler; böylece geliştiriciler daha etkileşimli uygulamalar oluşturabilir ve modelleri harici işlevlerle bağlayabilir.

• Çok modlu girdi: Desteklenen Kimi modelleri, modelin özelliklerine bağlı olarak metin, görsel ve video dahil farklı girdi türlerini işleyebilir.

Chat Completions API ile çalışırken geliştiriciler kimlik doğrulama, API yapılandırması, model kullanılabilirliği veya istek sınırlarıyla ilgili hatalarla karşılaşabilir. Bu yaygın sorunları anlamak, problemleri belirlemenize ve entegrasyonunuzu sorunsuz şekilde çalıştırmanıza yardımcı olabilir:

• Geçersiz veya eksik API anahtarı: API anahtarı yanlış, süresi dolmuş, iptal edilmiş ya da düzgün yapılandırılmamışsa HTTP 401 gibi kimlik doğrulama hataları oluşabilir. Anahtarın geçerli olduğunu, ortam değişkeninin doğru yüklendiğini ve isteğin uygun kimlik doğrulama bilgilerini içerdiğini kontrol edin.

• Yanlış API temel URL'si: Hatalı bir uç noktaya gönderilen istekler 404 veya bağlantı hatası gibi hatalar döndürebilir. Temel URL'nin API sağlayıcısının belgeleriyle eşleştiğini ve isteğin doğru uç nokta yolunu kullandığını doğrulayın. OpenAI ile uyumlu sağlayıcılar arasında geçiş yaparken temel URL'yi buna göre güncellemeyi unutmayın.

• Geçersiz veya kullanılamayan model kimliği: Belirtilen model adı yanlışsa, hesabınız aracılığıyla kullanılamıyorsa ya da seçilen uç nokta tarafından desteklenmiyorsa istek başarısız olabilir. Sağlayıcının model belgelerini kontrol edin ve model kimliğinin API hesabınızda kullanılabilen kimlikle eşleştiğini doğrulayın.

• Bağlam uzunluğu aşıldı: Birleştirilmiş giriş mesajları ve üretilen çıktı, modelin bağlam penceresini aşarsa API isteği reddedebilir. Giriş uzunluğunu azaltın, gereksiz konuşma geçmişini kaldırın veya isteği yeniden göndermeden önce önceki mesajları özetleyin.

• Çıktı kesildi: İstenen içerik tamamlanmadan önce max_completion_tokens sınırına ulaşılırsa yanıt durabilir. Destekleniyorsa token sınırını artırın veya uzun üretim görevini daha küçük isteklere bölün. Yanıtın length sınırı nedeniyle sona erip ermediğini kontrol etmek için choices[].finish_reason alanını da inceleyebilirsiniz.

• Hız sınırı veya kota aşıldı: OpenAI için HTTP 429; istek ya da token hız sınırını, harcama sınırını veya başka bir kullanım kısıtlamasını gösterebilir. Yeniden denemeden önce hata türünü ve kodunu inceleyin. Geçici bir hız sınırı söz konusuysa istek sıklığını azaltın, sağlanmışsa Retry-After değerine uyun veya üstel geri çekilme kullanın.

Hata, kredilerin tükendiğini ya da faturalandırma veya harcama sınırına ulaşıldığını gösteriyorsa hesabın bakiyesini ve faturalandırma ayarlarını kontrol edin; tekrarlanan denemeler erişimi geri getirmez. Kimi veya başka bir uyumlu sağlayıcı kullanırken durum kodları ve kota kuralları farklı olabileceğinden, o sağlayıcının hata kodu belgelerini izleyin.

Daha verimli hata ayıklamak için, istek parametrelerinizi değiştirmeden önce API'nin döndürdüğü HTTP durum kodunu ve hata mesajını kontrol edin. Bu ayrıntılar; kimlik doğrulama sorunlarını, yapılandırma hatalarını ve kullanım sınırlarını birbirinden ayırmanıza yardımcı olabilir.

Chat Completions API, geniş bir uygulama senaryosu yelpazesini destekleyebilir. Yapılandırılmış mesaj biçimi ve özelleştirilebilir üretim parametreleri, onu hem basit metin tabanlı özellikler hem de daha karmaşık AI iş akışları için uygun kılar.

• AI sohbet botları ve sanal asistanlar: Geliştiriciler API'yi web siteleri, mobil uygulamalar ve müşteri hizmetleri platformları için konuşma tabanlı asistanlar oluşturmak üzere kullanabilir. Uygulamalar, önceki mesajları sonraki isteklere aktararak konuşma bağlamını koruyabilir ve daha ilgili yanıtlar sunabilir.

• İçerik oluşturma ve metin düzenleme: API, kullanıcı yönergelerine göre metin üretebilir ve dönüştürebilir. Uygulamalar bunu blog yazısı taslağı hazırlamak, pazarlama metni yazmak, uzun içerikleri özetlemek, paragrafları yeniden yazmak ve yazım tarzlarını farklı hedef kitlelere ve amaçlara uyarlamak için kullanabilir.

• Metin sınıflandırma ve bilgi çıkarma: İşletmeler, API'yi büyük hacimli metinleri işleyen iş akışlarına entegre edebilir. Örneğin, müşteri geri bildirimlerini sınıflandırabilir, duygu durumunu belirleyebilir, mesajlardan önemli bilgileri çıkarabilir ve yapılandırılmamış içerikleri önceden tanımlanmış kategorilere ayırabilir.

• Kodlama asistanları: API; kod oluşturarak, programlama kavramlarını açıklayarak, çözüm önererek ve geliştiricilerin hataları belirlemesine yardımcı olarak yazılım geliştirme araçlarını destekleyebilir. Uygulamalar, işlev çağrısı aracılığıyla modeli harici geliştirme araçlarına da bağlayabilir.

• Yapay zekâ destekli iş akışları: Geliştiriciler, dille ilgili tekrarlayan görevleri otomatikleştirmek için API'yi iş uygulamalarına entegre edebilir. Buna müşteri taleplerini işlemek, rapor oluşturmak, belgelerden bilgi çıkarmak ve önceden tanımlanmış talimatlara göre yanıt hazırlamak örnek verilebilir.

OpenAI Chat Completions API, geliştiricilere konuşmaya dayalı yapay zekâyı uygulamalarına dahil etmenin ve daha kullanışlı kullanıcı deneyimleri oluşturmanın pratik bir yolunu sunar. Doğru modeli seçmek, parametrelerini anlamak ve API yanıtlarını dikkatle ele almak, bir uygulamanın performansında gerçek bir fark yaratabilir. Ancak geliştiriciler, yapay zekâ destekli çözümler geliştirirken tek bir sağlayıcıya bağlı kalmak zorunda değildir. Başka bir seçeneği keşfetmek isterseniz Kimi API'yi deneyin ve OpenAI uyumlu yapısının geliştirme ihtiyaçlarınıza nasıl uyduğunu görün.