مدل GLM-5.2 یکی از مدل‌های هوش مصنوعی جدید و قدرتمند خانواده GLM است که تمرکز ویژه‌ای بر برنامه‌نویسی، استدلال چندمرحله‌ای، کار با ابزارها و اجرای وظایف طولانی دارد. این مدل برای پاسخ‌دادن به یک سؤال ساده ساخته نشده است؛ مهم‌ترین مزیت آن زمانی آشکار می‌شود که باید یک پروژه پیچیده را بررسی کند، برای انجام آن برنامه بریزد، چند ابزار را فراخوانی کند، کد تولیدشده را اصلاح کند و تا رسیدن به نتیجه به کار ادامه دهد.

GLM-5.2 از یک Context Window بسیار بزرگ پشتیبانی می‌کند و می‌تواند حجم قابل‌توجهی از کد، مستندات، تاریخچه مکالمه و خروجی ابزارها را در یک فرایند پردازش کند. چنین قابلیتی آن را به گزینه‌ای جدی برای ساخت Coding Agent، دستیار برنامه‌نویسی سازمانی، سیستم تحلیل مخزن کد و Agentهای دارای وظایف چندمرحله‌ای تبدیل می‌کند.

توسعه‌دهندگان ایرانی می‌توانند از طریق API درواره به این مدل متصل شوند و آن را با ساختاری سازگار با OpenAI API در پروژه‌های Python، JavaScript، TypeScript، PHP و سایر زبان‌ها به کار بگیرند.

برای مشاهده وضعیت ارائه مدل و قیمت به‌روز آن، به صفحه مدل‌های درواره مراجعه کنید.

GLM-5.2 چه نوع مدلی است؟

GLM-5.2 را می‌توان هم‌زمان در چند دسته قرار داد:

• مدل زبانی بزرگ یا Large Language Model
• مدل استدلالی یا Reasoning Model
• مدل تخصصی برنامه‌نویسی
• مدل مناسب Coding Agent
• مدل مناسب Tool Calling و Function Calling
• مدل مناسب وظایف Long-Horizon
• مدل مناسب تحلیل Contextهای بسیار طولانی
• مدل مناسب اتوماسیون چندمرحله‌ای

تفاوت GLM-5.2 با بسیاری از چت‌بات‌های معمولی در مفهوم Long-Horizon Task است. وظیفه Long-Horizon کاری است که با یک پاسخ کوتاه تمام نمی‌شود و مدل باید در چند مرحله روی آن کار کند.

برای مثال، ساخت یک قابلیت جدید در پروژه ممکن است شامل این مراحل باشد:

1. بررسی ساختار Repository
2. پیداکردن فایل‌های مرتبط
3. درک معماری و قراردادهای پروژه
4. طراحی راه‌حل
5. ویرایش چند فایل
6. اجرای تست‌ها
7. بررسی خطاها
8. اصلاح پیاده‌سازی
9. اجرای دوباره تست‌ها
10. ارائه گزارش تغییرات

مدلی که فقط در تولید قطعه‌کد خوب باشد، لزوماً نمی‌تواند این چرخه را با کیفیت مناسب اجرا کند. GLM-5.2 مشخصاً برای حفظ هدف و ادامه‌دادن کار در چنین فرایندهایی بهینه شده است.

مشخصات مهم GLM-5.2

براساس مستندات رسمی GLM-5.2، این مدل برای Agentهای برنامه‌نویسی و وظایف طولانی آموزش تخصصی دیده و از Context یک میلیون توکنی پشتیبانی می‌کند.

ظرفیت Context اعلام‌شده به معنی آن نیست که باید در تمام درخواست‌ها یک میلیون توکن ارسال کنید. Context بسیار بزرگ یک ظرفیت است، نه توصیه‌ای برای مصرف همیشگی.

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

منظور از Context یک میلیون توکنی چیست؟

Context Window حداکثر فضایی است که مدل برای مجموع ورودی، تاریخچه گفتگو، پیام‌های سیستمی، خروجی ابزارها و پاسخ تولیدی در اختیار دارد.

Context یک میلیون توکنی می‌تواند برای سناریوهای زیر مفید باشد:

• تحلیل یک Repository بزرگ
• بررسی تعداد زیادی فایل کد
• پردازش مستندات فنی طولانی
• نگهداری تاریخچه یک Agent در اجرای طولانی
• مقایسه چند نسخه از یک سیستم
• تحلیل گزارش‌ها و Logهای حجیم
• Refactoring پروژه‌های چندماژوله
• تحقیق روی مجموعه بزرگی از منابع
• بررسی قراردادهای API و Schemaهای متعدد

اما ارسال تمام اطلاعات موجود به مدل معمولاً بهترین راه نیست. Context بزرگ همچنان هزینه، زمان پاسخ و پیچیدگی مدیریت اطلاعات را افزایش می‌دهد.

راهکار حرفه‌ای این است که Context را مهندسی کنید:

• ابتدا ساختار Repository را ارسال کنید.
• فایل‌ها را براساس ارتباط با وظیفه انتخاب کنید.
• خروجی ابزارهای قدیمی را خلاصه کنید.
• اطلاعات تکراری را حذف کنید.
• وضعیت پروژه را به‌صورت Structured State نگه دارید.
• برای جست‌وجوی مستندات از RAG استفاده کنید.
• فقط در صورت نیاز، Context کامل‌تر را به مدل بدهید.

قابلیت Long-Horizon در GLM-5.2 چه کاربردی دارد؟

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

در وظایف طولانی، یک مدل باید بتواند:

• هدف اصلی را حفظ کند.
• محدودیت‌های پروژه را به خاطر بسپارد.
• پیشرفت کار را ثبت کند.
• خروجی ابزارها را تفسیر کند.
• خطاهای قبلی را تکرار نکند.
• برنامه خود را براساس نتیجه اجرا تغییر دهد.
• بین اقدام، مشاهده و اصلاح جابه‌جا شود.
• تشخیص دهد چه زمانی کار واقعاً تمام شده است.

GLM-5.2 برای چنین الگوی کاری طراحی شده و در معرفی رسمی مدل نیز بر مهندسی نرم‌افزار طولانی‌مدت، تحقیق خودکار و بهینه‌سازی عملکرد تأکید شده است.

کاربردهای GLM-5.2

۱. ساخت Coding Agent

یک Coding Agent فقط کد پیشنهاد نمی‌کند؛ می‌تواند فایل‌ها را بخواند، تغییرات لازم را تشخیص دهد، Patch بسازد، تست اجرا کند و براساس نتیجه تست، کد را اصلاح کند.

GLM-5.2 می‌تواند هسته استدلالی چنین سیستمی باشد. ابزارهای واقعی باید توسط برنامه شما اجرا شوند و نتیجه آن‌ها مجدداً به مدل برگردد.

ابزارهای متداول یک Coding Agent عبارت‌اند از:

• read_file
• search_code
• list_files
• apply_patch
• run_tests
• run_linter
• get_git_diff
• read_documentation

۲. تحلیل Repositoryهای بزرگ

در پروژه‌های قدیمی، بخش زیادی از زمان توسعه‌دهنده صرف درک معماری می‌شود. مدل می‌تواند ساختار کد را تحلیل کرده و به پرسش‌هایی مانند موارد زیر پاسخ دهد:

• نقطه ورود برنامه کجاست؟
• احراز هویت در کدام لایه انجام می‌شود؟
• وابستگی میان ماژول‌ها چگونه است؟
• تغییر یک Interface چه فایل‌هایی را تحت‌تأثیر قرار می‌دهد؟
• علت احتمالی یک باگ Cross-Service چیست؟
• کدام بخش‌ها بیشترین Technical Debt را دارند؟

۳. Refactoring چندفایلی

Refactoring واقعی معمولاً به یک فایل محدود نیست. تغییر یک قرارداد ممکن است Controller، Service، Repository، Test و مستندات را هم‌زمان تحت‌تأثیر قرار دهد.

GLM-5.2 برای سناریوهایی مفید است که مدل باید تغییر را در سطح پروژه دنبال کند و سازگاری فایل‌ها را حفظ کند.

۴. تولید و اصلاح تست

مدل می‌تواند:

• Unit Test تولید کند.
• Edge Caseها را پیدا کند.
• Mock مناسب بسازد.
• تست‌های شکست‌خورده را تحلیل کند.
• Integration Test پیشنهاد دهد.
• پوشش تست بخش‌های حساس را افزایش دهد.
• تست‌های بی‌ثبات یا Flaky را شناسایی کند.

۵. مهاجرت میان فناوری‌ها

نمونه وظایف مهاجرتی مناسب عبارت‌اند از:

• تبدیل JavaScript به TypeScript
• ارتقای نسخه یک Framework
• تبدیل REST API قدیمی به معماری جدید
• جایگزینی یک ORM
• مهاجرت از Library منسوخ‌شده
• تبدیل پروژه Monolith به ماژول‌های مستقل
• به‌روزرسانی قراردادها و تست‌های وابسته

۶. ساخت Agent تحقیقاتی

GLM-5.2 صرفاً برای کدنویسی نیست. می‌توان آن را به ابزار جست‌وجو، پایگاه دانش و پردازش اسناد متصل کرد تا یک Research Agent بسازد.

Agent تحقیقاتی می‌تواند:

1. پرسش را به چند زیرمسئله تقسیم کند.
2. منابع لازم را جست‌وجو کند.
3. محتوای هر منبع را استخراج کند.
4. ادعاهای مشابه یا متناقض را مقایسه کند.
5. شکاف‌های اطلاعاتی را تشخیص دهد.
6. گزارش نهایی ساختاریافته تولید کند.

۷. تولید رابط کاربری

مدل‌های Coding جدید تنها برای Backend کاربرد ندارند. GLM-5.2 می‌تواند براساس شرح نیاز، کد HTML، CSS، Tailwind، React یا Vue تولید کند و سپس با دریافت خطا یا بازخورد، طرح را اصلاح کند.

برای نتیجه بهتر باید موارد زیر را در Prompt مشخص کنید:

• Design System
• رنگ‌ها
• Typography
• Breakpointها
• وضعیت‌های Loading و Error
• رفتار Responsive
• نیازهای Accessibility
• Framework و نسخه آن
• فرمت خروجی مورد انتظار

GLM-5.2 برای چه کسانی مناسب است؟

این مدل می‌تواند برای گروه‌های زیر ارزشمند باشد:

• برنامه‌نویسان Backend و Frontend
• تیم‌های DevOps
• توسعه‌دهندگان ابزارهای Coding
• تیم‌های نرم‌افزاری دارای Repository بزرگ
• سازندگان AI Agent
• استارتاپ‌های نرم‌افزاری
• تیم‌های تحقیق و توسعه
• شرکت‌های دارای مستندات فنی گسترده
• سازندگان دستیارهای سازمانی
• توسعه‌دهندگان سیستم‌های چندمدلی

اگر تنها به پاسخ‌های کوتاه، طبقه‌بندی ساده یا بازنویسی متن نیاز دارید، ممکن است یک مدل کوچک‌تر و اقتصادی‌تر انتخاب مناسب‌تری باشد. GLM-5.2 زمانی بیشترین ارزش را دارد که پیچیدگی وظیفه، Context بزرگ یا اجرای چندمرحله‌ای واقعاً ضروری باشد.

مزایای GLM-5.2

Context بسیار بزرگ

ظرفیت یک میلیون توکن امکان پردازش پروژه‌ها و اسناد بزرگ‌تر را فراهم می‌کند. بااین‌حال، کیفیت انتخاب Context همچنان از حجم آن مهم‌تر است.

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

این مدل برای تولید یک تابع ساده محدود نشده و هدف اصلی آن انجام وظایف مهندسی در سطح پروژه است.

مناسب برای Agent

پشتیبانی از Tool Calling و استدلال چندمرحله‌ای، GLM-5.2 را برای Agentهای عملی مناسب می‌کند.

خروجی ساختاریافته

در پروژه‌هایی که پاسخ باید مستقیماً توسط برنامه پردازش شود، می‌توان از JSON Schema یا الگوهای خروجی ساختاریافته استفاده کرد.

کنترل سطح Reasoning

بسته به قابلیت فعال API، می‌توان میزان تلاش استدلالی را با پارامتری مانند reasoning_effort تنظیم کرد. وظیفه ساده به Reasoning سنگین نیاز ندارد، اما طراحی معماری یا رفع باگ پیچیده می‌تواند از سطح بالاتر بهره ببرد.

مناسب برای فرایندهای چندمرحله‌ای

مدل می‌تواند برنامه‌ریزی، اجرا، مشاهده نتیجه و اصلاح مسیر را در قالب یک Agent Loop دنبال کند.

محدودیت‌های GLM-5.2

هیچ مدلی برای تمام وظایف بهترین گزینه نیست. محدودیت‌های احتمالی GLM-5.2 را نیز باید در طراحی سیستم در نظر گرفت.

تأخیر بیشتر در وظایف پیچیده

استدلال عمیق و تولید پاسخ طولانی ممکن است Latency را افزایش دهد. برای رابط کاربری بلادرنگ بهتر است Streaming فعال شود.

هزینه Context طولانی

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

احتمال تولید کد نادرست

مدل قدرتمند همچنان ممکن است:

• API غیرواقعی پیشنهاد کند.
• نسخه Library را اشتباه تشخیص دهد.
• Edge Case را نادیده بگیرد.
• تغییری ناسازگار با معماری بسازد.
• تستی تولید کند که هدف اصلی را درست ارزیابی نمی‌کند.

تمام کدهای تولیدشده باید با تست، Type Checker، Linter و Code Review بررسی شوند.

نبود اطلاعات لحظه‌ای به‌صورت پیش‌فرض

مدل بدون اتصال به ابزار خارجی از تغییرات لحظه‌ای Repository، مستندات جدید یا وضعیت سرویس‌ها آگاه نیست. این اطلاعات باید از طریق ابزار، RAG یا API به آن داده شود.

بزرگ‌بودن Context تضمین‌کننده توجه یکسان نیست

قرارگرفتن یک داده در Context به این معنی نیست که مدل در تمام مراحل به آن توجه یکسانی خواهد داشت. اطلاعات حیاتی را به‌صورت واضح، ساختاریافته و نزدیک به دستور اصلی ارائه کنید.

استفاده از GLM-5.2 با API درواره

برای شروع، ابتدا در درواره ثبت‌نام و API Key خود را دریافت کنید.

مشخصات اتصال:

Base URL: https://api.darvareh.ir/v1
Model ID درواره: z-ai/glm-5.2

کلید API را فقط در Backend نگه دارید. قراردادن کلید در کد Frontend، برنامه موبایل یا Repository عمومی می‌تواند آن را افشا کند.

نمونه درخواست با cURL

curl https://api.darvareh.ir/v1/chat/completions \
  -H "Authorization: Bearer YOUR_DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-ai/glm-5.2",
    "messages": [
      {
        "role": "system",
        "content": "You are a senior software engineer. Produce practical, testable and maintainable solutions."
      },
      {
        "role": "user",
        "content": "یک REST API با FastAPI طراحی کن که شامل pagination، validation، error handling و تست باشد."
      }
    ],
    "temperature": 0.2,
    "max_tokens": 4000
  }'

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

اتصال GLM-5.2 به Python

ابتدا SDK را نصب کنید:

pip install openai

کلید API را در متغیر محیطی قرار دهید:

export DARVAREH_API_KEY="YOUR_DARVAREH_API_KEY"

سپس درخواست را ارسال کنید:

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="z-ai/glm-5.2",
    messages=[
        {
            "role": "system",
            "content": (
                "You are a senior Python engineer. "
                "Prioritize correctness, maintainability and tests."
            )
        },
        {
            "role": "user",
            "content": """
کد زیر را از نظر معماری بررسی کن و نسخه Refactorشده ارائه بده.

الزامات:
- منطق کسب‌وکار از لایه HTTP جدا شود.
- Dependency Injection رعایت شود.
- خطاها ساختاریافته باشند.
- برای رفتارهای مهم Unit Test بنویس.
- قبل از تولید کد، برنامه تغییرات را توضیح بده.
"""
        }
    ],
    temperature=0.2,
    max_tokens=6000
)

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

اتصال GLM-5.2 به JavaScript و Node.js

نصب پکیج:

npm install openai

نمونه کد:

import OpenAI from "openai";

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

const response = await client.chat.completions.create({
  model: "z-ai/glm-5.2",
  messages: [
    {
      role: "system",
      content:
        "You are a senior TypeScript engineer. Return reliable and testable code.",
    },
    {
      role: "user",
      content: `
برای Node.js و TypeScript یک سرویس پردازش Job طراحی کن.

نیازمندی‌ها:
- Retry با exponential backoff
- idempotency
- graceful shutdown
- structured logging
- تست با Vitest
- توضیح تصمیم‌های معماری
      `,
    },
  ],
  temperature: 0.2,
  max_tokens: 6000,
});

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

استفاده از Streaming

برای پاسخ‌های طولانی بهتر است خروجی به‌صورت Streaming به کاربر نمایش داده شود.

نمونه Python:

import os
from openai import OpenAI

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

stream = client.chat.completions.create(
    model="z-ai/glm-5.2",
    messages=[
        {
            "role": "user",
            "content": (
                "برای مهاجرت یک پروژه بزرگ JavaScript به TypeScript "
                "یک برنامه اجرایی مرحله‌به‌مرحله تهیه کن."
            )
        }
    ],
    temperature=0.2,
    max_tokens=5000,
    stream=True
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Streaming مدت کل پردازش را لزوماً کاهش نمی‌دهد، اما زمان دریافت اولین بخش پاسخ را کمتر و تجربه کاربری را بهتر می‌کند.

ساخت یک Code Review API با FastAPI و GLM-5.2

در این مثال، یک Endpoint می‌سازیم که کد و توضیحات پروژه را دریافت کرده و گزارش Code Review تولید می‌کند.

import os
from typing import Literal

from fastapi import FastAPI, HTTPException
from openai import OpenAI
from pydantic import BaseModel, Field

app = FastAPI(title="GLM Code Review API")

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


class ReviewRequest(BaseModel):
    language: str = Field(min_length=1, max_length=50)
    code: str = Field(min_length=1, max_length=100_000)
    focus: Literal[
        "general",
        "performance",
        "maintainability",
        "testing"
    ] = "general"


class ReviewResponse(BaseModel):
    review: str


@app.post("/reviews", response_model=ReviewResponse)
def review_code(payload: ReviewRequest) -> ReviewResponse:
    prompt = f"""
زبان برنامه‌نویسی: {payload.language}
تمرکز بررسی: {payload.focus}

کد:
```{payload.language}
{payload.code}

کد را بررسی کن و پاسخ را با این ساختار ارائه بده:

1. خلاصه
2. مشکلات با اولویت Critical، High، Medium و Low
3. دلیل هر مشکل
4. راه‌حل پیشنهادی
5. نسخه اصلاح‌شده بخش‌های ضروری
6. تست‌های پیشنهادی

فقط درباره مشکلاتی صحبت کن که از روی کد قابل استنباط‌اند.
اگر اطلاعات کافی نیست، فرضیات را صریح بنویس.
"""

try:
    result = client.chat.completions.create(
        model="z-ai/glm-5.2",
        messages=[
            {
                "role": "system",
                "content": (
                    "You are a precise senior code reviewer. "
                    "Do not invent missing project context."
                )
            },
            {
                "role": "user",
                "content": prompt
            }
        ],
        temperature=0.1,
        max_tokens=5000
    )
except Exception as exc:
    raise HTTPException(
        status_code=502,
        detail="AI model request failed"
    ) from exc

return ReviewResponse(
    review=result.choices[0].message.content or ""
)

اجرای برنامه:

```bash
uvicorn main:app --reload

نمونه درخواست:

curl http://localhost:8000/reviews \
  -H "Content-Type: application/json" \
  -d '{
    "language": "python",
    "focus": "maintainability",
    "code": "def get_user(id):\n    return db.execute(\"SELECT * FROM users WHERE id=\" + id)"
  }'

ساخت AI Agent با GLM-5.2

معماری ساده یک Agent از چهار جزء تشکیل می‌شود:

1. مدل: تصمیم می‌گیرد چه کاری انجام شود.
2. ابزارها: عملیات واقعی مانند خواندن فایل یا اجرای تست را انجام می‌دهند.
3. حافظه یا State: وضعیت، تصمیم‌ها و نتایج قبلی را نگه می‌دارد.
4. Agent Loop: تا رسیدن به پاسخ نهایی، چرخه تصمیم و اجرا را ادامه می‌دهد.

جریان کار می‌تواند چنین باشد:

دریافت هدف
برنامه‌ریزی
انتخاب ابزار
اجرای ابزار توسط Backend
ارسال نتیجه ابزار به مدل
ارزیابی پیشرفت
ادامه کار یا تولید پاسخ نهایی

نکته مهم این است که مدل نباید مستقیماً به سیستم‌عامل یا فایل‌های حساس دسترسی نامحدود داشته باشد. برنامه شما باید Tool Call را اعتبارسنجی و سپس اجرا کند.

تعریف ابزار برای Agent

نمونه تعریف ابزار خواندن فایل:

tools = [
    {
        "type": "function",
        "function": {
            "name": "read_project_file",
            "description": "Read a UTF-8 text file from the project workspace.",
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {
                        "type": "string",
                        "description": "Project-relative file path"
                    }
                },
                "required": ["path"],
                "additionalProperties": False
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "run_project_tests",
            "description": "Run the predefined project test command.",
            "parameters": {
                "type": "object",
                "properties": {},
                "additionalProperties": False
            }
        }
    }
]

ارسال ابزارها به مدل:

response = client.chat.completions.create(
    model="z-ai/glm-5.2",
    messages=[
        {
            "role": "system",
            "content": """
You are a coding agent.

Rules:
- Inspect relevant files before proposing changes.
- Never claim a test passed unless the tool result confirms it.
- Use only the provided tools.
- Keep changes limited to the user's request.
- Finish with a concise summary and test status.
"""
        },
        {
            "role": "user",
            "content": "علت شکست تست‌های ماژول پرداخت را پیدا کن."
        }
    ],
    tools=tools,
    tool_choice="auto",
    temperature=0.1
)

برنامه باید tool_calls را از پاسخ دریافت کند، آرگومان‌ها را بررسی کند، ابزار مجاز را اجرا کند و نتیجه را با نقش tool به مدل برگرداند.

نمونه حلقه Tool Calling در Python

import json
import os
from pathlib import Path

from openai import OpenAI

WORKSPACE = Path("/app/project").resolve()

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


def safe_project_path(relative_path: str) -> Path:
    target = (WORKSPACE / relative_path).resolve()

    if target != WORKSPACE and WORKSPACE not in target.parents:
        raise ValueError("Path is outside the workspace")

    return target


def read_project_file(path: str) -> str:
    target = safe_project_path(path)

    if not target.is_file():
        return json.dumps({
            "ok": False,
            "error": "File not found"
        })

    return json.dumps({
        "ok": True,
        "path": path,
        "content": target.read_text(
            encoding="utf-8",
            errors="replace"
        )[:100_000]
    })


tool_definitions = [
    {
        "type": "function",
        "function": {
            "name": "read_project_file",
            "description": "Read a text file inside the project workspace.",
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {"type": "string"}
                },
                "required": ["path"],
                "additionalProperties": False
            }
        }
    }
]

tool_handlers = {
    "read_project_file": read_project_file
}

messages = [
    {
        "role": "system",
        "content": (
            "You are a coding agent. Inspect files before answering. "
            "Never invent file contents."
        )
    },
    {
        "role": "user",
        "content": (
            "فایل pyproject.toml را بررسی کن و درباره ساختار "
            "وابستگی‌های پروژه گزارش بده."
        )
    }
]

for _ in range(10):
    response = client.chat.completions.create(
        model="z-ai/glm-5.2",
        messages=messages,
        tools=tool_definitions,
        tool_choice="auto",
        temperature=0.1,
        max_tokens=3000
    )

    assistant_message = response.choices[0].message
    messages.append(assistant_message)

    if not assistant_message.tool_calls:
        print(assistant_message.content)
        break

    for tool_call in assistant_message.tool_calls:
        name = tool_call.function.name

        try:
            arguments = json.loads(
                tool_call.function.arguments
            )
            handler = tool_handlers[name]
            result = handler(**arguments)
        except Exception as exc:
            result = json.dumps({
                "ok": False,
                "error": str(exc)
            })

        messages.append({
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": result
        })
else:
    raise RuntimeError("Agent reached its maximum number of steps")

محدودکردن حلقه Agent ضروری است. بدون max_steps، Agent ممکن است ابزارها را بیش از حد فراخوانی کند و باعث افزایش هزینه یا زمان اجرا شود.

اصول ایمن‌سازی ابزارهای Agent

حتی برای ابزارهای غیرامنیتی و کاربردهای عادی، باید دسترسی Agent را کنترل کنید:

• فقط ابزارهای ضروری را در اختیار مدل قرار دهید.
• ورودی تمام Tool Callها را با Schema اعتبارسنجی کنید.
• مسیر فایل را به Workspace مشخص محدود کنید.
• فرمان Shell آزاد در اختیار مدل قرار ندهید.
• برای عملیات تغییردهنده، مرحله تأیید تعریف کنید.
• زمان اجرای ابزار را محدود کنید.
• اندازه خروجی ابزار را کنترل کنید.
• تعداد مراحل Agent را محدود کنید.
• تمام فراخوانی‌ها را Log کنید.
• عملیات حساس را در محیط Sandbox اجرا کنید.
• کلید API و Secretها را از خروجی ابزار حذف کنید.

قدرت بیشتر Agent بدون محدودیت‌های اجرایی، لزوماً به سیستم بهتری منجر نمی‌شود.

پرامپت‌نویسی برای GLM-5.2

یک Prompt حرفه‌ای برای مدل برنامه‌نویسی بهتر است شامل بخش‌های زیر باشد:

نقش

تو یک مهندس ارشد Backend با تخصص در Python، FastAPI و PostgreSQL هستی.

هدف

Endpoint ثبت سفارش را به‌گونه‌ای بازطراحی کن که idempotent باشد.

Context

پروژه از معماری لایه‌ای استفاده می‌کند.
تراکنش‌ها در Service Layer مدیریت می‌شوند.
شناسه درخواست از هدر Idempotency-Key دریافت می‌شود.

محدودیت‌ها

Schema فعلی دیتابیس را تغییر نده.
Dependency جدید اضافه نکن.
API عمومی موجود نباید شکسته شود.

معیار پذیرش

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

فرمت خروجی

ابتدا تحلیل کوتاه ارائه بده.
سپس فایل‌های نیازمند تغییر را فهرست کن.
بعد Patch هر فایل را تولید کن.
در پایان تست‌های لازم را بنویس.

نمونه Prompt کامل برای رفع باگ

نقش:
تو یک مهندس ارشد TypeScript و PostgreSQL هستی.

هدف:
علت ایجاد سفارش تکراری هنگام Retry شدن درخواست را پیدا کن و راه‌حل بده.

اطلاعات:
- Backend با NestJS نوشته شده است.
- Jobها از طریق Queue پردازش می‌شوند.
- ممکن است یک Job بیش از یک بار تحویل داده شود.
- PostgreSQL پایگاه داده اصلی است.

محدودیت‌ها:
- Queue را تعویض نکن.
- API عمومی تغییر نکند.
- راه‌حل باید در برابر اجرای هم‌زمان مقاوم باشد.
- موفقیت عملیات را بدون تست ادعا نکن.

معیارهای پذیرش:
- برای یک idempotency key فقط یک سفارش ساخته شود.
- Retry همان پاسخ قبلی را برگرداند.
- تست concurrent request نوشته شود.
- خطاهای موقت قابل Retry باقی بمانند.

فرایند:
1. ابتدا فرضیه‌های احتمالی را اولویت‌بندی کن.
2. اطلاعات ناقص را مشخص کن.
3. راه‌حل معماری را توضیح بده.
4. کد پیشنهادی را ارائه کن.
5. تست‌ها و روش اعتبارسنجی را بنویس.

Prompt مناسب برای بررسی Repository

این Repository را به‌صورت مرحله‌ای تحلیل کن.

هدف:
تهیه نقشه معماری برای ورود یک توسعه‌دهنده جدید.

مراحل:
1. ابتدا ساختار پوشه‌ها را بررسی کن.
2. Entry Pointها را پیدا کن.
3. ماژول‌های اصلی را شناسایی کن.
4. جریان یک درخواست را از HTTP تا Database دنبال کن.
5. سرویس‌های خارجی را فهرست کن.
6. تست‌ها و روش اجرای پروژه را پیدا کن.
7. موارد نامطمئن را به‌عنوان فرضیه مشخص کن.

قوانین:
- محتوای فایل‌ها را حدس نزن.
- قبل از نتیجه‌گیری فایل مرتبط را بخوان.
- شواهد هر نتیجه را با مسیر فایل ذکر کن.
- هیچ فایلی را تغییر نده.

آیا Prompt باید فارسی باشد یا انگلیسی؟

GLM-5.2 می‌تواند دستورهای زبان طبیعی را پردازش کند، اما کیفیت را باید با داده واقعی پروژه خود ارزیابی کنید. در پروژه‌های برنامه‌نویسی معمولاً ترکیب زیر نتیجه خوبی می‌دهد:

• توضیح نیاز کسب‌وکار به فارسی
• نام فناوری‌ها و مفاهیم فنی به انگلیسی
• نام متغیرها و کامنت کد به انگلیسی
• تعریف Tool و JSON Schema به انگلیسی
• نمونه خروجی دقیق و مستقل از زبان

مثلاً به‌جای ترجمه غیرطبیعی تمام اصطلاحات، بنویسید:

برای Endpoint ساخت سفارش، Retry، idempotency و transaction handling را پیاده‌سازی کن.

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

تنظیم Temperature برای GLM-5.2

temperature میزان تنوع خروجی را کنترل می‌کند.

این مقادیر قانون قطعی نیستند. برای کاربرد Production باید با مجموعه‌ای از وظایف واقعی Evaluation انجام دهید.

تنظیم Reasoning Effort

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

none
minimal
low
medium
high
xhigh
max

برای کارهای ساده از سطح پایین‌تر استفاده کنید:

• استخراج فیلدها
• بازنویسی کوتاه
• طبقه‌بندی
• تولید Boilerplate
• اصلاح قالب‌بندی

برای کارهای پیچیده سطح بالاتر مفید است:

• طراحی معماری
• Debug چندمرحله‌ای
• تحلیل Repository بزرگ
• Refactoring گسترده
• Agentهای طولانی
• بهینه‌سازی عملکرد

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

GLM-5.2 و Structured Output

در سیستم Production نباید برای پردازش خودکار به متن آزاد متکی باشید. خروجی ساختاریافته امکان Validation و پردازش قابل‌اعتمادتر را فراهم می‌کند.

نمونه Schema برای Code Review:

{
  "summary": "string",
  "risk_level": "low | medium | high",
  "findings": [
    {
      "title": "string",
      "severity": "low | medium | high",
      "file": "string",
      "line": 0,
      "explanation": "string",
      "suggestion": "string"
    }
  ],
  "recommended_tests": [
    "string"
  ]
}

حتی هنگام استفاده از Structured Output باید پاسخ را در Backend اعتبارسنجی کنید. مدل نباید مرجع نهایی صحت داده باشد.

معماری پیشنهادی برای استفاده Production

یک پیاده‌سازی قابل‌اعتماد بهتر است اجزای زیر را داشته باشد:

API Layer

درخواست کاربر را دریافت و اعتبارسنجی می‌کند. احراز هویت، Rate Limit و محدودیت اندازه ورودی نیز در این لایه قرار می‌گیرند.

Prompt Builder

اطلاعات کاربر، دستور سیستمی، Context و Schema خروجی را به Prompt نهایی تبدیل می‌کند.

Model Gateway

ارتباط با API درواره را مدیریت می‌کند. Timeout، Retry، Streaming و انتخاب مدل در این بخش قرار می‌گیرند.

Tool Executor

فراخوانی ابزارها را اعتبارسنجی و در محیط محدود اجرا می‌کند.

State Store

وضعیت Agent، مراحل انجام‌شده، خلاصه Context و شناسه درخواست‌ها را ذخیره می‌کند.

Evaluator

بررسی می‌کند خروجی از نظر ساختار، معیارهای پذیرش و قواعد پروژه معتبر باشد.

Observability

مدت پاسخ، مصرف Token، خطاها، تعداد Tool Callها و نتیجه هر اجرا را ثبت می‌کند.

مدیریت Context در پروژه‌های بزرگ

اگر Repository بسیار بزرگ باشد، ارسال یک‌باره تمام فایل‌ها رویکرد مناسبی نیست. بهتر است از یک فرایند چندمرحله‌ای استفاده کنید.

مرحله اول: ساخت نقشه Repository

اطلاعات زیر را استخراج کنید:

• درخت پوشه‌ها
• فایل‌های تنظیمات
• Entry Pointها
• Manifest وابستگی‌ها
• فایل‌های تست
• مستندات
• Schemaهای داده

مرحله دوم: انتخاب فایل‌های مرتبط

با جست‌وجوی نام Symbol، Importها و مسیرهای وابستگی، فایل‌های مرتبط با وظیفه را پیدا کنید.

مرحله سوم: ساخت Context Pack

یک بسته اطلاعاتی محدود و ساختاریافته بسازید:

{
  "task": "Add idempotency to order creation",
  "architecture": "Layered NestJS application",
  "relevant_files": [],
  "constraints": [],
  "acceptance_criteria": [],
  "known_failures": []
}

مرحله چهارم: اجرای Agent

مدل فقط در صورت نیاز فایل دیگری را از طریق Tool درخواست کند.

مرحله پنجم: فشرده‌سازی تاریخچه

پس از چند مرحله، خروجی‌های قدیمی ابزار را خلاصه کنید و فقط تصمیم‌ها، خطاهای باز و وضعیت فعلی را نگه دارید.

کاهش هزینه استفاده از GLM-5.2

برای کنترل هزینه API می‌توانید این اقدامات را انجام دهید:

• وظایف ساده را به مدل‌های کوچک‌تر بسپارید.
• فقط فایل‌های مرتبط را وارد Context کنید.
• نتایج ثابت را Cache کنید.
• تاریخچه طولانی را خلاصه کنید.
• max_tokens را بدون دلیل بالا نبرید.
• Tool Outputهای حجیم را برش یا خلاصه کنید.
• از Model Routing استفاده کنید.
• تعداد مراحل Agent را محدود کنید.
• درخواست‌های تکراری را با Idempotency کنترل کنید.
• مصرف هر کاربر و هر قابلیت را جداگانه ثبت کنید.

قیمت مدل‌ها ممکن است تغییر کند؛ عدد ثابت داخل کد یا مستندات محصول قرار ندهید و برای اطلاعات روز از صفحه قیمت و مدل‌های درواره استفاده کنید.

الگوی Model Routing برای GLM-5.2

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

نمونه سیاست:

def choose_model(task: dict) -> str:
    if task.get("requires_long_context"):
        return "z-ai/glm-5.2"

    if task.get("requires_tools") and task.get("complexity") == "high":
        return "z-ai/glm-5.2"

    if task.get("task_type") in {
        "repository_analysis",
        "multi_file_refactor",
        "complex_debugging"
    }:
        return "z-ai/glm-5.2"

    return "YOUR_LIGHTWEIGHT_MODEL_ID"

نام مدل‌های جایگزین را از فهرست فعال درواره انتخاب کنید. بهتر است انتخاب مدل به‌صورت Configuration انجام شود، نه اینکه در تمام فایل‌های پروژه Hardcode شود.

Retry و Timeout

همه درخواست‌های شبکه ممکن است با خطای موقت مواجه شوند. برای خطاهای قابل Retry از Exponential Backoff استفاده کنید.

import random
import time


def call_with_retry(operation, max_attempts=4):
    for attempt in range(max_attempts):
        try:
            return operation()
        except Exception:
            if attempt == max_attempts - 1:
                raise

            delay = min(2 ** attempt, 8)
            jitter = random.uniform(0, 0.5)
            time.sleep(delay + jitter)

تمام خطاها را Retry نکنید. خطای Validation، API Key نامعتبر یا درخواست ناسازگار معمولاً با تکرار حل نمی‌شود.

Evaluation مدل پیش از استفاده Production

انتخاب مدل را صرفاً براساس Benchmark عمومی انجام ندهید. یک Evaluation Set از وظایف واقعی محصول خود بسازید.

برای Coding Agent می‌توانید این معیارها را اندازه بگیرید:

• درصد تست‌های پاس‌شده
• صحت Patch
• تعداد فایل‌های غیرضروری تغییریافته
• تعداد Tool Callها
• زمان رسیدن به پاسخ
• هزینه هر وظیفه موفق
• نرخ ساخت API یا Symbol غیرواقعی
• درصد نیاز به اصلاح انسانی
• توانایی رعایت محدودیت‌ها
• پایداری نتیجه در اجرای مجدد

نمونه جدول ارزیابی:

حداقل چند نمونه از هر نوع وظیفه داشته باشید. ارزیابی با یک Prompt نمی‌تواند نماینده عملکرد واقعی مدل باشد.

GLM-5.2 در مقایسه با مدل کوچک‌تر

بهترین معماری معمولاً استفاده انحصاری از یک مدل نیست؛ بلکه ترکیب چند مدل و Routing هوشمند براساس نوع وظیفه است.

اشتباهات رایج هنگام استفاده از GLM-5.2

ارسال تمام Repository در هر درخواست

Context بزرگ نباید جایگزین انتخاب هوشمند اطلاعات شود.

نداشتن معیار پایان برای Agent

Agent باید بداند چه شرایطی به معنی تکمیل کار است. همچنین Backend باید تعداد مراحل، زمان و هزینه را محدود کند.

اعتماد کامل به ادعای اجرای تست

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

استفاده از Temperature بالا برای Tool Calling

برای Agentهای اجرایی، خروجی پایدار و قابل پیش‌بینی معمولاً از تنوع خلاقانه مهم‌تر است.

قراردادن API Key در Frontend

کلید درواره را در مرورگر، اپلیکیشن موبایل یا کد عمومی قرار ندهید. درخواست‌ها باید از Backend شما عبور کنند.

ذخیره‌کردن بی‌محدودیت تمام تاریخچه

تاریخچه Tool Callها می‌تواند بسیار حجیم شود. State مهم را استخراج و خروجی‌های قدیمی را خلاصه کنید.

نداشتن Evaluation

یک Demo موفق تضمین نمی‌کند که سیستم در صدها درخواست واقعی نیز قابل‌اعتماد باشد.

پرسش‌های متداول درباره GLM-5.2

GLM-5.2 چیست؟

GLM-5.2 یک مدل زبانی و Reasoning از خانواده GLM است که برای برنامه‌نویسی، Coding Agent، استفاده از ابزارها و اجرای وظایف طولانی بهینه شده است.

Context Window مدل GLM-5.2 چقدر است؟

طبق مستندات رسمی، این مدل از Context یک میلیون توکنی پشتیبانی می‌کند. محدودیت عملی هر مسیر API و مقدار مجاز خروجی را پیش از پیاده‌سازی بررسی کنید.

Model ID درواره برای GLM-5.2 چیست؟

Model ID درواره:

z-ai/glm-5.2

برای اطمینان از وضعیت فعال مدل، صفحه مدل‌های درواره را بررسی کنید.

Base URL درواره چیست؟

https://api.darvareh.ir/v1

آیا GLM-5.2 برای برنامه‌نویسی مناسب است؟

بله. یکی از کاربردهای اصلی این مدل، مهندسی نرم‌افزار در سطح پروژه، رفع باگ، Refactoring، تولید تست و اجرای فرایندهای Coding Agent است.

آیا می‌توان GLM-5.2 را به Python متصل کرد؟

بله. با استفاده از SDK سازگار و تنظیم base_url روی آدرس API درواره می‌توانید این مدل را در Python فراخوانی کنید.

آیا GLM-5.2 با JavaScript و Node.js کار می‌کند؟

بله. می‌توانید از SDK مربوط به Node.js استفاده کنید و Base URL و Model ID درواره را در تنظیمات قرار دهید.

آیا GLM-5.2 از Tool Calling پشتیبانی می‌کند؟

این خانواده برای Agent و استفاده از ابزارها طراحی شده است. جزئیات قابلیت فعال مسیر API را در فهرست مدل‌های درواره بررسی و Tool Callهای مدل را در Backend اعتبارسنجی کنید.

آیا GLM-5.2 برای چت‌بات ساده انتخاب مناسبی است؟

قابل استفاده است، اما ممکن است برای پرسش‌های کوتاه بیش از نیاز باشد. در چت‌بات‌های عمومی بهتر است از Model Routing استفاده کنید و فقط درخواست‌های پیچیده را به این مدل بفرستید.

آیا Context یک میلیون توکنی یعنی می‌توان کل پروژه را همیشه ارسال کرد؟

از نظر ظرفیت ممکن است حجم زیادی قابل پردازش باشد، اما ارسال بی‌هدف تمام پروژه هزینه و تأخیر را افزایش می‌دهد. انتخاب فایل مرتبط، RAG و خلاصه‌سازی همچنان ضروری‌اند.

آیا خروجی کد GLM-5.2 قابل اعتماد است؟

هیچ کد تولیدشده‌ای نباید بدون Review و Test وارد Production شود. از Unit Test، Integration Test، Linter، Type Checker و Code Review استفاده کنید.

چگونه هزینه GLM-5.2 را محاسبه کنیم؟

هزینه به مقدار Token ورودی، خروجی و قیمت فعال مدل وابسته است. برای مشاهده اطلاعات به‌روز به صفحه مدل‌های درواره مراجعه کنید.

جمع‌بندی

GLM-5.2 مدلی مناسب برای نسلی از کاربردهای هوش مصنوعی است که از یک پرسش و پاسخ ساده فراتر می‌روند. Context یک میلیون توکنی، تمرکز بر برنامه‌نویسی طولانی‌مدت، Reasoning، Tool Calling و اجرای وظایف چندمرحله‌ای، این مدل را به گزینه‌ای جدی برای Coding Agent، تحلیل Repository، Refactoring پروژه‌های بزرگ و اتوماسیون فرایندهای فنی تبدیل می‌کند.

بااین‌حال، کیفیت نهایی تنها به قدرت مدل وابسته نیست. طراحی ابزارها، مدیریت Context، محدودکردن Agent Loop، اعتبارسنجی خروجی، اجرای تست و اندازه‌گیری هزینه نقش تعیین‌کننده‌ای دارند.

برای شروع استفاده از GLM-5.2 از طریق API:

1. در درواره ثبت‌نام کنید.
2. API Key بگیرید.
3. وضعیت و قیمت مدل را در صفحه مدل‌های درواره ببینید.
4. Base URL را روی https://api.darvareh.ir/v1 قرار دهید.
5. از Model ID درواره یعنی z-ai/glm-5.2 استفاده کنید.
6. ابتدا یک نمونه محدود بسازید و مدل را با وظایف واقعی محصول ارزیابی کنید.

مقالات مرتبط

• راهنمای جامع مدل‌های هوش مصنوعی و انتخاب مدل مناسب
• بهترین مدل هوش مصنوعی برای برنامه‌نویسی؛ مقایسه هزینه و عملکرد
• انتخاب و مسیریابی مدل برای Coding Agent
• راهنمای AI Agent، ابزارها، Skills و MCP
• آموزش Function Calling در مدل‌های هوش مصنوعی
• راهنمای Tool Calling برای اتصال مدل هوش مصنوعی به ابزارها
• خروجی ساختاریافته و JSON Schema در API هوش مصنوعی
• Context Window چیست و چگونه آن را مدیریت کنیم؟
• معماری چندمدلی و چندارائه‌دهنده برای سرویس‌های هوش مصنوعی
• آموزش اتصال API هوش مصنوعی به اپلیکیشن
• راهنمای API سازگار با OpenAI
• ساخت API هوش مصنوعی آماده Production