AI Engineering Academy · Pelajaran

Memproses Panggilan Alat dalam Aplikasi Anda

Kenal pasti finish_reason tool_calls dalam respons API, ekstrak nama fungsi dan argumen, laksanakan fungsi Python yang sepadan dan hantar hasilnya kembali kepada model.

Pelajaran 2 daripada 413 langkah

Memproses Panggilan Alat dalam Aplikasi Anda ialah pelajaran AI Engineering Academy percuma di CoddyKit. Ini ialah pelajaran 2 daripada 4. Anda boleh membaca keseluruhan pelajaran di bawah secara percuma — kemudian berlatih secara praktikal dalam pelayar menggunakan penyunting kod terbina dalam dan tutor kecerdasan buatan 24/7. Pelajaran ini merupakan sebahagian daripada laluan pembelajaran AI Engineering Academy, dan kemajuan anda disegerakkan merentas web serta aplikasi CoddyKit. Kursus AI Engineering Academy merangkumi sejumlah 4 pelajaran.

Objek Respons Panggilan Alat

Apabila model memutuskan untuk memanggil fungsi, respons API mengandungi senarai tool_calls pada objek mesej. Setiap panggilan alat mempunyai id unik, function.name yang perlu dipanggil dan function.arguments — rentetan JSON yang mengandungi argumen yang ingin dihantar oleh model. Kod aplikasi anda bertanggungjawab untuk menghuraikan dan melaksanakan fungsi ini.

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)

Menghuraikan Argumen Fungsi

Medan function.arguments ialah rentetan yang dikodkan sebagai JSON, bukannya dict Python. Anda mesti menghuraikannya dengan json.loads(). Sentiasa bungkus operasi ini dalam try/except — model kadangkala menghasilkan JSON yang tidak sah walaupun telah diberikan panduan skema, dan anda perlu mengendalikannya dengan baik.

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'}

Menghantar kepada Fungsi yang Betul

Gunakan function.name untuk menghantar panggilan kepada fungsi Python yang betul. Corak yang kemas ialah menyimpan fungsi anda dalam kamus yang memetakan nama kepada objek yang boleh dipanggil. Ini mengelakkan rangkaian if/elif yang rapuh dan memudahkan penambahan alat baharu kemudian.

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)}'

Menghantar Semula Hasil kepada Model

Selepas melaksanakan fungsi, anda mesti menghantar semula hasilnya kepada model dalam panggilan API susulan. Tambahkan mesej pembantu (yang mengandungi tool_calls) kepada perbualan, kemudian tambahkan mesej baharu dengan role='tool', tool_call_id dan hasil fungsi sebagai kandungan. Kemudian panggil API sekali lagi.

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

Giliran Perbualan Lengkap

Interaksi panggilan alat yang lengkap melibatkan empat mesej dalam sejarah perbualan: mesej pengguna, mesej pembantu yang meminta panggilan alat, mesej hasil alat dan respons akhir pembantu yang menggabungkan hasil tersebut. Memahami struktur ini penting untuk membina pembantu yang menggunakan alat dalam berbilang giliran.

# 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)

Mengendalikan Keadaan Tiada Alat Dipanggil

Kadangkala model menjawab secara langsung tanpa memanggil alat — finish_reason akan menjadi 'stop', bukannya 'tool_calls'. Sentiasa semak keadaan ini sebelum cuba memproses panggilan alat. Pelaksanaan yang kukuh mengendalikan kedua-dua cabang dengan kemas.

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

Mengesahkan Argumen Sebelum Pelaksanaan

Model kadangkala mungkin menghantar argumen yang gagal dalam pengesahan logik perniagaan — tempoh negatif, e-mel tidak sah atau tarikh yang telah berlalu. Sahkan argumen sebelum memanggil fungsi sebenar dan kembalikan rentetan ralat yang jelas jika pengesahan gagal. Model kemudiannya boleh membetulkan argumennya pada giliran seterusnya.

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}'

Mencatat Interaksi Panggilan Alat

Sentiasa catat interaksi panggilan alat untuk penyahpepijatan dan analitis. Catat nama fungsi, argumen, hasil dan masa pelaksanaan. Data ini membantu anda mengenal pasti alat yang paling kerap dipanggil, alat yang gagal dan corak argumen yang dihasilkan oleh model — amat berguna untuk menambah baik skema dan pelaksanaan fungsi anda.

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

Pertimbangan Keselamatan Panggilan Alat

Jangan sekali-kali melaksanakan fungsi sewenang-wenangnya berdasarkan output model tanpa pengesahan. Sentiasa benarkan hanya nama fungsi yang tepat dalam TOOL_REGISTRY anda, sahkan semua argumen dan semak kebenaran sebelum melaksanakan tindakan. Model ialah pemanggil yang tidak dipercayai — gesaan berniat jahat mungkin cuba memanggil fungsi yang merosakkan jika logik penghantaran anda terlalu longgar.

  • Benarkan hanya fungsi yang disenaraikan secara jelas dalam TOOL_REGISTRY
  • Sahkan input dengan Pydantic sebelum pelaksanaan
  • Wajibkan kebenaran untuk operasi tulis/padam

Mengembalikan Hasil Berstruktur yang Kaya

Hasil alat tidak semestinya rentetan biasa. Anda boleh mengembalikan data berformat JSON, jadual atau ringkasan. Mengembalikan data berstruktur sebagai JSON membolehkan model menghuraikan dan merujuk medan tertentu dalam jawapan akhirnya. Untuk hasil yang besar, kembalikan ringkasan dengan fakta utama dan bukannya memasukkan semua data mentah ke dalam konteks.

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"]}'
    )

Perbualan Berbilang Giliran yang Menggunakan Alat

Corak yang berkuasa ialah perbualan berbilang giliran apabila model memanggil alat merentas beberapa mesej pengguna sambil membina konteks. Sentiasa kekalkan keseluruhan sejarah perbualan termasuk panggilan alat dan hasil terdahulu supaya model boleh merujuk jawapan sebelumnya tanpa memanggil semula alat yang tidak diperlukan.

Semakan Ringkas

Uji pemahaman anda tentang memproses panggilan alat dalam aplikasi anda.

Ringkasan Pelajaran

Dalam pelajaran ini, anda mempelajari bahawa: argumen panggilan alat tiba sebagai rentetan JSON yang mesti dihuraikan dengan json.loads(), kamus TOOL_REGISTRY memetakan nama fungsi kepada objek yang boleh dipanggil untuk penghantaran yang kemas, dan hasil dihantar semula kepada model sebagai mesej role='tool' dengan tool_call_id yang sepadan. Seterusnya, kita akan mengendalikan keadaan apabila model memanggil beberapa fungsi serentak dengan panggilan fungsi selari.

Percuma untuk bermula

Pelajari Python dengan tutor kecerdasan buatan — percuma

Tulis dan jalankan kod sebenar dalam pelayar anda, dapatkan bantuan segera daripada tutor kecerdasan buatan yang tersedia 24/7, dan sambung semula dari tempat anda berhenti di web atau dalam aplikasi.

Kursus
30
Pelajaran
120

Soalan Lazim

Adakah pelajaran “Memproses Panggilan Alat dalam Aplikasi Anda” percuma?

Ya — teks penuh “Memproses Panggilan Alat dalam Aplikasi Anda” boleh dibaca secara percuma di web ini. Untuk berlatih secara interaktif menggunakan penyunting kod terbina dalam dan tutor kecerdasan buatan 24/7, serta membuka kunci baki kursus AI Engineering Academy, tingkat taraf kepada CoddyKit PRO. Kursus AI Engineering Academy merangkumi sejumlah 4 pelajaran.

Apakah yang akan saya pelajari dalam “Memproses Panggilan Alat dalam Aplikasi Anda”?

Kenal pasti finish_reason tool_calls dalam respons API, ekstrak nama fungsi dan argumen, laksanakan fungsi Python yang sepadan dan hantar hasilnya kembali kepada model. Anda berlatih AI Engineering Academy menggunakan kod praktikal yang dijalankan terus dalam pelayar, manakala tutor kecerdasan buatan 24/7 menjawab soalan anda semasa anda mengikuti pelajaran.

Adakah saya memerlukan pengalaman untuk memulakan AI Engineering Academy?

Tiada pengalaman terdahulu diperlukan. Pembelajaran AI Engineering Academy di CoddyKit disusun untuk pelajar daripada peringkat pemula hingga lanjutan, jadi anda boleh bermula di sini atau dari awal dan belajar mengikut kadar anda sendiri. Ini ialah pelajaran 2 daripada 4.

Berapa lamakah pelajaran “Memproses Panggilan Alat dalam Aplikasi Anda” diambil?

Kebanyakan pelajaran CoddyKit mengambil masa kira-kira 5–10 minit. Setiap pelajaran ringkas dan interaktif, jadi anda boleh membuat kemajuan secara berterusan dan menyambung tepat dari tempat anda berhenti di web atau aplikasi.

Bolehkah saya menulis dan menjalankan kod dalam pelajaran AI Engineering Academy ini?

Ya. Setiap pelajaran AI Engineering Academy menyertakan penyunting kod terbina dalam, jadi anda boleh menulis dan menjalankan kod sebenar terus dalam pelayar serta menerima maklum balas kecerdasan buatan serta-merta — tanpa memerlukan persediaan setempat.

Semua pelajaran dalam kursus ini

  1. Mentakrifkan Skema Fungsi untuk API
  2. Memproses Panggilan Alat dalam Aplikasi Anda
  3. Panggilan Fungsi Selari
  4. Membina Antara Muka Pangkalan Data Bahasa Semula Jadi
← Kembali ke AI Engineering Academy