Toplantı kaydını metne çevirmek: Transify'ın asenkron iş hattını nasıl kurduk?

Bir saatlik toplantının video kaydı yüzlerce megabayt tutabilir; metne çevrilmesi, ardından çevrilip analiz edilmesi saniyeler değil dakikalar alır. Böyle bir işi “dosyayı gönder, cevabı bekle” mantığıyla tek bir HTTP isteğine sığdırmaya çalışmak, ürünün en kırılgan yeri olur. Kendi ürünümüz Transify AI'yi geliştirirken bu sorunu asenkron bir iş hattıyla çözdük. Bu yazıda, Transify'ın herkese açık API'sinde de görebileceğiniz tasarım kararlarını ve nedenlerini anlatıyoruz.

#Sorun: uzun iş, kısa istek

Transify'a API üzerinden 500 MB'a kadar ses ya da video dosyası yüklenebiliyor: MP3, WAV, M4A, OGG, MP4, MOV, MKV, AVI. Bu boyutta bir dosya işlenirken bağlantıyı açık tutmak üç ayrı yerde sorun çıkarır:

• Zaman aşımı: Tarayıcılar, vekil sunucular ve yük dengeleyiciler uzun süre yanıt gelmeyen bağlantıları keser. İş bitmek üzereyken kopan bağlantı, her şeyin baştan yapılması demektir.
• Kullanıcı davranışı: Kullanıcı sekmeyi kapatır, telefonu kilitler, ağ değiştirir. Sonucun o bağlantıya bağlı olmaması gerekir.
• Kapasite: Aynı anda gelen on dosyayı aynı anda işlemeye çalışmak yerine sıraya koymak, sunucunun ve yapay zekâ modelinin yükünü öngörülebilir kılar.

Çözüm bilinen bir kalıptır: isteği hemen kabul et, bir iş kimliği ver, işi arka planda yürüt, sonucu ayrı bir kanaldan bildir.

#İş modeli: yükle, kimliği al, sonra sor

Yükleme isteği dosyayı alır, işi kuyruğa koyar ve hemen yanıt döner. Yanıtta sonuç yoktur; yalnızca işin kimliği ve durumun sorulacağı adres vardır.

curl -X POST https://transify.averissoft.com/api/v1/transcribe \
  -H "X-Api-Key: tk_live_..." \
  -F "file=@toplanti.mp4" \
  -F "sourceLanguage=auto" \
  -F "targetLanguage=tr" \
  -F "jobType=full" \
  -F "outputFormats=txt,pdf,srt"

{
  "jobId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "queued",
  "statusUrl": "/api/v1/jobs/3fa85f64-...",
  "message": "İş kuyruğa alındı"
}

Kimliğin rastgele bir UUID olması bilinçli bir tercihtir: sıralı numaralar (1041, 1042…) hem kaç iş işlendiğini dışarı sızdırır hem de başkasının işini tahmin etmeyi kolaylaştırır. Ayrıca bir iş yalnızca onu başlatan API anahtarıyla sorgulanabilir; başka bir anahtarla sorulduğunda “bu iş size ait değil” yerine doğrudan “bulunamadı” yanıtı döner, böylece işin var olduğu bilgisi de verilmez.

#Durum makinesi: dört durum yeter

Durum sayısını az tutmak istemci tarafını sadeleştirir: completed ve failed dışındaki her durum “bekle” demektir. İçeride kaç aşama olursa olsun dışarıya verilen sözleşme aynı kalır; hatta yeni bir aşama eklendiğinde entegrasyon yapanların kodu bozulmaz.

#İşin kapsamını kullanıcı seçer

Her kayıt için çeviri ya da analiz gerekmez. Bu yüzden iş başlatılırken kapsam jobType parametresiyle belirtilir:

Aşamaları birbirinden ayırmanın iki faydası var: kullanıcı ihtiyaç duymadığı işin süresini beklemez ve her aşama ayrı ayrı izlenip yeniden denenebilir. Transify'da konuşma tanıma, çeviri ve analiz, yapay zekâ modellerine API üzerinden bağlanılarak yapılır; uygulamanın kendi işi dosyayı almak, adımları sırayla yürütmek ve sonucu toplamaktır.

#Hattın aşamaları

1. Kabul ve doğrulama: Dosya biçimi ve boyutu işe başlamadan önce kontrol edilir; desteklenmeyen biçim ya da sınırı aşan dosya kuyruğa hiç girmeden, anlaşılır bir hata koduyla reddedilir.
2. Konuşmadan metne: Whisper tabanlı konuşma tanıma. Kaynak dil belirtilmezse otomatik algılanır.
3. Çeviri (isteğe bağlı): Döküm hedef dile çevrilir; 50'den fazla dil desteklenir.
4. Analiz (isteğe bağlı): Özet, kararlar, aksiyon maddeleri ve anahtar konular çıkarılır. Ayrıntısı için: toplantıdan özet, karar ve aksiyon çıkarmak.
5. Çıktı üretimi: Aynı içerikten TXT, PDF, DOCX ve altyazı için SRT/VTT dosyaları üretilir.
6. Bildirim: Sonuç e-postayla, API kullananlara isteğe bağlı olarak webhook ile bildirilir.

#Sonucu almak: sorgulama mı, webhook mu?

İstemcinin sonucu öğrenmesinin iki yolu var. İkisi de destekleniyor, çünkü doğru oldukları durumlar farklı.

#Webhook'u güvenli hale getirmek

Webhook, dışarıdan sizin sunucunuza gelen bir istektir; adresi bilen herkes sahte bir “iş tamamlandı” bildirimi gönderebilir. Bu yüzden dört önlem birlikte çalışır:

• İmza: Her istek, zaman damgasının ve gövdenin HMAC-SHA256 imzasını X-Transify-Signature başlığında taşır. İmzalama sırrı yalnızca iki tarafta bulunur.
• Tekrar koruması: Zaman damgası 5 dakikadan eskiyse istek reddedilir; ele geçirilen eski bir bildirim yeniden gönderilemez.
• Yeniden deneme: Sunucunuz 10 saniye içinde 2xx dönmezse bildirim 30 saniye ve 5 dakika sonra tekrar gönderilir (toplam üç deneme). Başarısız işler de job.failed olayıyla bildirilir.
• Adres denetimi: Webhook adresi HTTPS olmalı ve genel bir IP'ye çözümlenmelidir. İç ağa çözümlenen adresler (127.x, 10.x, 192.168.x, 169.254.x) reddedilir; aksi halde bu özellik, sunucuya kendi iç ağına istek attırmak için kötüye kullanılabilirdi (SSRF).

import hmac, hashlib, time

def dogrula(govde: bytes, imza: str, zaman: str, sir: str) -> bool:
    # 5 dakikadan eski istekleri reddet (tekrar koruması)
    if abs(time.time() - int(zaman)) > 300:
        return False
    beklenen = hmac.new(
        sir.encode(),
        f"{zaman}.{govde.decode()}".encode(),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(f"sha256={beklenen}", imza)

Karşılaştırmanın == yerine hmac.compare_digest ile yapılması ayrıntı değildir: sabit süreli karşılaştırma, imzanın yanıt süresinden tahmin edilmesini engeller.

#Hatalar ve sınırlar da sözleşmenin parçası

İyi tasarlanmış bir API, başarılı yanıt kadar hatayı da öngörülebilir kılar. Transify'da bütün hatalar aynı biçimde döner: insanın okuyacağı bir açıklama ve programın karar vereceği sabit bir kod.

{ "error": "Dosya 500 MB sınırını aşıyor", "code": "FILE_TOO_LARGE" }

• Kimlik: MISSING_API_KEY, INVALID_API_KEY: anahtar yok, geçersiz ya da iptal edilmiş.
• Yetki: INSUFFICIENT_SCOPE: anahtarın bu uç nokta için yetkisi yok.
• Kota: RATE_LIMIT_EXCEEDED, PLAN_LIMIT_EXCEEDED, KEY_QUOTA_EXCEEDED: saatlik istek sınırı, plan sınırı ya da anahtarın kendi kotası doldu.
• Girdi: FILE_TOO_LARGE, UNSUPPORTED_FORMAT, INVALID_WEBHOOK_URL: istek daha kuyruğa girmeden reddedilir.

Saatlik istek sınırı anahtar başına uygulanır. Amacı kullanıcıyı kısıtlamak değil, tek bir hatalı döngünün herkesi etkilemesini önlemektir.

#Dosyalar ne kadar saklanır?

Toplantı kaydı hassas bir veridir; gereğinden uzun saklanan her dosya gereksiz bir risktir. Dosyalar varsayılan olarak 30 gün (720 saat) sonra otomatik silinir; Pro ve Team planlarında 24 saatte silme seçilebilir. Süresi dolan bir dosya istendiğinde API FILE_NOT_FOUND döner. Verinin nerede işlendiğini ve şirket içi kurulum seçeneğini ayrı bir yazıda anlattık: şirket içi yapay zekâ kurulumu ve KVKK.

#Hangi teknolojilerle?

Arka uç .NET (ASP.NET Core) ile yazıldı, veriler PostgreSQL'de tutuluyor, kurulum Docker ile yapılabiliyor. Konuşma tanımada Whisper, analizde MiniMax modeli kullanılıyor; ikisine de API üzerinden bağlanılıyor. API'nin makine tarafından okunabilir tanımı (OpenAPI) dokümantasyonla birlikte yayımlanıyor; Postman'e ya da kod üreteçlerine doğrudan aktarılabiliyor.

#Kendi projenizde ne zaman asenkron iş hattı gerekir?

Bu kalıp yalnızca ses dosyaları için değildir. Aşağıdakilerden biri geçerliyse, işi kullanıcının isteğinden ayırmak neredeyse her zaman doğru karardır:

• İşlem birkaç saniyeden uzun sürüyor: rapor üretimi, toplu e-posta, görüntü ya da video işleme, büyük dosya içe aktarma.
• İş, hızı sizin kontrolünüzde olmayan bir dış servise bağlı: ödeme, kargo, yapay zekâ modeli.
• Aynı anda gelen talepler kapasiteyi aşabiliyor ve sıraya konmaları gerekiyor.
• İş yarıda kalırsa güvenle yeniden denenebilmesi gerekiyor.

Benzer bir yapıyı kendi süreçlerinize kurmak isterseniz yapay zekâ çözümlerimize ve özel yazılım ve otomasyon hizmetimize göz atabilir, yayın ve izleme düzenimizi nasıl çalışıyoruz sayfasında görebilirsiniz.