คู่มือการแก้ปัญหา

ใช้คู่มือนี้เพื่อช่วยในการวินิจฉัยและแก้ไขปัญหาที่พบบ่อยซึ่งเกิดขึ้นเมื่อคุณเรียกใช้ Gemini API คุณอาจพบปัญหาจากบริการแบ็กเอนด์ของ Gemini API หรือ SDK ของไคลเอ็นต์ SDK ไคลเอ็นต์ของเราเป็นโอเพนซอร์สในที่เก็บต่อไปนี้

• python-genai
• js-genai
• go-genai

หากพบปัญหาเกี่ยวกับคีย์ API ให้ตรวจสอบว่าคุณได้ตั้งค่า คีย์ API อย่างถูกต้องตามคู่มือการตั้งค่าคีย์ API

รหัสข้อผิดพลาด

ดูข้อมูลอ้างอิงทั้งหมดของรหัสข้อผิดพลาด รวมถึงรหัสสถานะ HTTP รหัสที่บล็อกการสร้าง และรหัสข้อผิดพลาดของเนื้อหาได้ที่หน้าข้อผิดพลาดของ API

กลยุทธ์การลองใหม่

หากได้รับข้อผิดพลาดที่ระบุว่าคุณควรลองส่งคำขออีกครั้ง (เช่น 429 RESOURCE_EXHAUSTED หรือ 503 UNAVAILABLE) เราขอแนะนำให้ใช้กลยุทธ์ Exponential Backoff ซึ่งหมายความว่าคุณจะรอสักครู่ก่อนที่จะลองอีกครั้งเป็นครั้งแรก จากนั้นค่อยๆ เพิ่มเวลารอระหว่างการลองอีกครั้งในครั้งต่อๆ ไป

SDK ไคลเอ็นต์อย่างเป็นทางการสำหรับ Gemini API เช่น Python SDK มีตรรกะการลองใหม่โดยอัตโนมัติพร้อม Exponential Backoff โดยค่าเริ่มต้นเพื่อจัดการข้อผิดพลาดชั่วคราว เช่น หมดเวลา ปัญหาเครือข่าย และการจำกัดอัตราคำขอ (รหัสสถานะ 429 และ 5xx) ตัวอย่างเช่น Python SDK จะลองใหม่โดยอัตโนมัติสำหรับข้อผิดพลาดชั่วคราวสูงสุด 4 ครั้ง โดยมีการหน่วงเวลาเริ่มต้นประมาณ 1 วินาที และหน่วงเวลาสูงสุด 60 วินาที

หากคุณส่งคำขอ REST API โดยตรงหรือปรับแต่งตรรกะการลองใหม่ ให้ทำตามแนวทางปฏิบัติแนะนำต่อไปนี้เพื่อเพิ่มโอกาสที่คำขอจะสำเร็จและป้องกันไม่ให้บริการทำงานหนักเกินไป

• ใช้ Exponential Backoff: รอสักครู่ก่อนลองอีกครั้งครั้งแรก (เช่น 1 วินาที) จากนั้นเพิ่มการหน่วงเวลาแบบทวีคูณ (เช่น 2 วินาที 4 วินาที 8 วินาที)
• เพิ่ม Jitter: เพิ่ม "Jitter" แบบสุ่มลงในดีเลย์เพื่อช่วยป้องกันไม่ให้ไคลเอ็นต์ทั้งหมดลองอีกครั้งในเวลาเดียวกัน
• ลองอีกครั้งเมื่อเกิดข้อผิดพลาดที่เฉพาะเจาะจง: ลองอีกครั้งเฉพาะเมื่อเกิดข้อผิดพลาดชั่วคราว (เช่น 429, 408 หรือ 5xx) อย่าลองอีกครั้งเมื่อเกิดข้อผิดพลาดของไคลเอ็นต์ (เช่น 400, 402 หรือ 403) เนื่องจากข้อผิดพลาดเหล่านี้บ่งบอกถึงปัญหาต่างๆ เช่น คีย์ API ไม่ถูกต้อง เครดิตแบบชำระล่วงหน้าหมด หรือไวยากรณ์ไม่ถูกต้อง
• ตั้งค่าการลองใหม่สูงสุด: กำหนดจำนวนครั้งสูงสุดที่พยายามลองใหม่เพื่อป้องกันไม่ให้เกิดลูปที่ไม่มีที่สิ้นสุด

ตรวจสอบการเรียก API เพื่อหาข้อผิดพลาดของพารามิเตอร์โมเดล

ตรวจสอบว่าพารามิเตอร์ของโมเดลอยู่ภายในค่าต่อไปนี้

นอกเหนือจากการตรวจสอบค่าพารามิเตอร์แล้ว โปรดตรวจสอบว่าคุณใช้เวอร์ชัน API (เช่น /v1 หรือ /v1beta) และ โมเดลที่รองรับฟีเจอร์ที่คุณต้องการอย่างถูกต้อง เช่น หากฟีเจอร์อยู่ในรุ่นเบต้า ฟีเจอร์นั้นจะใช้ได้ใน /v1beta API เวอร์ชันเท่านั้น

ตรวจสอบว่าคุณมีโมเดลที่ถูกต้อง

ตรวจสอบว่าคุณใช้โมเดลที่รองรับซึ่งแสดงอยู่ในหน้าโมเดล

เวลาในการตอบสนองหรือการใช้โทเค็นที่สูงขึ้นเมื่อใช้โมเดลการคิด

ความหน่วงหรือการใช้โทเค็นที่สูงขึ้นมักเกิดขึ้นเนื่องจากโมเดล Gemini 3.x มีการเปิดใช้ การคิดโดยค่าเริ่มต้น โมเดล Gemini 2.5 ที่เลิกใช้งานแล้วจะใช้การคิดเริ่มต้นด้วย

โมเดลการคิดจะสร้างโทเค็นการให้เหตุผลภายในเพื่อปรับปรุงคุณภาพ กระบวนการให้เหตุผลนี้จะเพิ่มทั้งเวลาในการตอบสนองและปริมาณโทเค็นที่ใช้ทั้งหมด

หากต้องการให้ความสำคัญกับเวลาในการตอบสนองที่ต่ำกว่าหรือต้องการลดต้นทุนให้เหลือน้อยที่สุด คุณสามารถลด ระดับการคิดหรือปิดการคิดได้

ดูรายละเอียดการกำหนดค่าและตัวอย่างโค้ดได้ที่คู่มือการคิด

ปัญหาด้านความปลอดภัย

หากเห็นข้อความแจ้งว่าถูกบล็อกเนื่องจากการตั้งค่าความปลอดภัยในการเรียก API ให้ตรวจสอบพรอมต์โดยคำนึงถึงตัวกรองที่คุณตั้งค่าในการเรียก API

หากเห็น BlockedReason.OTHER แสดงว่าคำค้นหาหรือคำตอบอาจละเมิดข้อกำหนด ในการให้บริการหรือไม่รองรับ

ปัญหาเกี่ยวกับการอ่าน

หากเห็นว่าเอาต์พุตโมเดลหยุดสร้างเอาต์พุตเนื่องจากเหตุผลด้านการอ้างอิง แสดงว่าเอาต์พุตโมเดลอาจคล้ายกับข้อมูลบางอย่าง หากต้องการแก้ไขปัญหานี้ ให้ลองทำให้ พรอมต์ / บริบทไม่ซ้ำกันมากที่สุดและใช้อุณหภูมิที่สูงขึ้น

ปัญหาโทเค็นซ้ำ

หากเห็นโทเค็นเอาต์พุตซ้ำๆ ให้ลองทำตามคำแนะนำต่อไปนี้เพื่อช่วย ลดหรือกำจัดโทเค็นเหล่านั้น

          # 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.
        

        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 ที่ถูกบล็อกหรือไม่ทำงาน

ส่วนนี้อธิบายวิธีตรวจสอบว่าคีย์ 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 ที่ถูกบล็อก

คุณควรสร้างคีย์ API ใหม่สำหรับการผสานรวม Gemini API โดยใช้ Google AI Studio เราขอแนะนำให้ตรวจสอบแนวทางปฏิบัติในการจัดการคีย์ API เพื่อให้มั่นใจว่าคีย์ใหม่จะปลอดภัยและไม่เปิดเผยต่อสาธารณะ

การเรียกเก็บเงินที่ไม่คาดคิดเนื่องจากช่องโหว่

ส่งเคสขอรับความช่วยเหลือด้านการเรียกเก็บเงิน ทีมการเรียกเก็บเงินของเรากำลังดำเนินการแก้ไขปัญหานี้ และเราจะแจ้งข้อมูลอัปเดตให้คุณทราบโดยเร็วที่สุด

มาตรการรักษาความปลอดภัยของ Google สำหรับคีย์ที่รั่วไหล

Google จะช่วยรักษาความปลอดภัยให้บัญชีของฉันจากการใช้จ่ายเกินงบประมาณและการละเมิดได้อย่างไรหาก คีย์ API ของฉันรั่วไหล

• เรากำลังจะออกคีย์ API เมื่อคุณขอคีย์ใหม่โดยใช้ Google AI Studio ซึ่งโดยค่าเริ่มต้นจะจำกัดเฉพาะ Google AI Studio และไม่ยอมรับคีย์จากบริการอื่นๆ ซึ่งจะช่วยป้องกันการใช้คีย์ข้ามบัญชีโดยไม่ตั้งใจ
• เราจะบล็อกคีย์ API ที่รั่วไหลและใช้กับ Gemini API โดยค่าเริ่มต้น เพื่อช่วยป้องกันการละเมิดค่าใช้จ่ายและข้อมูลแอปพลิเคชันของคุณ
• คุณจะดูสถานะของคีย์ API ได้ภายใน Google AI Studio และเราจะสื่อสาร เชิงรุกเมื่อพบว่าคีย์ API ของคุณรั่วไหลเพื่อให้คุณดำเนินการได้ทันที

ปรับปรุงเอาต์พุตโมเดล

หากต้องการเอาต์พุตโมเดลที่มีคุณภาพสูงขึ้น ให้ลองเขียนพรอมต์ที่มีโครงสร้างมากขึ้น หน้าคู่มือวิศวกรรมพรอมต์ จะแนะนำแนวคิด กลยุทธ์ และแนวทางปฏิบัติแนะนำเบื้องต้นเพื่อช่วยให้คุณเริ่มต้นใช้งานได้

ทำความเข้าใจขีดจำกัดของโทเค็น

อ่านคู่มือโทเค็นเพื่อทำความเข้าใจวิธีนับโทเค็นและขีดจำกัดของโทเค็นให้ดียิ่งขึ้น

ปัญหาที่ทราบ

• API รองรับเฉพาะบางภาษาเท่านั้น การส่งพรอมต์ในภาษาที่ไม่รองรับอาจทำให้ได้คำตอบที่ไม่คาดคิดหรือถูกบล็อก ดูข้อมูลอัปเดตเกี่ยวกับ ภาษาที่ใช้ได้

รายงานข้อบกพร่อง

หากมีข้อสงสัย โปรดเข้าร่วมการสนทนาในฟอรัมนักพัฒนาซอฟต์แวร์ AI ของ Google