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

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 các SDK ứng dụng. Các 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 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 thường gặp ở phần phụ trợ 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 sai định dạ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 về 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 một điểm cuối cũ hơn có thể gây ra lỗi.
400 FAILED_PRECONDITION Bậc miễn phí của Gemini API chưa được cung cấp ở 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ợ cấp 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 thích hợp. Kiểm tra để đảm bảo bạn đã đặt khoá API 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 được đ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 đề cập 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 về tốc độ. Bạn đang gửi quá nhiều yêu cầu mỗi phút bằng Gemini API cấp miễn phí. Xác minh rằng bạn đang 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 với Google. Bối 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) để xem có hiệu quả không. Hoặc đợi một lát rồi thử lại yêu cầu. 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 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ụ này 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) để xem vấn đề có được giải quyết hay không. Hoặc đợi một lát rồi thử lại yêu cầu. 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 nên không xử lý kịp. Đặt "thời gian chờ" dài hơn trong yêu cầu của máy khách để 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 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 ứng cử 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 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 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 ở 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

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 với các mô hình 2.5

Nếu bạn nhận thấy độ trễ 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ì 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 đang ư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 này.

Hãy tham khảo trang suy nghĩ để biết hướng dẫn và mã mẫu.

Vấn đề 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 kết quả do lý do TRÍ NHỚ, thì điều này có nghĩa là kết quả 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ảm hoặc loại bỏ chúng.

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ề cách 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.
  • Hãy thử thêm các chỉ dẫn như sau vào câu lệnh hệ thống: 
                FOR TABLE HEADINGS, IMMEDIATELY ADD ' |' AFTER THE TABLE HEADING.
  • Hãy thử điều chỉnh nhiệt độ. Nhiệt độ cao hơn (>= 0,8) thường giúp loại bỏ các đoạn văn lặp lại hoặc trùng lặp trong đầu ra.
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 unicode hoặc các dãy ký tự 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.
  • Kiểm tra và thay thế các chuỗi thoát bị cấm bằng ký tự UTF-8 trong câu lệnh. Ví dụ: chuỗi thoát \u trong các ví dụ JSON có thể khiến mô hình sử dụng các chuỗi đó trong đầu ra của mô hình.
  • Hướng dẫn mô hình về các trường hợp thoát được phép. Thêm một chỉ dẫn hệ thống như sau: 
                In quoted strings, the only allowed escape sequences are \\, \n, and \". Instead of \u escapes, use UTF-8.
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.
  • Đừng chỉ định thứ tự của các trường trong câu lệnh.
  • Hãy đặt tất cả các trường đầu ra là bắt buộc.
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.
  • Nếu bạn bật tính năng tư duy, hãy tránh đưa ra các chỉ dẫn rõ ràng về cách suy nghĩ để giải quyết một vấn đề trong hướng dẫn. Chỉ cần yêu cầu kết quả cuối cùng.
  • Thử nhiệt độ cao hơn >= 0,8.
  • Thêm các chỉ dẫn như "Hãy súc tích", "Đừng lặp lại" hoặc "Chỉ đưa ra câu trả lời một lần".

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

Để có kết quả đầu ra chất lượng cao hơn, hãy thử viết các câu lệnh có cấu trúc hơn. Trang hướng dẫn kỹ thuật về 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 đếm mã thông báo và hạn mức của mã thông báo.

Vấn đề đã biết

  • API này chỉ hỗ trợ một số ngôn ngữ nhất định. 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.