Konsensüs Çalıştırmaları

Konsensüs uç noktası, aynı istemi paralel olarak N kez çalıştırır ve çoğunluğun üzerinde anlaştığı yanıtı döndürür. Bu, olgusal, analitik ve akıl yürütme görevleri için yanıt güvenilirliğini artırmak amacıyla Öz-Tutarlılık (Self-Consistency) tekniğini (Wang ve diğerleri, 2023) kullanır.

POST /ai/sessions/:sessionId/consensus

Kimlik Doğrulama: Bearer JWT
Gerekli yetki: ai.consensus.run
Yanıt türü: Senkron JSON (akışsız)

İstek

POST /ai/sessions/sess_abc123/consensus
Authorization: Bearer <token>
Content-Type: application/json

{
  "prompt": "What are the three most important considerations when designing a distributed cache?",
  "n": 3,
  "voteStrategy": "majority",
  "modelKey": "claude-sonnet-4-6"
}

Alan	Tür	Zorunlu	Açıklama
prompt	string	Evet	N kez çalıştırılacak istem.
n	integer (2–5)	Hayır	Paralel alt çalıştırmaların sayısı. Varsayılan: 3.
voteStrategy	'majority' | 'unanimous'	Hayır	Oylama kuralı. Varsayılan: 'majority'.
modelKey	string	Hayır	Kullanılacak model. En ucuz aktif modele geri döner.

Yanıt

{
  "consensusId": "cns_uuid",
  "winner": "The three most important considerations are: 1. Cache invalidation strategy...",
  "voteCount": 2,
  "totalRuns": 3,
  "agreedOnWinner": true,
  "strategy": "majority",
  "subResults": [
    {
      "runId": "run_1",
      "response": "The three most important considerations are: 1. Cache invalidation strategy...",
      "durationMs": 1842
    },
    {
      "runId": "run_2",
      "response": "When designing a distributed cache, the key factors are: cache eviction...",
      "durationMs": 2103
    },
    {
      "runId": "run_3",
      "response": "The three most important considerations are: 1. Cache invalidation strategy...",
      "durationMs": 1991
    }
  ]
}

Alan	Açıklama
consensusId	Bu konsensüs çalıştırması için benzersiz ID.
winner	Çoğu alt çalıştırmanın üzerinde anlaştığı yanıt metni.
voteCount	Kazananla eşleşen alt çalıştırmaların sayısı.
totalRuns	Denenen toplam alt çalıştırma sayısı.
agreedOnWinner	voteCount > totalRuns / 2 (çoğunluk) veya voteCount === totalRuns (oybirliği) ise true döner.
strategy	Kullanılan oylama stratejisi.
subResults	Hatalar dahil olmak üzere tüm bireysel alt çalıştırma sonuçları.

Hata Yanıtları

Durum	Neden
400	n < 2 veya n > 5, ya da istek gövdesi doğrulaması başarısız oldu.
403	ai.consensus.run yetkisi eksik.
500	Tüm alt çalıştırmalar başarısız oldu.

Kod Örnekleri

cURL

curl -X POST https://api.chainabit.com/api/v1/ai/sessions/$SESSION_ID/consensus \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What are the three most important considerations when designing a distributed cache?",
    "n": 3,
    "voteStrategy": "majority",
    "modelKey": "claude-sonnet-4-6"
  }'

JavaScript

const sessionId = process.env.SESSION_ID; // from a previous session-creation call

const response = await fetch(`${BASE_URL}/ai/sessions/${sessionId}/consensus`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompt: "What are the three most important considerations when designing a distributed cache?",
    n: 3,
    voteStrategy: "majority",
    modelKey: "claude-sonnet-4-6",
  }),
});
const data = await response.json();

Python

import requests, os

session_id = os.environ["SESSION_ID"]  # from a previous session-creation call
response = requests.post(
    f"{os.environ['BASE_URL']}/ai/sessions/{session_id}/consensus",
    headers={"Authorization": f"Bearer {os.environ['TOKEN']}"},
    json={
        "prompt": "What are the three most important considerations when designing a distributed cache?",
        "n": 3,
        "voteStrategy": "majority",
        "modelKey": "claude-sonnet-4-6",
    },
)
data = response.json()

---

Notlar

• Konsensüs senkrondur — yanıt yalnızca tüm N alt çalıştırmalar tamamlandıktan sonra döndürülür. n=3 için 5–10 saniye bekleyin.
• Kredi maliyeti yaklaşık olarak tek bir mesajın maliyetinin n × katıdır.
• agreedOnWinner = false olduğunda, kazanan çoğul yanıttır — kullanıcı arayüzünde bir "belirsiz" rozeti gösterin.
• Alt çalıştırma hataları subResults[i].error olarak dahil edilir. Oylama, başarılı çalıştırmalar üzerinden devam eder.
• Konsensüs çalıştırmaları oturum mesaj geçmişinde görünmez.

Kullanıcı Arayüzü Önerileri

• winner'ı birincil yanıt olarak gösterin.
• subResults dizisini bir karşılaştırma listesi olarak işleyen bir "Tüm çalıştırmaları göster" düğmesi sağlayın.
• agreedOnWinner = false olduğunda, görsel bir belirsizlik göstergesi görüntüleyin.
• voteCount / totalRuns değerini bir güven ölçütü olarak (ör. "2/3 kabul etti") görüntüleyin.