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

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

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

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

تولید کد

از مدل‌های AvalAI برای نوشتن، بازبینی، refactor و debug کد با APIهای سازگار با OpenAI استفاده کنید.

راهنمای رسمی code generation در OpenAI، Responses API را برای workflowهای کدنویسی مبتنی بر API و Codex را برای مهندسی نرم‌افزار agentic پیشنهاد می‌کند. در AvalAI همین الگو را با AVALAI_API_KEY و https://api.avalai.ir/v1 به کار ببرید: برای workflowهای جدید از /v1/responses شروع کنید، برای ادغام‌های موجود Chat Completions را نگه دارید، و وقتی agent در ترمینال یا editor می‌خواهید از راه‌اندازی Codex استفاده کنید.

انتخاب Workflow کدنویسی

Workflow	مسیر پیشنهادی	نکته
تولید کد یا debug یک‌مرحله‌ای	`/v1/responses`	از `instructions`، ورودی کوتاه و `response.output_text` استفاده کنید.
دستیار کدنویسی chat-based موجود	`/v1/chat/completions`	اگر app پایدار است نگه دارید؛ وقتی به آیتم‌های Responses، reasoning یا ابزارها نیاز دارید، flow به flow مهاجرت کنید.
ویرایش repo، تست و review	Codex با AvalAI به‌عنوان provider	راه‌اندازی Codex را ببینید.
refactorهای بزرگ	Responses همراه retrieval/tool loop خودتان	فقط فایل‌های مرتبط را بفرستید؛ وقتی ابزار یا reasoning دارید آیتم‌های `response.output` را حفظ کنید.

عامل‌های آگاه از Skill و ابزار Apply Patch

OpenAI ابزار apply_patch را در Responses/Agents SDK مستند کرده است که برای ساخت، به‌روزرسانی و حذف فایل، آیتم‌های ساختاریافته apply_patch_call برمی‌گرداند. برنامه شما این عملیات را اعمال می‌کند؛ مدل مستقیماً فایل‌های شما را نمی‌نویسد. پروتکل داخلی apply_patch هنوز در AvalAI پشتیبانی نمی‌شود، مگر آنکه مسیر انتخاب‌شده پشتیبانی از tools: [{"type": "apply_patch"}] را صریحاً تأیید کند. مستندات OpenAI به‌تنهایی دسترس‌پذیری آن را در AvalAI ثابت نمی‌کند. برای مسیر مستقل از ارائه‌دهنده، از مدل یک وصله استاندارد در قالب unified diff بخواهید و آن را در فرایند بازبینی خود، نشست Codex یا سامانه اعمال وصله در برنامه خود اجرا کنید.

هنگام ساخت سامانه اعمال وصله، مدل فقط پیشنهاد تغییر بدهد و اجرای ضوابط بر عهده برنامه شما باشد:

مسیرها را به محدوده مجاز محدود کنید و مسیرهایی را که از آن خارج می‌شوند، رد کنید؛
در صورت امکان، وصله‌ها را در یک نسخه آزمایشی یا تراکنش اعمال کنید؛
هنگام استفاده از پروتکل ابزار پشتیبانی‌شده، برای هر call_id دقیقاً یک apply_patch_call_output با status: "completed" یا status: "failed" و توضیح کوتاه خطا بازگردانید؛
پس از هر دور ویرایش، آزمون‌ها، بررسی‌های کد یا git diff --check را اجرا کنید و خطاها را به‌عنوان ورودی عادی به مدل بدهید؛
برای حذف فایل، تغییر وابستگی‌ها، فایل‌های باینری تولیدشده، مهاجرت یا بازنویسی گسترده، تأیید انسانی بگیرید.

حفظ فایل‌ها هنگام جابه‌جایی با وصله

ممکن است در پیشنهاد جابه‌جایی، مبدأ و مقصد یکسان باشند؛ برای نمونه src/app.py → src/app.py. این حالت را به‌روزرسانی همان فایل بدانید: محتوای جدید را یک بار بنویسید و مبدأ را حذف نکنید. نوشتن در مقصد و سپس حذف مبدأ، فایل به‌روزشده را از بین می‌برد، چون هر دو مسیر به همان فایل اشاره می‌کنند.

ابزار اعمال وصله در OpenAI Cookbook اکنون پیش از اجرای شاخه جابه‌جایی و حذف، شرط change.move_path != path را بررسی می‌کند. این اصلاح، رشته‌های مسیر یکسان را در نمونه پوشش می‌دهد؛ برنامه شما باید نام‌های جایگزین یا پیوندهای نمادین را نیز که باعث می‌شوند دو رشته متفاوت به یک فایل اشاره کنند، رد کند. پیش از هر نوشتن یا حذف، بررسی کنید که مسیرهای نهایی در محدوده مجاز قرار دارند.

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

Skillهای OpenAI مجموعه‌های نسخه‌داری با فایل راهنما به نام SKILL.md هستند که می‌توانند عامل‌های خط فرمان یا کدنویسی را هدایت کنند. Skillهای میزبانی‌شده هنوز در AvalAI پشتیبانی نمی‌شوند، مگر آنکه مسیر انتخاب‌شده پشتیبانی را صریحاً تأیید کند. همان دانش را در مستندات مخزن، الگوهای پرامپت، توضیح ابزارها یا فایل‌های اجرایی محلی نگه دارید. Skillها را مانند دستورها و کد دارای دسترسی ویژه بازبینی کنید، آن‌ها را به فرایندهای مشخص محصول محدود کنید و اجازه ندهید کاربران نهایی هر Skill دلخواهی را از یک فهرست باز به برنامه بیفزایند.

قالب Brief برای Task کدنویسی

مثال‌های code generation در OpenAI فراخوانی مدل را ساده نگه می‌دارند: ورودی task، instructions اختیاری در سطح سیستم، و مدل کدنویسی با reasoning effort بالاتر. برای appهای AvalAI، این ورودی را به یک brief کوتاه و تکرارپذیر تبدیل کنید:

هدف: یک جمله درباره تغییر، bug یا سوال review.
فایل‌های مجاز: مسیر دقیق فایل‌هایی که مدل می‌تواند inspect یا edit کند.
زمینه: فقط source مرتبط، excerpt مستندات، stack trace یا contract API.
محدودیت‌ها: non-goalهایی مثل «public API را تغییر نده»، «dependency جدید اضافه نکن» یا «متن RTL را سالم نگه دار».
خروجی مورد انتظار: diagnosis، unified diff، فایل جایگزین، test plan یا review note.
راستی‌آزمایی: commandی که انسان یا agent بعد از اعمال patch باید اجرا کند.

نمونه ورودی برای /v1/responses:

text

Goal: Fix the empty-state bug in the billing table.
Allowed files: src/components/BillingTable.tsx, tests/BillingTable.test.tsx
Context: The table renders nothing when invoices=[]; expected copy is "No invoices yet".
Constraints: Keep existing props and CSS classes. Do not add dependencies.
Expected output: Short diagnosis, minimal unified diff, and targeted test command.
Verification: npm test -- BillingTable.test.tsx

این brief را به‌عنوان input استفاده کنید و رفتار پایدار را در instructions نگه دارید. اگر مدل tool call، reasoning item یا چند آیتم خروجی برگرداند، response.output را بخوانید؛ از response.output_text فقط برای متن نهایی قابل‌خواندن توسط انسان استفاده کنید.

انتخاب مدل

مدلی را انتخاب کنید که با پیچیدگی کار هماهنگ باشد:

gpt-5.5: انتخاب پیش‌فرض قوی برای کدنویسی همراه استدلال عمومی.
gpt-5.3-codex: بهینه‌شده برای workflowهای agentic coding به سبک Codex.
claude-opus-4-8: مناسب برای codebaseهای بزرگ و استدلال long-context.
kimi-k2.7-code: جایگزین coding-focused قوی وقتی تنوع provider می‌خواهید.

پیش از production، جزئیات مدل‌ها و صفحه ارائه‌دهنده‌ها را بررسی کنید؛ availability، طول context و پشتیبانی route می‌تواند متفاوت باشد.

توسعه Frontend و Agentهای متکی بر مستندات

راهنمای code generation در OpenAI تأکید می‌کند مدل‌های جدید GPT وقتی داخل یک agent harness اجرا شوند، برای توسعه frontend بسیار قوی هستند. در AvalAI، تولید UI را با یک brief محدود و دقیق ایمن‌تر کنید، نه با درخواست مبهم:

framework، package manager، component library و فایل‌هایی را که اجازه تغییر دارند مشخص کنید؛
screenshot، tokenهای CSS، الزامات accessibility و breakpointهای responsive را اضافه کنید؛
از مدل یک مسیر پیاده‌سازی بخواهید، سپس app را اجرا کنید و با هدف بصری مقایسه کنید؛
متن قابل مشاهده برای کاربر، theme tokenها و نیازهای RTL/LTR را برای محصولات دوزبانه صریح بنویسید.

برای دستیارهای کدنویسی متکی بر docs، به حافظه مدل برای جزئیات API اعتماد نکنید. ابتدا صفحه مستندات، changelog یا convention داخلی مرتبط را retrieve کنید، سپس فقط excerptهای لازم را به /v1/responses بدهید. از مدل بخواهید excerpt استفاده‌شده را cite کند و رفتار API نامطمئن را به‌عنوان assumption علامت بزند. این نسخه قابل‌حمل AvalAI از الگوی docs-agent در OpenAI است.

مثال Responses

PythonJavaScriptBash

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=os.getenv("AVALAI_MODEL", "gpt-5.6-luna"),
    instructions=(
        "You are a senior software engineer. Return a concise diagnosis, "
        "then a minimal patch suggestion. Do not invent files."
    ),
    input="Find the likely null pointer bug in this code:\\n\\n...paste code here...",
    reasoning={"effort": "high"},
)

print(response.output_text)

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: process.env.AVALAI_MODEL ?? "gpt-5.6-luna",
  instructions:
    "You are a senior software engineer. Return a concise diagnosis, then a minimal patch suggestion. Do not invent files.",
  input: "Find the likely null pointer bug in this code:\\n\\n...paste code here...",
  reasoning: { effort: "high" },
});

console.log(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.6-luna",
    "instructions": "You are a senior software engineer. Return a concise diagnosis, then a minimal patch suggestion. Do not invent files.",
    "input": "Find the likely null pointer bug in this code:\n\n...paste code here...",
    "reasoning": { "effort": "high" }
  }'

جایگزین Chat Completions

وقتی دستیار کدنویسی موجود هنوز بر Chat Completions ساخته شده یا مدل انتخابی فقط chat compatibility دارد، از این شکل استفاده کنید.

PythonJavaScriptBash

python

import os
from openai import OpenAI

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

completion = client.chat.completions.create(
    model=os.getenv("AVALAI_MODEL", "gpt-5.6-luna"),
    messages=[
        {"role": "system", "content": "You are a senior software engineer."},
        {
            "role": "user",
            "content": "Refactor this function for readability:\\n\\n...code...",
        },
    ],
)

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

javascript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

const completion = await client.chat.completions.create({
  model: process.env.AVALAI_MODEL ?? "gpt-5.6-luna",
  messages: [
    { role: "system", content: "You are a senior software engineer." },
    { role: "user", content: "Refactor this function for readability:\\n\\n...code..." },
  ],
});

console.log(completion.choices[0].message.content);

bash

curl https://api.avalai.ir/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
    "model": "gpt-5.6-luna",
    "messages": [
      {"role": "system", "content": "You are a senior software engineer."},
      {"role": "user", "content": "Refactor this function for readability:\n\n...code..."}
    ]
  }'

چک‌لیست Prompting

زبان، framework، نسخه runtime و فایل‌هایی را که اجازه تغییر دارند مشخص کنید.
از مدل یک patch حداقلی یا فایل کامل جایگزین بخواهید، نه هر دو.
خروجی تست ناموفق، stack trace و پیام خطای دقیق را اضافه کنید.
برای repoهای بزرگ، فقط فایل‌های مرتبط را retrieve کنید و از مدل بخواهید قبل از تغییر کد assumptionها را فهرست کند.
برای refactor، non-goalها را مشخص کنید؛ مثل «public API را تغییر نده» یا «schema دیتابیس را تغییر نده».
برای کد تولیدشده، قبل از release تست و linter را اجرا کنید؛ خروجی مدل را draft بدانید.

Workflow بازبینی، Diff و امنیت

برای کار روی repository، از مدل بخواهید خروجی را در شکلی قابل review تولید کند:

وقتی task چند فایل را لمس می‌کند، پیش از کد یک plan کوتاه بخواهید.
برای بازبینی patch، unified diff یا فایل‌های جایگزین با نام روشن را ترجیح دهید.
از مدل بخواهید تغییرهای public API، گام‌های migration و پوشش test را توضیح دهد.
ابتدا testهای هدفمند را اجرا کنید، سپس وقتی patch پایدار شد testها یا linterهای گسترده‌تر را اجرا کنید.
کد تولیدشده را untrusted بدانید: dependencyهای جدید، shell commandها، مسیر فایل‌ها، SQL، regex، منطق authentication و network callها را پیش از اجرا review کنید.
برای کد security-sensitive، یک threat-model pass بخواهید و مدل را ملزم کنید assumptionها، input validation، authorization checkها و مرزهای secrets-handling را مشخص کند.

نکات مهاجرت

messages → input همراه instructions اختیاری در سطح بالا.
choices[0].message.content → response.output_text.
برای agentهای کدنویسی tool-using، response.output را بررسی کنید و آیتم‌های typed مثل reasoning، function_call و function_call_output را حفظ کنید.
برای ویرایش فایل‌هایی که خروجی آن‌ها تا حد زیادی معلوم است، اگر باید روی Chat Completions بمانید خروجی‌های پیش‌بینی‌شده را ببینید.

تولید کد ​

انتخاب Workflow کدنویسی ​

عامل‌های آگاه از Skill و ابزار Apply Patch ​

حفظ فایل‌ها هنگام جابه‌جایی با وصله ​

قالب Brief برای Task کدنویسی ​

انتخاب مدل ​

توسعه Frontend و Agentهای متکی بر مستندات ​

مثال Responses ​

جایگزین Chat Completions ​

چک‌لیست Prompting ​

Workflow بازبینی، Diff و امنیت ​

نکات مهاجرت ​

راهنماهای مرتبط ​