راهنمای Function Calling و Tool Use در API پیکو هوش

مقدارهای id و ساختار دقیق ممکن است با مدل‌ها فرق کند؛ همیشه مقدار برگشتی را عیناً استفاده کنید.

چرخه‌ی کامل در پایتون

import json, os
from openai import OpenAI

client = OpenAI(base_url="https://api.picoai.ir/v1", api_key=os.environ["PICO_API_KEY"])

def get_order_status(order_id: int) -> dict:
    return {"order_id": order_id, "status": "ارسال شده", "eta_days": 2}

TOOLS = [{
    "type": "function",
    "function": {
        "name": "get_order_status",
        "description": "وضعیت سفارش را با شماره‌ی سفارش برمی‌گرداند",
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "integer"}},
            "required": ["order_id"],
        },
    },
}]
REGISTRY = {"get_order_status": get_order_status}

messages = [{"role": "user", "content": "وضعیت سفارش 1042 چیست؟"}]

for _ in range(5):                      # سقف تکرار
    r = client.chat.completions.create(
        model="gpt-6-sol", messages=messages, tools=TOOLS, temperature=0)
    msg = r.choices[0].message
    if not msg.tool_calls:
        print(msg.content)
        break
    messages.append(msg)                # پیام assistant همراه tool_calls
    for call in msg.tool_calls:
        fn = REGISTRY.get(call.function.name)
        try:
            args = json.loads(call.function.arguments)
            result = fn(**args) if fn else {"error": "تابع ناشناخته"}
        except Exception as e:
            result = {"error": str(e)}
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(result, ensure_ascii=False),
        })

دو اصل: (۱) پیام assistant حاوی tool_calls باید پیش از پیام‌های tool در تاریخچه باشد؛ (۲) به ازای هر tool_call یک پیام tool با همان tool_call_id لازم است.

tool_choice

• "auto": مدل تصمیم می‌گیرد (پیش‌فرض)
• "none": ابزار صدا زده نشود
• "required": حتماً یک ابزار
• {"type":"function","function":{"name":"..."}}: ابزار مشخص

همه‌ی مدل‌ها همه‌ی مقادیر را یکسان پشتیبانی نمی‌کنند. اگر خطای 400 گرفتید، tool_choice را حذف کنید و در پرامپت راهنمایی بدهید.

چند ابزار هم‌زمان

مدل ممکن است در یک پاسخ چند tool_call بدهد. همه را اجرا کنید (در صورت استقلال، موازی) و برای هر یک پیام tool بفرستید.

استریم با ابزار

در حالت stream: true، آرگومان‌های ابزار تکه‌تکه در delta.tool_calls[i].function.arguments می‌آیند؛ باید تکه‌ها را بر اساس index به هم بچسبانید و پس از finish_reason == "tool_calls" JSON را پارس کنید. ساختار SSE: راهنمای استریم.

معادل در مسیر Anthropic

در /v1/messages ابزارها با tools[].input_schema تعریف می‌شوند و مدل بلوک tool_use می‌دهد؛ نتیجه را با بلوک tool_result در پیام کاربر برمی‌گردانید. پیکو هوش این قالب را به قالب چت تبدیل می‌کند. برای پروژه‌های جدید، یکی از دو قالب را انتخاب کنید و مخلوط نکنید.

بهترین‌روش‌ها

1. توضیح ابزار را روشن و کوتاه بنویسید؛ مدل بر اساس آن انتخاب می‌کند.
2. اعتبارسنجی: آرگومان‌ها را همیشه بررسی کنید؛ مدل ممکن است JSON ناقص یا مقدار نامعتبر بدهد. در صورت خطا، پیام خطا را در پیام tool برگردانید تا مدل اصلاح کند.
3. امنیت: هرگز خروجی مدل را مستقیم به شل، SQL یا فایل‌سیستم ندهید؛ فهرست مجاز بسازید.
4. سقف تکرار: حلقه‌ی بی‌پایان هزینه می‌سازد.
5. دما صفر برای انتخاب ابزار پایدارتر است.
6. هزینه: تعریف ابزارها و تاریخچه در هر دور دوباره ارسال می‌شود و توکن ورودی می‌خورد؛ تخمین هزینه.

برای ساخت ایجنت‌های کامل ببینید: ایجنت در LangChain و LangGraph.

عیب‌یابی

سوالات متداول

کدام مدل‌ها function calling دارند؟

مدل‌های چت مدرن کاتالوگ معمولاً دارند، اما کیفیت متفاوت است. روی سناریوی خودتان بسنجید؛ فهرست در کاتالوگ.

آیا ابزارها روی سرور پیکو هوش اجرا می‌شوند؟

خیر؛ اجرای ابزار همیشه سمت شماست.

آیا JSON mode یا structured output پشتیبانی می‌شود؟

پارامترها به مدل زیرین منتقل می‌شوند؛ نتیجه به پشتیبانی مدل بستگی دارد و باید آزمایش شود.

مرجع؟

مستندات، OpenAI Python.