Xử lý lỗi, giới hạn tốc độ và quản lý hạn mức

Khi bạn đang truy vấn API Kiến thức dành cho nhà phát triển hoặc máy chủ MCP Kiến thức dành cho nhà phát triển trong các ứng dụng sản xuất và các tác nhân AI, bạn phải xử lý lỗi và quản lý hạn mức để đạt được hiệu suất cao.

Trong hướng dẫn này, bạn sẽ tìm hiểu cách:

  • Triển khai thuật toán đợi lũy tuyến bị cắt bớt với độ trễ cho các phản hồi HTTP 429.
  • Xử lý mã lỗi gRPC chính tắc (INVALID_ARGUMENT, PERMISSION_DENIED, RESOURCE_EXHAUSTED).
  • Quản lý thời gian chờ kết nối MCP và logic thử lại.
  • Áp dụng các phương pháp hay nhất về quản lý hạn mức và lưu vào bộ nhớ đệm.

Giới hạn tốc độ HTTP 429 và thuật toán thời gian đợi luỹ thừa

Khi tốc độ yêu cầu vượt quá hạn mức API mặc định, dịch vụ sẽ trả về lỗi HTTP 429 Too Many Requests. Các ứng dụng phải triển khai logic thử lại bằng cách sử dụng thuật toán đợi luỹ thừa bị rút gọn có độ trễ để tránh làm quá tải dịch vụ.

Thuật toán thời gian đợi luỹ thừa bị cắt

Tính toán độ trễ khi thử lại bằng công thức sau:

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

Sử dụng các tham số sau để tính toán độ trễ khi thử lại:

  • initial_delay: độ trễ thử lại ban đầu (ví dụ: 1 giây).
  • max_delay: giới hạn tối đa của thời gian chờ (ví dụ: 32, 0 giây).
  • attempt: số lần thử lại hiện tại (0, 1, 2, ...).
  • jitter: giá trị ngẫu nhiên từ 0 đến 1 giây để ngăn chặn các đỉnh đồng bộ hoá luồng (vấn đề về đàn gia súc).

Xử lý lỗi gRPC

Các ứng dụng truy cập vào dịch vụ qua gRPC phải kiểm tra các giá trị grpc.StatusCode chuẩn.

Mã trạng thái gRPC tiêu chuẩn

Bảng sau đây liệt kê các mã trạng thái gRPC chuẩn do dịch vụ trả về và cách xử lý được đề xuất cho ứng dụng:

Mã trạng thái gRPC Trạng thái HTTP Căn nguyên Hành động được đề xuất
INVALID_ARGUMENT 400 Bad Request Chuỗi truy vấn sai định dạng, định dạng tham số không hợp lệ hoặc mặt nạ trường không hợp lệ. Không thử lại. Hãy sửa các thông số yêu cầu trước khi lặp lại.
UNAUTHENTICATED 401 Unauthorized Khoá API hoặc mã thông báo OAuth Bearer bị thiếu, hết hạn hoặc bị biến dạng. Không thử lại. Làm mới thông tin đăng nhập hoặc tạo khoá API hợp lệ.
PERMISSION_DENIED 403 Forbidden Khoá API không có quyền hoặc API Kiến thức dành cho nhà phát triển bị vô hiệu hoá trong dự án. Không thử lại. Xác minh trạng thái bật API trong Google Cloud Console.
NOT_FOUND 404 Not Found Đường dẫn đến tài liệu parent được chỉ định không tồn tại. BatchGetDocuments sẽ thất bại một cách tự động nếu không tìm thấy bất kỳ tài liệu nào được yêu cầu. Không thử lại. Xác minh tên tài nguyên của tài liệu.
RESOURCE_EXHAUSTED 429 Too Many Requests Đã vượt quá giới hạn tần suất hoặc hạn mức dự án. Thử lại bằng thuật toán thời gian đợi luỹ thừa có độ trễ ngẫu nhiên.
UNAVAILABLE 503 Service Unavailable Mạng bị ngắt kết nối tạm thời hoặc máy chủ khởi động lại. Thử lại với thời gian đợi luỹ thừa.
DEADLINE_EXCEEDED 504 Gateway Timeout Yêu cầu vượt quá thời hạn RPC đã định cấu hình trước khi hoàn tất. Thử lại với thời gian chờ RPC của máy khách tăng lên.

Hết thời gian chờ kết nối MCP và quản lý lỗi

Máy chủ MCP Developer Knowledge là một dịch vụ từ xa được lưu trữ tại https://developerknowledge.googleapis.com/mcp và được truy cập qua HTTPS (bằng cách sử dụng HTTP POST hoặc Server-Sent Events). Các tác nhân và máy chủ AI phải quản lý thời gian chờ kết nối và lỗi công cụ một cách hiệu quả.

Hết thời gian chờ thực thi công cụ

Khi một tác nhân gọi search_documents, get_documents hoặc answer_query, các lệnh gọi công cụ có thể vượt quá thời gian chờ (ví dụ: 30 giây) nếu kết nối mạng bị trễ.

Cách xử lý thời gian chờ thực thi công cụ:

  • Định cấu hình thời gian chờ của máy khách: đặt thời gian chờ thực thi công cụ thành 30 – 60 giây trong cấu hình máy khách lưu trữ MCP.
  • Xử lý tình trạng gián đoạn mạng: thử lại các yêu cầu HTTP không thành công bằng cách tăng thời gian chờ theo cấp số nhân khi gặp phải tình trạng mạng bị rớt tạm thời hoặc phản hồi HTTP 503.
  • Kiểm tra thông báo lỗi: phân tích cú pháp thông báo lỗi JSON-RPC tiêu chuẩn hoặc mã trạng thái lỗi HTTP để phân biệt các đối số không hợp lệ với tình trạng hết hạn mức.

Các phương pháp hay nhất để quản lý hạn mức

Hãy làm theo các phương pháp hay nhất này để duy trì mức sử dụng API tối ưu và tránh các giới hạn về tốc độ không mong muốn:

  1. Lưu nội dung tài liệu đã truy xuất vào bộ nhớ đệm: lưu trữ các tài liệu Markdown đã tìm nạp cục bộ hoặc trong bộ nhớ đệm (chẳng hạn như Redis) khi tạo các ứng dụng thường xuyên truy cập vào cùng một trang.
  2. Sử dụng tính năng truy xuất hàng loạt: sử dụng documents.batchGet thay vì thực thi nhiều yêu cầu documents.get tuần tự.
  3. Tối ưu hoá các trường truy vấn: chỉ yêu cầu các trường phản hồi bắt buộc bằng cách sử dụng mặt nạ trường có chọn lọc (fields=results(parent,content)).
  4. Theo dõi mức sử dụng hạn mức: theo dõi tốc độ yêu cầu API trong trang tổng quan API của Google Cloud Console.

Nội dung có liên quan