راهنمای عیب‌یابی

از این راهنما برای کمک به تشخیص و رفع مشکلات رایجی که هنگام تماس با Gemini API پیش می‌آید استفاده کنید. ممکن است با مشکلاتی ازسوی سرویس زیرینه Gemini API یا کیت‌های توسعه نرم‌افزار کارخواه مواجه شوید. کیت‌های توسعه نرم‌افزار مشتری ما در مخازن زیر متن‌باز هستند:

اگر با مشکلات کلید API مواجه شدید، بررسی کنید که کلید API خود را مطابق با راهنمای تنظیم کلید API به‌درستی تنظیم کرده‌اید.

کدهای خطا

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

استراتژی امتحان مجدد

اگر خطایی دریافت کردید که نشان می‌دهد باید درخواستتان را دوباره امتحان کنید (مثل 429 RESOURCE_EXHAUSTED یا 503 UNAVAILABLE)، توصیه می‌کنیم استراتژی پس‌گیری نمایی را پیاده‌سازی کنید. یعنی قبل‌از اولین تلاش مجدد، مدت کوتاهی صبر می‌کنید و سپس زمان انتظار بین تلاش‌های مجدد بعدی را به‌تدریج افزایش می‌دهید.

کیت‌های توسعه نرم‌افزار مشتری رسمی برای Gemini API، مانند کیت توسعه نرم‌افزار Python، به‌طور پیش‌فرض شامل منطق تلاش مجدد خودکار با عقب‌نشینی نمایی برای مدیریت خطاهای گذرا مانند اتمام مهلت، مشکلات شبکه، و محدودیت‌های نرخ (کدهای وضعیت 429 و 5xx) هستند. برای مثال، «کیت توسعه نرم‌افزار Python» به‌طور خودکار خطاهای گذرا را تا چهار بار با تأخیر اولیه تقریباً ۱ ثانیه و حداکثر تأخیر ۶۰ ثانیه دوباره امتحان می‌کند.

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

  • استفاده از پس‌گرد نمایی: قبل‌از اولین تلاش مجدد، مدت کوتاهی صبر کنید (برای مثال، ۱ ثانیه)، سپس تأخیر را به‌صورت نمایی افزایش دهید (برای مثال، ۲ ثانیه، ۴ ثانیه، ۸ ثانیه).
  • افزودن لرزش: «لرزش» تصادفی به تأخیر اضافه کنید تا از تلاش مجدد همه کارخواه‌ها در یک زمان دقیق جلوگیری شود.
  • امتحان مجدد درصورت بروز خطاهای خاص: فقط درصورت بروز خطاهای موقت (مانند 429، 408، یا 5xx) دوباره امتحان کنید. درصورت بروز خطاهای کارخواه (مانند 400، 402، یا 403) دوباره امتحان نکنید زیرا این خطاها نشان‌دهنده مشکلاتی مانند کلیدهای API نامعتبر، تمام شدن اعتبار پیش‌پرداخت، یا نحو نادرست هستند.
  • تنظیم حداکثر تلاش مجدد: حداکثر تعداد تلاش مجدد را برای جلوگیری از حلقه‌های بی‌نهایت تعریف کنید.

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

بررسی کنید که پارامترهای مدل شما در محدوده مقادیر زیر باشد:

پارامتر مدل مقادیر (محدوده)
تعداد نامزدها ‫۱-۸ (عدد صحیح)
دما ۰٫۰-۱٫۰
بیشینه داده‌واحدهای برونداد از صفحه مدل‌ها برای تعیین حداکثر تعداد داده‌واحدها برای مدلی که استفاده می‌کنید استفاده کنید.
TopP ۰٫۰ تا ۱٫۰

علاوه‌بر بررسی مقادیر پارامتر، مطمئن شوید که از نسخه API صحیح (مثلاً /v1 یا /v1beta) و مدلی که از ویژگی‌های موردنیازتان پشتیبانی می‌کند استفاده می‌کنید. برای مثال، اگر ویژگی‌ای در نسخه «بتا» باشد، فقط در نسخه /v1beta API دردسترس خواهد بود.

بررسی کنید که مدل درست را داشته باشید

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

تأخیر بیشتر یا مصرف بیشتر توکن با مدل‌های اندیشگر

تأخیر بالاتر یا استفاده از نشان اغلب به‌دلیل این است که مدل‌های Gemini 3.x به‌طور پیش‌فرض دارای تفکر فعال هستند. مدل‌های منسوخ‌شده Gemini 2.5 نیز از اندیشیدن پیش‌فرض استفاده می‌کنند.

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

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

برای جزئیات پیکربندی و نمونه کدها، راهنمای تفکر را ببینید.

مشکلات ایمنی

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

اگر BlockedReason.OTHER را می‌بینید، ممکن است پُرسمان یا پاسخ شرایط خدمات را نقض کند یا به‌دلیل دیگری پشتیبانی نشود.

مشکل تلاوت

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

مشکل کدهای تکراری

اگر نشان‌های خروجی تکراری می‌بینید، پیشنهادهای زیر را امتحان کنید تا به کاهش یا حذف آن‌ها کمک کنید.

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

در پیام‌واره‌تان دستورالعمل اضافه کنید تا رهنمودهای ویژه‌ای برای تولید جدول‌های «مارک‌داون» به مدل بدهید. نمونه‌هایی ارائه دهید که از آن دستورالعمل‌ها پیروی کند. همچنین می‌توانید دما را تنظیم کنید. برای تولید کد یا خروجی بسیار ساختاریافته مانند جدول‌های Markdown، مشخص شده است که دمای بالا بهتر عمل می‌کند (‎>= ۰٫۸).

در زیر نمونه‌ای از مجموعه رهنمودهایی که می‌توانید به پیام‌واره‌تان اضافه کنید تا از بروز این مشکل جلوگیری کنید آورده شده است: 

          # Markdown Table Format
          
          * Separator line: Markdown tables must include a separator line below
            the header row. The separator line must use only 3 hyphens per
            column, for example: |---|---|---|. Using more hypens like
            ----, -----, ------ can result in errors. Always
            use |:---|, |---:|, or |---| in these separator strings.

            For example:

            | Date | Description | Attendees |
            |---|---|---|
            | 2024-10-26 | Annual Conference | 500 |
            | 2025-01-15 | Q1 Planning Session | 25 |

          * Alignment: Do not align columns. Always use |---|.
            For three columns, use |---|---|---| as the separator line.
            For four columns use |---|---|---|---| and so on.

          * Conciseness: Keep cell content brief and to the point.

          * Never pad column headers or other cells with lots of spaces to
            match with width of other content. Only a single space on each side
            is needed. For example, always do "| column name |" instead of
            "| column name                |". Extra spaces are wasteful.
            A markdown renderer will automatically take care displaying
            the content in a visually appealing form.
نشانه‌های تکراری در جدول‌های Markdown مشابه خط تیره تکراری، این اتفاق زمانی رخ می‌دهد که مدل سعی می‌کند محتوای جدول را به‌صورت بصری تراز کند. تراز کردن در Markdown برای ارائه صحیح لازم نیست.
  • دستورالعمل‌هایی مانند موارد زیر را به پیام‌واره سیستم خود اضافه کنید: 
                FOR TABLE HEADINGS, IMMEDIATELY ADD ' |' AFTER THE TABLE HEADING.
  • دما را اصلاح کنید. دماهای بالاتر (>= ۰٫۸) معمولاً به حذف تکرارها یا تکثیر در برونداد کمک می‌کند.
خطوط جدید تکراری (\n) در برونداد ساختاریافته وقتی ورودی مدل حاوی یونی‌کد یا توالی‌های گریز مانند \u یا \t باشد، می‌تواند منجر به خطوط جدید تکراری شود.
  • دنبال توالی‌های گریز ممنوع بگردید و آن‌ها را با نویسه‌های UTF-8 در پیام‌واره‌تان جایگزین کنید. برای مثال، \u توالی گریز در نمونه‌های JSON شما می‌تواند باعث شود مدل از آن‌ها در برونداد خود نیز استفاده کند.
  • به مدل درباره گریزهای مجاز دستورالعمل بدهید. دستورالعمل سیستمی مانند این اضافه کنید: 
                In quoted strings, the only allowed escape sequences are \\, \n, and \". Instead of \u escapes, use UTF-8.
نوشتار تکراری دراستفاده از برونداد ساختاریافته وقتی ترتیب فیلدها در خروجی مدل با طرح‌واره ساختاریافته تعریف‌شده متفاوت باشد، این امر می‌تواند منجر به تکرار نوشتار شود.
  • ترتیب فیلدها را در پیام‌واره‌تان مشخص نکنید.
  • همه فیلدهای خروجی را الزامی کنید.
فراخوانی تکراری ابزار این اتفاق زمانی می‌افتد که مدل بافت افکار قبلی را ازدست بدهد و/یا مجبور شود نقطه پایانی غیرقابل‌دسترسی را فراخوانی کند. به مدل دستور دهید که وضعیت را در فرایند تفکر خود حفظ کند. این را به انتهای دستورالعمل‌های سیستم اضافه کنید: 
        When thinking silently: ALWAYS start the thought with a brief
        (one sentence) recap of the current progress on the task. In
        particular, consider whether the task is already done.
نوشتار تکراری که بخشی از برونداد ساختاریافته نیست این اتفاق می‌تواند زمانی رخ دهد که مدل در درخواستی که نمی‌تواند آن را حل کند گیر کند.
  • اگر تفکر روشن است، از ارائه دستورات صریح درباره نحوه فکر کردن به یک مشکل در دستورالعمل‌ها خودداری کنید. فقط خروجی نهایی را درخواست کنید.
  • دمای بالاتر از ۰٫۸ را امتحان کنید.
  • دستورالعمل‌هایی مثل «مختصر باش»، «خودت را تکرار نکن»، یا «پاسخ را یک‌بار ارائه کن» اضافه کنید.

کلیدهای میانای API مسدودشده یا غیرفعال

این بخش نحوه بررسی اینکه آیا کلید Gemini API شما مسدود شده است یا نه و اینکه در این‌صورت چه کاری باید انجام دهید را توضیح می‌دهد.

آشنایی با دلیل مسدود شدن کلیدها

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

تأیید کنید که آیا کلیدهایتان تحت‌تأثیر قرار گرفته‌اند یا نه

اگر مشخص شود کلیدتان لو رفته است، دیگر نمی‌توانید از آن کلید با Gemini API استفاده کنید. می‌توانید از Google AI Studio استفاده کنید تا ببینید آیا هیچ‌کدام از کلیدهای میانای API شما برای فراخوانی Gemini API مسدود شده‌اند یا نه و کلیدهای جدید تولید کنید. همچنین ممکن است هنگام تلاش برای استفاده از این کلیدها، خطای زیر را مشاهده کنید:

Your API key was reported as leaked. Please use another API key.

کنش برای کلیدهای میانای برنامه‌سازی کاربردی مسدودشده

باید کلیدهای API جدیدی برای یکپارچه‌سازی‌های Gemini API خود بااستفاده از Google AI Studio تولید کنید. اکیداً توصیه می‌کنیم روال‌های مدیریت کلید میانای API خود را مرور کنید تا مطمئن شوید کلیدهای جدیدتان ایمن نگه داشته می‌شوند و به‌طور عمومی افشا نمی‌شوند.

هزینه‌های غیرمنتظره به‌دلیل آسیب‌پذیری

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

اقدامات امنیتی Google برای کلیدهای فاش‌شده

اگر کلیدهای API من فاش شود، Google چگونه به ایمن کردن حساب من دربرابر تجاوز از هزینه و سوءاستفاده کمک می‌کند؟

  • ما درحال حرکت به‌سمت صدور کلیدهای API هستیم، وقتی‌که کلید جدیدی را بااستفاده از Google AI Studio درخواست می‌کنید، این کلید به‌طور پیش‌فرض فقط به Google AI Studio محدود خواهد بود و کلیدهای سرویس‌های دیگر را نمی‌پذیرد. این کار به جلوگیری از استفاده ناخواسته از کلیدهای متقاطع کمک می‌کند.
  • ما به‌طور پیش‌فرض کلیدهای API را که فاش شده‌اند و با Gemini API استفاده می‌شوند مسدود می‌کنیم تا به جلوگیری از سوءاستفاده از هزینه و داده‌های برنامه‌تان کمک کنیم.
  • می‌توانید وضعیت کلیدهای میانای برنامه‌سازی کاربردی خود را در Google AI Studio پیدا کنید و ما تلاش می‌کنیم درصورت شناسایی نشت کلیدهای میانای برنامه‌سازی کاربردی شما، به‌طور فعالانه اطلاع‌رسانی کنیم تا اقدام فوری انجام دهید.

بهبود دادن برونداد مدل

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

درک محدودیت‌های نشان

راهنمای توکن ما را بخوانید تا با نحوه شمارش توکن‌ها و محدودیت‌های آن‌ها بهتر آشنا شوید.

مشکلات شناخته‌شده

  • این «میانای برنامه‌سازی کاربردی» فقط از تعدادی زبان منتخب پشتیبانی می‌کند. ارسال پیام‌واره به زبان‌های پشتیبانی‌نشده می‌تواند منجر به پاسخ‌های غیرمنتظره یا حتی مسدودشده شود. زبان‌های دردسترس برای به‌روزرسانی‌ها را ببینید.

گزارش اشکال

اگر سؤالی دارید، به بحث در تالار گفتمان توسعه‌دهندگان هوش مصنوعی Google بپیوندید.