Trình bổ trợ Google Cloud

Trình bổ trợ Google Cloud sẽ xuất dữ liệu đo từ xa và nhật ký của Firebase Genkit sang bộ công cụ hoạt động của Google Cloud.

Lắp đặt

npm i --save @genkit-ai/google-cloud

Nếu muốn chạy các flow sử dụng trình bổ trợ này trên máy, bạn cũng cần cài đặt công cụ Google Cloud CLI.

Thiết lập tài khoản Google Cloud

Trình bổ trợ này yêu cầu bạn phải có tài khoản Google Cloud (đăng ký nếu bạn chưa có tài khoản) và một dự án Google Cloud.

Trước khi thêm trình bổ trợ, hãy nhớ bật các API sau cho dự án của bạn:

Các API này phải được liệt kê trong trang tổng quan API cho dự án của bạn.

Nhấp vào đây để tìm hiểu thêm về cách bật và tắt API.

Cấu hình Genkit

Để cho phép xuất sang tính năng Theo dõi, Ghi nhật ký và Giám sát của Google Cloud, hãy thêm trình bổ trợ googleCloud vào cấu hình Genkit của bạn:

import { googleCloud } from '@genkit-ai/google-cloud';

export default configureGenkit({
  plugins: [googleCloud()],
  enableTracingAndMetrics: true,
  telemetry: {
    instrumentation: 'googleCloud',
    logger: 'googleCloud',
  },
});

Khi chạy phiên bản chính thức, dữ liệu đo từ xa của bạn sẽ tự động được xuất.

Xác thực

Trình bổ trợ này yêu cầu bạn phải có mã dự án trên Google Cloud và thông tin đăng nhập cho dự án trên Google Cloud. Nếu bạn đang chạy flow từ môi trường Google Cloud (Cloud Functions, Cloud Run, v.v.), thì mã dự án và thông tin xác thực sẽ được đặt tự động.

Thông tin xác thực mặc định của ứng dụng

Để chạy trong các môi trường khác, bạn cần đặt biến môi trường GCLOUD_PROJECT thành dự án Google Cloud và xác thực bằng công cụ gcloud:

gcloud auth application-default login

Để biết thêm thông tin, hãy xem tài liệu về Thông tin xác thực mặc định của ứng dụng.

Thông tin đăng nhập của tài khoản dịch vụ

Nếu đang sử dụng tài khoản dịch vụ và chạy bên ngoài một môi trường Google Cloud, thì bạn có thể đặt thông tin đăng nhập làm biến môi trường. Làm theo hướng dẫn tại đây để thiết lập Khoá tài khoản dịch vụ Google Cloud.

Sau khi tải tệp khoá xuống, bạn có thể chỉ định thông tin xác thực theo hai cách, cụ thể là vị trí của tệp bằng cách sử dụng biến môi trường GOOGLE_APPLICATION_CREDENTIALS hoặc sao chép trực tiếp nội dung của tệp json vào biến môi trường GCLOUD_SERVICE_ACCOUNT_CREDS.

Đường dẫn tệp:

GOOGLE_APPLICATION_CREDENTIALS = "path/to/your/key/file"

Nội dung trực tiếp:

GCLOUD_SERVICE_ACCOUNT_CREDS='{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "your-private-key-id",
  "private_key": "your-private-key",
  "client_email": "your-client-email",
  "client_id": "your-client-id",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://accounts.google.com/o/oauth2/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "your-cert-url"
}'

Cấu hình trình bổ trợ

Trình bổ trợ googleCloud() sẽ lấy một đối tượng cấu hình không bắt buộc:

{
    projectId?: string,
    telemetryConfig?: TelemetryConfig
}

mã dự án

Lựa chọn này cho phép chỉ định rõ mã dự án trên Google Cloud. Trong hầu hết các trường hợp, bạn không cần làm việc này.

telemetryConfig

Tuỳ chọn này định cấu hình thực thể OpenTelemetry NodeSDK.

import { AlwaysOnSampler } from '@opentelemetry/sdk-trace-base';

googleCloud({
  telemetryConfig: {
    forceDevExport: false, // Set this to true to export telemetry for local runs
    sampler: new AlwaysOnSampler(),
    autoInstrumentation: true,
    autoInstrumentationConfig: {
      '@opentelemetry/instrumentation-fs': { enabled: false },
      '@opentelemetry/instrumentation-dns': { enabled: false },
      '@opentelemetry/instrumentation-net': { enabled: false },
    },
    metricExportIntervalMillis: 5_000,
  },
});

forceDevExport

Tuỳ chọn này sẽ buộc Genkit xuất dữ liệu đo từ xa và nhật ký khi chạy trong môi trường dev (ví dụ: cục bộ).

bộ lấy mẫu

Đối với trường hợp không thể xuất tất cả dấu vết, OpenTelemetry cho phép lấy mẫu dấu vết.

Có 4 bộ lấy mẫu được định cấu hình trước:

autoInstrumentation và autoInstrumentationConfig

Việc bật tính năng đo lường tự động cho phép OpenTelemetry thu thập dữ liệu đo từ xa từ thư viện bên thứ ba mà không cần sửa đổi mã.

metricsExportInterval

Trường này chỉ định khoảng thời gian xuất chỉ số tính bằng mili giây.

Kiểm thử quá trình tích hợp

Khi định cấu hình trình bổ trợ, hãy sử dụng forceDevExport: true để bật tính năng xuất dữ liệu đo từ xa cho các lần chạy cục bộ. Đây là cách nhanh chóng để gửi các sự kiện đầu tiên để theo dõi trong Google Cloud.

Giám sát hoạt động sản xuất thông qua bộ công cụ vận hành của Google Cloud

Sau khi triển khai một flow, hãy chuyển đến bộ công cụ hoạt động của Google Cloud rồi chọn dự án của bạn.

Nhật ký và dấu vết

Trong trình đơn bên, hãy tìm "Ghi nhật ký" rồi nhấp vào "Trình khám phá nhật ký".

Bạn sẽ thấy tất cả nhật ký được liên kết với luồng đã triển khai, bao gồm cả console.log(). Mọi nhật ký có tiền tố [genkit] đều là nhật ký nội bộ của Genkit, chứa thông tin có thể hữu ích cho mục đích gỡ lỗi. Ví dụ: nhật ký Genkit ở định dạng Config[...] chứa siêu dữ liệu như nhiệt độ và giá trị topK để suy luận các mô hình ngôn ngữ lớn (LLM) cụ thể. Nhật ký ở định dạng Output[...] chứa phản hồi của mô hình ngôn ngữ lớn (LLM), còn nhật ký Input[...] chứa các câu lệnh. Tính năng Ghi nhật ký trên đám mây có các Danh sách kiểm soát quyền truy cập (ACL) mạnh mẽ cho phép kiểm soát chi tiết các nhật ký nhạy cảm.

Đối với các dòng nhật ký cụ thể, bạn có thể chuyển đến dấu vết tương ứng bằng cách nhấp vào biểu tượng trình đơn mở rộng rồi chọn "Xem trong chi tiết dấu vết".

Thao tác này sẽ mở ra một ngăn xem trước dấu vết để xem nhanh thông tin chi tiết về dấu vết đó. Để xem toàn bộ thông tin chi tiết, hãy nhấp vào đường liên kết "Xem trong dấu vết" ở trên cùng bên phải của ngăn.

Phần tử điều hướng nổi bật nhất trong Cloud Trace là biểu đồ tán xạ theo dõi. Tệp này chứa tất cả dấu vết được thu thập trong một khoảng thời gian nhất định.

Khi nhấp vào từng điểm dữ liệu, bạn sẽ thấy thông tin chi tiết về điểm dữ liệu đó bên dưới biểu đồ tán xạ.

Chế độ xem chi tiết chứa hình dạng quy trình, bao gồm tất cả các bước và thông tin quan trọng về thời gian. Cloud Trace có thể kết hợp mọi nhật ký liên kết với một dấu vết nhất định trong chế độ xem này. Chọn hộp "Hiển thị mục đã mở rộng" trong mục "Nhật ký & sự kiện" trình đơn thả xuống.

Chế độ xem kết quả cho phép kiểm tra chi tiết nhật ký trong bối cảnh theo dõi, bao gồm cả câu lệnh và phản hồi của mô hình ngôn ngữ lớn (LLM).

Chỉ số

Bạn có thể xem tất cả chỉ số mà Genkit xuất bằng cách chọn "Ghi nhật ký" trong trình đơn bên rồi nhấp vào "Quản lý chỉ số".

Bảng điều khiển quản lý chỉ số chứa chế độ xem dạng bảng của tất cả các chỉ số đã thu thập, bao gồm cả các chỉ số liên quan đến Cloud Run và môi trường xung quanh. Nhấp vào 'Khối lượng công việc' sẽ hiển thị một danh sách bao gồm các chỉ số do Genkit thu thập. Mọi chỉ số có tiền tố genkit đều cấu thành chỉ số Genkit nội bộ.

Genkit thu thập một số loại chỉ số, bao gồm chỉ số ở cấp luồng, cấp hành động và cấp tạo. Mỗi chỉ số có một vài phương diện hữu ích hỗ trợ cho việc lọc và nhóm hiệu quả.

Các phương diện phổ biến bao gồm:

  • flow_name – tên cấp cao nhất của flow.
  • flow_path – span và span mẹ của span này liên kết với span gốc.
  • error_code – mã lỗi tương ứng trong trường hợp xảy ra lỗi.
  • error_message – trong trường hợp xảy ra lỗi, thông báo lỗi tương ứng.
  • model – tên mô hình.
  • temperature – giá trị nhiệt độ suy luận.
  • topK – giá trị hàng đầu của suy luận.
  • topP – giá trị đỉnh suy luận.

Chỉ số ở cấp luồng

Tên Kích thước
genkit/flow/requests flow_name, error_code, error_message
genkit/flow/latency flow_name

Chỉ số ở cấp hành động

Tên Kích thước
genkit/action/requests flow_name, error_code, error_message
genkit/action/latency tên_luồng

Chỉ số ở cấp độ tạo

Tên Kích thước
genkit/ai/generate flow_path, model, temperature, topK, topP, error_code, error_message
genkit/ai/generate/input_tokens flow_path, mô hình, nhiệt độ, topK, topP
genkit/ai/generate/output_tokens flow_path, mô hình, nhiệt độ, topK, topP
genkit/ai/generate/input_characters flow_path, mô hình, nhiệt độ, topK, topP
genkit/ai/generate/output_characters flow_path, model, temperature, topK, topP
genkit/ai/generate/input_images flow_path, model, temperature, topK, topP
genkit/ai/generate/output_images flow_path, model, temperature, topK, topP
genkit/ai/generate/latency flow_path, model, temperature, topK, topP, error_code, error_message

Bạn có thể trực quan hoá các chỉ số thông qua Trình khám phá chỉ số. Sử dụng trình đơn bên, chọn "Logging" (Ghi nhật ký) rồi nhấp vào "Trình khám phá chỉ số"

Chọn một chỉ số bằng cách nhấp vào trình đơn thả xuống "Chọn một chỉ số", chọn "Generic Node" (Điểm chung), "Genkit" (Genkit) và một chỉ số.

Hình ảnh của chỉ số sẽ phụ thuộc vào loại chỉ số đó (bộ đếm, biểu đồ, v.v.). Trình khám phá chỉ số cung cấp các cơ sở tổng hợp và truy vấn mạnh mẽ để giúp lập biểu đồ các chỉ số theo nhiều phương diện.

Độ trễ khi đo từ xa

Có thể có chút chậm trễ trước khi đo từ xa đối với một quá trình thực thi cụ thể của một luồng được hiển thị trong bộ vận hành của Cloud. Trong hầu hết trường hợp, thời gian trễ này là dưới 1 phút.

Hạn mức và giới hạn

Có một số hạn mức quan trọng cần ghi nhớ:

Chi phí

Cloud Logging, Cloud Trace và Cloud Monitoring có nhiều cấp miễn phí. Bạn có thể xem mức giá cụ thể tại các đường liên kết sau: