OpenAI Uyumlu Arayüz Güncellemesi: Claude için Derin Destek

OpenAI uyumlu arayüzü, özellikle Claude serisi modelleri için daha derin optimizasyonlarla güncelledik. Artık düşünme ve önbellekleme işlemlerini daha hassas ve pratik bir şekilde kontrol edebilirsiniz. Çoklu dönüşlü sohbetlerde iç içe düşünme, ek parametre olmadan sorunsuz entegrasyon sağlayarak daha kullanıcı dostu hale geldi. Ayrıca, Anthropic tarafından sunulan beta özelliklerin etkinleştirilmesini de desteklemektedir.

1. Model Düşünme (Genişletilmiş Düşünme)

1.1 İç İçe Düşünmenin Avantajları

İç içe düşünme etkinleştirilmediğinde, model yalnızca bir asistan dönüşünün başında düşünme yapar; sonraki yanıtlar, yeni düşünme blokları üretmeden, araç sonuçları alındıktan hemen sonra üretilir:

User → [Thinking] → Tool Call → Tool Result → Response

İç içe düşünme etkinleştirildiğinde, model her araç sonucu aldığında yeni bir düşünme bloğu ekler ve bir akıl yürütme zinciri oluşturur:

User → [Thinking] → Tool Call → Tool Result → [Thinking] → Response
                                                ↑ İç İçe Düşünme

Bu, modelin:

• Araç sonuçlarına dayalı ikincil akıl yürütme yapmasını, yalnızca çıktıları birleştirmek yerine sağlar.
• Birden fazla araç çağrısı arasında akıl yürütme zinciri oluşturmasını, her kararın bir önceki adımın analizi temelinde verilmesini sağlar.

Referans: Anthropic İç İçe Düşünme

1.2 Düşünmeyi Etkinleştirme

Düşünmeyi dört şekilde etkinleştirebilirsiniz, bunlardan birini seçerek:

Öncelik (birden fazla yöntem kullanıldığında): reasoning_effort > reasoning.max_tokens > reasoning.effort > -think eki

Çaba için olası değerler: minimal / low / medium / high / xhigh

1.3 Düşünme Yanıtı

Yanıt mesajı iki yeni alan içerecektir:

• reasoning_content: Düşünme içeriği (string), kolay görüntüleme için.
• reasoning_details: Düşünme hakkında tam yapılandırılmış bilgi, çoklu dönüşlü sohbetlerde olduğu gibi olduğu gibi döndürülmesi gereken; iç yapı sağlayıcılara göre farklılık gösterebilir.

Akış olmayan örnek (ilişiksiz alanlar hariç):

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Merhaba! Bugün size nasıl yardımcı olabilirim?",
      "reasoning_content": "Kullanıcı sadece merhaba diyor...",
      "reasoning_details": {
        "type": "thinking",
        "thinking": "Kullanıcı sadece merhaba diyor...",
        "signature": "Er8CCkYI..."
      }
    }
  }]
}

Akış yanıtlarında, düşünme içeriği delta.reasoning_content ve delta.reasoning_details aracılığıyla parçalar halinde gönderilecektir. Tam akış birleştirme mantığı için aşağıdaki tam örneğe bakın.

1.4 Çoklu Dönüşlü Sohbetlerde Düşünmeyi Koruma (İç İçe Düşünme yerleşik, ek parametre gerekmez)

Modelin çoklu dönüşlü sohbetlerde akıl yürütme yeteneklerini sürdürmesini sağlamak için, önceki döndürülen reasoning_details olduğu gibi bir sonraki turdaki asistan mesajına yerleştirmeniz yeterlidir:

messages = [
    {"role": "user", "content": "Boston'da hava nasıl?"}, 
    {
        "role": "assistant",
        "content": response.choices[0].message.content,
        "tool_calls": response.choices[0].message.tool_calls,
        "reasoning_details": response.choices[0].message.reasoning_details,
    },
    {
        "role": "tool",
        "tool_call_id": "toolu_xxx",
        "content": '{"temperature": 45, "condition": "rainy"}',
    }
]

AIHubMix, istekte tarihsel düşünme bilgilerini tespit ettiğinde otomatik olarak iç içe düşünmeyi etkinleştirecektir, böylece model, araç çağrısı sonuçlarını aldıktan sonra derin akıl yürütmeye devam edebilir ve ek parametre gerektirmez.

1.5 Tam Örnek

Aşağıdaki iki örnek, tam çoklu dönüşlü Araç Çağrısı + iç içe düşünme sürecini göstermektedir: kullanıcı sorgusu → model düşünür ve bir aracı arar → araç sonuçlarını enjekte etme ( reasoning_details koruyarak) → model iç içe düşünme son yanıtı verir.

Akış olmayan · İç İçe Düşünme

import os
import json
from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key=os.environ.get("AIHUBMIX_API_KEY", "sk-***"),
)

# ── Araç tanımı ───────────────────────────────────────────
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Bir yerin güncel hava durumunu al",
        "parameters": {
            "type": "object",
            "properties": {"location": {"type": "string", "description": "Şehir adı"}},
            "required": ["location"]
        }
    }
}]

# ── Mock araç yürütme ───────────────────────────────────────
WEATHER_DB = {
    "boston": {"temperature": "45°F (7°C)", "condition": "rainy", "humidity": "85%", "wind": "15 mph NE"},
    "tokyo":  {"temperature": "72°F (22°C)", "condition": "sunny", "humidity": "45%", "wind": "5 mph S"},
}

def execute_tool(name: str, args: dict) -> str:
    if name == "get_weather":
        key = next((k for k in WEATHER_DB if k in args.get("location", "").lower()), None)
        return json.dumps(WEATHER_DB.get(key, {"temperature": "65°F", "condition": "clear"}))
    return "{}"

# ── Çoklu dönüşlü sohbet döngüsü ─────────────────────────────
messages = [
    {"role": "user", "content": "Boston'da hava nasıl? Sonra ne giymemi öner."}
]

turn = 0
while True:
    turn += 1
    print(f"\n── Dönüş {turn} ──")

    response = client.chat.completions.create(
        model="claude-sonnet-4-5",
        messages=messages,
        tools=tools,
        extra_body={"reasoning": {"max_tokens": 2000}},
    )
    msg = response.choices[0].message

    # Düşünme sürecini yazdır
    if msg.reasoning_content:
        label = "İç İçe Düşünme" if turn > 1 else "Düşünme"
        print(f"[{label}] {msg.reasoning_content}")

    # Yanıt içeriğini yazdır
    if msg.content:
        print(f"[Yanıt] {msg.content}")

    # Araç çağrılarını yazdır
    if msg.tool_calls:
        for tc in msg.tool_calls:
            print(f"[Araç Çağrısı: {tc.function.name}] {tc.function.arguments}")

    # Asistan mesajını oluştur, reasoning_details'i koru (kritik!)
    assistant_msg = {"role": "assistant", "content": msg.content}
    if msg.tool_calls:
        assistant_msg["tool_calls"] = msg.tool_calls
    if msg.reasoning_details:
        assistant_msg["reasoning_details"] = msg.reasoning_details  # değiştirilmeden geri geçir
    messages.append(assistant_msg)

    # Araç çağrısı yoksa sohbet tamamlandı demektir
    if not msg.tool_calls:
        break

    # Araçları yürüt ve sonuçları mesajlara ekle
    for tc in msg.tool_calls:
        args = json.loads(tc.function.arguments)
        result = execute_tool(tc.function.name, args)
        print(f"[Araç Sonucu: {tc.function.name}] {result}")
        messages.append({"role": "tool", "tool_call_id": tc.id, "content": result})

Akış · İç İçe Düşünme

import os
import sys
import json
from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key=os.environ.get("AIHUBMIX_API_KEY", "sk-***"),
)

# ── Araç tanımı & mock yürütme ─────────────────────────
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Bir yerin güncel hava durumunu al",
        "parameters": {
            "type": "object",
            "properties": {"location": {"type": "string", "description": "Şehir adı"}},
            "required": ["location"]
        }
    }
}]

WEATHER_DB = {
    "boston": {"temperature": "45°F (7°C)", "condition": "rainy", "humidity": "85%", "wind": "15 mph NE"},
    "tokyo":  {"temperature": "72°F (22°C)", "condition": "sunny", "humidity": "45%", "wind": "5 mph S"},
}

def execute_tool(name: str, args: dict) -> str:
    if name == "get_weather":
        key = next((k for k in WEATHER_DB if k in args.get("location", "").lower()), None)
        return json.dumps(WEATHER_DB.get(key, {"temperature": "65°F", "condition": "clear"}))
    return "{}"

# ── Akış yanıtı toplayıcı ────────────────────────────────
def stream_and_collect(turn: int, **kwargs):
    """Yanıtı akışla gönder, düşünmeyi/içeriği gerçek zamanlı yazdır, reasoning_details/tool_calls'ı biriktir."""
    rd = {}            # birikmiş reasoning_details
    content = ""       # birikmiş yanıt metni
    tc_map = {}        # birikmiş tool_calls (indeksle)
    cur = "none"       # mevcut çıktı bölümü: none / thinking / content

    stream = client.chat.completions.create(stream=True, **kwargs)
    for chunk in stream:
        if not chunk.choices:
            continue
        delta = chunk.choices[0].delta

        # ── Düşünmeyi ele al ──
        rd_delta = getattr(delta, "reasoning_details", None)
        if rd_delta and isinstance(rd_delta, dict):
            for k, v in rd_delta.items():
                if k == "type":
                    rd[k] = v
                elif isinstance(v, str):
                    rd[k] = rd.get(k, "") + v
                elif v is not None:
                    rd[k] = v
            # Düşünme parçalarını gerçek zamanlı yazdır
            thinking_chunk = rd_delta.get("thinking", "")
            if thinking_chunk:
                if cur != "thinking":
                    cur = "thinking"
                    label = "İç İçe Düşünme" if turn > 1 else "Düşünme"
                    sys.stdout.write(f"\n[{label}] ")
                sys.stdout.write(thinking_chunk)
                sys.stdout.flush()

        # ── İçeriği ele al ──
        if delta.content:
            if cur != "content":
                if cur == "thinking":
                    sys.stdout.write("\n")
                cur = "content"
                sys.stdout.write("\n[Yanıt] ")
            sys.stdout.write(delta.content)
            sys.stdout.flush()
            content += delta.content

        # ── Araç çağrılarını ele al ──
        for tc in delta.tool_calls or []:
            i = tc.index
            if i not in tc_map:
                tc_map[i] = {"id": "", "type": "function",
                             "function": {"name": "", "arguments": ""}}
            if tc.id:
                tc_map[i]["id"] = tc.id
            if tc.function:
                tc_map[i]["function"]["name"] += tc.function.name or ""
                tc_map[i]["function"]["arguments"] += tc.function.arguments or ""

    # Mevcut çıktı bölümünü sonlandır
    if cur in ("thinking", "content"):
        sys.stdout.write("\n")

    tool_calls = [tc_map[i] for i in sorted(tc_map)] if tc_map else None
    return {
        "content": content or None,
        "reasoning_details": rd or None,
        "tool_calls": tool_calls,
    }

# ── Çoklu dönüşlü sohbet döngüsü ─────────────────────────────
messages = [
    {"role": "user", "content": "Boston'da hava nasıl? Sonra ne giymemi öner."}
]

turn = 0
while True:
    turn += 1
    print(f"\n── Dönüş {turn} ──")

    result = stream_and_collect(
        turn,
        model="claude-sonnet-4-5",
        messages=messages,
        tools=tools,
        extra_body={"reasoning": {"max_tokens": 2000}},
    )

    # Araç çağrılarını yazdır
    if result["tool_calls"]:
        for tc in result["tool_calls"]:
            print(f"[Araç Çağrısı: {tc['function']['name']}] {tc['function']['arguments']}")

    # Asistan mesajını oluştur, reasoning_details'i koru (kritik!)
    assistant_msg = {"role": "assistant", "content": result["content"]}
    if result["tool_calls"]:
        assistant_msg["tool_calls"] = result["tool_calls"]
    if result["reasoning_details"]:
        assistant_msg["reasoning_details"] = result["reasoning_details"]  # değiştirilmeden geri geçir
    messages.append(assistant_msg)

    # Araç çağrısı yoksa sohbet tamamlandı demektir
    if not result["tool_calls"]:
        break

    # Araçları yürüt ve sonuçları mesajlara ekle
    for tc in result["tool_calls"]:
        args = json.loads(tc["function"]["arguments"])
        tool_result = execute_tool(tc["function"]["name"], args)
        print(f"[Araç Sonucu: {tc['function']['name']}] {tool_result}")
        messages.append({"role": "tool", "tool_call_id": tc["id"], "content": tool_result})

1.6 Düşünme Yoğunluğu Eşleme Kuralları

Çaba Modu:

• Opus 4.6 / Sonnet 4.6 ve üzeri: Anthropic'in yerel Uyarlanabilir Düşünme çaba seviyesine eşlenir.
• Diğer modeller: budget_tokens formülü kullanılarak hesaplanır:

budget_tokens = max(min(max_tokens × effort_ratio, 128000), 1024)

Uyarlanabilir Düşünme Çaba Eşleme:

max_tokens Modu: Doğrudan Anthropic'in budget_tokens olarak atanır.

-think ek: Opus/Sonnet 4.6+ uyarlanabilir düşünmeyi kullanır (çaba=medium); diğer modellerde budget_tokens = min(10240, max_tokens - 1) olarak ayarlanır ve varsayılan max_tokens 4096'dır.

2. İstem Önbellekleme

Claude modeline Chat arayüzü aracılığıyla istek yaparken İstem Önbellekleme kullanabilirsiniz. Mesajlarda cache_control kesme noktaları ayarlayarak, büyük metin blokları (rol kartları, RAG verileri, kitap bölümleri vb.) yeniden kullanım için önbelleğe alınabilir, böylece sonraki istekler doğrudan önbelleğe ulaşabilir ve maliyetleri önemli ölçüde azaltabilir.

Claude Resmi Belgelendirmesi: İstem Önbellekleme

2.1 Önbellek Maliyetleri

2.2 Desteklenen Modeller ve Minimum Önbellek Uzunluğu

Kesme Noktası Miktar Sınırı: Her istekte en fazla 4 cache_control kesme noktası.

2.3 Önbellek TTL

1 saatlik TTL için yazma maliyetleri daha yüksektir, ancak uzun oturumlarda tekrar eden yazmaları azaltarak toplam masrafları tasarruf edebilir. Claude 4.5 ve sonraki tüm modeller (Anthropic, Amazon Bedrock, Google Vertex AI dahil) 1 saatlik TTL'yi desteklemektedir.

2.4 Kullanım

Önbellek kesme noktalarını system, user (görüntüler dahil) ve tools alanında cache_control alanını kullanarak ayarlayabilirsiniz. Aşağıdaki örnekler yalnızca anahtar yapısını göstermektedir, büyük metin blokları hariç tutulmuştur.

Sistem Mesajı Önbellekleme (varsayılan 5 dakikalık TTL):

{
  "model": "claude-opus-4-5",
  "messages": [
    {
      "role": "system",
      "content": [
        {"type": "text", "text": "Bir AI asistanısınız"},
        {
          "type": "text",
          "text": "(uzun bağlam)",
          "cache_control": {"type": "ephemeral"}
        }
      ]
    },
    {
      "role": "user",
      "content": [{"type": "text", "text": "Merhaba"}]
    }
  ]
}

Kullanıcı Mesajı Önbellekleme (1 saatlik TTL):

{
  "model": "claude-opus-4-5",
  "messages": [
    {
      "role": "system",
      "content": [{"type": "text", "text": "Bir AI asistanısınız"}]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "(uzun bağlam)",
          "cache_control": {"type": "ephemeral", "ttl": "1h"}
        },
        {"type": "text", "text": "Merhaba"}
      ]
    }
  ]
}

Görüntü Mesajı Önbellekleme:

{
  "role": "user",
  "content": [
    {
      "type": "image_url",
      "image_url": {"detail": "auto", "url": "data:image/jpeg;base64,/9j/4AAQ..."},
      "cache_control": {"type": "ephemeral"}
    },
    {"type": "text", "text": "Bu nedir?"}
  ]
}

Araç Tanımı Önbellekleme:

cache_control araç nesnesinin en üst seviyesinde ( type ve function ile birlikte) yer alır:

{
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Bir yerin güncel hava durumunu al",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    },
    "cache_control": {"type": "ephemeral", "ttl": "1h"}
  }]
}

2.5 Önbellek Durumunu Görüntüleme

Yanıtın usage alanı claude_cache_tokens_details döndürecektir ve detaylı önbellek bilgilerini kaydedecektir:

İlk İstek (Önbellek Oluşturma):

{
  "usage": {
    "prompt_tokens": 22,
    "completion_tokens": 890,
    "total_tokens": 912,
    "claude_cache_tokens_details": {
      "cache_creation_input_tokens": 6266,
      "cache_read_input_tokens": 0,
      "cache_write_5_minutes_input_tokens": 6266,
      "cache_write_1_hour_input_tokens": 0
    }
  }
}

Sonraki İstekler (Önbellek Vuruşu):

{
  "usage": {
    "prompt_tokens": 22,
    "completion_tokens": 810,
    "total_tokens": 832,
    "prompt_tokens_details": {
      "cached_tokens": 6266
    },
    "claude_cache_tokens_details": {
      "cache_creation_input_tokens": 0,
      "cache_read_input_tokens": 6266,
      "cache_write_5_minutes_input_tokens": 0,
      "cache_write_1_hour_input_tokens": 0
    }
  }
}

3. Anthropic-beta için İstek Başlığı

Claude modelinin beta özelliklerini anthropic-beta HTTP Başlığı aracılığıyla etkinleştirebilirsiniz; bu, AIHubMix tarafından Anthropic API'sine iletilecektir.

Kullanım

İstek başlığına anthropic-beta ekleyin, değeri ilgili beta özellik tanımlayıcısı olsun:

curl "https://aihubmix.com/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "anthropic-beta: context-1m-2025-08-07" \
  -d '{
  "model": "claude-opus-4-5",
  "messages": [
    {
      "role": "system",
      "content": [
        {"type": "text", "text": "Bir AI asistanısınız"},
        {
          "type": "text",
          "text": "(uzun bağlam)",
          "cache_control": {"type": "ephemeral"}
        }
      ]
    },
    {"role": "user", "content": [{"type": "text", "text": "merhaba"}]}
  ]
}'

Mevcut beta tanımlayıcıları için lütfen Anthropic API Belgeleri'ne bakın.

Son güncelleme: 2026-06-01