DEV Community

Cover image for DeepSeek V4 Pro API ile Fonksiyon Çağırma Nasıl Kullanılır
Tobias Hoffmann
Tobias Hoffmann

Posted on Originally published at apidog.com

DeepSeek V4 Pro API ile Fonksiyon Çağırma Nasıl Kullanılır

DeepSeek, 12 Ağustos 2026'da V4 Pro'yu ön izlemeden çıkardı ve lansman haberleri ajans iş akışlarına odaklanıyor: kodlama, araç kullanımı ve onlarca adımı birbirine bağlayan uzun süreli görevler. Bu konumlandırmada öne çıkan API özelliği fonksiyon çağırmadır. Çoğu eğitim sohbet tamamlamalarında kalırken, bu rehber üretime yakın bir araç döngüsünü kurmaya odaklanır.

Apidog'u bugün deneyin

Bu rehberde bir araç şeması tanımlayacak, standart Python openai SDK'sıyla ilk araç çağrınızı yapacak, tam aracı döngüsünü kuracak ve yayınlamadan önce her şeyi Apidog'da test edeceksiniz. Henüz DeepSeek API anahtarınız yoksa, DeepSeek V4 API'yi nasıl kullanacağınıza dair rehberle anahtarınızı oluşturup buraya dönebilirsiniz.

Özetle

  • deepseek-v4-pro (GA yapısı DeepSeek-V4-Pro-0813), OpenAI tarzı fonksiyon çağırmayı destekler: bir tools dizisi gönderin, tool_calls alın ve sonuçları tool mesajları olarak geri gönderin.
  • Standart openai SDK, https://api.deepseek.com temel URL'siyle çalışır.
  • Tam araç döngüsü yaklaşık 30 satır Python kodundan oluşur: model araç istemeyi bırakana kadar çağırın, yürütün, sonucu ekleyin ve tekrarlayın.
  • Paralel çağrılar ve yapılandırılmış çıktılar desteklenir. Düşünme modu reasoning_content alanını ekler.
  • Otomatik ön ek önbellekleme, önbellek isabetlerinde girdi maliyetini milyon jeton başına 0.003625 dolar seviyesine indirir. Bu, derin aracı döngülerini daha uygun maliyetli hale getirir.
  • Araç çağırma kalitesi, araç şemalarınıza, istem iskelenize ve çalışma zamanınıza göre değişebilir. Karşılaştırma testleri yerine gerçek araçlarınızı canlı modele karşı test edin.

Neden araç çağırma V4 Pro'nun ana kullanım senaryosu?

DeepSeek, V4 Pro'yu aracılar için geliştirdi. Teknik özellikler, bir aracı çalışma zamanı kontrol listesi gibi okunur:

Özellik DeepSeek V4 Pro
Mimari Seyrek MoE: Toplam 1.6T parametre, jeton başına aktif 49B
Bağlam penceresi 1M jeton
Maksimum çıktı 384K jeton
Girdi fiyatı $0.435/M jeton (önbellek kaçırma), $0.003625/M (önbellek isabeti)
Çıktı fiyatı $0.87/M jeton
Fonksiyon çağırma OpenAI uyumlu tools dizisi ve tool_calls yanıtları
Diğer arayüzler Anthropic Mesajlar formatı, DeepSeek Yanıtlar API'si

Bu özellikler aracı iş akışlarındaki doğrudan sorunlara karşılık gelir:

  • 1M jeton bağlam penceresi, uzun süren araç-sonuç geçmişini taşır.
  • 384K jeton çıktı sınırı, büyük yapılandırılmış yükler için alan bırakır.
  • Ön ek önbellekleme, tekrar eden bağlamı daha ucuz hale getirir.
  • OpenAI uyumlu araç çağırma, mevcut aracı kodlarını daha az değişiklikle taşımanızı sağlar.

Model, sağlayıcı karşılaştırmaları için OpenRouter'da deepseek-v4-pro-0813 olarak listelenmiştir.

Koda geçmeden önce önemli bir not: Hacker News lansman tartışmasında geliştiriciler, araç çağırma performansının donanım, çerçeve, istem iskelesi ve şema stiline duyarlı olduğunu bildirdi. Bu nedenle modelin kendi araçlarınızla davranışını mutlaka test edin.

DeepSeek fonksiyon çağırma nasıl çalışır?

Fonksiyon çağırma, modelin fonksiyonu kendisinin yürüttüğü anlamına gelmez. Model, düz metin yanıtı yerine örneğin şu şekilde yapılandırılmış bir istek üretir:

{
  "name": "get_order",
  "arguments": {
    "order_id": "ORD-10442"
  }
}
Enter fullscreen mode Exit fullscreen mode

Uygulamanız bu isteği doğrular, gerçek fonksiyonu çalıştırır, sonucu modele gönderir ve model gerçek veriye göre yanıt üretir.

İş akışı şöyledir:

  1. messages ile birlikte her fonksiyonu JSON Şeması olarak tanımlayan bir tools dizisi gönderirsiniz.
  2. Model bir araca ihtiyaç duyarsa tool_calls ve finish_reason: "tool_calls" ile yanıt verir.
  3. Kodunuz argümanları ayrıştırır, doğrular ve asıl fonksiyonu çalıştırır.
  4. Sonucu, çağrı kimliğine bağlı bir role: "tool" mesajı olarak eklersiniz.
  5. Model başka bir araç ister veya nihai yanıtını üretir.

OpenAI fonksiyon çağırma kullandıysanız protokol aynıdır. Genellikle yalnızca temel URL ve model adını değiştirmeniz gerekir. Resmi DeepSeek belgeleri Anthropic uyumlu Mesajlar uç noktasını ve Yanıtlar API'sini de kapsar; bu rehber OpenAI uyumlu yüzeye odaklanır.

Adım 1: İstemciyi kurun

Önce SDK'yı yükleyin ve API anahtarını ortam değişkeni olarak tanımlayın:

pip install openai
export DEEPSEEK_API_KEY="sk-..."
Enter fullscreen mode Exit fullscreen mode

Ardından istemciyi DeepSeek temel URL'sine yönlendirin:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)
Enter fullscreen mode Exit fullscreen mode

Bu rehberdeki örnekler, GA yapısı DeepSeek-V4-Pro-0813'e çözünen şu model adını kullanır:

model = "deepseek-v4-pro"
Enter fullscreen mode Exit fullscreen mode

Adım 2: Bir araç şeması tanımlayın

Bir çevrimiçi mağaza destek aracısı oluşturacağız. İlk aracımız sipariş bilgilerini getirir.

Araç tanımı şu üç parçadan oluşur:

  1. Araç adı
  2. Aracın ne zaman kullanılacağını açıklayan net bir açıklama
  3. Parametreleri tanımlayan JSON Şeması 
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_order",
            "description": (
                "Bir müşteri siparişini kimliğine göre arar. Sipariş durumunu, "
                "taşıyıcıyı, takip numarasını ve tahmini teslimat tarihini döndürür. "
                "Kullanıcı bir siparişin nerede olduğunu veya ne durumda olduğunu sorduğunda bunu kullanın."
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "order_id": {
                        "type": "string",
                        "description": "Sipariş kimliği, 'ORD-10442' gibi biçimlendirilmiş.",
                    }
                },
                "required": ["order_id"],
            },
        },
    }
]
Enter fullscreen mode Exit fullscreen mode

Araç açıklamasını kısa fakat karar vermeye yetecek kadar açık yazın. Model, aracı çağırıp çağırmayacağına büyük ölçüde bu açıklamaya göre karar verir. Belirsiz açıklamalar, yanlış araç seçiminin veya aracın hiç kullanılmamasının yaygın nedenidir.

Şimdi şemaya karşılık gelen yerel fonksiyonu ekleyin. Bu örnekte gerçek sipariş hizmeti yerine bir yer tutucu kullanıyoruz:

def get_order(order_id: str) -> dict:
    """Gerçek sipariş hizmetiniz için yer tutucu."""
    fake_db = {
        "ORD-10442": {
            "status": "shipped",
            "carrier": "DHL",
            "tracking_number": "4281337005",
            "estimated_delivery": "2026-08-15",
        },
        "ORD-10587": {
            "status": "processing",
            "estimated_ship_date": "2026-08-14",
        },
    }

    return fake_db.get(
        order_id,
        {"error": f"Bilinmeyen sipariş kimliği: {order_id}"}
    )
Enter fullscreen mode Exit fullscreen mode

Adım 3: İlk araç çağrınızı yapın

Modelin araç kullanmadan yanıtlayamayacağı bir soru gönderin:

messages = [
    {
        "role": "system",
        "content": "Sen bir çevrimiçi mağaza için destek aracısısın."
    },
    {
        "role": "user",
        "content": "ORD-10442 siparişim nerede?"
    },
]

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=messages,
    tools=tools,
)

message = response.choices[0].message

print(message.tool_calls[0].function.name)
# get_order

print(message.tool_calls[0].function.arguments)
# {"order_id": "ORD-10442"}
Enter fullscreen mode Exit fullscreen mode

Model bu aşamada sipariş durumunu uydurmak yerine get_order aracını çağırmanızı ister. Ham yanıt yükü şu yapıda görünür:

{
  "id": "chatcmpl-8f3a1c",
  "object": "chat.completion",
  "model": "deepseek-v4-pro",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "",
        "tool_calls": [
          {
            "id": "call_0_f1c29a44",
            "type": "function",
            "function": {
              "name": "get_order",
              "arguments": "{\"order_id\": \"ORD-10442\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 312,
    "completion_tokens": 24,
    "total_tokens": 336,
    "prompt_cache_hit_tokens": 0,
    "prompt_cache_miss_tokens": 312
  }
}
Enter fullscreen mode Exit fullscreen mode

Burada üç kritik ayrıntı vardır:

  • finish_reason, modelin yürütme istediğini belirten "tool_calls" değeridir.
  • Her çağrının, araç sonucuyla birlikte geri göndermeniz gereken bir id değeri vardır.
  • arguments alanı bir JSON dizgisidir; önce json.loads() ile ayrıştırmalı ve hatalı JSON olasılığını ele almalısınız.

Adım 4: Fonksiyonu yürütün ve sonucu döndürün

Araç çağrısını aldıktan sonra argümanları ayrıştırın, fonksiyonu yürütün ve iki mesaj ekleyin:

  1. tool_calls içeren asistan mesajı
  2. Sonucu taşıyan tool mesajı 
import json

tool_call = message.tool_calls[0]
args = json.loads(tool_call.function.arguments)

result = get_order(**args)

messages.append(message)

messages.append({
    "role": "tool",
    "tool_call_id": tool_call.id,
    "content": json.dumps(result),
})

final = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=messages,
    tools=tools,
)

print(final.choices[0].message.content)
# ORD-10442 siparişiniz DHL ile gönderildi ve tahmini olarak
# 15 Ağustos 2026'ya kadar ulaşacaktır. Takip numarası: 4281337005.
Enter fullscreen mode Exit fullscreen mode

tool_call_id eşleşmesi zorunludur. Her tool_calls girdisinin, bir sonraki model isteğinden önce karşılık gelen bir tool mesajı olmalıdır. Aksi halde istek başarısız olur.

Adım 5: Tam aracı döngüsü

Gerçek aracılar genellikle birden fazla çağrıyı zincirler. Örneğin:

  1. Siparişi getirir.
  2. İade politikasını kontrol eder.
  3. Müşteri için e-posta taslağı oluşturur.

Bunun için model nihai yanıt üretinceye kadar araç çağrılarını işleyen bir döngü gerekir.

import json

TOOLS_BY_NAME = {
    "get_order": get_order,
}

def run_agent(client, messages, tools, max_rounds=10):
    """Model nihai yanıt üretinceye veya tur sınırına ulaşıncaya kadar çalıştırır."""

    for _ in range(max_rounds):
        response = client.chat.completions.create(
            model="deepseek-v4-pro",
            messages=messages,
            tools=tools,
        )

        message = response.choices[0].message
        messages.append(message)

        # Araç çağrısı yoksa model nihai yanıtını üretmiştir.
        if not message.tool_calls:
            return message.content

        for tool_call in message.tool_calls:
            fn = TOOLS_BY_NAME.get(tool_call.function.name)

            try:
                if fn is None:
                    raise ValueError(
                        f"Bilinmeyen araç: {tool_call.function.name}"
                    )

                args = json.loads(tool_call.function.arguments)
                result = fn(**args)

            except Exception as exc:
                # Arızayı modele araç sonucu olarak verin.
                result = {"error": str(exc)}

            messages.append({
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": json.dumps(result),
            })

    raise RuntimeError(f"Aracı {max_rounds} tur içinde bitmedi")
Enter fullscreen mode Exit fullscreen mode

Bu döngü, çoğu aracı çerçevesinin temelidir. max_rounds sınırı önemlidir: model tekrar eden veya başarısız bir araç çağrısı döngüsüne girerse açık uçlu maliyet yerine kontrollü bir hata alırsınız.

Örnek kullanım:

messages = [
    {
        "role": "system",
        "content": "Sen bir çevrimiçi mağaza için destek aracısısın."
    },
    {
        "role": "user",
        "content": "ORD-10442 siparişim nerede?"
    },
]

answer = run_agent(client, messages, tools)
print(answer)
Enter fullscreen mode Exit fullscreen mode

Paralel araç çağrıları

Kullanıcı iki siparişi karşılaştırmak isterse model, bir dönüşte birden çok araç çağrısı döndürebilir:

“ORD-10442 ve ORD-10587'nin durumunu karşılaştırın.”

"tool_calls": [
  {
    "id": "call_0_a7d1",
    "type": "function",
    "function": {
      "name": "get_order",
      "arguments": "{\"order_id\": \"ORD-10442\"}"
    }
  },
  {
    "id": "call_1_b3e9",
    "type": "function",
    "function": {
      "name": "get_order",
      "arguments": "{\"order_id\": \"ORD-10587\"}"
    }
  }
]
Enter fullscreen mode Exit fullscreen mode

Yukarıdaki run_agent döngüsü birden çok çağrıyı zaten işler. Her çağrıyı kendi tool_call_id değeriyle yanıtlar.

Araçlarınız ağ isteği yapıyorsa, bu çağrıları eş zamanlı çalıştırabilirsiniz. Ancak sonraki model turuna geçmeden önce tüm tool_calls girdileri için bir tool sonucu eklemelisiniz.

Bu yaklaşım, modelin bir kum havuzunda orkestrasyon kodu yazdığı GPT-5.6'nın programatik araç çağırmasından farklıdır. DeepSeek'te yürütme ve güven sınırı uygulamanızın çalışma zamanında kalır.

Düşünme modu ve araçlar

V4 Pro üç düşünme moduyla gelir. Zor planlama dönüşlerinde muhakeme çabasını artırabilir, rutin aramalarda ise düşünmeyi kapatabilirsiniz. Mod adları ve varsayılanlar için resmi belgelere bakın.

Düşünme etkin olduğunda API, araç çağrılarıyla birlikte reasoning_content döndürebilir:

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=messages,
    tools=tools,
    extra_body={"thinking": {"type": "enabled"}},
)

message = response.choices[0].message

print(message.reasoning_content)
# planlama izi

print(message.tool_calls)
# karar verdiği çağrılar
Enter fullscreen mode Exit fullscreen mode

reasoning_content, modelin bir aracı neden seçtiğini anlamanıza yardımcı olabilir. Özellikle şema veya araç açıklaması sorunlarını teşhis ederken yararlıdır.

Yardımcı dönüşü geçmişe eklemeden önce reasoning_content alanını çıkarın. Düşünmeyi yalnızca planlama yoğun dönüşlerde kullanın; muhakeme çıktısı 0.87$/M üzerinden faturalandırılır.

Hata yönetimi: Model bir çağrıyı yanlış yaptığında

Bozuk araç çağrıları nadir olsa da, çok turlu aracı döngülerinde tek bir hata büyüyebilir. Temel yaklaşım şudur:

  • Kötü araç çağrısında uygulamayı çökertmeyin.
  • Hata bilgisini tool sonucu olarak modele geri gönderin.
  • Modelin doğru argümanlarla yeniden denemesine izin verin.

Hem JSON ayrıştırma hatalarını hem de şema doğrulama hatalarını ele alın:

pip install jsonschema
Enter fullscreen mode Exit fullscreen mode 
import json
from jsonschema import ValidationError, validate

schema = tools[0]["function"]["parameters"]

try:
    args = json.loads(tool_call.function.arguments)
    validate(instance=args, schema=schema)

    result = get_order(**args)

except (json.JSONDecodeError, ValidationError) as exc:
    result = {
        "error": f"Geçersiz argümanlar: {exc}",
        "hint": (
            "get_order aracını 'ORD-10442' gibi bir order_id "
            "dizesiyle tekrar çağırın."
        ),
    }
Enter fullscreen mode Exit fullscreen mode

hint alanı özellikle faydalıdır. Modele tek satırlık bir düzeltme önerisi vererek sonraki turda daha tutarlı bir yeniden deneme sağlayabilirsiniz.

Araç hatalarını güvenlik açısından da değerlendirin. Saldırgan girdilerle delete_order gibi bir aracı çağırmaya ikna edilen model, aracın sahip olduğu yetkiler kadar risklidir. Bu nedenle yapay zeka aracıları için en az ayrıcalıklı API anahtarları kullanın ve kimlik bilgilerini araç bazında kapsamlandırın.

Yayınlamadan önce Apidog ile araç çağrılarını test edin ve hata ayıklayın

Her araç, genellikle bir API'nin ince bir sarmalayıcısıdır. Model artık bu API'nin tüketicisidir. Destekleyici uç nokta belirsiz, tutarsız veya kararsızsa aracı davranışı da bundan etkilenir.

Apidog'u araç geliştirme döngüsüne şu şekilde ekleyin:

  1. Önce destekleyici API'yi tasarlayın.

    Apidog'un görsel tasarımcısında GET /orders/{order_id} uç noktasını tanımlayın. Araç JSON Şemanızı API sözleşmesiyle hizalayın; böylece API ve araç şeması zamanla birbirinden sapmaz.

  2. Arka uç hazır olmadan önce taklit edin.

    Apidog'un akıllı taklit sunucusuyla şemadan gerçekçi yanıtlar üretin. Gerçek sipariş servisi tamamlanmadan get_order araç döngüsünü test edebilirsiniz.

  3. Ham model yüklerini inceleyin.

    Aynı messages ve tools gövdesini Apidog üzerinden https://api.deepseek.com adresine gönderin. Ham tool_calls JSON'unu inceleyerek yanlış iç içe geçmiş properties alanlarını veya çift kodlanmış argümanları hızlıca tespit edin.

  4. Konuşmaları test senaryolarına dönüştürün.

    finish_reason, araç adı ve argüman şekli için assert ifadeleri yazın. Şema değiştiğinde test paketini çalıştırın. Donanım ve istem duyarlılığı göz önüne alındığında, gerçek şemalarınıza dayalı regresyon testleri üretimdeki davranışı daha iyi tahmin eder.

Daha derin bir uygulama deseni için bir yapay zeka aracısını Apidog test donanımına bağlama rehberine bakın.

Takip etmek için Apidog'u ücretsiz indirin; taklit sunucusu ve test senaryoları ücretsiz katmana dahildir.

Aracı döngülerinin maliyeti nedir?

Aracı döngülerinde her tur, konuşma geçmişini tekrar gönderir. Onuncu turda sistem istemi, araç şemaları ve önceki dokuz turun sonuçları tekrar girdi olarak değerlendirilir.

V4 Pro'nun otomatik ön ek önbelleklemesi bu maliyet eğrisini azaltır. Her turun girdisi genellikle bir önceki turun girdisi ve eklenen yeni içerikten oluşur. Bu nedenle önceki bağlamın büyük bölümü önbellek isabeti olarak fiyatlandırılabilir:

  • Önbellek kaçırma: $0.435/M girdi jetonu
  • Önbellek isabeti: $0.003625/M girdi jetonu

Örneğin 100K jetonluk bir konuşmayı yeniden okumak:

  • Önbelleksiz yaklaşık $0.0435
  • Önbellek isabetiyle yaklaşık $0.0004

Yanıtın usage bloğundaki şu alanları izleyin:

{
  "prompt_cache_hit_tokens": 0,
  "prompt_cache_miss_tokens": 312
}
Enter fullscreen mode Exit fullscreen mode

Önbellek isabet oranını yüksek tutmak için:

  • Önceki mesajları değiştirmeyin.
  • tools dizisini turlar arasında bayt düzeyinde sabit tutun.
  • Sistem istemini ve araç tanımlarını gereksiz yere yeniden sıralamayın.

İstem önbelleklemesinin ne olduğu rehberi mekanikleri daha ayrıntılı açıklar.

deepseek-v4-flash için belirtilen 0.14$/0.28$ fiyatları tek atışlık araç yönlendirmesi için cazip olabilir. Ancak 10'dan fazla çağrıyı zincirleyen döngülerde kalite düşüşü yeniden denemeleri artırabilir. Bu nedenle Pro, derin aracı iş akışlarında daha güvenli varsayılan olabilir.

Sıkça Sorulan Sorular

Araç tanımları jeton maliyetine neden olur mu?

Evet. tools dizisi her istekte girdi olarak gönderilir. Diziyi sabit tutarsanız, ilk turdan sonra önbelleğe alınmış ön eke dahil olur ve sonraki turlarda önbellek isabet fiyatlandırmasından yararlanır.

Fonksiyon çağırmayı yapılandırılmış çıktılarla birleştirebilir miyim?

Evet. Yaygın desen şudur:

  1. Araçlarla ara verileri alın.
  2. Modelin nihai yanıtını yapılandırılmış bir çıktı şemasına göre üretmesini sağlayın.
  3. Alt düzey uygulama kodunda düz metin ayrıştırmaktan kaçının.

Özet

DeepSeek V4 Pro'da fonksiyon çağırma kasıtlı olarak basittir: OpenAI uyumlu şemalar, bir tool_calls dizisi ve çağrı kimliğine bağlı tool mesajları.

Üretim için temel mimari, Adım 5'teki döngüdür:

  1. Modeli çağırın.
  2. Araç çağrılarını doğrulayın.
  3. Araçları yürütün.
  4. Sonuçları eşleşen tool_call_id ile geri gönderin.
  5. Nihai yanıt gelene kadar tekrarlayın.

Ön ek önbelleklemesi, çok turlu konuşmaların maliyetini düşürür. Ancak karşılaştırma testleri modelin sizin araç şemalarınızla nasıl çalışacağını göstermez. Destekleyici API'leri bilinçli tasarlayın, erken aşamada taklit edin ve Apidog'da araç çağrısı senaryoları için bir regresyon paketi oluşturun. Böylece şema değişiklikleri aracınızı sessizce bozmaz.

Top comments (0)