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

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

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

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

پارامترهای اختصاصی ارائه‌دهنده

این راهنما اطلاعات جامعی درباره استفاده از پارامترهای اختصاصی ارائه‌دهنده با AvalAI هنگام کار با مدل‌های ارائه‌دهندگان مختلف از طریق API سازگار با OpenAI ارائه می‌دهد.

فهرست مطالب

پارامترهای اختصاصی ارائه‌دهنده چیست؟
چه زمانی از پارامترهای اختصاصی ارائه‌دهنده استفاده کنیم؟
چرا از پارامترهای اختصاصی ارائه‌دهنده استفاده کنیم؟
نحوه استفاده از پارامترهای اختصاصی ارائه‌دهنده
پارامترهای اختصاصی ارائه‌دهنده رایج
نمونه‌های ارائه‌دهندگان
بهترین شیوه‌ها
عیب‌یابی

پارامترهای اختصاصی ارائه‌دهنده چیست؟

پارامترهای اختصاصی ارائه‌دهنده گزینه‌های پیکربندی اضافی هستند که منحصر به ارائه‌دهندگان مدل هوش مصنوعی فردی (مانند Black Forest Labs، Stability AI، Google، Anthropic و غیره) هستند اما بخشی از مشخصات استاندارد API OpenAI نیستند. این پارامترها به شما امکان دسترسی به ویژگی‌های پیشرفته و تنظیم دقیق رفتار مدل را فراتر از رابط پایه سازگار با OpenAI می‌دهند.

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

چه زمانی از پارامترهای اختصاصی ارائه‌دهنده استفاده کنیم؟

در موارد زیر باید استفاده از پارامترهای اختصاصی ارائه‌دهنده را در نظر بگیرید:

1. کنترل پیشرفته مدل

زمانی که نیاز به کنترل دقیق رفتار مدل دارید
برای تنظیم کیفیت تولید، سبک یا ویژگی‌ها
هنگام کار با ویژگی‌های تخصصی مدل

2. نتایج قابل تکرار

تنظیم بذر (seed) برای خروجی‌های ثابت در چندین اجرا
کنترل تصادفی‌بودن و روش‌های نمونه‌برداری

3. بهینه‌سازی کیفیت و عملکرد

تنظیم مراحل استنتاج، مقیاس‌های راهنمایی یا روش‌های نمونه‌برداری
بهینه‌سازی برای تعادل سرعت در مقابل کیفیت
تنظیم دقیق فرمت‌های خروجی و وضوح‌ها

4. ایمنی محتوا و فیلترینگ

تنظیم سطوح تحمل ایمنی
پیاده‌سازی فیلترینگ محتوای سفارشی
مدیریت تشخیص محتوای نامناسب

5. موارد استفاده تخصصی

ویرایش تصویر با کنترل‌های قدرت خاص
انتقال سبک با پیش‌تنظیمات از پیش تعریف شده
ویژگی‌های پیشرفته مهندسی پرامپت

چرا از پارامترهای اختصاصی ارائه‌دهنده استفاده کنیم؟

دسترسی به قابلیت‌های کامل مدل

هر ارائه‌دهنده مدل‌های خود را با ویژگی‌ها و بهینه‌سازی‌های منحصر به فرد طراحی می‌کند. پارامترهای اختصاصی ارائه‌دهنده این قابلیت‌ها را باز می‌کنند که از طریق رابط استاندارد OpenAI به تنهایی در دسترس نخواهند بود.

نتایج بهتر برای وظایف خاص

ارائه‌دهندگان مختلف در وظایف مختلف برتری دارند. با استفاده از پارامترهای بومی آنها، می‌توانید نتایج بهتری متناسب با مورد استفاده خاص خود به دست آورید.

بهینه‌سازی هزینه و عملکرد

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

ثبات و قابلیت تکرار

بسیاری از پارامترهای اختصاصی ارائه‌دهنده به تضمین نتایج ثابت در چندین فراخوانی API کمک می‌کنند که برای برنامه‌های تولیدی حیاتی است.

نحوه استفاده از پارامترهای اختصاصی ارائه‌دهنده

AvalAI دو روش اصلی برای استفاده از پارامترهای اختصاصی ارائه‌دهنده فراهم می‌کند:

روش 1: استفاده از پارامتر `extra_body` (توصیه شده)

پارامتر extra_body روش استاندارد و توصیه شده است:

python

from openai import OpenAI

client = OpenAI(api_key="your-avalai-api-key", base_url="https://api.avalai.ir/v1")

# مثال با مدل Stability AI
response = client.images.generate(
    model="stability.sd3-5-large-v1:0",
    prompt="منظره کوهستانی باشکوه در غروب آفتاب",
    size="1024x1024",
    extra_body={
        "cfg_scale": 7.5,
        "steps": 50,
        "sampler": "K_DPM_2_ANCESTRAL",
        "seed": 42424,
        "negative_prompt": "blurry, low quality",
    },
)

روش 2: پارامترهای مستقیم (جاوااسکریپت/تایپ‌اسکریپت)

برای کاربران تایپ‌اسکریپت، می‌توانید پارامترها را مستقیما با استفاده از @ts-expect-error ارسال کنید:

javascript

const response = await client.images.generate({
 model: "stability.sd3-5-large-v1:0",
 prompt: "منظره کوهستانی باشکوه در غروب آفتاب",
 size: "1024x1024",
 // @ts-expect-error cfg_scale یک پارامتر اختصاصی ارائه‌دهنده است
 cfg_scale: 7.5,
 // @ts-expect-error steps یک پارامتر اختصاصی ارائه‌دهنده است
 steps: 50,
 // @ts-expect-error sampler یک پارامتر اختصاصی ارائه‌دهنده است
 sampler: "K_DPM_2_ANCESTRAL",
 response_format: "url", // or b64_json
});

نحوه مدیریت پارامترهای اختصاصی ارائه‌دهنده توسط AvalAI

نگاشت خودکار: AvalAI به طور خودکار ارائه‌دهنده مدل را تشخیص می‌دهد و پارامترها را به فرمت API ارائه‌دهنده صحیح نگاشت می‌کند
اعتبارسنجی پارامتر: پارامترهای نامعتبر فیلتر می‌شوند تا از خطاهای API جلوگیری شود
ادغام یکپارچه: پارامترها به طور یکپارچه در کنار پارامترهای استاندارد OpenAI کار می‌کنند

پارامترهای اختصاصی ارائه‌دهنده رایج

در اینجا پرکاربردترین پارامترهای اختصاصی ارائه‌دهنده در ارائه‌دهندگان مختلف آورده شده است:

پارامترهای تولید تصویر

پارامتر	نوع	توضیحات	مقادیر رایج
`cfg_scale`	float	کنترل میزان پیروی مدل از پرامپت	1.0-20.0 (معمول: 7.5)
`steps`	integer	تعداد مراحل استنتاج	10-150 (معمول: 20-50)
`seed`	integer	بذر تصادفی برای نتایج قابل تکرار	هر عدد صحیح
`sampler`	string	روش نمونه‌برداری	"K_DPM_2_ANCESTRAL", "K_EULER"
`negative_prompt`	string	آنچه در تولید باید اجتناب شود	"blurry, low quality"
`style_preset`	string	سبک از پیش تعریف شده	"photographic", "digital-art"
`aspect_ratio`	string	نسبت ابعاد تصویر	"16:9", "1:1", "9:16"
`output_format`	string	فرمت تصویر خروجی	"png", "jpeg", "webp"
`samples`	integer	تعداد نمونه‌های تولیدی	1-10
`guidance_scale`	float	مقیاس راهنمایی برای مدل‌های انتشار	1.0-30.0 (معمول: 7.5)
`num_inference_steps`	integer	تعداد مراحل نویززدایی	10-150 (معمول: 20-50)
`safety_checker`	boolean	فعال/غیرفعال کردن فیلترینگ ایمنی	true, false

پارامترهای کنترل پیشرفته

پارامتر	نوع	توضیحات	مورد استفاده
`prompt_upsampling`	boolean	بهبود خودکار پرامپت	درک بهتر پرامپت
`safety_tolerance`	integer	سطح ایمنی محتوا	0-6 (0=سخت‌گیرانه، 6=ملایم)
`image_strength`	float	قدرت برای تصویر به تصویر	0.0-1.0
`init_image_mode`	string	حالت مقداردهی اولیه	"image_strength", "step_schedule"
`init_image`	string	تصویر اولیه کدگذاری شده Base64	برای تولید تصویر به تصویر
`clip_guidance_preset`	string	تنظیمات راهنمایی CLIP	"FAST_BLUE", "FAST_GREEN"
`extras`	object	گزینه‌های اضافی ارائه‌دهنده	اختصاصی ارائه‌دهنده
`strength`	float	قدرت تبدیل	0.0-1.0
`fidelity`	float	وفاداری به تصویر اصلی	0.0-1.0
`control_strength`	float	قدرت تاثیر شبکه کنترل	0.0-2.0

پارامترهای سبک و ترکیب‌بندی

پارامتر	نوع	توضیحات	مورد استفاده
`change_strength`	float	قدرت تغییرات اعمال شده	عملیات ویرایش تصویر
`style_strength`	float	قدرت اعمال سبک	عملیات انتقال سبک
`composition_fidelity`	float	وفاداری به ترکیب‌بندی اصلی	حفظ ساختار طرح‌بندی
`style_image`	string	مرجع سبک کدگذاری شده Base64	انتقال سبک و راهنمایی
`select_prompt`	string	پرامپت انتخاب ناحیه خاص	عملیات ویرایش هدفمند
`grow_mask`	integer	گسترش ماسک به پیکسل	اینپینتینگ و ویرایش

پارامترهای گفتگو و استدلال

پارامتر	نوع	توضیحات	مورد استفاده
`merge_reasoning_content_in_choices`	boolean	شامل کردن استدلال در پاسخ	مدل‌های استدلال پیشرفته
`chat_template_kwargs`	object	پیکربندی قالب گفتگو	قالب‌بندی گفتگوی سفارشی
`enable_thinking`	boolean	فعال کردن فرآیند تفکر مدل	استدلال و تحلیل
`reasoning_split`	boolean	جداسازی محتوای تفکر در فیلد `reasoning_details`	مدل‌های MiniMax M2.5
`parameters`	object	ظرف پارامتر عمومی	گزینه‌های اختصاصی ارائه‌دهنده

نمونه‌های ارائه‌دهندگان

Black Forest Labs (مدل‌های FLUX)

python

# مدل FLUX با پارامترهای اختصاصی BFL
response = client.images.generate(
    model="flux-1.1-pro",
    prompt="منظره شهری آینده‌نگرانه با ماشین‌های پرنده",
    size="1024x1024",
    extra_body={
        "aspect_ratio": "16:9",
        "output_format": "png",
        "safety_tolerance": 2,
        "prompt_upsampling": True,
    },
)

مدل‌های Stability AI

python

# Stability AI با پارامترهای جامع
response = client.images.generate(
    model="stability.sd3-5-large-v1:0",
    prompt="پرتره جادوگر پیر حکیم",
    size="1024x1024",
    extra_body={
        "cfg_scale": 8.0,
        "steps": 40,
        "sampler": "K_DPM_2_ANCESTRAL",
        "seed": 123456,
        "negative_prompt": "blurry, distorted, low quality, bad anatomy",
        "style_preset": "fantasy-art",
    },
)

ویرایش تصویر Stability AI

python

# اینپینتینگ تصویر با کنترل پیشرفته
response = client.images.edit(
    model="stability.stable-image-inpaint-v1:0",
    image=base64_image,
    mask=base64_mask,
    prompt="A beautiful garden with colorful flowers",  # پرامپت انگلیسی الزامی
    extra_body={
        "strength": 0.8,
        "guidance_scale": 7.5,
        "safety_checker": True,
    },
)

# انتقال سبک با وفاداری ترکیب‌بندی
response = client.images.edit(
    model="stability.stable-style-transfer-v1:0",
    image=content_image,
    prompt="Apply artistic watercolor style",  # پرامپت انگلیسی الزامی
    extra_body={
        "style_image": style_reference_image,
        "style_strength": 0.7,
        "composition_fidelity": 0.8,
        "change_strength": 0.6,
    },
)

# ویرایش انتخابی با رشد ماسک
response = client.images.edit(
    model="stability.stable-image-search-replace-v1:0",
    image=base64_image,
    prompt="Replace with a modern electric car",  # پرامپت انگلیسی الزامی
    extra_body={
        "select_prompt": "old car",  # پرامپت انتخاب انگلیسی
        "grow_mask": 10,
        "fidelity": 0.9,
        "control_strength": 1.2,
    },
)

مدل‌های Google Imagen

python

# Google Imagen با پارامترهای خاص
response = client.images.generate(
    model="imagen-4.0-ultra-generate-001",
    prompt="باغ ژاپنی آرام در بهار",
    size="1024x1024",
)

مدل‌های تصویری Nano Banana گوگل (Gemini)

مدل‌های سری Nano Banana (gemini-2.5-flash-image و gemini-3-pro-image) مدل‌های پیشرفته تولید تصویر گوگل هستند که از طریق AvalAI در دسترس هستند. هنگام استفاده از endpoint سازگار با OpenAI (v1/chat/completions)، می‌توانید پارامترهای بومی Gemini مانند aspectRatio و imageSize را از طریق پارامتر extra_body ارسال کنید.

توجه

کاربران همیشه می‌توانند از API بومی Gemini (v1beta) برای دسترسی به تمام پارامترهای Gemini به صورت مستقیم با استفاده از SDK رسمی گوگل استفاده کنند. اما هنگام استفاده از endpoint های سازگار با OpenAI، پارامترهای اختصاصی Gemini باید از طریق extra_body ارسال شوند.

پارامترهای پشتیبانی شده imageConfig:

پارامتر	نوع	توضیحات	مقادیر پشتیبانی شده	مدل‌های پشتیبانی شده
`aspectRatio`	string	نسبت ابعاد تصویر	"1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9"	`gemini-2.5-flash-image`, `gemini-3-pro-image`
`imageSize`	string	اندازه تصویر خروجی	"1K", "2K", "4K"	فقط `gemini-3-pro-image`

Gemini 2.5 Flash Image (Nano Banana)

python

from openai import OpenAI

client = OpenAI(api_key="your-avalai-api-key", base_url="https://api.avalai.ir/v1")

# تولید تصویر با نسبت ابعاد سفارشی
response = client.chat.completions.create(
    model="gemini-2.5-flash-image",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Generate a sunset beach scene",
                },
            ],
        }
    ],
    modalities=["image", "text"],
    extra_body={"generationConfig": {"imageConfig": {"aspectRatio": "16:9"}}},
)

# دسترسی به تصویر تولید شده
if response.choices[0].message.images:
    image_url = response.choices[0].message.images[0]["image_url"]["url"]
    print(f"URL تصویر تولید شده: {image_url}")

نسخه معادل Responses API مدل این نسخه روی `gpt-5.5` تنظیم شده، چون `gemini-2.5-flash-image` ممکن است در داده‌های فعلی AvalAI برای `/v1/responses` فعال نباشد.

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، این نسخه را کنار مثال Chat Completions استفاده کنید. messages به input منتقل می‌شود و متن نهایی از 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",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Describe this image."},
                {"type": "input_image", "image_url": "https://example.com/image.png"},
            ],
        }
    ],
)

print(response.output_text)

messages → input
پیام سیستمی → instructions یا آیتم developer
choices[0].message.content → response.output_text
برای ابزارها و خروجی‌های چندوجهی، response.output را بر اساس type بررسی کنید.

Gemini 3 Pro Image Preview (Nano Banana Pro)

python

from openai import OpenAI

client = OpenAI(api_key="your-avalai-api-key", base_url="https://api.avalai.ir/v1")

# تولید تصویر 4K با نسبت ابعاد سفارشی
response = client.chat.completions.create(
    model="gemini-3-pro-image",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Generate a sunset beach scene",
                },
            ],
        }
    ],
    modalities=["image", "text"],
    extra_body={
        "generationConfig": {
            "imageConfig": {
                "aspectRatio": "16:9",
                "imageSize": "4k",  # فقط توسط gemini-3-pro-image پشتیبانی می‌شود
            }
        }
    },
)

# دسترسی به تصویر تولید شده
if response.choices[0].message.images:
    image_url = response.choices[0].message.images[0]["image_url"]["url"]
    print(f"URL تصویر 4K تولید شده: {image_url}")

نسخه معادل Responses API مدل این نسخه روی `gpt-5.5` تنظیم شده، چون `gemini-3-pro-image` ممکن است در داده‌های فعلی AvalAI برای `/v1/responses` فعال نباشد.

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، این نسخه را کنار مثال Chat Completions استفاده کنید. messages به input منتقل می‌شود و متن نهایی از 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",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Describe this image."},
                {"type": "input_image", "image_url": "https://example.com/image.png"},
            ],
        }
    ],
)

print(response.output_text)

messages → input
پیام سیستمی → instructions یا آیتم developer
choices[0].message.content → response.output_text
برای ابزارها و خروجی‌های چندوجهی، response.output را بر اساس type بررسی کنید.

نمونه cURL:

bash

curl https://api.avalai.ir/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
    "model": "gemini-3-pro-image",
    "messages": [
      {
        "role": "user",
        "content": "Generate a sunset beach scene"
      }
    ],
    "modalities": ["image", "text"],
    "extra_body": {
      "generationConfig": {
        "imageConfig": {
          "aspectRatio": "16:9",
          "imageSize": "4k"
        }
      }
    }
  }'

نسخه معادل Responses API مدل این نسخه روی `gpt-5.5` تنظیم شده، چون `gemini-3-pro-image` ممکن است در داده‌های فعلی AvalAI برای `/v1/responses` فعال نباشد.

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، این نسخه را کنار مثال Chat Completions استفاده کنید. messages به input منتقل می‌شود و متن نهایی از response.output_text خوانده می‌شود.

bash

curl https://api.avalai.ir/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '
  {
    "model": "gpt-5.5",
    "input": "Generate a sunset beach scene",
    "instructions": "You are a helpful assistant."
  }'

messages → input
پیام سیستمی → instructions یا آیتم developer
choices[0].message.content → response.output_text
برای ابزارها و خروجی‌های چندوجهی، response.output را بر اساس type بررسی کنید.

برای مثال‌های جزئی‌تر، به تولید پیشرفته تصویر با Gemini و تولید تصاویر با Gemini 2.5 Flash مراجعه کنید.

تنظیمات ایمنی Gemini

هنگام استفاده از مدل‌های Gemini، می‌توانید تنظیمات ایمنی داخلی را از طریق extra_body پیکربندی کنید تا نظارت بر محتوا را مستقیما در فراخوانی‌های API خود کنترل کنید:

python

# پیکربندی تنظیمات ایمنی برای مدل‌های Gemini
response = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[{"role": "user", "content": "پرامپت شما اینجا"}],
    extra_body={
        "safety_settings": [
            {
                "category": "HARM_CATEGORY_HARASSMENT",
                "threshold": "BLOCK_MEDIUM_AND_ABOVE",
            },
            {
                "category": "HARM_CATEGORY_HATE_SPEECH",
                "threshold": "BLOCK_LOW_AND_ABOVE",
            },
            {
                "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
                "threshold": "BLOCK_MEDIUM_AND_ABOVE",
            },
            {
                "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
                "threshold": "BLOCK_ONLY_HIGH",
            },
        ]
    },
)

نسخه معادل Responses API مدل این نسخه روی `gpt-5.5` تنظیم شده، چون `gemini-2.5-flash` ممکن است در داده‌های فعلی AvalAI برای `/v1/responses` فعال نباشد.

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، این نسخه را کنار مثال Chat Completions استفاده کنید. messages به input منتقل می‌شود و متن نهایی از 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",
    instructions="You are a helpful assistant.",
    input="پرامپت شما اینجا",
)

print(response.output_text)

messages → input
پیام سیستمی → instructions یا آیتم developer
choices[0].message.content → response.output_text
برای ابزارها و خروجی‌های چندوجهی، response.output را بر اساس type بررسی کنید.

این زمانی مفید است که نیاز به نظارت بر محتوا دارید اما می‌خواهید از فراخوانی‌های جداگانه به API نظارت خودداری کنید. برای مستندات جامع درباره تنظیمات ایمنی Gemini، به راهنمای تنظیمات ایمنی Gemini مراجعه کنید.

تکمیل گفتگو با پارامترهای پیشرفته

پارامترهای اختصاصی ارائه‌دهنده با تکمیل گفتگو نیز کار می‌کنند:

python

# Anthropic Claude با پارامترهای استدلال
response = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "محاسبات کوانتومی را توضیح دهید"}],
    extra_body={
        "enable_thinking": True,
        "merge_reasoning_content_in_choices": True,
        "chat_template_kwargs": {"format": "detailed"},
        "parameters": {"analysis_depth": "comprehensive"},
    },
)

# OpenAI با پارامترهای سفارشی
response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "این داده‌ها را تحلیل کنید"}],
    extra_body={
        "safety_checker": True,
        "parameters": {"reasoning_mode": "step_by_step"},
    },
)

نسخه معادل Responses API مدل این نسخه روی `gpt-5.5` تنظیم شده، چون `claude-sonnet-4-6` ممکن است در داده‌های فعلی AvalAI برای `/v1/responses` فعال نباشد.

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، این نسخه را کنار مثال Chat Completions استفاده کنید. messages به input منتقل می‌شود و متن نهایی از 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",
    instructions="You are a helpful assistant.",
    input="این داده‌ها را تحلیل کنید",
)

print(response.output_text)

messages → input
پیام سیستمی → instructions یا آیتم developer
choices[0].message.content → response.output_text
برای ابزارها و خروجی‌های چندوجهی، response.output را بر اساس type بررسی کنید.

مدل‌های MiniMax (استدلال M2.5)

مدل‌های MiniMax M2.5 شامل قابلیت‌های استدلالی داخلی با محتوای تفکر هستند. به طور پیش‌فرض، محتوای استدلال در تگ‌های <think> و </think> در محتوای پاسخ ظاهر می‌شود. شما می‌توانید از پارامتر reasoning_split برای جداسازی این محتوا در فیلد اختصاصی reasoning_details استفاده کنید.

پارامترهای کلیدی:

پارامتر	نوع	توضیحات
`reasoning_split`	boolean	وقتی `true` باشد، محتوای تفکر را در فیلد `reasoning_details` جدا می‌کند به جای تگ‌های `<think>` در محتوا

رفتار پیش‌فرض (reasoning_split=false):

فرآیند تفکر مدل به صورت درون‌خطی با تگ‌های <think> ظاهر می‌شود:

python

from openai import OpenAI

client = OpenAI(api_key="your-avalai-api-key", base_url="https://api.avalai.ir/v1")

response = client.chat.completions.create(
    model="minimax-m2.5",
    messages=[{"role": "user", "content": "25 ضرب در 37 چند است؟"}],
)

# محتوای پاسخ شامل: <think>بگذارید محاسبه کنم... 25 * 37 = 925</think>پاسخ 925 است.
print(response.choices[0].message.content)

نسخه معادل Responses API مدل این نسخه روی `gpt-5.5` تنظیم شده، چون `minimax-m2.5` ممکن است در داده‌های فعلی AvalAI برای `/v1/responses` فعال نباشد.

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، این نسخه را کنار مثال Chat Completions استفاده کنید. messages به input منتقل می‌شود و متن نهایی از 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",
    instructions="You are a helpful assistant.",
    input="25 ضرب در 37 چند است؟",
)

print(response.output_text)

messages → input
پیام سیستمی → instructions یا آیتم developer
choices[0].message.content → response.output_text
برای ابزارها و خروجی‌های چندوجهی، response.output را بر اساس type بررسی کنید.

با reasoning_split=true:

محتوای تفکر در فیلد reasoning_details جدا می‌شود:

python

from openai import OpenAI

client = OpenAI(api_key="your-avalai-api-key", base_url="https://api.avalai.ir/v1")

response = client.chat.completions.create(
    model="minimax-m2.5",
    messages=[{"role": "user", "content": "25 ضرب در 37 چند است؟"}],
    extra_body={"reasoning_split": True},
)

# دسترسی به محتوای استدلال جداشده
message = response.choices[0].message
print(f"استدلال: {message.reasoning_details}")  # شامل فرآیند تفکر
print(f"پاسخ: {message.content}")  # فقط شامل پاسخ نهایی

نسخه معادل Responses API مدل این نسخه روی `gpt-5.5` تنظیم شده، چون `minimax-m2.5` ممکن است در داده‌های فعلی AvalAI برای `/v1/responses` فعال نباشد.

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، این نسخه را کنار مثال Chat Completions استفاده کنید. messages به input منتقل می‌شود و متن نهایی از 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",
    instructions="You are a helpful assistant.",
    input="25 ضرب در 37 چند است؟",
)

print(response.output_text)

messages → input
پیام سیستمی → instructions یا آیتم developer
choices[0].message.content → response.output_text
برای ابزارها و خروجی‌های چندوجهی، response.output را بر اساس type بررسی کنید.

مدیریت تاریخچه مکالمه:

هنگام استفاده از MiniMax-M2.5، مطمئن شوید که پیام پاسخ کامل (شامل استدلال) را در تاریخچه مکالمه خود حفظ می‌کنید:

python

messages = [{"role": "user", "content": "این را قدم به قدم حل کن: 2x + 5 = 15"}]

response = client.chat.completions.create(
    model="minimax-m2.5",
    messages=messages,
    extra_body={"reasoning_split": True},
)

# پیام پاسخ کامل را به تاریخچه اضافه کنید (reasoning_details حفظ می‌شود)
assistant_message = response.choices[0].message
messages.append(
    {
        "role": "assistant",
        "content": assistant_message.content,
        # وقتی reasoning_split=True، reasoning_details را هم در تاریخچه قرار دهید
        "reasoning_details": getattr(assistant_message, "reasoning_details", None),
    }
)

# ادامه مکالمه
messages.append({"role": "user", "content": "حالا 3x + 7 = 22 را حل کن"})

نسخه معادل Responses API مدل این نسخه روی `gpt-5.5` تنظیم شده، چون `minimax-m2.5` ممکن است در داده‌های فعلی AvalAI برای `/v1/responses` فعال نباشد.

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، این نسخه را کنار مثال Chat Completions استفاده کنید. messages به input منتقل می‌شود و متن نهایی از 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",
    instructions="You are a helpful assistant.",
    input="حالا 3x + 7 = 22 را حل کن",
)

print(response.output_text)

messages → input
پیام سیستمی → instructions یا آیتم developer
choices[0].message.content → response.output_text
برای ابزارها و خروجی‌های چندوجهی، response.output را بر اساس type بررسی کنید.

برای جزئیات بیشتر درباره مدل‌های MiniMax، به مدل‌های MiniMax مراجعه کنید.

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

1. با مقادیر پیش‌فرض شروع کنید

با پارامترهای استاندارد شروع کنید و تدریجا پارامترهای اختصاصی ارائه‌دهنده را در صورت نیاز معرفی کنید:

python

# ساده شروع کنید
response = client.images.generate(
    model="stability.sd3-5-large-v1:0", prompt="غروب آفتاب زیبا", size="1024x1024"
)

# سپس پارامترهای خاص را برای کنترل بهتر اضافه کنید
response = client.images.generate(
    model="stability.sd3-5-large-v1:0",
    prompt="غروب آفتاب زیبا",
    size="1024x1024",
    extra_body={"cfg_scale": 7.5, "steps": 30},  # پیروی بهتر از پرامپت  # کیفیت بالاتر
)

2. از مقادیر پارامتر مناسب استفاده کنید

محدوده‌های توصیه شده برای هر پارامتر را بررسی کنید:

python

# مقادیر پارامتر خوب
extra_body = {
    "cfg_scale": 7.5,  # نقطه بهینه برای اکثر موارد
    "steps": 20 - 50,  # تعادل کیفیت و سرعت
    "seed": 42424,  # هر عدد صحیح ثابت
    "safety_tolerance": 2,  # سطح ایمنی متوسط
}

# از مقادیر افراطی که ممکن است مشکل ایجاد کنند خودداری کنید
extra_body = {
    "cfg_scale": 50,  # خیلی بالا، ممکن است اختلال ایجاد کند
    "steps": 200,  # بی‌دلیل کند
    "safety_tolerance": 6,  # ممکن است محتوای نامناسب مجاز کند
}

3. خطاها را به درستی مدیریت کنید

همیشه مدیریت خطای مناسب پیاده‌سازی کنید:

python

try:
    response = client.images.generate(
        model="stability.sd3-5-large-v1:0",
        prompt="نقاشی منظره",
        size="1024x1024",
        extra_body={"cfg_scale": 7.5, "steps": 30},
    )
except Exception as e:
    print(f"خطا با پارامترهای اختصاصی ارائه‌دهنده: {e}")
    # بازگشت به پارامترهای پایه
    response = client.images.generate(
        model="stability.sd3-5-large-v1:0", prompt="نقاشی منظره", size="1024x1024"
    )

4. انتخاب‌های پارامتر خود را مستند کنید

ترکیبات پارامتر موفق را پیگیری کنید:

python

# پیکربندی‌های موفق را مستند کنید
STABILITY_PHOTOREALISTIC = {
    "cfg_scale": 8.0,
    "steps": 40,
    "sampler": "K_DPM_2_ANCESTRAL",
    "style_preset": "photographic",
    "negative_prompt": "cartoon, anime, painting, drawing",
}

STABILITY_ARTISTIC = {
    "cfg_scale": 7.0,
    "steps": 30,
    "sampler": "K_EULER",
    "style_preset": "digital-art",
}

5. تاثیر پارامتر را آزمایش کنید

با مقادیر مختلف آزمایش کنید تا اثرات آنها را درک کنید:

python

# A/B تست پیکربندی‌های مختلف
configs = [
    {"cfg_scale": 5.0, "steps": 20},
    {"cfg_scale": 7.5, "steps": 30},
    {"cfg_scale": 10.0, "steps": 40},
]

for i, config in enumerate(configs):
    response = client.images.generate(
        model="stability.sd3-5-large-v1:0",
        prompt="پرامپت آزمایشی",
        size="1024x1024",
        extra_body=config,
    )
    # نتایج را ذخیره و مقایسه کنید

6. از بذر برای قابلیت تکرار استفاده کنید

همیشه زمانی که نیاز به نتایج ثابت دارید از بذر استفاده کنید:

python

# برای برنامه‌های تولیدی که نیاز به ثبات دارند
PRODUCTION_CONFIG = {
    "seed": 42424,  # بذر ثابت
    "cfg_scale": 7.5,  # کیفیت ثابت
    "steps": 30,  # تعادل سرعت/کیفیت
}

# برای آزمایش، اجازه دهید بذر متغیر باشد
EXPERIMENTAL_CONFIG = {
    "cfg_scale": 7.5,
    "steps": 30,
    # بدون بذر = نتایج تصادفی در هر بار
}

7. برای مورد استفاده خود بهینه‌سازی کنید

برای سرعت (برنامه‌های بلادرنگ)

python

SPEED_OPTIMIZED = {
    "steps": 15,  # مراحل کمتر
    "cfg_scale": 6.0,  # راهنمایی پایین‌تر
    "sampler": "K_EULER",  # نمونه‌برداری سریع
}

برای کیفیت (تولید نهایی)

python

QUALITY_OPTIMIZED = {
    "steps": 50,  # مراحل بیشتر
    "cfg_scale": 8.0,  # راهنمایی بالاتر
    "sampler": "K_DPM_2_ANCESTRAL",  # نمونه‌برداری با کیفیت بالا
}

برای ثبات (پردازش دسته‌ای)

python

CONSISTENCY_OPTIMIZED = {
    "seed": 12345,  # بذر ثابت
    "cfg_scale": 7.5,  # راهنمایی استاندارد
    "steps": 30,  # مراحل ثابت
    "sampler": "K_DPM_2_ANCESTRAL",
}

عیب‌یابی

مشکلات رایج و راه‌حل‌ها

مشکل: پارامترها تاثیر نمی‌گذارند

python

# مشکل: پارامترها نادیده گرفته می‌شوند
response = client.images.generate(
    model="gpt-image-2",  # مدل OpenAI
    prompt="غروب آفتاب",
    extra_body={"cfg_scale": 7.5},  # این با مدل‌های OpenAI کار نمی‌کند
)

# راه‌حل: از مدل مناسب استفاده کنید
response = client.images.generate(
    model="stability.sd3-5-large-v1:0",  # مدل Stability AI
    prompt="غروب آفتاب",
    extra_body={"cfg_scale": 7.5},  # این کار می‌کند
)

مشکل: مقادیر پارامتر نامعتبر

python

# مشکل: محدوده پارامتر نامعتبر
extra_body = {"cfg_scale": 100, "steps": -5}  # خیلی بالا  # مقدار منفی نامعتبر

# راه‌حل: از محدوده‌های معتبر استفاده کنید
extra_body = {
    "cfg_scale": 7.5,  # محدوده معتبر: 1.0-20.0
    "steps": 30,  # محدوده معتبر: 1-150
}

مشکل: خطاهای نام پارامتر

python

# مشکل: نام‌های پارامتر نادرست
extra_body = {
    "guidance_scale": 7.5,  # نام اشتباه برای Stability AI
    "num_steps": 30,  # نام اشتباه برای Stability AI
}

# راه‌حل: از نام‌های پارامتر صحیح استفاده کنید
extra_body = {
    "cfg_scale": 7.5,  # صحیح برای Stability AI
    "steps": 30,  # صحیح برای Stability AI
}

نکات عیب‌یابی

سازگاری مدل را بررسی کنید: اطمینان حاصل کنید که مدل از پارامترهایی که استفاده می‌کنید پشتیبانی می‌کند
نام‌های پارامتر را اعتبارسنجی کنید: نام‌های پارامتر را با مستندات ارائه‌دهنده دوباره بررسی کنید
به تدریج آزمایش کنید: یک پارامتر در هر بار اضافه کنید تا مشکلات را شناسایی کنید
از مدیریت خطا استفاده کنید: بلوک‌های try-catch برای مدیریت مناسب خطاهای پارامتر پیاده‌سازی کنید
مستندات ارائه‌دهنده را بررسی کنید: برای جزئیات پارامتر به مستندات ارائه‌دهندگان فردی مراجعه کنید

دریافت کمک

مستندات AvalAI: برای پارامترهای پشتیبانی شده مرجع API را بررسی کنید
مستندات ارائه‌دهنده: برای اطلاعات جزئی پارامتر به مستندات ارائه‌دهندگان فردی مراجعه کنید
پشتیبانی انجمن: برای نکات و بهترین شیوه‌ها به انجمن AvalAI بپیوندید
پیام‌های خطا: به پیام‌های خطا توجه کنید که اغلب مشکلات پارامتر را نشان می‌دهند

منابع مرتبط

راهنمای شروع سریع - استفاده پایه از پارامترهای اختصاصی ارائه‌دهنده
راهنمای تولید تصویر - استفاده از پارامتر مخصوص تصویر
مرجع API - مستندات کامل API
مستندات مدل - قابلیت‌ها و پارامترهای مدل‌های فردی
بهترین شیوه‌ها - راهنمای استقرار

پارامترهای اختصاصی ارائه‌دهنده ​

فهرست مطالب ​

پارامترهای اختصاصی ارائه‌دهنده چیست؟ ​

چه زمانی از پارامترهای اختصاصی ارائه‌دهنده استفاده کنیم؟ ​

1. کنترل پیشرفته مدل ​

2. نتایج قابل تکرار ​

3. بهینه‌سازی کیفیت و عملکرد ​

4. ایمنی محتوا و فیلترینگ ​

5. موارد استفاده تخصصی ​

چرا از پارامترهای اختصاصی ارائه‌دهنده استفاده کنیم؟ ​

دسترسی به قابلیت‌های کامل مدل ​

نتایج بهتر برای وظایف خاص ​

بهینه‌سازی هزینه و عملکرد ​

ثبات و قابلیت تکرار ​

نحوه استفاده از پارامترهای اختصاصی ارائه‌دهنده ​

روش 1: استفاده از پارامتر extra_body (توصیه شده) ​

روش 2: پارامترهای مستقیم (جاوااسکریپت/تایپ‌اسکریپت) ​

نحوه مدیریت پارامترهای اختصاصی ارائه‌دهنده توسط AvalAI ​

پارامترهای اختصاصی ارائه‌دهنده رایج ​

پارامترهای تولید تصویر ​

پارامترهای کنترل پیشرفته ​

پارامترهای سبک و ترکیب‌بندی ​

پارامترهای گفتگو و استدلال ​

نمونه‌های ارائه‌دهندگان ​

Black Forest Labs (مدل‌های FLUX) ​

مدل‌های Stability AI ​

ویرایش تصویر Stability AI ​

مدل‌های Google Imagen ​

مدل‌های تصویری Nano Banana گوگل (Gemini) ​

Gemini 2.5 Flash Image (Nano Banana) ​

Gemini 3 Pro Image Preview (Nano Banana Pro) ​

تنظیمات ایمنی Gemini ​

تکمیل گفتگو با پارامترهای پیشرفته ​

مدل‌های MiniMax (استدلال M2.5) ​

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

1. با مقادیر پیش‌فرض شروع کنید ​

2. از مقادیر پارامتر مناسب استفاده کنید ​

3. خطاها را به درستی مدیریت کنید ​

4. انتخاب‌های پارامتر خود را مستند کنید ​

5. تاثیر پارامتر را آزمایش کنید ​

6. از بذر برای قابلیت تکرار استفاده کنید ​

7. برای مورد استفاده خود بهینه‌سازی کنید ​

برای سرعت (برنامه‌های بلادرنگ) ​

برای کیفیت (تولید نهایی) ​

برای ثبات (پردازش دسته‌ای) ​

عیب‌یابی ​

مشکلات رایج و راه‌حل‌ها ​

مشکل: پارامترها تاثیر نمی‌گذارند ​

مشکل: مقادیر پارامتر نامعتبر ​

مشکل: خطاهای نام پارامتر ​

نکات عیب‌یابی ​

دریافت کمک ​

منابع مرتبط ​

پارامترهای اختصاصی ارائه‌دهنده

فهرست مطالب

پارامترهای اختصاصی ارائه‌دهنده چیست؟

چه زمانی از پارامترهای اختصاصی ارائه‌دهنده استفاده کنیم؟

1. کنترل پیشرفته مدل

2. نتایج قابل تکرار

3. بهینه‌سازی کیفیت و عملکرد

4. ایمنی محتوا و فیلترینگ

5. موارد استفاده تخصصی

چرا از پارامترهای اختصاصی ارائه‌دهنده استفاده کنیم؟

دسترسی به قابلیت‌های کامل مدل

نتایج بهتر برای وظایف خاص

بهینه‌سازی هزینه و عملکرد

ثبات و قابلیت تکرار

نحوه استفاده از پارامترهای اختصاصی ارائه‌دهنده

روش 1: استفاده از پارامتر `extra_body` (توصیه شده)

روش 2: پارامترهای مستقیم (جاوااسکریپت/تایپ‌اسکریپت)

نحوه مدیریت پارامترهای اختصاصی ارائه‌دهنده توسط AvalAI

پارامترهای اختصاصی ارائه‌دهنده رایج

پارامترهای تولید تصویر

پارامترهای کنترل پیشرفته

پارامترهای سبک و ترکیب‌بندی

پارامترهای گفتگو و استدلال

نمونه‌های ارائه‌دهندگان

Black Forest Labs (مدل‌های FLUX)

مدل‌های Stability AI

ویرایش تصویر Stability AI

مدل‌های Google Imagen

مدل‌های تصویری Nano Banana گوگل (Gemini)

Gemini 2.5 Flash Image (Nano Banana)

Gemini 3 Pro Image Preview (Nano Banana Pro)

تنظیمات ایمنی Gemini

تکمیل گفتگو با پارامترهای پیشرفته

مدل‌های MiniMax (استدلال M2.5)

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

1. با مقادیر پیش‌فرض شروع کنید

2. از مقادیر پارامتر مناسب استفاده کنید

3. خطاها را به درستی مدیریت کنید

4. انتخاب‌های پارامتر خود را مستند کنید

5. تاثیر پارامتر را آزمایش کنید

6. از بذر برای قابلیت تکرار استفاده کنید

7. برای مورد استفاده خود بهینه‌سازی کنید

برای سرعت (برنامه‌های بلادرنگ)

برای کیفیت (تولید نهایی)

برای ثبات (پردازش دسته‌ای)

عیب‌یابی

مشکلات رایج و راه‌حل‌ها

مشکل: پارامترها تاثیر نمی‌گذارند

مشکل: مقادیر پارامتر نامعتبر

مشکل: خطاهای نام پارامتر

نکات عیب‌یابی

دریافت کمک

منابع مرتبط