اتصال Aider به AvalAI

Aider ابزار برنامه‌نویسی دونفره در پایانه است که می‌تواند درباره فایل‌های انتخابی گفتگو کند و آن‌ها را ویرایش کند. آن را با ارائه‌دهنده سازگار با OpenAI مستقیماً به AvalAI متصل کنید. ابتدا در حالت پرسش، بدون ثبت خودکار تغییرات در Git و بدون نقشه مخزن شروع کنید؛ زمان ویرایش را خودتان مشخص کنید.

منابع در ۱۴۰۵-۰۶-۱۷ / (2026-09-08) با مستندات رسمی مسیر API و فرمان‌های Aider بررسی شده‌اند. نشست زنده Aider با AvalAI اجرا نشده است.

۱. نصب Aider

نصب‌کننده رسمی محیط Python جداگانه‌ای برای Aider می‌سازد. راهنمای نصب و الزامات نسخه Python و سیستم‌عامل آن را دنبال کنید:

python3 -m pip install aider-install
aider-install
aider --version

نسخه نصب‌شده را برای استفاده تیمی ثبت کنید. نشست اول را در پروژه آزمایشی با یک README.md بی‌خطر اجرا کنید، نه مخزن شرکت که اسرار دارد.

۲. نگهداری خصوصی نشانی و کلید

یک پوشه پیکربندی خصوصی بسازید:

mkdir -p "$HOME/.config/aider"

با ویرایشگر خود فایل ~/.config/aider/avalai.env را با محتوای زیر بسازید. فقط مقدار نمونه کلید را با کلید اختصاصی AvalAI جایگزین کنید. فایل را در Git ثبت نکنید و کلید واقعی را در فرمان پوسته نچسبانید.

OPENAI_API_BASE=https://api.avalai.ir/v1
OPENAI_API_KEY=replace-with-your-avalai-key

chmod 600 "$HOME/.config/aider/avalai.env"

نام متغیر مستند Aider، OPENAI_API_BASE است، نه OPENAI_BASE_URL. اگر پوسته شما OPENAI_API_BASE یا OPENAI_API_KEY را برای سرویس دیگری تعریف کرده است، پیش از استفاده از فایل، آن‌ها را در همین نشست از محیط حذف کنید؛ ترتیب تقدم اعتبارنامه‌ها را حدس نزنید.

۳. شروع نشست فقط برای گفتگو

در پوشه پروژه آزمایشی اجرا کنید:

aider --env-file "$HOME/.config/aider/avalai.env" \
  --model openai/gpt-5.4-mini \
  --weak-model openai/gpt-5.4-mini \
  --chat-mode ask --map-tokens 0 \
  --no-auto-commits --no-dirty-commits README.md

این تفاوت‌ها مهم‌اند:

• پیشوند openai/ سازگارکننده OpenAI در Aider/LiteLLM را انتخاب می‌کند. شناسه مدل AvalAI، gpt-5.4-mini است؛ پیشوند Aider را مستقیماً به AvalAI نفرستید.
• مدل اصلی و کمکی مشخص‌اند. حالت‌های دیگر، مانند معماری و ویرایش، ممکن است مدل دیگری داشته باشند؛ آن‌ها را جدا تنظیم کنید.
• گزینه --chat-mode ask برای گفتگو بدون ویرایش خودکار است؛ محیط ایزوله فایل یا شبکه نیست.
• گزینه --map-tokens 0 نقشه مخزن را در این آزمون محدود اولیه غیرفعال می‌کند.
• گزینه‌های --no-auto-commits --no-dirty-commits جلوی ثبت خودکار تغییرات تولیدشده یا ازپیش‌موجود در Git را می‌گیرند.

فهرست جاری AvalAI این مدل را برای Chat Completions ثبت کرده است. سازگاری Aider به فراداده مدل و قالب ویرایش نیز وابسته است؛ پذیرفته‌شدن درخواست HTTP به‌تنهایی کیفیت ویرایش را ثابت نمی‌کند.

۴. بررسی نخستین درخواست

این درخواست را بفرستید:

Summarize the purpose of README.md in one sentence.
Do not edit files, run commands, or suggest installing anything.

بررسی کنید پاسخ با فایل مطابقت دارد و کد منبع تغییر نکرده است. در پروژه Git این موارد را ببینید:

git status --short
git diff

Aider حتی در گردش‌کار گفتگویی ممکن است فایل پیکربندی یا تاریخچه محلی بسازد. از فایل‌های .aider* محافظت کنید و تاریخچه خصوصی را در Git ثبت نکنید. پیش از اعتماد به مخزن، فایل .aider.conf.yml و دستورهای پروژه را بررسی کنید؛ گزینه‌های خط فرمان مرز امنیتی کامل نیستند.

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

عیب‌یابی

نشانه	بررسی بعدی
درخواست به سرویس دیگری می‌رود	OPENAI_API_BASE، متغیرهای به‌ارث‌رسیده از پوسته و فایل محیط انتخابی را بررسی کنید.
401 / 403	کلید اختصاصی، دسترسی حساب و فاصله اضافی را بررسی کنید؛ فایل محیط را در گزارش عیب‌یابی نمایش ندهید.
مدل پیدا نمی‌شود	در Aider از openai/gpt-5.4-mini استفاده کنید؛ پس از پیشوند، شناسه دقیق AvalAI قرار می‌گیرد.
هشدار ظرفیت یا هزینه نامشخص	هشدارهای مدل را بخوانید؛ هشدار را پنهان نکنید و فراداده نسازید. فهرست و قیمت AvalAI را بررسی کنید.
چت درست است اما ویرایش نه	قالب ویرایش و توان مدل با سازگاری API تفاوت دارند. یک فایل کوچک را امتحان و تفاوت پیشنهادی را بررسی کنید.
مصرف زیاد	تعداد فایل‌ها و تاریخچه را کم کنید؛ نقشه مخزن را ابتدا خاموش نگه دارید. مصرف AvalAI را ببینید، نه فقط برآورد قیمت محلی.
قابلیت صوتی یا تصویری کار نمی‌کند	این‌ها مسیرهای جداگانه‌اند. نشانی چت، تبدیل گفتار به متن یا تولید رسانه را تنظیم نمی‌کند.

منابع رسمی و گام بعد

• مخزن Aider.
• APIهای سازگار با OpenAI، نصب و گزینه‌های خط فرمان.
• فهرست مدل‌ها، قیمت‌ها، محدودیت نرخ و تمرین عامل برنامه‌نویسی.

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