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 bạn gọi Gemini API. Bạn có thể gặp vấn đề với dịch vụ phụ trợ Gemini API hoặc SDK ứng dụng. SDK ứng dụng của chúng tôi là nguồn mở trong các kho lưu trữ sau:
Nếu bạn gặp vấn đề về khoá API, hãy xác minh rằng 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ợ Gemini API
Bảng sau đây liệt kê các mã lỗi phụ trợ thường gặp 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:
| 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 chính xác. | Có lỗi chính tả hoặc thiếu trường bắt buộc trong yêu cầu của bạn. | Hãy tham khảo tài liệu tham chiếu 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ũ hơn có thể gây ra lỗi. |
| 400 | FAILED_PRECONDITION | Gói miễn phí của Gemini API không hoạt động ở 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 đưa ra 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 gói trả 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 thông qua quy trình xác thực thích hợp. | Kiểm tra để đảm bảo khoá API của bạn được thiết lập và có quyền truy cập phù hợp. Đồng thời, hãy nhớ thực hiện quy trình xác thực thích hợp để 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ả các tham số trong yêu cầu của bạn có hợp lệ đối với 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ần suất yêu cầu. | Bạn đang gửi quá nhiều yêu cầu mỗi phút bằng Gemini API gói miễn phí. | Xác minh rằng bạn đang nằm trong giới hạn tần suất yêu cầu của mô hình. Yêu cầu tăng hạn mức nếu cần. |
| 499 | CANCELLED | Thao tác đã bị huỷ, thường là do người gọi. | Ứng dụng đã đóng kết nối trước khi API có thể hoàn tất việc phản hồi. | Kiểm tra xem máy khách hoặc cơ sở hạ tầng mạng của bạn có đóng kết nối sớm hay không (ví dụ: do thời gian chờ ở phía máy khách). |
| 500 | INTERNAL | Đã xảy ra lỗi không mong muốn với Google. | Bối cảnh đầu vào của bạn quá dài. | Kiểm tra trang trạng thái Gemini API để biết mọi sự cố đang diễn ra. Giảm bối 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 2.5 Pro sang Gemini 2.5 Flash) và xem liệu mô hình đó có hoạt động hay không. Hoặc đợi một lá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 bạn thử lại, vui lòng báo cáo vấn đề đó bằng nút Gửi ý kiến phản hồi trong Google AI Studio. |
| 503 | UNAVAILABLE | 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 dung lượng. | Kiểm tra trang trạng thái Gemini API để biết mọi sự cố đang diễn ra. Tạm thời chuyển sang một mô hình khác (ví dụ: từ Gemini 2.5 Pro sang Gemini 2.5 Flash) và xem liệu mô hình đó có hoạt động hay không. Hoặc đợi một lá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 bạn thử lại, vui lòng báo cáo vấn đề đó bằ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 bối cảnh) của bạn quá lớn để xử lý kịp thời. | Đặ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. |
Kiểm tra các lệnh gọi API để tìm lỗi tham số mô hình
Xác minh rằng các tham số mô hình của bạn nằm trong các giá trị sau:
| Tham số mô hình | Giá trị (phạm vi) |
| Số ứng viên | 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 trang mô hình để xác định số 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 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 ở giai đoạ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ó mô hình phù hợp hay không
Xác minh rằng bạn đang sử dụng một mô hình được hỗ trợ có trong trang mô hình của chúng tôi.
Độ trễ cao hơn hoặc mức sử dụng mã thông báo cao hơn với các mô hình 2.5
Nếu bạn nhận thấy độ trễ cao hơn hoặc mức sử dụng mã thông báo cao hơn với các mô hình 2.5 Flash và Pro, thì điều này có thể là do các mô hình này được bật tính năng suy nghĩ theo mặc định để nâng cao chất lượng. Nếu bạn ưu tiên tốc độ hoặc cần giảm thiểu chi phí, bạn có thể điều chỉnh hoặc tắt tính năng suy nghĩ.
Hãy tham khảo trang suy nghĩ để được hướng dẫn và xem mã mẫu.
Vấn đề về an toàn
Nếu bạn thấy một câu lệnh bị chặn do chế độ cài đặt an toàn trong lệnh gọi API, hãy xem lại câu lệnh đó theo 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 trích dẫn
Nếu bạn thấy mô hình ngừng tạo kết quả đầu ra do lý do RECITATION (TRÍCH DẪN), thì điều này có nghĩa là kết quả đầu ra của mô hình có thể giống với một số dữ liệu. Để khắc phục vấn đề này, hãy cố gắng làm cho câu lệnh / bối cảnh trở nên độc đáo nhất có thể và sử dụng nhiệt độ cao hơn.
Vấn đề về mã thông báo lặp lại
Nếu bạn thấy các mã thông báo đầu ra lặp lại, hãy thử các đề xuất sau để giúp giảm hoặc loại bỏ các mã thông báo đó.
| Nội dung mô tả | Nguyên nhân | Giải pháp đề xuất |
|---|---|---|
| Dấu gạch ngang lặp lại trong bảng Markdown | Điều này có thể xảy ra khi nội dung của bảng dài vì mô hình cố gắng tạo một bảng Markdown được căn chỉnh trực quan. Tuy nhiên, việc căn chỉnh trong Markdown là không cần thiết để kết xuất chính xác. |
Thêm hướng dẫn vào câu lệnh để cung cấp cho mô hình các nguyên tắc cụ thể cho việc tạo bảng Markdown. Cung cấp các ví dụ tuân theo những nguyên tắc đó. Bạn cũng có thể thử điều chỉnh nhiệt độ. Đối với việc tạo mã hoặc kết quả đầu ra có cấu trúc cao như bảng Markdown, nhiệt độ cao đã cho thấy hiệu quả tốt hơn (>= 0,8). Sau đây là một ví dụ về bộ nguyên tắc mà bạn có thể thêm vào câu lệnh để ngăn vấn đề này:
# 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.
|
| Mã thông báo lặp lại trong bảng Markdown | Tương tự như dấu gạch ngang lặp lại, điều này xảy ra khi mô hình cố gắng căn chỉnh trực quan nội dung của bảng. Việc căn chỉnh trong Markdown là không cần thiết để kết xuất chính xác. |
|
Dòng mới lặp lại (\n) trong kết quả đầu ra có cấu trúc
|
Khi dữ liệu đầu vào của mô hình chứa unicode hoặc dãy ký tự thoát như
\u hoặc \t, điều này có thể dẫn đến các dòng mới lặp lại.
|
|
| Văn bản lặp lại khi sử dụng kết quả đầu ra có cấu trúc | Khi kết quả đầu ra của mô hình có thứ tự khác cho các trường so với lược đồ có cấu trúc đã xác định, điều này có thể dẫn đến việc lặp lại văn bản. |
|
| Lặp lại lệnh gọi công cụ | Điều này có thể xảy ra nếu mô hình mất bối cảnh của các suy nghĩ trước đó và/hoặc gọi một điểm cuối không có sẵn mà mô hình buộc phải gọi. |
Hướng dẫn mô hình duy trì trạng thái trong quá trình suy nghĩ.
Thêm hướng dẫn này vào cuối hướng dẫn hệ thống của bạn:
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.
|
| Văn bản lặp lại không thuộc kết quả đầu ra có cấu trúc | Điều này có thể xảy ra nếu mô hình bị kẹt ở một yêu cầu mà mô hình không thể giải quyết. |
|
Khoá API bị chặn hoặc không hoạt động
Phần này mô tả cách kiểm tra xem khoá Gemini API của bạn có bị chặn hay không và cách xử lý vấn đề này.
Tìm hiểu lý do khoá bị chặn
Chúng tôi đã xác định một lỗ hổng bảo mật mà một số khoá API có thể đã bị công khai. Để bảo vệ dữ liệu của bạn và ngăn chặn hành vi truy cập trái phép, chúng tôi đã chủ động chặn các khoá bị rò rỉ đã biết này truy cập vào Gemini API.
Xác nhận xem khoá của bạn có bị ảnh hưởng hay không
Nếu khoá của bạn bị rò rỉ, bạn sẽ không thể sử dụng khoá đó với Gemini API nữa. Bạn có thể sử dụng Google AI Studio để xem liệu có khoá API nào bị chặn gọi Gemini API hay không và tạo khoá mới. Bạn cũng có thể thấy lỗi sau đây được trả về khi cố gắng sử dụng các khoá này:
Your API key was reported as leaked. Please use another API key.
Hành động đối với khoá API bị chặn
Bạn nên tạo khoá API mới cho các hoạt động tích hợp Gemini API bằng Google AI Studio. Bạn nên xem lại các phương pháp quản lý khoá API để đảm bảo các khoá mới của bạn được bảo mật và không bị công khai.
Các khoản phí không mong muốn do lỗ hổng bảo mật
Gửi yêu cầu hỗ trợ thanh toán. Nhóm thanh toán của chúng tôi đang xử lý vấn đề này và chúng tôi sẽ thông báo thông tin cập nhật sớm nhất có thể.
Các biện pháp bảo mật của Google đối với các khoá bị rò rỉ
Google sẽ giúp bảo mật tài khoản của tôi khỏi tình trạng vượt quá chi phí và lạm dụng như thế nào nếu khoá API của tôi bị rò rỉ?
- Chúng tôi đang chuyển sang việc cấp khoá API khi bạn yêu cầu khoá mới bằng Google AI Studio. Theo mặc định, khoá này sẽ chỉ giới hạn ở Google AI Studio và không chấp nhận khoá từ các dịch vụ khác. Điều này sẽ giúp ngăn chặn mọi việc sử dụng khoá ngoài ý muốn.
- Chúng tôi đang chặn các khoá API bị rò rỉ và được sử dụng với Gemini API theo mặc định, giúp ngăn chặn hành vi lạm dụng chi phí và dữ liệu ứng dụng của bạn.
- Bạn có thể xem trạng thái của khoá API trong Google AI Studio và chúng tôi sẽ chủ động thông báo khi phát hiện khoá API của bạn bị rò rỉ để bạn có thể hành động ngay lập tức.
Cải thiện kết quả đầ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 khám phá cách viết câu lệnh có cấu trúc hơn. Trang hướng dẫn về thiết kế câu lệnh giới thiệu một số khái niệm, chiến lược và phương pháp hay nhất cơ bản để giúp bạn bắt đầu.
Tìm hiểu các giới hạn về mã thông báo
Đọc hướng dẫn về Mã thông báo để hiểu rõ hơn về cách đếm mã thông báo và các 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ữ được chọn. Việc gửi câu lệnh bằng các ngôn ngữ không được hỗ trợ có thể tạo ra các phản hồi không mong muốn hoặc thậm chí bị chặn. Hãy xem các ngôn ngữ được hỗ trợ để 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 nhà phát triển Google AI nếu bạn có thắc mắc.