راهنمای توسعه‌دهندگان جمینی ۳

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

تفکر بالا/پویا تفکر پایین

Gemini 3 Pro به طور پیش‌فرض از تفکر پویا برای استدلال از طریق دستورات استفاده می‌کند. برای پاسخ‌های سریع‌تر و با تأخیر کمتر، زمانی که استدلال پیچیده‌ای لازم نیست، می‌توانید سطح تفکر مدل را به low محدود کنید.

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="Find the race condition in this multi-threaded C++ snippet: [code here]",
)

print(response.text)

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents="Find the race condition in this multi-threaded C++ snippet: [code here]",
  });

  console.log(response.text);
}

run();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Find the race condition in this multi-threaded C++ snippet: [code here]"}]
    }]
  }'

کاوش

مجموعه برنامه‌های Gemini 3 ما را بررسی کنید تا ببینید که چگونه این مدل، استدلال پیشرفته، کدنویسی خودکار و وظایف پیچیده چندوجهی را مدیریت می‌کند.

با جمینی ۳ آشنا شوید

Gemini 3 Pro اولین مدل از سری جدید است. gemini-3-pro-preview برای کارهای پیچیده شما که نیاز به دانش جهانی گسترده و استدلال پیشرفته در زمینه‌های مختلف دارند، بهترین گزینه است.

* قیمت‌ها به ازای هر ۱ میلیون توکن است. قیمت‌های ذکر شده برای متن استاندارد است؛ نرخ ورودی چندوجهی ممکن است متفاوت باشد.

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

ویژگی‌های جدید API در Gemini 3

Gemini 3 پارامترهای جدیدی را معرفی می‌کند که برای کنترل بیشتر توسعه‌دهندگان بر تأخیر، هزینه و وفاداری چندوجهی طراحی شده‌اند.

سطح تفکر

پارامتر thinking_level حداکثر عمق فرآیند استدلال درونی مدل را قبل از تولید پاسخ کنترل می‌کند. Gemini 3 این سطوح را به عنوان مقادیر نسبی مجاز برای تفکر در نظر می‌گیرد، نه به عنوان تضمین‌های دقیق توکن. اگر thinking_level مشخص نشده باشد، Gemini 3 Pro به طور پیش‌فرض روی high قرار می‌گیرد.

• low : تأخیر و هزینه را به حداقل می‌رساند. بهترین گزینه برای دنبال کردن دستورالعمل‌های ساده، چت یا برنامه‌های کاربردی با توان عملیاتی بالا.
• medium : (به زودی)، در زمان عرضه پشتیبانی نمی‌شود
• high (پیش‌فرض): عمق استدلال را به حداکثر می‌رساند. ممکن است مدل برای رسیدن به اولین نشانه به طور قابل توجهی زمان بیشتری صرف کند، اما خروجی با دقت بیشتری استدلال خواهد شد.

وضوح رسانه

Gemini 3 از طریق پارامتر media_resolution کنترل دقیقی بر پردازش بینایی چندوجهی ارائه می‌دهد. وضوح بالاتر، توانایی مدل را در خواندن متن‌های ریز یا شناسایی جزئیات کوچک بهبود می‌بخشد، اما استفاده از توکن و تأخیر را افزایش می‌دهد. پارامتر media_resolution حداکثر تعداد توکن‌های اختصاص داده شده به ازای هر تصویر یا فریم ویدیویی ورودی را تعیین می‌کند.

اکنون می‌توانید وضوح را برای هر بخش رسانه‌ای جداگانه یا به صورت کلی (از طریق generation_config ) روی media_resolution_low ، media_resolution_medium یا media_resolution_high تنظیم کنید. در صورت عدم تعیین مقدار، مدل بر اساس نوع رسانه از مقادیر پیش‌فرض بهینه استفاده می‌کند.

تنظیمات توصیه شده

from google import genai
from google.genai import types
import base64

# The media_resolution parameter is currently only available in the v1alpha API version.
client = genai.Client(http_options={'api_version': 'v1alpha'})

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents=[
        types.Content(
            parts=[
                types.Part(text="What is in this image?"),
                types.Part(
                    inline_data=types.Blob(
                        mime_type="image/jpeg",
                        data=base64.b64decode("..."),
                    ),
                    media_resolution={"level": "media_resolution_high"}
                )
            ]
        )
    ]
)

print(response.text)

import { GoogleGenAI } from "@google/genai";

// The media_resolution parameter is currently only available in the v1alpha API version.
const ai = new GoogleGenAI({ apiVersion: "v1alpha" });

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: [
      {
        parts: [
          { text: "What is in this image?" },
          {
            inlineData: {
              mimeType: "image/jpeg",
              data: "...",
            },
            mediaResolution: {
              level: "media_resolution_high"
            }
          }
        ]
      }
    ]
  });

  console.log(response.text);
}

run();

curl "https://generativelanguage.googleapis.com/v1alpha/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [
        { "text": "What is in this image?" },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "..."
          },
          "mediaResolution": {
            "level": "media_resolution_high"
          }
        }
      ]
    }]
  }'

دما

برای Gemini 3، اکیداً توصیه می‌کنیم پارامتر دما را در مقدار پیش‌فرض 1.0 نگه دارید.

در حالی که مدل‌های قبلی اغلب از تنظیم دما برای کنترل خلاقیت در مقابل جبرگرایی بهره می‌بردند، قابلیت‌های استدلال Gemini 3 برای تنظیم پیش‌فرض بهینه شده‌اند. تغییر دما (تنظیم آن زیر ۱.۰) ممکن است منجر به رفتار غیرمنتظره‌ای مانند حلقه زدن یا کاهش عملکرد، به ویژه در کارهای پیچیده ریاضی یا استدلالی شود.

امضاهای فکری

Gemini 3 از امضاهای فکری برای حفظ زمینه استدلال در طول فراخوانی‌های API استفاده می‌کند. این امضاها، نمایش‌های رمزگذاری‌شده از فرآیند تفکر داخلی مدل هستند. برای اطمینان از اینکه مدل قابلیت‌های استدلال خود را حفظ می‌کند، باید این امضاها را دقیقاً همانطور که دریافت شده‌اند، در درخواست خود به مدل برگردانید:

• فراخوانی تابع (دقیق): API اعتبارسنجی دقیقی را روی "نوبت فعلی" اعمال می‌کند. فقدان امضاها منجر به خطای ۴۰۰ خواهد شد.
• متن/چت: اعتبارسنجی به طور جدی اجرا نمی‌شود، اما حذف امضاها باعث کاهش کیفیت استدلال و پاسخ مدل می‌شود.

فراخوانی تابع (اعتبارسنجی دقیق)

وقتی Gemini یک functionCall تولید می‌کند، برای پردازش صحیح خروجی ابزار در نوبت بعدی به thoughtSignature متکی است. "نوبت فعلی" شامل تمام مراحل Model ( functionCall ) و User ( functionResponse ) است که از آخرین پیام text استاندارد User رخ داده‌اند.

• فراخوانی تک‌تابع: بخش functionCall شامل یک امضا است. شما باید آن را برگردانید.
• فراخوانی‌های موازی تابع: فقط اولین بخش functionCall در لیست شامل امضا خواهد بود. شما باید بخش‌ها را دقیقاً به ترتیب دریافت شده برگردانید.
• چند مرحله‌ای (ترتیبی): اگر مدل یک ابزار را فراخوانی کند، نتیجه‌ای را دریافت کند و ابزار دیگری را (در همان نوبت) فراخوانی کند، هر دو فراخوانی تابع دارای امضا هستند. شما باید تمام امضاهای انباشته شده در تاریخچه را برگردانید.

متن و پخش جریانی

برای چت یا تولید متن استاندارد، وجود امضا تضمین نمی‌شود.

• غیر-جریانی : بخش پایانی محتوای پاسخ ممکن است حاوی یک thoughtSignature باشد، هرچند که همیشه وجود ندارد. اگر چنین چیزی برگردانده شود، باید آن را برای حفظ بهترین عملکرد، دوباره ارسال کنید.
• جریان‌سازی : اگر امضایی تولید شود، ممکن است در یک بخش نهایی که حاوی یک بخش متنی خالی است، دریافت شود. مطمئن شوید که تجزیه‌گر جریان شما حتی اگر فیلد متنی خالی باشد، امضاها را بررسی می‌کند.

مثال‌های کد

// Model Response (Turn 1, Step 1)
  {
    "role": "model",
    "parts": [
      {
        "functionCall": { "name": "check_flight", "args": {...} },
        "thoughtSignature": "<Sig_A>" // SAVE THIS
      }
    ]
  }

// User Request (Turn 1, Step 2)
[
  { "role": "user", "parts": [{ "text": "Check flight AA100..." }] },
  { 
    "role": "model", 
    "parts": [
      { 
        "functionCall": { "name": "check_flight", "args": {...} }, 
        "thoughtSignature": "<Sig_A>" // REQUIRED
      } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": { "name": "check_flight", "response": {...} } }] }
]

// Model Response (Turn 1, Step 3)
{
  "role": "model",
  "parts": [
    {
      "functionCall": { "name": "book_taxi", "args": {...} },
      "thoughtSignature": "<Sig_B>" // SAVE THIS
    }
  ]
}

// User Request (Turn 1, Step 4)
[
  // ... previous history ...
  { 
    "role": "model", 
    "parts": [
       { "functionCall": { "name": "check_flight", ... }, "thoughtSignature": "<Sig_A>" } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": {...} }] },
  { 
    "role": "model", 
    "parts": [
       { "functionCall": { "name": "book_taxi", ... }, "thoughtSignature": "<Sig_B>" } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": {...} }] }
]

// User Request (Sending Parallel Results)
[
  {
    "role": "user",
    "parts": [
      { "text": "Check the weather in Paris and London." }
    ]
  },
  {
    "role": "model",
    "parts": [
      // 1. First Function Call has the signature
      {
        "functionCall": { "name": "check_weather", "args": { "city": "Paris" } },
        "thoughtSignature": "<Signature_A>" 
      },
      // 2. Subsequent parallel calls DO NOT have signatures
      {
        "functionCall": { "name": "check_weather", "args": { "city": "London" } }
      } 
    ]
  },
  {
    "role": "user",
    "parts": [
      // 3. Function Responses are grouped together in the next block
      {
        "functionResponse": { "name": "check_weather", "response": { "temp": "15C" } }
      },
      {
        "functionResponse": { "name": "check_weather", "response": { "temp": "12C" } }
      }
    ]
  }
]

// User Request (Follow-up question)
[
  { 
    "role": "user", 
    "parts": [{ "text": "What are the risks of this investment?" }] 
  },
  { 
    "role": "model", 
    "parts": [
      {
        "text": "I need to calculate the risk step-by-step. First, I'll look at volatility...",
        "thoughtSignature": "<Signature_C>" // Recommended to include
      }
    ]
  },
  { 
    "role": "user", 
    "parts": [{ "text": "Summarize that in one sentence." }] 
  }
]

مهاجرت از مدل‌های دیگر

اگر در حال انتقال یک رد مکالمه از مدل دیگری (مثلاً Gemini 2.5) هستید یا یک فراخوانی تابع سفارشی را که توسط Gemini 3 تولید نشده است، تزریق می‌کنید، امضای معتبری نخواهید داشت.

برای دور زدن اعتبارسنجی دقیق در این سناریوهای خاص، فیلد را با این رشته‌ی ساختگی خاص پر کنید: "thoughtSignature": "context_engineering_is_the_way_to_go"

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

Gemini 3 به شما امکان می‌دهد خروجی‌های ساختاریافته را با ابزارهای داخلی، از جمله Grounding with Google Search ، URL Context و Code Execution، ترکیب کنید.

from google import genai
from google.genai import types
from pydantic import BaseModel, Field
from typing import List

class MatchResult(BaseModel):
    winner: str = Field(description="The name of the winner.")
    final_match_score: str = Field(description="The final match score.")
    scorers: List[str] = Field(description="The name of the scorer.")

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="Search for all details for the latest Euro.",
    config={
        "tools": [
            {"google_search": {}},
            {"url_context": {}}
        ],
        "response_mime_type": "application/json",
        "response_json_schema": MatchResult.model_json_schema(),
    },  
)

result = MatchResult.model_validate_json(response.text)
print(result)

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const ai = new GoogleGenAI({});

const matchSchema = z.object({
  winner: z.string().describe("The name of the winner."),
  final_match_score: z.string().describe("The final score."),
  scorers: z.array(z.string()).describe("The name of the scorer.")
});

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: "Search for all details for the latest Euro.",
    config: {
      tools: [
        { googleSearch: {} },
        { urlContext: {} }
      ],
      responseMimeType: "application/json",
      responseJsonSchema: zodToJsonSchema(matchSchema),
    },
  });

  const match = matchSchema.parse(JSON.parse(response.text));
  console.log(match);
}

run();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Search for all details for the latest Euro."}]
    }],
    "tools": [
      {"googleSearch": {}},
      {"urlContext": {}}
    ],
    "generationConfig": {
        "responseMimeType": "application/json",
        "responseJsonSchema": {
            "type": "object",
            "properties": {
                "winner": {"type": "string", "description": "The name of the winner."},
                "final_match_score": {"type": "string", "description": "The final score."},
                "scorers": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "The name of the scorer."
                }
            },
            "required": ["winner", "final_match_score", "scorers"]
        }
    }
  }'

مهاجرت از جمینی ۲.۵

Gemini 3 توانمندترین خانواده مدل ما تا به امروز است و نسبت به Gemini 2.5 Pro پیشرفت گام به گامی را ارائه می‌دهد. هنگام مهاجرت، موارد زیر را در نظر بگیرید:

• تفکر: اگر قبلاً از مهندسی پیچیده‌ی دستورالعمل‌ها (مانند زنجیره‌ی افکار) برای وادار کردن Gemini 2.5 به استدلال استفاده می‌کردید، Gemini 3 را با thinking_level: "high" و دستورالعمل‌های ساده‌شده امتحان کنید.
• تنظیمات دما: اگر کد موجود شما صریحاً دما را تنظیم می‌کند (به‌ویژه برای خروجی‌های قطعی روی مقادیر پایین)، توصیه می‌کنیم این پارامتر را حذف کرده و از مقدار پیش‌فرض ۱.۰ در Gemini 3 استفاده کنید تا از مشکلات احتمالی حلقه یا کاهش عملکرد در کارهای پیچیده جلوگیری شود.
• درک PDF و اسناد: وضوح پیش‌فرض OCR برای PDFها تغییر کرده است. اگر برای تجزیه و تحلیل متراکم اسناد به رفتار خاصی متکی بودید، تنظیم جدید media_resolution_high را آزمایش کنید تا از دقت مداوم آن اطمینان حاصل شود.
• مصرف توکن: مهاجرت به پیش‌فرض‌های Gemini 3 Pro ممکن است استفاده از توکن را برای فایل‌های PDF افزایش دهد اما استفاده از توکن را برای ویدیو کاهش دهد . اگر درخواست‌ها اکنون به دلیل وضوح پیش‌فرض بالاتر از پنجره زمینه فراتر می‌روند، توصیه می‌کنیم وضوح رسانه را به صراحت کاهش دهید.
• تقسیم‌بندی تصویر: قابلیت‌های تقسیم‌بندی تصویر (بازگرداندن ماسک‌های سطح پیکسل برای اشیاء) در Gemini 3 Pro پشتیبانی نمی‌شوند. برای بارهای کاری که نیاز به تقسیم‌بندی تصویر بومی دارند، توصیه می‌کنیم به استفاده از Gemini 2.5 Flash با خاموش بودن thinking یا Gemini Robotics-ER 1.5 ادامه دهید.

سازگاری با OpenAI

برای کاربرانی که از لایه سازگاری OpenAI استفاده می‌کنند، پارامترهای استاندارد به طور خودکار به معادل‌های Gemini نگاشت می‌شوند:

• reasoning_effort (OAI) به thinking_level (Gemini) نگاشت می‌شود. توجه داشته باشید که reasoning_effort متوسط ​​به thinking_level بالا نگاشت می‌شود.

ارائه بهترین شیوه‌ها

جمینی ۳ یک مدل استدلال است که نحوه‌ی ارائه‌ی پیشنهاد را تغییر می‌دهد.

• دستورالعمل‌های دقیق: در دستورالعمل‌های ورودی خود مختصر باشید. Gemini 3 به دستورالعمل‌های مستقیم و واضح بهترین پاسخ را می‌دهد. ممکن است تکنیک‌های مهندسی دستورالعمل طولانی یا بیش از حد پیچیده مورد استفاده در مدل‌های قدیمی را بیش از حد تجزیه و تحلیل کند.
• حجم خروجی: به طور پیش‌فرض، Gemini 3 کمتر حجم خروجی دارد و ترجیح می‌دهد پاسخ‌های مستقیم و کارآمد ارائه دهد. اگر مورد استفاده شما نیاز به یک شخصیت محاوره‌ای یا "پرحرف" دارد، باید صریحاً مدل را در اعلان هدایت کنید (مثلاً "این را به عنوان یک دستیار دوستانه و پرحرف توضیح دهید").
• مدیریت زمینه: هنگام کار با مجموعه داده‌های بزرگ (مثلاً کل کتاب‌ها، پایگاه‌های کد یا ویدیوهای طولانی)، دستورالعمل‌ها یا سوالات خاص خود را در انتهای دستور، پس از زمینه داده‌ها قرار دهید. با شروع سوال خود با عبارتی مانند «بر اساس اطلاعات بالا...»، استدلال مدل را به داده‌های ارائه شده متصل کنید.

در راهنمای مهندسی سریع، درباره استراتژی‌های طراحی سریع بیشتر بیاموزید.

سوالات متداول

1. حداقل دانش برای Gemini 3 Pro چقدر است؟ حداکثر دانش Gemini 3 ژانویه 2025 است. برای اطلاعات جدیدتر، از ابزار Search Grounding استفاده کنید.

2. محدودیت‌های پنجره زمینه چیست؟ جمینی ۳ پرو از یک پنجره زمینه ورودی ۱ میلیون توکن و تا ۶۴ هزار توکن خروجی پشتیبانی می‌کند.

3. آیا نسخه رایگانی برای Gemini 3 Pro وجود دارد؟ می‌توانید این مدل را به صورت رایگان در Google AI Studio امتحان کنید، اما در حال حاضر، هیچ نسخه رایگانی برای gemini-3-pro-preview در رابط برنامه‌نویسی کاربردی (API) Gemini در دسترس نیست.

4. آیا کد قدیمی thinking_budget من هنوز کار خواهد کرد؟ بله، thinking_budget هنوز برای سازگاری با نسخه‌های قبلی پشتیبانی می‌شود، اما برای عملکرد قابل پیش‌بینی‌تر، توصیه می‌کنیم به thinking_level مهاجرت کنید. از هر دو در یک درخواست استفاده نکنید.

5. آیا جمینی ۳ از Batch API پشتیبانی می‌کند؟ بله، جمینی ۳ از Batch API پشتیبانی می‌کند.

6. آیا از ذخیره‌سازی زمینه (Context Caching) پشتیبانی می‌شود؟ بله، ذخیره‌سازی زمینه برای Gemini 3 پشتیبانی می‌شود. حداقل تعداد توکن مورد نیاز برای شروع ذخیره‌سازی، 2048 توکن است.

7. کدام ابزارها در Gemini 3 پشتیبانی می‌شوند؟ Gemini 3 از جستجوی گوگل ، جستجوی فایل ، اجرای کد و متن URL پشتیبانی می‌کند. همچنین از فراخوانی تابع استاندارد برای ابزارهای سفارشی شما پشتیبانی می‌کند. لطفاً توجه داشته باشید که نقشه‌های گوگل و استفاده از رایانه در حال حاضر پشتیبانی نمی‌شوند.

مراحل بعدی

• با کتاب آشپزی Gemini 3 شروع کنید
• راهنمای اختصاصی کتاب آشپزی در مورد سطوح تفکر و نحوه مهاجرت از بودجه تفکر به سطوح تفکر را بررسی کنید.