یکپارچه‌سازی AvalAI با افزونه‌های VSCode

دستیارهای کدنویسی مبتنی بر هوش مصنوعی VSCode مانند GitHub Copilot، Continue و افزونه‌های مشابه، قابلیت‌های پیشرفته توسعه را مستقیما در محیط ویرایشگر شما فراهم می‌کنند. با یکپارچه‌سازی AvalAI، به بیش از 410 مدل پیشرفته هوش مصنوعی از ارائه‌دهندگان برتری چون OpenAI، Anthropic، Google و Meta—همگی از طریق یک API واحد—دسترسی خواهید داشت.

اکثر افزونه‌های مدرن هوش مصنوعی VSCode از APIهای سازگار با OpenAI به همراه قابلیت تنظیم URL پایه سفارشی پشتیبانی می‌کنند، که یکپارچه‌سازی با AvalAI را بسیار ساده می‌سازد. این رویکرد در سایر ویرایشگرهای کد نظیر Cursor که از پیکربندی‌های سازگار با OpenAI پشتیبانی می‌کنند نیز به خوبی کار می‌کند.

💰 پیشنهاد ویژه

با بسته‌های اعتباری اختصاصی AvalAI، تا ۷۰٪ اعتبار بیشتر دریافت کنید یا از تا ۴۰٪ تخفیف ویژه در خریدهای خود بهره‌مند شوید. این پیشنهادهای منحصر به فرد به شما کمک می‌کنند بودجه توسعه هوش مصنوعی خود را به بهترین شکل مدیریت کنید!

چرا AvalAI را با افزونه‌های VSCode یکپارچه کنیم؟

یکپارچه‌سازی AvalAI با دستیار کدنویسی شما، مزایا و قابلیت‌های قدرتمندی را به گردش کار توسعه شما اضافه می‌کند:

• دسترسی به بیش از 410 مدل: از میان مدل‌هایی مانند GPT-5.5، Claude Opus 4.8، Gemini 3.5 Flash، GLM-5.2، MiniMax M3، Kimi K2.7 Code، DeepSeek-V4 و بسیاری دیگر انتخاب کنید
• تولید کد هوشمند: قطعات کد، توابع کامل یا حتی فایل‌های کامل را در زبان‌های برنامه‌نویسی مختلف تولید کنید
• توضیح و تحلیل کد: توضیحات روشن و مفصل از بخش‌های پیچیده کد دریافت کنید
• کمک به بازسازی کد: با پیشنهادات هوشمند مبتنی بر هوش مصنوعی، کیفیت کد خود را ارتقا دهید
• شناسایی و رفع باگ: مشکلات موجود در کدبیس را به سرعت شناسایی و رفع کنید
• مستندسازی خودکار: مستندات جامع و حرفه‌ای برای کد خود تولید کنید
• پشتیبانی چند زبانه: با تقریبا هر زبان برنامه‌نویسی یا فریمورکی کار کنید
• مقرون به صرفه بودن: از قیمت‌گذاری رقابتی AvalAI که کاملا با نرخ‌های ارائه‌دهندگان اصلی همسو است، بهره‌مند شوید
• انعطاف‌پذیری کامل: به راحتی بین مدل‌های مختلف هوش مصنوعی بر اساس نیازهای خاص پروژه خود جابجا شوید

دریافت کلید API از AvalAI (راهنمای گام به گام)

برای دریافت کلید API خود، این مراحل را دنبال کنید:

1. ایجاد حساب کاربری AvalAI: در صورتی که هنوز حساب کاربری ندارید، به داشبورد AvalAI مراجعه کرده و ثبت‌نام کنید.

2. ورود به بخش کلیدهای API: پس از ورود به حساب کاربری، به بخش "کلید‌های API" در داشبورد خود بروید.

3. ایجاد کلید جدید: روی دکمه "ساخت کلید جدید" یا "Create new secret key" کلیک کنید.

4. نام‌گذاری کلید (اختیاری اما توصیه می‌شود): برای مدیریت بهتر، به کلید API خود نامی توصیفی مانند "توسعه VSCode" یا "پروژه X" اختصاص دهید.

5. کپی و ذخیره‌سازی کلید API: کلید تولید شده تنها یک بار نمایش داده می‌شود. بسیار مهم: این کلید را فورا کپی کرده و در مکانی امن ذخیره کنید. به دلایل امنیتی، امکان مشاهده مجدد کلید کامل وجود ندارد.

پیکربندی افزونه‌های VSCode برای استفاده از AvalAI

راه‌اندازی GitHub Copilot (استفاده از کلید شخصی - BYOK)

اکنون VS Code Copilot به طور مستقیم از ارائه‌دهندگان API شخص ثالث مانند AvalAI پشتیبانی می‌کند؛ این کار از طریق قابلیت داخلی Custom Endpoint / Bring Your Own Key (BYOK) انجام می‌شود. شما می‌توانید مدل‌های سازگار با OpenAI متعلق به AvalAI را با استفاده از رابط کاربری بومی، بازنویسی فایل settings.json یا یک افزونه واسط از فروشگاه، به منوی انتخاب مدل Copilot Chat اضافه کنید.

روش اول: رابط کاربری Custom Endpoint داخلی

VS Code به صورت بومی از endpointهای شخص ثالث مستقیما در معماری مدل زبانی خود پشتیبانی می‌کند.

1. باز کردن Language Models: نمای Chat را باز کنید، سپس روی آیکون چرخ‌دنده (Manage Language Models) کنار انتخابگر مدل کلیک کنید. به عنوان جایگزین، Command Palette را باز کنید (Ctrl+Shift+P / Cmd+Shift+P) و دستور Chat: Manage Language Models را اجرا کنید.

2. افزودن Custom Endpoint: روی Add Models کلیک کرده و گزینه Custom Endpoint (یا OpenAI Compatible) را از فهرست کشویی ارائه‌دهندگان انتخاب کنید.

3. پیکربندی تنظیمات:

   • Group Name: یک برچسب برای شناسایی گروه ارائه‌دهنده سفارشی خود وارد کنید (برای مثال: AvalAI).
   • Base URL: آدرس https://api.avalai.ir/v1 را وارد کنید.
   • API Key: کلید API خود از AvalAI را وارد کنید.
   • API Type: گزینه Chat Completions را انتخاب کنید.

4. انتخاب مدل: تغییرات خود را ذخیره کنید. در صورت نیاز VS Code را مجددا راه‌اندازی کنید، سپس مدل جدید خود را از انتخابگر کشویی مدل در Copilot Chat انتخاب کنید.

روش دوم: بازنویسی مستقیم از طریق JSON در Settings

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

1. باز کردن Settings: فایل settings.json سراسری خود را در VS Code باز کنید.

2. افزودن مدل‌های سفارشی: پیکربندی مدل سفارشی را با استفاده از اسکیمای بومی تنظیمات اضافه کنید:

   {
   "github.copilot.chat.customOAIModels": [
    {
      "modelId": "claude-opus-4-8",
      "displayName": "AvalAI Claude Opus 4.8",
      "endpoint": "https://api.avalai.ir/v1",
   
      "apiKey": "کلید_API_شما"
    }
   ]
   }

3. جایگزینی کلید API: عبارت کلید_API_شما را با کلید واقعی API خود از AvalAI جایگزین کنید و مقادیر modelId/displayName را روی هر یک از 410+ مدل موجود تنظیم کنید.

روش سوم: استفاده از افزونه واسط فروشگاه

اگر رابط کاربری بومی BYOK برای پیکربندی خاص پروکسی یا gateway شما محدودکننده است، می‌توانید API را از طریق افزونه‌های تخصصی واسط متصل کنید.

1. نصب یک افزونه واسط: در فروشگاه به دنبال ابزارهایی مانند Copilot Custom Provider یا LM Custom Provider بگردید.

2. اجرای مدیر راه‌اندازی: افزونه را نصب کنید، سپس مدیر راه‌اندازی مخصوص آن را از Command Palette اجرا کنید.

3. پیکربندی AvalAI: آدرس پایه سفارشی (https://api.avalai.ir/v1) و کلید API خود از AvalAI را وارد کنید، سپس مدل‌های سفارشی خود را به صورت دستی واکشی یا اضافه کنید. این مدل‌ها بلافاصله در منوی کشویی Copilot Chat نمایش داده می‌شوند.

راه‌اندازی افزونه Continue

Continue یکی دیگر از دستیارهای محبوب کدنویسی هوش مصنوعی است که از APIهای سازگار با OpenAI پشتیبانی می‌کند:

1. نصب افزونه Continue: افزونه Continue را از فروشگاه افزونه‌های VSCode نصب کنید.

2. ورود به پیکربندی Continue: روی نماد تنظیمات (چرخ‌دنده) در نوار کناری Continue کلیک کنید.

3. افزودن ارائه‌دهنده AvalAI: فایل پیکربندی JSON را ویرایش کرده و مورد زیر را اضافه کنید:

   {
   "models": [
    {
      "title": "AvalAI Claude 4.5 Sonnet",
      "provider": "openai",
      "model": "claude-sonnet-4-5",
      "apiKey": "کلید_API_شما",
      "apiBase": "https://api.avalai.ir/v1"
   
    }
   ]
   }

4. جایگزینی کلید API: عبارت کلید_API_شما را با کلید واقعی API که از AvalAI دریافت کرده‌اید، جایگزین کنید.

راه‌اندازی سایر افزونه‌های سازگار با OpenAI

اکثر افزونه‌های هوش مصنوعی VSCode که از endpointهای سفارشی OpenAI پشتیبانی می‌کنند، به روش مشابهی پیکربندی می‌شوند:

1. یافتن بخش تنظیمات API: قسمت پیکربندی API یا تنظیمات ارائه‌دهنده افزونه را پیدا کنید.

2. انتخاب ارائه‌دهنده سازگار با OpenAI: گزینه "OpenAI" یا "OpenAI Compatible" را به عنوان نوع ارائه‌دهنده انتخاب کنید.

3. تنظیم پارامترهای اتصال:

   • Base URL/Endpoint: https://api.avalai.ir/v1
   • API Key: کلید API دریافتی از AvalAI
   • Model: هر یک از 410+ مدل موجود را انتخاب کنید

4. آزمایش اتصال: با ارسال یک درخواست آزمایشی، صحت عملکرد پیکربندی را بررسی کنید.

استفاده از پروفایل‌های Native Anthropic یا Gemini

نکته

برخی از افزونه‌های VSCode و ویرایشگرهای کد، علاوه بر حالت سازگار با OpenAI، از پروفایل‌های Native API برای Anthropic و Gemini نیز پشتیبانی می‌کنند. AvalAI به صورت بومی از هر دو پشتیبانی می‌کند!

اگر افزونه شما گزینه‌های پیکربندی بومی Anthropic یا Gemini را ارائه می‌دهد، می‌توانید با تنظیمات زیر از آن‌ها استفاده کنید:

برای پروفایل Native Anthropic:

• API Key: کلید API دریافتی از AvalAI
• Base URL: https://api.avalai.ir (⚠️ بدون /v1)
• مدل‌های در دسترس: فقط مدل‌های Claude (Claude 4 Opus، Claude 4.5 Sonnet، Claude 3.5 Sonnet و غیره)

برای پروفایل Native Gemini:

• API Key: کلید API دریافتی از AvalAI
• Base URL: https://api.avalai.ir (⚠️ بدون /v1)
• مدل‌های در دسترس: فقط مدل‌های Gemini (Gemini 3.1 Pro، Gemini 3 Flash، Gemini 2.5 Flash و غیره)

نکته مهم

هنگام استفاده از پروفایل‌های Native Anthropic یا Gemini، تنها به مدل‌های همان ارائه‌دهنده دسترسی خواهید داشت. برای دسترسی به تمامی 410+ مدل از ارائه‌دهندگان مختلف (OpenAI، Anthropic، Google، Meta، Mistral و سایرین)، از پیکربندی سازگار با OpenAI که در بالا توضیح داده شد با آدرس https://api.avalai.ir/v1 استفاده کنید.

پیکربندی محیط Cursor IDE

Cursor یک ویرایشگر کد محبوب مبتنی بر هوش مصنوعی است که بر پایه VSCode ساخته شده است. نحوه پیکربندی آن مشابه است:

1. ورود به تنظیمات Cursor: به مسیر Settings → Features → Models بروید

2. افزودن مدل سفارشی:

   • روی گزینه "Add Model" یا مشابه آن کلیک کنید
   • Provider: OpenAI را انتخاب کنید
   • Base URL: آدرس https://api.avalai.ir/v1 را وارد کنید
   • API Key: کلید API دریافتی از AvalAI را وارد کنید
   • Model Name: شناسه مدل مورد نظر را وارد کنید (مانند gpt-5.5 یا claude-opus-4-8)

3. ذخیره و آزمایش: پیکربندی را ذخیره کرده و با ارسال یک درخواست کدنویسی، عملکرد آن را آزمایش کنید.

راهنمای انتخاب مدل مناسب

AvalAI دسترسی به بیش از 410 مدل هوش مصنوعی را فراهم می‌کند. در اینجا برخی پیشنهادات برای وظایف مختلف کدنویسی آورده شده است:

برای تولید کد پیچیده و استدلال عمیق

• Claude Opus 4.8 (claude-opus-4-8) - بهترین انتخاب برای استدلال‌های پیچیده و کار با کدبیس‌های بزرگ
• GPT-5.5 (gpt-5.5) - گزینه‌ای عالی برای حل مسائل پیشرفته و چالش‌برانگیز
• Claude 4.6 Sonnet (claude-sonnet-4-6) - تعادل بی‌نظیر بین سرعت و کیفیت خروجی

برای کدنویسی سریع و کارآمد

• GPT-5.5 (gpt-5.5) - قدرتمند و قابل اطمینان برای کدنویسی روزمره و وظایف دشوار
• Gemini 2.5 Flash (gemini-2.5-flash) - پاسخ‌دهی فوری با کیفیت بالا
• Claude Sonnet 4.6 (claude-sonnet-4-6) - ایده‌آل برای توسعه سریع پروژه‌ها

برای توسعه اقتصادی و مقرون به صرفه

• DeepSeek V4 Flash (deepseek-v4-flash) - دارای سطح رایگان، تخصصی برای کدنویسی
• Qwen Coder (qwen-2.5-coder-32b-instruct) - کیفیت خوب با هزینه پایین
• Gemini 3.5 Flash (gemini-3.5-flash) - ترکیبی از سرعت، چندوجهی بودن و صرفه اقتصادی
• Kimi K2.7 Code (kimi-k2.7-code) - مدل کدنویسی متن‌باز قدرتمند برای گردش‌کارهای عاملی

برای وظایف تخصصی و پیشرفته

• DeepSeek V4 Pro (deepseek-v4-pro) - استثنایی برای کارهای ریاضی، الگوریتمی و استدلال منطقی
• Codestral (codestral-latest) - بهینه‌شده به طور خاص برای تکمیل خودکار کد

نکات و بهترین شیوه‌های استفاده

• امنیت کلید API: با کلید API خود مانند یک رمز عبور حساس برخورد کنید. هرگز آن را در سیستم کنترل نسخه (مثل Git) commit نکنید یا به صورت عمومی منتشر نکنید.
• استفاده از متغیرهای محیطی: برای امنیت بیشتر، کلید API را در متغیرهای محیطی یا یک مدیر اعتبارنامه امن ذخیره کنید.
• شروع با مدل متعادل: ابتدا با مدلی متعادل مانند Claude Sonnet 4.6، Gemini 3.5 Flash یا GPT-5.5 شروع کنید، سپس بر اساس نیازهای خاص پروژه، به مدل‌های دیگر مراجعه کنید.
• مدیریت دقیق زمینه (Context): برای دریافت نتایج بهتر، درخواست‌های واضح، مشخص و همراه با زمینه مناسب ارائه دهید.
• آگاهی از محدودیت‌های نرخ: از محدودیت‌های نرخ AvalAI مطلع باشید. اغلب وظایف کدنویسی در محدوده مجاز قرار می‌گیرند، اما در عملیات دسته‌ای و خودکار دقت بیشتری لازم است.
• پایش مصرف و هزینه: استفاده خود را از طریق داشبورد AvalAI پیگیری کنید تا بتوانید هزینه‌ها را کنترل و انتخاب مدل را بهینه کنید.
• ایجاد پروفایل‌های متعدد: برای پروژه‌ها یا موارد استفاده مختلف، پروفایل‌های پیکربندی جداگانه ایجاد کنید.
• آزمایش و تجربه: مدل‌های مختلف را برای وظایف مختلف امتحان کنید—برخی در اشکال‌زدایی و برخی دیگر در مستندسازی عملکرد بهتری دارند.

عیب‌یابی مشکلات رایج

• خطای کلید API نامعتبر:

  • دوباره بررسی کنید که کلید را به درستی از داشبورد AvalAI کپی کرده‌اید
  • مطمئن شوید که فاصله یا کاراکتر اضافی در ابتدا یا انتهای کلید وجود ندارد
  • تایید کنید که کلید هنوز در داشبورد AvalAI شما فعال و معتبر است

• مشکلات اتصال به سرور:

  • کیفیت و وضعیت اتصال اینترنت خود را بررسی کنید
  • بررسی کنید که آیا فایروال یا پروکسی شبکه دسترسی به https://api.avalai.ir را مسدود کرده است
  • مطمئن شوید که URL پایه دقیقا https://api.avalai.ir/v1 است (حتما شامل /v1 در انتها باشد)

• خطای یافت نشدن مدل:

  • صحت شناسه مدل را با مراجعه به مستندات AvalAI تایید کنید
  • اطمینان حاصل کنید که مدل مورد نظر در سطح اشتراک شما در دسترس است
  • برای آزمایش، از مدل‌های متداول مانند gpt-5.5 یا claude-opus-4-8 استفاده کنید

• کندی پاسخ‌دهی:

  • به مدل سریع‌تری مانند Gemini 3.5 Flash یا gpt-5.4-mini مهاجرت کنید
  • کیفیت و سرعت اتصال شبکه خود را بررسی کنید
  • حجم زمینه (context) ارسالی در درخواست‌های خود را کاهش دهید

• خطاهای محدودیت نرخ درخواست:

  • محدودیت‌های نرخ مربوط به سطح اشتراک خود را مطالعه کنید
  • قبل از تلاش مجدد، چند لحظه صبر کنید
  • برای دسترسی به محدودیت‌های بالاتر، ارتقای سطح اشتراک را در نظر بگیرید

• افزونه پیکربندی را تشخیص نمی‌دهد:

  • پس از تغییر تنظیمات، VSCode را مجددا راه‌اندازی کنید
  • مستندات افزونه را برای اطمینان از صحت قالب پیکربندی بررسی کنید
  • تایید کنید که افزونه از قابلیت تنظیم endpointهای سفارشی OpenAI پشتیبانی می‌کند

پیکربندی‌های پیشرفته

استفاده همزمان از چند مدل

برای انعطاف‌پذیری بیشتر، می‌توانید پروفایل‌های متعدد برای مدل‌های مختلف تعریف کنید:

{
  "models": [
    {
      "title": "کدنویسی سریع - GPT-5.5",
      "model": "gpt-5.5",
      "apiBase": "https://api.avalai.ir/v1",

      "apiKey": "کلید_API_شما"
    },
    {
      "title": "استدلال عمیق - Claude 4 Opus",
      "model": "anthropic.claude-opus-4-20250514-v1:0",
      "apiBase": "https://api.avalai.ir/v1",

      "apiKey": "کلید_API_شما"
    },
    {
      "title": "اقتصادی - Gemini Flash",
      "model": "gemini-2.5-flash",
      "apiBase": "https://api.avalai.ir/v1",

      "apiKey": "کلید_API_شما"
    }
  ]
}

افزودن هدرهای سفارشی (در صورت پشتیبانی)

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

جمع‌بندی

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

چه از GitHub Copilot، Continue، Cursor یا هر افزونه سازگار با OpenAI دیگری استفاده کنید، فرآیند پیکربندی مشابه است و تنها چند دقیقه زمان می‌برد. با آزمایش مدل‌های مختلف، بهترین گزینه را برای نیازهای توسعه خود پیدا کنید!

منابع مرتبط

• مرجع API AvalAI: معرفی
• مرور کلی مدل‌های AvalAI
• راهنمای محدودیت‌های نرخ
• بهترین شیوه‌ها برای دستیارهای کدنویسی هوش مصنوعی
• راهنمای انتخاب مدل