Entegrasyon rehberleri · 2026-09-22

Gemini API'de function calling: OpenAI uyumlu uçta araç çağırma

Gemini modellerini OpenAI uyumlu chat completions ucundan çağırırken tools dizisini, tool_choice davranışını ve paralel araç çağrılarını nasıl kuracağınızı adım adım anlatır.

tools dizisi neden değişmeden çalışır

Gemini API OpenAI uyumlu rehberinde anlatılan temel geçiş, base URL ve model kimliğiyle sınırlıdır; fonksiyon çağırma da aynı prensiple çalışır. İstekte gönderilen `tools` dizisi ve her aracın `parameters` şeması, gateway tarafından Gemini'nin kendi fonksiyon bildirim biçimine çevrilir. İstemci kodunda OpenAI'nin `tool_calls` yanıt alanını okuyan mantığı değiştirmeniz gerekmez.

Fark, modelin bir aracı ne zaman çağırmaya karar verdiğinde ortaya çıkar. Gemini ailesindeki modeller, aynı sistem talimatı ve araç tanımıyla bile OpenAI modellerinden farklı bir eşiğe sahip olabilir; bu yüzden ilk entegrasyonda birkaç gerçek istekle karar davranışını gözlemlemek, dokümantasyonu okumaktan daha güvenilir bir kontrol adımıdır.

tool_choice değerleri ve paralel çağrılar

`tool_choice: "auto"` modelin araç kullanıp kullanmayacağına kendisinin karar vermesini sağlar ve varsayılan davranıştır. `tool_choice: "required"` bir araç çağrısını zorunlu kılar; modelin serbest metinle yanıt vermesi engellenir. Belirli bir fonksiyonu isimle zorlamak da desteklenir, ancak bu davranış modelden modele değişir ve katalogdaki her Gemini modelinde aynı şekilde garanti edilmez.

Paralel araç çağrısı, yani tek yanıtta birden fazla `tool_calls` girdisi dönmesi, karmaşık ajan akışlarında sık karşılaşılan bir ihtiyaçtır. Bunu üretime almadan önce test isteği atıp yanıtın gerçekten birden fazla çağrı içerip içermediğini kontrol edin; modelin tek çağrıyla yetinip sonucu bekleyerek ikinci adımı bir sonraki turda istemesi de geçerli bir davranıştır.

`tools` ve `parameters` şeması OpenAI biçiminde kalır, çeviri gateway tarafında yapılır.
`tool_choice: "auto"` ve `"required"` iki temel moddur; isimle zorlama modele göre değişir.
Paralel çağrı desteğini üretime almadan gerçek bir istekle doğrulayın.

Hata ayıklarken nereye bakmalı

Araç çağrısı beklenirken düz metin dönüyorsa önce sistem talimatını ve araç açıklamasının netliğini kontrol edin; model çoğu zaman belirsiz bir görev tanımında metni tercih eder. Şema doğrulama hatası alıyorsanız `parameters` alanındaki zorunlu/opsiyonel alan işaretlemesinin JSON Schema ile uyumlu olduğundan emin olun. Gemini, JSON Schema'nın yalnızca bir alt kümesini kabul eder; gateway bu yüzden Gemini'ye göndermeden önce `$schema`, `$id`, `$ref`, `definitions` ve `additionalProperties` anahtarlarını şemadan çıkarır. Aracınız bu anahtarlara dayanıyorsa (örneğin `$ref` ile başka bir tanıma işaret ediyorsa veya `additionalProperties: false` ile fazladan alanı reddetmeyi bekliyorsa) şemayı bu anahtarlar olmadan, açık `properties` ve `required` listeleriyle yazın ve dönen argümanları kendi tarafınızda doğrulayın.

Sık sorulan sorular

Gemini modelleri OpenAI'deki gibi tüm tool_choice değerlerini destekler mi?

`auto` ve `required` katalogdaki Gemini modellerinde tutarlı çalışır. Belirli bir fonksiyonu isimle zorlama davranışı modelden modele değişebilir; kritik bir akışta bu davranışı üretime almadan önce test etmeniz gerekir.

İstemci kodumu Gemini için ayrıca değiştirmem gerekir mi?

Hayır. tools tanımı ve tool_calls okuma mantığı OpenAI uyumlu istemcide aynı kalır; değişen tek şey base URL ve model kimliğidir, bu da temel Gemini API OpenAI uyumlu geçiş rehberinde anlatılır.