Sohbet API'si

POST /chat/completions, bir istemi girdi filtrelerinden geçirir, sağlayıcıyı çağırır, yanıtı çıktı filtrelerinden geçirir ve sonucu bir Server-Sent Events (SSE) akışı olarak döndürür.

Uç nokta

İstek gövdesi

Doğrulama beyaz liste ile çalışır: bu tabloda yer almayan bir alan, hata verilmeden gövdeden temizlenir. Yanlış yazılmış bir temperture, varsayılan sıcaklıkta başarılı bir çağrı üretir.

Mesaj biçimi

role değeri system, user veya assistant'tır. content ya bir metin ya da içerik parçalarından oluşan bir dizidir.

{ "role": "user", "content": "Message content" }

{
  "role": "user",
  "content": [
    { "type": "text", "text": "What is in this image?" },
    { "type": "image_url", "image_url": { "url": "data:image/png;base64,iVBORw0KG…", "detail": "auto" } }
  ]
}

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Summarise this contract" },
    { "type": "document", "document": { "data": "JVBERi0xLjQK…", "type": "pdf", "name": "contract.pdf" } }
  ]
}

Bir document parçasının type değeri pdf, docx, txt, csv veya xlsx olabilir. Görüntü ve belge içeriği, metin gibi, modele ulaşmadan önce denetlenir ve redakte edilir.

Örnek istek

curl -N -sS -X POST "https://<appliance-fqdn>/chat/completions" \
  -H "Authorization: Bearer cid_key_0123456789abcdef…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "provider": "openai",
    "messages": [
      { "role": "system", "content": "You are a helpful customer service agent." },
      { "role": "user", "content": "My name is John Smith and my email is john@example.com" }
    ]
  }'

İstemcinin aldığı şey — alışverişin tamamı, sırasıyla:

data: {"type":"token_usage","usage":{"prompt_tokens":320,"completion_tokens":12,"total_tokens":332}}

data: {"id":"filtered-response","content":"Hello. How can I help you today?","finish_reason":"stop","filtered":false,"entities_masked":0}

data: [DONE]

Ad ve e-posta, sağlayıcı görmeden önce maskelenmiştir; ancak bu maskelemeyi bildiren olay bu uç noktada iletilmez. Neyin tespit edildiğini görmek için kontrol panelinde Tespit ve Filtreleme → Tüm Tespitler bölümünü açın veya aynı metni tespitleri eşzamanlı döndüren POST /api/v1/guardrails/detect adresine gönderin.

SSE sözleşmesi

Sağlayıcı token farklarını akıtır. CID222 bunların hepsini tüketir, metni biriktirir, yanıtın tamamı üzerinde çıktı filtrelemesini çalıştırır ve ancak ondan sonra cevabı bağlantınıza yazar. Bu nedenle istemci şunu görür: isteğe bağlı kontrol olayları, üretim süresi boyunca sessizlik, tek bir içerik olayı ve data: [DONE].

Her satır data: ile başlar, tek bir JSON nesnesi taşır ve satırlar boş satırla ayrılır. Akış her zaman data: [DONE] ile biter.

Olaylar, görünebilecekleri sırayla

İlk iki olay LLM inceleme kilit kapısından gelir ve yalnızca bir inceleme kullanıcıyı kilitlediğinde veya bekleyen bir uyarı bıraktığında görünür. 4 ile 6 arasındaki olaylar yalnızca model yönlendirmesi veya istem sıkıştırması etkinken görünür. 3. olay yalnızca istek documents taşıdığında görünür. 9a ve 9b'den tam olarak biri gerçekleşir; 9c, 9b'yi izleyebilir.

Sekizinci ve dokuzuncu olayların sırasına dikkat edin: token_usage, yanıt hâlâ arabelleğe alınırken iletilir; bu nedenle cevaptan sonra değil, önce gelir.

Nasıl okunur

Model metnini taşıyan tek olay bir type ile değil, "id":"filtered-response" ile tanımlanır. Bunu eşleştirin:

if event.get("id") == "filtered-response":
    answer = event["content"]      # yanıtın tamamı, tam olarak bir kez

content alanını olaylar boyunca biriktirmeyin. Yalnızca bir tane vardır.

token_usage çeşitleri

usage her zaman prompt_tokens, completion_tokens ve total_tokens taşır. İstem önbelleği rakamlarını, bunları bildiren sağlayıcılar kendi alan adlarıyla ekler: OpenAI'de cached_input_tokens, Anthropic'te cache_read_input_tokens ve cache_creation_input_tokens. Bunları savunmacı biçimde okuyun.

Var olmayan olaylar

Bunlardan herhangi birini bekleyen bir istemci yazmayın — hiçbirini üreten yoktur:

• content_block_delta, delta.text, message_stop, chatcmpl-… artımlı kimlikleri ve her türlü OpenAI veya Anthropic akış çerçevesi.
• input_rejected. Girdi reddetme olayı content_rejected'tır.
• hallucination. Bağlam doğrulama kontrolü, yanıt döndürüldükten sonra arka planda çalışır. Bir tespit kaydı ve bir oturum uyarısı yazar; akışa hiçbir zaman ulaşmaz.

Var olan ama burada iletilmeyen olaylar

• İstemde neyin maskelendiğini bildiren user_message_processed, dahili olarak üretilir ve /chat/completions üzerinde orkestratör tarafından yutulur. POST /sessions/:id/messages üzerinde iletilir.
• Her token başına sağlayıcı parçası, sağlayıcının kendi finish_reason parçası ve sağlayıcının kendi [DONE] çerçevesi.

Engellenen içerik

Politika engeli bir HTTP hatası değildir. Yanıt durumu 200'dür ve engel bir olay olarak gelir; bu nedenle yalnızca durum koduna bakan bir istemci başarı görür.

Engellenen girdi — sağlayıcı hiç çağrılmaz ve sağlayıcı token'ı harcanmaz:

data: {"error":"Content contains prohibited information","type":"content_rejected","entities":[{"type":"jailbreak","action":"reject","confidence":0.96}]}

data: [DONE]

Engellenen çıktı — model bir yanıt üretti, ancak çıktı filtresi onu döndürmeyi reddetti:

data: {"type":"token_usage","usage":{"prompt_tokens":88,"completion_tokens":140,"total_tokens":228}}

data: {"type":"output_content_rejected","severity":"critical","message":"🚫 Response blocked due to policy violations","reason":"Credit card detected in response","entities_detected":1,"actions_applied":["reject"]}

data: [DONE]

Ele alınmamış bir sunucu hatasında denetleyici data: {"error":"An error occurred"} yazar ve akışı kapatır.

Desteklenen modeller

model, kiracınızın etkin sağlayıcı kimlik bilgisine sahip olduğu her modeli kabul eder. Güncel liste için GET /models çağırın. Ürünle gelen katalog şudur:

openai ve azure_openai, gpt-4o, gpt-4o-mini ve gpt-4-turbo modellerinin ikisini de kaydeder. Hangisini kastettiğinizi belirtmek için model ile birlikte provider gönderin. Azure'un GPT-3.5 dağıtımı, noktasız biçimde gpt-35-turbo'dur.

Hatalar

Bu uç noktada 429 yoktur: /chat/completions hız sınırlı değildir.

Diğer sohbet uç noktaları

İlgili

• API genel bakış — yüzeyler genelinde temel yollar, kimlik bilgileri ve hata biçimleri.
• Oturumlar API'si — sunucu tarafında konuşma durumuyla aynı pipeline.
• İçerik tespiti — bir sağlayıcı çağırmadan metin tarama.