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

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

  • ใช้ Exponential Backoff: รอสักครู่ก่อนลองอีกครั้งเป็นครั้งแรก (เช่น 1 วินาที) จากนั้นเพิ่มระยะเวลาหน่วงแบบทวีคูณ (เช่น 2 วินาที, 4 วินาที, 8 วินาที)
  • เพิ่ม Jitter: เพิ่ม "Jitter" แบบสุ่มลงในความล่าช้าเพื่อช่วยป้องกันไม่ให้ไคลเอ็นต์ทั้งหมดลองอีกครั้งพร้อมกัน
  • ลองอีกครั้งเมื่อเกิดข้อผิดพลาดบางอย่าง: ลองอีกครั้งเฉพาะเมื่อเกิดข้อผิดพลาดชั่วคราว (เช่น 429, 408 หรือ 5xx) อย่าลองอีกครั้งเมื่อเกิดข้อผิดพลาดฝั่งไคลเอ็นต์ (เช่น 400, 402 หรือ 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 หมายความว่าเอาต์พุตโมเดลอาจคล้ายกับข้อมูลบางอย่าง หากต้องการแก้ไขปัญหานี้ ให้ลองทำให้พรอมต์ / บริบทไม่ซ้ำกันมากที่สุด และใช้ค่า Temperature ที่สูงขึ้น

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

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

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

เพิ่มคำสั่งในพรอมต์เพื่อให้หลักเกณฑ์เฉพาะแก่โมเดลสำหรับการสร้างตาราง Markdown ระบุตัวอย่างที่เป็นไปตามหลักเกณฑ์เหล่านั้น นอกจากนี้ คุณยังลองปรับอุณหภูมิได้ด้วย สำหรับการสร้างโค้ดหรือเอาต์พุตที่มีโครงสร้างชัดเจน เช่น ตาราง Markdown อุณหภูมิสูงจะทำงานได้ดีกว่า (>= 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.
โทเค็นซ้ำในตารางมาร์กดาวน์ กรณีนี้คล้ายกับเครื่องหมายขีดกลางซ้ำๆ ซึ่งเกิดขึ้นเมื่อโมเดลพยายามจัดแนวเนื้อหาของตารางให้ตรงกันในเชิงภาพ การจัดแนวใน Markdown ไม่จำเป็นสำหรับการแสดงผลที่ถูกต้อง
  • ลองเพิ่มคำสั่งต่อไปนี้ลงในพรอมต์ของระบบ 
                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 แสดงผล 403 PERMISSION_DENIED ("โปรเจ็กต์ของคุณถูกปฏิเสธการเข้าถึง") หรือสถานะโปรเจ็กต์แสดงเป็นถูกจำกัด รุ่นฟรีไม่พร้อมใช้งาน ต้องชำระเงิน หรือไม่พร้อมใช้งานใน Google AI Studio ให้ตรวจสอบว่าส่วนใดต่อไปนี้เกี่ยวข้องกับโปรเจ็กต์ของคุณ

Gemini API free tier unavailability

โปรเจ็กต์หรือบัญชี Google Cloud บางรายการไม่มีสิทธิ์ใช้ Gemini API ระดับที่ไม่มีค่าใช้จ่าย หากโปรเจ็กต์ถูกจำกัดไม่ให้ใช้รุ่นฟรี ให้ทำดังนี้

  • การสร้างคีย์ API ใหม่ในโปรเจ็กต์เดียวกันจะไม่ช่วยแก้ไขข้อผิดพลาด Google จะประเมินการมีสิทธิ์ที่ระดับโปรเจ็กต์ Google Cloud
  • หากต้องการใช้ Gemini API กับโปรเจ็กต์นี้ คุณต้องอัปเกรดเป็นระดับแบบชำระเงินโดยลิงก์บัญชีสำหรับการเรียกเก็บเงินใน Cloud ที่ใช้งานอยู่
  • หมายเหตุ: การอัปเกรดโปรเจ็กต์เป็นระดับที่ต้องชำระเงินจะไม่ปลดล็อกโควต้าระดับฟรี Google จะเรียกเก็บเงินสำหรับการใช้งานระดับที่ต้องชำระเงินตามราคาของ Gemini API หรือหักจากเครดิต Google Cloud ที่มีสิทธิ์

ต้องชำระเงินผ่านบัญชีสำหรับการเรียกเก็บเงินใน Cloud

หากโปรเจ็กต์ลิงก์กับบัญชีสำหรับการเรียกเก็บเงินใน Cloud อยู่แล้วและแสดงข้อความต้องชำระเงิน (หรือแสดงข้อผิดพลาด 403 PERMISSION_DENIED โดยอ้างอิงยอดค้างชำระ) ให้ทำดังนี้

คีย์ API ที่รั่วไหลหรือถูกบล็อก

หากข้อผิดพลาด 403 PERMISSION_DENIED ระบุว่าคีย์ API ของคุณถูกรายงานว่ารั่วไหลหรือถูกบล็อก ให้ทำดังนี้

  • ไปที่หน้าคีย์ API ของ AI Studio เพื่อสร้างคีย์ API ใหม่และอัปเดตข้อมูลเข้าสู่ระบบของแอปพลิเคชัน
  • อย่าฝังคีย์ API ไว้ในโค้ดฝั่งไคลเอ็นต์หรือที่เก็บสาธารณะโดยตรง

การระงับโปรเจ็กต์หรือบัญชีสำหรับการเรียกเก็บเงินเนื่องจากละเมิดนโยบาย

หาก Google ระงับโปรเจ็กต์ที่อยู่ในระบบคลาวด์ หรือบัญชีสำหรับการเรียกเก็บเงินใน Cloud เนื่องจาก การละเมิดนโยบาย โปรดตรวจสอบอีเมลที่เชื่อมโยง ไปที่คอนโซล Google Cloud เพื่อตรวจสอบประกาศการระงับและทำตามหลักเกณฑ์การระงับโปรเจ็กต์

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

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

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

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

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

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

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

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

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