Trình bổ trợ Google Cloud sẽ xuất dữ liệu đo từ xa và ghi nhật ký Firebase Genkit sang bộ công cụ Cloud Observability (Quan sát trên đám mây). Bộ công cụ này hỗ trợ trang tổng quan Firebase AI Monitoring (Theo dõi AI trên Firebase).
Lắp đặt
npm i --save @genkit-ai/google-cloudKhi chạy mã Genkit cục bộ có chứa trình bổ trợ nà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 tài khoản/dự án Google Cloud. Tất cả dự án Firebase đều có một tài khoản theo mặc định (Bảng điều khiển GCP), hoặc bạn có thể đăng ký tại https://cloud.google.com.
Trước khi thêm trình bổ trợ, hãy đảm bảo rằng bạn đã bật các API sau cho dự án GCP:
Các API này sẽ đượ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
Để bật tính năng Theo dõi trên đám mây, Ghi nhật ký và Giám sát (chỉ số), bạn chỉ cần gọi enableGoogleCloudTelemetry():
import { enableGoogleCloudTelemetry } from '@genkit-ai/google-cloud';
enableGoogleCloudTelemetry();
Khi chạy trong môi trường phát hành công khai, dữ liệu đo từ xa sẽ được tự động xuất.
Xác thực và uỷ quyền
Trình bổ trợ này yêu cầu mã dự án Google Cloud và thông tin xác thực ứng dụng.
Google Cloud
Nếu bạn triển khai mã của mình cho mộ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ự động phát hiện thông qua Thông tin xác thực mặc định của ứng dụng.
Bạn sẽ cần áp dụng các vai trò sau cho tài khoản dịch vụ đang chạy mã của bạn (tức là "tài khoản dịch vụ đính kèm") thông qua Bảng điều khiển IAM:
roles/monitoring.metricWriterroles/cloudtrace.agentroles/logging.logWriter
Phát triển cục bộ
Khi phát triển cục bộ, để trình bổ trợ có thể sử dụng thông tin xác thực người dùng, bạn cần thực hiện thêm các bước.
Đặt biến môi trường
GCLOUD_PROJECTthành dự án Google Cloud của bạn.Xác thực bằng CLI
gcloud:gcloud auth application-default login
Môi trường sản xuất bên ngoài Google Cloud
Nếu có thể, bạn vẫn nên tận dụng quy trình Thông tin xác thực mặc định của ứng dụng để cung cấp thông tin xác thực cho trình bổ trợ.
Thông thường, việc này liên quan đến việc tạo khoá/cặp tài khoản dịch vụ và triển khai thông tin xác thực đó vào môi trường sản xuất.
Làm theo hướng dẫn để thiết lập khoá tài khoản dịch vụ.
Đảm bảo tài khoản dịch vụ có các vai trò sau:
roles/monitoring.metricWriterroles/cloudtrace.agentroles/logging.logWriter
Triển khai tệp thông tin xác thực cho môi trường phát hành công khai (không kiểm tra vào mã nguồn)
Đặt biến môi trường
GOOGLE_APPLICATION_CREDENTIALSlàm đường dẫn đến tệp thông tin xác thực.GOOGLE_APPLICATION_CREDENTIALS = "path/to/your/key/file"
Trong một số môi trường không có máy chủ, bạn có thể không triển khai được tệp thông tin xác thực. Trong trường hợp này, thay vì các bước 3 và 4 ở trên, bạn có thể đặt biến môi trường GCLOUD_SERVICE_ACCOUNT_CREDS bằng nội dung của tệp thông tin xác thực như sau:
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ợ
Hàm enableGoogleCloudTelemetry() nhận một đối tượng cấu hình tuỳ chọn để định cấu hình thực thể OpenTelemetry NodeSDK.
import { AlwaysOnSampler } from '@opentelemetry/sdk-trace-base';
enableGoogleCloudTelemetry({
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,
});
Các đối tượng cấu hình cho phép kiểm soát chi tiết nhiều khía cạnh của quá trình xuất dữ liệu đo từ xa được nêu dưới đây.
thông tin xác thực
Cho phép chỉ định thông tin xác thực trực tiếp bằng cách sử dụng JWTInput từ thư viện google-auth.
bộ lấy mẫu
Đối với các 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:
- AlwaysOnSampler – lấy mẫu tất cả dấu vết
- AlwaysOffSampler – không lấy mẫu dấu vết
- ParentBased – lấy mẫu dựa trên span mẹ
- TraceIdRatioBased – lấy mẫu một tỷ lệ phần trăm có thể định cấu hình của các dấu vết
autoInstrumentation và autoInstrumentationConfig
Việc bật tính năng tự động đo lường cho phép OpenTelemetry thu thập dữ liệu đo từ xa từ thư viện của bên thứ ba mà không cần sửa đổi mã.
metricExportIntervalMillis
Trường này chỉ định khoảng thời gian xuất chỉ số tính bằng mili giây.
metricExportTimeoutMillis
Trường này chỉ định thời gian chờ để xuất chỉ số tính bằng mili giây.
disableMetrics
Cung cấp một cơ chế ghi đè vô hiệu hoá tính năng xuất chỉ số trong khi vẫn xuất dấu vết và nhật ký.
disableTraces
Cung cấp một cơ chế ghi đè vô hiệu hoá tính năng xuất dấu vết trong khi vẫn xuất các chỉ số và nhật ký.
disableLoggingIO
Cung cấp một cơ chế ghi đè để tắt tính năng thu thập nhật ký đầu vào và đầu ra.
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ộ).
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ộ. Chuyển đến Nhật ký Google Cloud, Chỉ số hoặc Trình khám phá dấu vết để xem dữ liệu đo từ xa.
Bộ công cụ Google Cloud Observability
Sau khi triển khai mã (ví dụ: flow), hãy chuyển đến trang tổng quan Cloud Monitoring (Theo dõi trên đám mây) rồi chọn dự án của bạn. Tại đây, bạn có thể dễ dàng di chuyển giữa các trình khám phá Nhật ký, Chỉ số và Dấu vết để theo dõi bản phát hành chính thức.
Nhật ký và dấu vết
Trên trình đơn bên trái, hãy nhấp vào "Trình khám phá nhật ký" trong tiêu đề "Khám phá".
Tại đây, bạn sẽ thấy tất cả nhật ký được liên kết với mã Genkit đã 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 cho các suy luận LLM cụ thể.
Nhật ký ở định dạng Output[...] chứa các phản hồi LLM, còn nhật ký Input[...] chứa các lời nhắc. Tính năng Nhật ký trên đám mây có các ACL mạnh mẽ cho phép kiểm soát chi tiết quyền truy cập vào nhật ký nhạy cảm.
Thao tác này sẽ hiển thị ngăn xem trước dấu vết, cung cấp thông tin nhanh về chi tiết của 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" ở góc trên cùng bên phải của ngăn.
Thành phần điều hướng nổi bật nhất trong Cloud Trace là biểu đồ tán xạ dấu vết. 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 luồng, bao gồm tất cả các bước và thông tin quan trọng về thời gian. Cloud Trace có khả năng xen kẽ tất cả 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 tuỳ chọn "Hiện mở rộng" trong trình đơn thả xuống "Nhật ký và sự kiện".
Chế độ xem kết quả cho phép kiểm tra chi tiết nhật ký trong ngữ cảnh của dấu vết, bao gồm cả câu lệnh và phản hồi LLM.
Chỉ số
Bạn có thể xem tất cả chỉ số do Genkit xuất bằng cách nhấp vào 'Quản lý chỉ số' trong tiêu đề 'Định cấu hình' trong trình đơn bên trái.
Bảng điều khiển quản lý chỉ số chứa chế độ xem dạng bảng của tất cả chỉ số đã thu thập, bao gồm cả những chỉ số liên quan đến Cloud Run và môi trường xung quanh.
Khi nhấp vào tuỳ chọn "Workload" (Gánh nặng công việc), bạn sẽ thấy 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 là một chỉ số Genkit nội bộ.
Genkit thu thập một số danh mục chỉ số, bao gồm: tính năng, hành động và tạo. Mỗi chỉ số có một số phương diện hữu ích hỗ trợ 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– trong trường hợp xảy ra lỗi, mã lỗi tương ứng.error_message– trong trường hợp xảy ra lỗi, thông báo lỗi tương ứng.model– tên của mô hình.
Chỉ số về tính năng
Tính năng là điểm truy cập cấp cao nhất vào mã Genkit. Trong hầu hết các trường hợp, đây sẽ là một luồng. Nếu không, đây sẽ là span trên cùng trong một dấu vết.
| Tên | Loại | Mô tả |
|---|---|---|
| genkit/feature/requests | Bộ đếm | Số lượng yêu cầu |
| genkit/feature/latency | Biểu đồ | Độ trễ thực thi (mili giây) |
Mỗi chỉ số về tính năng đều chứa các phương diện sau:
| Tên | Mô tả |
|---|---|
| name | Tên của tính năng. Trong hầu hết các trường hợp, đây là luồng Genkit cấp cao nhất |
| trạng thái | "success" (thành công) hoặc "failure" (không thành công) tuỳ thuộc vào việc yêu cầu tính năng có thành công hay không |
| error | Chỉ đặt khi status=failure. Chứa loại lỗi gây ra lỗi |
| nguồn | Ngôn ngữ nguồn Genkit. Ví dụ: 'ts' |
| sourceVersion | Phiên bản khung Genkit |
Chỉ số hành động
Thao tác đại diện cho một bước thực thi chung trong Genkit. Mỗi bước trong số này sẽ có các chỉ số sau được theo dõi:
| Tên | Loại | Mô tả |
|---|---|---|
| genkit/action/requests | Bộ đếm | Số lần thực thi hành động này |
| genkit/action/latency | Biểu đồ | Độ trễ thực thi (mili giây) |
Mỗi chỉ số hành động chứa các phương diện sau:
| Tên | Mô tả |
|---|---|
| name | Tên của hành động |
| featureName | Tên của tính năng mẹ đang được thực thi |
| đường dẫn | Đường dẫn thực thi từ thư mục gốc của tính năng đến hành động này. Ví dụ: '/myFeature/parentAction/thisAction' |
| trạng thái | "success" (thành công) hoặc "failure" (không thành công) tuỳ thuộc vào việc hành động có thành công hay không |
| error | Chỉ đặt khi status=failure. Chứa loại lỗi gây ra lỗi |
| nguồn | Ngôn ngữ nguồn Genkit. Ví dụ: 'ts' |
| sourceVersion | Phiên bản khung Genkit |
Tạo chỉ số
Đây là các chỉ số hành động đặc biệt liên quan đến các hành động tương tác với một mô hình. Ngoài các yêu cầu và độ trễ, dữ liệu đầu vào và đầu ra cũng được theo dõi, với các phương diện cụ thể theo mô hình giúp việc gỡ lỗi và điều chỉnh cấu hình trở nên dễ dàng hơn.
| Tên | Loại | Mô tả |
|---|---|---|
| genkit/ai/generate/requests | Bộ đếm | Số lần gọi mô hình này |
| genkit/ai/generate/latency | Biểu đồ | Độ trễ thực thi (mili giây) |
| genkit/ai/generate/input/tokens | Bộ đếm | Mã thông báo đầu vào |
| genkit/ai/generate/output/tokens | Bộ đếm | Mã thông báo đầu ra |
| genkit/ai/generate/input/characters | Bộ đếm | Nhập ký tự |
| genkit/ai/generate/output/characters | Bộ đếm | Ký tự đầu ra |
| genkit/ai/generate/input/images | Bộ đếm | Nhập hình ảnh |
| genkit/ai/generate/output/images | Bộ đếm | Hình ảnh đầu ra |
| genkit/ai/generate/input/audio | Bộ đếm | Tệp âm thanh đầu vào |
| genkit/ai/generate/output/audio | Bộ đếm | Tệp âm thanh đầu ra |
Mỗi chỉ số được tạo chứa các phương diện sau:
| Tên | Mô tả |
|---|---|
| modelName | Tên mô hình |
| featureName | Tên của tính năng mẹ đang được thực thi |
| đường dẫn | Đường dẫn thực thi từ thư mục gốc của tính năng đến hành động này. Ví dụ: '/myFeature/parentAction/thisAction' |
| latencyMs | Thời gian phản hồi của mô hình |
| trạng thái | "success" (thành công) hoặc "failure" (không thành công) tuỳ thuộc vào việc yêu cầu tính năng có thành công hay không |
| error | Chỉ đặt khi status=failure. Chứa loại lỗi gây ra lỗi |
| nguồn | Ngôn ngữ nguồn Genkit. Ví dụ: 'ts' |
| sourceVersion | Phiên bản khung Genkit |
Bạn có thể trực quan hoá các chỉ số thông qua Trình khám phá chỉ số. Trên trình đơn bên trái, hãy nhấp vào "Trình khám phá chỉ số" trong tiêu đề "Khám phá".
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" 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 biểu đồ các chỉ số theo nhiều phương diện.
Độ trễ của dữ liệu đo từ xa
Có thể sẽ có độ trễ nhỏ trước khi dữ liệu đo từ xa cho một lần thực thi cụ thể của một luồng xuất hiện trong bộ hoạt động của Cloud. Trong hầu hết các trường hợp, độ trễ này dưới 1 phút.
Hạn mức
Bạn cần lưu ý một số hạn mức quan trọng sau:
Chi phí
Cloud Logging, Cloud Trace và Cloud Monitoring có các cấp miễn phí hào phóng. Bạn có thể xem mức giá cụ thể tại các đường liên kết sau: