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

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

หากพบปัญหาเกี่ยวกับคีย์ 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 วินาที)
  • เพิ่มการสั่น: เพิ่ม "การสั่น" แบบสุ่มในการหน่วงเวลาเพื่อช่วยป้องกันไม่ให้ไคลเอ็นต์ทั้งหมดลองใหม่ในเวลาเดียวกัน
  • ลองใหม่เมื่อเกิดข้อผิดพลาดที่เฉพาะเจาะจง: ลองใหม่เฉพาะเมื่อเกิดข้อผิดพลาดชั่วคราว (เช่น 429, 408 หรือ 5xx) อย่าลองใหม่เมื่อเกิดข้อผิดพลาดของไคลเอ็นต์ (เช่น 400 หรือ 403) เนื่องจากข้อผิดพลาดเหล่านี้บ่งบอกถึงปัญหาต่างๆ เช่น คีย์ API ไม่ถูกต้องหรือไวยากรณ์ไม่ถูกต้อง
  • กำหนดจำนวนการลองใหม่สูงสุด: กำหนดจำนวนครั้งสูงสุดที่จะลองใหม่เพื่อป้องกันไม่ให้เกิดการวนซ้ำไม่สิ้นสุด

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

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

พารามิเตอร์โมเดล ค่า (ช่วง)
จำนวนตัวเลือก 1-8 (จำนวนเต็ม)
อุณหภูมิ 0.0-1.0
โทเค็นเอาต์พุตสูงสุด ใช้หน้าโมเดล เพื่อกำหนดจำนวนโทเค็นสูงสุดสำหรับโมเดลที่คุณใช้
TopP 0.0-1.0

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

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

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

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

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

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

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

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

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

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

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

ปัญหาการท่องจำ

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

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

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

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

เพิ่มวิธีการในพรอมต์เพื่อให้โมเดลมีหลักเกณฑ์ที่เฉพาะเจาะจง สำหรับการสร้างตารางมาร์กดาวน์ ระบุตัวอย่างที่เป็นไปตามหลักเกณฑ์เหล่านั้น นอกจากนี้ คุณยังลองปรับอุณหภูมิได้ด้วย สำหรับการสร้าง โค้ดหรือเอาต์พุตที่มีโครงสร้างชัดเจนมาก เช่น ตารางมาร์กดาวน์ พบว่าอุณหภูมิสูงทำงานได้ดีกว่า (>= 0.8)

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

          # 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.
โทเค็นซ้ำในตารางมาร์กดาวน์ ปัญหานี้เกิดขึ้นเมื่อโมเดลพยายามจัดแนวเนื้อหาของตารางด้วยสายตา ซึ่งคล้ายกับขีดกลางซ้ำ การจัดแนวในมาร์กดาวน์ไม่จำเป็นสำหรับการแสดงผลที่ถูกต้อง
  • ลองเพิ่มวิธีการต่อไปนี้ลงในพรอมต์ระบบ 
                FOR TABLE HEADINGS, IMMEDIATELY ADD ' |' AFTER THE TABLE HEADING.
  • ลองปรับอุณหภูมิ โดยทั่วไปแล้วอุณหภูมิที่สูงขึ้น (>= 0.8) จะช่วยกำจัดการทำซ้ำใน เอาต์พุต
บรรทัดใหม่ (\n) ซ้ำในเอาต์พุตที่มีโครงสร้าง เมื่ออินพุตของโมเดลมี Unicode หรือลำดับการหลีก เช่น \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.
ข้อความซ้ำซึ่งไม่ได้เป็นส่วนหนึ่งของเอาต์พุตที่มีโครงสร้าง ปัญหานี้อาจเกิดขึ้นหากโมเดลติดอยู่กับคำขอที่โมเดลแก้ไขไม่ได้
  • หากเปิดใช้การคิดอยู่ ให้หลีกเลี่ยงการให้คำสั่งที่ชัดเจนเกี่ยวกับวิธี คิดเพื่อแก้ปัญหาในวิธีการ เพียงขอเอาต์พุตสุดท้าย
  • ลองใช้อุณหภูมิที่สูงขึ้น >= 0.8
  • เพิ่มวิธีการ เช่น "กระชับ", "อย่าพูดซ้ำ" หรือ "ระบุคำตอบเพียงครั้งเดียว"

คีย์ API ที่ถูกบล็อกหรือไม่ทำงาน

ส่วนนี้อธิบายวิธีตรวจสอบว่าคีย์ Gemini API ถูกบล็อกหรือไม่และสิ่งที่ควรทำ

ทำความเข้าใจเหตุผลที่คีย์ถูกบล็อก

เราพบช่องโหว่ที่คีย์ 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 ของคุณรั่วไหลเพื่อให้คุณดำเนินการได้ทันที

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

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

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

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

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

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

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

เข้าร่วมการสนทนาใน ฟอรัมสำหรับนักพัฒนาแอป Google AI หากมีข้อสงสัย