Gemma 4 چیست؟ آموزش کامل مدل هوش مصنوعی Google برای متن، تصویر، صدا و AI Agent

Gemma 4 نسل جدید مدل‌های Open Weight شرکت Google DeepMind است که برای استدلال یا Reasoning، برنامه‌نویسی، تحلیل متن و تصویر، پردازش صدا، Function Calling و اجرای AI Agent روی Cloud، کامپیوتر شخصی، موبایل و دستگاه‌های Edge طراحی شده است.

خانواده Gemma با این هدف ساخته شده که توسعه‌دهندگان بتوانند از فناوری مدل‌های هوش مصنوعی Google در اندازه‌ها و معماری‌های مختلف استفاده کنند. برخلاف یک مدل واحد، Gemma 4 خانواده‌ای از مدل‌هاست که از نسخه‌های کوچک مناسب دستگاه‌های شخصی تا نسخه‌های بزرگ‌تر مناسب پردازش Cloud را شامل می‌شود.

این تنوع به توسعه‌دهنده اجازه می‌دهد براساس نیاز محصول میان این عوامل تعادل ایجاد کند:

• کیفیت و دقت
• سرعت پاسخ
• هزینه API
• حافظه سخت‌افزاری
• نوع ورودی
• اندازه Context
• اجرای Local یا Cloud
• قابلیت Reasoning
• Tool Calling
• مصرف انرژی

برای استفاده ساده‌تر از نسخه‌های ارائه‌شده Gemma 4، می‌توانید از API درواره استفاده کنید و مدل را با یک API سازگار با OpenAI به پروژه Python، JavaScript، TypeScript، PHP یا سایر زبان‌ها متصل کنید.

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

مشخصات کلی Gemma 4

براساس مستندات رسمی Gemma 4، تمام مدل‌های این خانواده از متن و تصویر پشتیبانی می‌کنند و برخی نسخه‌ها قابلیت پردازش صدا و ویدئو را نیز دارند.

نسخه‌های مختلف Gemma 4

Gemma 4 در چند اندازه و معماری ارائه شده است. هر نسخه برای سطح متفاوتی از سخت‌افزار و کاربرد طراحی شده است.

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

Model ID درواره برای Gemma 4

نسخه قدرتمند 31B می‌تواند با این شناسه در دسترس باشد:

Model ID درواره: google/gemma-4-31b-it

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

در این مقاله، مثال‌های API بر نسخه زیر متمرکز هستند:

google/gemma-4-31b-it

پسوند it به نسخه Instruction-Tuned اشاره دارد؛ یعنی مدلی که برای دنبال‌کردن دستور و تعامل با کاربر بهینه شده است.

تفاوت Gemma و Gemini چیست؟

Gemma و Gemini هر دو توسط Google DeepMind توسعه یافته‌اند، اما یکسان نیستند.

Gemma برای توسعه‌دهندگانی جذاب است که به انعطاف بیشتر در استقرار، Fine-Tuning یا اجرای Local نیاز دارند. Gemini معمولاً برای استفاده مستقیم از مدل‌های Frontier و سرویس‌های Cloud گوگل انتخاب می‌شود.

معماری Gemma 4 چه ویژگی‌هایی دارد؟

Gemma 4 فقط نسخه بزرگ‌تر Gemma 3 نیست. این خانواده چند قابلیت معماری جدید دارد:

• پشتیبانی گسترده‌تر از ورودی‌های چندوجهی
• Thinking Mode
• Function Calling بومی
• Context طولانی‌تر
• Multi-Token Prediction
• نسخه‌های Dense و MoE
• بهینه‌سازی برای Edge
• پشتیبانی از Agentic Workflow

مدل Dense چیست؟

در مدل Dense تمام پارامترهای اصلی برای پردازش هر Token درگیر می‌شوند. نسخه‌های Gemma 4 12B و 31B از این نوع هستند.

مزیت‌های مدل Dense:

• رفتار قابل پیش‌بینی‌تر
• پیاده‌سازی و استقرار ساده‌تر
• سازگاری گسترده با Runtimeها
• کیفیت پایدار در وظایف مختلف

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

مدل MoE چیست؟

Gemma 4 26B-A4B از معماری Mixture of Experts استفاده می‌کند. این مدل حدود ۲۶ میلیارد پارامتر کلی دارد، اما در هر مرحله تقریباً ۴ میلیارد پارامتر فعال می‌شوند.

عبارت 26B-A4B به این معنی است:

26B = پارامترهای کلی
A4B = پارامترهای فعال

هدف این طراحی ایجاد تعادل میان ظرفیت مدل و هزینه استنتاج است.

معماری Encoder-Free در Gemma 4 12B

یکی از ویژگی‌های مهم Gemma 4 12B، معماری چندوجهی یکپارچه و Encoder-Free است.

در بسیاری از مدل‌های Multimodal، ورودی تصویر یا صدا ابتدا توسط Encoder جداگانه پردازش و سپس به مدل زبانی ارسال می‌شود. Gemma 4 12B از معماری یکپارچه‌تری استفاده می‌کند که داده‌های چندوجهی را مستقیم‌تر وارد Backbone مدل می‌کند.

براساس راهنمای توسعه‌دهندگان Gemma 4 12B، این معماری برای کاهش پیچیدگی و تأخیر پردازش Multimodal طراحی شده است.

این نسخه برای کاربردهای زیر اهمیت دارد:

• پردازش صدا روی لپ‌تاپ
• تحلیل تصویر و متن
• دستیار صوتی محلی
• Agent چندوجهی
• تحلیل فایل‌های صوتی
• استخراج اطلاعات از اسناد تصویری

Thinking Mode در Gemma 4 چیست؟

Thinking Mode به مدل اجازه می‌دهد قبل از ارائه پاسخ نهایی، محاسبات و استدلال بیشتری انجام دهد.

این قابلیت برای مسائل زیر مفید است:

• مسائل منطقی
• برنامه‌نویسی پیچیده
• طراحی معماری
• تحلیل چند سند
• برنامه‌ریزی Agent
• تصمیم‌گیری چندمرحله‌ای
• مسائل ریاضی
• Tool Calling پیچیده

Thinking بیشتر همیشه بهتر نیست. برای سؤال‌های ساده می‌تواند فقط Latency و تعداد Token خروجی را افزایش دهد.

در محصول Production بهتر است Thinking براساس پیچیدگی وظیفه فعال شود.

Function Calling در Gemma 4

Gemma 4 برای Workflowهای Agentic از Function Calling پشتیبانی می‌کند. مدل می‌تواند تشخیص دهد برای تکمیل درخواست باید یک Function یا ابزار خارجی فراخوانی شود.

برای مثال، اگر کاربر بپرسد:

وضعیت سفارش شماره ۸۲۱۴ چیست؟

مدل نباید وضعیت سفارش را حدس بزند. در عوض باید ابزار زیر را فراخوانی کند:

get_order_status(order_id="8214")

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

Multi-Token Prediction چیست؟

مدل‌های زبانی به‌صورت سنتی Token بعدی را پیش‌بینی می‌کنند. Multi-Token Prediction یا MTP از یک بخش پیش‌بینی‌کننده کمکی برای پیشنهاد چند Token آینده استفاده می‌کند.

Runtime می‌تواند Tokenهای پیشنهادی را به‌صورت گروهی بررسی کند. اگر پیش‌بینی‌ها صحیح باشند، سرعت تولید افزایش می‌یابد.

Google اعلام کرده که استفاده از MTP در برخی استقرارهای Gemma 4 می‌تواند به افزایش سرعت تولید کمک کند. میزان بهبود به مدل، سخت‌افزار و Runtime وابسته است.

این قابلیت در سطح API معمولاً توسط زیرساخت مدیریت می‌شود و کاربر لازم نیست آن را در Prompt کنترل کند.

Context Window در Gemma 4

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

• مدل‌های کوچک‌تر: حدود 128K Token
• مدل‌های متوسط و بزرگ‌تر: تا حدود 256K Token

Context شامل مجموع این موارد است:

• System Prompt
• پیام‌های کاربر
• پاسخ‌های قبلی
• اسناد
• محتوای تصویر و صدا پس از Tokenization
• خروجی ابزارها
• پاسخ در حال تولید

Context 256K برای کاربردهای زیر مناسب است:

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

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

پشتیبانی Gemma 4 از زبان فارسی

Gemma 4 از بیش از ۱۴۰ زبان پشتیبانی می‌کند و می‌توان از آن برای ورودی و خروجی فارسی استفاده کرد.

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

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

پشتیبانی چندزبانه به معنی کیفیت کاملاً یکسان در تمام زبان‌ها نیست. پیش از استفاده Production باید مدل را روی داده واقعی فارسی ارزیابی کنید.

کاربردهای Gemma 4

۱. ساخت چت‌بات و دستیار هوش مصنوعی

Gemma 4 را می‌توان برای ساخت Backend یک دستیار هوش مصنوعی استفاده کرد.

دستیار می‌تواند:

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

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

۲. تحلیل تصویر

نسخه‌های Multimodal مدل می‌توانند تصویر و Prompt متنی را هم‌زمان پردازش کنند.

کاربردها:

• تحلیل Screenshot
• استخراج اطلاعات از نمودار
• بررسی رابط کاربری
• توضیح تصویر
• پاسخ به سؤال درباره تصویر
• تحلیل اسناد تصویری
• مقایسه دو تصویر
• تهیه توضیح محصول
• بررسی Mockup
• تبدیل تصویر به داده ساختاریافته

برای OCR دقیق یا پردازش صنعتی ممکن است ترکیب مدل با ابزار تخصصی مناسب‌تر باشد.

۳. تحلیل صدا

نسخه‌هایی مانند Gemma 4 12B از ورودی Audio پشتیبانی می‌کنند.

کاربردهای احتمالی:

• تبدیل گفتار به خلاصه
• تحلیل جلسه
• استخراج Action Item
• ویرایش متن با فرمان صوتی
• طبقه‌بندی فایل صوتی
• پاسخ به سؤال درباره مکالمه
• ساخت دستیار صوتی
• پردازش پیام‌های صوتی

پشتیبانی Audio باید برای Model ID و مسیر API فعال بررسی شود.

۴. برنامه‌نویسی

Gemma 4 می‌تواند برای وظایف برنامه‌نویسی استفاده شود:

• تولید کد
• توضیح کد
• Refactoring
• رفع باگ
• تولید Unit Test
• تبدیل زبان برنامه‌نویسی
• بررسی Pull Request
• تحلیل Stack Trace
• طراحی API
• تولید مستندات

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

۵. ساخت AI Agent

Gemma 4 از Reasoning و Function Calling پشتیبانی می‌کند و می‌تواند هسته یک AI Agent باشد.

ساختار ساده Agent:

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

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

search_documents
get_customer
get_order_status
calculate_price
query_database
create_report
read_file
run_tests

۶. تحلیل اسناد

Gemma 4 برای این وظایف قابل استفاده است:

• خلاصه‌سازی گزارش
• پاسخ به سؤال درباره سند
• استخراج جدول
• استخراج موجودیت‌ها
• مقایسه دو قرارداد فنی
• تولید FAQ
• استخراج تصمیم‌ها
• تشخیص تناقض
• ساخت Knowledge Base
• تهیه گزارش مدیریتی

در محصولات سازمانی، استفاده از RAG معمولاً بهتر از ارسال همه اسناد در هر درخواست است.

۷. تولید محتوای ساختاریافته

مدل می‌تواند محتوا را در قالب مشخص تولید کند:

• JSON
• Markdown
• جدول
• FAQ
• توضیحات محصول
• عنوان و Meta Description
• Schema
• گزارش تحلیلی
• برنامه اجرایی
• داده قابل ورود به CMS

تمام خروجی‌های ساختاریافته باید در Backend اعتبارسنجی شوند.

۸. Edge AI و اجرای Local

یکی از تفاوت‌های مهم Gemma با بسیاری از مدل‌های Cloud، امکان اجرای نسخه‌های کوچک‌تر روی سخت‌افزار شخصی است.

پلتفرم‌های هدف می‌توانند شامل این موارد باشند:

• Android
• iOS
• Windows
• macOS
• Linux
• مرورگر با WebGPU
• Raspberry Pi
• دستگاه‌های Edge
• سیستم‌های IoT

در اجرای Local، توسعه‌دهنده باید مسئولیت موارد زیر را بر عهده بگیرد:

• انتخاب Quantization
• مدیریت RAM و VRAM
• نصب Runtime
• بهینه‌سازی سرعت
• به‌روزرسانی مدل
• مانیتورینگ
• مدیریت Context
• سازگاری سخت‌افزار

اگر نمی‌خواهید زیرساخت استنتاج را مدیریت کنید، استفاده از API درواره راه ساده‌تری است.

۹. معماری Hybrid Local و Cloud

در برخی محصولات می‌توان نسخه کوچک Gemma را روی دستگاه اجرا کرد و وظایف پیچیده را به مدل Cloud فرستاد.

برای مثال:

Local

• تشخیص Intent
• بازنویسی کوتاه
• خلاصه‌سازی محدود
• پردازش اطلاعات دستگاه
• قابلیت‌های Offline

Cloud

• Reasoning پیچیده
• تحلیل اسناد طولانی
• پردازش چندمرحله‌ای
• Agent Tool Calling
• تولید خروجی طولانی
• بررسی نهایی

این معماری می‌تواند Latency و مصرف API را کاهش دهد.

تفاوت نسخه‌های 12B، 26B-A4B و 31B

نسخه 31B برای کاربردهای Cloud و وظایف پیچیده‌تر انتخاب مناسبی است. نسخه 12B برای Multimodal و اجرای روی سخت‌افزار متوسط جذاب‌تر است. نسخه MoE می‌تواند تعادل خوبی میان سرعت و کیفیت ایجاد کند.

مزایای Gemma 4

خانواده متنوع مدل‌ها

توسعه‌دهنده می‌تواند نسخه مناسب Edge، Local یا Cloud را انتخاب کند.

ورودی چندوجهی

متن و تصویر در تمام خانواده و Audio در برخی نسخه‌ها پشتیبانی می‌شوند.

پشتیبانی از Reasoning

Thinking Mode برای وظایف پیچیده قابل استفاده است.

Function Calling

مدل می‌تواند در Workflowهای Agentic ابزار مناسب را انتخاب کند.

Context طولانی

Context تا 256K برای اسناد، Agent و کدهای بزرگ مفید است.

پشتیبانی چندزبانه

بیش از ۱۴۰ زبان، از جمله فارسی، در دامنه پشتیبانی مدل قرار می‌گیرند.

امکان اجرای Local

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

مناسب Fine-Tuning

در صورت داشتن داده و زیرساخت، مدل‌های Gemma را می‌توان برای کاربردهای اختصاصی شخصی‌سازی کرد.

محدودیت‌های Gemma 4

نسخه‌های کوچک‌تر برای همه وظایف مناسب نیستند

مدل Edge ممکن است در Reasoning پیچیده یا برنامه‌نویسی سطح پروژه عملکرد مدل بزرگ‌تر را نداشته باشد.

تفاوت قابلیت میان نسخه‌ها

همه مدل‌های Gemma 4 دقیقاً Modalities یکسانی ندارند. برای مثال، Audio فقط در برخی نسخه‌ها وجود دارد.

نیاز به سخت‌افزار برای اجرای Local

Open Weight بودن به معنی اجرای آسان روی هر دستگاه نیست. نسخه، Quantization و Runtime باید متناسب با سخت‌افزار انتخاب شوند.

احتمال Hallucination

مدل ممکن است اطلاعات غیرواقعی، API اشتباه یا تحلیل ناقص تولید کند.

Context بزرگ هزینه دارد

ارسال ورودی طولانی باعث افزایش هزینه و زمان پردازش می‌شود.

نیاز به Evaluation فارسی

پشتیبانی از زبان فارسی باید با Promptها و داده واقعی محصول ارزیابی شود.

استفاده از Gemma 4 با API درواره

برای شروع:

1. وارد درواره شوید.
2. ثبت‌نام کنید.
3. API Key بسازید.
4. مدل Gemma 4 را در صفحه مدل‌ها پیدا کنید.
5. درخواست را از Backend ارسال کنید.

تنظیمات نمونه:

Base URL: https://api.darvareh.ir/v1
Model ID درواره: google/gemma-4-31b-it

کلید API را در 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": "google/gemma-4-31b-it",
    "messages": [
      {
        "role": "system",
        "content": "You are a precise Persian AI assistant. Separate facts from assumptions."
      },
      {
        "role": "user",
        "content": "یک برنامه عملی برای اضافه‌کردن قابلیت جست‌وجوی هوشمند به فروشگاه اینترنتی بنویس."
      }
    ],
    "temperature": 0.3,
    "max_tokens": 3000
  }'

اتصال Gemma 4 به Python

نصب SDK:

pip install openai

قرار دادن API Key در متغیر محیطی:

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="google/gemma-4-31b-it",
    messages=[
        {
            "role": "system",
            "content": """
تو یک مهندس ارشد Python هستی.
راه‌حل‌ها باید عملی، تست‌پذیر و قابل نگهداری باشند.
فرضیات را صریح مشخص کن.
"""
        },
        {
            "role": "user",
            "content": """
برای FastAPI یک سرویس جست‌وجوی محصول طراحی کن.

نیازمندی‌ها:
- PostgreSQL
- فیلتر و مرتب‌سازی
- Pagination
- Validation
- Cache با Redis
- Unit Test
- Structured Error Response
"""
        }
    ],
    temperature=0.2,
    max_tokens=5000
)

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

اتصال Gemma 4 به JavaScript

نصب پکیج:

npm install openai

نمونه Node.js:

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: "google/gemma-4-31b-it",
  messages: [
    {
      role: "system",
      content:
        "You are a senior TypeScript engineer. Produce explicit and testable solutions.",
    },
    {
      role: "user",
      content: `
یک API با NestJS طراحی کن که بازخورد کاربران را
دسته‌بندی و خلاصه کند.

نیازمندی‌ها:
- input validation
- batch processing
- retry
- structured JSON output
- logging
- tests with Vitest
      `,
    },
  ],
  temperature: 0.2,
  max_tokens: 4000,
});

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

استفاده از Streaming

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="google/gemma-4-31b-it",
    messages=[
        {
            "role": "user",
            "content": (
                "یک راهنمای جامع برای مهاجرت REST API "
                "از JavaScript به TypeScript بنویس."
            )
        }
    ],
    temperature=0.2,
    max_tokens=5000,
    stream=True
)

for chunk in stream:
    content = chunk.choices[0].delta.content

    if content:
        print(content, end="", flush=True)

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

ارسال تصویر به Gemma 4

برای نسخه‌ای که Vision آن در مسیر API فعال است، می‌توان تصویر را همراه Prompt ارسال کرد.

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="google/gemma-4-31b-it",
    messages=[
        {
            "role": "system",
            "content": (
                "You are a senior frontend engineer "
                "and accessibility reviewer."
            )
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": """
این Screenshot را بررسی کن و موارد زیر را بنویس:
1. اجزای اصلی رابط کاربری
2. Component Tree پیشنهادی
3. مشکلات Responsive
4. مشکلات Accessibility قابل مشاهده
5. اطلاعاتی که از روی تصویر قابل تشخیص نیست
"""
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/dashboard.png"
                    }
                }
            ]
        }
    ],
    temperature=0.2,
    max_tokens=3000
)

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

برای فایل Local می‌توان در مسیرهای پشتیبانی‌شده از Data URL و Base64 استفاده کرد. فرمت دقیق و محدودیت اندازه تصویر را برای نسخه فعال بررسی کنید.

ارسال تصویر Base64

import base64
import os
from pathlib import Path
from openai import OpenAI

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

image_path = Path("dashboard.png")
image_base64 = base64.b64encode(
    image_path.read_bytes()
).decode("utf-8")

response = client.chat.completions.create(
    model="google/gemma-4-31b-it",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": (
                        "این رابط کاربری را تحلیل و "
                        "مشکلات UX قابل مشاهده را فهرست کن."
                    )
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": (
                            "data:image/png;base64,"
                            f"{image_base64}"
                        )
                    }
                }
            ]
        }
    ],
    temperature=0.2,
    max_tokens=3000
)

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

پیش از استفاده، پشتیبانی Base64 را در مسیر API مدل بررسی کنید.

Tool Calling با Gemma 4

نمونه تعریف ابزار وضعیت سفارش:

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_order_status",
            "description": (
                "Get the current status of a customer order."
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "order_id": {
                        "type": "string",
                        "description": "The order identifier"
                    }
                },
                "required": ["order_id"],
                "additionalProperties": False
            }
        }
    }
]

فراخوانی مدل:

response = client.chat.completions.create(
    model="google/gemma-4-31b-it",
    messages=[
        {
            "role": "system",
            "content": """
تو دستیار پیگیری سفارش هستی.

قوانین:
- وضعیت سفارش را حدس نزن.
- برای اطلاعات فعلی از ابزار استفاده کن.
- شماره سفارش را قبل از Tool Call بررسی کن.
- اگر شماره وجود ندارد، از کاربر سؤال کن.
"""
        },
        {
            "role": "user",
            "content": "سفارش 8214 من الان کجاست؟"
        }
    ],
    tools=tools,
    tool_choice="auto",
    temperature=0.1
)

Backend باید tool_calls را بررسی و Function واقعی را اجرا کند.

حلقه کامل Function Calling

import json
import os
from openai import OpenAI

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


def get_order_status(order_id: str) -> dict:
    # در پروژه واقعی، اطلاعات از Database
    # یا سرویس سفارش دریافت می‌شود.
    return {
        "order_id": order_id,
        "status": "shipped",
        "tracking_code": "TRK-78421",
        "estimated_delivery": "2026-07-22"
    }


tools = [
    {
        "type": "function",
        "function": {
            "name": "get_order_status",
            "description": "Get current order status.",
            "parameters": {
                "type": "object",
                "properties": {
                    "order_id": {"type": "string"}
                },
                "required": ["order_id"],
                "additionalProperties": False
            }
        }
    }
]

handlers = {
    "get_order_status": get_order_status
}

messages = [
    {
        "role": "system",
        "content": (
            "Use tools for current order information. "
            "Do not invent status or delivery dates."
        )
    },
    {
        "role": "user",
        "content": "وضعیت سفارش 8214 را بررسی کن."
    }
]

for step in range(5):
    response = client.chat.completions.create(
        model="google/gemma-4-31b-it",
        messages=messages,
        tools=tools,
        tool_choice="auto",
        temperature=0.1,
        max_tokens=1500
    )

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

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

    for call in assistant_message.tool_calls:
        try:
            name = call.function.name
            arguments = json.loads(
                call.function.arguments
            )
            result = handlers[name](**arguments)
        except Exception as exc:
            result = {
                "ok": False,
                "error": str(exc)
            }

        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(
                result,
                ensure_ascii=False
            )
        })
else:
    raise RuntimeError("Agent reached maximum steps")

ساخت دستیار تحلیل تصویر

یک API ساده FastAPI می‌تواند URL تصویر و سؤال کاربر را دریافت کند.

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

app = FastAPI(title="Gemma Vision API")

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


class ImageRequest(BaseModel):
    image_url: HttpUrl
    question: str = Field(
        min_length=3,
        max_length=2000
    )


class ImageResponse(BaseModel):
    answer: str


@app.post(
    "/analyze-image",
    response_model=ImageResponse
)
def analyze_image(
    payload: ImageRequest
) -> ImageResponse:
    try:
        result = client.chat.completions.create(
            model="google/gemma-4-31b-it",
            messages=[
                {
                    "role": "system",
                    "content": (
                        "Analyze only visible evidence. "
                        "Separate observations from inferences."
                    )
                },
                {
                    "role": "user",
                    "content": [
                        {
                            "type": "text",
                            "text": payload.question
                        },
                        {
                            "type": "image_url",
                            "image_url": {
                                "url": str(payload.image_url)
                            }
                        }
                    ]
                }
            ],
            temperature=0.1,
            max_tokens=2500
        )
    except Exception as exc:
        raise HTTPException(
            status_code=502,
            detail="Model request failed"
        ) from exc

    return ImageResponse(
        answer=(
            result.choices[0].message.content or ""
        )
    )

در Production باید URL ورودی، اندازه تصویر، Timeout و نوع Content را کنترل کنید.

پرامپت‌نویسی برای Gemma 4

Prompt مناسب بهتر است شامل شش قسمت باشد.

نقش

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

هدف

علت ایجاد سفارش تکراری را پیدا کن و راه‌حل ارائه بده.

Context

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

محدودیت‌ها

قرارداد API تغییر نکند.
Dependency جدید اضافه نشود.

معیار پذیرش

برای هر Event ID فقط یک سفارش ایجاد شود.
اجرای هم‌زمان با تست بررسی شود.

فرمت خروجی

1. فرضیات
2. علت‌های احتمالی
3. راه‌حل پیشنهادی
4. کد
5. تست
6. ریسک‌های باقی‌مانده

Prompt مناسب تحلیل تصویر

این Screenshot مربوط به Dashboard مالی است.

وظیفه:
- ساختار صفحه را تحلیل کن.
- اجزای اصلی را فهرست کن.
- مشکلات خوانایی را مشخص کن.
- مشکلات Responsive قابل مشاهده را توضیح بده.
- Component Tree برای React پیشنهاد بده.
- حالت‌های Loading، Error و Empty را اضافه کن.

قوانین:
- چیزی را که در تصویر دیده نمی‌شود قطعی اعلام نکن.
- Observation را از Inference جدا کن.
- برای موارد نامشخص مقدار Confidence بده.

Prompt مناسب Code Review

این کد را به‌عنوان Senior Code Reviewer بررسی کن.

تمرکز:
- correctness
- maintainability
- performance
- concurrency
- testability
- error handling

قوانین:
- فقط مشکل قابل اثبات را گزارش کن.
- تغییر سلیقه‌ای را Bug اعلام نکن.
- Severity هر Finding را مشخص کن.
- برای هر مشکل راه‌حل عملی ارائه بده.
- اگر Context کافی نیست، اطلاعات لازم را بپرس.

تنظیم Temperature

این مقادیر نقطه شروع هستند و باید روی داده واقعی ارزیابی شوند.

Structured Output

برای پردازش خودکار، پاسخ را در قالب JSON تعریف کنید.

نمونه Schema تحلیل بازخورد:

{
  "language": "fa",
  "sentiment": "positive | neutral | negative",
  "category": "string",
  "summary": "string",
  "urgency": "low | medium | high",
  "action_items": [
    "string"
  ]
}

خروجی مدل را با Pydantic، Zod یا JSON Schema Validator بررسی کنید. پشتیبانی Response Format را برای نسخه فعال مدل در درواره کنترل کنید.

Validation با Pydantic

from typing import Literal
from pydantic import BaseModel


class FeedbackResult(BaseModel):
    language: str
    sentiment: Literal[
        "positive",
        "neutral",
        "negative"
    ]
    category: str
    summary: str
    urgency: Literal[
        "low",
        "medium",
        "high"
    ]
    action_items: list[str]

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

استفاده از Gemma 4 در سیستم RAG

Gemma 4 می‌تواند مدل تولیدکننده پاسخ در معماری RAG باشد.

جریان RAG:

سؤال کاربر
ساخت Query
جست‌وجوی اسناد
Hybrid Search
Reranking
ساخت Context
ارسال به Gemma 4
تولید پاسخ همراه با منابع

System Prompt پیشنهادی:

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

حتی با Context 256K بهتر است فقط اسناد مرتبط پس از Retrieval و Reranking وارد Prompt شوند.

مدیریت Context

Context را به چهار بخش تقسیم کنید:

دستور ثابت

• نقش
• قواعد
• محدودیت‌ها
• فرمت پاسخ

درخواست جاری

• سؤال
• هدف
• معیار پذیرش

شواهد

• اسناد
• تصویر
• خروجی ابزار
• محتوای فایل

State

• مراحل قبلی
• تصمیم‌ها
• خطاهای حل‌نشده
• اقدام بعدی

اطلاعات تکراری و خروجی ابزارهای قدیمی را خلاصه کنید.

معماری Production پیشنهادی

Backend API

کلید API را نگهداری و درخواست کاربر را اعتبارسنجی می‌کند.

Model Router

براساس نوع وظیفه، نسخه مناسب Gemma یا مدل دیگری را انتخاب می‌کند.

Media Processor

تصویر و Audio را از نظر اندازه، نوع و دسترسی آماده می‌کند.

Context Builder

Prompt، اسناد و تاریخچه را به درخواست نهایی تبدیل می‌کند.

Tool Executor

Function Callها را اعتبارسنجی و اجرا می‌کند.

Output Validator

ساختار و معیارهای پاسخ را بررسی می‌کند.

Observability

موارد زیر را ثبت می‌کند:

• Latency
• Token ورودی
• Token خروجی
• هزینه
• نرخ خطا
• تعداد Tool Call
• کیفیت پاسخ
• Model ID

Model Routing میان نسخه‌های Gemma 4

def select_gemma_model(task: dict) -> str:
    if task.get("requires_high_quality_reasoning"):
        return "google/gemma-4-31b-it"

    if task.get("requires_audio"):
        return "YOUR_GEMMA_4_12B_MODEL_ID"

    if task.get("requires_local_execution"):
        return "YOUR_LOCAL_GEMMA_MODEL"

    if task.get("requires_low_latency"):
        return "YOUR_LIGHTWEIGHT_GEMMA_MODEL_ID"

    return "google/gemma-4-31b-it"

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

کنترل هزینه API

• مدل را متناسب با پیچیدگی انتخاب کنید.
• درخواست ساده را به نسخه کوچک‌تر Route کنید.
• تصاویر را با وضوح غیرضروری ارسال نکنید.
• Context تکراری را Cache کنید.
• خروجی‌های قدیمی ابزار را خلاصه کنید.
• max_tokens را بیش از نیاز بالا نبرید.
• تعداد مراحل Agent را محدود کنید.
• از RAG و Reranking استفاده کنید.
• درخواست تکراری را دوباره پردازش نکنید.
• هزینه هر قابلیت را جداگانه ثبت کنید.

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

Evaluation مدل Gemma 4

پیش از استفاده Production، یک مجموعه تست از داده واقعی محصول بسازید.

ارزیابی فارسی

• درک سؤال فارسی
• کیفیت نگارش
• رعایت نیم‌فاصله و علائم
• استخراج موجودیت فارسی
• مدیریت ترکیب فارسی و English
• خلاصه‌سازی
• پاسخ به سؤال
• پایداری JSON

ارزیابی تصویر

• تشخیص اجزا
• استخراج متن
• تحلیل نمودار
• پاسخ به سؤال
• تشخیص اطلاعات ناموجود
• تفکیک مشاهده از حدس

ارزیابی Coding

• صحت کد
• پاس‌شدن تست‌ها
• نرخ API غیرواقعی
• رعایت محدودیت‌ها
• کیفیت Error Handling
• تغییرات غیرضروری

ارزیابی Agent

• انتخاب ابزار
• صحت آرگومان
• تعداد Tool Call
• مدیریت خطا
• حفظ هدف
• تشخیص پایان کار
• هزینه هر وظیفه موفق

اشتباهات رایج

یکسان فرض‌کردن تمام نسخه‌های Gemma 4

Modalities، Context و منابع سخت‌افزاری نسخه‌ها متفاوت است.

استفاده از مدل بزرگ برای درخواست ساده

Model Routing می‌تواند هزینه و Latency را کاهش دهد.

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

مدل را با داده واقعی فارسی محصول خود ارزیابی کنید.

استفاده از تمام Context بدون فیلتر

Context بزرگ جایگزین Retrieval و انتخاب اطلاعات مرتبط نیست.

اجرای مستقیم Function Call

نام ابزار، آرگومان و مجوز کاربر باید بررسی شوند.

ادعای اجرای تست توسط مدل

فقط خروجی واقعی ابزار تست معتبر است.

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

API Key باید فقط در Backend ذخیره شود.

فرض پشتیبانی Audio در تمام نسخه‌ها

Audio فقط در نسخه‌های مشخصی از خانواده Gemma 4 پشتیبانی می‌شود.

پرسش‌های متداول درباره Gemma 4

Gemma 4 چیست؟

Gemma 4 خانواده‌ای از مدل‌های Open Weight شرکت Google DeepMind برای متن، تصویر، Reasoning، برنامه‌نویسی، Function Calling و پردازش چندوجهی است.

Gemma 4 چه تفاوتی با Gemini دارد؟

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

آیا Gemma 4 از زبان فارسی پشتیبانی می‌کند؟

بله. Gemma 4 بیش از ۱۴۰ زبان را پشتیبانی می‌کند، اما کیفیت فارسی باید روی کاربرد واقعی ارزیابی شود.

آیا Gemma 4 تصویر را تحلیل می‌کند؟

بله. مدل‌های اصلی Gemma 4 می‌توانند ورودی متن و تصویر دریافت کنند و پاسخ متنی تولید کنند.

آیا Gemma 4 از صدا پشتیبانی می‌کند؟

نسخه‌های E2B، E4B و 12B قابلیت ورودی Audio دارند. وضعیت این قابلیت را برای مسیر API فعال بررسی کنید.

آیا Gemma 4 ویدئو را پردازش می‌کند؟

برخی نسخه‌ها و Runtimeهای این خانواده قابلیت پردازش ویدئو دارند. پشتیبانی دقیق در API به Model ID و مسیر ارائه وابسته است.

Context Window مدل Gemma 4 چقدر است؟

مدل‌های کوچک‌تر معمولاً 128K و نسخه‌های متوسط و بزرگ‌تر تا حدود 256K Context دارند.

آیا Gemma 4 برای برنامه‌نویسی مناسب است؟

بله. تولید کد، Refactoring، رفع باگ، تولید تست و تحلیل Repository از کاربردهای آن هستند.

آیا Gemma 4 برای AI Agent مناسب است؟

بله. Thinking Mode و Function Calling امکان استفاده از آن در Agentهای متصل به ابزار را فراهم می‌کنند.

Model ID درواره چیست؟

برای نسخه 31B:

google/gemma-4-31b-it

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

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

https://api.darvareh.ir/v1

آیا می‌توان Gemma 4 را با Python استفاده کرد؟

بله. با تنظیم Base URL و API Key درواره می‌توانید آن را از Backend پایتون فراخوانی کنید.

آیا Gemma 4 در Node.js قابل استفاده است؟

بله. API سازگار درواره را می‌توان با JavaScript و TypeScript فراخوانی کرد.

آیا می‌توان Gemma 4 را روی کامپیوتر شخصی اجرا کرد؟

بله، برخی نسخه‌ها با Runtime و Quantization مناسب قابل اجرای Local هستند. سخت‌افزار لازم به اندازه مدل و دقت وزن‌ها وابسته است.

قیمت Gemma 4 چقدر است؟

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

جمع‌بندی

Gemma 4 یکی از منعطف‌ترین خانواده‌های مدل هوش مصنوعی Google برای توسعه‌دهندگان است. این خانواده نسخه‌هایی برای Cloud، لپ‌تاپ، موبایل، مرورگر و Edge ارائه می‌دهد و از قابلیت‌هایی مانند متن، تصویر، Audio، Reasoning، Function Calling و Context طولانی پشتیبانی می‌کند.

مهم‌ترین ویژگی‌های Gemma 4 عبارت‌اند از:

• مدل‌های متنوع از E2B تا 31B
• نسخه Dense و Mixture of Experts
• پردازش متن و تصویر
• پشتیبانی Audio در نسخه‌های منتخب
• Thinking Mode
• Function Calling
• Context تا 256K
• پشتیبانی از بیش از ۱۴۰ زبان
• امکان اجرای Local
• مناسب برای Coding و AI Agent

برای انتخاب نسخه مناسب باید کیفیت، Modalities، Context، سرعت، هزینه و محل استقرار را هم‌زمان بررسی کنید.

برای شروع استفاده از نسخه Cloud:

1. در درواره ثبت‌نام کنید.
2. API Key دریافت کنید.
3. نسخه‌های فعال Gemma 4 را در صفحه مدل‌ها ببینید.
4. Base URL را روی https://api.darvareh.ir/v1 قرار دهید.
5. برای نسخه 31B از Model ID درواره یعنی google/gemma-4-31b-it استفاده کنید.
6. مدل را روی داده‌های واقعی فارسی و وظایف محصول ارزیابی کنید.
7. برای کنترل هزینه از Model Routing استفاده کنید.

مقالات مرتبط

• راهنمای جامع مدل‌های هوش مصنوعی و انتخاب مدل مناسب
• راهنمای کامل Google Gemini
• راهنمای کامل Gemini 3.5
• بهترین مدل‌های هوش مصنوعی برای برنامه‌نویسی
• راهنمای کامل AI Agent
• راهنمای AI Agent، ابزارها، Skills و MCP
• آموزش Function Calling در مدل‌های هوش مصنوعی
• راهنمای Tool Calling برای اتصال مدل به ابزارها
• Context Window چیست و چگونه مدیریت می‌شود؟
• راهنمای خروجی ساختاریافته در API هوش مصنوعی
• ساخت RAG با LangChain و LlamaIndex
• راهنمای اتصال مدل‌های هوش مصنوعی به Open WebUI
• معماری چندمدلی و چندارائه‌دهنده هوش مصنوعی
• آموزش اتصال API هوش مصنوعی به اپلیکیشن