Khắc phục lỗi 403 PermissionDenied: Vertex AI API chưa được kích hoạt

Rào cản triển khai lúc 2 giờ sáng

Bạn vừa viết xong một đoạn mã Python để tích hợp Gemini 1.5 Pro thông qua Vertex AI. Mọi thứ trông thật hoàn hảo trong IDE của bạn. Bạn chạy mã, mong đợi một phản hồi AI tuyệt vời, nhưng terminal của bạn lại báo lỗi 403. Thật bực bội, nhưng cách khắc phục thường chỉ mất vài cú nhấp chuột hoặc một câu lệnh duy nhất.

Thông báo lỗi chính xác

google.api_core.exceptions.PermissionDenied: 403 Vertex AI API has not been used in project PROJECT_ID before or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/aiplatform.googleapis.com/overview?project=PROJECT_ID

Bạn sẽ thấy lỗi này thường xuyên nhất khi khởi tạo một dự án Google Cloud mới. Theo mặc định, GCP giữ cho hầu hết các dịch vụ ở trạng thái ngủ. Đây là một biện pháp bảo mật giúp ngăn chặn việc phát sinh chi phí ngoài ý muốn, nhưng nó có nghĩa là bạn không thể bắt đầu gọi các endpoint mà không thực hiện một vài bước thiết lập.

Gỡ lỗi lỗi 403

Trước tiên, hãy kiểm tra kỹ PROJECT_ID của bạn. Nghe có vẻ đơn giản, nhưng các nhà phát triển thường xuyên sử dụng dự án mặc định được thiết lập trong cấu hình gcloud của họ, vốn có thể là một sandbox cũ hoặc một tài khoản khách hàng hoàn toàn khác. Chỉ cần một chuỗi ký tự sai ở đây, mọi thứ sẽ không hoạt động.

Chạy lệnh sau để xem CLI của bạn hiện đang nhắm mục tiêu đến dự án nào:

gcloud config get-value project

Nếu ID chính xác, vấn đề nằm ở khâu quản trị. API đơn giản là đang bị tắt. Google Cloud yêu cầu bạn phải chọn tham gia (opt-in) rõ ràng cho mọi dịch vụ trước khi nó xử lý các yêu cầu, ngay cả khi bạn là chủ sở hữu dự án với đầy đủ quyền hạn.

Giải pháp: Bật API

Bạn có hai cách để khắc phục điều này. Console là lựa chọn tuyệt vời để sửa lỗi một lần, trong khi CLI sẽ tốt hơn cho việc tự động hóa.

Cách 1: Sử dụng Google Cloud Console

Sao chép URL cụ thể từ thông báo lỗi của bạn. Nó thường bao gồm ID dự án duy nhất của bạn.
Dán nó vào trình duyệt. Đảm bảo bạn đã đăng nhập vào đúng tài khoản Google, vì các phiên đăng nhập nhiều tài khoản thường chuyển hướng đến bảng điều khiển dự án sai.
Nhấp vào nút Enable.
Đợi khoảng 60 đến 90 giây. Việc kích hoạt API cần một chút thời gian để lan truyền trên các vị trí biên toàn cầu của Google.

Cách 2: Sử dụng gcloud CLI

Những người yêu thích terminal có thể bỏ qua hoàn toàn trình duyệt. Phương pháp này nhanh hơn nhiều khi bạn đang quản lý nhiều dự án hoặc làm việc trên máy chủ từ xa qua SSH.

# Xác thực phiên làm việc của bạn
gcloud auth login

# Đảm bảo bạn đang làm việc đúng dự án
gcloud config set project YOUR_PROJECT_ID

# Bật dịch vụ Vertex AI
gcloud services enable aiplatform.googleapis.com

Khắc phục quyền IAM

Bật API mới chỉ là một nửa chặng đường. Nếu bạn vẫn thấy lỗi 403 sau khi bật dịch vụ, danh tính của bạn—cho dù đó là email cá nhân hay Service Account—có khả năng thiếu các quyền phù hợp. Đối với các công việc liên quan đến Vertex AI, thông thường bạn cần vai trò roles/aiplatform.user.

Cấp quyền này nhanh chóng thông qua CLI:

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
    --member="serviceAccount:your-service-account@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/aiplatform.user"

Nếu bạn đang chạy script cục bộ và chưa thiết lập khóa service account, hãy đảm bảo bạn đã làm mới thông tin xác thực cục bộ của mình:

gcloud auth application-default login

Xác minh việc khắc phục

Kiểm tra kết nối của bạn với đoạn mã Python tối giản này. Nó sẽ cố gắng khởi tạo Vertex AI SDK và tạo một phản hồi đơn giản. Nếu thành công, môi trường của bạn đã chính thức sẵn sàng cho môi trường production.

import vertexai
from vertexai.generative_models import GenerativeModel

PROJECT_ID = "your-project-id"
REGION = "us-central1"

vertexai.init(project=PROJECT_ID, location=REGION)

try:
    model = GenerativeModel("gemini-1.5-flash")
    response = model.generate_content("Xác nhận API đang hoạt động.")
    print(f"Thành công! Phản hồi: {response.text}")
except Exception as e:
    print(f"Xác minh thất bại: {e}")

Bài học rút ra & Cách phòng ngừa

GCP có cơ chế "mặc định là bảo mật". Không có gì được bật cho đến khi bạn yêu cầu. Khi xây dựng cơ sở hạ tầng AI mới, hãy luôn bao gồm bước bật API trong các script Terraform hoặc tài liệu hướng dẫn thiết lập. Điều này giúp ngăn nhóm của bạn gặp phải rào cản 403 tương tự sau này.

Nếu bạn đang triển khai lên một máy ảo Linux, hãy để ý đến quyền truy cập tệp cho các khóa JSON của bạn. Tôi đã thấy các nhà phát triển dành hàng giờ để gỡ lỗi 403 mà thực chất chỉ là do hệ điều hành ngăn ứng dụng đọc khóa service account. Sử dụng Unix Permissions Calculator có thể giúp bạn xác minh rằng các khóa của mình được đặt thành 600—riêng tư và bảo mật, nhưng ứng dụng vẫn có thể đọc được. Kiểm tra nhỏ này sẽ giúp tránh được những rắc rối lớn trong quá trình đẩy lên production.

Danh sách kiểm tra dự án mới của bạn nên luôn bao gồm:

Bật aiplatform.googleapis.com.
Bật generativelanguage.googleapis.com cho các tính năng Gemini cụ thể.
Gán vai trò Vertex AI User cho service account liên quan.
Làm mới thông tin xác thực application-default trên máy cục bộ của bạn.