Hướng dẫn khắc phục sự cố

Hãy sử dụng hướng dẫn này để giúp bạn chẩn đoán và giải quyết các vấn đề thường gặp khi gọi API Gemini. Bạn có thể gặp phải sự cố từ dịch vụ phụ trợ API Gemini hoặc SDK ứng dụng. SDK ứng dụng của chúng tôi được tạo nguồn mở trong các kho lưu trữ sau:

Nếu bạn gặp vấn đề về khoá API, hãy đảm bảo bạn đã thiết lập khoá API đúng cách theo hướng dẫn thiết lập khoá API.

Mã lỗi dịch vụ phụ trợ của Gemini API

Bảng sau đây liệt kê các mã lỗi phụ trợ phổ biến mà bạn có thể gặp phải, cùng với nội dung giải thích về nguyên nhân và các bước khắc phục sự cố:

Mã HTTP Trạng thái Nội dung mô tả Ví dụ Giải pháp
400 INVALID_ARGUMENT Nội dung yêu cầu có định dạng không đúng. Yêu cầu của bạn có lỗi chính tả hoặc thiếu trường bắt buộc. Hãy xem tài liệu tham khảo API để biết định dạng yêu cầu, ví dụ và các phiên bản được hỗ trợ. Việc sử dụng các tính năng của phiên bản API mới hơn với điểm cuối cũ có thể gây ra lỗi.
400 FAILED_PRECONDITION Cấp miễn phí của Gemini API chưa có ở quốc gia của bạn. Vui lòng bật tính năng thanh toán cho dự án của bạn trong Google AI Studio. Bạn đang gửi yêu cầu ở một khu vực không hỗ trợ gói miễn phí và bạn chưa bật tính năng thanh toán cho dự án của mình trong Google AI Studio. Để sử dụng Gemini API, bạn cần thiết lập một gói có tính phí bằng Google AI Studio.
403 PERMISSION_DENIED Khoá API của bạn không có các quyền cần thiết. Bạn đang sử dụng sai khoá API; bạn đang cố gắng sử dụng một mô hình đã điều chỉnh mà không trải qua quy trình xác thực đúng cách. Kiểm tra để đảm bảo bạn đã đặt khoá API và có quyền truy cập phù hợp. Và hãy nhớ xác thực đúng cách để sử dụng các mô hình đã điều chỉnh.
404 NOT_FOUND Không tìm thấy tài nguyên được yêu cầu. Không tìm thấy tệp hình ảnh, âm thanh hoặc video được tham chiếu trong yêu cầu của bạn. Kiểm tra xem tất cả tham số trong yêu cầu của bạn có hợp lệ cho phiên bản API của bạn hay không.
429 RESOURCE_EXHAUSTED Bạn đã vượt quá giới hạn tốc độ. Bạn đang gửi quá nhiều yêu cầu mỗi phút bằng API Gemini cấp miễn phí. Đảm bảo bạn nằm trong giới hạn tốc độ của mô hình. Yêu cầu tăng hạn mức nếu cần.
500 NỘI BỘ Đã xảy ra lỗi không mong muốn ở phía Google. Ngữ cảnh đầu vào của bạn quá dài. Giảm ngữ cảnh đầu vào hoặc tạm thời chuyển sang một mô hình khác (ví dụ: từ Gemini 1.5 Pro sang Gemini 1.5 Flash) và xem liệu mô hình đó có hoạt động hay không. Hoặc chờ một chút rồi thử lại yêu cầu của bạn. Nếu vấn đề vẫn tiếp diễn sau khi thử lại, vui lòng báo cáo vấn đề bằng cách sử dụng nút Gửi ý kiến phản hồi trong Google AI Studio.
503 KHÔNG CÓ Dịch vụ có thể tạm thời bị quá tải hoặc ngừng hoạt động. Dịch vụ tạm thời hết công suất. Tạm thời chuyển sang một mô hình khác (ví dụ: từ Gemini 1.5 Pro sang Gemini 1.5 Flash) và xem liệu mô hình đó có hoạt động hay không. Hoặc chờ một chút rồi thử lại yêu cầu của bạn. Nếu vấn đề vẫn tiếp diễn sau khi thử lại, vui lòng báo cáo vấn đề bằng cách sử dụng nút Gửi ý kiến phản hồi trong Google AI Studio.
504 DEADLINE_EXCEEDED Dịch vụ không thể hoàn tất quá trình xử lý trong thời hạn. Câu lệnh (hoặc ngữ cảnh) của bạn quá lớn nên không thể xử lý kịp thời. Hãy đặt "thời gian chờ" lớn hơn trong yêu cầu của ứng dụng để tránh lỗi này.

Mã lỗi SDK ứng dụng

Bảng sau đây liệt kê các mã lỗi SDK ứng dụng Python phổ biến mà bạn có thể gặp phải, cùng với nội dung giải thích về nguyên nhân gây ra các lỗi đó:

Loại ngoại lệ/lỗi Lớp Mô tả
APIError google.genai.errors.APIError Các lỗi chung do API GenAI gây ra.
ClientError google.genai.errors.ClientError Lỗi máy khách do API GenAI gây ra.
ServerError google.genai.errors.ServerError Lỗi máy chủ do API GenAI gây ra.
UnknownFunctionCallArgumentError google.genai.errors.UnknownFunctionCallArgumentError Được gửi khi không thể chuyển đổi đối số lệnh gọi hàm thành chú thích tham số.
UnsupportedFunctionError google.genai.errors.UnsupportedFunctionError Được gửi khi hàm không được hỗ trợ.
FunctionInvocationError google.genai.errors.FunctionInvocationError Được gửi khi không thể gọi hàm bằng các đối số đã cho.
ValidationError pydantic.ValidationError Do Pydantic gửi ra bất cứ khi nào phát hiện lỗi trong dữ liệu đang xác thực. Xem phần Xử lý lỗi Pydantic.

Bạn cũng sẽ tìm thấy tất cả lỗi trong lớp lỗi.

Để xử lý các lỗi do SDK gây ra, bạn có thể sử dụng khối try-except:

from google.genai import errors

try:
    client.models.generate_content(
        model="invalid-model-name",
        contents="What is your name?",
    )
except errors.APIError as e:
    print(e.code) # 404
    print(e.message)

Kiểm tra các lệnh gọi API để tìm lỗi tham số mô hình

Đảm bảo các thông số mô hình của bạn nằm trong các giá trị sau:

Thông số mô hình Giá trị (dải ô)
Số lượng đề xuất 1-8 (số nguyên)
Nhiệt độ 0,0-1,0
Số mã thông báo đầu ra tối đa Sử dụng get_model (Python) để xác định số lượng mã thông báo tối đa cho mô hình mà bạn đang sử dụng.
TopP 0.0-1.0

Ngoài việc kiểm tra các giá trị tham số, hãy đảm bảo bạn đang sử dụng đúng phiên bản API (ví dụ: /v1 hoặc /v1beta) và mô hình hỗ trợ các tính năng bạn cần. Ví dụ: nếu một tính năng đang ở bản phát hành Beta, thì tính năng đó sẽ chỉ có trong phiên bản API /v1beta.

Kiểm tra xem bạn có đúng mẫu không

Đảm bảo bạn đang sử dụng một mô hình được hỗ trợ được liệt kê trên trang mô hình của chúng tôi.

Vấn đề về an toàn

Nếu bạn thấy một lời nhắc bị chặn do chế độ cài đặt an toàn trong lệnh gọi API, hãy xem xét lời nhắc đó liên quan đến các bộ lọc mà bạn đặt trong lệnh gọi API.

Nếu bạn thấy BlockedReason.OTHER, thì truy vấn hoặc phản hồi có thể vi phạm điều khoản dịch vụ hoặc không được hỗ trợ.

Vấn đề về việc đọc thuộc lòng

Nếu bạn thấy mô hình ngừng tạo đầu ra do lý do RECITATION, thì điều này có nghĩa là đầu ra của mô hình có thể giống với một số dữ liệu nhất định. Để khắc phục vấn đề này, hãy cố gắng làm cho lời nhắc / bối cảnh trở nên độc đáo nhất có thể và sử dụng nhiệt độ cao hơn.

Cải thiện đầu ra của mô hình

Để có kết quả đầu ra của mô hình chất lượng cao hơn, hãy tìm hiểu cách viết câu lệnh có cấu trúc hơn. Trang giới thiệu về thiết kế lời nhắc giới thiệu một số khái niệm, chiến lược và phương pháp hay nhất để bạn bắt đầu.

Nếu có hàng trăm ví dụ về các cặp đầu vào/đầu ra tốt, bạn cũng có thể cân nhắc việc điều chỉnh mô hình.

Tìm hiểu về giới hạn mã thông báo

Hãy đọc Hướng dẫn về mã thông báo để hiểu rõ hơn về cách tính mã thông báo và giới hạn của mã thông báo.

Vấn đề đã biết

  • API này chỉ hỗ trợ một số ngôn ngữ. Việc gửi câu lệnh bằng ngôn ngữ không được hỗ trợ có thể tạo ra các câu trả lời không mong muốn hoặc thậm chí bị chặn. Hãy xem các ngôn ngữ có sẵn để biết thông tin cập nhật.

Báo cáo lỗi

Tham gia thảo luận trên diễn đàn dành cho nhà phát triển AI của Google nếu bạn có thắc mắc.