Hãy 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. Các SDK ứng dụng của chúng tôi được cung cấp dưới dạng nguồn mở trong các kho lưu trữ sau:
Nếu bạn gặp vấn đề về khoá API, hãy kiểm tra để đảm bảo 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 thông tin tham khảo đầy đủ về tất cả mã lỗi, bao gồm cả mã trạng thái HTTP, mã bị 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 nhận được lỗi cho biết 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 khoảng 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.
Các SDK ứng dụng chính thức cho Gemini API (chẳng hạn như Python SDK) theo mặc định có logic tự động thử lại với độ trễ luỹ thừa để xử lý các lỗi tạm thời như hết thời gian chờ, sự cố về mạng và giới hạn về tốc độ (mã trạng thái 429 và 5xx). Ví dụ: Python SDK tự động thử lại các lỗi tạm thời tối đa 4 lần với độ trễ ban đầu khoảng 1 giây và độ trễ tối đa là 60 giây.
Nếu bạn đang thực hiện các yêu cầu trực tiếp đến API REST 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 cơ chế giảm thời gian chờ theo cấp số nhâ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 biên độ: Thêm "biên độ" ngẫu nhiên vào độ 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 (chẳng hạn như
429,408hoặc5xx). Đừng thử lại khi gặp lỗi phía máy khách (chẳng hạn như400hoặc403) vì những lỗi này cho biết các vấn đề như khoá API không hợp lệ hoặc cú pháp không chính xác. - Đặt số lần thử lại tối đa: Xác định số lần thử lại tối đa để ngăn chặn 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 thông 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 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 rằng bạn đang sử dụng phiên bản API chính xác (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ó đúng mẫu 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ễ hoặc mức sử dụng mã thông báo cao hơn khi dùng mô hình tư duy
Độ trễ cao hơn hoặc mức sử dụng mã thông báo cao hơn thường xảy ra vì 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 tư duy mặc định.
Các mô hình tư duy tạo ra mã thông báo lý 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 tiêu thụ 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à các đoạn mã mẫu, hãy xem hướng dẫn tư duy.
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 mà bạn đã đặt trong lệnh gọi API.
Nếu bạn thấy BlockedReason.OTHER, thì có thể truy vấn hoặc câu trả lời đó 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 TRÍCH DẪN, 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 tạo 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ỏ các mã thông báo đó.
| Mô tả | Nguyên nhân | Giải pháp thay thế được đề 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 quá 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, bạn không cần phải căn chỉnh trong Markdown để 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ể về việc tạo bảng Markdown. Cung cấp ví dụ tuân thủ các nguyên tắc đó. Bạn cũng có thể thử điều chỉnh nhiệt độ. Để tạo mã hoặc đầu ra có cấu trúc cao như bảng Markdown, nhiệt độ cao đã cho thấy hiệu quả 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 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 ngang 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. |
|
Ký tự xuống dòng lặp lại (\n) trong đầu ra có cấu trúc
|
Khi đầu vào mô hình chứa các chuỗi unicode hoặc chuỗi thoát như \u hoặc \t, điều này có thể dẫn đến việc lặp lại các dòng mớ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ự khác cho các trường so 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 những 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 hướng 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 đầ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 có thể khiến một số khoá API 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 các khoá của bạn có bị ảnh hưởng hay không
Nếu biết khoá của mình đã bị lộ, bạn sẽ không thể tiếp tục dùng khoá đó với Gemini API. 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 đượ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 mối liên kết tích hợp Gemini API bằng Google AI Studio. Bạn nên xem xét kỹ các phương pháp quản lý khoá API để đảm bảo khoá mới của bạn được bảo mật và không bị lộ công khai.
Các khoản phí ngoài dự kiến do lỗ hổng
Gửi yêu cầu hỗ trợ về việc 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ỉ
Nếu khoá API của tôi bị lộ, Google sẽ giúp bảo vệ tài khoản của tôi khỏi tình trạng vượt quá chi phí và hành vi sai trái như thế nào?
- Chúng tôi đang tiến tới việc phát hành khoá API khi bạn yêu cầu một 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 trường hợp sử dụng khoá chéo ngoài ý muốn.
- Chúng tôi sẽ chặn các khoá API bị rò rỉ và được dùng với Gemini API theo mặc định, giúp ngăn chặn hành vi sai trái về 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 liên hệ với bạn 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 đầu ra của mô hình
Để có kết quả đầu ra chất lượng cao hơn từ mô hình, hãy thử viết các 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 về giới hạn mã thông báo
Hãy đọ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 tính mã thông báo và hạn mức 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 các ngôn ngữ không được hỗ trợ có thể tạo ra những câu trả lời không mong muốn hoặc thậm chí bị chặn. 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 AI của Google nếu bạn có thắc mắc.