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를 통해 번역되었습니다.

Cloud Run을 사용하여 흐름 배포

Cloud Run을 사용하여 Genkit 흐름을 HTTPS 엔드포인트로 배포할 수 있습니다. Cloud Run에는 컨테이너 기반 배포를 비롯한 여러 배포 옵션이 있습니다. 이 페이지에서는 코드에서 직접 흐름을 배포하는 방법을 설명합니다.

시작하기 전에

Google Cloud CLI 설치
Genkit의 흐름 개념과 이를 작성하는 방법을 숙지해야 합니다. 이 페이지에서는 배포하려는 흐름이 이미 있다고 가정합니다.
이전에 Google Cloud 및 Cloud Run을 사용한 적이 있으면 도움이 되지만 필수는 아닙니다.

1. Google Cloud 프로젝트 설정

Google Cloud 프로젝트를 아직 설정하지 않았다면 다음 단계를 따르세요.

Cloud 콘솔을 사용하여 새 Google Cloud 프로젝트를 만들거나 기존 프로젝트를 선택합니다.
Cloud Run에 필요한 결제 계정에 프로젝트를 연결합니다.
프로젝트를 사용하도록 Google Cloud CLI를 구성합니다.
```
gcloud init
```

2. 배포를 위한 Node 프로젝트 준비

흐름을 배포하려면 프로젝트 코드를 약간 변경해야 합니다.

package.json에 시작 및 빌드 스크립트 추가

Node.js 프로젝트를 Cloud Run에 배포할 때 배포 도구는 프로젝트에 start 스크립트와 선택적으로 build 스크립트가 있어야 한다고 예상합니다. 일반적인 TypeScript 프로젝트의 경우 다음 스크립트가 일반적으로 적합합니다.

"scripts": {
  "start": "node lib/index.js",
  "build": "tsc"
},

흐름 서버를 구성하고 시작하는 코드 추가

start 스크립트에서 실행되는 파일에 startFlowServer 호출을 추가합니다. 이 메서드는 흐름을 웹 엔드포인트로 제공하도록 설정된 Express 서버를 시작합니다.

호출할 때 게재할 흐름을 지정합니다.

ai.startFlowServer({
  flows: [menuSuggestionFlow],
});

지정할 수 있는 선택적 매개변수도 있습니다.

port: 리슨할 네트워크 포트입니다. 지정하지 않으면 서버가 PORT 환경 변수에 정의된 포트에서 리슨하고 PORT가 설정되지 않으면 기본값 3400으로 설정됩니다.
cors: 흐름 서버의 CORS 정책입니다. 웹 애플리케이션에서 이러한 엔드포인트에 액세스하는 경우 이를 지정해야 할 수 있습니다.
pathPrefix: 흐름 엔드포인트 앞에 추가할 선택적 경로 접두사입니다.
jsonParserOptions: Express의 JSON 본문 파서에 전달할 옵션입니다.

선택사항: 승인 정책 정의

배포된 모든 흐름에는 어떤 형태로든 승인이 필요합니다. 그러지 않으면 비용이 많이 들 수 있는 생성형 AI 흐름을 누구나 호출할 수 있게 됩니다.

Cloud Run으로 흐름을 배포할 때는 다음과 같은 두 가지 승인 옵션이 있습니다.

Cloud IAM 기반 승인: Google Cloud의 기본 액세스 관리 기능을 사용하여 엔드포인트에 대한 액세스를 제어합니다. 사용자 인증 정보를 제공하는 방법에 대한 자세한 내용은 Cloud Run 문서의 인증을 참고하세요.
코드에 정의된 승인 정책: Genkit 흐름의 승인 정책 기능을 사용하여 맞춤 코드를 통해 승인 정보를 확인합니다. 이는 토큰 기반 승인인 경우가 많지만 반드시 그런 것은 아닙니다.

코드에서 승인 정책을 정의하려면 흐름 정의에서 authPolicy 매개변수를 사용합니다.

const myFlow = ai.defineFlow(
  {
    name: "myFlow",
    authPolicy: (auth, input) => {
      if (!auth) {
        throw new Error("Authorization required.");
      }
      // Custom checks go here...
    },
  },
  async () => {
    // ...
  }
);

승인 정책의 auth 매개변수는 요청 객체의 auth 속성에서 가져옵니다. 일반적으로 이 속성은 Express 미들웨어를 사용하여 설정합니다. 승인 및 무결성을 참고하세요.

배포된 흐름에 API 사용자 인증 정보 제공

배포된 후에는 흐름이 사용하는 원격 서비스와 인증할 방법이 필요합니다. 대부분의 흐름에는 최소한 사용하는 모델 API 서비스에 액세스하기 위한 사용자 인증 정보가 필요합니다.

이 예에서는 선택한 모델 공급업체에 따라 다음 중 하나를 실행합니다.

Gemini(Google AI)

Google AI를 해당 리전에서 사용할 수 있는지 확인합니다.
Google AI Studio를 사용하는 Gemini API의 API 키를 생성합니다.
Cloud Run 환경에서 API 키를 사용할 수 있도록 설정합니다.
1. Cloud 콘솔에서 Secret Manager API를 사용 설정합니다.
2. Secret Manager 페이지에서 API 키가 포함된 새 보안 비밀을 만듭니다.
3. 보안 비밀을 만든 후 같은 페이지에서 Secret Manager 보안 비밀 접근자 역할을 통해 기본 컴퓨팅 서비스 계정에 보안 비밀에 대한 액세스 권한을 부여합니다. (IAM 페이지에서 기본 컴퓨팅 서비스 계정의 이름을 찾을 수 있습니다.)
이후 단계에서 서비스를 배포할 때 이 보안 비밀의 이름을 참조해야 합니다.

Gemini(Vertex AI)

Cloud 콘솔에서 프로젝트에 대해 Vertex AI API를 사용 설정합니다.
IAM 페이지에서 기본 컴퓨팅 서비스 계정에 Vertex AI 사용자 역할이 부여되었는지 확인합니다.

이 튜토리얼에서 설정해야 하는 유일한 보안 비밀은 모델 제공업체이지만, 일반적으로 흐름에서 사용하는 각 서비스에 대해 유사한 작업을 수행해야 합니다.

3. Cloud Run에 흐름 배포

배포할 프로젝트를 준비한 후 gcloud 도구를 사용하여 배포할 수 있습니다.

Gemini(Google AI)

gcloud run deploy --update-secrets=GOOGLE_GENAI_API_KEY=<your-secret-name>:latest

Gemini(Vertex AI)

gcloud run deploy

배포 도구에서 필요한 정보를 요청합니다.

인증되지 않은 호출을 허용할지 묻는 메시지가 표시되면 다음 단계를 따르세요.

IAM을 사용하지 않고 대신 코드에서 승인 정책을 정의한 경우 Y를 선택합니다.
N으로 응답하여 IAM 사용자 인증 정보를 요구하도록 서비스를 구성합니다.

선택사항: 배포된 흐름 사용해 보기

배포가 완료되면 도구에서 서비스 URL을 출력합니다. curl로 테스트할 수 있습니다.

curl -X POST https://<service-url>/menuSuggestionFlow \
  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  -H "Content-Type: application/json" -d '{"data": "banana"}'