Hãy sử dụng hướng dẫn này để 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 phải vấn đề từ dịch vụ phụ trợ Gemini API hoặc SDK ứng dụng. SDK ứng dụng của chúng tôi là mã 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
Để xem tài liệu tham khảo đầy đủ về tất cả mã lỗi, bao gồm cả mã trạng thái HTTP, mã chặn tạo và mã lỗi nội dung, hãy xem trang Lỗi API.
Chiến lược thử lại
Nếu bạn nhận được lỗi cho biết rằng bạn nên thử lại yêu cầu (chẳng hạn như 429 RESOURCE_EXHAUSTED hoặc 503 UNAVAILABLE), bạn nên triển khai chiến lược thời gian đợi luỹ thừa. Điều này có nghĩa là bạn đợi một thời gian ngắn trước lần thử lại đầu tiên, sau đó tăng dần thời gian chờ giữa các lần thử lại tiếp theo.
SDK ứng dụng chính thức cho Gemini API, chẳng hạn như Python SDK, bao gồm logic thử lại tự động với thời gian đợi luỹ thừa theo mặc định để xử lý các lỗi tạm thời như hết thời gian chờ, sự cố mạng và giới hạn tốc độ (mã trạng thái 429 và 5xx). Ví dụ: SDK Python tự động thử lại tối đa 4 lần đối với các lỗi tạm thời, với độ trễ ban đầu là khoảng 1 giây và độ trễ tối đa là 60 giây.
Nếu bạn đang gửi yêu cầu API REST trực tiếp hoặc tuỳ chỉnh logic thử lại, hãy làm theo các phương pháp hay nhất sau đây để tăng khả năng yêu cầu thành công và tránh làm quá tải dịch vụ:
- Sử dụng thuật toán đợi luỹ tuyến: Chờ một khoảng thời gian ngắn trước lần thử lại đầu tiên (ví dụ: 1 giây), sau đó tăng độ trễ theo cấp số nhân (ví dụ: 2 giây, 4 giây, 8 giây).
- Thêm độ trễ: Thêm "độ trễ" ngẫu nhiên vào thời gian trễ để giúp ngăn tất cả ứng dụng khách thử lại cùng một lúc.
- Thử lại khi gặp lỗi cụ thể: Chỉ thử lại khi gặp lỗi tạm thời (như
429,408hoặc5xx). Đừng thử lại khi gặp lỗi phía máy khách (như400,402hoặc403) vì những lỗi này cho biết các vấn đề như khoá API không hợp lệ, hết tín dụng trả trước hoặc cú pháp không hợp lệ. - Đặt số lần thử lại tối đa: Xác định số lần thử lại tối đa để tránh vòng lặp vô hạn.
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ố 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 trang mô hình để xác định số lượng mã thông báo tối đa cho mô hình 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 thử nghiệm, 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
Xác minh rằng bạn đang sử dụng một mẫu được hỗ trợ có trong danh sách trên trang mẫu của chúng tôi.
Độ trễ hoặc mức sử dụng mã thông báo cao hơn khi dùng mô hình tư duy
Độ trễ hoặc mức sử dụng mã thông báo cao hơn thường xảy ra do các mô hình Gemini 3.x được bật tính năng suy nghĩ theo mặc định. Các mô hình Gemini 2.5 không còn được dùng nữa cũng sử dụng chế độ suy nghĩ mặc định.
Các mô hình tư duy tạo ra mã thông báo suy luận nội bộ để cải thiện chất lượng. Quá trình suy luận này làm tăng cả độ trễ phản hồi và tổng mức sử dụng mã thông báo.
Nếu ưu tiên độ trễ thấp hơn hoặc cần giảm thiểu chi phí, bạn có thể giảm mức độ suy nghĩ hoặc tắt tính năng suy nghĩ.
Để biết thông tin chi tiết về cấu hình và mã mẫu, hãy xem hướng dẫn về suy nghĩ.
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 xét câu lệnh đó theo các bộ lọc bạn đặt trong lệnh gọi API.
Nếu bạn thấy BlockedReason.OTHER, thì câu hỏi hoặc câu trả lờ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 vì 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 đưa ra câu lệnh/bối cảnh độ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ỏ chúng.
| Mô tả | Nguyên nhân | Giải pháp đề xuất |
|---|---|---|
| Dấu gạch nối 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 để hiển thị 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ể để 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 độ. Để tạo mã hoặc kết quả 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 bộ nguyên tắc mẫu mà bạn có thể thêm vào câu lệnh để ngăn chặ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 nối lặp lại, điều này xảy ra khi mô hình cố gắng căn chỉnh nội dung của bảng một cách trực quan. Bạn không cần phải căn chỉnh trong Markdown để hiển thị chính xác. |
|
Dòng mới lặp lại (\n) trong kết quả có cấu trúc
|
Khi dữ liệu đầu vào của mô hình chứa unicode hoặc trình tự thoát như
\u hoặc \t, thì 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 đầu ra có cấu trúc | Khi đầu ra của mô hình có thứ tự các trường khác với giản đồ 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. |
|
| Gọi công cụ lặp lại | Điều này có thể xảy ra nếu mô hình mất ngữ 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 nội dung này vào cuối chỉ dẫn hệ thống:
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ả 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. |
|
Dự án bị hạn chế hoặc không hoạt động
Nếu các yêu cầu API của bạn trả về 403 PERMISSION_DENIED ("Dự án của bạn đã bị từ chối quyền truy cập") hoặc trạng thái dự án của bạn là Bị hạn chế, Không có cấp miễn phí, Cần thanh toán hoặc Không có sẵn trong Google AI Studio, hãy kiểm tra xem phần nào sau đây áp dụng cho dự án của bạn:
Không thể sử dụng Gemini API cấp miễn phí
Không phải dự án hoặc tài khoản Google Cloud nào cũng đủ điều kiện sử dụng Gemini API cấp miễn phí. Nếu dự án của bạn bị hạn chế sử dụng cấp miễn phí:
- Việc tạo khoá API mới trong cùng một dự án sẽ không giải quyết được lỗi này. Google đánh giá điều kiện sử dụng ở cấp dự án trên Google Cloud.
- Để sử dụng Gemini API trong dự án này, bạn phải nâng cấp lên bậc có tính phí bằng cách liên kết một tài khoản thanh toán trên Cloud đang hoạt động.
- Lưu ý: Việc nâng cấp dự án lên cấp có tính phí sẽ không mở khoá hạn mức của cấp miễn phí. Google tính phí sử dụng cấp có tính phí theo giá của Gemini API hoặc khấu trừ phí này vào khoản tín dụng đủ điều kiện của Google Cloud.
Bạn cần thanh toán cho tài khoản thanh toán trên Cloud
Nếu dự án của bạn đã được liên kết với một tài khoản thanh toán trên Cloud và cho thấy trạng thái Cần thanh toán (hoặc trả về mã lỗi 403 PERMISSION_DENIED cho biết có số dư chưa thanh toán):
- Truy cập vào trang Thanh toán của AI Studio hoặc Bảng điều khiển thanh toán của Google Cloud để thanh toán mọi khoản nợ quá hạn hoặc cập nhật phương thức thanh toán.
- Sau khi tài khoản thanh toán của bạn trở lại trạng thái tốt, dự án của bạn sẽ tự động lấy lại quyền truy cập API.
Khoá API bị rò rỉ hoặc bị chặn
Nếu trạng thái lỗi 403 PERMISSION_DENIED cho biết khoá API của bạn bị báo cáo là bị rò rỉ hoặc bị chặn:
- Truy cập vào trang Khoá API của AI Studio để tạo khoá API mới và cập nhật thông tin xác thực của ứng dụng.
- Tuyệt đối không nhúng khoá API trực tiếp vào mã phía máy khách hoặc kho lưu trữ công khai.
Tạm ngưng dự án hoặc tài khoản thanh toán do vi phạm chính sách
Nếu Google tạm ngưng dự án của bạn trên Google Cloud hoặc tài khoản Cloud Billing do vi phạm chính sách, hãy kiểm tra địa chỉ email được liên kết. Truy cập vào Google Cloud Console để xem mọi thông báo tạm ngưng và làm theo Nguyên tắc tạm ngưng dự án.
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à việc cần làm trong trường hợp đó.
Tìm hiểu lý do khoá bị chặn
Chúng tôi đã xác định được một lỗ hổng bảo mật khiến một số khoá API có thể đã bị lộ 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 những 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 có khoá API nào của bạn 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 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 xét các phương pháp quản lý khoá API để đảm bảo rằng 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í ngoài dự kiế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 cho bạn ngay khi có thông tin cập nhật.
Các biện pháp bảo mật của Google đối với 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 chi phí vượt mức và hành vi sai trái như thế nào nếu khoá API của tôi bị rò rỉ?
- Chúng tôi đang chuyển sang 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ỉ được dùng cho 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 trường hợp sử dụng khoá chéo ngoài ý muốn.
- Theo mặc định, chúng tôi sẽ chặn các khoá API bị rò rỉ và được dùng với Gemini API, giúp ngăn chặn hành vi sử dụng sai trái chi phí và dữ liệu ứng dụng của bạn.
- Bạn có thể tìm thấy trạng thái của khoá API trong Google AI Studio. 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ể xử lý ngay lập tức.
Cải thiện đầu ra của mô hình
Để có đầu ra của mô hình chất lượng cao hơn, hãy thử viết câu lệnh có cấu trúc rõ ràng hơn. Trang hướng dẫn 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 để giúp bạn bắt đầu.
Tìm hiểu về giới hạn mã thông báo
Đọc Hướng dẫn về mã thông báo của chúng tôi để hiểu rõ hơn về cách đếm 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âu trả lời không mong muốn hoặc thậm chí bị chặn. Xem trang thông tin chi tiết về mô hình để 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 AI của Google nếu bạn có thắc mắc.