Kaynaklar · Çıktı Sözleşmeleri

Birleşik Çıktı Sözleşmeleri

Metin, ses, görüntü ve video sağlayıcıları arasında yanıtların tutarlı kalmasını sağlayan üretim sözleşmesi.

Kanonik Yanıt Sözleşmesi

{
  "success": true,
  "content": "Primary human-readable output",
  "provider": "openai",
  "usage": {
    "input_tokens": 120,
    "output_tokens": 64
  },
  "metadata": {
    "model": "gpt-x",
    "latency_ms": 540,
    "trace_id": "trc_123"
  },
  "images": [],
  "files": [],
  "videos": []
}

Tasarım İlkeleri

Tüm modaliteler ve sağlayıcılar için tek bir yapı.
Alan adları çalışma zamanı sürümleri arasında sabit kalır.
Sağlayıcıya özel ayrıntılar metadata'da tutulur; üst seviye yapıda sapma olmaz.
Eksik modalite çıktıları yapı değişikliğine yol açmaz; boş diziler döner.
success bayrağı deterministik istemci işleyişi için zorunludur.

Alan Referansı

success: işlem sonucunu gösteren boolean değer.
content: birincil, insan tarafından okunabilir çıktı.
provider: normalleştirilmiş sağlayıcı tanımlayıcısı.
usage: normalleştirilmiş faturalama nesnesi.
metadata: tanılama ve yürütme bağlamı.
images/files/videos: modaliteye ait çıktı dizileri.
error: success=false olduğunda yapılandırılmış hata nesnesi.

Çok Sağlayıcılı Örnekler

OpenAI tarzı normalize edilmiş yanıt

{
  "success": true,
  "content": "Generated response",
  "provider": "openai",
  "usage": { "input_tokens": 90, "output_tokens": 52 },
  "metadata": { "latency_ms": 480 },
  "images": [],
  "files": [],
  "videos": []
}

Replicate tarzı normalize edilmiş yanıt

{
  "success": true,
  "content": "Image generation completed",
  "provider": "replicate",
  "usage": { "input_tokens": 0, "output_tokens": 0 },
  "metadata": { "duration_ms": 2300 },
  "images": [{ "url": "https://..." }],
  "files": [],
  "videos": []
}

İstemci Uyumluluk Kuralları

Ön uç render mantığı, sağlayıcı iç detaylarına değil yanıt zarfının yapısına bağlı olmalıdır.
İstemciler, ileriye dönük uyumluluk için bilinmeyen metadata anahtarlarını göz ardı edebilmeli.
Uygulanamaz modaliteler için boş diziler geçerli çıktılardır.
Ayrıştırma, sağlayıcıya özel dallanma yerine açık alan kontrollerini tercih etmelidir.

Hata Sözleşmesi

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request payload",
    "details": {}
  },
  "provider": "system",
  "metadata": {
    "trace_id": "trc_123"
  }
}

Hata yükü, makine tarafından okunabilir bir kod ve insan tarafından okunabilir bir mesaj içermelidir.
Tanılama için iz (trace) tanımlayıcıları iletilmelidir.
success=false yanıtları, sadece başarı yüküne ait alanları asla yeniden kullanmamalıdır.
HTTP durum kodu ile yapılandırılmış hata kodu tutarlı olmalıdır.