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.
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.contentGiliran 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_reasonMengesahkan 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 resultPertimbangan 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.
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
- Mentakrifkan Skema Fungsi untuk API
- Memproses Panggilan Alat dalam Aplikasi Anda
- Panggilan Fungsi Selari
- Membina Antara Muka Pangkalan Data Bahasa Semula Jadi