پرسش از هوش مصنوعی

پرسش از AvalAI پرسش از Claude پرسش از ChatGPT

پرسش از هوش مصنوعی

پرسش از AvalAI پرسش از Claude پرسش از ChatGPT

ابزارها

از جستجوی وب، فراخوانی تابع، بارگذاری deferred ابزارها و ابزارهای میزبانی‌شده وابسته به route برای گسترش قابلیت‌های مدل استفاده کنید.

هنگام تولید پاسخ‌های مدل، می‌توانید با ابزارها قابلیت‌های مدل را گسترش دهید. قابل‌حمل‌ترین الگوی AvalAI این است که در /v1/responses از web_search برای زمینه عمومی و به‌روز وب، و از ابزارهای سفارشی function برای داده‌های خودتان، side effectها و جریان‌های approval استفاده کنید. خانواده‌های ابزار میزبانی‌شده دیگر مانند file search، computer use، remote MCP، shell، code interpreter، ابزارهای تولید تصویر و tool_search به مدل و route وابسته‌اند؛ وقتی ابزار میزبانی‌شده فعال نیست، آن قابلیت را در برنامه خودتان پیاده کنید و نتیجه را از طریق فراخوانی تابع برگردانید.

مثال زیر از ابزار جستجوی وب برای بازیابی زمینه عمومی و به‌روز وب در پاسخ مدل استفاده می‌کند.

شامل کردن نتایج جستجوی وب برای پاسخ مدل

bash

curl https://api.avalai.ir/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
"model": "gpt-5.5",
"tools": [{"type": "web_search"}],
"input": "what was a positive news story from today?"
}'

javascript

import { OpenAI } from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,

  baseURL: "https://api.avalai.ir/v1",
});

const response = await client.responses.create({
  model: "gpt-5.5",

  tools: [{ type: "web_search" }],

  input: "What was a positive news story from today?",
});

console.log(response.output_text);

python

import os
from openai import OpenAI

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

response = client.responses.create(
    model="gpt-5.5",
    tools=[{"type": "web_search"}],
    input="What was a positive news story from today?",
)

print(response.output_text)

go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	payload := map[string]any{
		"model": "gpt-5.5",
		"tools": []map[string]string{{"type": "web_search"}},
		"input": "What was a positive news story from today?",
	}

	body, err := json.Marshal(payload)
	if err != nil {
		panic(err)
	}

	req, err := http.NewRequest("POST", "https://api.avalai.ir/v1/responses", bytes.NewBuffer(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AVALAI_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	responseBody, err := io.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}

	fmt.Println(string(responseBody))
}

php

<?php

$apiKey = getenv('AVALAI_API_KEY');
$payload = [
    'model' => 'gpt-5.5',
    'tools' => [['type' => 'web_search']],
    'input' => 'What was a positive news story from today?',
];

$ch = curl_init('https://api.avalai.ir/v1/responses');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

ابزارهای موجود

در اینجا مروری بر ابزارهای موجود از طریق API یکپارچه AvalAI ارائه شده است - یکی از آنها را برای راهنمایی بیشتر در مورد استفاده انتخاب کنید.

هشدار

موجود بودن ابزار به مدل و route انتخابی بستگی دارد. برای گردش‌کارهای تولیدی امروز، از /v1/responses همراه web_search و ابزارهای سفارشی function استفاده کنید. File Search میزبانی‌شده، Computer Use، remote MCP، shell، code interpreter و بسته‌های skill میزبانی‌شده OpenAI در AvalAI وابسته به فعال بودن هستند؛ اگر ابزار میزبانی‌شده برای مدل انتخابی فعال نیست، آن قابلیت را در برنامه خودتان پیاده کنید و به شکل ابزار function در اختیار مدل بگذارید.

خانواده ابزار	شکل سازگار با OpenAI	راهنمای AvalAI
جستجوی وب	`tools: [{"type": "web_search"}]`	بهترین پیش‌فرض برای زمینه عمومی و به‌روز وب از مسیر `/v1/responses`.
فراخوانی تابع	`tools: [{"type": "function", ...}]`	برای داده خصوصی، side effectها، تأیید انسانی و یکپارچه‌سازی‌هایی که خودتان مالک آن هستید استفاده کنید.
جستجوی فایل	`tools: [{"type": "file_search", ...}]`	vector store میزبانی‌شده در حال توسعه است؛ امروز از RAG سمت برنامه با embeddings استفاده کنید.
Computer use / shell / code interpreter	آبجکت‌های ابزار میزبانی‌شده	وابسته به موجود بودن بدانید؛ مگر اینکه AvalAI برای مدل انتخابی پشتیبانی را اعلام کند، از ابزار تابعی یا runtime خودتان استفاده کنید.
جستجوی ابزار	`tools: [{"type": "tool_search"}]`	OpenAI این قابلیت را برای `gpt-5.4` و مدل‌های بعد از آن مستند کرده است؛ پیش از اتکا به بارگذاری تعویقی، پشتیبانی AvalAI/مدل را بررسی کنید.
ابزار تولید تصویر	`tools: [{"type": "image_generation"}]` یا endpointهای تصویر	برای گردش‌کارهای تولیدی تصویر، endpointهای تصویر AvalAI را ترجیح دهید مگر اینکه route انتخابی Responses صریحا ابزار تولید تصویر را پشتیبانی کند؛ مسیر مهاجرت تصویر را ببینید.
shell / skills / code interpreter	ابزارهای runtime میزبانی‌شده	این‌ها را قابلیت‌های runtime میزبانی‌شده OpenAI بدانید؛ مگر اینکه AvalAI runtime میزبانی‌شده را برای مدل انتخابی فعال کرده باشد، sandbox خودتان را اجرا کنید و نتیجه را با ابزار تابعی برگردانید.
Remote MCP / connectorها	`tools: [{"type": "mcp", ...}]`	فقط وقتی استفاده کنید که route پشتیبانی کند و سرور، connector، دامنه‌های OAuth و سیاست approval قابل اعتماد باشند.

انتخاب سطح ابزار مناسب

کوچک‌ترین سطحی را انتخاب کنید که قابلیت مورد نیاز مدل را فراهم می‌کند:

زمینه عمومی و به‌روز: در /v1/responses از web_search استفاده کنید و وقتی برنامه به منابع یا متادیتای query نیاز دارد، آیتم‌های web_search_call را بررسی کنید.
داده خصوصی یا side effect: یکپارچه‌سازی را در برنامه خودتان نگه دارید و یک ابزار function محدود با JSON Schema سخت‌گیرانه در اختیار مدل بگذارید.
پایگاه دانش خصوصی بزرگ: امروز از RAG سمت برنامه با embeddings استفاده کنید؛ فقط پس از پشتیبانی route انتخابی AvalAI از vector store به file_search میزبانی‌شده مهاجرت کنید.
عملیات مرتبط زیاد: ابزارها را بر اساس دامنه در namespace گروه‌بندی کنید، هر namespace را متمرکز نگه دارید و فقط پس از تأیید پشتیبانی مدل سراغ tool_search بروید.
سرویس‌های ثالث: remote MCP رسمی یا connectorهای معتبر را ترجیح دهید، ابزارهای واردشده را با allowed_tools محدود کنید و برای نوشتن‌ها یا خواندن‌های حساس approval الزامی کنید.
runtimeهای میزبانی‌شده: shell، code interpreter، skill bundleها و computer-use را وابسته به route بدانید؛ اگر فعال نیستند، runtime را خودتان اجرا کنید و نتیجه را با function_call_output برگردانید.

GPT Actions در برابر ابزارهای function در AvalAI

GPT Actions در OpenAI یک سطح مخصوص ChatGPT/Custom GPT است: سازنده endpointهای REST توصیف‌شده با OpenAPI، احراز هویت و instructions را به یک GPT متصل می‌کند و ChatGPT زبان طبیعی را به payload JSON همان endpointها تبدیل می‌کند. در AvalAI، GPT Actions را به‌عنوان route API مستند نکنید. همان اصول طراحی را با ابزارهای function در /v1/responses یا MCP serverهای قابل اعتماد پیاده کنید:

مفهوم GPT Actions	پیاده‌سازی در AvalAI
schema عملیات OpenAPI	JSON Schema روی ابزار `function`، یا یک MCP server کوچک با schema ابزارهای صریح.
action بازیابی داده	تابع backend فقط‌خواندنی مثل `lookup_order`، `search_docs` یا `get_forecast`.
action پیامددار	تابع نوشتن یا خرید که همیشه پیش از اجرا approval سمت برنامه می‌خواهد.
احراز هویت action با OAuth/API key	credentialها را در backend نگه دارید؛ bearer token یا refresh token را در prompt قابل مشاهده برای مدل قرار ندهید.
پاسخ action	JSON خام و فشرده برگردانید تا مدل آن را خلاصه کند، نه prose طبیعی از پیش نوشته‌شده.

نگاشت احراز هویت برای port کردن الگوهای Actions

OpenAI Actions در سازنده ChatGPT سه حالت احراز هویت None، API key و OAuth را پشتیبانی می‌کند. وقتی این طراحی را به AvalAI منتقل می‌کنید، تصمیم احراز هویت را به backend خودتان ببرید و فقط شکل ابزار امن را در اختیار مدل بگذارید:

بدون احراز هویت: فقط برای داده عمومی و read-only استفاده کنید که ترافیک ناشناس برای آن قابل قبول است. پیش از expose کردن از طریق مدل، rate limit و abuse monitoring اضافه کنید.
API key: کلیدهای provider یا سرویس را server-side نگه دارید. مدل باید تابعی مثل lookup_shipping_rate را صدا بزند؛ backend شما پس از validate کردن argumentها API key را اضافه می‌کند.
OAuth: flow ورود کاربر را در برنامه خودتان کامل کنید، refresh tokenها را در secret store نگه دارید، و فقط access token کوتاه‌مدت را به سرویس downstream بفرستید. برای ابزارهای MCP/connector، access token را در هر درخواست از طریق فیلد مستند authorization ارسال کنید.
ایمنی state و redirect: اگر طراحی OAuth شبیه Actions را reuse می‌کنید، بررسی state در OAuth را حفظ کنید، redirect URL دقیق همان surface را register کنید، و خطاهای auth را بدون افشای secret به مدل log کنید.
ارتقا از signed-out به signed-in: discovery بدون احراز هویت را از actionهای شخصی یا write-capable جدا کنید. برای مثال search_public_docs را بدون auth expose کنید، اما برای create_ticket یا send_email ورود کاربر و approval لازم باشد.

هنگام انتقال یک integration سبک Actions به AvalAI، endpointها را محدود نگه دارید، descriptionها را کوتاه و دقیق بنویسید، argumentها را پیش از فراخوانی شبکه validate کنید، برای 429 و 5xx backoff بگذارید و کارهای طولانی را asynchronous طراحی کنید. نکات production در OpenAI Actions همچنین endpoint عمومی HTTPS/TLS، timeout حدود ۴۵ ثانیه برای action، payloadهای متنی و اندازه payload کمتر از ۱۰۰٬۰۰۰ کاراکتر را فرض می‌کند؛ برای ابزارهای function در AvalAI، حتی اگر backend شما بیشتر می‌پذیرد، این‌ها را guardrail محافظه‌کارانه طراحی بدانید.

fallback برای code interpreter و runtimeهای میزبانی‌شده

Code Interpreter میزبانی‌شده OpenAI به مدل اجازه می‌دهد Python را در sandbox موقت بنویسد و اجرا کند، فایل ورودی بگیرد و فایل‌های تولیدشده را به شکل annotation برگرداند. در AvalAI فقط وقتی از این شکل hosted استفاده کنید که route انتخابی /v1/responses صریحا از tools: [{"type": "code_interpreter", ...}] پشتیبانی کند. در غیر این صورت runtime خودتان را به شکل ابزار function سفارشی expose کنید:

اجرا را سمت سرور و داخل container محدود نگه دارید؛ shell خام یا دسترسی شبکه دلخواه را مستقیم در اختیار مدل نگذارید.
تابع محدودی مثل run_python_analysis تعریف کنید که ورودی‌های صریح برای کد، فایل‌های مجاز، محدودیت زمانی و نوع artifact مورد انتظار داشته باشد.
کد و argumentها را قبل از اجرا validate کنید، محدودیت CPU/حافظه/زمان/فایل بگذارید و retryها را idempotent طراحی کنید.
فایل‌های آپلودشده و artifactهای تولیدشده را در storage خودتان نگه دارید؛ URL یا file ID پایدار، خلاصه، stdout و stderr را از طریق function_call_output برگردانید.
chartها، CSVها و notebookهای تولیدشده را تا وقتی برنامه شما scan، sign یا approve نکرده است خروجی untrusted بدانید.
اگر container میزبانی‌شده سبک OpenAI بعدا برای route شما فعال شد، policy مربوط به artifact و approval را حفظ کنید و فقط پیاده‌سازی runtime را عوض کنید.

ابزارهای استاندارد

جستجوی وب شامل کردن داده‌ها از اینترنت در تولید پاسخ مدل.

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

استفاده از رایانه ایجاد گردش‌های کاری عاملی که مدل را قادر می‌سازد رابط کاربری رایانه را کنترل کند.

فراخوانی تابع فعال کردن مدل برای فراخوانی کد سفارشی که شما تعریف می‌کنید، و دسترسی آن به داده‌ها و قابلیت‌های اضافی.

Code Interpreter اجرای Python در sandbox میزبانی‌شده وقتی route انتخابی /v1/responses پشتیبانی می‌کند، یا استفاده از fallback تابع Python مدیریت‌شده توسط برنامه.

Shell اجرای commandهای ترمینال غیرتعاملی در container میزبانی‌شده وقتی فعال است، یا از طریق runtime shell محدود و مدیریت‌شده توسط خودتان.

MCP و connectorها اتصال به سرورهای remote MCP یا ابزارهای SaaS به سبک connector همراه OAuth، allowed_tools، approvalها و مرزهای اعتماد سخت‌گیرانه.

ابزارهای مختص Google/Gemini

مدل‌های Gemini (به ویژه gemini-3.5-flash، gemini-3.1-pro-preview، gemini-3.1-flash-lite، gemini-2.5-pro و gemini-2.5-flash) از چندین ابزار تخصصی پشتیبانی می‌کنند:

[اجرای کد] به Gemini اجازه می‌دهد از کد برای حل مسائل پیچیده استفاده کند. هنگامی که این ابزار فعال است، هیچ ابزار دیگری نمی‌تواند همزمان استفاده شود.

python

# مثال: اجرای کد با Gemini
response = client.chat.completions.create(
    model="gemini-3.1-pro-preview",
    messages=[{"role": "user", "content": "۱۰ عدد اول فیبوناچی را محاسبه کن"}],
    tools=[
        {"codeExecution": {}},
    ],
)

مسیر مهاجرت این مثال به Responses API

codeExecution قالب ابزار مختص Gemini در Chat Completions است. آن را با یک ابزار تابع نامرتبط جایگزین نکنید. برای محاسبات سبک، مستقیما از /v1/responses با یک مدل پشتیبان Responses استفاده کنید. اگر اجرای کد sandbox شده لازم دارید، تا وقتی مدل و ابزار معادل در AvalAI برای Responses فعال نشده، همین مثال Gemini Chat را نگه دارید.

python

import os
from openai import OpenAI

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

response = client.responses.create(
    model="gpt-5.5",
    instructions="وقتی محاسبه به تأیید پاسخ کمک می‌کند، مراحل را کوتاه نشان بده.",
    input="۱۰ عدد اول فیبوناچی را محاسبه کن.",
)

print(response.output_text)

نکات مهاجرت:

messages به input منتقل می‌شود.
ابزار Gemini با شکل tools=[{"codeExecution": {}}] در این مثال AvalAI معادل مستقیم Responses ندارد.
برای ابزارهای Responses از آبجکت‌های مستند مثل web_search، file_search، computer یا ابزار سفارشی function استفاده کنید، به شرطی که مدل انتخابی پشتیبانی کند. computer_use_preview را فقط برای integrationهای legacy نگه دارید که هنوز به مدل preview قدیمی وابسته‌اند.
هنگام اجرای ابزارها، response.output را بر اساس type بررسی کنید؛ برای متن نهایی از response.output_text استفاده کنید.

[جستجوی گوگل] مدل‌های Gemini را قادر می‌سازد با استفاده از جستجوی گوگل، اطلاعات به‌روز را بازیابی کنند. این ابزار فقط می‌تواند در ترکیب با ابزار urlContext استفاده شود.

python

# مثال: جستجوی گوگل با Gemini
response = client.chat.completions.create(
    model="gemini-3.1-pro-preview",
    messages=[
        {
            "role": "user",
            "content": "آخرین پیشرفت‌ها در محاسبات کوانتومی چیست؟",
        }
    ],
    tools=[
        {"googleSearch": {}},
    ],
)

مسیر مهاجرت این مثال به Responses API

googleSearch قالب ابزار مختص Gemini در Chat Completions است. در /v1/responses، به جای انتقال همان آبجکت Gemini، از ابزار سازگار AvalAI/OpenAI یعنی web_search با یک مدل پشتیبان Responses استفاده کنید.

python

import os
from openai import OpenAI

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

response = client.responses.create(
    model="gpt-5.5",
    input="آخرین پیشرفت‌ها در محاسبات کوانتومی چیست؟ منابع را ذکر کن.",
    tools=[{"type": "web_search", "search_context_size": "medium"}],
)

print(response.output_text)

نکات مهاجرت:

messages به input منتقل می‌شود.
ابزار Gemini با شکل tools=[{"googleSearch": {}}] در Responses به tools=[{"type": "web_search"}] تبدیل می‌شود، اگر مدل انتخابی جستجوی وب را پشتیبانی کند.
اگر رابط کاربری شما علاوه بر citation متنی به متادیتای ساختاریافته منابع نیاز دارد، include=["web_search_call.action.sources"] را اضافه کنید.
در response.output به دنبال آیتم‌های web_search_call و آیتم نهایی message باشید.

[زمینه URL] این ویژگی آزمایشی به مدل‌های Gemini اجازه می‌دهد URL‌ها را به عنوان زمینه بخوانند و استفاده کنند. مدل URL‌ها را در محتوای کاربر جستجو می‌کند و آنها را می‌خواند، که منجر به افزایش مصرف توکن ورودی می‌شود.

python

# مثال: زمینه URL با Gemini (می‌تواند با جستجوی گوگل ترکیب شود)
response = client.chat.completions.create(
    model="gemini-3.1-pro-preview",
    messages=[
        {
            "role": "user",
            "content": "این مقاله را خلاصه کن: https://example.com/article",
        }
    ],
    tools=[
        {"urlContext": {}},
    ],
)

مسیر مهاجرت این مثال به Responses API

urlContext قالب ابزار مختص Gemini در Chat Completions است. در /v1/responses، یا URL را در برنامه خود دریافت و متن استخراج‌شده را به عنوان ورودی ارسال کنید، یا وقتی مدل باید زمینه عمومی و به‌روز وب را بازیابی کند، prompt را با web_search همراه کنید.

python

import os
from openai import OpenAI

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

response = client.responses.create(
    model="gpt-5.5",
    input="اگر این مقاله به‌صورت عمومی قابل دسترسی است، آن را خلاصه کن: https://example.com/article",
    tools=[{"type": "web_search", "search_context_size": "medium"}],
)

print(response.output_text)

نکات مهاجرت:

messages به input منتقل می‌شود.
ابزار Gemini با شکل tools=[{"urlContext": {}}] ابزار هم‌نام در Responses ندارد.
برای خلاصه‌سازی قطعی در محصول، صفحه را سمت سرور دریافت و پاک‌سازی کنید و محتوای استخراج‌شده را به input بدهید.
وقتی تازگی اطلاعات و بازیابی وب عمومی مهم‌تر از ingestion قطعی است، از web_search استفاده کنید.

توجه

محدودیت‌های سازگاری ابزارها برای مدل‌های Gemini:

هنگامی که اجرای کد فعال است، هیچ ابزار دیگری نمی‌تواند استفاده شود
اعلان‌های تابع فقط می‌توانند به تنهایی استفاده شوند
جستجوی گوگل فقط می‌تواند با زمینه URL ترکیب شود

ابزارهای مختص Alibaba/DashScope

مدل‌های Qwen شرکت Alibaba (از جمله qwen3.7-max، qwen3.7-plus، qwen3.6-plus، qwen3.6-flash و اسنپ‌شات‌های قدیمی qwen3-max) از جستجوی وب از طریق پلتفرم DashScope پشتیبانی می‌کنند:

[جستجوی وب (enable_search)] مدل‌های Qwen را قادر می‌سازد اطلاعات به‌روز را از وب بازیابی کنند. بر خلاف سایر ارائه‌دهندگان، Alibaba از پارامتر enable_search به جای آرایه tools استفاده می‌کند.

python

# مثال: جستجوی وب با Alibaba Qwen3.7 Max
import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="qwen3.7-max",
    messages=[{"role": "user", "content": "قیمت فعلی سهام علی‌بابا چقدر است؟"}],
    extra_body={"enable_search": True, "search_options": {"search_strategy": "agent"}},
)

print(response.choices[0].message.content)

مسیر مهاجرت این مثال به Responses API

extra_body={"enable_search": true} افزونه Chat Completions مخصوص DashScope/Qwen است. این پارامتر ارائه‌دهنده‌محور را به /v1/responses منتقل نکنید. برای پیاده‌سازی Responses-first، از ابزار استاندارد web_search با یک مدل پشتیبان Responses استفاده کنید.

python

import os
from openai import OpenAI

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

response = client.responses.create(
    model="gpt-5.5",
    input="قیمت فعلی سهام علی‌بابا چقدر است؟ منابع و زمان اطلاعاتی که پیدا کردی را ذکر کن.",
    tools=[{"type": "web_search", "search_context_size": "medium"}],
)

print(response.output_text)

نکات مهاجرت:

messages به input منتقل می‌شود.
DashScope extra_body.enable_search برای مدل‌های پشتیبان Responses به tools=[{"type": "web_search"}] تبدیل می‌شود.
وقتی دقیقا به رفتار Qwen/DashScope enable_search نیاز دارید، مثال Chat Completions را نگه دارید.
در response.output به دنبال آیتم‌های web_search_call و آیتم نهایی message باشید.

توجه

برای جستجوی وب Alibaba:

مدل‌های فعلی Qwen3.7 و Qwen3.6 مانند qwen3.7-max، qwen3.7-plus، qwen3.6-plus و qwen3.6-flash از جستجوی وب پشتیبانی می‌کنند؛ اسنپ‌شات‌های قدیمی qwen3-max نیز ممکن است بسته به موجود بودن پشتیبانی شوند
search_strategy باید برای مناطق بین‌المللی روی "agent" تنظیم شود
نتایج جستجوی وب به پرامپت اضافه می‌شوند و توکن‌های ورودی را افزایش می‌دهند

قیمت‌گذاری ابزارها

هر ابزار دارای قیمت‌گذاری جداگانه علاوه بر قیمت‌گذاری پایه API مدل برای توکن‌های ورودی/خروجی است. توکن‌های استفاده شده برای ابزارهای داخلی با نرخ هر توکن مدل انتخابی محاسبه می‌شوند، به علاوه هزینه‌های اضافی مختص هر ابزار:

ابزار	هزینه
مفسر کد (Code Interpreter)	$۰.۰۳ به ازای هر جلسه (session)
ذخیره‌سازی جستجوی فایل (File Search Storage)	$۰.۱۰ گیگابایت/روز (۱ گیگابایت رایگان)
فراخوانی ابزار جستجوی فایل (فقط Responses API*)	$۲.۵۰ به ازای هر ۱هزار فراخوانی (*برای Assistants API اعمال نمی‌شود)
جستجوی وب (Web Search)	قیمت‌گذاری ابزار جستجوی وب شامل توکن‌های استفاده شده برای ترکیب اطلاعات از وب است. قیمت‌گذاری به مدل و اندازه زمینه جستجو بستگی دارد.

قیمت‌گذاری جستجوی وب

مدل	اندازه زمینه جستجو	هزینه
gpt-5.5 / gpt-5.4 / gpt-5.4-pro	کم	$۳۰.۰۰ به ازای هر ۱هزار فراخوانی
	متوسط (پیش‌فرض)	$۳۵.۰۰ به ازای هر ۱هزار فراخوانی
	زیاد	$۵۰.۰۰ به ازای هر ۱هزار فراخوانی
gpt-5.4-mini / gpt-5.4-nano	کم	$۲۵.۰۰ به ازای هر ۱هزار فراخوانی
	متوسط (پیش‌فرض)	$۲۷.۵۰ به ازای هر ۱هزار فراخوانی
	زیاد	$۳۰.۰۰ به ازای هر ۱هزار فراخوانی
qwen3.7-max / qwen3.7-plus / qwen3.6-flash (Alibaba)	agent	$۱۰.۰۰ به ازای هر ۱هزار فراخوانی

برای اطلاعات کامل قیمت‌گذاری، لطفا به صفحه قیمت‌گذاری مراجعه کنید.

استفاده در API

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

بر اساس دستور ورودی ارائه شده، مدل به طور خودکار تصمیم می‌گیرد که از ابزار پیکربندی شده استفاده کند یا خیر. به عنوان مثال، اگر دستور ورودی شما اطلاعاتی فراتر از تاریخ قطع آموزش مدل را درخواست کند و جستجوی وب فعال باشد، مدل معمولا ابزار جستجوی وب را برای بازیابی اطلاعات مرتبط و به‌روز فراخوانی می‌کند.

می‌توانید با تنظیم پارامتر tool_choice در درخواست API این رفتار را به صراحت کنترل یا هدایت کنید.

مدل آیتم‌های چرخه ابزار در Responses

/v1/responses به جای یک message واحد شبیه Chat Completions، آرایه تایپ‌شده output برمی‌گرداند. هر آیتم را بخشی از چرخه ابزار بدانید و آیتم‌هایی را که درخواست بعدی به آن‌ها وابسته است حفظ کنید.

آیتم خروجی	معنی	کار برنامه شما
`message`	محتوای نهایی یا میانی دستیار	متن را نمایش دهید، یا اگر state را دستی replay می‌کنید آن را نگه دارید.
`reasoning`	state استدلال پنهان یا خلاصه‌شده مدل‌های reasoning	اگر route آن را برگرداند، همراه خروجی ابزارهای بعدی نگه دارید؛ حذف آن می‌تواند قابلیت اعتماد را کاهش دهد.
`web_search_call`	مدل از جستجوی وب میزبانی‌شده استفاده کرده است	وقتی UI به auditability نیاز دارد، متادیتای query/action/source را بررسی کنید؛ در غیر این صورت `message` نهایی یا `output_text` را بخوانید.
`function_call`	مدل از برنامه شما می‌خواهد یک تابع سفارشی اجرا کند	`arguments` را parse کنید، کد قابل اعتماد را اجرا کنید و سپس `function_call_output` متناظر را با همان `call_id` بفرستید.
`function_call_output`	نتیجه برنامه شما برای یک فراخوانی تابع قبلی	آن را در درخواست بعدی Responses قرار دهید تا مدل پاسخ را کامل کند.
`tool_search_call` / `tool_search_output`	ابزارهای deferred جستجو و load شده‌اند	در حالت hosted، ابزارهای load شده را بررسی کنید؛ در حالت client، قبل از انتظار برای function call، خودتان `tool_search_output` را برگردانید.
`mcp_list_tools` / `mcp_call`	سرور Remote MCP ابزارها را فهرست کرده یا یکی را اجرا کرده است	ابزارهای فهرست‌شده را cache/validate کنید، برای عملیات حساس approval بگیرید و خروجی‌ها را داده ثالث بدانید.
`image_generation_call`	ابزار تولید تصویر میزبانی‌شده اجرا شده است	endpointهای تصویر AvalAI را ترجیح دهید مگر اینکه route انتخابی Responses صریحا این آیتم را پشتیبانی کند.

اگر از previous_response_id استفاده می‌کنید، state سازگار با AvalAI/OpenAI در routeهای پشتیبانی‌شده بخش زیادی از این آیتم‌ها را جلو می‌برد. اگر state را خودتان replay می‌کنید، آیتم‌های تایپ‌شده قبلی و خروجی‌های ابزار جدید را به ترتیب اضافه کنید.

چک‌لیست طراحی ابزار

در درخواست‌های سازگار با OpenAI می‌توانید ابزارهای داخلی و ابزارهای تابعی خودتان را ترکیب کنید، اما هر تعریف ابزار بخشی از ورودی مدل است. سطح ابزارهای اولیه را کوچک نگه دارید، نام و توضیح پارامترها را شفاف بنویسید و از مدل نخواهید آرگومان‌هایی را حدس بزند که برنامه شما از قبل می‌داند.

برای مسیریابی عادی از tool_choice: "auto"، برای الزام اجرای حداقل یک ابزار از "required" و برای پاسخ فقط متنی از "none" استفاده کنید.
وقتی ابزارها state را تغییر می‌دهند، به تایید نیاز دارند یا باید به ترتیب دقیق اجرا شوند، از parallel_tool_calls: false استفاده کنید.
در routeهایی که پشتیبانی می‌کنند، از max_tool_calls برای محدود کردن کار ابزارهای داخلی میزبانی‌شده استفاده کنید. این مقدار را سقف کلی همه فراخوانی‌های ابزار داخلی بدانید، نه محدودیت جداگانه برای هر ابزار.
جزئیات اختیاری ابزار را با include فقط وقتی درخواست کنید که UI، audit log یا debugger به آن نیاز دارد؛ مثل web_search_call.action.sources، code_interpreter_call.outputs، file_search_call.results یا URL تصویر خروجی computer.
برای تعداد زیادی تابع سفارشی، ابتدا فقط ابزارهای محتمل را در دسترس بگذارید؛ از tool_search فقط وقتی استفاده کنید که پشتیبانی مدل انتخابی در AvalAI را تأیید کرده باشید.
برای دامنه‌های بزرگ مثل CRM، billing یا عملیات اسناد از ابزارهای namespaced استفاده کنید؛ در صورت امکان هر namespace را کمتر از ۱۰ تابع نگه دارید.
اگر ابزارها بیرون از آرایه معمول tools کشف می‌شوند، آن‌ها را با آیتم ورودی additional_tools اضافه کنید و هنگام replay کردن state مکالمه، جایگاه همان آیتم را حفظ کنید.
ابزارهای میزبانی‌شده خاص OpenAI مانند remote MCP، shell یا runtimeهای شبیه code interpreter را وابسته به موجود بودن در نظر بگیرید. وقتی برای مدل انتخابی شما در AvalAI ارائه نشده‌اند، آن قابلیت را در قالب ابزار function برنامه خودتان پیاده کنید.
آیتم‌های خروجی تایپ‌شده Responses مانند tool_search_call، tool_search_output، web_search_call، function_call، mcp_list_tools، mcp_call، image_generation_call و message را بررسی کنید؛ فقط وقتی متن نهایی کافی است از output_text استفاده کنید.

بارگذاری تعویقی ابزار با `tool_search`

الگوی tool search در مستندات OpenAI به برنامه‌های بزرگ اجازه می‌دهد تابع‌ها را در namespaceها گروه‌بندی کنند و تابع‌های کم‌استفاده را با defer_loading علامت بزنند. این کار prompt اولیه را کوچک‌تر نگه می‌دارد و همچنان به مدل اجازه می‌دهد ابزار مناسب را بعدا load کند. در AvalAI فقط وقتی از این الگو استفاده کنید که پشتیبانی مدل و route انتخابی از tool_search را تأیید کرده باشید؛ در غیر این صورت همین گروه‌بندی را در backend نگه دارید و فقط تابع‌های محتمل همان turn را بفرستید.

Tool search دو سبک اجرایی دارد:

جستجوی میزبانی‌شده: موجودی کامل ابزارها را در درخواست اعلام کنید، {"type": "tool_search"} را اضافه کنید و اجازه دهید API ابزارهای deferred مرتبط را load کند. این روش وقتی مناسب است که ابزارهای کاندید از قبل مشخص باشند.
جستجوی اجراشده توسط client: tool_search را با execution: "client" پیکربندی کنید؛ مدل یک tool_search_call تولید می‌کند، برنامه شما registry خودش را جستجو می‌کند، سپس tool_search_output را همراه ابزارهای load شده برمی‌گرداند. این روش برای کاتالوگ ابزارهای tenant-specific یا project-specific مناسب‌تر است.

برای namespaceها، defer_loading روی تابع‌های داخل namespace قرار می‌گیرد، نه روی خود namespace. نام و توضیح namespace را کوتاه و شفاف بنویسید و هر namespace را آن‌قدر کوچک نگه دارید که مدل بتواند با اطمینان آن را انتخاب کند.

نکات production:

OpenAI قابلیت tool_search را برای gpt-5.4 و مدل‌های بعد از آن مستند کرده است. در AvalAI همچنان route دقیق /v1/responses و مدل انتخابی را پیش از استقرار بررسی کنید.
به جای تعداد زیادی تابع deferred جداگانه، namespace یا سرور MCP را ترجیح دهید. با namespace، مدل در ابتدا فقط نام و توضیح namespace را می‌بیند؛ اما برای تابع deferred مستقل، همچنان نام و توضیح تابع را می‌بیند و بیشتر schema پارامترها deferred می‌شود.
ابزارهای load شده نزدیک انتهای context مدل تزریق می‌شوند تا prompt cache حفظ شود. مجموعه ابزارهای load شده را وسط مکالمه تغییر ندهید، مگر اینکه عمدا بخواهید مسیر cache را بی‌اعتبار کنید.
در حالت hosted، آیتم‌های tool_search_call / tool_search_output مقدار execution: "server" و call_id: null دارند. در حالت client-executed، همان مقدار دقیق tool_search_call.call_id را در tool_search_output برگردانید.
اگر برنامه شما ابزارها را بیرون از جریان معمول tool search load می‌کند، از آیتم ورودی additional_tools در جای درست مکالمه استفاده کنید و هنگام replay کردن state جایگاه همان آیتم را حفظ کنید.

json

{
  "model": "gpt-5.5",
  "input": "سفارش‌های باز مشتری CUST-12345 را فهرست کن.",
  "tools": [
    {
      "type": "namespace",
      "name": "crm",
      "description": "ابزارهای CRM برای جستجوی مشتری و مدیریت سفارش.",
      "tools": [
        {
          "type": "function",
          "name": "get_customer_profile",
          "description": "پروفایل مشتری را با شناسه مشتری دریافت می‌کند.",
          "parameters": {
            "type": "object",
            "properties": {
              "customer_id": {
                "type": "string"
              }
            },
            "required": [
              "customer_id"
            ],
            "additionalProperties": false
          },
          "strict": true
        },
        {
          "type": "function",
          "name": "list_open_orders",
          "description": "سفارش‌های باز یک مشتری را فهرست می‌کند.",
          "defer_loading": true,
          "parameters": {
            "type": "object",
            "properties": {
              "customer_id": {
                "type": "string"
              }
            },
            "required": [
              "customer_id"
            ],
            "additionalProperties": false
          },
          "strict": true
        }
      ]
    },
    {
      "type": "tool_search"
    }
  ],
  "parallel_tool_calls": false
}

ایمنی Remote MCP و connectorها

سرورهای Remote MCP و connectorهای میزبانی‌شده OpenAI قدرتمند هستند، چون می‌توانند ابزارها، داده‌ها و عملیات سرویس‌های ثالث را مستقیم در اختیار مدل بگذارند. در AvalAI این قابلیت‌ها را وابسته به مدل و route بدانید: اگر type: "mcp" یا connector میزبانی‌شده برای مدل انتخابی فعال نیست، یکپارچه‌سازی را در backend خودتان نگه دارید و فقط عملیات امن را به شکل ابزار سفارشی function به مدل بدهید.

وقتی Remote MCP یا connector فعال است:

فقط به سرورهای قابل اعتماد وصل شوید؛ ترجیحا سرورهای رسمی که خود ارائه‌دهنده سرویس اداره می‌کند.
از توکن‌های OAuth یا API با حداقل دسترسی استفاده کنید، آن‌ها را داخل prompt قرار ندهید و مثل هر secret تولیدی rotate کنید.
مقدارهای OAuth در فیلد authorization را در هر درخواستی که به آن نیاز دارد ارسال کنید؛ فرض نکنید state میزبانی‌شده Responses توکن‌های محرمانه را برای turnهای بعدی ذخیره می‌کند.
سطح ابزارهای واردشده را با allowed_tools محدود کنید؛ وقتی workflow فقط به یک یا دو عملیات نیاز دارد، همه ابزارهای سرور را در اختیار مدل نگذارید.
برای عملیات حساس مانند پرداخت، تغییر حساب، حذف داده، ارسال ایمیل یا نوشتن در سیستم‌های خارجی approval الزامی کنید. فراخوانی‌های تأییدشده را با previous_response_id یا با replay کردن آیتم‌های خروجی تایپ‌شده قبلی ادامه دهید.
داده‌هایی را که به سرورهای MCP ثالث فرستاده می‌شود بازبینی و log کنید، به‌ویژه وقتی prompt شامل محتوای کاربر یا محتوای بازیابی‌شده است.
قبل از embed کردن URL یا تصویر برگشتی از ابزارهای MCP، دامنه را اعتبارسنجی کنید؛ خروجی ابزار می‌تواند لینک غیرقابل اعتماد داشته باشد.
اگر route پشتیبانی می‌کند، آیتم‌های mcp_list_tools را در state نگه دارید تا در هر turn ابزارها دوباره فهرست نشوند؛ در غیر این صورت تعریف ابزارها را در لایه برنامه cache و validate کنید.

برای شکل درخواست، نکات OAuth مربوط به connectorها، مدیریت approval و fallback با ابزار function، MCP و connectorها را ببینید.

Agents SDK و agentهای مدیریت‌شده در برنامه

راهنمای ابزارهای OpenAI همین مفاهیم ابزار را در Agents SDK هم به کار می‌برد: ابزارهای میزبانی‌شده یا تابعی را به یک agent متخصص وصل می‌کنید، یا یک agent متخصص را به شکل ابزار قابل فراخوانی برای agent مدیر expose می‌کنید. در مستندات AvalAI این را یک الگوی orchestration بدانید، نه یک قابلیت میزبانی‌شده جداگانه. وقتی runtime و پیکربندی SDK شما بتواند route سازگار با AvalAI را هدف بگیرد از آن استفاده کنید؛ در غیر این صورت orchestration را در برنامه خودتان نگه دارید و مستقیم /v1/responses را فراخوانی کنید.

هنگام تطبیق workflowهای Agents SDK با AvalAI:

همان contract ابزار را نگه دارید که در /v1/responses استفاده می‌کنید: JSON Schema سخت‌گیرانه برای function toolها، توضیح شفاف و خروجی محدود.
approval، چندمستاجری، secretها و بررسی side effectها را در برنامه یا runtime عامل انجام دهید، نه داخل prompt مدل.
اگر یک agent متخصص را به شکل ابزار expose می‌کنید، مرز مسئولیت آن را دقیق توضیح دهید و به‌جای trace کامل، خلاصه فشرده برگردانید.
برای debugging همچنان آیتم‌های تایپ‌شده پاسخ (function_call، mcp_call، web_search_call، message) را بررسی کنید؛ abstraction مربوط به SDK نباید نیازهای audit و billing را پنهان کند.
اگر SDK مقدار base URL، مدل یا گزینه‌های route-specific مورد نیاز شما را expose نمی‌کند، به فراخوانی مستقیم Responses برگردید.

فراخوانی تابع

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

ابزارها

ابزارهای موجود

انتخاب سطح ابزار مناسب

GPT Actions در برابر ابزارهای function در AvalAI

نگاشت احراز هویت برای port کردن الگوهای Actions

fallback برای code interpreter و runtimeهای میزبانی‌شده

ابزارهای استاندارد

ابزارهای مختص Google/Gemini

ابزارهای مختص Alibaba/DashScope

قیمت‌گذاری ابزارها

قیمت‌گذاری جستجوی وب

استفاده در API

مدل آیتم‌های چرخه ابزار در Responses

چک‌لیست طراحی ابزار

بارگذاری تعویقی ابزار با `tool_search`

ایمنی Remote MCP و connectorها

Agents SDK و agentهای مدیریت‌شده در برنامه

فراخوانی تابع

منابع مرتبط

ابزارهای استاندارد

ابزارهای Google/Gemini

ابزارهای Alibaba/DashScope

ابزارها ​

ابزارهای موجود ​

انتخاب سطح ابزار مناسب ​

GPT Actions در برابر ابزارهای function در AvalAI ​

نگاشت احراز هویت برای port کردن الگوهای Actions ​

fallback برای code interpreter و runtimeهای میزبانی‌شده ​

ابزارهای استاندارد ​

ابزارهای مختص Google/Gemini ​

ابزارهای مختص Alibaba/DashScope ​

قیمت‌گذاری ابزارها ​

قیمت‌گذاری جستجوی وب ​

استفاده در API ​

مدل آیتم‌های چرخه ابزار در Responses ​

چک‌لیست طراحی ابزار ​

بارگذاری تعویقی ابزار با tool_search ​

ایمنی Remote MCP و connectorها ​

Agents SDK و agentهای مدیریت‌شده در برنامه ​

فراخوانی تابع ​

منابع مرتبط ​

ابزارهای استاندارد ​

ابزارهای Google/Gemini ​

ابزارهای Alibaba/DashScope ​

ابزارها

ابزارهای موجود

انتخاب سطح ابزار مناسب

GPT Actions در برابر ابزارهای function در AvalAI

نگاشت احراز هویت برای port کردن الگوهای Actions

fallback برای code interpreter و runtimeهای میزبانی‌شده

ابزارهای استاندارد

ابزارهای مختص Google/Gemini

ابزارهای مختص Alibaba/DashScope

قیمت‌گذاری ابزارها

قیمت‌گذاری جستجوی وب

استفاده در API

مدل آیتم‌های چرخه ابزار در Responses

چک‌لیست طراحی ابزار

بارگذاری تعویقی ابزار با `tool_search`

ایمنی Remote MCP و connectorها

Agents SDK و agentهای مدیریت‌شده در برنامه

فراخوانی تابع

منابع مرتبط

ابزارهای استاندارد

ابزارهای Google/Gemini

ابزارهای Alibaba/DashScope