کلید را به محیط فرایند بدهید
در Bash می‌توانید کلید را بدون نوشتن مقدار آن در متن فرمان دریافت کنید. مقدار ورودی هنگام تایپ نمایش داده نمی‌شود و در همان محیط فرایند قابل استفاده است. متغیر را چاپ نکنید و فایل تاریخچه یا تنظیمات حاوی کلید نسازید. اگر از ابزار مدیریت کلید سازمان استفاده می‌کنید، روش مورد تأیید همان محیط را به کار ببرید.
read -rs -p "Paasta API key: " PAASTA_API_KEY
export PAASTA_API_KEY
در PowerShell، دریافت محرمانه را میتوان با Read-Host انجام داد و مقدار را فقط برای فرایندهای همین نشست در محیط قرار داد. رشته محیطی در زمان اجرا همچنان قابل دسترسی برای همان فرایند است؛ این روش، Sandbox یا جداسازی از کد دارای مجوز همان کاربر ایجاد نمی‌کند. پیش از اجرای افزونه ناشناس، همین دسترسی را در نظر بگیرید.
$piApiKeyInput = Read-Host "Paasta API key" -AsSecureString
$env:PAASTA_API_KEY = [System.Net.NetworkCredential]::new("", $piApiKeyInput).Password
ارائهدهنده Paasta را در models.json تعریف کنید
طبق مستندات پیکربندی Pi، پوشه پیشفرض تنظیم کاربر ~/.pi/agent است و models.json در آن قرار میگیرد؛ محل آن میتواند با تنظیم محیطی تغییر کند. در Windows، مسیر پیشفرض زیر پوشه کاربر و سپس .pi\agent است. اگر فایل از قبل وجود دارد، نمونه را با بخش providers ادغام کنید و تنظیم سایر اتصالها را نگه دارید.
فایل نمونه پیکربندی Pi برای پاستا را می‌توانید دانلود کنید. شناسه MODEL_ID_FROM_PAASTA را پیش از استفاده جایگزین کنید. ارجاع محیطی با علامت دلار مطابق قرارداد فعلی Pi است؛ قراردادن صرف نام متغیر بدون این شکل، ممکن است همان متن را بهعنوان کلید تلقی کند. کلید واقعی در فایل نمونه قرار نمی‌گیرد.
{
"$schema": "https://pi.dev/schemas/models.schema.json",
"providers": {
"paasta": {
"name": "Paasta",
"baseUrl": "https://console.paasta.cloud/api/ai/v1",
"api": "openai-completions",
"apiKey": "$PAASTA_API_KEY",
"authHeader": true,
"models": [
{
"id": "MODEL_ID_FROM_PAASTA",
"name": "Paasta coding model",
"input": ["text"]
}
]
}
}
}
نوع openai-completions در این تنظیم نام adapter مربوط به Chat Completions در Pi است. برای این مسیر، baseUrl پایه را بگذارید و عبارت chat/completions را به انتهای آن اضافه نکنید. جزئیات فیلدها در مرجع مدل‌های Pi آمدهاند. تغییر تصادفی چند گزینه compat برای رفع خطا، تشخیص علت واقعی را سخت میکند؛ فقط تفاوت مستند یا مشاهدهشده را تنظیم کنید.
اول اتصال، سپس اولین کار روی پروژه
در یک پوشه کاری مشخص Pi را اجرا کنید و با فرمان /model مدل تعریفشده را انتخاب کنید. راهنمای انتخاب مدل میگوید این انتخاب، فایل مدلها را نیز دوباره میخواند. اگر مدل دیده نمی‌شود، قبل از بررسی توانایی کدنویسی، JSON، شناسه ارائهدهنده و در دسترس بودن متغیر محیطی را بررسی کنید.
برای اولین پیام، یک پاسخ کوتاه و بدون نیاز به تغییر فایل بخواهید. پس از آن، یک کار محدود روی پروژه آزمایشی بدهید: مثلاً پیدا کردن یک تابع، توضیح رفتار آن و پیشنهاد یک تست مرزی. این مرحله مشخص میکند خواندن فایل و قرارداد پاسخ چگونه عمل میکنند. اجرای مستقیم یک کار چندساعته، خطای ساده اتصال را با مشکلات زمینه و ابزار درهم میآمیزد.
AGENTS.md را برای نتیجه قابل سنجش بنویسید
در فایل راهنمای پروژه، مسیرهای مهم، فرمان تست و محدودیت تغییر را ثبت کنید. دستور کوتاه و دقیق از یک متن طولانی با توصیههای کلی مفیدتر است. برای مثال، بگویید تست مرتبط با ماژول کجاست و خروجی قابل قبول چه چیزی است. اگر پروژه تغییرات ثبتنشده دارد، ایجنت باید همان تغییرها را در تصمیم خود حفظ کند.
Project instructions:
- Read the relevant module and its existing tests before editing.
- Preserve unrelated changes.
- Make the requested fix and run the focused test.
- Report the changed files and the observed test result.
- Do not publish, deploy, or modify credentials for this task.
این متن قرارداد رفتاری است و مجوز سیستم را محدود نمی‌کند. Pi با اختیار فرایند خودش کار میکند. اگر باید دسترسی فایل یا شبکه واقعاً محدود شود، راهنمای Sandbox ایجنت و کانتینر را دنبال کنید. مخزن ناشناس، اسکریپت نصب و بسته افزونه هرکدام میتوانند سطح دسترسی تازهای وارد محیط کنند.
یک تغییر کوچک را از ابتدا تا پذیرش دنبال کنید
کاری انتخاب کنید که بتوان نتیجه آن را با یک تست یا بررسی مشخص سنجید. شرح مناسب شامل نشانه فعلی، رفتار مورد انتظار و محدوده تغییر است. مثلاً «این تابع برای آرایه خالی خطا میدهد؛ نتیجه باید صفر باشد و رفتار ورودیهای معتبر تغییر نکند». پیش از اجرا، نتیجه فعلی را ثبت کنید تا بعداً صرف ادعای ایجنت را موفقیت ندانید.
پس از تغییر، diff را بخوانید، تست مرتبط را اجرا کنید و وضعیت فایلهای دیگر را بررسی کنید. نتیجه تست باید از خروجی واقعی بیاید. اگر ایجنت فقط فرمانی پیشنهاد داده، آن را تست انجامشده محسوب نکنید. برای تست گسترده یا ساخت پروژه، ظرفیت محیط و مدت اجرا را در نظر بگیرید و تغییر کوچک را با اصلاحات نامرتبط مخلوط نکنید.
نشست و هزینه را با دامنه کار هماهنگ کنید
گفت‌وگوی طولانی، خروجی فرمانهای حجیم و فایلهای نامرتبط، زمینه مورد استفاده مدل را بزرگ میکنند. فقط آنچه برای کار لازم است وارد زمینه کنید. پس از پایان یک مسئله، برای کار مستقل بعدی محدوده تازهای تعریف کنید. خلاصهسازی نشست میتواند بخشی از مدیریت زمینه باشد، اما جای ثبت تصمیم و نتیجه در خود پروژه را نمی‌گیرد.
گزارش هزینه ابزار ممکن است با صورتحساب ارائهدهنده تفاوت داشته باشد، بهویژه اگر metadata قیمت سفارشی کامل نباشد. برای مصرف API پاستا، گزارش واقعی همان کلید را معیار قرار دهید. در راهنمای هزینه و ارزیابی ایجنت، هزینه هر کار پذیرفتهشده بهجای مقایسه صرف قیمت توکن توضیح داده شده است.
خطاهای رایج اتصال را چطور بررسی کنیم؟
خطای احراز هویت را با بررسی متغیر، وضعیت کلید و دسترسی مدل پیگیری کنید؛ مقدار کلید را در گزارش نیاورید. برای شناسه نامعتبر، مقدار کامل را با کاتالوگ تطبیق دهید. اگر درخواست متنی موفق است ولی استفاده از ابزار خطا دارد، قرارداد tool calling همان مدل را جدا بررسی کنید. هر مدل مناسب پاسخگویی، الزاماً برای ایجنت کدنویسی انتخاب خوبی نیست.
اگر پاسخ ناقص میرسد، ابتدا مشخص کنید مشکل از اتصال، adapter یا مدل است. راهنمای عیب‌یابی پاسخ جریانی AI برای فهم تفکیک لایههای استریم نیز مفید است. Retry پیدرپی بدون شناخت علت، میتواند هزینه تازه ایجاد کند. ورودی کوتاه و تنظیم ثابت، تشخیص را سادهتر میکنند.
استفاده مناسب Pi در جریان توسعه با پاستا
اگر بین دو مدل مردد هستید، یک وظیفه و وضعیت شروع یکسان انتخاب کنید و تغییر پذیرفتهشده را معیار بگیرید. تعداد تلاش، مدت رسیدگی و نیاز به اصلاح دستی را کنار مصرف واقعی ثبت کنید. برای این مقایسه، نتیجهای که تست را رد میکند صرفاً به دلیل پاسخ سریعتر برنده نیست. همچنین موفقیت روی یک تابع کوچک، بهمعنی برتری عمومی روی همه پروژهها نیست.
نشست حاوی کد خصوصی یا خروجی فرمان را پیش از اشتراک بازبینی کنید. حذف کلید از models.json کافی نیست اگر قبلاً در لاگ یا متن گفتوگو چاپ شده باشد. برای دریافت کمک، خطا، نسخه و بخش لازم از تنظیم را با مقدارهای نمونه ارائه کنید. لازم نیست تاریخچه کامل پروژه یا اعتبارنامه را برای تشخیص یک اشتباه در نام مدل منتشر کنید.
Pi میتواند ابزار توسعه محلی یا یک محیط کاری کنترلشده باشد و API پاستا مدل آن را تأمین کند. پس از پذیرش تغییر کد، استقرار برنامه مرحله مستقلی دارد. برای پروژه Next.js، امکانات هاست Next.js پاستا را بررسی کنید. نتیجه یک نشست ایجنت را پیش از تست و بازبینی، آماده انتشار فرض نکنید.
نقطه شروع خوب، یک کلید محدود، مدل مشخص و کاری با نتیجه قابل مشاهده است. وقتی کیفیت تغییر و هزینه همان کار روشن شد، استفاده را گسترش دهید. این مقاله ساختار اتصال مطابق مستندات و روش پذیرش را ارائه میکند؛ بنچمارک استنتاج زنده Pi با مدل‌های پاستا یا برتری یک مدل برای همه پروژهها را ادعا نمی‌کند.
