Beta: Firebase Genkit is in Beta, which means that it is not subject to any SLA or deprecation policy and could change in backwards-incompatible ways. Throughout the Beta period, Firebase Genkit and its documentation will be updated and improved.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Google Cloud 플러그인

Google Cloud 플러그인은 Firebase Genkit 원격 분석 및 로깅 데이터를 Firebase AI Monitoring 대시보드를 지원하는 Cloud Observability 제품군으로 내보냅니다.

설치

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

이 플러그인이 포함된 Genkit 코드를 로컬에서 실행하는 경우 Google Cloud CLI 도구도 설치되어 있어야 합니다.

Google Cloud 계정 설정

이 플러그인에는 Google Cloud 계정/프로젝트가 필요합니다. 모든 Firebase 프로젝트에는 기본적으로 하나의 프로젝트가 포함되어 있습니다 (GCP Console). 또는 https://cloud.google.com에서 가입할 수 있습니다.

플러그인을 추가하기 전에 GCP 프로젝트에 다음 API가 사용 설정되어 있는지 확인합니다.

이러한 API는 프로젝트의 API 대시보드에 표시되어야 합니다.

API 사용 설정 및 중지에 대해 자세히 알아보려면 여기를 클릭하세요.

Genkit 구성

Cloud Trace, Logging, Monitoring (측정항목)을 사용 설정하려면 enableGoogleCloudTelemetry()를 호출하면 됩니다.

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

enableGoogleCloudTelemetry();

프로덕션에서 실행하면 원격 분석이 자동으로 내보내집니다.

인증 및 승인

이 플러그인에는 Google Cloud 프로젝트 ID와 애플리케이션 사용자 인증 정보가 필요합니다.

Google Cloud

Google Cloud 환경 (Cloud Functions, Cloud Run 등)에 코드를 배포하는 경우 프로젝트 ID와 사용자 인증 정보는 애플리케이션 기본 사용자 인증 정보를 통해 자동으로 검색됩니다.

IAM 콘솔을 통해 코드를 실행하는 서비스 계정 (즉, '연결된 서비스 계정')에 다음 역할을 적용해야 합니다.

roles/monitoring.metricWriter
roles/cloudtrace.agent
roles/logging.logWriter

로컬 개발

로컬 개발을 할 때 플러그인에서 사용자 인증 정보를 사용할 수 있도록 하려면 추가 단계가 필요합니다.

GCLOUD_PROJECT 환경 변수를 Google Cloud 프로젝트로 설정합니다.
gcloud CLI를 사용하여 인증합니다.
```
gcloud auth application-default login
```

Google Cloud 외부의 프로덕션 환경

가능하면 애플리케이션 기본 사용자 인증 정보 프로세스를 활용하여 플러그인에서 사용자 인증 정보를 사용할 수 있도록 하는 것이 좋습니다.

일반적으로 서비스 계정 키/쌍을 생성하고 이러한 사용자 인증 정보를 프로덕션 환경에 배포하는 작업이 포함됩니다.

안내에 따라 서비스 계정 키를 설정합니다.
서비스 계정에 다음 역할이 있는지 확인합니다.
- roles/monitoring.metricWriter
- roles/cloudtrace.agent
- roles/logging.logWriter
사용자 인증 정보 파일을 프로덕션에 배포합니다 (소스 코드에 체크인하지 마세요).
GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 사용자 인증 정보 파일의 경로로 설정합니다.
```
GOOGLE_APPLICATION_CREDENTIALS = "path/to/your/key/file"
```

일부 서버리스 환경에서는 사용자 인증 정보 파일을 배포할 수 없습니다. 이 경우 위의 3단계와 4단계 대신 다음과 같이 사용자 인증 정보 파일의 콘텐츠로 GCLOUD_SERVICE_ACCOUNT_CREDS 환경 변수를 설정할 수 있습니다.

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"
}'

플러그인 구성

enableGoogleCloudTelemetry() 함수는 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,
});

구성 객체를 사용하면 아래에 설명된 원격 분석 내보내기의 다양한 측면을 세부적으로 제어할 수 있습니다.

credentials

google-auth 라이브러리의 JWTInput을 사용하여 사용자 인증 정보를 직접 지정할 수 있습니다.

샘플러

모든 트레이스를 내보내는 것이 실용적이지 않은 경우 OpenTelemetry에서는 트레이스 샘플링을 허용합니다.

사전 구성된 샘플러는 4가지가 있습니다.

AlwaysOnSampler - 모든 트레이스를 샘플링합니다.
AlwaysOffSampler - 트레이스가 없는 샘플
ParentBased - 상위 스팬을 기반으로 한 샘플
TraceIdRatioBased: 구성 가능한 비율의 트레이스를 샘플링합니다.

autoInstrumentation 및 autoInstrumentationConfig

자동 계측을 사용 설정하면 OpenTelemetry에서 코드를 수정하지 않고도 서드 파티 라이브러리에서 원격 분석 데이터를 캡처할 수 있습니다.

metricExportIntervalMillis

이 필드는 측정항목 내보내기 간격을 밀리초 단위로 지정합니다.

참고: Google Cloud Monitoring의 최소 내보내기 간격은 5,000밀리초입니다.

metricExportTimeoutMillis

이 필드는 측정항목 내보내기의 제한 시간(밀리초)을 지정합니다.

disableMetrics

트레이스와 로그를 계속 내보내면서 측정항목 내보내기를 사용 중지하는 재정의를 제공합니다.

disableTraces

측정항목과 로그는 계속 내보내면서 트레이스 내보내기를 사용 중지하는 재정의를 제공합니다.

disableLoggingIO

입력 및 출력 로그 수집을 사용 중지하는 재정의를 제공합니다.

forceDevExport

이 옵션을 사용하면 dev 환경 (예: 로컬)에서 실행할 때 Genkit가 원격 분석 및 로그 데이터를 내보내도록 강제합니다.

참고: 로컬에서 실행할 때는 프로세스가 종료되기 전에 내부 원격 분석 버퍼가 완전히 플러시되지 않아 원격 분석이 완전히 내보내지지 않을 수 있습니다.

통합 테스트

플러그인을 구성할 때 forceDevExport: true를 사용하여 로컬 실행에 대한 원격 분석 내보내기를 사용 설정합니다. Google Cloud 로그, 측정항목 또는 Trace Explorer로 이동하여 원격 분석을 확인합니다.

Google Cloud Observability 모음

코드 (예: 흐름)가 배포되면 Cloud Monitoring 대시보드로 이동하여 프로젝트를 선택합니다. 여기에서 프로덕션 모니터링을 위해 로그, 측정항목, 트레이스 탐색기를 쉽게 탐색할 수 있습니다.

로그 및 trace

왼쪽 사이드 메뉴에서 '탐색' 제목 아래의 '로그 탐색기'를 클릭합니다.

여기에는 console.log()를 비롯하여 배포된 Genkit 코드와 연결된 모든 로그가 표시됩니다. [genkit] 접두사가 있는 모든 로그는 디버깅 목적으로 관심을 가질 수 있는 정보가 포함된 Genkit 내부 로그입니다. 예를 들어 Config[...] 형식의 Genkit 로그에는 특정 LLM 추론을 위한 온도 및 topK 값과 같은 메타데이터가 포함됩니다. Output[...] 형식의 로그에는 LLM 응답이 포함되고 Input[...] 로그에는 프롬프트가 포함됩니다. Cloud Logging에는 민감한 로그에 대한 액세스를 세분화하여 제어할 수 있는 강력한 ACL이 있습니다.

참고: 프롬프트와 LLM 응답은 Cloud Trace의 trace 속성에서 수정됩니다. 특정 로그 줄의 경우 확장 메뉴 아이콘을 클릭하고 'trace 세부정보에서 보기'를 선택하여 각 trace로 이동할 수 있습니다.

그러면 trace의 세부정보를 한눈에 볼 수 있는 trace 미리보기 창이 표시됩니다. 전체 세부정보를 보려면 창의 오른쪽 상단에서 'Trace에서 보기' 링크를 클릭합니다.

Cloud Trace에서 가장 눈에 띄는 탐색 요소는 trace 분산형 차트입니다. 특정 기간에 수집된 모든 trace가 포함됩니다.

각 데이터 포인트를 클릭하면 분산형 차트 아래에 세부정보가 표시됩니다.

상세 뷰에는 모든 단계와 중요한 타이밍 정보를 포함한 흐름 형태가 포함됩니다. Cloud Trace는 이 뷰 내에서 특정 trace와 연결된 모든 로그를 인터리브 처리할 수 있습니다. '로그 및 이벤트' 드롭다운에서 '펼쳐진 항목 표시' 옵션을 선택합니다.

결과 뷰를 사용하면 프롬프트 및 LLM 응답을 비롯하여 trace 컨텍스트에서 로그를 자세히 검사할 수 있습니다.

측정항목

왼쪽 사이드 메뉴의 '구성' 제목 아래에 있는 '측정항목 관리'를 클릭하여 Genkit에서 내보낸 모든 측정항목을 볼 수 있습니다.

측정항목 관리 콘솔에는 Cloud Run 및 주변 환경과 관련된 측정항목을 포함하여 수집된 모든 측정항목의 테이블 형식 뷰가 포함됩니다. '워크로드' 옵션을 클릭하면 Genkit에서 수집한 측정항목이 포함된 목록이 표시됩니다. genkit 접두사가 있는 모든 측정항목은 내부 Genkit 측정항목을 구성합니다.

Genkit는 기능, 작업, 생성 등 여러 카테고리의 측정항목을 수집합니다. 각 측정항목에는 강력한 필터링과 그룹화를 용이하게 하는 여러 유용한 측정기준이 있습니다.

일반적인 측정기준은 다음과 같습니다.

flow_name - 흐름의 최상위 이름
flow_path - 스팬과 루트 스팬까지의 상위 스팬 체인
error_code - 오류 발생 시 해당하는 오류 코드
error_message - 오류 발생 시 해당하는 오류 메시지
model: 모델의 이름

기능 측정항목

기능은 Genkit 코드의 최상위 진입점입니다. 대부분의 경우 흐름입니다. 그렇지 않으면 트레이스의 최상위 스팬이 됩니다.

이름	유형	설명
genkit/feature/requests	카운터	요청 수
genkit/feature/latency	히스토그램	실행 지연 시간(밀리초)

각 기능 측정항목에는 다음과 같은 측정기준이 포함됩니다.

이름	설명
name	기능의 이름입니다. 대부분의 경우 최상위 Genkit 흐름입니다.
상태	기능 요청의 성공 여부에 따라 'success' 또는 'failure'
오류	`status=failure`인 경우에만 설정됩니다. 실패를 일으킨 오류 유형을 포함합니다.
source	Genkit 소스 언어입니다. 예: 'ts'
sourceVersion	Genkit 프레임워크 버전

액션 측정항목

작업은 Genkit 내에서 실행되는 일반적인 단계를 나타냅니다. 각 단계에는 다음과 같은 측정항목이 추적됩니다.

이름	유형	설명
genkit/action/requests	카운터	이 작업이 실행된 횟수
genkit/action/latency	히스토그램	실행 지연 시간(밀리초)

각 액션 측정항목에는 다음 측정기준이 포함됩니다.

이름	설명
name	작업 이름
featureName	실행 중인 상위 기능의 이름
경로	기능 루트에서 이 작업으로의 실행 경로입니다. 예: '/myFeature/parentAction/thisAction'
상태	작업의 성공 여부에 따라 'success' 또는 'failure'
오류	`status=failure`인 경우에만 설정됩니다. 실패를 일으킨 오류 유형을 포함합니다.
source	Genkit 소스 언어입니다. 예: 'ts'
sourceVersion	Genkit 프레임워크 버전

측정항목 생성

모델과 상호작용하는 작업과 관련된 특수 작업 측정항목입니다. 요청 및 지연 시간 외에도 입력과 출력도 추적되며, 디버깅 및 구성 조정을 더 쉽게 할 수 있는 모델별 측정기준이 제공됩니다.

이름	유형	설명
genkit/ai/generate/requests	카운터	이 모델이 호출된 횟수
genkit/ai/generate/latency	히스토그램	실행 지연 시간(밀리초)
genkit/ai/generate/input/tokens	카운터	입력 토큰
genkit/ai/generate/output/tokens	카운터	출력 토큰
genkit/ai/generate/input/characters	카운터	문자 입력
genkit/ai/generate/output/characters	카운터	출력 문자
genkit/ai/generate/input/images	카운터	입력 이미지
genkit/ai/generate/output/images	카운터	출력 이미지
genkit/ai/generate/input/audio	카운터	오디오 파일 입력
genkit/ai/generate/output/audio	카운터	오디오 파일 출력

각 생성 측정항목에는 다음 측정기준이 포함됩니다.

이름	설명
modelName	모델 이름
featureName	실행 중인 상위 기능의 이름
경로	기능 루트에서 이 작업으로의 실행 경로입니다. 예: '/myFeature/parentAction/thisAction'
latencyMs	모델이 걸린 응답 시간
상태	기능 요청의 성공 여부에 따라 'success' 또는 'failure'
오류	`status=failure`인 경우에만 설정됩니다. 실패를 일으킨 오류 유형을 포함합니다.
source	Genkit 소스 언어입니다. 예: 'ts'
sourceVersion	Genkit 프레임워크 버전

측정항목 탐색기를 통해 측정항목을 시각화할 수 있습니다. 왼쪽 사이드 메뉴에서 '탐색' 제목 아래에 있는 '측정항목 탐색기'를 클릭합니다.

'측정항목 선택' 드롭다운을 클릭하여 측정항목을 선택하고 '일반 노드', 'Genkit', 측정항목을 선택합니다.

측정항목의 시각화는 유형 (카운터, 히스토그램 등)에 따라 다릅니다. 측정항목 탐색기는 다양한 측정기준별로 측정항목을 그래프로 표시하는 데 도움이 되는 강력한 집계 및 쿼리 도구를 제공합니다.

원격 분석 지연

흐름의 특정 실행에 대한 원격 분석이 Cloud 운영 제품군에 표시되기까지 약간의 지연이 발생할 수 있습니다. 대부분의 경우 이 지연 시간은 1분 미만입니다.

할당량 및 한도

다음과 같은 몇 가지 중요한 할당량이 있습니다.

비용

Cloud Logging, Cloud Trace, Cloud Monitoring은 무료 등급 혜택을 넉넉하게 제공합니다. 구체적인 가격은 다음 링크에서 확인할 수 있습니다.