0Pricing
AI Engineering Academy · Ders

Uygulamanızda Araç Çağrılarını İşleme

API yanıtındaki finish_reason tool_calls değerini algılayın, işlev adlarını ve bağımsız değişkenleri çıkarın, ilgili Python işlevini çalıştırın ve sonucu modele geri gönderin.

Uygulamanızda Araç Çağrılarını İşleme, CoddyKit'te ücretsiz bir AI Engineering Academy dersidir. Bu, 4 dersinin 2. dersidir. Aşağıdan dersin tamamını ücretsiz okuyabilir, sonra tarayıcıda yerleşik kod editörü ve 7/24 yapay zeka koçu ile uygulamalı olarak pratik yapabilirsin. Bu, AI Engineering Academy öğrenme yolunun bir parçasıdır ve ilerlemeniz web ve CoddyKit uygulaması arasında senkronize olur. AI Engineering Academy kursu toplamda 4 dersten oluşur.

Araç Çağrısı Yanıt Nesnesi

Model bir işlevi çağırmaya karar verdiğinde API yanıtı, ileti nesnesinde bir tool_calls listesi içerir. Her araç çağrısında benzersiz bir id, çağrılacak function.name ve modelin göndermek istediği bağımsız değişkenlerin JSON dizesi olan function.arguments bulunur. Bunu ayrıştırmak ve işlevi çalıştırmak uygulama kodunuzun sorumluluğundadır.

from openai import OpenAI
import json

client = OpenAI()

response = client.chat.completions.create(
    model='gpt-4o',
    messages=[{'role': 'user', 'content': 'What is the weather in Paris?'}],
    tools=tools  # defined previously
)

message = response.choices[0].message

if response.choices[0].finish_reason == 'tool_calls':
    for tool_call in message.tool_calls:
        print('Call ID:', tool_call.id)
        print('Function name:', tool_call.function.name)
        print('Arguments (JSON string):', tool_call.function.arguments)

İşlev Bağımsız Değişkenlerini Ayrıştırma

function.arguments alanı bir Python dict değil, JSON ile kodlanmış bir dizedir. Bu alanı json.loads() ile ayrıştırmanız gerekir. Bunu her zaman bir try/except bloğuna alın — model, şema yönergelerine rağmen zaman zaman hatalı JSON üretebilir ve bunu uygun şekilde işlemeniz gerekir.

import json

def parse_tool_call(tool_call) -> dict:
    '''Parse a tool call's arguments from JSON string to dict.'''
    try:
        args = json.loads(tool_call.function.arguments)
        return args
    except json.JSONDecodeError as e:
        print(f'Failed to parse arguments for {tool_call.function.name}: {e}')
        print(f'Raw arguments: {tool_call.function.arguments}')
        return {}

# Usage
tool_call = message.tool_calls[0]
args = parse_tool_call(tool_call)
print('Parsed args:', args)  # {'location': 'Paris', 'unit': 'celsius'}

Doğru İşleve Yönlendirme

Doğru Python işlevine yönlendirmek için function.name kullanın. Temiz bir yaklaşım, işlevlerinizi adı çağrılabilir nesneyle eşleyen bir sözlükte tutmaktır. Bu, kırılgan if/elif zincirlerini önler ve daha sonra yeni araçlar eklemeyi kolaylaştırır.

def get_current_weather(location: str, unit: str = 'celsius') -> str:
    # Real implementation calls a weather API
    return f'{location}: 18{chr(176)}C, partly cloudy'

def create_calendar_event(title: str, start_time: str, duration_minutes: int, **kwargs) -> str:
    return f'Event created: {title} at {start_time} for {duration_minutes} minutes'

# Tool registry: maps function names to callables
TOOL_REGISTRY = {
    'get_current_weather': get_current_weather,
    'create_calendar_event': create_calendar_event
}

def execute_tool_call(tool_call) -> str:
    name = tool_call.function.name
    args = parse_tool_call(tool_call)

    if name not in TOOL_REGISTRY:
        return f'Unknown function: {name}'

    try:
        result = TOOL_REGISTRY[name](**args)
        return str(result)
    except Exception as e:
        return f'Function {name} raised an error: {str(e)}'

Sonuçları Modele Geri Gönderme

İşlevi çalıştırdıktan sonra sonucu, sonraki bir API çağrısında modele geri göndermeniz gerekir. Araç çağrılarını içeren asistan iletisini konuşmaya ekleyin, ardından role='tool', tool_call_id ve işlev sonucunu içerik olarak taşıyan yeni bir ileti ekleyin. Sonra API'yi yeniden çağırın.

def run_tool_call_loop(messages: list, tools: list) -> str:
    response = client.chat.completions.create(
        model='gpt-4o',
        messages=messages,
        tools=tools
    )
    message = response.choices[0].message
    messages.append(message)  # Add assistant's tool_calls message

    # Execute all tool calls and collect results
    for tool_call in (message.tool_calls or []):
        result = execute_tool_call(tool_call)
        # Add each tool result as a 'tool' role message
        messages.append({
            'role': 'tool',
            'tool_call_id': tool_call.id,
            'content': result
        })

    # Second API call with results appended
    final_response = client.chat.completions.create(
        model='gpt-4o',
        messages=messages,
        tools=tools
    )
    return final_response.choices[0].message.content

Eksiksiz Konuşma Turu

Tam bir araç çağrısı etkileşimi, konuşma geçmişinde dört ileti içerir: kullanıcının iletisi, araç çağrısı isteyen asistan iletisi, araç sonucu iletisi ve sonucu içeren asistanın son yanıtı. Bu yapıyı anlamak, birden fazla turda araç kullanan asistanlar oluşturmak için gereklidir.

# The full message history for a tool-calling conversation:
conversation = [
    {'role': 'user', 'content': 'What is the weather in Tokyo?'},

    # Model requests a tool call (added by run_tool_call_loop)
    # {'role': 'assistant', 'content': None, 'tool_calls': [...]},

    # Application sends tool result back
    # {'role': 'tool', 'tool_call_id': 'call_abc123', 'content': 'Tokyo: 22C, sunny'},

    # Model produces final human-readable response
    # {'role': 'assistant', 'content': 'The weather in Tokyo is 22 degrees Celsius and sunny.'}
]

final_answer = run_tool_call_loop(
    [{'role': 'user', 'content': 'What is the weather in Tokyo?'}],
    tools
)
print(final_answer)

Hiçbir Araç Çağrılmadığında Durumu Ele Alma

Bazen model hiçbir araç çağırmadan doğrudan yanıt verir — finish_reason, 'tool_calls' yerine 'stop' olur. Araç çağrılarını işlemeye çalışmadan önce bu durumu her zaman kontrol edin. Sağlam bir uygulama her iki dalı da temiz şekilde ele alır.

def smart_complete(user_message: str) -> str:
    messages = [{'role': 'user', 'content': user_message}]
    response = client.chat.completions.create(
        model='gpt-4o',
        messages=messages,
        tools=tools
    )
    choice = response.choices[0]

    if choice.finish_reason == 'stop':
        # Model answered directly without calling a tool
        return choice.message.content

    elif choice.finish_reason == 'tool_calls':
        # Process tool calls
        messages.append(choice.message)
        for tc in choice.message.tool_calls:
            result = execute_tool_call(tc)
            messages.append({'role': 'tool', 'tool_call_id': tc.id, 'content': result})
        # Get final answer
        final = client.chat.completions.create(model='gpt-4o', messages=messages)
        return final.choices[0].message.content

    return 'Unexpected finish reason: ' + choice.finish_reason

Çalıştırmadan Önce Bağımsız Değişkenleri Doğrulama

Model zaman zaman iş mantığı doğrulamasından geçemeyen bağımsız değişkenler gönderebilir — negatif bir süre, geçersiz bir e-posta veya geçmişte kalan bir tarih. Gerçek işlevi çağırmadan önce bağımsız değişkenleri doğrulayın ve doğrulama başarısız olursa açıklayıcı bir hata dizesi döndürün. Model sonraki turda bağımsız değişkenlerini düzeltebilir.

from pydantic import BaseModel, ValidationError
from datetime import datetime

class CreateEventArgs(BaseModel):
    title: str
    start_time: str  # ISO 8601
    duration_minutes: int

def safe_create_event(tool_call) -> str:
    try:
        raw_args = json.loads(tool_call.function.arguments)
        validated = CreateEventArgs(**raw_args)
        # Additional business rule
        event_time = datetime.fromisoformat(validated.start_time)
        if event_time < datetime.now():
            return 'Error: start_time must be in the future.'
        return create_calendar_event(**validated.dict())
    except ValidationError as e:
        return f'Invalid arguments: {e}'

Araç Çağrısı Etkileşimlerini Günlüğe Kaydetme

Hata ayıklama ve analiz için araç çağrısı etkileşimlerini her zaman günlüğe kaydedin. İşlev adını, bağımsız değişkenleri, sonucu ve çalıştırma süresini kaydedin. Bu veriler, hangi araçların en sık çağrıldığını, hangilerinin başarısız olduğunu ve modelin hangi bağımsız değişken kalıplarını ürettiğini belirlemenize yardımcı olur — şemalarınızı ve işlev uygulamalarınızı geliştirmek için paha biçilmezdir.

import time
import logging

logger = logging.getLogger('tool_calls')

def logged_execute(tool_call) -> str:
    name = tool_call.function.name
    args_str = tool_call.function.arguments
    start = time.time()
    result = execute_tool_call(tool_call)
    elapsed = time.time() - start

    logger.info(
        'Tool call executed',
        extra={
            'function': name,
            'arguments': args_str,
            'result_length': len(result),
            'elapsed_ms': round(elapsed * 1000)
        }
    )
    return result

Araç Çağrısı Güvenliğiyle İlgili Hususlar

Model çıktısına dayanarak doğrulama yapmadan hiçbir keyfi işlevi çalıştırmayın. TOOL_REGISTRY içinde yalnızca tam işlev adlarına izin verin, tüm bağımsız değişkenleri doğrulayın ve eylemleri çalıştırmadan önce yetkilendirmeyi kontrol edin. Model güvenilmeyen bir çağırandır — yönlendirme mantığınız çok izin verici olursa kötü amaçlı bir istem yıkıcı işlevleri çağırmaya çalışabilir.

  • Yalnızca TOOL_REGISTRY içinde açıkça listelenen işlevlere izin verin
  • Çalıştırmadan önce girdileri Pydantic ile doğrulayın
  • Yazma/silme işlemleri için yetkilendirme gerektirin

Zengin Yapılandırılmış Sonuçlar Döndürme

Araç sonuçlarının düz dizeler olması gerekmez. JSON biçimli veriler, tablolar veya özetler döndürebilirsiniz. Yapılandırılmış verileri JSON olarak döndürmek, modelin son yanıtındaki belirli alanları ayrıştırmasına ve bunlara başvurmasına olanak tanır. Büyük sonuçlar için tüm ham verileri bağlama yığmak yerine temel bilgileri içeren bir özet döndürün.

def get_order_status(order_id: str) -> str:
    # Fetch from real database
    order = {'id': order_id, 'status': 'shipped', 'estimated_delivery': '2024-03-15', 'carrier': 'FedEx', 'tracking': 'FX123456'}
    # Return concise summary, not raw DB record
    return (
        f'Order {order_id}: Status={order["status"]}, '
        f'Estimated delivery: {order["estimated_delivery"]}, '
        f'Carrier: {order["carrier"]}, Tracking: {order["tracking"]}'
    )

Birden Fazla Turlu Araç Kullanan Konuşmalar

Güçlü bir yaklaşım, modelin birden fazla kullanıcı iletisi boyunca araçları çağırarak bağlamı oluşturduğu birden fazla turlu konuşmadır. Modelin araçları gereksiz yere yeniden çağırmadan önceki yanıtları kullanabilmesi için geçmiş araç çağrılarını ve sonuçlarını da içeren tam konuşma geçmişini her zaman koruyun.

Hızlı Kontrol

Uygulamanızdaki araç çağrılarını işleme konusundaki anlayışınızı sınayın.

Ders Özeti

Bu derste şunları öğrendiniz: araç çağrısı bağımsız değişkenleri ayrıştırılması gereken bir JSON dizesi olarak gelir ve bunun için json.loads() kullanılır; bir TOOL_REGISTRY sözlüğü, temiz yönlendirme için işlev adlarını çağrılabilir nesnelerle eşler; sonuçlar, eşleşen tool_call_id değerlerini taşıyan role='tool' iletileri olarak modele geri gönderilir. Sırada, modelin paralel işlev çağrısıyla aynı anda birden fazla işlev çağırdığı durumu ele alacağız.

Sıkça Sorulan Sorular

“Uygulamanızda Araç Çağrılarını İşleme” dersi ücretsiz mi?

Evet — “Uygulamanızda Araç Çağrılarını İşleme” dersin tüm metni burada web'de ücretsiz olarak okunabilir. Etkileşimli olarak pratik yapmak (yerleşik kod editörü ve 7/24 yapay zeka koçu) ve AI Engineering Academy kursunun geri kalanını açmak için CoddyKit PRO'ya yükselt. AI Engineering Academy kursu toplamda 4 dersten oluşur.

“Uygulamanızda Araç Çağrılarını İşleme” dersinde ne öğreneceğim?

API yanıtındaki finish_reason tool_calls değerini algılayın, işlev adlarını ve bağımsız değişkenleri çıkarın, ilgili Python işlevini çalıştırın ve sonucu modele geri gönderin. AI Engineering Academy ile uygulamalı kodu tarayıcıda doğrudan çalıştırarak pratik yaparsın ve 7/24 yapay zeka koçu dersi çalışırken sorularını yanıtlar.

AI Engineering Academy öğrenmeye başlamak için deneyim gerekli mi?

Önceden deneyim gerekmez. CoddyKit'te AI Engineering Academy, başlangıçtan ileri seviyeye kadar yapılandırıldığı için buradan başlayabilir veya başından başlayıp kendi hızında ilerleme yapabilirsin. Bu, 4 dersinin 2. dersidir.

“Uygulamanızda Araç Çağrılarını İşleme” dersi ne kadar sürer?

Çoğu CoddyKit dersi yaklaşık 5–10 dakika sürer. Her biri kısa ve etkileşimli olduğu için sabit ilerleme yaparsın ve web ile uygulama arasında tam olarak bıraktığın yerden devam edebilirsin.

Bu AI Engineering Academy dersinde kod yazıp çalıştırabilir miyim?

Evet. Her AI Engineering Academy dersi yerleşik bir kod editörü içerir, bu sayede tarayıcıda gerçek kod yazıp çalıştırabilir ve anlık yapay zeka geri bildirimi alırsın — yerel kurulum gerekli değildir.

Bu kursun tüm dersleri

  1. API İçin İşlev Şemaları Tanımlama
  2. Uygulamanızda Araç Çağrılarını İşleme
  3. Paralel İşlev Çağrıları
  4. Doğal Dil Veritabanı Arayüzü Oluşturma
← AI Engineering Academy Sayfasına Dön