การจัดการข้อผิดพลาด การจำกัดอัตรา และการจัดการโควต้า

เมื่อคุณค้นหา Developer Knowledge API หรือเซิร์ฟเวอร์ Developer Knowledge MCP ในแอปพลิเคชันที่ใช้งานจริง และเอเจนต์ AI จะต้องมีการจัดการข้อผิดพลาดและการจัดการโควต้าเพื่อให้ได้ประสิทธิภาพสูง

ในคู่มือนี้ คุณจะได้เรียนรู้วิธีการทำสิ่งต่อไปนี้

  • ใช้ Exponential Backoff ที่ถูกตัดทอนพร้อม Jitter สำหรับการตอบกลับ HTTP 429
  • จัดการรหัสข้อผิดพลาด gRPC ที่เป็น Canonical (INVALID_ARGUMENT, PERMISSION_DENIED, RESOURCE_EXHAUSTED)
  • จัดการการหมดเวลาการเชื่อมต่อ MCP และตรรกะการลองใหม่
  • ใช้แนวทางปฏิบัติแนะนำในการจัดการโควต้าและการแคช

การจำกัดอัตราคำขอ HTTP 429 และ Exponential Backoff

เมื่ออัตราคำขอเกินโควต้า API เริ่มต้น บริการจะแสดงข้อผิดพลาด HTTP 429 Too Many Requests แอปพลิเคชันต้องใช้ตรรกะการลองใหม่ โดยใช้ Exponential Backoff ที่ถูกตัดทอนพร้อม Jitter เพื่อหลีกเลี่ยงการโอเวอร์โหลดบริการ

Exponential Backoff ที่ถูกตัดทอน

คำนวณการหน่วงเวลาการลองใหม่โดยใช้สูตรต่อไปนี้

retry_delay = min(max_delay, initial_delay * (2 ^ attempt) + jitter)

ใช้พารามิเตอร์ต่อไปนี้เพื่อคำนวณระยะเวลาก่อนลองใหม่

  • initial_delay: ระยะเวลาก่อนที่จะลองใหม่ครั้งแรก (เช่น 1.0 วินาที)
  • max_delay: ขีดจำกัดสูงสุดของการหยุดชั่วคราว (เช่น 32.0 วินาที)
  • attempt: จำนวนครั้งที่ลองใหม่ในปัจจุบัน (0, 1, 2, ...)
  • jitter: ค่าแบบสุ่มระหว่าง 0 ถึง 1.0 วินาทีเพื่อป้องกันไม่ให้เกิดการเพิ่มขึ้นของ การซิงโครไนซ์เธรด (ปัญหาฝูงชนที่วิ่งตามกัน)

การจัดการข้อผิดพลาดของ gRPC

แอปพลิเคชันที่เข้าถึงบริการผ่าน gRPC ต้องตรวจสอบค่า grpc.StatusCode ที่เป็นมาตรฐาน

รหัสสถานะ gRPC มาตรฐาน

ตารางต่อไปนี้แสดงรหัสสถานะ gRPC ที่เป็นมาตรฐานซึ่งบริการส่งคืน และการจัดการฝั่งไคลเอ็นต์ที่แนะนำ

รหัสสถานะ gRPC สถานะ HTTP สาเหตุของปัญหา การดำเนินการที่แนะนำ
INVALID_ARGUMENT 400 Bad Request สตริงการค้นหามีรูปแบบไม่ถูกต้อง รูปแบบพารามิเตอร์ไม่ถูกต้อง หรือมาสก์ฟิลด์ไม่ถูกต้อง ไม่ต้องลองใหม่ แก้ไขพารามิเตอร์คำขอก่อนทำซ้ำ
UNAUTHENTICATED 401 Unauthorized ไม่มีคีย์ API หรือโทเค็นผู้ถือ OAuth หรือคีย์ API หรือโทเค็นผู้ถือ OAuth หมดอายุหรือมีรูปแบบไม่ถูกต้อง ไม่ต้องลองใหม่ รีเฟรชข้อมูลเข้าสู่ระบบหรือสร้างคีย์ API ที่ถูกต้อง
PERMISSION_DENIED 403 Forbidden คีย์ API ไม่มีสิทธิ์หรือปิดใช้ Developer Knowledge API ในโปรเจ็กต์ ไม่ต้องลองใหม่ ยืนยันการเปิดใช้ API ในคอนโซล Google Cloud
NOT_FOUND 404 Not Found ไม่มีเส้นทางเอกสาร parent ที่ระบุ BatchGetDocuments จะล้มเหลวโดยอัตโนมัติหากไม่พบเอกสารที่ขอ ไม่ต้องลองใหม่ ยืนยันชื่อทรัพยากรของเอกสาร
RESOURCE_EXHAUSTED 429 Too Many Requests เกินขีดจำกัดของอัตราหรือโควต้าโปรเจ็กต์ ลองอีกครั้งโดยใช้ Exponential Backoff พร้อม Jitter
UNAVAILABLE 503 Service Unavailable การยกเลิกการเชื่อมต่อเครือข่ายชั่วคราวหรือการรีสตาร์ทเซิร์ฟเวอร์ ลองอีกครั้งโดยใช้ Exponential Backoff
DEADLINE_EXCEEDED 504 Gateway Timeout คำขอเกินกำหนดเวลา RPC ที่กำหนดค่าไว้ก่อนที่จะเสร็จสมบูรณ์ ลองอีกครั้งโดยเพิ่มระยะหมดเวลา RPC ของไคลเอ็นต์

การจัดการข้อผิดพลาดและการหมดเวลาการเชื่อมต่อ MCP

เซิร์ฟเวอร์ MCP ความรู้สำหรับนักพัฒนาซอฟต์แวร์เป็นบริการระยะไกลที่โฮสต์อยู่ที่ https://developerknowledge.googleapis.com/mcp ซึ่งเข้าถึงได้ผ่าน HTTPS (โดยใช้ HTTP POST หรือเหตุการณ์ที่เซิร์ฟเวอร์ส่ง) โฮสต์และเอเจนต์ AI ต้องจัดการการหมดเวลาการเชื่อมต่อ และข้อผิดพลาดของเครื่องมืออย่างเหมาะสม

การหมดเวลาการดำเนินการเครื่องมือ

เมื่อเอเจนต์เรียกใช้ search_documents, get_documents หรือ answer_query การเรียกใช้เครื่องมืออาจเกินระยะหมดเวลา (เช่น 30 วินาที) หากการเชื่อมต่อเครือข่าย ล่าช้า

วิธีจัดการการหมดเวลาการดำเนินการเครื่องมือ

  • กำหนดค่าการหมดเวลาของไคลเอ็นต์: ตั้งค่าการหมดเวลาการดำเนินการเครื่องมือเป็น 30-60 วินาที ในการกำหนดค่าไคลเอ็นต์โฮสต์ MCP
  • จัดการการหยุดชะงักของเครือข่าย: ลองส่งคำขอ HTTP ที่ล้มเหลวอีกครั้งด้วย Exponential Backoff เมื่อเครือข่ายขาดหายไปชั่วคราวหรือได้รับการตอบกลับ HTTP 503
  • ตรวจสอบข้อความแสดงข้อผิดพลาด: แยกวิเคราะห์ข้อความแสดงข้อผิดพลาด JSON-RPC มาตรฐานหรือรหัสสถานะข้อผิดพลาด HTTP เพื่อแยกแยะอาร์กิวเมนต์ที่ไม่ถูกต้องจากการใช้โควต้าจนหมด

แนวทางปฏิบัติแนะนำในการจัดการโควต้า

ทําตามแนวทางปฏิบัติแนะนําเหล่านี้เพื่อรักษาการใช้งาน API ให้ได้ประสิทธิภาพสูงสุดและหลีกเลี่ยงการจํากัดอัตราที่ไม่คาดคิด

  1. แคชเนื้อหาเอกสารที่ดึงข้อมูล: จัดเก็บเอกสารมาร์กดาวน์ที่ดึงข้อมูล ไว้ในเครื่องหรือในแคช (เช่น Redis) เมื่อสร้างแอปพลิเคชันที่ เข้าถึงหน้าเดียวกันบ่อยๆ
  2. ใช้การดึงข้อมูลแบบเป็นกลุ่ม: ใช้ documents.batchGet แทนการส่งคำขอ documents.get หลายรายการตามลำดับ
  3. เพิ่มประสิทธิภาพช่องการค้นหา: ขอเฉพาะช่องการตอบกลับที่จำเป็นโดยใช้ มาสก์ฟิลด์แบบเลือก (fields=results(parent,content))
  4. ตรวจสอบการใช้โควต้า: ติดตามอัตราคำขอ API ในแดชบอร์ด API ของคอนโซล Google Cloud

เนื้อหาที่เกี่ยวข้อง