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

ใช้คู่มือนี้เพื่อช่วยคุณวิเคราะห์และแก้ไขปัญหาที่พบบ่อยซึ่งเกิดขึ้นเมื่อ เรียกใช้ 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) และ โมเดลที่รองรับฟีเจอร์ที่คุณต้องการอย่างถูกต้อง เช่น หากฟีเจอร์อยู่ในรุ่นเบต้า ฟีเจอร์นั้นจะใช้ได้เฉพาะใน API เวอร์ชัน /v1beta เท่านั้น

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

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

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

ความหน่วงหรือการใช้โทเค็นที่สูงขึ้นมักเกิดขึ้นเนื่องจากโมเดล 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 รองรับเฉพาะบางภาษาเท่านั้น การส่งพรอมต์ในภาษาที่ไม่รองรับอาจทำให้ได้คำตอบที่ไม่คาดคิดหรือถูกบล็อก ดูข้อมูลอัปเดตเกี่ยวกับ ภาษาที่ใช้ได้

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

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