1. OpenAI Assistants API'nin Tanıtımı

1.1 Assistants API'nin Tanımı ve Amacı

Assistants API, geliştiricilere kendi uygulamaları içinde yapay zeka asistanları oluşturmalarını sağlar. Özel komutlar belirleyerek ve modeller seçerek, asistanlar kullanıcı sorularına cevap vermek için modeller, araçlar ve bilgiyi kullanabilir. Şu anda Assistants API, Kod Yorumlayıcı, Geri Çağırma ve Fonksiyon Çağırma olmak üzere üç tür aracı desteklemektedir.

1.2 Assistants API'nin Uygulama Alanları

Assistants API, etkileşimli yapay zeka desteği gerektiren çeşitli senaryolara uygundur. Örneğin:

  • Müşteri Desteği: İnsan müşteri hizmetlerinin iş yükünü azaltmak için yaygın soruları otomatik olarak yanıtlayabilir.
  • Online Eğitim: Öğrencilerin sorularını cevaplayabilir ve özelleştirilmiş öğrenme desteği sağlayabilir.
  • Veri Analizi: Kullanıcılar tarafından yüklenen veri dosyalarını analiz edebilir, raporlar oluşturabilir ve grafikleştirebilir.
  • Kişiselleştirilmiş Öneriler: Kullanıcıların geçmiş etkileşimlerine dayalı olarak kişiselleştirilmiş öneriler ve hizmetler sunabilir.

1.3 Assistants'ın Temel Kavramları

image

Assistants API'nin temel nesneleri arasında Assistant, Thread ve Message bulunmaktadır. Bu nesneler ve işlevleri hakkında detaylı tanıtımlar şunlardır:

Assistant

Assistant nesnesi, OpenAI modelleri üzerine inşa edilmiş olup yapay zeka asistanlarının araçlarını çağırabilir. Assistant'ın talimatlarını özelleştirebilir ve kişiliğini ve işlevselliğini uyarlayabilirsiniz. Örneğin, "Veri Analisti" adında "code_interpreter" aracını kullanarak veri analiz eden ve grafikler oluşturan bir Assistant oluşturabilirsiniz.

Thread

Thread nesnesi, kullanıcı ile Assistant arasındaki konuşma oturumunu temsil eder. Her kullanıcı için bir Thread oluşturabilir ve kullanıcı Assistant ile etkileşime geçtiğinde bu Thread'e mesajlar ekleyebilirsiniz. Thread nesnesi, mesaj geçmişini etkili bir şekilde depolar ve gerektiğinde mesajları modelin bağlam uzunluk sınırına uygun şekilde kırpar.

Message

Message nesnesi, kullanıcı veya Assistant tarafından oluşturulabilir. Mesajlar metin, resim ve diğer dosyaları içerebilir. Mesajlar, Thread üzerinde bir liste olarak saklanır. API'nin gerçek kullanımında, geliştiriciler kullanıcı mesajlarını Thread'e ekleyebilir ve ihtiyaç duyulduğunda Assistant'ın yanıtını tetikleyebilir.

Run

Run nesnesi, bir asistan isteğinin yürütülmesini temsil eder ve Thread içindeki mesaj içeriğine göre asistanı çağırır. Asistan, yapılandırmasını ve Thread'in mesajlarını kullanarak modelleri ve araçları çağırarak görevleri yürütür. Bir çalışmanın bir parçası olarak, asistan mesajları Thread'e ekler.

2. Assistants API Geliştirme Süreci

2.1 Asistan Oluşturma

Bir Assistant oluşturmak için, sistem talimatları, model adı ve araç yapılandırması ile birlikte API'ya bir istek göndermeniz gerekmektedir. İşte kişisel bir matematik öğretmeni asistanı oluşturmanın basit bir örneği:

curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SENİN_OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Kişisel matematik öğretmenisin. Kod yaz ve çalıştırarak matematik sorularını cevapla.",
    "name": "Matematik Öğretmeni",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4"
  }'

API parametreleri:

  • instructions - asistana ne yapması gerektiğini anlatan sistem talimatları.
  • name - asistanın adı.
  • tools - asistanın hangi araçları kullanabileceğini tanımlar. Her asistanın en fazla 128 aracı olabilir. Mevcut araç tipleri kod_yorumlayıcı, geri_çağırma veya fonksiyon olabilir.
  • model - asistan hangi modeli kullanmalı?

Assistant başarıyla oluşturulduktan sonra, bir Assistant ID alacaksınız.

2.2 Oturum Thread'i Oluşturma

Bir Thread, bir konuşmayı temsil eder ve kullanıcıların bir konuşma başlattığında her kullanıcı için bir oturum Thread'i oluşturmanızı öneririz. Bir Thread'i şu şekilde oluşturabilirsiniz:

curl https://api.openai.com/v1/threads \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d ''

Thread başarıyla oluşturulduktan sonra, bir Thread ID alacaksınız.

2.3 Konuşma Dizesine Mesaj Ekle

Bir konuşma dizesine metin ekleyebilirsiniz, bu metinleri isteğe bağlı olarak kullanıcı tarafından yüklenen dosyalarla birlikte içerebilir. Örneğin:

curl https://api.openai.com/v1/threads/{thread_id}/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SİZİN_OPENAI_API_ANAHTARINIZ" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
      "role": "user",
      "content": "Bu denklemi çözmek istiyorum: `3x + 11 = 14`. Bana yardımcı olabilir misiniz?"
    }'

API parametreleri:

  • thread_id - konuşma dizesini temsil eder, bu dizeyi oluştururken elde edebilirsiniz.

API istek gövdesi bir kullanıcı mesajıdır, genellikle kullanıcının sorusunu temsil eder, konuşma modelinin mesaj yapısıyla benzerdir.

2.4 Yardımcıyı Yanıt Oluşturmak İçin Çalıştırın

Yardımcının kullanıcı mesajlarına yanıt vermesi için bir Çalıştır oluşturmanız gerekir. Bu, yardımcının Konuşmayı okumasına ve araçları kullanıp kullanmamaya (etkinse) veya sadece sorguyu en iyi şekilde cevaplamak için modeli kullanıp kullanmamaya karar vermesine olanak tanır.

Not: Bu noktaya kadar yardımcı, kullanıcının sorusuna yanıt vermemiştir. Yalnızca Çalıştır API'sini çağırdığınızda yapay zeka yardımcısı kullanıcının sorusuna yanıt verecektir.

curl https://api.openai.com/v1/threads/{thread_id}/runs \
  -H "Authorization: Bearer SİZİN_OPENAI_API_ANAHTARINIZ" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "assistant_id": "yardımcı_id",
    "instructions": "Kullanıcıyı Jane Doe olarak adlandırın. Kullanıcı bir premium hesabıdır."
  }'

API parametreleri:

  • thread_id - konuşma dizesini temsil eder, bu dizeyi oluştururken elde edebilirsiniz.
  • assistant_id - yardımcıyı oluştururken elde edebileceğiniz yardımcı kimliğini temsil eder.
  • instructions - yardımcı talimatları, yardımcı oluşturulurken ayarlanmış talimatları geçersiz kılabilir.

Başarılı bir API isteği bir Çalıştır Kimliği döndürecektir.

2.5 Yardımcı Çalışma Durumunu Kontrol Et

Yardımcıda bir görev (Çalıştır) başlatıldıktan sonra görev yürütme asenkron bir şekilde gerçekleşir. Bu, Çalıştır'ın durumunu düzenli olarak kontrol etmemiz gerektiği anlamına gelir. Çalıştır'ın durumunu kontrol etmek için CURL kullanarak bir HTTP isteği yapılabilir. Aşağıda bu sürecin spesifik bir tanıtımı bulunmaktadır.

CURL İstek Örneği:

curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

API Parametre Açıklaması:

  • https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123: Bu, API'nin istek URL'sidir, burada thread_abc123 konuşma dizesinin benzersiz kimliğini ve run_abc123 Çalıştır'ın benzersiz kimliğini temsil eder.

Yanıt Gövdesi Örneği:

{
  "id": "run_abc123",
  "object": "konu.calistir",
  "status": "tamamlandı",
  "created_at": 1699073585,
  ...
}

API Yanıt Parametre Açıklaması:

  • id: Çalıştır'ın benzersiz kimliği.
  • object: Dönen nesnenin türünü gösterir, burada konu.calistirdir.
  • status: Çalıştır'ın durumu, olası değerler arasında sıraya alındı, devam ediyor, tamamlandı, eylem gerektiriyor, başarısız vb. bulunur.
  • created_at: Çalıştır'ın ne zaman oluşturulduğunun zaman damgasıdır.

2.6 Yardımcı Yanıt Sonuçlarını Al

Yardımcı Çalıştırı tamamlandıktan sonra, Yardımcının yanıt sonuçlarını konuşma dizesine eklenen mesajları kontrol ederek okuyabiliriz. Aşağıda CURL kullanarak API'ye istekte bulunmanın ve API parametrelerinin detaylı açıklamasının bir gösterimi bulunmaktadır.

İpucu: Bir Yardımcı ile yapılan konuşmaya benzer şekilde, Yardımcı kullanıcının sorusunu işledikten sonra bir mesajı konuşma dizesine ekleyecektir. Bu nedenle, Yardımcının yanıtını almak için konuşma dizesindeki en son mesajı sorgulamamız yeterlidir.

CURL İstek Örneği:

curl https://api.openai.com/v1/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

API Parametre Açıklaması:

  • https://api.openai.com/v1/threads/thread_abc123/messages: API'nin istek URL'si, burada thread_abc123 thread'ın (konu) benzersiz tanımlayıcısıdır.
  • Run durumunu kontrol etmek için kullanılan istek başlıkları ile aynı, içerisinde kimlik doğrulama bilgileri ve API versiyon bilgisi bulunmaktadır.

Yardımcı Cevap Örnekleri:

Bu örnekte, kullanıcı Yardımcıya bir matematik sorusu sordu ve Yardımcı bunu işledikten sonra Thread'e bir cevap Mesajı ekledi.

Kullanıcı: `3x + 11 = 14` denklemini çözmek istiyorum. Bana yardımcı olabilir misin?
Yardımcı: Tabii ki, Jane Doe. `(3x + 11 = 14)` denklemini çözmek için denklemin bir tarafında `(x)`'i yalıtmalısın. `(x)`'in değerini hesaplayayım.
Yardımcı: `(3x + 11 = 14)` denkleminin çözümü `(x = 1)`'dir.

Yardımcıdan alınan cevap sonuçları, kullanıcının Yardımcı tarafından sağlanan hizmetleri daha iyi anlamasına ve kullanmasına yardımcı olmak için kullanıcıya sunulabilir.

3. Araçlar: OpenAI Tarafından Sağlanan Dahili Araçlar

3.1 Kod Yorumlayıcı Aracı

Kod Yorumlayıcı aracı, Asistanın API'sinin Python kodunu bir kum havuzu yürütme ortamında yazmasına ve çalıştırmasına olanak tanır. Bu araç çeşitli veri ve dosya formatlarıyla başa çıkabilir ve verileri ve grafiksel görüntülerle dosyalar oluşturabilir. Kod Yorumlayıcı, Asistanınızın karmaşık kodlama ve matematik sorunlarını çözmek için kodu tekrar tekrar çalıştırmasına olanak tanır. Yardımcının yazdığı kod çalışmazsa, başarılı bir şekilde çalışacak farklı kod deneyerek bu kodu tekrarlayabilir.

Kod Yorumlayıcıyı Etkinleştirme

Kod Yorumlayıcıyı etkinleştirmek için, Asistan nesnesi oluşturulurken tools parametresinde code_interpreter geçirin:

curl https://api.openai.com/v1/assistants \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v1' \
  -d '{
    "instructions": "Kişisel bir matematik öğretmenisin. Bir matematik sorusu sorulduğunda, ona cevap vermek için kod yaz ve çalıştır.",
    "tools": [
      { "type": "code_interpreter" }
    ],
    "model": "gpt-4-turbo-preview"
  }'

Daha sonra model, kullanıcının isteğinin doğasına bağlı olarak Çalışma zamanında Kod Yorumlayıcıyı ne zaman çağıracağına karar verecektir. Bu davranışı Asistanın instructions (örneğin, "Bu problemi çözmek için kod yaz") aracılığıyla kolaylaştırabilirsiniz.

Dosyaları İşlemek İçin Kod Yorumlayıcıyı Kullanma

Kod Yorumlayıcı, dosyalardan veri ayrıştırabilir. Bu, Yardımcıya büyük miktarda veri sağlamak istediğinizde veya kullanıcıların kendi dosyalarını analiz etmelerine izin vermek istediğinizde kullanışlıdır. Kod Yorumlayıcı için yüklenen dosyaların alım için dizinlenmeyeceğini unutmayın. Alım için dizinlenen dosyalar hakkında ayrıntılı bilgi için aşağıdaki Alım Aracı bölümüne bakın.

Asistan seviyesinde iletilen dosyalar, bu Asistanla ilişkilendirilen tüm Çalışmalar tarafından erişilebilir:

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="assistants" \
  -F file="@/path/to/mydata.csv"

curl https://api.openai.com/v1/assistants \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v1' \
  -d '{
    "instructions": "Kişisel bir matematik öğretmenisin. Bir matematik sorusu sorulduğunda, kod yaz ve çalıştır.",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4-turbo-preview",
    "file_ids": ["file_123abc456"]
  }'

Kod Yorumlayıcısı Tarafından Oluşturulan Dosyaların ve Görüntülerin Okunması

Kod Yorumlayıcısı ayrıca API'de dosyaları da çıktı olarak verebilir, örneğin görüntü grafikleri, CSV ve PDF dosyaları oluşturabilir. Oluşturulan dosyaların iki türü vardır: görüntüler ve veri dosyaları (örneğin, Asistan tarafından oluşturulan verilerle bir CSV dosyası).

Kod Yorumlayıcısı bir görüntü oluşturduğunda, bu dosyayı Asistan Mesajı yanıtının file_id alanında bulup indirebilirsiniz:

{
    "id": "msg_abc123",
    "object": "thread.message",
    "created_at": 1698964262,
    "thread_id": "thread_abc123",
    "role": "assistant",
    "content": [
    {
      "type": "image_file",
      "image_file": {
        "file_id": "file-abc123"
      }
    }
  ]
  // ...
}

3.2 Geri Alma Aracı

Geri Alma Aracı, Asistanın yeteneklerini modelin dışından bilgi ekleyerek (örneğin, özel ürün bilgisi veya kullanıcı tarafından sağlanan belgeler) artırır. Dosya yüklendikten ve Asistana iletildikten sonra, OpenAI otomatik olarak belgenizi dilimler, indeksler, gömmelemeleri depolar ve kullanıcı sorularını cevaplamak için ilgili içeriği geri almaya yönelik vektör aramasını uygular.

Geri Almayı Etkinleştirme

Asistanın tools parametresinde geri almayı etkinleştirmek için retrieval geçirin:

curl https://api.openai.com/v1/assistants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Müşteri destek sohbet botusunuz. Müşteri sorularına etkili bir şekilde cevap vermek için bilgi tabanınızı kullanın.",
    "tools": [{"type": "retrieval"}],
    "model": "gpt-4-turbo-preview"
  }'

Geri Alınacak Dosyaları Yükleme

Kod Yorumlayıcısı'na benzer şekilde, dosyalar Asistan seviyesinde veya bireysel Mesaj seviyelerinde yüklenebilir.

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="assistants" \
  -F file="@/path/to/knowledge.pdf"

curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Müşteri destek sohbet botusunuz. Müşteri sorularına etkili bir şekilde cevap vermek için bilgi tabanınızı kullanın.",
    "name": "Matematik Öğretmeni",
    "tools": [{"type": "retrieval"}],
    "model": "gpt-4-turbo-preview"
    "file_ids": ["file_123abc456"]
  }'

3.3 Fonksiyon Çağırma Aracı

Sohbet Tamamlama API'si'ne benzer şekilde, Assistants API fonksiyon çağırmayı destekler. Fonksiyon çağırma, Asistana fonksiyonları tanımlamanıza ve akıllıca çağrılacak fonksiyonu ve parametrelerini geri döndürmenize olanak tanır. Bir fonksiyon çağrısı yapıldığında, Assistants API yürütmesini duraklatır ve fonksiyon çağrısının sonucunu vererek yürütmesini devam ettirebilirsiniz.

Fonksiyonları Tanımlama

Asistan oluştururken, asistanın çağırabileceği bir dizi fonksiyon tanımlayabilirsiniz. Bu fonksiyonlar, asistan nesnesi oluşturulurken açıkça belirtilmelidir. Her fonksiyonun benzersiz bir adı, açıklaması ve parametre spesifikasyonu olmalıdır.

Aşağıdaki kod, bir asistan oluştururken curl komutunu kullanarak iki fonksiyonun nasıl tanımlandığını göstermektedir:

curl https://api.openai.com/v1/assistants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Hava durumu tahmin botusun. Soruları yanıtlamak için sağlanan fonksiyonları kullan.",
    "tools": [{
      "type": "function",
      "function": {
        "name": "getCurrentWeather",
        "description": "Belirli bir konum için hava durumu koşullarını al",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "Şehir ve eyalet, mesela San Francisco, CA"},
            "unit": {"type": "string", "enum": ["c", "f"]}
          },
          "required": ["location"]
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "getNickname",
        "description": "Bir şehir için takma adı al",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "Şehir ve eyalet, mesela San Francisco, CA"}
          },
          "required": ["location"]
        }
      }
    }],
    "model": "gpt-4-turbo-preview"
  }'

Asistan tarafından çağrılan fonksiyonların okunması

Kullanıcı bir mesajı asistana gönderdiğinde ve mesajın içeriği bir fonksiyon çağrısını tetiklediğinde, bu fonksiyon çağrısının bilgilerini okumanız gerekmektedir. Bu süreçte, asistan bir gerektirir_aksiyon durumu çalıştıracaktır. Bu noktada, Run nesnesini alarak fonksiyon çağrısının detaylı bilgilerine ulaşabilirsiniz.

İşte Run nesnesini alarak fonksiyon çağrılarının bilgilerini nasıl elde edeceğinizi gösteren bir örnek:

{
  "id": "run_abc123",
  "object": "thread.run",
  "status": "gerektirir_aksiyon",
  "gerektirir_aksiyon": {
    "type": "submit_tool_outputs",
    "submit_tool_outputs": {
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "getCurrentWeather",
            "arguments": "{\"location\":\"San Francisco\"}"
          }
        },
        {
          "id": "call_abc456",
          "type": "function",
          "function": {
            "name": "getNickname",
            "arguments": "{\"location\":\"Los Angeles\"}"
          }
        }
      ]
    }
  },
  ...
}

tool_calls parametresi, fonksiyon çağrısı bilgilerini içerir ve sadece karşılık gelen fonksiyonu yerel programınızda çağırmanız gerekmektedir.

Fonksiyon çıktılarının gönderilmesi

Fonksiyon çağrısını yerel olarak yürüttükten ve sonuçları elde ettikten sonra, bu sonuçları Asistanlar asistanına göndererek asistanın kullanıcının isteğini işlemeye devam edebilmesini sağlamanız gerekmektedir. Fonksiyon çıktılarını gönderirken, çıktıların orijinal fonksiyon çağrılarıyla ilişkilendirildiğinden emin olmanız gerekmektedir.

İşte fonksiyon çıktı sonuçlarını nasıl göndereceğinize dair bir örnek kod:

curl https://api.openai.com/v1/threads/thread_abc123/runs/run_123/submit_tool_outputs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "tool_outputs": [
      {
        "tool_call_id": "call_abc123",
        "output": "{\"temperature\": \"22\", \"unit\": \"celsius\"}"
      }, 
      {
        "tool_call_id": "call_abc456",
        "output": "{\"nickname\": \"LA\"}"
      }
    ]
  }'

Parametre açıklaması:

  • thread_abc123 konuşma thread ID'sini temsil eder
  • run_123 Run nesnesinin ID'sini temsil eder
  • tool_call_id belirli bir fonksiyon çağrısının ID'sini temsil eder, bu önceki tool_calls parametresinden alınır.

Tüm fonksiyon çıktılarını başarıyla gönderdikten sonra, Run nesnesinin durumu tekrar güncellenecek ve asistan kullanıcının son isteğini işlemeye devam edecek ve nihai cevabı kullanıcıya dönecektir.