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

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

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

รหัสข้อผิดพลาดของบริการแบ็กเอนด์ของ Gemini API

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

รหัส HTTP สถานะ คำอธิบาย ตัวอย่าง Solution
400 INVALID_ARGUMENT เนื้อหาของคำขอมีรูปแบบไม่ถูกต้อง คำขอของคุณมีข้อผิดพลาดในการพิมพ์หรือไม่มีช่องที่ต้องกรอก ดูรูปแบบคำขอ ตัวอย่าง และเวอร์ชันที่รองรับได้ในเอกสารอ้างอิง API การใช้ฟีเจอร์จาก API เวอร์ชันใหม่กว่ากับปลายทางที่เก่ากว่าอาจทำให้เกิดข้อผิดพลาดได้
400 FAILED_PRECONDITION ระดับฟรีของ Gemini API ไม่พร้อมให้บริการในประเทศของคุณ โปรดเปิดใช้การเรียกเก็บเงินในโปรเจ็กต์ใน Google AI Studio คุณกำลังส่งคำขอในภูมิภาคที่ไม่รองรับระดับฟรี และคุณยังไม่ได้เปิดใช้การเรียกเก็บเงินในโปรเจ็กต์ใน Google AI Studio หากต้องการใช้ Gemini API คุณจะต้องตั้งค่าแพ็กเกจแบบชำระเงินโดยใช้ Google AI Studio
403 PERMISSION_DENIED คีย์ API ของคุณไม่มีสิทธิ์ที่จำเป็น คุณใช้คีย์ API ที่ไม่ถูกต้อง คุณ พยายามใช้โมเดลที่ปรับแต่งแล้วโดยไม่ได้ผ่านการตรวจสอบสิทธิ์ที่เหมาะสม ตรวจสอบว่าได้ตั้งค่าคีย์ API และมีสิทธิ์เข้าถึงที่ถูกต้อง และอย่าลืมตรวจสอบสิทธิ์อย่างถูกต้องเพื่อใช้โมเดลที่ปรับแต่งแล้ว
404 NOT_FOUND ไม่พบทรัพยากรที่ร้องขอ ไม่พบไฟล์รูปภาพ เสียง หรือวิดีโอที่อ้างอิงในคำขอของคุณ ตรวจสอบว่าพารามิเตอร์ทั้งหมดในคำขอใช้ได้กับ API เวอร์ชันของคุณ
429 RESOURCE_EXHAUSTED คุณส่งคำขอเกินขีดจำกัดอัตราแล้ว คุณส่งคำขอต่อนาทีมากเกินไปด้วย Gemini API ระดับฟรี ตรวจสอบว่าคุณอยู่ภายในขีดจำกัดอัตราของโมเดล ขอเพิ่มโควต้าหากจำเป็น
500 ภายใน เกิดข้อผิดพลาดที่ไม่คาดคิดจากทางฝั่ง Google บริบทของข้อมูลที่คุณป้อนยาวเกินไป ลดบริบทอินพุตหรือเปลี่ยนไปใช้โมเดลอื่นชั่วคราว (เช่น จาก Gemini 2.5 Pro เป็น Gemini 2.5 Flash) แล้วดูว่าใช้งานได้หรือไม่ หรือรอสักครู่แล้วลองส่งคำขออีกครั้ง หากปัญหายังคงอยู่หลังจากลองอีกครั้ง โปรดรายงานปัญหาโดยใช้ปุ่มส่งความคิดเห็นใน Google AI Studio
503 UNAVAILABLE บริการอาจมีการใช้งานมากเกินไปหรือหยุดทำงานชั่วคราว บริการนี้มีขีดจำกัดชั่วคราว เปลี่ยนไปใช้โมเดลอื่นชั่วคราว (เช่น จาก Gemini 2.5 Pro เป็น Gemini 2.5 Flash) แล้วดูว่าใช้งานได้หรือไม่ หรือรอสักครู่แล้วลองส่งคำขออีกครั้ง หากปัญหายังคงอยู่หลังจากลองอีกครั้ง โปรดรายงานปัญหาโดยใช้ปุ่มส่งความคิดเห็นใน Google AI Studio
504 DEADLINE_EXCEEDED บริการไม่สามารถประมวลผลให้เสร็จสิ้นภายในกำหนดเวลาได้ พรอมต์ (หรือบริบท) มีขนาดใหญ่เกินกว่าจะประมวลผลได้ทันเวลา ตั้งค่า "หมดเวลา" ให้ยาวขึ้นในคำขอของไคลเอ็นต์เพื่อหลีกเลี่ยงข้อผิดพลาดนี้

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

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

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

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

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

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

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

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

โปรดดูคำแนะนำและโค้ดตัวอย่างในหน้าการคิด

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

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

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

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

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

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

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

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

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