فراخوانی ابزار (Tool Calling) در راهیانا

اتصال مدل‌های هوش مصنوعی به توابع و سرویس‌های خارجی با استاندارد Function Calling

مقدمه: فراخوانی ابزار چیست؟

فراخوانی ابزار (Tool Calling یا Function Calling) قابلیتی است که به مدل‌های هوش مصنوعی اجازه می‌دهد در حین گفتگو، توابع یا سرویس‌های خارجی را فراخوانی کنند. این قابلیت امکان ساخت دستیارهای هوشمند متصل به دنیای واقعی (مانند دریافت آب‌وهوا، جستجو، محاسبات و...) را فراهم می‌کند.

مدل، نیاز به فراخوانی یک ابزار را تشخیص می‌دهد و درخواست اجرای تابع را صادر می‌کند.
کلاینت (شما) خروجی ابزار را محاسبه و به مدل بازمی‌گردانید.
مدل با توجه به نتیجه ابزار، پاسخ نهایی را تولید می‌کند.

در عمل این یک چرخه ساده و قابل تکرار است: مدل می‌گوید «این تابع را صدا بزن»، شما نتیجه واقعی را می‌فرستید، و مدل ادامه مکالمه را با اتکا به آن نتیجه می‌سازد.

فرآیند کامل فراخوانی ابزار: گام به گام

پیام کاربر را همراه با تعریف ابزارها (tools) به مسیر
```
/chat/completions
```
بفرستید.
اگر مدل به ابزار نیاز داشته باشد، در نقش
```
assistant
```
یک آرایه tool_calls برمی‌گرداند. در این حالت مقدار
```
content
```
می‌تواند null باشد.
شما تابع را واقعاً اجرا می‌کنید و پیام جدیدی با نقش
```
tool
```
ارسال می‌کنید که حتماً شامل
```
tool_call_id
```
ِ دقیقا مطابق با همان مقدار بازگشتی مدل باشد. مقدار
```
content
```
یک رشته است (ترجیحاً JSON).
مدل با توجه به نتیجه ابزار، پاسخ نهایی را تولید کرده و بازمی‌گرداند (در صورت نیاز این چرخه می‌تواند تکرار شود).

نکته مهم

در راهیانا، پیام

role: tool

الزاماً باید فیلد

tool_call_id

داشته باشد؛ در غیر این صورت با خطای اعتبارسنجی روبه‌رو می‌شوید.

راهنمای عملی و قواعد پذیرش پیام‌ها در راهیانا

نقش‌های پشتیبانی‌شده:
```
user | system | assistant | tool
```
.
پیام
```
assistant
```
می‌تواند
```
tool_calls
```
داشته باشد و در این حالت
```
content
```
می‌تواند null باشد.
پیام
```
tool
```
باید شامل
```
tool_call_id
```
باشد و
```
content
```
یک رشته است (بهترین کار ارسال JSON-String از نتیجه ابزار است).
فیلدهای
```
tools
```
و
```
tool_choice
```
مستقیماً به ارائه‌دهنده منتقل می‌شوند.
خروجی
```
tool_calls
```
در پاسخ‌های عادی و جریانی (SSE) به شما بازگردانده می‌شود.
خطاها به‌صورت فارسی و با کدهای مشخص (مثلاً
```
payload_validation_failed
```
) برگردانده می‌شوند.

نمونه حداقلی ساختار پیام‌ها

{
  "model": "your-model",
  "tools": [{"type":"function","function":{"name":"get_weather","parameters":{"type":"object","properties":{"city":{"type":"string"}}}}}],
  "messages": [
    {"role":"user","content":"هوای تهران چطوره؟"},
    {"role":"assistant","content":null,"tool_calls":[{"id":"call_1","type":"function","function":{"name":"get_weather","arguments":"{"city":"Tehran"}"}}]},
    {"role":"tool","tool_call_id":"call_1","content":"{"city":"Tehran","temp":25}"}
  ]
}

استریم (SSE) و Tool Calls

اگر stream را فعال کنید، پاسخ به‌صورت رویدادهای SSE برمی‌گردد. در این حالت، به جای یک پاسخ نهایی، تکه‌های کوچکی از داده دریافت می‌کنید. وقتی مدل تصمیم بگیرد ابزاری را فراخوانی کند، در دل رویدادها، فیلد

choices[0].delta.tool_calls

را خواهید دید.

در استریم،
```
delta.tool_calls
```
ممکن است به‌صورت تدریجی ارسال شود.
وقتی پیام پایانی با
```
finish_reason: "tool_calls"
```
رسید، نوبت شماست که ابزار را اجرا کرده و پیام
```
role: "tool"
```
را برگردانید.
ساختار کلی دلتا مطابق استاندارد OpenAI است (نام تابع و آرگومان‌ها به‌صورت رشته JSON تجمیع می‌شوند).

نمونه رویداد استریم شامل tool_calls

data: {
  "id": "cmpl-...",
  "object": "chat.completion.chunk",
  "created": 1234567890,
  "model": "your-model",
  "choices": [
    {
      "index": 0,
      "delta": {
        "tool_calls": [
          {
            "index": 0,
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\":\"Tehran\"}"
            }
          }
        ]
      }
    }
  ]
}

توجه: در عمل ممکن است نام تابع و آرگومان‌ها در چند رویداد جداگانه کامل شوند. باید این دلتاها را کنار هم تجمیع کنید.

برای اطلاعات بیشتر درباره استریم، به مستندات Streaming مراجعه کنید.

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

پارامترهای درخواست

پارامتر	نوع	ضروری؟	توضیحات
model	string	بله	شناسه مدل مورد استفاده (مثال: `openai/gpt-4o`). برای لیست کامل مدل‌ها و شناسه‌ها به صفحه مدل‌ها مراجعه کنید.
messages	array	بله	آرایه‌ای از اشیاء پیام که تاریخچه گفتگو را تشکیل می‌دهند. هر پیام شامل `role` و `content` است.
stream	boolean	خیر	اگر `true` باشد، پاسخ به صورت جریانی (Server-Sent Events) ارسال می‌شود.
temperature	number	خیر	میزان خلاقیت پاسخ (معمولاً بین 0.0 تا 2.0). مقادیر بالاتر پاسخ‌های تصادفی‌تر و مقادیر پایین‌تر پاسخ‌های متمرکزتر تولید می‌کنند.
max_tokens	integer	خیر	حداکثر تعداد توکن‌هایی که مدل می‌تواند در پاسخ تولید کند.
top_p	number	خیر	روشی جایگزین برای کنترل خلاقیت با نمونه‌برداری هسته‌ای.
tools	array	خیر	لیستی از ابزارهایی که مدل می‌تواند فراخوانی کند.
tool_choice	string \| object	خیر	نحوه انتخاب ابزار توسط مدل را کنترل می‌کند.

ساختار پیام‌ها (messages)

پارامتر	نوع	ضروری؟	توضیحات
role	string	بله	نقش پیام دهنده. می‌تواند `"system"`, `"user"`, `"assistant"`, یا `"tool"` باشد.
content	string \| array	بله	محتوای پیام. برای نقش `user` می‌تواند آرایه‌ای از متن و اشیاء تصویر باشد.
name	string	خیر	نام تابع (در صورتی که `role` برابر `tool` یا `assistant` با `tool_calls` باشد).
tool_call_id	string	خیر	شناسه فراخوانی ابزار که این پیام پاسخی به آن است.

ساختار ابزار (tools)

پارامتر	نوع	ضروری؟	توضیحات
type	string	بله	نوع ابزار. در حال حاضر فقط `function` پشتیبانی می‌شود.
function	object	بله	جزئیات تابع. شامل `name` تابع برای فراخوانی است.

ساختار تابع (function)

پارامتر	نوع	ضروری؟	توضیحات
name	string	بله	نام تابع خاص برای فراخوانی.

مثال‌های عملی: درخواست و ارسال خروجی ابزار

درخواست فراخوانی ابزار (Tool Calling Request)

curl -X POST https://rahyana.ir/api/v1/chat/completions   -H "Content-Type: application/json"   -H "Authorization: Bearer YOUR_API_KEY"   -d '{     "model": "rahyana-chat-v1",     "messages": [       {"role": "user", "content": "آب و هوای تهران چطور است؟"}     ],     "tools": [       {         "type": "function",         "function": {           "name": "get_current_weather",           "description": "Get the current weather in a given location",           "parameters": {             "type": "object",             "properties": {               "location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"},               "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}             },             "required": ["location"]           }         }       }     ]   }'

ارسال خروجی ابزار به مدل (Submit Tool Output)

curl -X POST https://api.rahyana.ir/v1/chat/completions   -H "Content-Type: application/json"   -H "Authorization: Bearer YOUR_API_KEY"   -d '{     "model": "rahyana-chat-v1",     "messages": [       {"role": "user", "content": "آب و هوای تهران چطور است؟"},       {"role": "assistant", "content": null, "tool_calls": [{"id": "call_abc123", "type": "function", "function": {"name": "get_current_weather", "arguments": "{"location": "Tehran, Iran", "unit": "celsius"}"}}]},       {"role": "tool", "tool_call_id": "call_abc123", "content": "{"location": "Tehran", "temperature": "25", "unit": "celsius", "forecast": "sunny"}"}     ]   }'

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

همیشه ابزارها را با ساختار دقیق و معتبر (مطابق استاندارد OpenAI Function Calling) تعریف کنید.
اطمینان حاصل کنید که مدل انتخابی از Tool Calling پشتیبانی می‌کند (supportsTools).
در صورت استفاده از چند ابزار،
```
tool_choice
```
را برای کنترل انتخاب مدل تنظیم کنید.
در پیام
```
tool
```
، مقدار
```
tool_call_id
```
باید دقیقاً با مقدار بازگشتی مدل مطابقت داشته باشد.
برای اطلاعات بیشتر، به OpenAI Function Calling مراجعه کنید.